diff --git a/IDE/Espressif/ESP-IDF/README.md b/IDE/Espressif/ESP-IDF/README.md index ea9dd16a1..65eef865e 100644 --- a/IDE/Espressif/ESP-IDF/README.md +++ b/IDE/Espressif/ESP-IDF/README.md @@ -1,21 +1,81 @@ -# ESP-IDF port +# ESP-IDF Port -NOTICE: These Espressif examples have been created and tested with the latest stable release branch of -[ESP-IDF V4](https://docs.espressif.com/projects/esp-idf/en/v4.4.1/esp32/get-started/index.html) -and have not yet been upgraded to the master branch V5. -See the latest [migration guides](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html). +These Espressif examples have been created and tested with the latest stable release branch of +[ESP-IDF V5.1](https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32/get-started/index.html). +The prior version 4.4 ESP-IDF is still supported, however version 5.1 or greater is recommended. +Espressif has [a list of all ESP-IDF versions](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html). -## Overview +See the latest [Espressif Migration Guides](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html). - ESP-IDF development framework with wolfSSL by setting *WOLFSSL_ESPIDF* definition +## Examples -Including the following examples: +Included are the following [examples](./examples/README.md): -* Simple [TLS client](./examples/wolfssl_client/)/[server](./examples/wolfssl_server/) -* Cryptographic [test](./examples/wolfssl_test/) -* Cryptographic [benchmark](./examples/wolfssl_benchmark/) +* Bare-bones [Template](./examples/template/README.md) +* Simple [TLS Client](./examples/wolfssl_client/README.md) / [TLS Server](./examples/wolfssl_server/README.md) +* Cryptographic [Test](./examples/wolfssl_test/README.md) +* Cryptographic [Benchmark](./examples/wolfssl_benchmark/README.md) - The *user_settings.h* file enables some of the hardened settings. +## Important Usage Details + +The wolfSSL code specific to the Espressif ESP-IDF development framework +is gated in code with the `WOLFSSL_ESPIDF` definition. This is enabled +automatically when the `WOLFSSL_USER_SETTINGS` is defined. The recommended +method is to have this line in the main `CMakeLists.txt` file as shown in the +[example](./examples/template/main/CMakeLists.txt): + +```cmake +set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DWOLFSSL_USER_SETTINGS") +``` + +When defining `WOLFSSL_USER_SETTINGS`, this tells the `settings.h` file to +looks for the wolfSSL `user_settings.h` in the project as described below. + +### File: `sdkconfig.h` + +The Espressif `sdkconfig.h`, generated automatically from your `sdkconfig` +file at [build](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html) +time, should be included before any other files. + +### File: `user_settings.h` + +The `user_settings.h` file enables some of the hardened security settings. There are also some +default configuration items in the wolfssl `settings.h`. With the latest version of +wolfSSL, some of these defaults can be disabled with `NO_ESPIDF_DEFAULT` and customized +in your project `user_settings.h` as desired. + +See the respective project directory: + + `[project-dir]/components/wolfssl/user_settings.h` + +A typical project will _not_ directly reference the `user_settings.h` file. +Here's an example to be included at the top of a given source file: + +```c +/* ESP-IDF */ +#include +#include "sdkconfig.h" + +/* wolfSSL */ +#include /* references user_settings.h */ +/* Do not explicitly include wolfSSL user_settings.h */ +#include +#include +``` + +Prior versions of the wolfSSL Espressif library expected the `user_settings.h` to be in the root wolfssl folder in a directory +called `/include`. This method, while possible, is no longer recommended. + +Be sure to *not* have a `user_settings.h` in _both_ the local project and the wolfssl `include` directories. + +### File: `wolfssl/wolfcrypt/settings.h` + +The wolfSSL built-in `settings.h` references your project `user_settings.h`. The +`settings.h` should _not_ be edited directly. Any wolfSSL settings should be adjusted in your local project +`user_settings.h` file. + +The `settings.h` has some SoC-target-specific settings, so be sure to `#include "sdkconfig.h"` at the beginning +of your source code, particularly before the `#include ` line. ## Requirements @@ -56,12 +116,16 @@ See the specific examples for additional details. ## Setup for Linux (wolfSSL local copy) +This is a legacy method for installation. It is recommended to use the new `CMakeLists.txt` to point to wolfSSL source code. + 1. Run `setup.sh` at _/path/to_`/wolfssl/IDE/Espressif/ESP-IDF/` to deploy files into ESP-IDF tree 2. Find Wolfssl files at _/path/to/esp_`/esp-idf/components/wolfssl/` 3. Find [Example Programs](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF/examples) under _/path/to/esp_`/esp-idf/examples/protocols/wolfssl_xxx` (where xxx is the project name) ## Setup for Windows +This is a legacy method for installation. It is recommended to use the new `CMakeLists.txt` to point to wolfSSL source code. + 1. Run ESP-IDF Command Prompt (cmd.exe) or Run ESP-IDF PowerShell Environment 2. Run `setup_win.bat` at `.\IDE\Espressif\ESP-IDF\` 3. Find Wolfssl files at _/path/to/esp_`/esp-idf/components/wolfssl/` @@ -69,6 +133,12 @@ See the specific examples for additional details. ## Setup for VisualGDB +See the local project `./VisualGDB` for sample project files. For single-step JTAG debugging on boards that do not +have a built-in JTAG port, the wolfSSL examples use the open source [Tigard board](https://github.com/tigard-tools/tigard#readme). + +See also the [gojimmypi blog](https://gojimmypi.github.io/Tigard-JTAG-SingleStep-Debugging-ESP32/) on using the Tigard +to JTAG debug the ESP32. + ### Clone a specific version: ``` @@ -77,11 +147,15 @@ C:\SysGCC\esp32\esp-idf>git clone -b v5.0.2 --recursive https://github.com/espre ## Configuration + 1. The `user_settings.h` can be found in `[project]/components/wolfssl/include/user_settings.h`. + +## Configuration (Legacy IDF install) + 1. The `user_settings.h` can be found in _/path/to/esp_`/esp-idf/components/wolfssl/include/user_settings.h` ## Build examples - 1. See README in each example folder + 1. See README in each example folder. ## Support @@ -89,13 +163,13 @@ C:\SysGCC\esp32\esp-idf>git clone -b v5.0.2 --recursive https://github.com/espre Note: This is tested with : - OS: Ubuntu 20.04.3 LTS - - Microsoft Windows 10 Pro 10.0.19041 - - WSL Ubuntu + - Microsoft Windows 10 Pro 10.0.19041 / Windows 11 Pro 22H2 22621.2715 + - Visual Studio 2022 17.7.6 with VisualGDB 5.6R9 (build 4777) + - WSL 1 Ubuntu 22.04.3 LTS + - ESP-IDF: ESP-IDF v5.1 + - SoC Module : all those supported in ESP-IDF v5.1 - - ESP-IDF: ESP-IDF v4.3.2 - - Module : ESP32-WROOM-32 - -## JTAG Debugging +## JTAG Debugging Notes All of the examples are configured to use either the on-board JTAG (when available) or the open source [Tigard multi-protocol tool for hardware hacking](https://github.com/tigard-tools/tigard). @@ -105,3 +179,28 @@ VisualGDB users should find the configuration file in the `interface\ftdi` direc ``` C:\Users\%USERNAME%\AppData\Local\VisualGDB\EmbeddedDebugPackages\com.sysprogs.esp32.core\share\openocd\scripts\interface\ftdi ``` + +For reference, the `tigard.cfg` looks like this: + +``` +# SPDX-License-Identifier: GPL-2.0-or-later +# +# Tigard: An FTDI FT2232H-based multi-protocol tool for hardware hacking. +# https://github.com/tigard-tools/tigard + +adapter driver ftdi + +ftdi device_desc "Tigard V1.1" +ftdi vid_pid 0x0403 0x6010 + +ftdi channel 1 + +ftdi layout_init 0x0038 0x003b +ftdi layout_signal nTRST -data 0x0010 +ftdi layout_signal nSRST -data 0x0020 + +# This board doesn't support open-drain reset modes since its output buffer is +# always enabled. +reset_config srst_push_pull trst_push_pull + +``` diff --git a/IDE/Espressif/ESP-IDF/examples/README.md b/IDE/Espressif/ESP-IDF/examples/README.md new file mode 100644 index 000000000..e0414d2fe --- /dev/null +++ b/IDE/Espressif/ESP-IDF/examples/README.md @@ -0,0 +1,120 @@ +# wolfSSL Examples for Espressif + +## Core Examples + +These are the core examples for wolfSSL: + +- [Template](./template/README.md) + +- [Benchmark](./wolfssl_benchmark/README.md) + +- [Test](./wolfssl_test/README.md) + +- [TLS Client](./wolfssl_client/README.md) + +- [TLS Server](./wolfssl_server/README.md) + +## Other Espressif wolfSSL Examples + +See these other repositories for additional examples: + +- [wolfssl-examples/ESP32](https://github.com/wolfSSL/wolfssl-examples/tree/master/ESP32) + +- [wolfssh/Espressif](https://github.com/wolfSSL/wolfssh/tree/master/ide/Espressif) + +- [wolfssh-examples/Espressif](https://github.com/wolfSSL/wolfssh-examples/tree/main/Espressif) + + +## Interaction with wolfSSL CLI + +See the [server](https://github.com/wolfSSL/wolfssl/tree/master/examples/server) +and [client](https://github.com/wolfSSL/wolfssl/tree/master/examples/client) +examples. + +Here are some examples using wolfSSL from Linux to communicate with an +ESP32 TLS client or server: + +TLS1.3 Linux Server +``` +./examples/server/server -v 4 -b -d -p 11111 -c ./certs/server-cert.pem -k ./certs/server-key.pem +``` + +TLS1.3 Linux Client to Linux Server: `TLS_AES_128_GCM_SHA256` (default) +``` +./examples/client/client -v 4 -h 127.0.0.1 -p 11111 -A ./certs/ca-cert.pem +``` + +TLS1.2 Linux Server +``` +./examples/server/server -v 3 -b -d -p 11111 -c ./certs/server-cert.pem -k ./certs/server-key.pem +``` + +TLS1.2 Linux Client to Linux Server: `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` (default) +``` +./examples/client/client -v 3 -h 127.0.0.1 -p 11111 -A ./certs/ca-cert.pem +``` + +TLS1.2 Linux Client to ESP32 Server: `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` +``` +./examples/client/client -v 3 -h 192.168.1.109 -p 11111 -A ./certs/ca-cert.pem +``` + +TLS1.3 Linux Client to ESP32 Server: `TLS_AES_128_GCM_SHA256` +``` +./examples/client/client -v 4 -h 192.168.1.109 -p 11111 -A ./certs/ca-cert.pem +``` + + +There's an additional example that uses wolfSSL installed as a component to the shared ESP-IDF: + +- [Test IDF](./wolfssl_test_idf/README.md) + +## Installing wolfSSL for Espressif projects + +[Core examples](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF/examples) +have a local `components/wolfssl` directory with a special CMakeFile.txt that does not require +wolfSSL to be installed. + +If you want to install wolfSSL, see the setup for [wolfSSL](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF#setup-for-linux) +and [wolfSSH](https://github.com/wolfSSL/wolfssh/tree/master/ide/Espressif#setup-for-linux). + +The [Espressif Managed Component for wolfSSL](https://components.espressif.com/components/wolfssl/wolfssl) +also installs source code locally, instead of pointing to a source repository. + +## VisualGDB + +Users of [VisualGDB](https://visualgdb.com/) can find Espressif project files in each respective +example `.\VisualGDB` directory. For convenience, there are separate project for various +target SoC and ESP-IDF version. + +For devices without a built-in JTAG, the projects are configured with the open source [Tigard](https://www.crowdsupply.com/securinghw/tigard) +and using port `COM20`. + +For devices _with_ a built-in JTAG, the projects are using `COM9`. + +Edit the COM port for your project: + +- ESP-IDF Project; Bootloader COM Port. +- Raw Terminal; COM Port + + +## Troubleshooting + +If unusual errors occur, exit Visual Studio and manually delete these directories to start over: + +- `.\build` +- `.\VisualGDB\.visualgdb` +- `.\VisualGDB\.vs` + +It may be helpful to also delete the `sdkconfig` file. (Save a backup if you've made changes to defaults) + +## Other Topics + +- esp32.com: [RSA peripheral 50% slower on ESP32-S3/C3 than S2](https://www.esp32.com/viewtopic.php?t=23830) + +- esp32.com: [GPIO6,GPIO7,GPIO8,and GPIO9 changed for ESP32-WROOM-32E](https://esp32.com/viewtopic.php?t=29058) + +See also [this ESP-FAQ Handbook](https://docs.espressif.com/projects/esp-faq/en/latest/esp-faq-en-master.pdf). + + + diff --git a/IDE/Espressif/ESP-IDF/examples/template/README.md b/IDE/Espressif/ESP-IDF/examples/template/README.md index bbad2a752..274e22dea 100644 --- a/IDE/Espressif/ESP-IDF/examples/template/README.md +++ b/IDE/Espressif/ESP-IDF/examples/template/README.md @@ -1,6 +1,9 @@ # wolfSSL Template Project -This is an example minimally viable wolfSSL template to get started with your own project. +This is an example of a minimally viable wolfSSL template to get started with your own project. + +For general information on [wolfSSL examples for Espressif](../README.md), see the +[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file. ### Prerequisites @@ -64,4 +67,6 @@ For examples, see: - [wolfssh-examples](https://github.com/wolfSSL/wolfssh-examples/tree/main/Espressif) +See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md). + diff --git a/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark/README.md b/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark/README.md index 198927f2c..7decc9aa4 100644 --- a/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark/README.md +++ b/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark/README.md @@ -2,7 +2,7 @@ This ESP32 example uses the [wolfSSL wolfcrypt Benchmark Application](https://github.com/wolfSSL/wolfssl/tree/master/wolfcrypt/benchmark). -For general information on wolfSSL examples for Espressif, see the +For general information on [wolfSSL examples for Espressif](../README.md), see the [README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file. ## Espressif ESP Component Registry @@ -33,7 +33,7 @@ The naming convention for project files is: `[project name]_IDF_[Version]_[chips -------- |------------- |------------- | -ChipSet | ESP-IDF v4.4 | ESP-IDF v5.0 | +ChipSet | ESP-IDF v4.4 | ESP-IDF v5.1 | -------- |------------- |------------- | ESP32 | x | | ESP32-S2 | | | @@ -84,11 +84,20 @@ git submodule update --init --recursive cd /mnt/c/workspace/wolfssl/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark -# Pick ESP-IDF install directory, this one for v5.0 in VisualGDB -. /mnt/c/SysGCC/esp32/esp-idf/v5.0/export.sh +# Pick ESP-IDF install directory, this one for v5.1 in VisualGDB -idf.py set-target ESP32C3 +WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.1 +WRK_IDF_PATH=/mnt/c/SysGCC/esp32-8.4/esp-idf/v4.4.1 +WRK_IDF_PATH=~/esp/esp-idf +. $WRK_IDF_PATH/export.sh + +# Set target SoC +idf.py set-target esp32c3 + +# Optionally erase + +# Build and flash idf.py build flash -p /dev/ttyS20 -b 115200 monitor ``` @@ -245,3 +254,5 @@ A 'clean` may be needed after freshly installing a new component: ``` idf.py clean build flash -p /dev/ttyS7 -b 115200 monitor ``` + +See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md). diff --git a/IDE/Espressif/ESP-IDF/examples/wolfssl_client/README.md b/IDE/Espressif/ESP-IDF/examples/wolfssl_client/README.md index b89cbfe4b..21855add8 100644 --- a/IDE/Espressif/ESP-IDF/examples/wolfssl_client/README.md +++ b/IDE/Espressif/ESP-IDF/examples/wolfssl_client/README.md @@ -1,6 +1,12 @@ -#wolfSSL Example +# wolfSSL TLS Client Example -The Example contains of wolfSSL tls client demo. +This is the wolfSSL TLS Client demo, typically used with the [Espressif TLS Server](../wolfssl_server/README.md) +or the CLI [Server](https://github.com/wolfSSL/wolfssl/tree/master/examples/server). + +When using the CLI, see the [example parameters](/IDE/Espressif/ESP-IDF/examples#interaction-with-wolfssl-cli). + +For general information on [wolfSSL examples for Espressif](../README.md), see the +[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file. ## VisualGDB @@ -39,14 +45,14 @@ When you want to test the wolfSSL client Command: ``` -cd /mnt/c/workspace/wolfssl-gojimmypi/IDE/Espressif/ESP-IDF/examples/wolfssl_server +cd /mnt/c/workspace/wolfssl-$USER/IDE/Espressif/ESP-IDF/examples/wolfssl_server . /mnt/c/SysGCC/esp32/esp-idf/v5.1/export.sh idf.py flash -p /dev/ttyS19 -b 115200 monitor ``` ``` -cd /mnt/c/workspace/wolfssl-gojimmypi +cd /mnt/c/workspace/wolfssl-$USER ./examples/client/client -h 192.168.1.108 -v 4 -l TLS_SM4_GCM_SM3 -c ./certs/sm2/client-sm2.pem -k ./certs/sm2/client-sm2-priv.pem -A ./certs/sm2/root-sm2.pem -C ``` @@ -68,5 +74,5 @@ I hear you fa shizzle! ./examples/server/server -v 3 -l ECDHE-ECDSA-SM4-CBC-SM3 -c ./certs/sm2/server-sm2.pem -k ./certs/sm2/server-sm2-priv.pem -A ./certs/sm2/client-sm2.pem -V ``` -See the README.md file in the upper level 'examples' directory for more information about examples. +See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md). diff --git a/IDE/Espressif/ESP-IDF/examples/wolfssl_server/README.md b/IDE/Espressif/ESP-IDF/examples/wolfssl_server/README.md index 7d8d0d127..3380c0f2d 100644 --- a/IDE/Espressif/ESP-IDF/examples/wolfssl_server/README.md +++ b/IDE/Espressif/ESP-IDF/examples/wolfssl_server/README.md @@ -1,5 +1,12 @@ -# wolfSSL Server Example +# wolfSSL TLS Server Example +This is the wolfSSL TLS Server demo, typically used with the [Espressif TLS Client](../wolfssl_client/README.md) +or the CLI [Client](https://github.com/wolfSSL/wolfssl/tree/master/examples/client). + +When using the CLI, see the [example parameters](/IDE/Espressif/ESP-IDF/examples#interaction-with-wolfssl-cli). + +For general information on [wolfSSL examples for Espressif](../README.md), see the +[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file. ## VisualGDB @@ -10,7 +17,7 @@ No wolfSSL setup is needed. You may need to adjust your specific COM port. The d The Example contains a wolfSSL simple server. -1. `idf.py menuconfigure` to configure the project +1. `idf.py menuconfig` to configure the project 1-1. Example Connection Configuration -> @@ -33,7 +40,7 @@ See the README.md file in the upper level 'examples' directory for more informat ``` # . /mnt/c/SysGCC/esp32/esp-idf/master/export.sh . /mnt/c/SysGCC/esp32/esp-idf/v5.1/export.sh -cd /mnt/c/workspace/wolfssl-gojimmypi/IDE/Espressif/ESP-IDF/examples/wolfssl_server +cd /mnt/c/workspace/wolfssl-$USER/IDE/Espressif/ESP-IDF/examples/wolfssl_server # optionally erase idf.py erase-flash -p /dev/ttyS19 -b 115200 @@ -46,7 +53,7 @@ idf.py flash -p /dev/ttyS19 -b 115200 monitor Linux Client to x108 SM server ``` -cd /mnt/c/workspace/wolfssl-gojimmypi +cd /mnt/c/workspace/wolfssl-$USER # show the ciphers ./examples/client/client -e @@ -100,3 +107,5 @@ ECDHE-RSA-CHACHA20-POLY1305-OLD: ECDHE-ECDSA-CHACHA20-POLY1305-OLD: DHE-RSA-CHACHA20-POLY1305-OLD: ``` + +See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md). diff --git a/IDE/Espressif/ESP-IDF/examples/wolfssl_test/README.md b/IDE/Espressif/ESP-IDF/examples/wolfssl_test/README.md index 993d56fcc..e4e79dce8 100644 --- a/IDE/Espressif/ESP-IDF/examples/wolfssl_test/README.md +++ b/IDE/Espressif/ESP-IDF/examples/wolfssl_test/README.md @@ -2,7 +2,8 @@ This is the ESP32 Version of the [wolfSSL wolfcrypt test application](https://github.com/wolfSSL/wolfssl/tree/master/wolfcrypt/test). - +For general information on [wolfSSL examples for Espressif](../README.md), see the +[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file. ## ESP Registry @@ -18,7 +19,7 @@ idf.py -b 115200 flash monitor ## VisualGDB -Open the VisualGDB Visual Studio Project file in the [VisualGDB directory]() and click the "Start" button. +Open the VisualGDB Visual Studio Project file in the [VisualGDB directory](./VisualGDB/README.md) and click the "Start" button. No wolfSSL setup is needed. You may need to adjust your specific COM port. The default is `COM20`. ## ESP-IDF Commandline @@ -170,3 +171,5 @@ I (136548) wolfcrypt_test: Exiting main with return code: 0 I (136548) wolfssl_test: wolf_test_task complete success result code = 0 ``` + +See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md). diff --git a/IDE/Espressif/README.md b/IDE/Espressif/README.md new file mode 100644 index 000000000..dea3b36a3 --- /dev/null +++ b/IDE/Espressif/README.md @@ -0,0 +1,161 @@ + + +# wolfSSL Espressif IDE + +This directory contains documentation and examples for the Espressif SoC devices. + +Although wolfSSL _should_ work on any Espressif device, there's explicit support for these: + +- esp32 +- esp32c2 +- esp32c3 +- esp32c6 +- esp32s2 +- esp32s3 +- esp32h2 + + +## Getting Started + +If you are new to wolfSSL on the Espressif ESP32, [this video](https://www.youtube.com/watch?v=CzwA3ZBZBZ8) +can help to get started: + +[![Video Preview](https://img.youtube.com/vi/CzwA3ZBZBZ8/0.jpg)](https://www.youtube.com/watch?v=CzwA3ZBZBZ8) + +Additional ESP-IDF specifics can be found in [Espressif/ESP-IDF](./ESP-IDF/README.md). The [wolfSSL Manual](https://www.wolfssl.com/documentation/manuals/wolfssl/index.html) is also a useful +resource. + +## Requirements + +The wolfSSL Espressif code requires the ESP-IDF to be installed for +[Windows](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-setup.html) +or [Linux / MacOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html). + +See the [Espressif Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/). + +Any editor can be used. See also the [Espressif Third-Party Tools](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/resources.html) +for a list of feature-rich Integrated Development Environments. +The [wolfSSL examples](./ESP-IDF/examples/README.md) all include a `./VisualGDB` directory with SoC-specific configurations +to help get started quickly. + +Although not required, a [JTAG Adapter](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html) +can be helpful for development. When not using a built-in JTAG from Espressif, the examples typically +use the open source [Tigard board](https://github.com/tigard-tools/tigard#readme). + +## Examples: + +There are a variety of examples to help get started: + +* [ESP-IDF Examples](./ESP-IDF/README.md) + +## Managed Component + +The wolfSSL library can be installed as a managed component: + +* [Espressif Managed Component Registry](https://components.espressif.com/components/wolfssl/wolfssl) + +## Notes: + +WSL environment: + +Contents of `/etc/wsl.conf`: +```text +[automount] +options = "metadata" +``` + +To ignore changes in file attributes, see https://github.com/microsoft/WSL/issues/936#issuecomment-1751469229 + +``` +git config core.filemode false +``` + + +Quick start +``` + +WORKSPACE=/mnt/c/workspace +WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.1 +WRK_WOLFSSL_PATH=${WORKSPACE}/wolfssl-$USER +WRK_PROJECT_DIR=${WRK_WOLFSSL_PATH}/IDE/Espressif/ESP-IDF/examples/wolfssl_test + +echo "Run export.sh from ${WRK_IDF_PATH}" +. ${WRK_IDF_PATH}/export.sh + +echo "Build and flash project in ${WRK_PROJECT_DIR}" +cd ${WRK_PROJECT_DIR} +idf.py build flash -p /dev/ttyS9 -b 115200 monitor +``` + +Bad chip version: + +``` +ESP-ROM:esp32c3-20200918 +Build:Sep 18 2020 +rst:0x3 (RTC_SW_SYS_RST),boot:0xc (SPI_FAST_FLASH_BOOT) +Saved PC:0x403d151e +SPIWP:0xee +mode:DIO, clock div:2 +load:0x3fcd6100,len:0x16c8 +load:0x403ce000,len:0x930 +load:0x403d0000,len:0x2d28 +entry 0x403ce000 +I (34) boot: ESP-IDF v4.4.2-1-g0aba20e63d-dirty 2nd stage bootloader +I (35) boot: compile time 08:29:06 +I (35) boot: chip revision: 2 +E (38) boot_comm: This chip is revision 2 but the application is configured for minimum revision 3. Can't run. +``` + +If you've encountered a chip version earlier than that confirmed to be working +at wolfSSL, try adjusting the settings in `menuconfig`. + +#### A fatal error occurred: This chip is esp[X] not esp[Y] + +``` +A fatal error occurred: This chip is ESP32-S3 not ESP32-C3. Wrong --chip argument? +CMake Error at run_serial_tool.cmake:56 (message): + /home/gojimmypi/.espressif/python_env/idf4.4_py3.8_env/bin/python + /mnt/c/SysGCC/esp32/esp-idf/v4.4.2/components/esptool_py/esptool/esptool.py + --chip esp32c3 failed +``` + +Delete the `./build` and rename/delete your `sdkconfig` file, then run +`idf.py set-target`, in this example setting to `esp32c3`: + +```bash +idf.py set-target esp32c3 +``` + +#### Cmake Cache Warning + +``` +Executing action: clean +Project sdkconfig was generated for target 'esp32s3', but CMakeCache.txt contains 'esp32c3'. To keep the setting in sdkconfig (esp32s3) and re-generate CMakeCache.txt, run 'idf.py fullclean'. To re-generate sdkconfig for 'esp32c3' target, run 'idf.py set-target esp32c3'. +``` + +As indicated, run `idf.py set-target` and/or delete the `./build` directory. + +#### Connecting, but fails to connect. + +Some devices, particularly 3rd party, non-Espressif dev boards may not have implemented +the reset-program hardware properly, causing devices to not be programmed with the +`idf.py flash` command: + +``` +Connecting...................................... + +A fatal error occurred: Failed to connect to ESP32: Wrong boot mode detected (0x13)! The chip needs to be in download mode. +For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html +CMake Error at run_serial_tool.cmake:56 (message): + /home/gojimmypi/.espressif/python_env/idf4.4_py3.8_env/bin/python + /mnt/c/SysGCC/esp32/esp-idf/v4.4.2/components/esptool_py/esptool/esptool.py + --chip esp32 failed +``` + +Solution: + +Press and hold`EN` button, press and release `IO0` button, then release `EN` button. + +#### Other Solutions + +See also [this ESP-FAQ Handbook](https://docs.espressif.com/projects/esp-faq/en/latest/esp-faq-en-master.pdf)