#wifi #bluetooth #esp #networking #udp-socket #log-level #tcp-socket

nightly no-std esp-wifi

A WiFi, Bluetooth and ESP-NOW driver for use with Espressif chips and bare-metal Rust

6 releases (breaking)

0.4.0 Mar 12, 2024
0.3.0 Jan 29, 2024
0.2.0 Jan 5, 2024
0.1.1 Nov 27, 2023
0.0.1 Nov 1, 2023

#104 in Embedded development

Download history 99/week @ 2023-12-22 123/week @ 2023-12-29 300/week @ 2024-01-05 150/week @ 2024-01-12 126/week @ 2024-01-19 210/week @ 2024-01-26 136/week @ 2024-02-02 222/week @ 2024-02-09 321/week @ 2024-02-16 263/week @ 2024-02-23 256/week @ 2024-03-01 432/week @ 2024-03-08 270/week @ 2024-03-15 221/week @ 2024-03-22 286/week @ 2024-03-29 197/week @ 2024-04-05

1,023 downloads per month

MIT/Apache

80MB
88K SLoC

Rust 77K SLoC // 0.0% comments Alex 11K 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"]

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 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.2-602-gdb1e54a0c5-dirty commit db1e54a0c537d8b2cc2bd109ee88b50e1ca0ea80

https://github.com/esp-rs/esp-wireless-drivers-3rdparty/ (commit ca2809144cf6d2f89d413f1d415f1c4454ee6249)

License

Licensed under either of:

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–19MB
~377K SLoC