xPablo.cz/arduino-esp32-custom-lwip-ppp-enabled
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Prvni ulozeni z chegewara githubu

Browse Source
This commit is contained in:
Pavel Brychta
2023-02-25 16:13:53 +01:00
commit 01eb80dfe2
3279 changed files with 638407 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
docs/source/api/adc.rst Normal file
View File

@ -0,0 +1,208 @@
###
ADC
###
About
-----
ADC (analog to digital converter) is a very common peripheral used to convert an analog signal such as voltage
to a digital form so that it can be read and processed by a microcontroller.
ADCs are very useful in control and monitoring applications since most sensors
(e.g., temperature, pressure, force) produce analogue output voltages.
.. note:: Each SoC or module has a different number of ADC's with a different number of channels and pins availible. Refer to datasheet of each board for more info.
Arduino-ESP32 ADC API
---------------------
ADC common API
**************
analogRead
^^^^^^^^^^
This function is used to get the ADC raw value for a given pin/ADC channel.
.. code-block:: arduino
uint16_t analogRead(uint8_t pin);
* ``pin`` GPIO pin to read analog value
This function will return analog raw value.
analogReadMillivolts
^^^^^^^^^^^^^^^^^^^^
This function is used to get ADC value for a given pin/ADC channel in millivolts.
.. code-block:: arduino
uint32_t analogReadMilliVolts(uint8_t pin);
* ``pin`` GPIO pin to read analog value
This function will return analog value in millivolts.
analogReadResolution
^^^^^^^^^^^^^^^^^^^^
This function is used to set the resolution of ``analogRead`` return value. Default is 12 bits (range from 0 to 4096)
for all chips except ESP32S3 where default is 13 bits (range from 0 to 8192).
When different resolution is set, the values read will be shifted to match the given resolution.
Range is 1 - 16 .The default value will be used, if this function is not used.
.. note:: For the ESP32, the resolution is between 9 to12 and it will change the ADC hardware resolution. Else value will be shifted.
.. code-block:: arduino
void analogReadResolution(uint8_t bits);
* ``bits`` sets analog read resolution
analogSetClockDiv
^^^^^^^^^^^^^^^^^
This function is used to set the divider for the ADC clock.
Range is 1 - 255. Default value is 1.
.. code-block:: arduino
void analogSetClockDiv(uint8_t clockDiv);
* ``clockDiv`` sets the divider for ADC clock.
analogSetAttenuation
^^^^^^^^^^^^^^^^^^^^
This function is used to set the attenuation for all channels.
Input voltages can be attenuated before being input to the ADCs.
There are 4 available attenuation options, the higher the attenuation is, the higher the measurable input voltage could be.
The measurable input voltage differs for each chip, see table below for detailed information.
.. tabs::
.. tab:: ESP32
===================== ===========================================
Attenuation Measurable input voltage range
===================== ===========================================
``ADC_ATTEN_DB_0`` 100 mV ~ 950 mV
``ADC_ATTEN_DB_2_5`` 100 mV ~ 1250 mV
``ADC_ATTEN_DB_6`` 150 mV ~ 1750 mV
``ADC_ATTEN_DB_11`` 150 mV ~ 2450 mV
===================== ===========================================
.. tab:: ESP32-S2
===================== ===========================================
Attenuation Measurable input voltage range
===================== ===========================================
``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV
``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV
``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV
===================== ===========================================
.. tab:: ESP32-C3
===================== ===========================================
Attenuation Measurable input voltage range
===================== ===========================================
``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV
``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV
``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV
===================== ===========================================
.. tab:: ESP32-S3
===================== ===========================================
Attenuation Measurable input voltage range
===================== ===========================================
``ADC_ATTEN_DB_0`` 0 mV ~ 950 mV
``ADC_ATTEN_DB_2_5`` 0 mV ~ 1250 mV
``ADC_ATTEN_DB_6`` 0 mV ~ 1750 mV
``ADC_ATTEN_DB_11`` 0 mV ~ 3100 mV
===================== ===========================================
.. code-block:: arduino
void analogSetAttenuation(adc_attenuation_t attenuation);
* ``attenuation`` sets the attenuation.
analogSetPinAttenuation
^^^^^^^^^^^^^^^^^^^^^^^
This function is used to set the attenuation for a specific pin/ADC channel. For more information refer to `analogSetAttenuation`_.
.. code-block:: arduino
void analogSetPinAttenuation(uint8_t pin, adc_attenuation_t attenuation);
* ``pin`` selects specific pin for attenuation settings.
* ``attenuation`` sets the attenuation.
adcAttachPin
^^^^^^^^^^^^
This function is used to attach the pin to ADC (it will also clear any other analog mode that could be on)
.. code-block:: arduino
bool adcAttachPin(uint8_t pin);
This function will return ``true`` if configuration is successful. Else returns ``false``.
ADC API specific for ESP32 chip
*******************************
analogSetWidth
^^^^^^^^^^^^^^
This function is used to set the hardware sample bits and read resolution.
Default is 12bit (0 - 4095).
Range is 9 - 12.
.. code-block:: arduino
void analogSetWidth(uint8_t bits);
analogSetVRefPin
^^^^^^^^^^^^^^^^
This function is used to set pin to use for ADC calibration if the esp is not already calibrated (pins 25, 26 or 27).
.. code-block:: arduino
void analogSetVRefPin(uint8_t pin);
* ``pin`` GPIO pin to set VRefPin for ADC calibration
hallRead
^^^^^^^^
This function is used to get the ADC value of the HALL sensor conneted to pins 36(SVP) and 39(SVN).
.. code-block:: arduino
int hallRead();
This function will return the hall sensor value.
Example Applications
********************
Here is an example of how to use the ADC.
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogRead/AnalogRead.ino
:language: arduino
Or you can run Arduino example 01.Basics -> AnalogReadSerial.

3
docs/source/api/bluetooth.rst Normal file
View File

@ -0,0 +1,3 @@
#############
Bluetooth API
#############

47
docs/source/api/dac.rst Normal file
View File

@ -0,0 +1,47 @@
###
DAC
###
About
-----
DAC (digital to analog converter) is a very common peripheral used to convert a digital signal to an
analog form.
ESP32 and ESP32-S2 have two 8-bit DAC channels. The DAC driver allows these channels to be set to arbitrary voltages.
DACs can be used for generating a specific (and dynamic) reference voltage for external sensors,
controlling transistors, etc.
========= ========= =========
ESP32 SoC DAC_1 pin DAC_2 pin
========= ========= =========
ESP32 GPIO 25 GPIO 26
ESP32-S2 GPIO 17 GPIO 18
========= ========= =========
Arduino-ESP32 DAC API
---------------------
dacWrite
********
This function is used to set the DAC value for a given pin/DAC channel.
.. code-block:: arduino
void dacWrite(uint8_t pin, uint8_t value);
* ``pin`` GPIO pin.
* ``value`` to be set. Range is 0 - 255 (equals 0V - 3.3V).
dacDisable
**********
This function is used to disable DAC output on a given pin/DAC channel.
.. code-block:: arduino
void dacDisable(uint8_t pin);
* ``pin`` GPIO pin.

3
docs/source/api/deepsleep.rst Normal file
View File

@ -0,0 +1,3 @@
##########
Deep Sleep
##########

16
docs/source/api/espnow.rst Normal file
View File

@ -0,0 +1,16 @@
#######
ESP-NOW
#######
ESP-NOW is a fast, connectionless communication technology featuring a short packet transmission.
ESP-NOW is ideal for smart lights, remote control devices, sensors and other applications.
Example
-------
Resources
---------
* `ESP-NOW`_ (User Guide)
.. _ESP-NOW: https://www.espressif.com/sites/default/files/documentation/esp-now_user_guide_en.pdf

170
docs/source/api/gpio.rst Normal file
View File

@ -0,0 +1,170 @@
####
GPIO
####
About
-----
One of the most used and versatile peripheral in a microcontroller is the GPIO. The GPIO is commonly used to write and read the pin state.
GPIO stands to General Purpose Input Output, and is responsible to control or read the state of a specific pin in the digital world. For example, this peripheral is widely used to create the LED blinking or to read a simple button.
.. note:: There are some GPIOs with special restrictions, and not all GPIOs are accessible through the developemnt board. For more information about it, see the corresponding board pin layout information.
GPIOs Modes
***********
There are two different modes in the GPIO configuration:
- **Input Mode**
In this mode, the GPIO will receive the digital state from a specific device. This device could be a button or a switch.
- **Output Mode**
For the output mode, the GPIO will change the GPIO digital state to a specific device. You can drive an LED for example.
GPIO API
--------
Here is the common functions used for the GPIO peripheral.
pinMode
*******
The ``pinMode`` function is used to define the GPIO operation mode for a specific pin.
.. code-block:: arduino
void pinMode(uint8_t pin, uint8_t mode);
* ``pin`` defines the GPIO pin number.
* ``mode`` sets operation mode.
The following modes are supported for the basic `input` and `output`:
* **INPUT** sets the GPIO as input without pullup or pulldown (high impedance).
* **OUTPUT** sets the GPIO as output/read mode.
* **INPUT_PULLDOWN** sets the GPIO as input with the internal pulldown.
* **INPUT_PULLUP** sets the GPIO as input with the internal pullup.
Internal Pullup and Pulldown
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ESP32 SoC families supports the internal pullup and pulldown throught a 45kR resistor, that can be enabled when configuring the GPIO mode as ``INPUT`` mode.
If the pullup or pulldown mode is not defined, the pin will stay in the high impedance mode.
digitalWrite
*************
The function ``digitalWrite`` sets the state of the selected GPIO to ``HIGH`` or ``LOW``. This function is only used if the ``pinMode`` was configured as ``OUTPUT``.
.. code-block:: arduino
void digitalWrite(uint8_t pin, uint8_t val);
* ``pin`` defines the GPIO pin number.
* ``val`` set the output digital state to ``HIGH`` or ``LOW``.
digitalRead
***********
To read the state of a given pin configured as ``INPUT``, the function ``digitalRead`` is used.
.. code-block:: arduino
int digitalRead(uint8_t pin);
* ``pin`` select GPIO
This function will return the logical state of the selected pin as ``HIGH`` or ``LOW``.
Interrupts
----------
The GPIO peripheral on the ESP32 supports interruptions.
attachInterrupt
***************
The function ``attachInterruptArg`` is used to attach the interrupt to the defined pin.
.. code-block:: arduino
attachInterrupt(uint8_t pin, voidFuncPtr handler, int mode);
* ``pin`` defines the GPIO pin number.
* ``handler`` set the handler function.
* ``mode`` set the interrupt mode.
Here are the supported interrupt modes:
* **DISABLED**
* **RISING**
* **FALLING**
* **CHANGE**
* **ONLOW**
* **ONHIGH**
* **ONLOW_WE**
* **ONHIGH_WE**
attachInterruptArg
******************
The function ``attachInterruptArg`` is used to attach the interrupt to the defined pin using arguments.
.. code-block:: arduino
attachInterruptArg(uint8_t pin, voidFuncPtrArg handler, void * arg, int mode);
* ``pin`` defines the GPIO pin number.
* ``handler`` set the handler function.
* ``arg`` pointer to the interrupt arguments.
* ``mode`` set the interrupt mode.
detachInterrupt
***************
To detach the interruption from a specific pin, use the ``detachInterrupt`` function giving the GPIO to be detached.
.. code-block:: arduino
detachInterrupt(uint8_t pin);
* ``pin`` defines the GPIO pin number.
.. _gpio_example_code:
Example Code
------------
GPIO Input and Output Modes
***************************
.. code-block:: arduino
#define LED 12
#define BUTTON 2
uint8_t stateLED = 0;
void setup() {
pinMode(LED, OUTPUT);
pinMode(BUTTON,INPUT_PULLUP);
}
void loop() {
if(!digitalRead(BUTTON)){
stateLED = stateLED^1;
digitalWrite(LED,stateLED);
}
}
GPIO Interrupt
**************
.. literalinclude:: ../../../libraries/ESP32/examples/GPIO/GPIOInterrupt/GPIOInterrupt.ino
:language: arduino
.. _datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf

