Skip to content

Commit 38eddd7

Browse files
JacobBarthelmehJacobBarthelmeh
authored
Merge pull request #7043 from gojimmypi/PR-Espressif-README
Espressif README files
2 parents 0c9555b + 17c663b commit 38eddd7

8 files changed

Lines changed: 450 additions & 36 deletions

File tree

‎IDE/Espressif/ESP-IDF/README.md‎

Lines changed: 118 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,81 @@
1-
# ESP-IDF port
1+
# ESP-IDF Port
22

3-
NOTICE: These Espressif examples have been created and tested with the latest stable release branch of
4-
[ESP-IDF V4](https://docs.espressif.com/projects/esp-idf/en/v4.4.1/esp32/get-started/index.html)
5-
and have not yet been upgraded to the master branch V5.
6-
See the latest [migration guides](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html).
3+
These Espressif examples have been created and tested with the latest stable release branch of
4+
[ESP-IDF V5.1](https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32/get-started/index.html).
5+
The prior version 4.4 ESP-IDF is still supported, however version 5.1 or greater is recommended.
6+
Espressif has [a list of all ESP-IDF versions](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html).
77

8-
## Overview
8+
See the latest [Espressif Migration Guides](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html).
99

10-
ESP-IDF development framework with wolfSSL by setting *WOLFSSL_ESPIDF* definition
10+
## Examples
1111

12-
Including the following examples:
12+
Included are the following [examples](./examples/README.md):
1313

14-
* Simple [TLS client](./examples/wolfssl_client/)/[server](./examples/wolfssl_server/)
15-
* Cryptographic [test](./examples/wolfssl_test/)
16-
* Cryptographic [benchmark](./examples/wolfssl_benchmark/)
14+
* Bare-bones [Template](./examples/template/README.md)
15+
* Simple [TLS Client](./examples/wolfssl_client/README.md) / [TLS Server](./examples/wolfssl_server/README.md)
16+
* Cryptographic [Test](./examples/wolfssl_test/README.md)
17+
* Cryptographic [Benchmark](./examples/wolfssl_benchmark/README.md)
1718

18-
The *user_settings.h* file enables some of the hardened settings.
19+
## Important Usage Details
20+
21+
The wolfSSL code specific to the Espressif ESP-IDF development framework
22+
is gated in code with the `WOLFSSL_ESPIDF` definition. This is enabled
23+
automatically when the `WOLFSSL_USER_SETTINGS` is defined. The recommended
24+
method is to have this line in the main `CMakeLists.txt` file as shown in the
25+
[example](./examples/template/main/CMakeLists.txt):
26+
27+
```cmake
28+
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DWOLFSSL_USER_SETTINGS")
29+
```
30+
31+
When defining `WOLFSSL_USER_SETTINGS`, this tells the `settings.h` file to
32+
looks for the wolfSSL `user_settings.h` in the project as described below.
33+
34+
### File: `sdkconfig.h`
35+
36+
The Espressif `sdkconfig.h`, generated automatically from your `sdkconfig`
37+
file at [build](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html)
38+
time, should be included before any other files.
39+
40+
### File: `user_settings.h`
41+
42+
The `user_settings.h` file enables some of the hardened security settings. There are also some
43+
default configuration items in the wolfssl `settings.h`. With the latest version of
44+
wolfSSL, some of these defaults can be disabled with `NO_ESPIDF_DEFAULT` and customized
45+
in your project `user_settings.h` as desired.
46+
47+
See the respective project directory:
48+
49+
`[project-dir]/components/wolfssl/user_settings.h`
50+
51+
A typical project will _not_ directly reference the `user_settings.h` file.
52+
Here's an example to be included at the top of a given source file:
53+
54+
```c
55+
/* ESP-IDF */
56+
#include <esp_log.h>
57+
#include "sdkconfig.h"
58+
59+
/* wolfSSL */
60+
#include <wolfssl/wolfcrypt/settings.h> /* references user_settings.h */
61+
/* Do not explicitly include wolfSSL user_settings.h */
62+
#include <wolfssl/version.h>
63+
#include <wolfssl/wolfcrypt/port/Espressif/esp32-crypt.h>
64+
```
65+
66+
Prior versions of the wolfSSL Espressif library expected the `user_settings.h` to be in the root wolfssl folder in a directory
67+
called `/include`. This method, while possible, is no longer recommended.
68+
69+
Be sure to *not* have a `user_settings.h` in _both_ the local project and the wolfssl `include` directories.
70+
71+
### File: `wolfssl/wolfcrypt/settings.h`
72+
73+
The wolfSSL built-in `settings.h` references your project `user_settings.h`. The
74+
`settings.h` should _not_ be edited directly. Any wolfSSL settings should be adjusted in your local project
75+
`user_settings.h` file.
76+
77+
The `settings.h` has some SoC-target-specific settings, so be sure to `#include "sdkconfig.h"` at the beginning
78+
of your source code, particularly before the `#include <wolfssl/wolfcrypt/settings.h>` line.
1979

2080
## Requirements
2181

@@ -56,19 +116,29 @@ See the specific examples for additional details.
56116

57117
## Setup for Linux (wolfSSL local copy)
58118

119+
This is a legacy method for installation. It is recommended to use the new `CMakeLists.txt` to point to wolfSSL source code.
120+
59121
1. Run `setup.sh` at _/path/to_`/wolfssl/IDE/Espressif/ESP-IDF/` to deploy files into ESP-IDF tree
60122
2. Find Wolfssl files at _/path/to/esp_`/esp-idf/components/wolfssl/`
61123
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)
62124

