Fix README.md include (esp-rs#359)

* Fix README.md include * Fix links
bjoernQ · May 24, 2024 · f0cc90d · f0cc90d
1 parent 01a918b
commit f0cc90d
Show file tree

Hide file tree

Showing 5 changed files with 355 additions and 2 deletions.
diff --git a/esp-wifi/Cargo.toml b/esp-wifi/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "esp-wifi"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 authors = [
     "The ESP-RS team",

diff --git a/esp-wifi/README.md b/esp-wifi/README.md
@@ -0,0 +1,151 @@
+# esp-wifi
+
+A WiFi, BLE and ESP-NOW driver for Espressif microcontrollers.
+
+## Current support
+
+If a cell contains am em dash (&mdash;) this means that the particular feature is not present for a chip. A check mark (✓) means that some driver implementation exists. A Tilde (&tilde;) means its implemented but buggy. An empty cell means that the feature is present in the chip but not implemented yet.
+
+|          | [Wifi](https://github.com/esp-rs/esp-wifi/issues/94) | [BLE](https://github.com/esp-rs/esp-wifi/issues/93) | [Coex](https://github.com/esp-rs/esp-wifi/issues/92) | ESP-NOW |
+| :------: | :--------------------------------------------------: | :-------------------------------------------------: | :--------------------------------------------------: | :-----: |
+|  ESP32   |                          ✓                           |                          ✓                          |                       &tilde;                        |    ✓    |
+| ESP32-S2 |                          ✓                           |                       &mdash;                       |                       &mdash;                        |    ✓    |
+| ESP32-S3 |                          ✓                           |                          ✓                          |                          ✓                           |    ✓    |
+| ESP32-C3 |                          ✓                           |                          ✓                          |                          ✓                           |    ✓    |
+| ESP32-C2 |                          ✓                           |                          ✓                          |                          ✓                           |    ✓    |
+| ESP32-C6 |                          ✓                           |                          ✓                          |                          ✓                           |    ✓    |
+
+Minimum supported Rust compiler version: 1.72.0.0
+
+## Usage
+
+### Importing
+
+Ensure that the right features are enabled for your chip. See [Examples] for more examples.
+
+```toml
+[dependencies.esp-wifi]
+# A supported chip needs to be specified, as well as specific use-case features
+features = ["esp32s3", "wifi", "esp-now"]
+```
+
+### Link configuration
+
+Make sure to include the rom functions for your target:
+
+```toml
+# .cargo/config.toml
+rustflags = [
+    "-C", "link-arg=-Tlinkall.x",
+    "-C", "link-arg=-Trom_functions.x",
+]
+```
+At time of writing, you will already have the linkall flag if you used `cargo generate`. Generating from a template does not include the `rom_functions` flag.
+
+
+### Optimization Level
+
+Link time optimization is not yet recommended for use, please ensure `lto = "off"` is in your `Cargo.toml` for both release and debug profiles.
+
+It is necessary to build with optimization level 2 or 3 since otherwise it might not even be able to connect or advertise.
+
+To make it work also for your debug builds add this to your `Cargo.toml`
+
+```toml
+[profile.dev.package.esp-wifi]
+opt-level = 3
+
+[profile.dev]
+lto = "off"
+[profile.release]
+lto = "off"
+
+```
+
+### Xtensa considerations
+
+Within this crate, `CCOMPARE0` CPU timer is used for timing, ensure that in your application you are not using this CPU timer.
+
+## USB-SERIAL-JTAG
+
+When using USB-SERIAL-JTAG you have to activate the feature `phy-enable-usb`.
+
+Don't use this feature if your are _not_ using USB-SERIAL-JTAG since it might reduce WiFi performance.
+
+## Features
+
+| Feature        | Meaning                                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| wifi-logs      | logs the WiFi logs from the driver at log level info                                                 |
+| dump-packets   | dumps packet info at log level info                                                                  |
+| utils          | Provide utilities for smoltcp initialization; adds `smoltcp` dependency                              |
+| embedded-svc   | Provides a (very limited) implementation of the `embedded-svc` WiFi trait                            |        
+| ble            | Enable BLE support                                                                                   |
+| wifi           | Enable WiFi support                                                                                  |
+| esp-now        | Enable esp-now support                                                                               |
+| coex           | Enable coex support                                                                                  |
+| big-heap       | Reserve more heap memory for the drivers                                                             |
+| ipv4           | IPv4 support: includes `utils` feature                                                               |
+| ipv6           | IPv6 support: includes `utils` feature                                                               |
+| tcp            | TCP socket support: includes `ipv4` feature                                                          |
+| udp            | UDP socket support: includes `ipv4` feature                                                          |
+| igmp           | IGMP (multicast) support: includes `ipv4` feature                                                    |
+| dns            | DNS support: includes `udp` feature                                                                  |
+| dhcpv4         | DHCPv4 support, both creating sockets and autoconfiguring network settings: includes `utils` feature |
+| phy-enable-usb | See _USB-SERIAL-JTAG_ below                                                                          |
+| ps-min-modem   | Enable minimum modem sleep. Only for STA mode                                                        |
+| ps-max-modem   | Enable maximum modem sleep. Only for STA mode                                                        |
+| log            | Route log output to the `log` crate                                                                  |
+| defmt          | Add `defmt::Format` implementation                                                                   |
+
+When using the `dump-packets` feature you can use the extcap in `extras/esp-wifishark` to analyze the frames in Wireshark.
+For more information see [extras/esp-wifishark/README.md](extras/esp-wifishark/README.md)
+
+## Tuning
+
+The defaults used by `esp-wifi` and the examples are rather conservative. It is possible to change a few of the important settings.
+
+See [Tuning](https://github.com/esp-rs/esp-wifi/esp-wifi/blob/main/docs/tuning.md) for details
+
+## Examples
+
+See [Examples] for details.
+
+[Examples]: https://github.com/esp-rs/esp-wifi/esp-wifi/blob/main/docs/examples.md
+
+## Missing / To be done
+
+- Make CoEx work on ESP32 (it kind of works when commenting out setting the country in wifi_start, probably some mis-compilation since it then crashes in a totally different code path)
+- Support for non-open SoftAP
+
+## Directory Structure
+
+- `src/timer/`: systimer code used for timing and task switching
+- `src/preemt/`: a bare minimum RISCV and Xtensa round-robin task scheduler
+- `src/compat/`: code needed to emulate enough of an (RT)OS to use the driver
+  - `common.rs`: basics like semaphores and recursive mutexes
+  - `timer_compat.rs`: code to emulate timer related functionality
+- `examples/*.rs`: examples
+
+## Driver version
+
+This uses the WiFi drivers from https://github.com/esp-rs/esp-wireless-drivers-3rdparty
+
+v5.1-rc2-4-gc570f67461 commit c570f674610479fc5e070c8db6d181b73ddf60a8
+
+https://github.com/esp-rs/esp-wireless-drivers-3rdparty/ (commit 976e9cc6c0725e8325a7e3a362d113559238c45c)
+
+## License
+
+Licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
+any additional terms or conditions.
diff --git a/esp-wifi/docs/examples.md b/esp-wifi/docs/examples.md
@@ -0,0 +1,145 @@
+## Examples
+
+ > The following instructions assume you have the [Xtensa toolchain](https://esp-rs.github.io/book/installation/riscv-and-xtensa.html) set up. In case you are building for a RISC-V target and would use
+the mainline Rust compiler, you'll need to edit or remove the `rust-toolchain.toml` file.
+
+To build these ensure you are in the `esp-wifi` directory (the inner one, which has `examples` inside) and you are using the right chip name invocation. For example, to build for the `esp32c3`, please run 
+
+```
+cargo esp32c3 --release ...
+```
+
+### dhcp
+
+- set SSID and PASSWORD env variable
+- gets an ip address via DHCP
+- performs an HTTP get request to some "random" server
+
+`cargo $CHIP --example dhcp --release --features "embedded-svc,wifi"`
+
+### static_ip
+
+- set SSID and PASSWORD env variable
+- set STATIC_IP and GATEWAY_IP env variable (e.g. "192.168.2.191" / "192.168.2.1")
+- might be necessary to configure your WiFi access point accordingly
+- uses the given static IP
+- responds with some HTML content when connecting to port 8080
+
+`cargo $CHIP --example static_ip --release --features "embedded-svc,wifi"`
+
+### ble
+
+- starts Bluetooth advertising
+- offers one service with three characteristics (one is read/write, one is write only, one is read/write/notify)
+- pressing the boot-button on a dev-board will send a notification if it is subscribed
+- this uses a toy level BLE stack - might not work with every BLE central device (tested with Android and Windows Bluetooth LE Explorer)
+
+`cargo $CHIP --example ble --release --features "ble"`
+
+**NOTE:** ESP32-S2 doesn't support bluetooth
+
+### embassy_ble
+
+- same as `ble` but async
+
+`cargo $CHIP --example embassy_ble --release --features "async,ble"`
+
+**NOTE:** ESP32-S2 doesn't support bluetooth
+
+### coex
+
+- set SSID and PASSWORD env variable
+- gets an ip address via DHCP
+- performs an HTTP get request to some "random" server
+- does BLE advertising
+- coex support is still somewhat flaky
+
+`cargo $CHIP --example coex --release --features "embedded-svc,wifi,ble"`
+
+**NOTE:** Not currently available for the ESP32, ESP32-C2, ESP32-C6 or ESP32-S2
+
+### esp_now
+
+- broadcasts, receives and sends messages via esp-now
+
+`cargo $CHIP --example esp_now --release --features "esp-now"`
+
+### embassy_esp_now
+
+- broadcasts, receives and sends messages via esp-now in an async way
+
+`cargo $CHIP --example embassy_esp_now --release --features "async,esp-now"`
+
+### embassy_esp_now_duplex
+
+- asynchronously broadcasts, receives and sends messages via esp-now in multiple embassy tasks
+
+`cargo $CHIP --example embassy_esp_now_duplex --release --features "async,esp-now"`
+
+### embassy_dhcp
+
+- Read and Write to sockets over WiFi asyncronously using embassy-executor.
+
+`cargo $CHIP --example embassy_dhcp --release --features "async,embedded-svc,wifi,embassy-net"`
+
+### access_point
+
+- creates an open access-point with SSID `esp-wifi`
+- you can connect to it using a static IP in range 192.168.2.2 .. 192.168.2.255, gateway 192.168.2.1
+- open http://192.168.2.1:8080/ in your browser
+- on Android you might need to choose _Keep Accesspoint_ when it tells you the WiFi has no internet connection, Chrome might not want to load the URL - you can use a shell and try `curl` and `ping`
+
+`cargo $CHIP --example access_point --release --features "embedded-svc,wifi"`
+
+### access_point_with_sta
+
+- set SSID and PASSWORD env variable
+- gets an ip address via DHCP
+- creates an open access-point with SSID `esp-wifi`
+- you can connect to it using a static IP in range 192.168.2.2 .. 192.168.2.255, gateway 192.168.2.1
+- open http://192.168.2.1:8080/ in your browser - the example will perform an HTTP get request to some "random" server
+- on Android you might need to choose _Keep Accesspoint_ when it tells you the WiFi has no internet connection, Chrome might not want to load the URL - you can use a shell and try `curl` and `ping`
+
+`cargo $CHIP --example access_point_with_sta --release --features "embedded-svc,wifi"`
+
+### embassy_access_point
+
+- creates an open access-point with SSID `esp-wifi`
+- you can connect to it using a static IP in range 192.168.2.2 .. 192.168.2.255, gateway 192.168.2.1
+- open http://192.168.2.1:8080/ in your browser
+- on Android you might need to choose _Keep Accesspoint_ when it tells you the WiFi has no internet connection, Chrome might not want to load the URL - you can use a shell and try `curl` and `ping`
+
+`cargo $CHIP --example embassy_access_point --release --features "async,embedded-svc,wifi,embassy-net"`
+
+### embassy_access_point_with_sta
+
+- set SSID and PASSWORD env variable
+- gets an ip address via DHCP
+- creates an open access-point with SSID `esp-wifi`
+- you can connect to it using a static IP in range 192.168.2.2 .. 192.168.2.255, gateway 192.168.2.1
+- open http://192.168.2.1:8080/ in your browser - the example will perform an HTTP get request to some "random" server
+- on Android you might need to choose _Keep Accesspoint_ when it tells you the WiFi has no internet connection, Chrome might not want to load the URL - you can use a shell and try `curl` and `ping`
+
+`cargo $CHIP --example embassy_access_point_with_sta --release --features "async,embedded-svc,wifi,embassy-net"`
+
+## Benchmarking
+
+A prerequisite to running the benchmark examples is to run the benchmark server on your local machine. Simply run the following commands to do so.
+
+```
+cd extras/bench-server
+cargo run --release
+```
+
+### bench
+
+- Run a test of download, upload and download+upload in a blocking fashion.
+- Ensure you have set the IP of your local machine in the `HOST_IP` env variable. E.g `HOST_IP="192.168.0.24"`
+
+`cargo $CHIP --example bench --release --features "wifi"`
+
+### embassy_bench
+
+- Run a test of download, upload and download+upload in a async fashion.
+
+`cargo $CHIP --example embassy_bench --release --features "wifi,embassy-net"`
diff --git a/esp-wifi/docs/tuning.md b/esp-wifi/docs/tuning.md
@@ -0,0 +1,57 @@
+# Tuning the configuration
+
+You can change a few of the default settings used. Please keep in mind that it's almost always a tradeoff between memory usage and performance.
+It's easy to decrease performance by using unfortunate settings or even break the application or making it less stable.
+
+So you should test every change very carefully.
+
+Be aware that settings which work fine on one ESP32 model might not work at all on other. Also, settings should be adjusted according to your application's needs.
+
+## Create a configuration
+
+We use [toml-cfg](https://crates.io/crates/toml-cfg) for the build time configuration
+
+You need to add a `cfg.toml` file in the root of your binary crate. When using a _Cargo Workspace_ you should put the file in the root of the workspace directory.
+
+A configuration file can look like this:
+```toml
+[esp-wifi]
+rx_queue_size = 15
+tx_queue_size = 3
+static_rx_buf_num = 10
+dynamic_rx_buf_num = 16
+ampdu_rx_enable = 0
+ampdu_tx_enable = 0
+rx_ba_win = 32
+max_burst_size = 6
+```
+
+You can set the following settings
+|Key|Description|
+|-|-|
+|rx_queue_size|Size of the RX queue in frames|
+|tx_queue_size|Size of the TX queue in frames|
+|max_burst_size|See [documentation](https://docs.rs/smoltcp/0.10.0/smoltcp/phy/struct.DeviceCapabilities.html#structfield.max_burst_size)|
+|static_rx_buf_num|WiFi static RX buffer number. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|dynamic_rx_buf_num|WiFi dynamic RX buffer number. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|static_tx_buf_num|WiFi static TX buffer number. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|dynamic_tx_buf_num|WiFi dynamic TX buffer number. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|ampdu_rx_enable|WiFi AMPDU RX feature enable flag. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|ampdu_rx_enable|WiFi AMPDU RX feature enable flag. (0 or 1) See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|ampdu_tx_enable|WiFi AMPDU TX feature enable flag. (0 or 1) See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|amsdu_tx_enable|WiFi AMSDU TX feature enable flag. (0 or 1) See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|rx_ba_win|WiFi Block Ack RX window size. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv418wifi_init_config_t)|
+|country_code|Country code. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/wifi.html#wi-fi-country-code)|
+|country_code_operating_class|If not 0: Operating Class table number. See [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/wifi.html#wi-fi-country-code)|
+|mtu|MTU, see [documentation](https://docs.rs/smoltcp/0.10.0/smoltcp/phy/struct.DeviceCapabilities.html#structfield.max_transmission_unit)|
+|heap_size|Size of the WiFi/BLE heap in bytes|
+|tick_rate_hz|Tick rate of the internal task scheduler in hertz.|
+|listen_interval|Interval for station to listen to beacon from AP. The unit of listen interval is one beacon interval. For example, if beacon interval is 100 ms and listen interval is 3, the interval for station to listen to beacon is 300 ms|
+|beacon_timeout|For Station, If the station does not receive a beacon frame from the connected SoftAP during the  inactive time, disconnect from SoftAP. Default 6s. Range 6-30|
+|ap_beacon_timeout|For SoftAP, If the SoftAP doesn’t receive any data from the connected STA during inactive time, the SoftAP will force deauth the STA. Default is 300s.|
+|failure_retry_cnt|Number of connection retries station will do before moving to next AP. scan_method should be set as WIFI_ALL_CHANNEL_SCAN to use this config. Note: Enabling this may cause connection time to increase incase best AP doesn't behave properly. Defaults to 1|
+|scan_method|0 = WIFI_FAST_SCAN, 1 = WIFI_ALL_CHANNEL_SCAN, defaults to 0|
+
+## Globally disable logging
+
+`esp-wifi` contains a lot of trace-level logging statements. For maximum performance you might want to disable logging via a feature flag of the `log` crate. See [documentation](https://docs.rs/log/0.4.19/log/#compile-time-filters). You should set it to `release_max_level_off`
diff --git a/esp-wifi/src/lib.rs b/esp-wifi/src/lib.rs
@@ -4,7 +4,7 @@
 #![feature(linkage)]
 #![cfg_attr(feature = "async", feature(async_fn_in_trait))]
 #![cfg_attr(feature = "async", allow(incomplete_features))]
-#![doc = include_str!("../../README.md")]
+#![doc = include_str!("../README.md")]
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 // MUST be the first module