From a905c924926db04576d340093dedfad503cb62ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Thu, 17 May 2018 12:56:57 +0100 Subject: [PATCH] Improvements in ESP32 related docs (#691) --- .vscode/tasks.TEMPLATE-ESP32.json | 12 +- targets/FreeRTOS/ESP32_DevKitC/BUILD-ESP32.md | 183 +++++++++++------- 2 files changed, 123 insertions(+), 72 deletions(-) diff --git a/.vscode/tasks.TEMPLATE-ESP32.json b/.vscode/tasks.TEMPLATE-ESP32.json index a1ff204fc5..084faf898e 100644 --- a/.vscode/tasks.TEMPLATE-ESP32.json +++ b/.vscode/tasks.TEMPLATE-ESP32.json @@ -4,9 +4,9 @@ "version": "2.0.0", "tasks": [ { - "taskName": "Flash NanoClr ", + "taskName": "Flash nanoCLR ", "type": "shell", - "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 115200 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/nanoCLR.bin 0x8000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/partitions_4mb.bin", + "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 921600 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 //build/nanoCLR.bin 0x8000 //build/partitions_4mb.bin", "presentation": { "reveal": "always", "panel": "shared" @@ -14,9 +14,9 @@ "problemMatcher": [] }, { - "taskName": "Flash NanoClr Wrover ", + "taskName": "Flash nanoCLR Wrover ", "type": "shell", - "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 115200 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/nanoCLR.bin 0x8000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/partitions_4mb.bin", + "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 921600 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 //build/nanoCLR.bin 0x8000 //build/partitions_4mb.bin", "presentation": { "reveal": "always", "panel": "shared" @@ -24,9 +24,9 @@ "problemMatcher": [] }, { - "taskName": "Flash NanoClr ESP32-EVB ", + "taskName": "Flash nanoCLR ESP32-EVB ", "type": "shell", - "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 115200 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/nanoCLR.bin 0x8000 /nf-interpreter/build/targets/FreeRTOS/ESP32_DevKitC/partitions_4mb.bin", + "command": "python /esp-idf/components/esptool_py/esptool/esptool.py --chip esp32 --port \"\" --baud 921600 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 /esp-idf/examples/get-started/blink/build/bootloader/bootloader.bin 0x10000 //build/nanoCLR.bin 0x8000 //build/partitions_4mb.bin", "presentation": { "reveal": "always", "panel": "shared" diff --git a/targets/FreeRTOS/ESP32_DevKitC/BUILD-ESP32.md b/targets/FreeRTOS/ESP32_DevKitC/BUILD-ESP32.md index 116639f991..77af3a80ee 100644 --- a/targets/FreeRTOS/ESP32_DevKitC/BUILD-ESP32.md +++ b/targets/FreeRTOS/ESP32_DevKitC/BUILD-ESP32.md @@ -1,12 +1,13 @@ -# How to Build, Flash and Debug the ESP32 nanoClr on Windows using Visual Code +# How to Build, Flash and Debug the ESP32 nanoCLR on Windows using Visual Code -## Table of contents ## + +## Table of contents - [Prerequisites](#prerequisites) - [Setting up the build environment for ESP32](#Setting up the build environment for ESP32) - [Set up Visual Code](#Set up Visual Code) -- [Build the nanoClr](#Build the nanoClr) -- [Flash nanoClr to ESP32](#Flash nanoClr to ESP32) +- [Build the nanoCLR](#Build the nanoCLR) +- [Flash nanoCLR to ESP32](#Flash nanoCLR to ESP32) - [Start with a Hello World C# application](#Start with a Hello World C# application) - [Debug the nanoCLR](#Debug the nanoCLR) @@ -15,7 +16,8 @@ This document describes how to build the required images for **nanoFramework** for ESP32. The build is based on CMake tool to ease the development in all major platforms. -# Prerequisites + +## Prerequisites You'll need: @@ -27,58 +29,66 @@ You'll need: - [Python 3.6.5](https://www.python.org/ftp/python/3.6.5/python-3.6.5.exe) Required for uploading the nanoCLR to the ESP32. - [OpenOCD](https://github.com/espressif/openocd-esp32/releases/download/v0.10.0-esp32-20180418/openocd-esp32-win32-0.10.0-esp32-20180418.zip) For on chip debugging of the nanoCLR -# Setting up the build environment for ESP32 -To save time on building the nanoClr and to avoid having to create a CMakeLists.txt project for the ESP32 IDF files, the ESP32 IDF libraries are prebuilt using the Esp32 Msys32 environment then used for linking in the CMake build of nanoClr. +## Setting up the build environment for ESP32 + +To save time on building the nanoCLR and to avoid having to create a CMakeLists.txt project for the ESP32 IDF files, the ESP32 IDF libraries are prebuilt using the Esp32 Msys32 environment then used for linking in the CMake build of nanoCLR. This has already been done and the libraries can be just be downloaded. -Create the following directory structure:- +1. Create a directory structure such as the following: + + - `C:\Esp32_Tools` + - `C:\Esp32_Tools\libs` + +2. Download the pre-built libs zip from [here](https://bintray.com/nfbot/internal-build-tools/download_file?file_path=IDF_libs.zip) +and extract it into `C:\Esp32_Tools\libs`. -- c:\Esp32_Tools -- c:\Esp32_Tools\libs +3. Download the v3.0rc1 IDF source zip file from [here](https://github.com/espressif/esp-idf/releases/download/v3.0-rc1/esp-idf-v3.0-rc1.zip) and extract it into `C:\Esp32_Tools` so you get `C:\ESP32_Tools\esp-idf-v3.0-rc1\components` etc. -Download the pre-built libs zip from here:- https://bintray.com/nfbot/internal-build-tools/download_file?file_path=IDF_libs.zip -and unzip into c:\Esp32_Tools\libs +4. Download the Esp32 toolchain from [here](https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-75-gbaf03c2-5.2.0.zip) and extract it into `C:\Esp32_Tools` so you get `C:\Esp32_Tools\xtensa-esp32-elf`. -Download the v3.0rc1 IDF source zip file from here :- https://github.com/espressif/esp-idf/releases/download/v3.0-rc1/esp-idf-v3.0-rc1.zip -Unzip into c:\Esp32_Tools so you get C:\ESP32_Tools\esp-idf-v3.0-rc1\components etc. +5. Extract OpenOCD into `C:\Esp32_Tools` so you get `C:\Esp32_Tools\openocd-esp32`. -Download the Esp32 toolchain from https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-75-gbaf03c2-5.2.0.zip -Unzip into C:\Esp32_Tools so you get C:\Esp32_Tools\xtensa-esp32-elf -Unzip the OpenOCD into C:\Esp32_Tools so you get C:\Esp32_Tools\openocd-esp32 +## **nanoFramework** GitHub repo -## Nanoframework on GitHub ( https://github.com/nanoframework/nf-interpreter ) +If you intend to change the nanoCLR for ESP32 and create Pull Requests then you will need to fork the [nanoFramework/nf-interpreter](https://github.com/nanoFramework/nf-interpreter) to your own GitHub repo and clone the forked GitHub repo to your Windows system using an Git client such as the [GitHub Desktop application](https://desktop.github.com/). + +You should use the _develop_ branch for mainstream development or the _develop-network_ branch to work with the networking features which is currently a work in progress. -If you intend to changed the nanoCLR for ESP32 and create Pull Requests then you will need to fork the Nanoframework/nf-interpreter to your own github repo and clone the forked github repo to your Windows system. (GitHub Desktop application). -You should use the develop branch for all activity or develop-network to include the Networking work in progrees. ## Set up CMake -- Download the latest stable version from https://cmake.org/download/ and install it. + +1. Download the latest stable version from [here](https://cmake.org/download/) and install it. + + ## Set up Visual Code -Install extensions +1. Install the extensions: -"C/C++" extension by Microsoft -"CMake" language support for Visual Studio Code by twxs -"CMake tools" Extended CMake support in Visual Studio code by vector-of-bool (Must be version 0.10.4 as version 0.11 is currently not supported) -To install an older version of a VS extension you have to hack it. -- In Visual Studio Code goto settings -> settings and set "extensions.autoUpdate" to false -- Download https://ms-vscode.gallery.vsassets.io/_apis/public/gallery/publisher/vector-of-bool/extension/cmake-tools/0.10.4/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage -- Rename the download into a file with ".vsix" extension -- In Visual Studio Code goto Extension click the "..." and select "Install form VSIX" and select the renamed download. + - "C/C++" extension by Microsoft. + - "CMake" language support for Visual Studio Code by twxs. + - "CMake tools" Extended CMake support in Visual Studio code by vector-of-bool (Must be version 0.10.4 as version 0.11 is currently not supported). + + To install an older version of a VS extension you have to hack it like this: + - In Visual Studio Code goto settings -> settings and set "extensions.autoUpdate" to false. + - Download version 0.10.4 from [here](https://ms-vscode.gallery.vsassets.io/_apis/public/gallery/publisher/vector-of-bool/extension/cmake-tools/0.10.4/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage). + - Rename the download into a file with ".vsix" extension. + - In Visual Studio Code goto Extension click the "..." and select "Install form VSIX" and select the file that you've just renamed. -Set up the "CMake-variants.json' in root directory of nanoframework/nf-interpreter clone -There is a template file called cmake-variants.TEMPLATE.json that can be renamed and set up to the following:- -Be aware of the foreward slashes in the paths. The TOOLCHAIN_PREFIX should be set to the directory where the xtensa-esp32-elf is the subdirectory. If you follow the paths in this guide then you can use this as it is:- +2. Set up the `CMake-variants.json` in root directory of your local nanoFramework/nf-interpreter clone. + + There is a template file called `cmake-variants.TEMPLATE.json` that can be renamed and set up to the following: + + Be aware of the forward slashes in the paths. The TOOLCHAIN_PREFIX should be set to the directory where the xtensa-esp32-elf is the subdirectory. If you follow the paths in this guide then you can use this as it is: ``` "linkage": { - "Esp32_NanoCLR": { - "oneWordSummary$": "NanoCLR", - "description$": "Build TinyCLR for ESP32 environment", + "Esp32_nanoCLR": { + "oneWordSummary$": "nanoCLR", + "description$": "Build nanoCLR for ESP32 environment", "settings": { - "TOOLCHAIN_PREFIX" : "C:/ESP32_Tools", + "TOOLCHAIN_PREFIX" : "C:/ESP32_Tools", "TARGET_SERIES" : "ESP32", "RTOS" : "FREERTOS", "ESP32_IDF_PATH" : "C:/ESP32_Tools/esp-idf-v3.0-rc1", @@ -100,24 +110,25 @@ Be aware of the foreward slashes in the paths. The TOOLCHAIN_PREFIX should be se "API_Windows.Devices.Adc" : "ON", "API_Windows.Devices.Pwm" : "ON", "API_Windows.Devices.Wifi": "ON", - "API_System.Net" : "OFF", - "API_Windows.Networking.Sockets" : "OFF" + "API_System.Net" : "OFF", + "API_Windows.Networking.Sockets" : "OFF" } }, ``` -Create a ./.vscode/tasks.json from /.vscode/tasks.TEMPLATE-ESP32.json -For flashing the nanoCLR into the ESP32 or to erase the flash of the ESP32 you will need this in the tasks.json file -Adjust the COM port and the to your needs. +3. Create a `./.vscode/tasks.json` from `/.vscode/tasks.TEMPLATE-ESP32.json`. + + For flashing the nanoCLR into the ESP32 or to erase the flash of the ESP32 you will need this in the `tasks.json` file. + Adjust the COM port and the path to nanoFramework build directory (**!!mind the forward slashes!!**) to your needs. ``` { "version": "2.0.0", "tasks": [ { - "taskName": "Flash NanoClr COM6", + "taskName": "Flash nanoCLR COM6", "type": "shell", - "command": "python C:/ESP32_Tools/esp-idf-v3.0-rc1/components/esptool_py/esptool/esptool.py --chip esp32 --port \"COM6\" --baud 115200 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 C:/ESP32_Tools/libs/bootloader.bin 0x10000 /NanoCLR.bin 0x8000 /partitions_4mb.bin", + "command": "python C:/ESP32_Tools/esp-idf-v3.0-rc1/components/esptool_py/esptool/esptool.py --chip esp32 --port \"COM6\" --baud 115200 --before \"default_reset\" --after \"hard_reset\" write_flash -z --flash_mode \"dio\" --flash_freq \"40m\" --flash_size detect 0x1000 C:/ESP32_Tools/libs/bootloader.bin 0x10000 /nanoCLR.bin 0x8000 /partitions_4mb.bin", "presentation": { "reveal": "always", "panel": "shared" @@ -138,32 +149,73 @@ Adjust the COM port and the to your needs. +Create a `./.vscode/launch.json` from `/.vscode/launch.TEMPLATE-ESP32.json`. + +Edit the file and adjust the absolute path to the build folder (**!!mind the forward slashes!!**) to your needs. ``` { @@ -203,14 +255,13 @@ Edit the file and adjust the