mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
117 lines
5.0 KiB
Markdown
117 lines
5.0 KiB
Markdown
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
|
|
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |
|
|
|
|
# ESP Local Control using HTTPS server
|
|
|
|
This example creates a `esp_local_ctrl` service over HTTPS transport, for securely controlling the device over local network. In this case the device name is resolved through `mDNS`, which in this example is `my_esp_ctrl_device.local`.
|
|
|
|
See the `esp_local_ctrl` component documentation for details.
|
|
|
|
Before using the example, run `idf.py menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details.
|
|
|
|
Note, that this example in not supported for IPv6-only configuration.
|
|
|
|
## Client Side Implementation
|
|
|
|
A python test script `scripts/esp_local_ctrl.py` has been provided for as a client side application for controlling the device over the same Wi-Fi network. The script relies on a pre-generated `main/certs/rootCA.pem` to verify the server certificate. The server side private key and certificate can also be found under `main/certs`, namely `prvtkey.pem` and `cacert.pem`.
|
|
|
|
After configuring the Wi-Fi, flashing and booting the device, run the following command to test the device name
|
|
resolution through mDNS:
|
|
|
|
```
|
|
ping my_esp_ctrl_device.local
|
|
```
|
|
|
|
Sample output:
|
|
|
|
```
|
|
64 bytes from 192.168.32.156 (192.168.32.156): icmp_seq=1 ttl=255 time=58.1 ms
|
|
64 bytes from 192.168.32.156 (192.168.32.156): icmp_seq=2 ttl=255 time=89.9 ms
|
|
64 bytes from 192.168.32.156 (192.168.32.156): icmp_seq=3 ttl=255 time=123 ms
|
|
```
|
|
|
|
After you've tested the name resolution, run:
|
|
|
|
```
|
|
python scripts/esp_local_ctrl.py --sec_ver 2 --sec2_username wifiprov --sec2_pwd abcd1234
|
|
```
|
|
Sample output:
|
|
|
|
```
|
|
python scripts/esp_local_ctrl.py --sec_ver 2 --sec2_username wifiprov --sec2_pwd abcd1234
|
|
|
|
++++ Connecting to my_esp_ctrl_device.local++++
|
|
|
|
==== Starting Session ====
|
|
==== Session Established ====
|
|
|
|
==== Available Properties ====
|
|
S.N. Name Type Flags Value
|
|
[ 1] timestamp (us) TIME(us) Read-Only 168561481
|
|
[ 2] property1 INT32 123456
|
|
[ 3] property2 BOOLEAN Read-Only True
|
|
[ 4] property3 STRING
|
|
|
|
Select properties to set (0 to re-read, 'q' to quit) : 0
|
|
|
|
==== Available Properties ====
|
|
S.N. Name Type Flags Value
|
|
[ 1] timestamp (us) TIME(us) Read-Only 22380117
|
|
[ 2] property1 INT32 123456
|
|
[ 3] property2 BOOLEAN Read-Only False
|
|
[ 4] property3 STRING
|
|
|
|
Select properties to set (0 to re-read, 'q' to quit) : 2,4
|
|
Enter value to set for property (property1) : -5555
|
|
Enter value to set for property (property3) : hello world!
|
|
|
|
==== Available Properties ====
|
|
S.N. Name Type Flags Value
|
|
[ 1] timestamp (us) TIME(us) Read-Only 55110859
|
|
[ 2] property1 INT32 -5555
|
|
[ 3] property2 BOOLEAN Read-Only False
|
|
[ 4] property3 STRING hello world!
|
|
|
|
Select properties to set (0 to re-read, 'q' to quit) : q
|
|
Quitting...
|
|
```
|
|
|
|
The script also allows to connect over plain HTTP or BLE, and provide a custom service name. To display the list of supported parameters, run:
|
|
|
|
```
|
|
python scripts/esp_local_ctrl.py --help
|
|
```
|
|
|
|
**Note:** To use plain HTTP transport, disable the config option `CONFIG_ESP_HTTPS_SERVER_ENABLE`.
|
|
|
|
## Certificates
|
|
|
|
You can generate a new server certificate using the OpenSSL command line tool.
|
|
|
|
For the purpose of this example, lets generate a rootCA, which we will use to sign the server certificates and which the client will use to verify the server certificate during SSL handshake. You will need to set a password for encrypting the generated `rootkey.pem`.
|
|
|
|
```
|
|
openssl req -new -x509 -subj "/CN=root" -days 3650 -sha256 -out rootCA.pem -keyout rootkey.pem
|
|
```
|
|
|
|
Now generate a certificate signing request for the server, along with its private key `prvtkey.pem`.
|
|
|
|
```
|
|
openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -days 3650 -out server.csr -subj "/CN=my_esp_ctrl_device.local"
|
|
```
|
|
|
|
Now use the previously generated rootCA to process the server's certificate signing request, and generate a signed certificate `cacert.pem`. The password set for encrypting `rootkey.pem` earlier, has to be entered during this step.
|
|
|
|
```
|
|
openssl x509 -req -in server.csr -CA rootCA.pem -CAkey rootkey.pem -CAcreateserial -out cacert.pem -days 500 -sha256
|
|
```
|
|
|
|
Now that we have `rootCA.pem`, `cacert.pem` and `prvtkey.pem`, copy these into main/certs. Note that only the server related files (`cacert.pem` and `prvtkey.pem`) are embedded into the firmware.
|
|
|
|
Expiry time and metadata fields can be adjusted in the invocation.
|
|
|
|
Please see the `openssl` man pages (man `openssl-req`) for more details.
|
|
|
|
It is **strongly recommended** to not reuse the example certificate in your application;
|
|
it is included only for demonstration.
|