espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2026-05-05 12:25:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

Moved files into separate folders per 'en' and 'zh_CN' language version and linked 'zh_CN' files back to 'en' files if translation is not yet available

Browse Source
This commit is contained in:
krzychb
2018-02-03 22:12:13 +01:00
parent c8d8cdbf38
commit 097adc3a33
267 changed files with 754 additions and 481 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/get-started/add-idf_path-to-profile.rst
+64
View File
@@ -0,0 +1,64 @@
Add IDF_PATH to User Profile
============================
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
.. _add-idf_path-to-profile-windows:
Windows
-------
The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
#. Add the ``export`` command to the script file, e.g.::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
Remember to replace back-slashes with forward-slashes in the original Windows path.
#. Save the script file.
#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
printenv IDF_PATH
The path previusly entered in the script file should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
.. _add-idf_path-to-profile-linux-macos:
Linux and MacOS
---------------
Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
export IDF_PATH=~/esp/esp-idf
Log off and log in back to make this change effective.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
Run the following command to check if ``IDF_PATH`` is set::
printenv IDF_PATH
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
export IDF_PATH=~/esp/esp-idf
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
docs/en/get-started/eclipse-setup-windows.rst
+78
View File
@@ -0,0 +1,78 @@
**********************
Eclipse IDE on Windows
**********************
Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.
(For OS X and Linux instructions, see the :doc:`Eclipse IDE page <eclipse-setup>`.)
Installing Eclipse IDE
======================
Follow the steps under :ref:`Installing Eclipse IDE <eclipse-install-steps>` for all platforms.
.. _eclipse-windows-setup:
Setting up Eclipse on Windows
=============================
Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" uncheck "Show only available toolchains that support this platform".
* On the extended list that appears, choose "Cygwin GCC". Then click Finish.
*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.*
Project Properties
------------------
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
* Click on the "C/C++ Build" properties page (top-level):
* Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py``.
* Click on the "Environment" properties page under "C/C++ Build":
* Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/MyUser/Development/esp-idf*.
* Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match).
* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page:
* Click the "Providers" tab
* In the list of providers, click "CDT GCC Built-in Compiler Settings Cygwin". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern, and wrap remaining part with brackets. This means the full Compiler command pattern should be ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``
Building in Eclipse
-------------------
Continue from :ref:`Building in Eclipse <eclipse-build-project>` for all platforms.
Technical Details
=================
**Of interest to Windows gurus or very curious parties, only.**
Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support:
* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility.
* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse.
docs/en/get-started/eclipse-setup.rst
+109
View File
@@ -0,0 +1,109 @@
********************************
Build and Flash with Eclipse IDE
********************************
.. _eclipse-install-steps:
Installing Eclipse IDE
======================
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
* Download the Eclipse Installer for your platform from eclipse.org_.
* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
Windows Users
=============
Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
Setting up Eclipse
==================
Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
Project Properties
------------------
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed.
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain that will installed as part of IDF setup (``something/xtensa-esp32-elf/bin``) if this is not already listed on the PATH.
* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
* Click the "Providers" tab
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``
.. _eclipse-build-project:
Building in Eclipse
-------------------
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
* Click OK to close the Properties dialog in Eclipse.
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
* Back in Eclipse, choose Project -> Build to build your project.
**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
Flash from Eclipse
------------------
You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
* Select Build Targets -> Create... from the context menu.
* Type "flash" as the target name. Leave the other options as their defaults.
* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
Related Documents
-----------------
.. toctree::
:maxdepth: 1
eclipse-setup-windows
.. _eclipse.org: https://www.eclipse.org/
docs/en/get-started/establish-serial-connection.rst
+129
View File
@@ -0,0 +1,129 @@
Establish Serial Connection with ESP32
======================================
This section provides guidance how to establish serial connection between ESP32 and PC.
Connect ESP32 to PC
--------------------
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
Below are the links to drivers for ESP32 boards produced by Espressif:
* ESP32-PICO-KIT and ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* ESP32-WROVER-KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/D2XX.htm>`_
Above drivers are primarily for reference. They should already be bundled with the operating system and installed automatically once one of listed boards is connected to the PC.
Check port on Windows
---------------------
Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again.
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
.. figure:: ../_static/esp32-devkitc-in-device-manager.png
:align: center
:alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager
:figclass: align-center
USB to UART bridge of ESP32-DevKitC in Windows Device Manager
.. figure:: ../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
:figclass: align-center
Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
Check port on Linux and MacOS
-----------------------------
To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
Linux ::
ls /dev/tty*
MacOS ::
ls /dev/cu.*
.. _linux-dialout-group:
Adding user to ``dialout`` on Linux
-----------------------------------
The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command::
sudo usermod -a -G dialout $USER
Make sure you re-login to enable read and write permissions for the serial port.
Verify serial connection
------------------------
Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client <http://www.putty.org/>`_ that is avilable for both Windows and Linux. You can use other serial program and set communication parameters like below.
Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
.. figure:: ../_static/putty-settings-windows.png
:align: center
:alt: Setting Serial Communication in PuTTY on Windows
:figclass: align-center
Setting Serial Communication in PuTTY on Windows
.. figure:: ../_static/putty-settings-linux.png
:align: center
:alt: Setting Serial Communication in PuTTY on Linux
:figclass: align-center
Setting Serial Communication in PuTTY on Linux
Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below.
.. highlight:: none
::
ets Jun 8 2016 00:22:57
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0008,len:8
load:0x3fff0010,len:3464
load:0x40078000,len:7828
load:0x40080000,len:252
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...
If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
.. note::
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
.. note::
Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
docs/en/get-started/get-started-devkitc-v2.rst
+79
View File
@@ -0,0 +1,79 @@
ESP32-DevKitC V2 Getting Started Guide
======================================
This user guide shows how to get started with ESP32-DevKitC development board.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-DevKitC is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC board.
ESP-WROOM-32
Standard `ESP-WROOM-32 <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ module soldered to the ESP32-DevKitC board.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP-WROOM-32.
I/O
Most of the pins on the ESP-WROOM-32 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
.. _get-started-esp32-devkitc-v2-board-front:
.. figure:: ../_static/esp32-devkitc-v2-functional-overview.png
:align: center
:alt: ESP32-DevKitC V2 board layout
:figclass: align-center
ESP32-DevKitC V2 board layout
Power Supply Options
--------------------
There following options are available to provide power supply to this board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
------------------------------
Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Related Documents
-----------------
* `ESP32-DevKitC schematic <https://dl.espressif.com/dl/schematics/ESP32-Core-Board-V2_sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
docs/en/get-started/get-started-devkitc.rst
+113
View File
@@ -0,0 +1,113 @@
ESP32-DevKitC V4 Getting Started Guide
======================================
This user guide shows how to get started with ESP32-DevKitC V4 development board. For description of other versions of the ESP32-DevKitC check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
The board comes in two versions, either with :ref:`esp-modules-and-boards-esp-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module soldered.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC V4 board.
ESP-WROOM-32
:ref:`esp-modules-and-boards-esp-wroom-32` module soldered to the ESP32-DevKitC V4 board.
ESP32-WROVER
Optionally :ref:`esp-modules-and-boards-esp32-wrover` module may be soldered instead of the ESP-WROOM-32.
USB-UART Bridge
A single chip USB-UART bridge provides up to 3 Mbps transfers rates.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and the ESP module.
5V Power On LED
This LED lights when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
EN
Reset button: pressing this button resets the system.
I/O
Most of the pins on the ESP module are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
.. note::
Some of broken out pins are used internally be the ESP32 module to communicate with SPI memory. They are grouped on one side of the board besides the USB connector and labeled D0, D1, D2, D3, CMD and CLK. In general these pins should be left unconnected or access to the SPI flash memory / SPI RAM may be disturbed.
.. note::
GPIO16 and 17 are used internally by the ESP32-WROVER module. They are broken out and avialable for use only for boards that have the ESP-WROOM-32 module installed.
.. _get-started-esp32-devkitc-board-front:
.. figure:: ../_static/esp32-devkitc-functional-overview.jpg
:align: center
:alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
:figclass: align-center
ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
Power Supply Options
--------------------
There following options are available to provide power supply to this board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
------------------------------
Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Board Dimensions
----------------
.. figure:: ../_static/esp32-devkitc-dimensions-back.jpg
:align: center
:alt: ESP32 DevKitC board dimensions - back
:figclass: align-center
ESP32 DevKitC board dimensions - back
Related Documents
-----------------
* `ESP32-DevKitC V4 schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
.. toctree::
:hidden:
get-started-devkitc-v2
docs/en/get-started/get-started-pico-kit-v3.rst
+66
View File
@@ -0,0 +1,66 @@
ESP32-PICO-KIT V3 Getting Started Guide
=======================================
This user guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × ESP32-PICO-KIT V3 mini development board
* 1 × USB A / Micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-PICO-KIT V3 is a mini development board based on the ESP32-PICO-D4 SIP module produced by `Espressif <https://espressif.com>`_. All the IO signals and system power on ESP32-PICO-D4 are led out through two standard 20 pin x 0.1" pitch headers on both sides for easy interfacing. The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the development board to a PC's USB port for downloads and debugging.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V3 board.
ESP32-PICO-D4
Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V3 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
USB-UART Bridge
A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
I/O
All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V3.
EN Button
Reset button; pressing this button resets the system.
BOOT Button
Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
.. figure:: ../_static/esp32-pico-kit-v3-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V3 board layout
:figclass: align-center
ESP32-PICO-KIT V3 board layout
Start Application Development
------------------------------
Before powering up the ESP32-PICO-KIT V3, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Related Documents
-----------------
* `ESP32-PICO-KIT V3 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v3_schematic.pdf>`_ (PDF)
* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
* :doc:`../hw-reference/index`
docs/en/get-started/get-started-pico-kit.rst
+211
View File
@@ -0,0 +1,211 @@
ESP32-PICO-KIT V4 Getting Started Guide
=======================================
This user guide shows how to get started with the ESP32-PICO-KIT V4 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × :ref:`ESP32-PICO-KIT V4 mini development board <get-started-pico-kit-v4-board-front>`
* 1 × USB A / Micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
If you like to start using this board right now, go directly to section `Start Application Development`_.
Overview
--------
ESP32-PICO-KIT V4 is a mini development board produced by `Espressif <https://espressif.com>`_. At the core of this board is the ESP32-PICO-D4, a System-in-Package (SIP) module with complete Wi-Fi and Bluetooth functionalities. Comparing to other ESP32 chips, the ESP32-PICO-D4 integrates several peripheral components in one single package, that otherwise would need to be installed separately. This includes a 40 MHz crystal oscillator, 4 MB flash, filter capacitors and RF matching links in. This greatly reduces quantity and costs of additional components, subsequent assembly and testing cost, as well as overall product complexity.
The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the board to a PC's USB port for downloads and debugging.
For easy interfacing, all the IO signals and system power on ESP32-PICO-D4 are led out through two rows of 20 x 0.1" pitch header pads on both sides of the development board. To make the ESP32-PICO-KIT V4 fit into mini breadboards, the header pads are populated with two rows of 17 pin headers. Remaining 2 x 3 pads grouped on each side of the board besides the antenna are not populated. The remaining 2 x 3 pin headers may be soldered later by the user.
.. note::
The 2 x 3 pads not populated with pin headers are internally connected to the flash memory embedded in the ESP32-PICO-D4 SIP module. For more details see module's datasheet in `Related Documents`_.
The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see section `Board Dimensions`_. An overview functional block diagram is shown below.
.. figure:: ../_static/esp32-pico-kit-v4-functional-block-diagram.png
:align: center
:alt: ESP32-PICO-KIT V4 functional block diagram
:figclass: align-center
ESP32-PICO-KIT V4 functional block diagram
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V4 board.
ESP32-PICO-D4
Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V4 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
LDO
5V-to-3.3V Low dropout voltage regulator (LDO).
USB-UART Bridge
A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V4.
5V Power On LED
This light emitting diode lits when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
I/O
All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details please see section `Pin Descriptions`_.
BOOT Button
Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
EN Button
Reset button; pressing this button resets the system.
.. _get-started-pico-kit-v4-board-front:
.. figure:: ../_static/esp32-pico-kit-v4-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V4 board layout
:figclass: align-center
ESP32-PICO-KIT V4 board layout
Power Supply Options
--------------------
There following options are available to provide power supply to the ESP32-PICO-KIT V4:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
-----------------------------
Before powering up the ESP32-PICO-KIT V4, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Pin Descriptions
----------------
The two tables below provide the **Name** and **Function** of I/O headers on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front`. The pin numbering and header names are the same as on a schematic in `Related Documents`_.
Header J2
"""""""""
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2CTS
2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2RTS
3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U1CTS
4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN
5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1
6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0
7 IO23 I/O | GPIO23, VSPID, HS1_STROBE
8 IO18 I/O | GPIO18, VSPICLK, HS1_DATA7
9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD
11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD
12 RXD0 I/O | GPIO3, U0RXD :ref:`(4) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT2
13 TXD0 I/O | GPIO1, U0TXD :ref:`(4) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT3, EMAC_RXD2
14 IO35 I | ADC1_CH7, RTC_GPIO5
15 IO34 I | ADC1_CH6, RTC_GPIO4
16 IO38 I | GPIO38, ADC1_CH2, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO2
17 IO37 I | GPIO37, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH1, RTC_GPIO1
18 EN I | CHIP_PU
19 GND P | Ground
20 VDD33 (3V3) P | 3.3V power supply
====== ================= ====== ======================================================
Header J3
"""""""""
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2RXD, EMAC_CLK_OUT
2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2TXD, EMAC_CLK_OUT_180
3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U1RTS
4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO0
5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO3
6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
8 IO32 I/O | 32K_XP :ref:`(3a) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH4, TOUCH9, RTC_GPIO9
9 IO33 I/O | 32K_XN :ref:`(3b) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH5, TOUCH8, RTC_GPIO8
10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17
| EMAC_RX_DV
11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,
| HS2_CLK, SD_CLK, EMAC_TXD2
12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(5) <get-started-pico-kit-v4-pin-notes>` , HSPIQ,
| HS2_DATA2, SD_DATA2, EMAC_TXD3
13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,
| HS2_DATA3, SD_DATA3, EMAC_RX_ER
14 IO15 I/O | ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0
| HS2_CMD, SD_CMD, EMAC_RXD3
15 IO2 I/O | ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,
| HS2_DATA0, SD_DATA0
16 IO4 I/O | ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,
| HS2_DATA1, SD_DATA1, EMAC_TX_ER
17 IO0 I/O | ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1
| EMAC_TX_CLK
18 VDD33 (3V3) P | 3.3V power supply
19 GND P | Ground
20 EXT_5V (5V) P | 5V power supply
====== ================= ====== ======================================================
.. _get-started-pico-kit-v4-pin-notes:
**Notes to** `Pin Descriptions`_
1. This pin is connected to the flash pin of ESP32-PICO-D4.
2. When used as ADC_PRE_AMP, connect 270 pF capacitors between: (a) SENSOR_VP and IO37, (b) SENSOR_VN and IO38.
3. 32.768 kHz crystal oscillator: (a) input, (b) output.
4. This pin is connected to the pin of the USB bridge chip on the board.
5. The operating voltage of ESP32-PICO-KIT’s embedded SPI flash is 3.3V. Therefore, the strapping pin MTDI should hold bit ”0” during the module power-on reset.
Board Dimensions
----------------
.. figure:: ../_static/esp32-pico-kit-v4-dimensions-back.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - back
:figclass: align-center
ESP32-PICO-KIT V4 dimensions - back
.. figure:: ../_static/esp32-pico-kit-v4-dimensions-side.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - side
:figclass: align-center
ESP32-PICO-KIT V4 dimensions - side
Related Documents
-----------------
* `ESP32-PICO-KIT V4 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v4_schematic.pdf>`_ (PDF)
* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
* :doc:`../hw-reference/index`
.. toctree::
:hidden:
get-started-pico-kit-v3
docs/en/get-started/get-started-wrover-kit-v2.rst
+191
View File
@@ -0,0 +1,191 @@
ESP-WROVER-KIT V2 Getting Started Guide
=======================================
This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-v2-start-development`.
What You Need
-------------
* 1 × ESP-WROVER-KIT V2 board
* 1 x Micro USB 2.0 Cable, Type A to Micro B
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
^^^^^^^^
The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
.. note::
ESP-WROVER-KIT V2 integrates the ESP-WROOM-32 module by default.
Functionality Overview
^^^^^^^^^^^^^^^^^^^^^^
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
ESP-WROVER-KIT block diagram
Functional Description
^^^^^^^^^^^^^^^^^^^^^^
The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
32.768 kHz
An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
ESP32 Module
ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
.. note::
GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
CTS/RTS
Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
UART
Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
SPI
SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. If an ESP32-WROVER is being used, please note that the electrical level on the flash and SRAM is 1.8V.
JTAG
JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
FT2232
FT2232 chip is a multi-protocol USB-to-serial bridge. The FT2232 chip features USB-to-UART and USB-to-JTAG functionalities. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32.
The embedded FT2232 chip is one of the distinguishing features of the ESP-WROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, uses do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V2 schematic`_.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
Power Select
Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`esp-wrover-kit-v2-setup-options`, jumper header JP7.
Power Key
Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
5V Input
The 5V power supply interface is used as a backup power supply in case of full-load operation.
LDO
NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V2 schematic`_.
Camera
Camera interface: a standard OV7670 camera module is supported.
RGB
Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
I/O
All the pins on the ESP32 module are led out to the pin headers on the ESPWROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro SD Card
Micro SD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the Micro SD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in section :ref:`esp-wrover-kit-v2-setup-options`.
LCD
ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-kit-v2-board-back`.
.. figure:: ../_static/esp-wrover-kit-v2-layout-front.png
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
ESP-WROVER-KIT board layout - front
.. _esp-wrover-kit-v2-board-back:
.. figure:: ../_static/esp-wrover-kit-v2-layout-back.png
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
ESP-WROVER-KIT board layout - back
.. _esp-wrover-kit-v2-setup-options:
Setup Options
^^^^^^^^^^^^^
There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+--------+----------------------+-------------------------------------------------+
| Header | Jumper Setting | Description of Functionality |
+--------+----------------------+-------------------------------------------------+
| JP1 | |jp1-sd_io2| | Enable pull up for the Micro SD Card |
+--------+----------------------+-------------------------------------------------+
| JP1 | |jp1-both| | Assert GPIO2 low during each download |
| | | (by jumping it to GPIO0) |
+--------+----------------------+-------------------------------------------------+
| JP7 | |jp7-ext_5v| | Power ESP-WROVER-KIT board from an external |
| | | power supply |
+--------+----------------------+-------------------------------------------------+
| JP7 | |jp7-usb_5v| | Power ESP-WROVER-KIT board from an USB port |
+--------+----------------------+-------------------------------------------------+
| JP8 | |jp8| | Enable JTAG functionality |
+--------+----------------------+-------------------------------------------------+
| JP11 | |jp11-rx-tx| | Enable UART communication |
+--------+----------------------+-------------------------------------------------+
| JP14 | |jp14| | Enable RTS/CTS flow control for serial |
| | | communication |
+--------+----------------------+-------------------------------------------------+
.. _esp-wrover-kit-v2-start-development:
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Initial Setup
^^^^^^^^^^^^^
Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+----------------------+----------------------+
| Power up | Enable UART |
| from USB port | communication |
+----------------------+----------------------+
| |jp7-usb_5v| | |jp11-rx-tx| |
+----------------------+----------------------+
Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Related Documents
-----------------
* `ESP-WROVER-KIT V2 schematic`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
* :doc:`../api-guides/jtag-debugging/index`
* :doc:`../hw-reference/index`
.. |jp1-sd_io2| image:: ../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf
docs/en/get-started/get-started-wrover-kit.rst
+415
View File
@@ -0,0 +1,415 @@
ESP-WROVER-KIT V3 Getting Started Guide
=======================================
This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
If you like to start using this board right now, go directly to section :ref:`get-started-esp-wrover-kit-start-development`.
What You Need
-------------
* 1 × :ref:`ESP-WROVER-KIT V3 board <get-started-esp-wrover-kit-board-front>`
* 1 x Micro USB 2.0 Cable, Type A to Micro B
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
^^^^^^^^
The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
.. note::
ESP-WROVER-KIT V3 integrates the ESP32-WROVER module by default.
Functionality Overview
^^^^^^^^^^^^^^^^^^^^^^
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
ESP-WROVER-KIT block diagram
Functional Description
^^^^^^^^^^^^^^^^^^^^^^
The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
32.768 kHz
An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
0R
A zero Ohm resistor intended as a placeholder for a current shunt. May be desoldered or replaced with a current shunt to facilitate measurement of current required by ESP32 module depending on power mode.
ESP32 Module
ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
.. note::
GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
FT2232
The FT2232 chip is a multi-protocol USB-to-serial bridge. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32. The FT2232 chip also features USB-to-JTAG interface. USB-to-JTAG is available on channel A of FT2232, USB-to-serial on channel B. The embedded FT2232 chip is one of the distinguishing features of the ESPWROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, users do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V3 schematic`_.
UART
Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
SPI
SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. The electrical level on the flash of this module is 1.8V. If an ESP-WROOM-32 is being used, please note that the electrical level on the flash of this module is 3.3V.
CTS/RTS
Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
JTAG
JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
Power Select
Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`get-started-esp-wrover-kit-setup-options`, jumper header JP7.
Power Key
Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
5V Input
The 5V power supply interface is used as a backup power supply in case of full-load operation.
LDO
NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V3 schematic`_.
Camera
Camera interface: a standard OV7670 camera module is supported.
RGB
Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
I/O
All the pins on the ESP32 module are led out to the pin headers on the ESP-WROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro SD Card
Micro SD card slot for data storage.
LCD
ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-board-back`.
.. _get-started-esp-wrover-kit-board-front:
.. figure:: ../_static/esp32-wrover-kit-layout-front.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
ESP-WROVER-KIT board layout - front
.. _get-started-esp-wrover-kit-board-back:
.. figure:: ../_static/esp32-wrover-kit-layout-back.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
ESP-WROVER-KIT board layout - back
.. _get-started-esp-wrover-kit-setup-options:
Setup Options
^^^^^^^^^^^^^
There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+--------+------------------+--------------------------------------------------+
| Header | Jumper Setting | Description of Functionality |
+--------+------------------+--------------------------------------------------+
| JP7 | |jp7-ext_5v| | Power ESP-WROVER-KIT board from an external |
| | | | power supply |
+--------+------------------+--------------------------------------------------+
| JP7 | |jp7-usb_5v| | Power ESP-WROVER-KIT board from an USB port |
+--------+------------------+--------------------------------------------------+
| JP8 | |jp8| | Enable JTAG functionality |
+--------+------------------+--------------------------------------------------+
| JP11 | |jp11-rx-tx| | Enable UART communication |
+--------+------------------+--------------------------------------------------+
| JP14 | |jp14| | Enable RTS/CTS flow control for serial |
| | | communication |
+--------+------------------+--------------------------------------------------+
Allocation of ESP32 Pins
^^^^^^^^^^^^^^^^^^^^^^^^
Several pins / terminals of ESP32 module are allocated to the on board hardware. Some of them, like GPIO0 or GPIO2, have multiple functions. If certain hardware is not installed, e.g. nothing is plugged in to the Camera / JP4 header, then selected GPIOs may be used for other purposes.
Main I/O Connector / JP1
""""""""""""""""""""""""
The JP1 connector is shown in two columns in the middle under "I/O" headers. The two columns "Shared With" outside, describe where else on the board certain GPIO is used.
+----------------------+------+------+----------------------+
| Shared With | I/O | I/O | Shared With |
+======================+======+======+======================+
| | 3.3V | GND | |
+----------------------+------+------+----------------------+
| NC/XTAL | IO32 | IO33 | NC/XTAL |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO12 | IO13 | JTAG, MicroSD |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO14 | IO27 | Camera |
+----------------------+------+------+----------------------+
| Camera | IO26 | IO25 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera | IO35 | IO34 | Camera |
+----------------------+------+------+----------------------+
| Camera | IO39 | IO36 | Camera |
+----------------------+------+------+----------------------+
| JTAG | EN | IO23 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO22 | IO21 | Camera, LCD, MicroSD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO19 | IO18 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO5 | IO17 | PSRAM |
+----------------------+------+------+----------------------+
| PSRAM | IO16 | IO4 | LED, Camera, MicroSD |
+----------------------+------+------+----------------------+
| LED, Boot | IO0 | IO2 | LED, Camera, MicroSD |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO15 | 5V | |
+----------------------+------+------+----------------------+
Legend:
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-xtal>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-jtag-header>`
* Boot - Boot button / SW2
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-camera-header>`
* LED - :ref:`RGB LED <get-started-esp-wrover-rgb-led-connections>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-microsd-card-slot>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-lcd-connector>`
* PSRAM - ESP32-WROVER's PSRAM, if ESP32-WROVER is installed
.. _get-started-esp-wrover-kit-xtal:
32.768 kHz Oscillator
"""""""""""""""""""""
+---+-----------+
| | ESP32 Pin |
+===+===========+
| 1 | GPIO32 |
+---+-----------+
| 2 | GPIO33 |
+---+-----------+
.. note::
As GPIO32 and GPIO33 are connected to the oscillator, to maintain signal integrity, they are not connected to JP1 I/O expansion connector. This allocation may be changed from oscillator to JP1 by desoldering 0R resistors from positions R11 / R23 and installing them in positions R12 / R24.
.. _get-started-esp-wrover-spi-flash-header:
SPI Flash / JP13
""""""""""""""""
+---+--------------+
| | ESP32 Pin |
+===+==============+
| 1 | CLK / GPIO6 |
+---+--------------+
| 2 | SD0 / GPIO7 |
+---+--------------+
| 3 | SD1 / GPIO8 |
+---+--------------+
| 4 | SD2 / GPIO9 |
+---+--------------+
| 5 | SD3 / GPIO10 |
+---+--------------+
| 6 | CMD / GPIO11 |
+---+--------------+
.. important::
The module's flash bus is connected to the pin header JP13 through 0-Ohm resistors R140 ~ R145. If the flash frequency needs to operate at 80 MHz, to improve integrity of the bus signals, it is recommended to desolder resistors R140 ~ R145. At this point, the module's flash bus is disconnected with the pin header JP13.
.. _get-started-esp-wrover-jtag-header:
JTAG / JP8
""""""""""
+---+---------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+===============+=============+
| 1 | EN | TRST_N |
+---+---------------+-------------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-------------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-------------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-------------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-------------+
.. _get-started-esp-wrover-camera-header:
Camera / JP4
""""""""""""
+----+--------------+----------------------+
| | ESP32 Pin | Camera Signal |
+====+==============+======================+
| 1 | GPIO27 | SCCB Clock |
+----+--------------+----------------------+
| 2 | GPIO26 | SCCB Data |
+----+--------------+----------------------+
| 3 | GPIO21 | System Clock |
+----+--------------+----------------------+
| 4 | GPIO25 | Vertical Sync |
+----+--------------+----------------------+
| 5 | GPIO23 | Horizontal Reference |
+----+--------------+----------------------+
| 6 | GPIO22 | Pixel Clock |
+----+--------------+----------------------+
| 7 | GPIO4 | Pixel Data Bit 0 |
+----+--------------+----------------------+
| 8 | GPIO5 | Pixel Data Bit 1 |
+----+--------------+----------------------+
| 9 | GPIO18 | Pixel Data Bit 2 |
+----+--------------+----------------------+
| 10 | GPIO19 | Pixel Data Bit 3 |
+----+--------------+----------------------+
| 11 | GPIO36 | Pixel Data Bit 4 |
+----+--------------+----------------------+
| 11 | GPIO39 | Pixel Data Bit 5 |
+----+--------------+----------------------+
| 11 | GPIO34 | Pixel Data Bit 6 |
+----+--------------+----------------------+
| 11 | GPIO35 | Pixel Data Bit 7 |
+----+--------------+----------------------+
| 11 | GPIO2 | Camera Reset |
+----+--------------+----------------------+
.. _get-started-esp-wrover-rgb-led-connections:
RGB LED
"""""""
+---+-----------+---------+
| | ESP32 Pin | RGB LED |
+===+===========+=========+
| 1 | GPIO0 | Red |
+---+-----------+---------+
| 2 | GPIO2 | Blue |
+---+-----------+---------+
| 3 | GPIO4 | Green |
+---+-----------+---------+
.. _get-started-esp-wrover-microsd-card-slot:
MicroSD Card / J4
"""""""""""""""""
+---+---------------+----------------+
| | ESP32 Pin | MicroSD Signal |
+===+===============+================+
| 1 | MTDI / GPIO12 | DATA2 |
+---+---------------+----------------+
| 2 | MTCK / GPIO13 | CD / DATA3 |
+---+---------------+----------------+
| 3 | MTDO / GPIO15 | CMD |
+---+---------------+----------------+
| 4 | MTMS / GPIO14 | CLK |
+---+---------------+----------------+
| 5 | GPIO2 | DATA0 |
+---+---------------+----------------+
| 6 | GPIO4 | DATA1 |
+---+---------------+----------------+
| 7 | GPIO21 | CD |
+---+---------------+----------------+
.. _get-started-esp-wrover-lcd-connector:
LCD / U5
""""""""
+---+-----------+------------+
| | ESP32 Pin | LCD Signal |
+===+===========+============+
| 1 | GPIO18 | RESET |
+---+-----------+------------+
| 2 | GPIO19 | SCL |
+---+-----------+------------+
| 3 | GPIO21 | D/C |
+---+-----------+------------+
| 4 | GPIO22 | CS |
+---+-----------+------------+
| 5 | GPIO23 | SDA |
+---+-----------+------------+
| 6 | GPIO25 | SDO |
+---+-----------+------------+
| 7 | GPIO5 | Backlight |
+---+-----------+------------+
.. _get-started-esp-wrover-kit-start-development:
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Initial Setup
^^^^^^^^^^^^^
Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+----------------------+----------------------+
| Power up | Enable UART |
| from USB port | communication |
+----------------------+----------------------+
| |jp7-usb_5v| | |jp11-rx-tx| |
+----------------------+----------------------+
Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP-WROVER-KIT, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Related Documents
-----------------
* `ESP-WROVER-KIT V3 schematic`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* :doc:`../api-guides/jtag-debugging/index`
* :doc:`../hw-reference/index`
.. |jp1-sd_io2| image:: ../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V3 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf
.. toctree::
:hidden:
get-started-wrover-kit-v2.rst
docs/en/get-started/idf-monitor.rst
+133
View File
@@ -0,0 +1,133 @@
***********
IDF Monitor
***********
The idf_monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.
It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific xfeatures.
Interacting With idf_monitor
============================
- ``Ctrl-]`` will exit the monitor.
- ``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts.
- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port.
Automatically Decoding Addresses
================================
Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, idf_monitor will use addr2line_ to look up the source code location and function name.
.. highlight:: none
When an esp-idf app crashes and panics a register dump and backtrace such as this is produced::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
idf_monitor will augment the dump::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
Behind the scenes, the command idf_monitor runs to decode each address is::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
Launch GDB for GDBStub
======================
By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets.
Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
If this option is enabled and idf_monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
Behind the scenes, the command idf_monitor runs is::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
Quick Compile and Flash
=======================
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``make flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``make app-flash`` target, then resume idf_monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed.
Quick Reset
===========
The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.)
Pause the Application
=====================
The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is
useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the
application.
Toggle Output Display
=====================
Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will
toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
again quickly without quitting the monitor.
Simple Monitor
==============
Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
This program can still be run, via ``make simple_monitor``.
idf_monitor is based on miniterm and shares the same basic keyboard shortcuts.
Known Issues with idf_monitor
=============================
Issues Observed on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix.
- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations.
- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes.
- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub.
.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html
.. _gdb: https://sourceware.org/gdb/download/onlinedocs/
.. _pySerial: https://github.com/pyserial/pyserial
.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm
docs/en/get-started/index.rst
+332
View File
@@ -0,0 +1,332 @@
***********
Get Started
***********
This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
Introduction
============
ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
What You Need
=============
To develop applications for ESP32 you need:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to build the **Application** for ESP32
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
.. figure:: ../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
Development of applications for ESP32
Preparation of development environment consists of three steps:
1. Setup of **Toolchain**
2. Getting of **ESP-IDF** from GitHub
3. Installation and configuration of **Eclipse**
You may skip the last step, if you prefer to use different editor.
Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
1. Configuration of a **Project** and writing the code
2. Compilation of the **Project** and linking it to build an **Application**
3. Flashing (uploading) of the **Application** to **ESP32**
4. Monitoring / debugging of the **Application**
See instructions below that will walk you through these steps.
Guides
======
If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
.. toctree::
:maxdepth: 1
ESP32 DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
If you have different board, move to sections below.
.. _get-started-setup-toolchain:
Setup Toolchain
===============
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. note::
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
.. _get-started-get-esp-idf:
Get ESP-IDF
===========
.. highlight:: bash
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
.. note::
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
cd ~/esp/esp-idf
git submodule update --init
.. _get-started-setup-path:
Setup Path to ESP-IDF
=====================
The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
.. _get-started-start-project:
Start a Project
===============
Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to ``~/esp`` directory::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
.. important::
The esp-idf build system does not support spaces in paths to esp-idf or to projects.
.. _get-started-connect:
Connect
=======
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
.. _get-started-configure:
Configure
=========
Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
cd ~/esp/hello_world
make menuconfig
If previous steps have been done correctly, the following menu will be displayed:
.. figure:: ../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
Project configuration - Home window
In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
.. note::
On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
(See :doc:`establish-serial-connection` for full details.)
Here are couple of tips on navigation and use of ``menuconfig``:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go out or to exit.
* Type ``?`` to see a help screen. Enter key exits the help screen.
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* Pressing ``?`` while highlighting a configuration item displays help about that item.
* Type ``/`` to search the configuration items.
.. note::
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. _get-started-build-flash:
Build and Flash
===============
Now you can build and flash the application. Run::
make flash
This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
.. highlight:: none
::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-build-monitor:
Monitor
=======
To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
...
Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit the monitor use shortcut ``Ctrl+]``.
.. note::
If instead of the messages above, you see a random garbage similar to::
e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
That's all what you need to get started with ESP32!
Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
Updating ESP-IDF
================
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
Another solution is to update only what has changed. This method is useful if you have slow connection to the GiHub. To do the update run the following commands::
cd ~/esp/esp-idf
git pull
git submodule update --init --recursive
The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
cd ~/esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
cd esp-idf-v2.1/
git checkout v2.1
git submodule update --init --recursive
After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
Related Documents
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
idf-monitor
toolchain-setup-scratch
docs/en/get-started/linux-setup-scratch.rst
+66
View File
@@ -0,0 +1,66 @@
**********************************
Setup Linux Toolchain from Scratch
**********************************
The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- Ubuntu and Debian::
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
Compile the Toolchain from Source
=================================
- Install dependencies:
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
- Ubuntu 16.04::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Arch::
TODO
Download ``crosstool-NG`` and build it::
cd ~/esp
git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
cd crosstool-NG
./bootstrap && ./configure --enable-local && make install
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
docs/en/get-started/linux-setup.rst
+109
View File
@@ -0,0 +1,109 @@
*************************************
Standard Setup of Toolchain for Linux
*************************************
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install git wget make ncurses-devel flex bison gperf python pyserial
- Ubuntu and Debian::
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
Toolchain Setup
===============
ESP32 toolchain for Linux is available for download from Espressif website:
- for 64-bit Linux:
https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
- for 32-bit Linux:
https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
1. Download this file, then extract it in ``~/esp`` directory::
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
.. _setup-linux-toolchain-add-it-to-path:
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32='export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
printenv PATH
You are looking for similar result containing toolchain's path at the end of displayed string::
$ printenv PATH
/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
Instead of ``/home/user-name`` there should be a home path specific to your installation.
Permission issues /dev/ttyUSB0
------------------------------
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
Arch Linux Users
----------------
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Related Documents
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
docs/en/get-started/macos-setup-scratch.rst
+67
View File
@@ -0,0 +1,67 @@
***************************************
Setup Toolchain for Mac OS from Scratch
***************************************
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
- install pyserial::
sudo pip install pyserial
Compile the Toolchain from Source
=================================
- Install dependencies:
- Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
- with MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
- with homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
Create a case-sensitive filesystem image::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
Mount it::
hdiutil mount ~/esp/crosstool.dmg
Create a symlink to your work directory::
cd ~/esp
ln -s /Volumes/ctng crosstool-NG
Download ``crosstool-NG`` and build it::
cd ~/esp
git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
cd crosstool-NG
./bootstrap && ./configure --enable-local && make install
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
docs/en/get-started/macos-setup.rst
+57
View File
@@ -0,0 +1,57 @@
**************************************
Standard Setup of Toolchain for Mac OS
**************************************
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
- install pyserial::
sudo pip install pyserial
Toolchain Setup
===============
ESP32 toolchain for macOS is available for download from Espressif website:
https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
Download this file, then extract it in ``~/esp`` directory::
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
.. _setup-macos-toolchain-add-it-to-path:
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Related Documents
=================
.. toctree::
:maxdepth: 1
macos-setup-scratch
docs/en/get-started/make-project.rst
+73
View File
@@ -0,0 +1,73 @@
Build and Flash with Make
=========================
Finding a project
-----------------
As well as the `esp-idf-template <https://github.com/espressif/esp-idf-template>`_ project, ESP-IDF comes with some example projects on github in the :idf:`examples` directory.
Once you've found the project you want to work with, change to its directory and you can configure and build it.
Configuring your project
------------------------
::
make menuconfig
Compiling your project
----------------------
::
make all
... will compile app, bootloader and generate a partition table based on the config.
Flashing your project
---------------------
When ``make all`` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running::
make flash
This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`.
You don't need to run ``make all`` before running ``make flash``, ``make flash`` will automatically rebuild anything which needs it.
Compiling & Flashing Just the App
---------------------------------
After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
* ``make app`` - build just the app.
* ``make app-flash`` - flash just the app.
``make app-flash`` will automatically rebuild the app if it needs it.
There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.
The Partition Table
-------------------
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
A single ESP32's flash can contain multiple apps, as well as many kinds of data (calibration data, filesystems, parameter storage, etc). For this reason, a partition table is flashed to offset 0x8000 in the flash.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`.
docs/en/get-started/toolchain-setup-scratch.rst
+25
View File
@@ -0,0 +1,25 @@
.. _get-started-customized-setup:
*****************************
Customized Setup of Toolchain
*****************************
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself.
If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:
- if you want to customize toolchain build configuration
- if you want to use a different GCC version (such as 4.8.5)
- if you want to hack gcc or newlib or libstdc++
- if you are curious and/or have time to spare
- if you don't trust binaries downloaded from the Internet
In any case, here are the instructions to compile the toolchain yourself.
.. toctree::
:maxdepth: 1
windows-setup-scratch
linux-setup-scratch
macos-setup-scratch
docs/en/get-started/windows-setup-scratch.rst
+115
View File
@@ -0,0 +1,115 @@
************************************
Setup Windows Toolchain from Scratch
************************************
Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps.
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
.. _configure-windows-toolchain-from-scratch:
Configure Toolchain & Environment from Scratch
==============================================
This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
*(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
Troubleshooting
~~~~~~~~~~~~~~~
* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
*** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
MSYS2 Mirrors in China
~~~~~~~~~~~~~~~~~~~~~~
There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
Add these lines at the top of ``mirrorlist.mingw32``::
Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
Add these lines at the top of ``mirrorlist.msys``::
Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
HTTP Proxy
~~~~~~~~~~
You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
export http_proxy='http://http.proxy.server:PORT'
Or with credentials::
export http_proxy='http://user:password@http.proxy.server:PORT'
Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
Alternative Setup: Just download a toolchain
============================================
If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
.. note::
If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
.. important::
Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
.. _updating-existing-windows-environment:
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
- Update IDF to the new version you want to use.
- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
.. _MSYS2: https://msys2.github.io/
.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new
docs/en/get-started/windows-setup.rst
+65
View File
@@ -0,0 +1,65 @@
***************************************
Standard Setup of Toolchain for Windows
***************************************
Introduction
============
Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
Toolchain Setup
===============
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip
Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
Check it Out
============
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell.
.. figure:: ../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
MSYS2 MINGW32 shell window
Use this window in the following steps setting up development environment for ESP32.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
- Download the new precompiled environment using the steps above.
- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
You can have independent different MSYS2 environments on your system, as long as they are in different directories.
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
Related Documents
=================
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _MSYS2: https://msys2.github.io/