From 6b54092a4be10eb6e26a0ea1f79a90f1f57ddf99 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 14 Feb 2022 15:55:08 +0000 Subject: [PATCH 1/8] Added the Tools Options into the docs. --- docs/source/api/i2s.rst | 566 ++++++++++++++++++++++++++++ docs/source/guides/guides.rst | 10 + docs/source/guides/tools_menu.rst | 111 ++++++ docs/source/index.rst | 1 + docs/source/tutorials/tutorials.rst | 8 +- 5 files changed, 691 insertions(+), 5 deletions(-) create mode 100644 docs/source/api/i2s.rst create mode 100644 docs/source/guides/guides.rst create mode 100644 docs/source/guides/tools_menu.rst diff --git a/docs/source/api/i2s.rst b/docs/source/api/i2s.rst new file mode 100644 index 00000000000..02539fb3f2b --- /dev/null +++ b/docs/source/api/i2s.rst @@ -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 `_. + +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 + 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(); diff --git a/docs/source/guides/guides.rst b/docs/source/guides/guides.rst new file mode 100644 index 00000000000..4aa538a7e22 --- /dev/null +++ b/docs/source/guides/guides.rst @@ -0,0 +1,10 @@ +###### +Guides +###### + +.. toctree:: + :caption: Guides: + :maxdepth: 1 + :glob: + + * diff --git a/docs/source/guides/tools_menu.rst b/docs/source/guides/tools_menu.rst new file mode 100644 index 00000000000..6d23691486e --- /dev/null +++ b/docs/source/guides/tools_menu.rst @@ -0,0 +1,111 @@ +###################### +Arduino IDE Tools Menu +###################### + +Introduction +------------ + +This guide is a walkthrough for the Arduino IDE configuration menu for the ESP32 SoC's. In this guide, you will see the most relevant configuration +to get your project optimized and working. + +Since some boards and SoC's may vary in terms of hardware configuration, be sure you know all the board characteristics that you are using, like flash memory size, SoC variant (ESP32 family), PSRAM, etc. + +.. note:: To help you identify the characteristics, you can see the boards section and the Espressif Product Selector. + +Arduino IDE +----------- + + + +Tools Menu +---------- + +To properly configure your project build and flash, some settings must be done in order to get it compiled and flashed without any issues. +Some boards are natively supported and almost no configuration is required. However, if your is not yet supported or you have a custom board, you need to configure the environment by yourself. + +Generic Options +--------------- + +Board +***** + +This option is the target board and must be selected in order to get all the default configuration settings. Once you select the correct board, you will see that some configurations will be automatically selected, but be aware that some boards can have multiple versions (i.e different flash sizes). + +To select the board, go to ``Tools -> Board -> ESP32 Arduino`` and select the target board. + +If your board is not present on this list, you can select the generic ``ESP32-XX Dev Module``. + +Currently we have one generic development module for each of the supported targets. + +Upload Speed +************ + +To select the flashing speed, change the ``Tools -> Upload Speed``. This value will be used for flashing the code to the device. + +.. note:: If you have issues while flashing the device at high speed, try to decrease this value. This could be due the external serial-to-USB chip limitations. + +CPU Frequency +************* + +On this option, you can select the CPU clock frequency. This option is critical and must be selected according to the high frequency crystal present on the board and the radio usage (Wi-Fi and Bluetooth). + +Flash Frequency +*************** + +Flash Mode +********** + +Flash Size +********** + +Partition Scheme +**************** + +Core Debug Level +**************** + +PSRAM +***** + +Arduino Runs On +*************** + +Events Run On +************* + +Port +**** + +Get Board Info +************** + +USB Options +----------- + +Some ESP32 families have the USB peripheral. This peripheral can be used also for flashing and debigging. + +Currently, the SoC's with USB supported are: + +* ESP32-C3 +* ESP32-S2 +* ESP32-S3 (in development mode, not stable yet) + +The USB option will be available only if the correct target is selected. + +USB CDC On Boot +*************** + +The USB Communications Device Class, or USB CDC, is a class used for basic communication to be used as a regular serial controller (like RS-232). + +This class is used for flashing the device without any other external device attached to the SoC. + +This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new serial port will appear in the serial ports list. +Use this new serial port for flashing the device. + +USB Firmware MSC On Boot +************************ + +The USB Mass Storage Class + +USB DFU On Boot +*************** diff --git a/docs/source/index.rst b/docs/source/index.rst index 02f62c30290..25b8e33e7e3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Here you will find all the relevant information about the project. Getting Started Libraries Tutorials + Guides Advanced Utilities FAQ Troubleshooting diff --git a/docs/source/tutorials/tutorials.rst b/docs/source/tutorials/tutorials.rst index 57eead06f31..9fca4ac3ce5 100644 --- a/docs/source/tutorials/tutorials.rst +++ b/docs/source/tutorials/tutorials.rst @@ -3,10 +3,8 @@ Tutorials ######### .. toctree:: - :maxdepth: 2 :caption: Tutorials: + :maxdepth: 1 + :glob: - Blink - Basic - DFU - GPIO Matrix and Pin Mux + * From 9b7651f9800a78a55365ab5071bd2ce5213a61c9 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 14 Feb 2022 17:07:48 +0000 Subject: [PATCH 2/8] Added more options --- docs/source/guides/tools_menu.rst | 69 ++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/docs/source/guides/tools_menu.rst b/docs/source/guides/tools_menu.rst index 6d23691486e..f49c82a4bd4 100644 --- a/docs/source/guides/tools_menu.rst +++ b/docs/source/guides/tools_menu.rst @@ -15,8 +15,6 @@ Since some boards and SoC's may vary in terms of hardware configuration, be sure Arduino IDE ----------- - - Tools Menu ---------- @@ -37,6 +35,10 @@ If your board is not present on this list, you can select the generic ``ESP32-XX Currently we have one generic development module for each of the supported targets. +If the board selected belongs to another SoC family, you will see the following information at the build output: + + ``A fatal error occurred: This chip is ESP32 not ESP32-S2. Wrong --chip argument?`` + Upload Speed ************ @@ -52,32 +54,80 @@ On this option, you can select the CPU clock frequency. This option is critical Flash Frequency *************** +Use this function to select the flash memory frequency. + +* **40MHz** +* **80MHz** + Flash Mode ********** +This option is used to select the SPI mode for the flash memory. + +* **QIO** - Quad I/O Fast Read + * Four SPI pins are used to write the flash address part of the command, and to read flash data out. + +* **DIO** - Dual I/O Fast Read + * Two SPI pins are used to write the flash address part of the command, and to read flash data out. + +* **QOUT** - Quad Output Fast Read + * Four SPI pins are used to read the flash data out. + +* **DOUT** - Dual Output Fast Read + * Two SPI pins are used to read flash data out. + +If don't know how the board flash is phisically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. + Flash Size ********** +This option is used to select the flash size. + +* **2MB** (16Mb) +* **4MB** (32Mb) +* **8MB** (64Mb) +* **16MB** (128Mb) + Partition Scheme **************** +This option is used to select the partition model according to the flash size and the resources needed, like storage area and OTA (Over The Air updates). + +.. note:: Be carefull selecting the right partition according to the flash size. + Core Debug Level **************** +This option is used to select the Arduino core debugging level to be printed to the serial debug. + +* **None** - Prints nothing. +* **Error** - Onle at error level. +* **Warning** - Only at warning level and above. +* **Info** - Only at info level and above. +* **Debug** - Only at debug level and above. +* **Verbose** - Prints everything. + PSRAM ***** +The PSRAM is an internal or external extended RAM. + +This option can be used to ``Enable`` or ``Disable`` the PSRAM. + Arduino Runs On *************** +This function is used to selecte the core that runs the Arduino core. This is only valid if the target SoC has 2 cores. + Events Run On ************* +This function is used to selecte the core that runs the events. This is only valid if the target SoC has 2 cores. + Port **** -Get Board Info -************** +This option is used to select the serial port to be used on the flashing and monitor. USB Options ----------- @@ -102,10 +152,19 @@ This class is used for flashing the device without any other external device att This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new serial port will appear in the serial ports list. Use this new serial port for flashing the device. +This option can be used as well for debigging via the ``Serial Monitor``. + USB Firmware MSC On Boot ************************ -The USB Mass Storage Class +The USB Mass Storage Class, or USB MSC, is a class used for storage devices, like a USB flash drive. + +This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new storage device will appear in the system as a storage drive. +Use this new storage drive to write or read files, or to drop a new firmware binary to flash the device. USB DFU On Boot *************** + +The USB Device Firmware Upgrade is a class used for flashing the device throught USB. + +This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, the device will appear as a USB DFU capable device. From 274e343bb77f9ee53bf313a277659ed7841efddd Mon Sep 17 00:00:00 2001 From: Pedro Minatel Date: Mon, 14 Feb 2022 17:11:31 +0000 Subject: [PATCH 3/8] Deleted wrong file. --- docs/source/api/i2s.rst | 566 ---------------------------------------- 1 file changed, 566 deletions(-) delete mode 100644 docs/source/api/i2s.rst diff --git a/docs/source/api/i2s.rst b/docs/source/api/i2s.rst deleted file mode 100644 index 02539fb3f2b..00000000000 --- a/docs/source/api/i2s.rst +++ /dev/null @@ -1,566 +0,0 @@ -### -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 `_. - -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 - 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(); From 6ac34b161c21b4f513f83b3421e5ed0e31dab399 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 15 Feb 2022 09:50:13 +0000 Subject: [PATCH 4/8] [Docs] Added image to show the MSC and some grammar fixes --- docs/source/_static/usb_msc_drive.png | Bin 0 -> 75704 bytes docs/source/guides/tools_menu.rst | 51 +++++++++++++++++--------- 2 files changed, 34 insertions(+), 17 deletions(-) create mode 100644 docs/source/_static/usb_msc_drive.png diff --git a/docs/source/_static/usb_msc_drive.png b/docs/source/_static/usb_msc_drive.png new file mode 100644 index 0000000000000000000000000000000000000000..de0796c39805134b0f97ba2876d419209ac4267c GIT binary patch literal 75704 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