63125
## Setup for Windows
64126

127+
This is a legacy method for installation. It is recommended to use the new `CMakeLists.txt` to point to wolfSSL source code.
128+
65129
1. Run ESP-IDF Command Prompt (cmd.exe) or Run ESP-IDF PowerShell Environment
66130
2. Run `setup_win.bat` at `.\IDE\Espressif\ESP-IDF\`
67131
3. Find Wolfssl files at _/path/to/esp_`/esp-idf/components/wolfssl/`
68132
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)
69133

70134
## Setup for VisualGDB
71135

136+
See the local project `./VisualGDB` for sample project files. For single-step JTAG debugging on boards that do not
137+
have a built-in JTAG port, the wolfSSL examples use the open source [Tigard board](https://github.com/tigard-tools/tigard#readme).
138+
139+
See also the [gojimmypi blog](https://gojimmypi.github.io/Tigard-JTAG-SingleStep-Debugging-ESP32/) on using the Tigard
140+
to JTAG debug the ESP32.
141+
72142
### Clone a specific version:
73143

74144
```
@@ -77,25 +147,29 @@ C:\SysGCC\esp32\esp-idf>git clone -b v5.0.2 --recursive https://github.com/espre
77147

78148
## Configuration
79149

150+
1. The `user_settings.h` can be found in `[project]/components/wolfssl/include/user_settings.h`.
151+
152+
## Configuration (Legacy IDF install)
153+
80154
1. The `user_settings.h` can be found in _/path/to/esp_`/esp-idf/components/wolfssl/include/user_settings.h`
81155

82156
## Build examples
83157

84-
1. See README in each example folder
158+
1. See README in each example folder.
85159

86160
## Support
87161

88162
For question please email [support@wolfssl.com]
89163

90164
Note: This is tested with :
91165
- OS: Ubuntu 20.04.3 LTS
92-
- Microsoft Windows 10 Pro 10.0.19041
93-
- WSL Ubuntu
166+
- Microsoft Windows 10 Pro 10.0.19041 / Windows 11 Pro 22H2 22621.2715
167+
- Visual Studio 2022 17.7.6 with VisualGDB 5.6R9 (build 4777)
168+
- WSL 1 Ubuntu 22.04.3 LTS
169+
- ESP-IDF: ESP-IDF v5.1
170+
- SoC Module : all those supported in ESP-IDF v5.1
94171

95-
- ESP-IDF: ESP-IDF v4.3.2
96-
- Module : ESP32-WROOM-32
97-
98-
## JTAG Debugging
172+
## JTAG Debugging Notes
99173

100174
All of the examples are configured to use either the on-board JTAG (when available) or
101175
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
105179
```
106180
C:\Users\%USERNAME%\AppData\Local\VisualGDB\EmbeddedDebugPackages\com.sysprogs.esp32.core\share\openocd\scripts\interface\ftdi
107181
```
182+
183+
For reference, the `tigard.cfg` looks like this:
184+
185+
```
186+
# SPDX-License-Identifier: GPL-2.0-or-later
187+
#
188+
# Tigard: An FTDI FT2232H-based multi-protocol tool for hardware hacking.
189+
# https://github.com/tigard-tools/tigard
190+
191+
adapter driver ftdi
192+
193+
ftdi device_desc "Tigard V1.1"
194+
ftdi vid_pid 0x0403 0x6010
195+
196+
ftdi channel 1
197+
198+
ftdi layout_init 0x0038 0x003b
199+
ftdi layout_signal nTRST -data 0x0010
200+
ftdi layout_signal nSRST -data 0x0020
201+
202+
# This board doesn't support open-drain reset modes since its output buffer is
203+
# always enabled.
204+
reset_config srst_push_pull trst_push_pull
205+
206+
```