384
docs/source/api/i2c.rst Normal file
View File

@ -0,0 +1,384 @@
###
I2C
###
About
-----
I2C (Inter-Integrated Circuit) / TWI (Two-wire Interface) is a widely used serial communication to connect devices in a short distance. This is one of the most common peripherals used to connect sensors, EEPROMs, RTC, ADC, DAC, displays, OLED, and many other devices and microcontrollers.
This serial communication is considered as a low-speed bus, and multiple devices can be connected on the same two-wires bus, each with a unique 7-bits address (up to 128 devices). These two wires are called SDA (serial data line) and SCL (serial clock line).
.. note:: The SDA and SCL lines require pull-up resistors. See the device datasheet for more details about the resistors' values and the operating voltage.
I2C Modes
*********
The I2C can be used in two different modes:
* **I2C Master Mode**
* In this mode, the ESP32 generates the clock signal and initiates the communication with the slave device.
.. figure:: ../_static/arduino_i2c_master.png
:align: center
:width: 720
:figclass: align-center
* **I2C Slave Mode**
* The slave mode, the clock is generated by the master device and responds to the master if the destination address is the same as the destination.
.. figure:: ../_static/arduino_i2c_slave.png
:align: center
:width: 520
:figclass: align-center
Arduino-ESP32 I2C API
---------------------
The ESP32 I2C library is based on the `Arduino Wire Library`_ and implements a few more APIs, described in this documentation.
I2C Common API
**************
Here are the common functions used for master and slave modes.
begin
^^^^^
This function is used to start the peripheral using the default configuration.
.. code-block:: arduino
bool begin();
This function will return ``true`` if the peripheral was initialized correctly.
setPins
^^^^^^^
This function is used to define the ``SDA`` and ``SCL`` pins.
.. note:: Call this function before ``begin`` to change the pins from the default ones.
.. code-block:: arduino
bool setPins(int sdaPin, int sclPin);
* ``sdaPin`` sets the GPIO to be used as the I2C peripheral data line.
* ``sclPin`` sets the GPIO to be used as the I2C peripheral clock line.
The default pins may vary from board to board. On the *Generic ESP32* the default I2C pins are:
* ``sdaPin`` **GPIO21**
* ``sclPin`` **GPIO22**
This function will return ``true`` if the peripheral was configured correctly.
setClock
^^^^^^^^
Use this function to set the bus clock. The default value will be used if this function is not used.
.. code-block:: arduino
bool setClock(uint32_t frequency);
* ``frequency`` sets the bus frequency clock.
This function will return ``true`` if the clock was configured correctly.
getClock
^^^^^^^^
Use this function to get the bus clock.
.. code-block:: arduino
uint32_t getClock();
This function will return the current frequency configuration.
setTimeOut
^^^^^^^^^^
Set the bus timeout given in milliseconds. The default value is 50ms.
.. code-block:: arduino
void setTimeOut(uint16_t timeOutMillis);
* ``timeOutMillis`` sets the timeout in ms.
getTimeOut
^^^^^^^^^^
Get the bus timeout in milliseconds.
.. code-block:: arduino
uint16_t getTimeOut();
This function will return the current timeout configuration.
.. _i2c write:
write
^^^^^
This function writes data to the buffer.
.. code-block:: arduino
size_t write(uint8_t);
or
.. code-block:: arduino
size_t write(const uint8_t *, size_t);
The return will be the size of the data added to the buffer.
.. _i2c end:
end
^^^
This function will finish the communication and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the I2C driver again.
.. code-block:: arduino
bool end();
I2C Master Mode
***************
This mode is used to initiate communication to the slave.
Basic Usage
^^^^^^^^^^^
To start using I2C master mode on the Arduino, the first step is to include the ``Wire.h`` header to the sketch.
.. code-block:: arduino
#include "Wire.h"
Now, we can start the peripheral configuration by calling ``begin`` function.
.. code-block:: arduino
Wire.begin();
By using ``begin`` without any arguments, all the settings will be done by using the default values. To set the values by your own, see the function description. This function is described here: `i2c begin`_
After calling ``begin``, we can start the transmission by calling ``beginTransmission`` and passing the I2C slave address:
.. code-block:: arduino
Wire.beginTransmission(I2C_DEV_ADDR);
To write some bytes to the slave, use the ``write`` function.
.. code-block:: arduino
Wire.write(x);
You can pass different data types using ``write`` function. This function is described here: `i2c write`_
.. note:: The ``write`` function does not write directly to the slave device but adds to the I2C buffer. To do so, you need to use the ``endTransmission`` function to send the buffered bytes to the slave device.
.. code-block:: arduino
Wire.endTransmission(true);
After calling ``endTransmission``, the data stored in the I2C buffer will be transmitted to the slave device.
Now you can request a reading from the slave device. The ``requestFrom`` will ask for a readout to the selected device by giving the address and the size.
.. code-block:: arduino
Wire.requestFrom(I2C_DEV_ADDR, SIZE);
and the ``readBytes`` will read it.
.. code-block:: arduino
Wire.readBytes(temp, error);
.. _i2c begin:
I2C Master APIs
***************
Here are the I2C master APIs. These function are intended to be used only for master mode.
begin
^^^^^
In master mode, the ``begin`` function can be used by passing the **pins** and **bus frequency**. Use this function only for the master mode.
.. code-block:: arduino
bool begin(int sdaPin, int sclPin, uint32_t frequency)
Alternatively, you can use the ``begin`` function without any argument to use all default values.
This function will return ``true`` if the peripheral was initialized correctly.
beginTransmission
^^^^^^^^^^^^^^^^^
This function is used to star a communication process with the slave device. Call this function by passing the slave ``address`` before writing the message to the buffer.
.. code-block:: arduino
void beginTransmission(uint16_t address)
endTransmission
^^^^^^^^^^^^^^^
After writing to the buffer using `i2c write`_, use the function ``endTransmission`` to send the message to the slave device address defined on the ``beginTransmission`` function.
.. code-block:: arduino
uint8_t endTransmission(bool sendStop);
* ``sendStop`` enables **(true)** or disables **(false)** the stop signal *(only used in master mode)*.
Calling the this function without ``sendStop`` is equivalent to ``sendStop = true``.
.. code-block:: arduino
uint8_t endTransmission(void);
This function will return the error code.
requestFrom
^^^^^^^^^^^
To read from the slave device, use the ``requestFrom`` function.
.. code-block:: arduino
uint8_t requestFrom(uint16_t address, uint8_t size, bool sendStop)
* ``address`` set the device address.
* ``size`` define the size to be requested.
* ``sendStop`` enables (true) or disables (false) the stop signal.
This function will return the number of bytes read from the device.
Example Application - WireMaster.ino
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is an example of how to use the I2C in Master Mode.
.. literalinclude:: ../../../libraries/Wire/examples/WireMaster/WireMaster.ino
:language: arduino
I2C Slave Mode
**************
This mode is used to accept communication from the master.
Basic Usage
^^^^^^^^^^^
To start using I2C as slave mode on the Arduino, the first step is to include the ``Wire.h`` header to the scketch.
.. code-block:: arduino
#include "Wire.h"
Before calling ``begin`` we must create two callback functions to handle the communication with the master device.
.. code-block:: arduino
Wire.onReceive(onReceive);
and
.. code-block:: arduino
Wire.onRequest(onRequest);
The ``onReceive`` will handle the request from the master device uppon a slave read request and the ``onRequest`` will handle the answer to the master.
Now, we can start the peripheral configuration by calling ``begin`` function with the device address.
.. code-block:: arduino
Wire.begin((uint8_t)I2C_DEV_ADDR);
By using ``begin`` without any arguments, all the settings will be done by using the default values. To set the values by your own, see the function description. This function is described here: `i2c begin`_
**For ESP32 only!**
Use the function ``slaveWrite`` in order to pre-write to the slave response buffer. This is used only for the ESP32 in order to add the slave capability on the chip and keep compatability with Arduino.
.. code-block:: arduino
Wire.slaveWrite((uint8_t *)message, strlen(message));
I2C Slave APIs
**************
Here are the I2C slave APIs. These function are intended to be used only for slave mode.
begin
^^^^^
In slave mode, the ``begin`` function must be used by passing the **slave address**. You can also define the **pins** and the **bus frequency**.
.. code-block:: arduino
bool Wire.begin(uint8_t addr, int sdaPin, int sclPin, uint32_t frequency)
This function will return ``true`` if the peripheral was initialized correctly.
onReceive
^^^^^^^^^
The ``onReceive`` function is used to define the callback for the data received from the master.
.. code-block:: arduino
void onReceive( void (*)(int) );
onRequest
^^^^^^^^^
The ``onRequest`` function is used to define the callback for the data to be send to the master.
.. code-block:: arduino
void onRequest( void (*)(void) );
slaveWrite
^^^^^^^^^^
The ``slaveWrite`` function writes on the slave response buffer before receiving the response message. This function is only used for adding the slave compatability for the ESP32.
.. warning:: This function is only required for the ESP32. You **don't** need to use for ESP32-S2 and ESP32-C3.
.. code-block:: arduino
size_t slaveWrite(const uint8_t *, size_t);
Example Application - WireSlave.ino
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is an example of how to use the I2C in Slave Mode.
.. literalinclude:: ../../../libraries/Wire/examples/WireSlave/WireSlave.ino
:language: arduino
.. _Arduino Wire Library: https://www.arduino.cc/en/reference/wire

566
docs/source/api/i2s.rst Normal file
View File