asN#YH`B)bE2~ogqIIs22|@$ktL)x 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 Board -> ESP32 Arduino`` and select the ta If your board is not present on this list, you can select the generic ``ESP32-XX Dev Module``. -Currently we have one generic development module for each of the supported targets. +Currently, we have one generic development module for each of the supported targets. If the board selected belongs to another SoC family, you will see the following information at the build output: @@ -44,12 +50,14 @@ Upload Speed To select the flashing speed, change the ``Tools -> Upload Speed``. This value will be used for flashing the code to the device. -.. note:: If you have issues while flashing the device at high speed, try to decrease this value. This could be due the external serial-to-USB chip limitations. +.. note:: If you have issues while flashing the device at high speed, try to decrease this value. This could be due to the external serial-to-USB chip limitations. CPU Frequency ************* -On this option, you can select the CPU clock frequency. This option is critical and must be selected according to the high frequency crystal present on the board and the radio usage (Wi-Fi and Bluetooth). +On this option, you can select the CPU clock frequency. This option is critical and must be selected according to the high-frequency crystal present on the board and the radio usage (Wi-Fi and Bluetooth). + +If you don't know why you shuld change this frequency, leave the default option. Flash Frequency *************** @@ -65,10 +73,10 @@ Flash Mode This option is used to select the SPI mode for the flash memory. * **QIO** - Quad I/O Fast Read - * Four SPI pins are used to write the flash address part of the command, and to read flash data out. + * Four SPI pins are used to write the flash address part of the command and to read flash data out. * **DIO** - Dual I/O Fast Read - * Two SPI pins are used to write the flash address part of the command, and to read flash data out. + * Two SPI pins are used to write the flash address part of the command and to read flash data out. * **QOUT** - Quad Output Fast Read * Four SPI pins are used to read the flash data out. @@ -76,7 +84,7 @@ This option is used to select the SPI mode for the flash memory. * **DOUT** - Dual Output Fast Read * Two SPI pins are used to read flash data out. -If don't know how the board flash is phisically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. +If you don't know how the board flash is physically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. Flash Size ********** @@ -93,7 +101,7 @@ Partition Scheme This option is used to select the partition model according to the flash size and the resources needed, like storage area and OTA (Over The Air updates). -.. note:: Be carefull selecting the right partition according to the flash size. +.. note:: Be careful selecting the right partition according to the flash size. Core Debug Level **************** @@ -110,19 +118,19 @@ This option is used to select the Arduino core debugging level to be printed to PSRAM ***** -The PSRAM is an internal or external extended RAM. +The PSRAM is an internal or external extended RAM present on some boards, modules or SoC.. This option can be used to ``Enable`` or ``Disable`` the PSRAM. Arduino Runs On *************** -This function is used to selecte the core that runs the Arduino core. This is only valid if the target SoC has 2 cores. +This function is used to select the core that runs the Arduino core. This is only valid if the target SoC has 2 cores. Events Run On ************* -This function is used to selecte the core that runs the events. This is only valid if the target SoC has 2 cores. +This function is used to select the core that runs the events. This is only valid if the target SoC has 2 cores. Port **** @@ -132,11 +140,11 @@ This option is used to select the serial port to be used on the flashing and mon USB Options ----------- -Some ESP32 families have the USB peripheral. This peripheral can be used also for flashing and debigging. +Some ESP32 families have a USB peripheral. This peripheral can be used for flashing and debugging. Currently, the SoC's with USB supported are: -* ESP32-C3 +* ESP32-C3 (CDC only) * ESP32-S2 * ESP32-S3 (in development mode, not stable yet) @@ -149,10 +157,10 @@ The USB Communications Device Class, or USB CDC, is a class used for basic commu This class is used for flashing the device without any other external device attached to the SoC. -This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new serial port will appear in the serial ports list. +This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new serial port will appear in the list of the serial ports. Use this new serial port for flashing the device. -This option can be used as well for debigging via the ``Serial Monitor``. +This option can be used as well for debugging via the ``Serial Monitor``. USB Firmware MSC On Boot ************************ @@ -162,9 +170,18 @@ The USB Mass Storage Class, or USB MSC, is a class used for storage devices, lik This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new storage device will appear in the system as a storage drive. Use this new storage drive to write or read files, or to drop a new firmware binary to flash the device. +.. figure:: ../_static/usb_msc_drive.png + :align: center + :width: 720 + :figclass: align-center + USB DFU On Boot *************** -The USB Device Firmware Upgrade is a class used for flashing the device throught USB. +The USB Device Firmware Upgrade is a class used for flashing the device through USB. This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, the device will appear as a USB DFU capable device. + + +.. _Espressif Product Selector: https://products.espressif.com/ +.. _boards.txt: https://github.com/espressif/arduino-esp32/blob/master/boards.txt \ No newline at end of file From 70a71330f4b21d35c06bd323a94ea56a1c18a38c Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 15 Feb 2022 12:03:43 +0000 Subject: [PATCH 5/8] [Docs] Added more information about the core selection --- docs/source/guides/tools_menu.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/source/guides/tools_menu.rst b/docs/source/guides/tools_menu.rst index 08cd85b8c9a..7693e222400 100644 --- a/docs/source/guides/tools_menu.rst +++ b/docs/source/guides/tools_menu.rst @@ -57,51 +57,61 @@ CPU Frequency On this option, you can select the CPU clock frequency. This option is critical and must be selected according to the high-frequency crystal present on the board and the radio usage (Wi-Fi and Bluetooth). +In some application, reducing the CPU clock frequency is recommended in order to reduce the power consumption. + If you don't know why you shuld change this frequency, leave the default option. Flash Frequency *************** -Use this function to select the flash memory frequency. +Use this function to select the flash memory frequency. The frequency will be dependant of the memory model. * **40MHz** * **80MHz** +If you don't know if your memory supports **80Mhz**, you can try to upload you scketch and watch the log output via the serial monitor. + Flash Mode ********** -This option is used to select the SPI mode for the flash memory. +This option is used to select the SPI communication mode with the flash memory. + +Depending on the application, this mode can be changed in order to increase the flash communication speed. * **QIO** - Quad I/O Fast Read - * Four SPI pins are used to write the flash address part of the command and to read flash data out. + * Four SPI pins are used to write to the flash and to read from flash. * **DIO** - Dual I/O Fast Read - * Two SPI pins are used to write the flash address part of the command and to read flash data out. + * Two SPI pins are used to write to the flash and to read from flash. * **QOUT** - Quad Output Fast Read - * Four SPI pins are used to read the flash data out. + * Four SPI pins are used to read the flash data. * **DOUT** - Dual Output Fast Read - * Two SPI pins are used to read flash data out. + * Two SPI pins are used to read flash data. If you don't know how the board flash is physically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. Flash Size ********** -This option is used to select the flash size. +This option is used to select the flash size. The flash size should be selected according to the flash model used on your board. * **2MB** (16Mb) * **4MB** (32Mb) * **8MB** (64Mb) * **16MB** (128Mb) +If you choose the wrong size, you may have issues when selecting the partition scheme. + + + Partition Scheme **************** This option is used to select the partition model according to the flash size and the resources needed, like storage area and OTA (Over The Air updates). -.. note:: Be careful selecting the right partition according to the flash size. +.. note:: Be careful selecting the right partition according to the flash size. If you select the wrong partition, the system will crash. Core Debug Level **************** @@ -127,11 +137,15 @@ Arduino Runs On This function is used to select the core that runs the Arduino core. This is only valid if the target SoC has 2 cores. +When you have some heavy task running, you might want to run this task on a different core then the Arduino tasks. For this reason, you have this configuration to select the core. + Events Run On ************* This function is used to select the core that runs the events. This is only valid if the target SoC has 2 cores. +The same situation on the previous configuration. + Port **** From 51697314ccd98bd9923e7103e17d17d9cc42ac12 Mon Sep 17 00:00:00 2001 From: Pedro Minatel Date: Mon, 14 Feb 2022 17:11:31 +0000 Subject: [PATCH 6/8] Deleted wrong file. --- docs/source/api/i2s.rst | 566 ---------------------------------------- 1 file changed, 566 deletions(-) delete mode 100644 docs/source/api/i2s.rst diff --git a/docs/source/api/i2s.rst b/docs/source/api/i2s.rst deleted file mode 100644 index 02539fb3f2b..00000000000 --- a/docs/source/api/i2s.rst +++ /dev/null @@ -1,566 +0,0 @@ -### -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 `_. - -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 - 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(); From fa0d731445b1a1dec6db29ec7b9d62c4b062f6bc Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 15 Feb 2022 12:03:43 +0000 Subject: [PATCH 7/8] [Docs] Added more information about the core selection --- docs/source/guides/tools_menu.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/source/guides/tools_menu.rst b/docs/source/guides/tools_menu.rst index 08cd85b8c9a..7693e222400 100644 --- a/docs/source/guides/tools_menu.rst +++ b/docs/source/guides/tools_menu.rst @@ -57,51 +57,61 @@ CPU Frequency On this option, you can select the CPU clock frequency. This option is critical and must be selected according to the high-frequency crystal present on the board and the radio usage (Wi-Fi and Bluetooth). +In some application, reducing the CPU clock frequency is recommended in order to reduce the power consumption. + If you don't know why you shuld change this frequency, leave the default option. Flash Frequency *************** -Use this function to select the flash memory frequency. +Use this function to select the flash memory frequency. The frequency will be dependant of the memory model. * **40MHz** * **80MHz** +If you don't know if your memory supports **80Mhz**, you can try to upload you scketch and watch the log output via the serial monitor. + Flash Mode ********** -This option is used to select the SPI mode for the flash memory. +This option is used to select the SPI communication mode with the flash memory. + +Depending on the application, this mode can be changed in order to increase the flash communication speed. * **QIO** - Quad I/O Fast Read - * Four SPI pins are used to write the flash address part of the command and to read flash data out. + * Four SPI pins are used to write to the flash and to read from flash. * **DIO** - Dual I/O Fast Read - * Two SPI pins are used to write the flash address part of the command and to read flash data out. + * Two SPI pins are used to write to the flash and to read from flash. * **QOUT** - Quad Output Fast Read - * Four SPI pins are used to read the flash data out. + * Four SPI pins are used to read the flash data. * **DOUT** - Dual Output Fast Read - * Two SPI pins are used to read flash data out. + * Two SPI pins are used to read flash data. If you don't know how the board flash is physically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. Flash Size ********** -This option is used to select the flash size. +This option is used to select the flash size. The flash size should be selected according to the flash model used on your board. * **2MB** (16Mb) * **4MB** (32Mb) * **8MB** (64Mb) * **16MB** (128Mb) +If you choose the wrong size, you may have issues when selecting the partition scheme. + + + Partition Scheme **************** This option is used to select the partition model according to the flash size and the resources needed, like storage area and OTA (Over The Air updates). -.. note:: Be careful selecting the right partition according to the flash size. +.. note:: Be careful selecting the right partition according to the flash size. If you select the wrong partition, the system will crash. Core Debug Level **************** @@ -127,11 +137,15 @@ Arduino Runs On This function is used to select the core that runs the Arduino core. This is only valid if the target SoC has 2 cores. +When you have some heavy task running, you might want to run this task on a different core then the Arduino tasks. For this reason, you have this configuration to select the core. + Events Run On ************* This function is used to select the core that runs the events. This is only valid if the target SoC has 2 cores. +The same situation on the previous configuration. + Port **** From 8acd614b549f95503e217d0881c68d40fbbf0a82 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Wed, 16 Feb 2022 12:51:14 +0000 Subject: [PATCH 8/8] [Docs] Changes according to the PR review --- docs/source/getting_started.rst | 3 +++ docs/source/guides/tools_menu.rst | 22 ++++++++++------------ docs/source/index.rst | 2 +- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 66c917283ad..94442e705dc 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -26,6 +26,9 @@ power consumption. The ESP32 series is available as a chip or module. + +.. _supported_socs: + Supported SoC's --------------- diff --git a/docs/source/guides/tools_menu.rst b/docs/source/guides/tools_menu.rst index 7693e222400..65b96395730 100644 --- a/docs/source/guides/tools_menu.rst +++ b/docs/source/guides/tools_menu.rst @@ -59,17 +59,17 @@ On this option, you can select the CPU clock frequency. This option is critical In some application, reducing the CPU clock frequency is recommended in order to reduce the power consumption. -If you don't know why you shuld change this frequency, leave the default option. +If you don't know why you should change this frequency, leave the default option. Flash Frequency *************** -Use this function to select the flash memory frequency. The frequency will be dependant of the memory model. +Use this function to select the flash memory frequency. The frequency will be dependent of the memory model. * **40MHz** * **80MHz** -If you don't know if your memory supports **80Mhz**, you can try to upload you scketch and watch the log output via the serial monitor. +If you don't know if your memory supports **80Mhz**, you can try to upload you scketch using the **80MHz** option and watch the log output via the serial monitor. Flash Mode ********** @@ -90,7 +90,7 @@ Depending on the application, this mode can be changed in order to increase the * **DOUT** - Dual Output Fast Read * Two SPI pins are used to read flash data. -If you don't know how the board flash is physically connected or the flash memory model, try the **QIO/QOUT** first and then **DIO/DOUT**. +If you don't know how the board flash is physically connected or the flash memory model, try the **QIO** at **80MHz** first. Flash Size ********** @@ -119,7 +119,7 @@ Core Debug Level This option is used to select the Arduino core debugging level to be printed to the serial debug. * **None** - Prints nothing. -* **Error** - Onle at error level. +* **Error** - Only at error level. * **Warning** - Only at warning level and above. * **Info** - Only at info level and above. * **Debug** - Only at debug level and above. @@ -128,7 +128,7 @@ This option is used to select the Arduino core debugging level to be printed to PSRAM ***** -The PSRAM is an internal or external extended RAM present on some boards, modules or SoC.. +The PSRAM is an internal or external extended RAM present on some boards, modules or SoC. This option can be used to ``Enable`` or ``Disable`` the PSRAM. @@ -156,11 +156,7 @@ USB Options Some ESP32 families have a USB peripheral. This peripheral can be used for flashing and debugging. -Currently, the SoC's with USB supported are: - -* ESP32-C3 (CDC only) -* ESP32-S2 -* ESP32-S3 (in development mode, not stable yet) +To see the supported list for each SoC, see this section: `Libraries <../libraries.html>`_. The USB option will be available only if the correct target is selected. @@ -174,7 +170,9 @@ This class is used for flashing the device without any other external device att This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new serial port will appear in the list of the serial ports. Use this new serial port for flashing the device. -This option can be used as well for debugging via the ``Serial Monitor``. +This option can be used as well for debugging via the ``Serial Monitor`` using **CDC** instead of the **UART0**. + +To use the UART as serial output, you can use ``Serial0.print("Hello World!");`` instead of ``Serial.print("Hello World!");`` which will be printed using USB CDC. USB Firmware MSC On Boot ************************ diff --git a/docs/source/index.rst b/docs/source/index.rst index 25b8e33e7e3..48f30396270 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,8 +13,8 @@ Here you will find all the relevant information about the project. Getting Started Libraries - Tutorials Guides + Tutorials Advanced Utilities FAQ Troubleshooting