‎IDE/Espressif/ESP-IDF/examples/README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# wolfSSL Examples for Espressif
2+
3+
## Core Examples
4+
5+
These are the core examples for wolfSSL:
6+
7+
- [Template](./template/README.md)
8+
9+
- [Benchmark](./wolfssl_benchmark/README.md)
10+
11+
- [Test](./wolfssl_test/README.md)
12+
13+
- [TLS Client](./wolfssl_client/README.md)
14+
15+
- [TLS Server](./wolfssl_server/README.md)
16+
17+
## Other Espressif wolfSSL Examples
18+
19+
See these other repositories for additional examples:
20+
21+
- [wolfssl-examples/ESP32](https://github.com/wolfSSL/wolfssl-examples/tree/master/ESP32)
22+
23+
- [wolfssh/Espressif](https://github.com/wolfSSL/wolfssh/tree/master/ide/Espressif)
24+
25+
- [wolfssh-examples/Espressif](https://github.com/wolfSSL/wolfssh-examples/tree/main/Espressif)
26+
27+
28+
## Interaction with wolfSSL CLI
29+
30+
See the [server](https://github.com/wolfSSL/wolfssl/tree/master/examples/server)
31+
and [client](https://github.com/wolfSSL/wolfssl/tree/master/examples/client)
32+
examples.
33+
34+
Here are some examples using wolfSSL from Linux to communicate with an
35+
ESP32 TLS client or server:
36+
37+
TLS1.3 Linux Server
38+
```
39+
./examples/server/server -v 4 -b -d -p 11111 -c ./certs/server-cert.pem -k ./certs/server-key.pem
40+
```
41+
42+
TLS1.3 Linux Client to Linux Server: `TLS_AES_128_GCM_SHA256` (default)
43+
```
44+
./examples/client/client -v 4 -h 127.0.0.1 -p 11111 -A ./certs/ca-cert.pem
45+
```
46+
47+
TLS1.2 Linux Server
48+
```
49+
./examples/server/server -v 3 -b -d -p 11111 -c ./certs/server-cert.pem -k ./certs/server-key.pem
50+
```
51+
52+
TLS1.2 Linux Client to Linux Server: `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` (default)
53+
```
54+
./examples/client/client -v 3 -h 127.0.0.1 -p 11111 -A ./certs/ca-cert.pem
55+
```
56+
57+
TLS1.2 Linux Client to ESP32 Server: `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
58+
```
59+
./examples/client/client -v 3 -h 192.168.1.109 -p 11111 -A ./certs/ca-cert.pem
60+
```
61+
62+
TLS1.3 Linux Client to ESP32 Server: `TLS_AES_128_GCM_SHA256`
63+
```
64+
./examples/client/client -v 4 -h 192.168.1.109 -p 11111 -A ./certs/ca-cert.pem
65+
```
66+
67+
68+
There's an additional example that uses wolfSSL installed as a component to the shared ESP-IDF:
69+
70+
- [Test IDF](./wolfssl_test_idf/README.md)
71+
72+
## Installing wolfSSL for Espressif projects
73+
74+
[Core examples](https://github.com/wolfSSL/wolfssl/tree/master/IDE/Espressif/ESP-IDF/examples)
75+
have a local `components/wolfssl` directory with a special CMakeFile.txt that does not require
76+
wolfSSL to be installed.
77+
78+
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)
79+
and [wolfSSH](https://github.com/wolfSSL/wolfssh/tree/master/ide/Espressif#setup-for-linux).
80+
81+
The [Espressif Managed Component for wolfSSL](https://components.espressif.com/components/wolfssl/wolfssl)
82+
also installs source code locally, instead of pointing to a source repository.
83+
84+
## VisualGDB
85+
86+
Users of [VisualGDB](https://visualgdb.com/) can find Espressif project files in each respective
87+
example `.\VisualGDB` directory. For convenience, there are separate project for various
88+
target SoC and ESP-IDF version.
89+
90+
For devices without a built-in JTAG, the projects are configured with the open source [Tigard](https://www.crowdsupply.com/securinghw/tigard)
91+
and using port `COM20`.
92+
93+
For devices _with_ a built-in JTAG, the projects are using `COM9`.
94+
95+
Edit the COM port for your project:
96+
97+
- ESP-IDF Project; Bootloader COM Port.
98+
- Raw Terminal; COM Port
99+
100+
101+
## Troubleshooting
102+
103+
If unusual errors occur, exit Visual Studio and manually delete these directories to start over:
104+
105+
- `.\build`
106+
- `.\VisualGDB\.visualgdb`
107+
- `.\VisualGDB\.vs`
108+
109+
It may be helpful to also delete the `sdkconfig` file. (Save a backup if you've made changes to defaults)
110+
111+
## Other Topics
112+
113+
- esp32.com: [RSA peripheral 50% slower on ESP32-S3/C3 than S2](https://www.esp32.com/viewtopic.php?t=23830)
114+
115+
- esp32.com: [GPIO6,GPIO7,GPIO8,and GPIO9 changed for ESP32-WROOM-32E](https://esp32.com/viewtopic.php?t=29058)
116+
117+
See also [this ESP-FAQ Handbook](https://docs.espressif.com/projects/esp-faq/en/latest/esp-faq-en-master.pdf).
118+
119+
120+

‎IDE/Espressif/ESP-IDF/examples/template/README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# wolfSSL Template Project
22

3-
This is an example minimally viable wolfSSL template to get started with your own project.
3+
This is an example of a minimally viable wolfSSL template to get started with your own project.
4+
5+
For general information on [wolfSSL examples for Espressif](../README.md), see the
6+
[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file.
47

58
### Prerequisites
69

@@ -64,4 +67,6 @@ For examples, see:
6467
- [wolfssh-examples](https://github.com/wolfSSL/wolfssh-examples/tree/main/Espressif)
6568

6669

70+
See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md).
71+
6772

‎IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark/README.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This ESP32 example uses the [wolfSSL wolfcrypt Benchmark Application](https://github.com/wolfSSL/wolfssl/tree/master/wolfcrypt/benchmark).
44

5-
For general information on wolfSSL examples for Espressif, see the
5+
For general information on [wolfSSL examples for Espressif](../README.md), see the
66
[README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md) file.
77

88
## Espressif ESP Component Registry
@@ -33,7 +33,7 @@ The naming convention for project files is: `[project name]_IDF_[Version]_[chips
3333

3434

3535
-------- |------------- |------------- |
36-
ChipSet | ESP-IDF v4.4 | ESP-IDF v5.0 |
36+
ChipSet | ESP-IDF v4.4 | ESP-IDF v5.1 |
3737
-------- |------------- |------------- |
3838
ESP32 | x | |
3939
ESP32-S2 | | |
@@ -84,11 +84,20 @@ git submodule update --init --recursive
8484
8585
cd /mnt/c/workspace/wolfssl/IDE/Espressif/ESP-IDF/examples/wolfssl_benchmark
8686
87-
# Pick ESP-IDF install directory, this one for v5.0 in VisualGDB
88-
. /mnt/c/SysGCC/esp32/esp-idf/v5.0/export.sh
87+
# Pick ESP-IDF install directory, this one for v5.1 in VisualGDB
8988
90-
idf.py set-target ESP32C3
89+
WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.1
90+
WRK_IDF_PATH=/mnt/c/SysGCC/esp32-8.4/esp-idf/v4.4.1
91+
WRK_IDF_PATH=~/esp/esp-idf
9192
93+
. $WRK_IDF_PATH/export.sh
94+
95+
# Set target SoC
96+
idf.py set-target esp32c3
97+
98+
# Optionally erase
99+
100+
# Build and flash
92101
idf.py build flash -p /dev/ttyS20 -b 115200 monitor
93102
```
94103

@@ -245,3 +254,5 @@ A 'clean` may be needed after freshly installing a new component:
245254
```
246255
idf.py clean build flash -p /dev/ttyS7 -b 115200 monitor
247256
```
257+
258+
See the README.md file in the upper level 'examples' directory for [more information about examples](../README.md).

0 commit comments

Comments
 (0)