@ -0,0 +1,566 @@
###
I2S
###
About
-----
I2S - Inter-IC Sound, correctly written I²S pronounced "eye-squared-ess", alternative notation is IIS. I²S is an electrical serial bus interface standard used for connecting digital audio devices together.
It is used to communicate PCM (Pulse-Code Modulation) audio data between integrated circuits in an electronic device. The I²S bus separates clock and serial data signals, resulting in simpler receivers than those required for asynchronous communications systems that need to recover the clock from the data stream.
Despite the similar name, I²S is unrelated and incompatible with the bidirectional I²C (IIC) bus.
The I²S bus consists of at least three lines:
.. note:: All lines can be attached to almost any pin and this change can occur even during operation.
* **Bit clock line**
* Officially "continuous serial clock (SCK)". Typically written "bit clock (BCLK)".
* In this library function parameter ``sckPin`` or constant ``PIN_I2S_SCK``.
* **Word clock line**
* Officially "word select (WS)". Typically called "left-right clock (LRCLK)" or "frame sync (FS)".
* 0 = Left channel, 1 = Right channel
* In this library function parameter ``fsPin`` or constant ``PIN_I2S_FS``.
* **Data line**
* Officially "serial data (SD)", but can be called SDATA, SDIN, SDOUT, DACDAT, ADCDAT, etc.
* Unlike Arduino I2S with single data pin switching between input and output, in ESP core driver use separate data line for input and output.
* For backward compatibility, the shared data pin is ``sdPin`` or constant ``PIN_I2S_SD`` when using simplex mode.
* When using in duplex mode, there are two data lines:
* Output data line is called ``outSdPin`` for function parameter, or constant ``PIN_I2S_SD_OUT``
* Input data line is called ``inSdPin`` for function parameter, or constant ``PIN_I2S_SD_IN``
I2S Modes
---------
The I2S can be set up in three groups of modes:
* Master (default) or Slave.
* Simplex (default) or Duplex.
* Operation modes (Philips standard, ADC/DAC, PDM)
* Most of them are dual-channel, some can be single channel
.. note:: Officially supported operation mode is only ``I2S_PHILIPS_MODE``. Other modes are implemented, but we cannot guarantee flawless execution and behavior.
Master / Slave Mode
*******************
In **Master mode** (default) the device is generating clock signal ``sckPin`` and word select signal on ``fsPin``.
In **Slave mode** the device listens on attached pins for the clock signal and word select - i.e. unless externally driven the pins will remain LOW.
How to enter either mode is described in the function section.
Operation Modes
***************
Setting the operation mode is done with function ``begin`` (see API section)
* ``I2S_PHILIPS_MODE``
* Currently the only official* ``PIN_I2S_SCK``
* ``PIN_I2S_FS``
* ``PIN_I2S_SD``
* ``PIN_I2S_SD_OUT`` only need to send one channel data but the data will be copied for another channel automatically, then both channels will transmit same data.
* ``ADC_DAC_MODE``
The output will be an analog signal on pins ``25`` (L or R?) and ``26`` (L or R?).
Input will be received on pin ``_inSdPin``.
The data are sampled in 12 bits and stored in a 16 bits, with the 4 most significant bits set to zero.
* ``PDM_STEREO_MODE``
Pulse-density-modulation is similar to PWM, but instead, the pulses have constant width. The signal is modulated with the number of ones or zeroes in sequence.
* ``PDM_MONO_MODE``
Single-channel version of PDM mode described above.
Simplex / Duplex Mode
*********************
The **Simplex** mode is the default after driver initialization. Simplex mode uses the shared data pin ``sdPin`` or constant ``PIN_I2S_SD`` for both output and input, but can only read or write. This is the same behavior as in original Arduino library.
The **Duplex** mode uses two separate data pins:
* Output pin ``outSdPin`` for function parameter, or constant ``PIN_I2S_SD_OUT``
* Input pin ``inSdPin`` for function parameter, or constant ``PIN_I2S_SD_IN``
In this mode, the driver is able to read and write simultaneously on each line and is suitable for applications like walkie-talkie or phone.
Switching between these modes is performed simply by calling setDuplex() or setSimplex() (see APi section for details and more functions).
Arduino-ESP32 I2S API
---------------------
The ESP32 I2S library is based on the Arduino I2S Library and implements a few more APIs, described in this `documentation <https://www.arduino.cc/en/Reference/I2S>`_.
Initialization and deinitialization
***********************************
Before initialization, choose which pins you want to use. In DAC mode you can use only pins `25` and `26` for the output.
begin (Master Mode)
^^^^^^^^^^^^^^^^^^^
Before usage choose which pins you want to use. In DAC mode you can use only pins 25 and 26 as output.
.. code-block:: arduino
int begin(int mode, int sampleRate, int bitsPerSample)
Parameters:
* [in] ``mode`` one of above mentioned operation mode, for example ``I2S_PHILIPS_MODE``.
* [in] ``sampleRate`` is the sampling rate in Hz. Currently officially supported value is only 16000 - other than this value will print warning, but continue to operate, however the resulting audio quality may suffer and the app may crash.
* [in] ``bitsPerSample`` is the number of bits in a channel sample.
Currently, the supported value is only 16 - other than this value will print a warning, but continues to operate, however, the resulting audio quality may suffer and the application may crash.
For ``ADC_DAC_MODE`` the only possible value will remain 16.
This function will return ``true`` on success or ``fail`` in case of failure.
When failed, an error message will be printed if subscribed.
begin (Slave Mode)
^^^^^^^^^^^^^^^^^^
Performs initialization before use - creates buffers, task handling underlying driver messages, configuring and starting the driver operation.
This version initializes I2S in SLAVE mode (see previous entry for MASTER mode).
.. code-block:: arduino
int begin(int mode, int bitsPerSample)
Parameters:
* [in] ``mode`` one of above mentioned modes for example ``I2S_PHILIPS_MODE``.
* [in] ``bitsPerSample`` is the umber of bits in a channel sample. Currently, the only supported value is only 16 - other than this value will print warning, but continue to operate, however the resulting audio quality may suffer and the app may crash.
For ``ADC_DAC_MODE`` the only possible value will remain 16.
This function will return ``true`` on success or ``fail`` in case of failure.
When failed, an error message will be printed if subscribed.
end
^^^
Performs safe deinitialization - free buffers, destroy task, end driver operation, etc.
.. code-block:: arduino
void end()
Pin setup
*********
Pins can be changed in two ways- 1st constants, 2nd functions.
.. note:: Shared data pin can be equal to any other data pin, but must not be equal to clock pin nor frame sync pin! Input and Output pins must not be equal, but one of them can be equal to shared data pin!
.. code-block:: arduino
sckPin != fsPin != outSdPin != inSdPin
.. code-block:: arduino
sckPin != fsPin != sdPin
By default, the pin numbers are defined in constants in the header file. You can redefine any of those constants before including ``I2S.h``. This way the driver will use these new default values and you will not need to specify pins in your code. The constants and their default values are:
* ``PIN_I2S_SCK`` 14
* ``PIN_I2S_FS`` 25
* ``PIN_I2S_SD`` 26
* ``PIN_I2S_SD_OUT`` 26
* ``PIN_I2S_SD_IN`` 35
The second option to change pins is using the following functions. These functions can be called on either on initialized or uninitialized object.
If called on the initialized object (after calling ``begin``) the pins will change during operation.
If called on the uninitialized object (before calling ``begin``, or after calling ``end``) the new pin setup will be used on next initialization.
setSckPin
^^^^^^^^^
Set and apply clock pin.
.. code-block:: arduino
int setSckPin(int sckPin)
This function will return ``true`` on success or ``fail`` in case of failure.
setFsPin
^^^^^^^^
Set and apply frame sync pin.
.. code-block:: arduino
int setFsPin(int fsPin)
This function will return ``true`` on success or ``fail`` in case of failure.
setDataPin
^^^^^^^^^^
Set and apply shared data pin used in simplex mode.
.. code-block:: arduino
int setDataPin(int sdPin)
This function will return ``true`` on success or ``fail`` in case of failure.
setDataInPin
^^^^^^^^^^^^
Set and apply data input pin.
.. code-block:: arduino
int setDataInPin(int inSdPin)
This function will return ``true`` on success or ``fail`` in case of failure.
setDataOutPin
^^^^^^^^^^^^^
Set and apply data output pin.
.. code-block:: arduino
int setDataOutPin(int outSdPin)
This function will return ``true`` on success or ``fail`` in case of failure.
setAllPins
^^^^^^^^^^
Set all pins using given values in parameters. This is simply a wrapper of four functions mentioned above.
.. code-block:: arduino
int setAllPins(int sckPin, int fsPin, int sdPin, int outSdPin, int inSdPin)
Set all pins to default i.e. take values from constants mentioned above. This simply calls the the function with the following constants.
* ``PIN_I2S_SCK`` 14
* ``PIN_I2S_FS`` 25
* ``PIN_I2S_SD`` 26
* ``PIN_I2S_SD_OUT`` 26
* ``PIN_I2S_SD_IN`` 35
.. code-block:: arduino
int setAllPins()
getSckPin
^^^^^^^^^
Get the current value of the clock pin.
.. code-block:: arduino
int getSckPin()
getFsPin
^^^^^^^^
Get the current value of frame sync pin.
.. code-block:: arduino
int getFsPin()
getDataPin
^^^^^^^^^^
Get the current value of shared data pin.
.. code-block:: arduino
int getDataPin()
getDataInPin
^^^^^^^^^^^^
Get the current value of data input pin.
.. code-block:: arduino
int getDataInPin()
getDataOutPin
^^^^^^^^^^^^^
Get the current value of data output pin.
.. code-block:: arduino
int getDataOutPin()
onTransmit
^^^^^^^^^^
Register the function to be called on each successful transmit event.
.. code-block:: arduino
void onTransmit(void(*)(void))
onReceive
^^^^^^^^^
Register the function to be called on each successful receives event.
.. code-block:: arduino
void onReceive(void(*)(void))
setBufferSize
^^^^^^^^^^^^^
Set the size of buffer.
.. code-block:: arduino
int setBufferSize(int bufferSize)
This function can be called on both the initialized or uninitialized driver.
If called on initialized, it will change internal values for buffer size and re-initialize driver with new value.
If called on uninitialized, it will only change the internal values which will be used for next initialization.
Parameter ``bufferSize`` must be in range from 8 to 1024 and the unit is sample words. The default value is 128.
Example: 16 bit sample, dual channel, buffer size for input:
``128 = 2B sample * 2 channels * 128 buffer size * buffer count (default 2) = 1024B``
And more ```1024B`` for output buffer in total of ``2kB`` used.
This function always assumes dual-channel, keeping the same size even for MONO modes.
This function will return ``true`` on success or ``fail`` in case of failure.
When failed, an error message will be printed.
getBufferSize
^^^^^^^^^^^^^
Get current buffer sizes in sample words (see description for ``setBufferSize``).
.. code-block:: arduino
int getBufferSize()
Duplex vs Simplex
*****************
Original Arduino I2S library supports only *simplex* mode (only transmit or only receive at a time). For compatibility, we kept this behavior, but ESP natively supports *duplex* mode (receive and transmit simultaneously on separate pins).
By default this library is initialized in simplex mode as it would in Arduino, switching input and output on ``sdPin`` (constant ``PIN_I2S_SD`` default pin 26).
setDuplex
^^^^^^^^^
Switch to duplex mode and use separate pins:
.. code-block:: arduino
int setDuplex()
input: inSdPin (constant PIN_I2S_SD_IN, default 35)
output: outSdPin (constant PIN_I2S_SD, default 26)
setSimplex
^^^^^^^^^^
(Default mode)
Switch to simplex mode using shared data pin sdPin (constant PIN_I2S_SD, default 26).
.. code-block:: arduino
int setSimplex()
isDuplex
^^^^^^^^
Returns 1 if current mode is duplex, 0 if current mode is simplex (default).
.. code-block:: arduino
int isDuplex()
Data stream
***********
available
^^^^^^^^^
Returns number of **bytes** ready to read.
.. code-block:: arduino
int available()
read
^^^^
Read ``size`` bytes from internal buffer if possible.
.. code-block:: arduino
int read(void* buffer, size_t size)
This function is non-blocking, i.e. if the requested number of bytes is not available, it will return as much as possible without waiting.
Hint: use ``available()`` before calling this function.
Parameters:
[out] ``void* buffer`` buffer into which will be copied data read from internal buffer. WARNING: this buffer must be allocated before use!
[in] ``size_t size`` number of bytes required to be read.
Returns number of successfully bytes read. Returns ``false``` in case of reading error.
Read one sample.
.. code-block:: arduino
int read()
peek
^^^^
Read one sample from the internal buffer and returns it.
.. code-block:: arduino
int peek()
Repeated peeks will be returned in the same sample until ``read`` is called.
flush
^^^^^
Force write internal buffer to driver.
.. code-block:: arduino
void flush()
write
^^^^^
Write a single byte.
.. code-block:: arduino
size_t write(uint8_t)
Single-sample writes are blocking - waiting until there is free space in the internal buffer to be written into.
Returns number of successfully written bytes, in this case, 1. Returns 0 on error.
Write single sample.
.. code-block:: arduino
size_t write(int32_t)
Single-sample writes are blocking - waiting until there is free space in the internal buffer to be written into.
Returns number of successfully written bytes. Returns 0 on error.
Expected return number is ``bitsPerSample/8``.
Write buffer of supplied size;
.. code-block:: arduino
size_t write(const void *buffer, size_t size)
Parameters:
[in] ``const void *buffer`` buffer to be written
[in] ``size_t size`` size of buffer in bytes
Returns number of successfully written bytes. Returns 0 in case of error.
The expected return number is equal to ``size``.
write
^^^^^
This is a wrapper of the previous function performing typecast from `uint8_t*`` to ``void*``.
.. code-block:: arduino
size_t write(const uint8_t *buffer, size_t size)
availableForWrite
^^^^^^^^^^^^^^^^^
Returns number of bytes available for write.
.. code-block:: arduino
int availableForWrite()
write_blocking
^^^^^^^^^^^^^^
Core function implementing blocking write, i.e. waits until all requested data are written.
.. code-block:: arduino
size_t write_blocking(const void *buffer, size_t size)
WARNING: If too many bytes are requested, this can cause WatchDog Trigger Reset!
Returns number of successfully written bytes. Returns 0 on error.
write_nonblocking
^^^^^^^^^^^^^^^^^
Core function implementing non-blocking write, i.e. writes as much as possible and exits.
.. code-block:: arduino
size_t write_nonblocking(const void *buffer, size_t size)
Returns number of successfully written bytes. Returns 0 on error.
Sample code
-----------
.. code-block:: c
#include <I2S.h>
const int buff_size = 128;
int available, read;
uint8_t buffer[buff_size];
I2S.begin(I2S_PHILIPS_MODE, 16000, 16);
I2S.read(); // Switch the driver in simplex mode to receive
available = I2S.available();
if(available < buff_size){
read = I2S.read(buffer, available);
}else{
read = I2S.read(buffer, buff_size);
}
I2S.write(buffer, read);
I2S.end();

183
docs/source/api/ledc.rst Normal file
View File

@ -0,0 +1,183 @@
##################
LED Control (LEDC)
##################
About
-----
The LED control (LEDC) peripheral is primarly designed to control the intensity of LEDs,
although it can also be used to generate PWM signals for other purposes.
ESP32 SoCs has from 6 to 16 channels (variates on socs, see table below) which can generate independent waveforms, that can be used for example to drive RGB LED devices.
========= =======================
ESP32 SoC Number of LEDC channels
========= =======================
ESP32 16
ESP32-S2 8
ESP32-C3 6
ESP32-S3 8
========= =======================
Arduino-ESP32 LEDC API
----------------------
ledcSetup
*********
This function is used to setup the LEDC channel frequency and resolution.
.. code-block:: arduino
double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits);
* ``channel`` select LEDC channel to config.
* ``freq`` select frequency of pwm.
* ``resolution_bits`` select resolution for ledc channel.
* range is 1-14 bits (1-20 bits for ESP32).
This function will return ``frequency`` configured for LEDC channel.
If ``0`` is returned, error occurs and ledc channel was not configured.
ledcWrite
*********
This function is used to set duty for the LEDC channel.
.. code-block:: arduino
void ledcWrite(uint8_t chan, uint32_t duty);
* ``chan`` select the LEDC channel for writing duty.
* ``duty`` select duty to be set for selected channel.
ledcRead
********
This function is used to get configured duty for the LEDC channel.
.. code-block:: arduino
uint32_t ledcRead(uint8_t chan);
* ``chan`` select LEDC channel to read the configured duty.
This function will return ``duty`` set for selected LEDC channel.
ledcReadFreq
************
This function is used to get configured frequency for the LEDC channel.
.. code-block:: arduino
double ledcReadFreq(uint8_t chan);
* ``chan`` select the LEDC channel to read the configured frequency.
This function will return ``frequency`` configured for selected LEDC channel.
ledcWriteTone
*************
This function is used to setup the LEDC channel to 50 % PWM tone on selected frequency.
.. code-block:: arduino
double ledcWriteTone(uint8_t chan, double freq);
* ``chan`` select LEDC channel.
* ``freq`` select frequency of pwm signal.
This function will return ``frequency`` set for channel.
If ``0`` is returned, error occurs and ledc cahnnel was not configured.
ledcWriteNote
*************
This function is used to setup the LEDC channel to specific note.
.. code-block:: arduino
double ledcWriteNote(uint8_t chan, note_t note, uint8_t octave);
* ``chan`` select LEDC channel.
* ``note`` select note to be set.
======= ======= ======= ======= ======= ======
NOTE_C NOTE_Cs NOTE_D NOTE_Eb NOTE_E NOTE_F
NOTE_Fs NOTE_G NOTE_Gs NOTE_A NOTE_Bb NOTE_B
======= ======= ======= ======= ======= ======
* ``octave`` select octave for note.
This function will return ``frequency`` configured for the LEDC channel according to note and octave inputs.
If ``0`` is returned, error occurs and the LEDC channel was not configured.
ledcAttachPin
*************
This function is used to attach the pin to the LEDC channel.
.. code-block:: arduino
void ledcAttachPin(uint8_t pin, uint8_t chan);
* ``pin`` select GPIO pin.
* ``chan`` select LEDC channel.
ledcDetachPin
*************
This function is used to detach the pin from LEDC.
.. code-block:: arduino
void ledcDetachPin(uint8_t pin);
* ``pin`` select GPIO pin.
ledcChangeFrequency
*******************
This function is used to set frequency for the LEDC channel.
.. code-block:: arduino
double ledcChangeFrequency(uint8_t chan, double freq, uint8_t bit_num);
* ``channel`` select LEDC channel.
* ``freq`` select frequency of pwm.
* ``bit_num`` select resolution for LEDC channel.
* range is 1-14 bits (1-20 bits for ESP32).
This function will return ``frequency`` configured for the LEDC channel.
If ``0`` is returned, error occurs and the LEDC channel frequency was not set.
analogWrite
***********
This function is used to write an analog value (PWM wave) on the pin.
It is compatible with Arduinos analogWrite function.
.. code-block:: arduino
void analogWrite(uint8_t pin, int value);
* ``pin`` select the GPIO pin.
* ``value`` select the duty cycle of pwm.
* range is from 0 (always off) to 255 (always on).
Example Applications
********************
LEDC software fade example:
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/LEDCSoftwareFade/LEDCSoftwareFade.ino
:language: arduino
LEDC Write RGB example:
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/ledcWrite_RGB/ledcWrite_RGB.ino
:language: arduino

701
docs/source/api/preferences.rst Normal file
View File

@ -0,0 +1,701 @@
###########
Preferences
###########
About
-----
The Preferences library is unique to arduino-esp32. It should be considered as the replacement for the Arduino EEPROM library.
It uses a portion of the on-board non-volatile memory (NVS) of the ESP32 to store data. This data is retained across restarts and loss of power events to the system.
Preferences works best for storing many small values, rather than a few large values. If large amounts of data are to be stored, consider using a file system library such as LitteFS.
The Preferences library is usable by all ESP32 variants.
Header File
-----------
.. code-block:: arduino
#include <Preferences.h>
..
Overview
--------
Library methods are provided to:
- create a namespace;
- open and close a namespace;
- store and retrieve data within a namespace for supported data types;
- determine if a key value has been initialized;
- delete a ``key-value`` pair;
- delete all ``key-value`` pairs in a namespace;
- determine data types stored against a key;
- determine the number of key entries in the namespace.
Preferences directly supports the following data types:
.. table:: **Table 1 — Preferences Data Types**
:align: center
+-------------------+-------------------+---------------+
| Preferences Type | Data Type | Size (bytes) |
+===================+===================+===============+
| Bool | bool | 1 |
+-------------------+-------------------+---------------+
| Char | int8_t | 1 |
+-------------------+-------------------+---------------+
| UChar | uint8_t | 1 |
+-------------------+-------------------+---------------+
| Short | int16_t | 2 |
+-------------------+-------------------+---------------+
| UShort | uint16_t | 2 |
+-------------------+-------------------+---------------+
| Int | int32_t | 4 |
+-------------------+-------------------+---------------+
| UInt | uint32_t | 4 |
+-------------------+-------------------+---------------+
| Long | int32_t | 4 |
+-------------------+-------------------+---------------+
| ULong | uint32_t | 4 |
+-------------------+-------------------+---------------+
| Long64 | int64_t | 8 |
+-------------------+-------------------+---------------+
| ULong64 | uint64_t | 8 |
+-------------------+-------------------+---------------+
| Float | float_t | 8 |
+-------------------+-------------------+---------------+
| Double | double_t | 8 |
+-------------------+-------------------+---------------+
| | const char* | variable |
| String +-------------------+ |
| | String | |
+-------------------+-------------------+---------------+
| Bytes | uint8_t | variable |
+-------------------+-------------------+---------------+
String values can be stored and retrieved either as an Arduino String or as a null terminated ``char`` array (c-string).
Bytes type is used for storing and retrieving an arbitrary number of bytes in a namespace.
Arduino-esp32 Preferences API
-----------------------------
``begin``
**********
Open non-volatile storage with a given namespace name from an NVS partition.
.. code-block:: arduino
bool begin(const char * name, bool readOnly=false, const char* partition_label=NULL)
..
**Parameters**
* ``name`` (Required)
- Namespace name. Maximum length is 15 characters.
* ``readOnly`` (Optional)
- ``false`` will open the namespace in read-write mode.
- ``true`` will open the namespace in read-only mode.
- if omitted, the namespace is opened in read-write mode.
* ``partition_label`` (Optional)
- name of the NVS partition in which to open the namespace.
- if omitted, the namespace is opened in the "``nvs``" partition.
**Returns**
* ``true`` if the namespace was opened successfully; ``false`` otherwise.
**Notes**
* If the namespace does not exist within the partition, it is first created.
* Attempting to write a key value to a namespace open in read-only mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``end``
*********
Close the currently opened namespace.
.. code-block:: arduino
void end()
..
**Parameters**
* None
**Returns**
* Nothing
**Note**
* After closing a namespace, methods used to access it will fail.
``clear``
**********
Delete all keys and values from the currently opened namespace.
.. code-block:: arduino
bool clear()
..
**Parameters**
* None
**Returns**
* ``true`` if all keys and values were deleted; ``false`` otherwise.
**Note**
* the namespace name still exists afterward.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``remove``
*************
Delete a key-value pair from the currently open namespace.
.. code-block:: arduino
bool remove(const char * key)
..
**Parameters**
* ``key`` (Required)
- the name of the key to be deleted.
**Returns**
* ``true`` if key-value pair was deleted; ``false`` otherwise.
**Note**
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putChar, putUChar``
**********************
Store a value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putChar(const char* key, int8_t value)
size_t putUChar(const char* key, uint8_t value)
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- must match the data type of the method.
**Returns**
* ``1`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putShort, putUShort``
************************
Store a value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putShort(const char* key, int16_t value)
size_t putUShort(const char* key, uint16_t value)
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- must match the data type of the method.
**Returns**
* ``2`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putInt, putUInt``
********************
``putLong, putULong``
**********************
Store a value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putInt(const char* key, int32_t value)
size_t putUInt(const char* key, uint32_t value)
size_t putLong(const char* key, int32_t value)
size_t putULong(const char* key, uint32_t value)
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- must match the data type of the method.
**Returns**
* ``4`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putLong64, putULong64``
*************************
``putFloat, putDouble``
***********************
Store a value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putLong64(const char* key, int64_t value)
size_t putULong64(const char* key, uint64_t value)
size_t putFloat(const char* key, float_t value)
size_t putDouble(const char* key, double_t value)
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- must match the data type of the method.
**Returns**
* ``8`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putBool``
***********
Store a value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putBool(const char* key, bool value)
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- must match the data type of the method.
**Returns**
* ``true`` if successful; ``false`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putString``
**************
Store a variable length value against a given key in the currently open namespace.
.. code-block:: arduino
size_t putString(const char* key, const char* value);
size_t putString(const char* key, String value);
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- if ``const char*``, a null-terminated (c-string) character array.
- if ``String``, a valid Arduino String type.
**Returns**
* if successful: the number of bytes stored; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``putBytes``
************
Store a variable number of bytes against a given key in the currently open namespace.
.. code-block:: arduino
size_t putBytes(const char* key, const void* value, size_t len);
..
**Parameters**
* ``key`` (Required)
- if the key does not exist in the currently opened namespace it is first created.
* ``value`` (Required)
- pointer to an array or buffer containing the bytes to be stored.
* ``len`` (Required)
- the number of bytes from ``value`` to be stored.
**Returns**
* if successful: the number of bytes stored; ``0`` otherwise.
**Notes**
* Attempting to store a value without a namespace being open in read-write mode will fail.
* This method operates on the bytes used by the underlying data type, not the number of elements of a given data type. The data type of ``value`` is not retained by the Preferences library afterward.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``getChar, getUChar``
*********************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
int8_t getChar(const char* key, int8_t defaultValue = 0)
uint8_t getUChar(const char* key, uint8_t defaultValue = 0)
..
**Parameters**
* ``key`` (Required)
* ``defaultValue`` (Optional)
- must match the data type of the method if provided.
**Returns**
* the value stored against ``key`` if the call is successful.
* ``defaultValue``, if it is provided; ``0`` otherwise.
**Notes**
* Attempting to retrieve a key without a namespace being available will fail.
* Attempting to retrieve value from a non existant key will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``getShort, getUShort``
****************************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
int16_t getShort(const char* key, int16_t defaultValue = 0)
uint16_t getUShort(const char* key, uint16_t defaultValue = 0)
..
Except for the data type returned, behaves exactly like ``getChar``.
``getInt, getUInt``
*******************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
int32_t getInt(const char* key, int32_t defaultValue = 0)
uint32_t getUInt(const char* key, uint32_t defaultValue = 0)
..
Except for the data type returned, behaves exactly like ``getChar``.
``getLong, getULong``
*********************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
int32_t getLong(const char* key, int32_t defaultValue = 0)
uint32_t getULong(const char* key, uint32_t defaultValue = 0)
..
Except for the data type returned, behaves exactly like ``getChar``.
``getLong64, getULong64``
*************************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
int64_t getLong64(const char* key, int64_t defaultValue = 0)
uint64_t getULong64(const char* key, uint64_t defaultValue = 0)
..
Except for the data type returned, behaves exactly like ``getChar``.
``getFloat``
*************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
float_t getFloat(const char* key, float_t defaultValue = NAN)
..
Except for the data type returned and the value of ``defaultValue``, behaves exactly like ``getChar``.
``getDouble``
*************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
double_t getDouble(const char* key, double_t defaultValue = NAN)
..
Except for the data type returned and the value of ``defaultValue``, behaves exactly like ``getChar``.
``getBool``
************
Retrieve a value stored against a given key in the currently open namespace.
.. code-block:: arduino
uint8_t getUChar(const char* key, uint8_t defaultValue = 0);
..
Except for the data type returned, behaves exactly like ``getChar``.
``getString``
*************
Copy a string of ``char`` stored against a given key in the currently open namespace to a buffer.
.. code-block:: arduino
size_t getString(const char* key, char* value, size_t len);
..
**Parameters**
* ``key`` (Required)
* ``value`` (Required)
- a buffer of a size large enough to hold ``len`` bytes
* ``len`` (Required)
- the number of type ``char``` to be written to the buffer pointed to by ``value``
**Returns**
* if successful; the number of bytes equal to ``len`` is written to the buffer pointed to by ``value``, and the method returns ``1``.
* if the method fails, nothing is written to the buffer pointed to by ``value`` and the method returns ``0``.
**Notes**
* ``len`` must equal the number of bytes stored against the key or the call will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``getString``
*************
Retrieve an Arduino String value stored against a given key in the currently open namespace.
.. code-block:: arduino
String getString(const char* key, String defaultValue = String());
..
**Parameters**
* ``key`` (Required)
* ``defaultValue`` (Optional)
**Returns**
* the value stored against ``key`` if the call if successful
* if the method fails: it returns ``defaultValue``, if provided; ``""`` (an empty String) otherwise.
**Notes**
* ``defaultValue`` must be of type ``String``.
``getBytes``
*************
Copy a series of bytes stored against a given key in the currently open namespace to a buffer.
.. code-block:: arduino
size_t getBytes(const char* key, void * buf, size_t len);
..
**Parameters**
* ``key`` (Required)
* ``buf`` (Required)
- a buffer of a size large enough to hold ``len`` bytes.
* ``len`` (Required)
- the number of bytes to be written to the buffer pointed to by ``buf``
**Returns**
* if successful, the number of bytes equal to ``len`` is written to buffer ``buf``, and the method returns ``1``.
* if the method fails, nothing is written to the buffer and the method returns ``0``.
**Notes**
* ``len`` must equal the number of bytes stored against the key or the call will fail.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``getBytesLength``
******************
Get the number of bytes stored in the value against a key of type ``Bytes`` in the currently open namespace.
.. code-block:: arduino
size_t getBytesLength(const char* key)
..
**Parameters**
* ``key`` (Required)
**Returns**
* if successful: the number of bytes in the value stored against ``key``; ``0`` otherwise.
**Notes**
* This method will fail if ``key`` is not of type ``Bytes``.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
``getType``
***********
Get the Preferences data type of a given key within the currently open namespace.
.. code-block:: arduino
PreferenceType getType(const char* key)
..
**Parameters**
* ``key`` (Required)
**Returns**
* an ``int`` value as per Table 2 below.
* a value of ``10`` (PT_INVALID) if the call fails.
**Notes**
* The return values are enumerated in ``Preferences.h``. Table 2 includes the enumerated values for information.
* A return value can map to more than one Prefs Type.
* The method will fail if: the namespace is not open; the key does not exist; the provided key exceeds 15 characters.
.. table:: **Table 2 — getType Return Values**
:align: center
+---------------+---------------+-------------------+-----------------------+
| Return value | Prefs Type | Data Type | Enumerated Value |
+===============+===============+===================+=======================+
| 0 | Char | int8_t | PT_I8 |
+---------------+---------------+-------------------+-----------------------+
| 1 | UChar | uint8_t | PT_U8 |
| +---------------+-------------------+ |
| | Bool | bool | |
+---------------+---------------+-------------------+-----------------------+
| 2 | Short | int16_t | PT_I16 |
+---------------+---------------+-------------------+-----------------------+
| 3 | UShort | uint16_t | PT_U16 |
+---------------+---------------+-------------------+-----------------------+
| 4 | Int | int32_t | PT_I32 |
| +---------------+ | |
| | Long | | |
+---------------+---------------+-------------------+-----------------------+
| 5 | UInt | uint32_t | PT_U32 |
| +---------------+ | |
| | ULong | | |
+---------------+---------------+-------------------+-----------------------+
| 6 | Long64 | int64_t | PT_I64 |
+---------------+---------------+-------------------+-----------------------+
| 7 | ULong64 | uint64_t | PT_U64 |
+---------------+---------------+-------------------+-----------------------+
| 8 | String | String | PT_STR |
| | +-------------------+ |
| | | \*char | |
+---------------+---------------+-------------------+-----------------------+
| 9 | Double | double_t | PT_BLOB |
| +---------------+-------------------+ |
| | Float | float_t | |
| +---------------+-------------------+ |
| | Bytes | uint8_t | |
+---------------+---------------+-------------------+-----------------------+
| 10 | \- | \- | PT_INVALID |
+---------------+---------------+-------------------+-----------------------+
``freeEntries``
***************
Get the number of free entries available in the key table of the currently open namespace.
.. code-block:: arduino
size_t freeEntries()
..
**Parameters**
* none
**Returns**
* if successful: the number of free entries available in the key table of the currently open namespace; ``0`` otherwise.
**Notes**
* keys storing values of type ``Bool``, ``Char``, ``UChar``, ``Short``, ``UShort``, ``Int``, ``UInt``, ``Long``, ``ULong``, ``Long64``, ``ULong64`` use one entry in the key table.
* keys storing values of type ``Float`` and ``Double`` use three entries in the key table.
* Arduino or c-string ``String`` types use a minimum of two key table entries with the number of entries increasing with the length of the string.
* keys storing values of type ``Bytes`` use a minimum of three key table entries with the number of entries increasing with the number of bytes stored.
* A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
.. --- EOF ----

3
docs/source/api/rainmaker.rst Normal file
View File

@ -0,0 +1,3 @@
#########
RainMaker
#########

3
docs/source/api/reset_reason.rst Normal file
View File

@ -0,0 +1,3 @@
############
Reset Reason
############

84
docs/source/api/sigmadelta.rst Normal file
View File

@ -0,0 +1,84 @@
##########
SigmaDelta
##########
About
-----
ESP32 provides a second-order sigma delta modulation module and 8 (4 for ESP32-C3)
independent modulation channels. The channels are capable to output 1-bit
signals (output index: 100 ~ 107) with sigma delta modulation.
========= =============================
ESP32 SoC Number of SigmaDelta channels
========= =============================
ESP32 8
ESP32-S2 8
ESP32-C3 4
ESP32-S3 8
========= =============================
Arduino-ESP32 SigmaDelta API
----------------------------
sigmaDeltaSetup
***************
This function is used to setup the SigmaDelta channel frequency and resolution.
.. code-block:: arduino
double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits);
* ``pin`` select GPIO pin.
* ``channel`` select SigmaDelta channel.
* ``freq`` select frequency.
* range is 1-14 bits (1-20 bits for ESP32).
This function will return ``frequency`` configured for the SigmaDelta channel.
If ``0`` is returned, error occurs and the SigmaDelta channel was not configured.
sigmaDeltaWrite
***************
This function is used to set duty for the SigmaDelta channel.
.. code-block:: arduino
void sigmaDeltaWrite(uint8_t channel, uint8_t duty);
* ``channel`` select SigmaDelta channel.
* ``duty`` select duty to be set for selected channel.
sigmaDeltaRead
**************
This function is used to get configured duty for the SigmaDelta channel.
.. code-block:: arduino
uint8_t sigmaDeltaRead(uint8_t channel)
* ``channnel`` select SigmaDelta channel.
This function will return ``duty`` configured for the selected SigmaDelta channel.
sigmaDeltaDetachPin
*******************
This function is used to detach pin from SigmaDelta.
.. code-block:: arduino
void sigmaDeltaDetachPin(uint8_t pin);
* ``pin`` select GPIO pin.
Example Applications
********************
Here is example use of SigmaDelta:
.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/SigmaDelta/SigmaDelta.ino
:language: arduino

377
docs/source/api/timer.rst Normal file
View File

@ -0,0 +1,377 @@
##########
Timer
##########
About
-----
The ESP32 SoCs contains from 2 to 4 hardware timers.
They are all 64-bit (54-bit for ESP32-C3) generic timers based on 16-bit pre-scalers and 64-bit (54-bit for ESP32-C3)
up / down counters which are capable of being auto-reloaded.
========= ================
ESP32 SoC Number of timers
========= ================
ESP32 4
ESP32-S2 4
ESP32-C3 2
ESP32-S3 4
========= ================
Arduino-ESP32 Timer API
----------------------------
timerBegin
**********
This function is used to configure the timer. After successful setup the timer will automatically start.
.. code-block:: arduino
hw_timer_t * timerBegin(uint8_t num, uint16_t divider, bool countUp);
* ``num`` select timer number.
* ``divider`` select timer divider.
* ``resolution`` select timer resolution.
* range is 1-14 bits (1-20 bits for ESP32).
This function will return ``timer`` structure if configuration is successful.
If ``NULL`` is returned, error occurs and the timer was not configured.
timerEnd
********
This function is used to end timer.
.. code-block:: arduino
void timerEnd(hw_timer_t *timer);
* ``timer`` timer struct.
timerSetConfig
**************
This function is used to configure initialized timer (timerBegin() called).
.. code-block:: arduino
uint32_t timerGetConfig(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``configuration`` as uint32_t number.
This can be translated by inserting it to struct ``timer_cfg_t.val``.
timerAttachInterrupt
********************
This function is used to attach interrupt to timer.
.. code-block:: arduino
void timerAttachInterrupt(hw_timer_t *timer, void (*fn)(void), bool edge);
* ``timer`` timer struct.
* ``fn`` funtion to be called when interrupt is triggered.
* ``edge`` select edge to trigger interrupt (only LEVEL trigger is currently supported).
timerDetachInterrupt
********************
This function is used to detach interrupt from timer.
.. code-block:: arduino
void timerDetachInterrupt(hw_timer_t *timer);
* ``timer`` timer struct.
timerStart
**********
This function is used to start counter of the timer.
.. code-block:: arduino
void timerStart(hw_timer_t *timer);
* ``timer`` timer struct.
timerStop
*********
This function is used to stop counter of the timer.
.. code-block:: arduino
void timerStop(hw_timer_t *timer);
* ``timer`` timer struct.
timerRestart
************
This function is used to restart counter of the timer.
.. code-block:: arduino
void timerRestart(hw_timer_t *timer);
* ``timer`` timer struct.
timerWrite
**********
This function is used to set counter value of the timer.
.. code-block:: arduino
void timerWrite(hw_timer_t *timer, uint64_t val);
* ``timer`` timer struct.
* ``val`` counter value to be set.
timerSetDivider
***************
This function is used to set the divider of the timer.
.. code-block:: arduino
void timerSetDivider(hw_timer_t *timer, uint16_t divider);
* ``timer`` timer struct.
* ``divider`` divider to be set.
timerSetCountUp
***************
This function is used to configure counting direction of the timer.
.. code-block:: arduino
void timerSetCountUp(hw_timer_t *timer, bool countUp);
* ``timer`` timer struct.
* ``countUp`` select counting direction (``true`` = increment).
timerSetAutoReload
******************
This function is used to set counter value of the timer.
.. code-block:: arduino
void timerSetAutoReload(hw_timer_t *timer, bool autoreload);
* ``timer`` timer struct.
* ``autoreload`` select autoreload (``true`` = enabled).
timerStarted
************
This function is used to get if the timer is running.
.. code-block:: arduino
bool timerStarted(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``true`` if the timer is running. If ``false`` is returned, timer is stopped.
timerRead
*********
This function is used to read counter value of the timer.
.. code-block:: arduino
uint64_t timerRead(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``counter value`` of the timer.
timerReadMicros
***************
This function is used to read counter value in microseconds of the timer.
.. code-block:: arduino
uint64_t timerReadMicros(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``counter value`` of the timer in microseconds.
timerReadMilis
**************
This function is used to read counter value in miliseconds of the timer.
.. code-block:: arduino
uint64_t timerReadMilis(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``counter value`` of the timer in miliseconds.
timerReadSeconds
****************
This function is used to read counter value in seconds of the timer.
.. code-block:: arduino
double timerReadSeconds(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``counter value`` of the timer in seconds.
timerGetDivider
***************
This function is used to get divider of the timer.
.. code-block:: arduino
uint16_t timerGetDivider(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``divider`` of the timer.
timerGetCountUp
***************
This function is used get counting direction of the timer.
.. code-block:: arduino
bool timerGetCountUp(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``true`` if the timer counting direction is UP (incrementing).
If ``false`` returned, the timer counting direction is DOWN (decrementing).
timerGetAutoReload
******************
This function is used to get configuration of auto reload of the timer.
.. code-block:: arduino
bool timerGetAutoReload(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``true`` if the timer auto reload is enabled.
If ``false`` returned, the timer auto reload is disabled.
timerAlarmEnable
****************
This function is used to enable generation of timer alarm events.
.. code-block:: arduino
void timerAlarmEnable(hw_timer_t *timer);
* ``timer`` timer struct.
timerAlarmDisable
*****************
This function is used to disable generation of timer alarm events.
.. code-block:: arduino
void timerAlarmDisable(hw_timer_t *timer);
* ``timer`` timer struct.
timerAlarmWrite
***************
This function is used to configure alarm value and autoreload of the timer.
.. code-block:: arduino
void timerAlarmWrite(hw_timer_t *timer, uint64_t alarm_value, bool autoreload);
* ``timer`` timer struct.
* ``alarm_value`` alarm value to generate event.
* ``autoreload`` enabled/disabled autorealod.
timerAlarmEnabled
*****************
This function is used to get status of timer alarm.
.. code-block:: arduino
bool timerAlarmEnabled(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``true`` if the timer alarm is enabled.
If ``false`` returned, the timer alarm is disabled.
timerAlarmRead
**************
This function is used to read alarm value of the timer.
.. code-block:: arduino
uint64_t timerAlarmRead(hw_timer_t *timer);
* ``timer`` timer struct.
timerAlarmReadMicros
********************
This function is used to read alarm value of the timer in microseconds.
.. code-block:: arduino
uint64_t timerAlarmReadMicros(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``alarm value`` of the timer in microseconds.
timerAlarmReadSeconds
*********************
This function is used to read alarm value of the timer in seconds.
.. code-block:: arduino
double timerAlarmReadSeconds(hw_timer_t *timer);
* ``timer`` timer struct.
This function will return ``alarm value`` of the timer in seconds.
Example Applications
********************
There are 2 examples uses of Timer:
Repeat timer example:
.. literalinclude:: ../../../libraries/ESP32/examples/Timer/RepeatTimer/RepeatTimer.ino
:language: arduino
Watchdog timer example:
.. literalinclude:: ../../../libraries/ESP32/examples/Timer/WatchdogTimer/WatchdogTimer.ino
:language: arduino

331
docs/source/api/usb.rst Normal file
View File

@ -0,0 +1,331 @@
#######
USB API
#######
.. note:: This feature is only supported on ESP chips that have USB peripheral, like the ESP32-S2 and ESP32-S3. Some chips, like the ESP32-C3 include native CDC+JTAG peripheral that is not covered here.
About
-----
The **Universal Serial Bus** is a widely used peripheral to exchange data between devices. USB was introduced on the ESP32, supporting both device and host mode.
To learn about the USB, see the `USB.org`_ for developers.
USB as Device
*************
In the device mode, the ESP32 acts as an USB device, like a mouse or keyboard to be connected to a host device, like your computer or smartphone.
USB as Host
***********
The USB host mode, you can connect devices on the ESP32, like external modems, mouse and keyboards.
.. note:: This mode is still under development for the ESP32.
API Description
---------------
This is the common USB API description.
For more supported USB classes implementation, see the following sections:
.. toctree::
:maxdepth: 1
:caption: Classes:
USB CDC <usb_cdc>
USB MSC <usb_msc>
USB Common
**********
These are the common APIs for the USB driver.
onEvent
^^^^^^^
Event handling function to set the callback.
.. code-block:: arduino
void onEvent(esp_event_handler_t callback);
Event handling function for the specific event.
.. code-block:: arduino
void onEvent(arduino_usb_event_t event, esp_event_handler_t callback);
Where ``event`` can be:
* ARDUINO_USB_ANY_EVENT
* ARDUINO_USB_STARTED_EVENT
* ARDUINO_USB_STOPPED_EVENT
* ARDUINO_USB_SUSPEND_EVENT
* ARDUINO_USB_RESUME_EVENT
* ARDUINO_USB_MAX_EVENT
VID
^^^
Set the Vendor ID. This 16 bits identification is used to identify the company that develops the product.
.. note:: You can't define your own VID. If you need your own VID, you need to buy one. See https://www.usb.org/getting-vendor-id for more details.
.. code-block:: arduino
bool VID(uint16_t v);
Get the Vendor ID.
.. code-block:: arduino
uint16_t VID(void);
Returns the Vendor ID. The default value for the VID is: ``0x303A``.
PID
^^^
Set the Product ID. This 16 bits identification is used to identify the product.
.. code-block:: arduino
bool PID(uint16_t p);
Get the Product ID.
.. code-block:: arduino
uint16_t PID(void);
Returns the Product ID. The default PID is: ``0x0002``.
firmwareVersion
^^^^^^^^^^^^^^^
Set the firmware version. This is a 16 bits unsigned value.
.. code-block:: arduino
bool firmwareVersion(uint16_t version);
Get the firmware version.
.. code-block:: arduino
uint16_t firmwareVersion(void);
Return the 16 bits unsigned value. The default value is: ``0x100``.
usbVersion
^^^^^^^^^^
Set the USB version.
.. code-block:: arduino
bool usbVersion(uint16_t version);
Get the USB version.
.. code-block:: arduino
uint16_t usbVersion(void);
Return the USB version. The default value is: ``0x200`` (USB 2.0).
usbPower
^^^^^^^^
Set the USB power as mA (current).
.. note:: This configuration does not change the physical power output. This is only used for the USB device information.
.. code-block:: arduino
bool usbPower(uint16_t mA);
Get the USB power configuration.
.. code-block:: arduino
uint16_t usbPower(void);
Return the current in mA. The default value is: ``0x500`` (500mA).
usbClass
^^^^^^^^
Set the USB class.
.. code-block:: arduino
bool usbClass(uint8_t _class);
Get the USB class.
.. code-block:: arduino
uint8_t usbClass(void);
Return the USB class. The default value is: ``TUSB_CLASS_MISC``.
usbSubClass
^^^^^^^^^^^
Set the USB sub-class.
.. code-block:: arduino
bool usbSubClass(uint8_t subClass);
Get the USB sub-class.
.. code-block:: arduino
uint8_t usbSubClass(void);
Return the USB sub-class. The default value is: ``MISC_SUBCLASS_COMMON``.
usbProtocol
^^^^^^^^^^^
Define the USB protocol.
.. code-block:: arduino
bool usbProtocol(uint8_t protocol);
Get the USB protocol.
.. code-block:: arduino
uint8_t usbProtocol(void);
Return the USB protocol. The default value is: ``MISC_PROTOCOL_IAD``
usbAttributes
^^^^^^^^^^^^^
Set the USB attributes.
.. code-block:: arduino
bool usbAttributes(uint8_t attr);
Get the USB attributes.
.. code-block:: arduino
uint8_t usbAttributes(void);
Return the USB attributes. The default value is: ``TUSB_DESC_CONFIG_ATT_SELF_POWERED``
webUSB
^^^^^^
This function is used to enable the ``webUSB`` functionality.
.. code-block:: arduino
bool webUSB(bool enabled);
This function is used to get the ``webUSB`` setting.
.. code-block:: arduino
bool webUSB(void);
Return the ``webUSB`` setting (`Enabled` or `Disabled`)
productName
^^^^^^^^^^^
This function is used to define the product name.
.. code-block:: arduino
bool productName(const char * name);
This function is used to get the product's name.
.. code-block:: arduino
const char * productName(void);
manufacturerName
^^^^^^^^^^^^^^^^
This function is used to define the manufacturer name.
.. code-block:: arduino
bool manufacturerName(const char * name);
This function is used to get the manufacturer's name.
.. code-block:: arduino
const char * manufacturerName(void);
serialNumber
^^^^^^^^^^^^
This function is used to define the serial number.
.. code-block:: arduino
bool serialNumber(const char * name);
This function is used to get the serial number.
.. code-block:: arduino
const char * serialNumber(void);
The default serial number is: ``0``.
webUSBURL
^^^^^^^^^
This function is used to define the ``webUSBURL``.
.. code-block:: arduino
bool webUSBURL(const char * name);
This function is used to get the ``webUSBURL``.
.. code-block:: arduino
const char * webUSBURL(void);
The default ``webUSBURL`` is: https://espressif.github.io/arduino-esp32/webusb.html
enableDFU
^^^^^^^^^
This function is used to enable the DFU capability.
.. code-block:: arduino
bool enableDFU();
begin
^^^^^
This function is used to start the peripheral using the default configuration.
.. code-block:: arduino
bool begin();
Example Code
------------
There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device.
.. _USB.org: https://www.usb.org/developers

193
docs/source/api/usb_cdc.rst Normal file
View File

@ -0,0 +1,193 @@
#######
USB CDC
#######
About
-----
USB Communications Device Class API. This class is used to enable communication between the host and the device.
This class is often used to enable serial communication and can be used to flash the firmware on the ESP32 without the external USB to Serial chip.
APIs
****
onEvent
^^^^^^^
Event handling functions.
.. code-block:: arduino
void onEvent(esp_event_handler_t callback);
.. code-block:: arduino
void onEvent(arduino_usb_cdc_event_t event, esp_event_handler_t callback);
Where ``event`` can be:
* ARDUINO_USB_CDC_ANY_EVENT
* ARDUINO_USB_CDC_CONNECTED_EVENT
* ARDUINO_USB_CDC_DISCONNECTED_EVENT
* ARDUINO_USB_CDC_LINE_STATE_EVENT
* ARDUINO_USB_CDC_LINE_CODING_EVENT
* ARDUINO_USB_CDC_RX_EVENT
* ARDUINO_USB_CDC_TX_EVENT
* ARDUINO_USB_CDC_RX_OVERFLOW_EVENT
* ARDUINO_USB_CDC_MAX_EVENT
setRxBufferSize
^^^^^^^^^^^^^^^
The ``setRxBufferSize`` function is used to set the size of the RX buffer.
.. code-block:: arduino
size_t setRxBufferSize(size_t size);
setTxTimeoutMs
^^^^^^^^^^^^^^
This function is used to define the time to reach the timeout for the TX.
.. code-block:: arduino
void setTxTimeoutMs(uint32_t timeout);
begin
^^^^^
This function is used to start the peripheral using the default CDC configuration.
.. code-block:: arduino
void begin(unsigned long baud);
Where:
* ``baud`` is the baud rate.
end
^^^
This function will finish the peripheral as CDC and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the USB CDC driver again.
.. code-block:: arduino
void end();
available
^^^^^^^^^
This function will return if there are messages in the queue.
.. code-block:: arduino
int available(void);
The return is the number of bytes available to read.
availableForWrite
^^^^^^^^^^^^^^^^^
This function will return if the hardware is available to write data.
.. code-block:: arduino
int availableForWrite(void);
peek
^^^^
This function is used to ``peek`` messages from the queue.
.. code-block:: arduino
int peek(void);
read
^^^^
This function is used to read the bytes available.
.. code-block:: arduino
size_t read(uint8_t *buffer, size_t size);
Where:
* ``buffer`` is the pointer to the buffer to be read.
* ``size`` is the number of bytes to be read.
write
^^^^^
This function is used to write the message.
.. code-block:: arduino
size_t write(const uint8_t *buffer, size_t size);
Where:
* ``buffer`` is the pointer to the buffer to be written.
* ``size`` is the number of bytes to be written.
flush
^^^^^
This function is used to flush the data.
.. code-block:: arduino
void flush(void);
baudRate
^^^^^^^^
This function is used to get the ``baudRate``.
.. code-block:: arduino
uint32_t baudRate();
setDebugOutput
^^^^^^^^^^^^^^
This function will enable the debug output, usually from the `UART0`, to the USB CDC.
.. code-block:: arduino
void setDebugOutput(bool);
enableReboot
^^^^^^^^^^^^
This function enables the device to reboot by the DTR as RTS signals.
.. code-block:: arduino
void enableReboot(bool enable);
rebootEnabled
^^^^^^^^^^^^^
This function will return if the reboot is enabled.
.. code-block:: arduino
bool rebootEnabled(void);
Example Code
------------
Here is an example of how to use the USB CDC.
USBSerial
*********
.. literalinclude:: ../../../libraries/USB/examples/USBSerial/USBSerial.ino
:language: arduino
.. _USB.org: https://www.usb.org/developers

114
docs/source/api/usb_msc.rst Normal file
View File

@ -0,0 +1,114 @@
#######
USB MSC
#######
About
-----
USB Mass Storage Class API. This class makes the device accessible as a mass storage device and allows you to transfer data between the host and the device.
One of the examples for this mode is to flash the device by dropping the firmware binary like a flash memory device when connecting the ESP32 to the host computer.
APIs
****
begin
^^^^^
This function is used to start the peripheral using the default MSC configuration.
.. code-block:: arduino
bool begin(uint32_t block_count, uint16_t block_size);
Where:
* ``block_count`` set the disk sector count.
* ``block_size`` set the disk sector size.
This function will return ``true`` if the configuration was successful.
end
^^^
This function will finish the peripheral as MSC and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the USB MSC driver again.
.. code-block:: arduino
void end();
vendorID
^^^^^^^^
This function is used to define the vendor ID.
.. code-block:: arduino
void vendorID(const char * vid);//max 8 chars
productID
^^^^^^^^^
This function is used to define the product ID.
.. code-block:: arduino
void productID(const char * pid);//max 16 chars
productRevision
^^^^^^^^^^^^^^^
This function is used to define the product revision.
.. code-block:: arduino
void productRevision(const char * ver);//max 4 chars
mediaPresent
^^^^^^^^^^^^
Set the ``mediaPresent`` configuration.
.. code-block:: arduino
void mediaPresent(bool media_present);
onStartStop
^^^^^^^^^^^
Set the ``onStartStop`` callback function.
.. code-block:: arduino
void onStartStop(msc_start_stop_cb cb);
onRead
^^^^^^
Set the ``onRead`` callback function.
.. code-block:: arduino
void onRead(msc_read_cb cb);
onWrite
^^^^^^^
Set the ``onWrite`` callback function.
.. code-block:: arduino
void onWrite(msc_write_cb cb);
Example Code
------------
Here is an example of how to use the USB MSC.
FirmwareMSC
***********
.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino
:language: arduino
.. _USB.org: https://www.usb.org/developers

563
docs/source/api/wifi.rst Normal file
View File

@ -0,0 +1,563 @@
#########
Wi-Fi API
#########
About
-----
The Wi-Fi API provides support for the 802.11b/g/n protocol driver. This API includes:
* Station mode (STA mode or Wi-Fi client mode). ESP32 connects to an access point
* AP mode (aka Soft-AP mode or Access Point mode). Devices connect to the ESP32
* Security modes (WPA2, WPA3 etc.)
* Scanning for access points
Working as AP
*************
In this mode, the ESP32 is configured as an Access Point (AP) and it's capable of receiving incoming connections from other devices (stations) by providing
a Wi-Fi network.
.. figure:: ../_static/wifi_esp32_ap.png
:align: center
:width: 520
:figclass: align-center
This mode can be used for serving an HTTP or HTTPS server inside the ESP32, for example.
Working as STA
**************
The STA mode is used to connect the ESP32 to a Wi-Fi network, provided by an Access Point.
.. figure:: ../_static/wifi_esp32_sta.png
:align: center
:width: 520
:figclass: align-center
This is the mode to be used if you want to connect your project to the Internet.
API Description
---------------
Here is the description of the WiFi API.
Common API
----------
Here are the common APIs that are used for both modes, AP and STA.
useStaticBuffers
****************
This function is used to set the memory allocation mode for the Wi-Fi buffers.
.. code-block:: arduino
static void useStaticBuffers(bool bufferMode);
* Set ``true`` to use the Wi-Fi buffers memory allocation as **static**.
* Set ``false`` to set the buffers memory allocation to **dynamic**.
The use of dynamic allocation is recommended to save memory and reduce resources usage. However, the dynamic performs slightly slower than the static allocation.
Use static allocation if you want to have more performance and if your application is multi-tasking.
By default, the memory allocation will be set to **dynamic** if this function is not being used.
setDualAntennaConfig
********************
Configures the Dual antenna functionallity. This function should be used only on the **ESP32-WROOM-DA** module or any other ESP32 with RF switch.
.. code-block:: arduino
bool setDualAntennaConfig(uint8_t gpio_ant1, uint8_t gpio_ant2, wifi_rx_ant_t rx_mode, wifi_tx_ant_t tx_mode);
* ``gpio_ant1`` Configure the GPIO number for the antenna 1 connected to the RF switch (default ``GPIO2`` on ESP32-WROOM-DA)
* ``gpio_ant2`` Configure the GPIO number for the antenna 2 connected to the RF switch (default ``GPIO25`` on ESP32-WROOM-DA)
* ``rx_mode`` Set the RX antenna mode. See wifi_rx_ant_t for the options.
* ``tx_mode`` Set the TX antenna mode. See wifi_tx_ant_t for the options.
Return ``true`` if the configuration was successful.
For the ``rx_mode`` you can use the following configuration:
* ``WIFI_RX_ANT0`` Selects the antenna 1 for all RX activity.
* ``WIFI_RX_ANT1`` Selects the antenna 2 for all RX activity.
* ``WIFI_RX_ANT_AUTO`` Selects the antenna for RX automatically.
For the ``tx_mode`` you can use the following configuration:
* ``WIFI_TX_ANT0`` Selects the antenna 1 for all TX activity.
* ``WIFI_TX_ANT1`` Selects the antenna 2 for all TX activity.
* ``WIFI_TX_ANT_AUTO`` Selects the antenna for TX automatically.
WiFiAP
------
The ``WiFiAP`` is used to configure and manage the Wi-Fi as an Access Point. This is where you can find the related functions for the AP.
Basic Usage
***********
To start the Wi-Fi as an Access Point.
.. code-block:: arduino
WiFi.softAP(ssid, password);
Please see the full WiFiAP example in: `ap example`_.
AP Configuration
----------------
softAP
******
Use the function ``softAP`` to configure the Wi-Fi AP characteristics:
.. code-block:: arduino
bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4, bool ftm_responder = false);
Where:
* ``ssid`` sets the Wi-Fi network SSID.
* ``passphrase`` sets the Wi-Fi network password. If the network is open, set as ``NULL``.
* ``channel`` configures the Wi-Fi channel.
* ``ssid_hidden`` sets the network as hidden.
* ``max_connection`` sets the maximum number of simultaneous connections. The default is 4.
* ``ftm_responder`` sets the Wi-Fi FTM responder feature. **Only for ESP32-S2 and ESP32-C3 SoC!**
Return ``true`` if the configuration was successful.
softAPConfig
************
Function used to configure the IP as static (fixed) as well as the gateway and subnet.
.. code-block:: arduino
bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);
Where:
* ``local_ip`` sets the local IP address.
* ``gateway`` sets the gateway IP.
* ``subnet`` sets the subnet mask.
The function will return ``true`` if the configuration is successful.
AP Connection
-------------
softAPdisconnect
****************
Function used to force the AP disconnection.
.. code-block:: arduino
bool softAPdisconnect(bool wifioff = false);
Where:
* ``wifioff`` sets the Wi-Fi off if ``true``.
The function will return ``true`` if the configuration is successful.
softAPgetStationNum
*******************
This function returns the number of clients connected to the AP.
.. code-block:: arduino
uint8_t softAPgetStationNum();
softAPIP
********
Function to get the AP IPv4 address.
.. code-block:: arduino
IPAddress softAPIP();
The function will return the AP IP address in ``IPAddress`` format.
softAPBroadcastIP
*****************
Function to get the AP IPv4 broadcast address.
.. code-block:: arduino
IPAddress softAPBroadcastIP();
The function will return the AP broadcast address in ``IPAddress`` format.
softAPNetworkID
***************
Get the softAP network ID.
.. code-block:: arduino
IPAddress softAPNetworkID();
The function will return the AP network address in ``IPAddress`` format.
softAPSubnetCIDR
****************
Get the softAP subnet CIDR.
.. code-block:: arduino
uint8_t softAPSubnetCIDR();
softAPenableIpV6
****************
Function used to enable the IPv6 support.
.. code-block:: arduino
bool softAPenableIpV6();
The function will return ``true`` if the configuration is successful.
softAPIPv6
**********
Function to get the IPv6 address.
.. code-block:: arduino
IPv6Address softAPIPv6();
The function will return the AP IPv6 address in ``IPv6Address`` format.
softAPgetHostname
*****************
Function to get the AP hostname.
.. code-block:: arduino
const char * softAPgetHostname();
softAPsetHostname
*****************
Function to set the AP hostname.
.. code-block:: arduino
bool softAPsetHostname(const char * hostname);
Where:
* ``hostname`` sets the device hostname.
The function will return ``true`` if the configuration is successful.
softAPmacAddress
****************
Function to define the AP MAC address.
.. code-block:: arduino
uint8_t* softAPmacAddress(uint8_t* mac);
Where:
* ``mac`` sets the new MAC address.
Function to get the AP MAC address.
.. code-block:: arduino
String softAPmacAddress(void);
softAPSSID
**********
Function to get the AP SSID.
.. code-block:: arduino
String softAPSSID(void) const;
Returns the AP SSID.
WiFiSTA
-------
The ``WiFiSTA`` is used to configure and manage the Wi-Fi as Station. The related functions for the STA are here.
Basic Usage
***********
The following code shows the basic usage of the WifiSTA functionality.
.. code-block:: arduino
WiFi.begin(ssid, password);
Where the ``ssid`` and ``password`` are from the network you want to connect the ESP32.
To check if the connection is successful, you can use:
.. code-block:: arduino
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
After a successful connection, you can print the IP address given by the network.
.. code-block:: arduino
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
Please see the full example of the WiFiSTA in: `sta example`_.
STA Configuration
-----------------
begin
*****
- Functions ``begin`` are used to configure and start the Wi-Fi.
.. code-block:: arduino
wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
Where:
* ``ssid`` sets the AP SSID.
* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks.
* ``channel`` sets the Wi-Fi channel.
* ``uint8_t* bssid`` sets the AP BSSID.
* ``connect`` sets ``true`` to connect to the configured network automatically.
.. code-block:: arduino
wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
Where:
* ``ssid`` sets the AP SSID.
* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks.
* ``channel`` sets the Wi-Fi channel.
* ``bssid`` sets the AP BSSID.
* ``connect`` sets ``true`` to connect to the configured network automatically.
Function to start the connection after being configured.
.. code-block:: arduino
wl_status_t begin();
config
******
Function ``config`` is used to configure Wi-Fi. After configuring, you can call function ``begin`` to start the Wi-Fi process.
.. code-block:: arduino
bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 = (uint32_t)0x00000000, IPAddress dns2 = (uint32_t)0x00000000);
Where:
* ``local_ip`` sets the local IP.
* ``gateway`` sets the gateway IP.
* ``subnet`` sets the subnet mask.
* ``dns1`` sets the DNS.
* ``dns2`` sets the DNS alternative option.
The function will return ``true`` if the configuration is successful.
The ``IPAddress`` format is defined by 4 bytes as described here:
.. code-block:: arduino
IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);
Example:
.. code-block:: arduino
IPAddress local_ip(192, 168, 10, 20);
See the ``WiFiClientStaticIP.ino`` for more details on how to use this feature.
STA Connection
--------------
reconnect
*********
Function used to reconnect the Wi-Fi connection.
.. code-block:: arduino
bool reconnect();
disconnect
**********
Function to force disconnection.
.. code-block:: arduino
bool disconnect(bool wifioff = false, bool eraseap = false);
Where:
* ``wifioff`` use ``true`` to turn the Wi-Fi radio off.
* ``eraseap`` use ``true`` to erase the AP configuration from the NVS memory.
The function will return ``true`` if the configuration is successful.
isConnected
***********
Function used to get the connection state.
.. code-block:: arduino
bool isConnected();
Return the connection state.
setAutoConnect
**************
Function is deprecated.
getAutoConnect
**************
Function is deprecated.
setAutoReconnect
****************
Function used to set the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool setAutoReconnect(bool autoReconnect);
Where:
* ``autoConnect`` is set to ``true`` to enable this option.
getAutoReconnect
****************
Function used to get the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool getAutoReconnect();
The function will return ``true`` if this setting is enabled.
setMinSecurity
**************
Function used to set the minimum security for AP to be considered connectable.
.. code-block:: arduino
bool setMinSecurity(wifi_auth_mode_t minSecurity);
Where:
* ``minSecurity`` is the minimum security for AP to be considered connectable. Default is ``WIFI_AUTH_WPA2_PSK``.
WiFiMulti
---------
The ``WiFiMulti`` allows you to add more than one option for the AP connection while running as a station.
To add the AP, use the following function. You can add multiple AP's and this library will handle the connection.
.. code-block:: arduino
bool addAP(const char* ssid, const char *passphrase = NULL);
After adding the AP's, run by the following function.
.. code-block:: arduino
uint8_t run(uint32_t connectTimeout=5000);
To see how to use the ``WiFiMulti``, take a look at the ``WiFiMulti.ino`` example available.
WiFiScan
--------
To perform the Wi-Fi scan for networks, you can use the following functions:
Start scan WiFi networks available.
.. code-block:: arduino
int16_t scanNetworks(bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0);
Called to get the scan state in Async mode.
.. code-block:: arduino
int16_t scanComplete();
Delete last scan result from RAM.
.. code-block:: arduino
void scanDelete();
Loads all infos from a scanned wifi in to the ptr parameters.
.. code-block:: arduino
bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel);
To see how to use the ``WiFiScan``, take a look at the ``WiFiScan.ino`` example available.
Examples
--------
.. _ap example:
Wi-Fi AP Example
****************
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino
:language: arduino
.. _sta example:
Wi-Fi STA Example
*****************
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino
:language: arduino
References
----------