From 676680d44e5bfa271b7b0040bb5578c4531d77a0 Mon Sep 17 00:00:00 2001 From: mikee47 Date: Mon, 9 Nov 2020 21:20:50 +0000 Subject: [PATCH] Update docs --- Sming/Arch/Esp32/Components/esp32/README.rst | 50 +++++++++++++++++-- docs/source/arch/esp32/debugging/index.rst | 34 ++++++------- .../arch/esp32/getting-started/index.rst | 35 +++++++------ 3 files changed, 82 insertions(+), 37 deletions(-) diff --git a/Sming/Arch/Esp32/Components/esp32/README.rst b/Sming/Arch/Esp32/Components/esp32/README.rst index d1089cf388..5017d7f176 100644 --- a/Sming/Arch/Esp32/Components/esp32/README.rst +++ b/Sming/Arch/Esp32/Components/esp32/README.rst @@ -3,26 +3,68 @@ Esp32 Core Component .. highlight:: bash -Contains startup code, crash handling and additional Esp32-specific support code. +Introduction +------------ + +Contains startup code, crash handling and additional Esp32-specific support code, +including the ESP-IDF SDK. If you want to tune ESP-IDF to your needs you should run:: - make sdk-menuconfig + make SMING_ARCH=Esp32 sdk-menuconfig Followed by:: - make sdk-build - + make + + +Configuration variables +----------------------- + +These are read-only debug variables: .. envvar:: SDK_INTERNAL **READONLY** When compiled using the current (version 3+) Espressif SDK this value is set to 1. + .. envvar:: SDK_LIBDIR **READONLY** Path to the directory containing SDK archive libraries + .. envvar:: SDK_INCDIR **READONLY** Path to the directory containing SDK header files + +Option variables: + +.. envvar:: ESP_VARIANT + + Build for for esp32 or esp32s2 device + + +The following variables may need to be changed if tools are installed in a different location, +or if multiple versions are installed. By default, the most current version will be used. + + +.. envvar:: ESP32_COMPILER_PATH + + Location of xtensa compiler toolchain + + +.. envvar:: ESP32_ULP_PATH + + Location of ULP compiler toolchain + + +.. envvar:: ESP32_OPENOCD_PATH + + Location of ESP32 version of Open OCD JTAG debugging tools. + + +.. envvar:: ESP32_PYTHON_PATH + + Location of ESP-IDF python. + diff --git a/docs/source/arch/esp32/debugging/index.rst b/docs/source/arch/esp32/debugging/index.rst index 5983d3972c..0f0f36f514 100644 --- a/docs/source/arch/esp32/debugging/index.rst +++ b/docs/source/arch/esp32/debugging/index.rst @@ -21,21 +21,21 @@ Configure Hardware The JTAG adapter has to be connected to your ESP32 microcontroller. The following pins from the JTAG adapter have to be connected to ESP32 for the communication to work. - +---+---------------+-------------+ - | | ESP32 Pin | JTAG Signal | - +===+===============+=============+ - | 1 | VCC | VCC | - +---+---------------+-------------+ - | 2 | MTDO / GPIO15 | TDO | - +---+---------------+-------------+ - | 3 | MTDI / GPIO12 | TDI | - +---+---------------+-------------+ - | 4 | MTCK / GPIO13 | TCK | - +---+---------------+-------------+ - | 5 | MTMS / GPIO14 | TMS | - +---+---------------+-------------+ - | 6 | GND | GND | - +---+---------------+-------------+ + +---+---------------+-------------+-------------+-------------+ + | | ESP32 Pin | nodeMCU Pin | USB Blaster | JTAG Signal | + +===+===============+=============+=============+=============+ + | 1 | VCC | 3V3 | 4 | VCC | + +---+---------------+-------------+-------------+-------------+ + | 2 | MTDO / GPIO15 | D15 | 3 | TDO | + +---+---------------+-------------+-------------+-------------+ + | 3 | MTDI / GPIO12 | D12 | 9 | TDI | + +---+---------------+-------------+-------------+-------------+ + | 4 | MTCK / GPIO13 | D13 | 1 | TCK | + +---+---------------+-------------+-------------+-------------+ + | 5 | MTMS / GPIO14 | D14 | 5 | TMS | + +---+---------------+-------------+-------------+-------------+ + | 6 | GND | GND | 2 | GND | + +---+---------------+-------------+-------------+-------------+ Running OpenOCD @@ -43,7 +43,7 @@ Running OpenOCD Once the JTAG adapter is connected to the microcontroller and to a computer we have to start the OpenOCD server that will communicate with the JTAG adapter. For our specific hardware the following command has to be executed:: - openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg + openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f target/esp32.cfg If you have configured your JTAG adapter correctly the following messages should show up:: @@ -103,7 +103,7 @@ sample application:: The device will restart then wait for a debugger to be connected. Before starting the debugger you must be sure that the OpenOCD server is running and listening for incoming connections on localhost port 3333. Now start the debugger with the command below -:: +::::::::::::::::::::::::::::::::::::::::::::: make gdb diff --git a/docs/source/arch/esp32/getting-started/index.rst b/docs/source/arch/esp32/getting-started/index.rst index e45723d699..ecf1f20a1a 100644 --- a/docs/source/arch/esp32/getting-started/index.rst +++ b/docs/source/arch/esp32/getting-started/index.rst @@ -1,16 +1,23 @@ Getting Started: ESP32 -======================== +====================== Requirements ------------ -In order to be able to compile for the ESP32 architecture you should have ESP-IDF v4.0 installed. +In order to be able to compile for the ESP32 architecture you should have ESP-IDF v4.1 installed. -Get the latest `release/v4.0` branch. This can be done using the following command:: +Get the latest `release/v4.1` branch. This can be done using the following command:: - git clone -b release/v4.0 --recursive https://github.com/espressif/esp-idf.git + git clone -b release/v4.1 https://github.com/espressif/esp-idf.git -Once the command above finishes follow the installation steps described in the `ESP-IDF documentation `__. +Note that a recursive clone is not required as the necessary submodules will be fetched during the build stage. + +Now install the toolchain:: + + esp-idf/install + +For information about pre-requisites and other issues, see +`ESP-IDF documentation `__. Building -------- @@ -21,10 +28,8 @@ Make sure that the IDF_PATH environmental variable is set. On Linux you can use Replace `path/to` with the correct path. -Also make sure that the other ESP-IDF environmental variables are set. -For example on Linux this can be done using the following command:: - - source $IDF_PATH/export.sh +Note that you do not need to run ``IDF export.sh`` as this is handled by the Sming build system. +This simplifies use within the Eclipse IDE as there is only one environment variable to set. Build the framework and application as usual, specifying :envvar:`SMING_ARCH` =Esp32. For example:: @@ -37,13 +42,11 @@ Flashing can be done using the following command:: make flash -SDK ---- - -Sming comes with initial configuration for ESP-IDF. If needed you can re-configure ESP-IDF using the command below:: +.. note:: - make SMING_ARCH=Esp32 sdk-menuconfig + If you have an ESP32-S2 device you'll need to change :envvar:`ESP_VARIANT`:: + + make ESP_VARIANT=esp32s2 -A re-compilation is required after the change of the configuration. This can be done with the following command:: - make SMING_ARCH=Esp32 sdk-build +See :component-esp32:`esp32` for further details.