8 releases (5 breaking)
new 0.5.1 | Apr 22, 2024 |
---|---|
0.5.0 | Apr 19, 2024 |
0.4.0 | Mar 12, 2024 |
0.3.0 | Jan 29, 2024 |
0.0.1 | Nov 1, 2023 |
#116 in Embedded development
1,498 downloads per month
80MB
88K
SLoC
esp-wifi
A WiFi, BLE and ESP-NOW driver for Espressif microcontrollers.
Current support
If a cell contains an em dash (—) this means that the particular feature is not present for a chip. A check mark (✓) means that some driver implementation exists. A Tilde (˜) means it is implemented but buggy. An empty cell means that the feature is present in the chip but not implemented yet.
Wifi | BLE | Coex | ESP-NOW | |
---|---|---|---|---|
ESP32 | ✓ | ✓ | ✓ | ✓ |
ESP32-C2 | ✓ | ✓ | ✓ | ✓ |
ESP32-C3 | ✓ | ✓ | ✓ | ✓ |
ESP32-C6 | ✓ | ✓ | ✓ | ✓ |
ESP32-H2 | — | ✓ | — | — |
ESP32-S2 | ✓ | — | — | ✓ |
ESP32-S3 | ✓ | ✓ | ✓ | ✓ |
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.
[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:
# .cargo/config.toml
rustflags = [
"-C", "link-arg=-Tlinkall.x",
"-C", "link-arg=-Trom_functions.x",
]
At the 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
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
[profile.dev.package.esp-wifi]
opt-level = 3
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 (for example by selecting jtag-serial
in esp-println
) you have to activate the feature phy-enable-usb
.
Don't use this feature if you are not using USB-SERIAL-JTAG as it might reduce WiFi performance.
Features
Feature | Meaning |
---|---|
wifi-logs | logs the WiFi logs from the driver at log level info |
wifi-default | A convenience feature to enable some reasonable defaults for wifi use. |
dump-packets | dumps packet info at log level info |
smoltcp | Provide implementations of smoltcp traits |
utils | Provide utilities for smoltcp initialization. Adds smoltcp dependency |
ble | Enable BLE support |
wifi | Enable WiFi support |
esp-now | Enable esp-now support |
coex | Enable WiFi-BLE coexistence support |
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 above |
ps-min-modem | Enable minimum modem sleep. Only affects STA mode |
ps-max-modem | Enable maximum modem sleep. Only affects STA mode |
log | Route log output to the log crate |
defmt | Add defmt::Format implementation and output logs via defmt |
embedded-svc | Implement the embedded-svc Wifi trait |
Note that not all features are available on every MCU. For example, ble
(and thus, coex
) is not available on ESP32-S2.
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
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 for details
Examples
See Examples for details.
Missing / To be done
- Support for non-open SoftAP
Directory Structure
src/timer/
: systimer code used for timing and task switchingsrc/preemt/
: a bare minimum RISCV and Xtensa round-robin task schedulersrc/compat/
: code needed to emulate enough of an (RT)OS to use the drivercommon.rs
: basics like semaphores and recursive mutexestimer_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.2-602-gdb1e54a0c5-dirty commit db1e54a0c537d8b2cc2bd109ee88b50e1ca0ea80
https://github.com/esp-rs/esp-wireless-drivers-3rdparty/ (commit ca2809144cf6d2f89d413f1d415f1c4454ee6249)
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (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.
Dependencies
~8–18MB
~361K SLoC