Update docs

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.
+

docs/source/arch/esp32/debugging/index.rst

@@ -21,29 +21,29 @@ 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
 ---------------
 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
 

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 <https://docs.espressif.com/projects/esp-idf/en/v4.0/get-started/index.html#installation-step-by-step>`__.
+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 <https://docs.espressif.com/projects/esp-idf/en/v4.0/get-started/index.html#installation-step-by-step>`__.
 
 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.