wolfssl-w32/IDE/Espressif/ESP-IDF/README.md

207 lines
8.1 KiB
Markdown
Raw Normal View History

# ESP-IDF Port
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).
See the latest [Espressif Migration Guides](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html).
## Examples
Included are the following [examples](./examples/README.md):
* 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)
## 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 <esp_log.h>
#include "sdkconfig.h"
/* wolfSSL */
#include <wolfssl/wolfcrypt/settings.h> /* references user_settings.h */
/* Do not explicitly include wolfSSL user_settings.h */
#include <wolfssl/version.h>
#include <wolfssl/wolfcrypt/port/Espressif/esp32-crypt.h>
```
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 <wolfssl/wolfcrypt/settings.h>` line.
## Requirements
1. [ESP-IDF development framework](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/)
## wolfSSL as an Espressif component
There are various methods available for using wolfSSL as a component:
* Managed Component - easiest to get started.
* Local component directory - best for development.
* Install locally - least flexible, but project is fully self-contained.
## Espressif Managed Components
Visit https://components.espressif.com/components/wolfssl/wolfssl and see the instructions. Typically:
```
idf.py add-dependency "wolfssl/wolfssl^5.6.0-stable"
```
## Standard local component:
See the [template example](./examples/template/README.md). Simply created a `wolfssl` directory in the
local project `components` directory and place the [CMakeLists.txt](./examples/template/components/CMakeLists.txt)
file there. Then add a `components/wolfssl/include` directory and place the [user_settings.h](/examples/template/components/wolfssl/include/user_settings.h)
file there. If wolfSSL is in a structure such as `./workspace/wolfssl` with respect to your project at `./workspace/wolfssl`,
then the cmake file should automatically find the wolfSSL source code. Otherwise set the cmake `WOLFSSL_ROOT` variable
in the top-level CMake file. Examples:
```cmake
set(WOLFSSL_ROOT "C:/some-path/wolfssl")
set(WOLFSSL_ROOT "c:/workspace/wolfssl-[username]")
set(WOLFSSL_ROOT "/mnt/c/somepath/wolfssl")
```
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/`
4. 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 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:
```
C:\SysGCC\esp32\esp-idf>git clone -b v5.0.2 --recursive https://github.com/espressif/esp-idf.git v5.0.2
```
## 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.
## Support
For question please email [support@wolfssl.com]
Note: This is tested with :
- OS: Ubuntu 20.04.3 LTS
- 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
## 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).
VisualGDB users should find the configuration file in the `interface\ftdi` directory:
```
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
```