Crate esp_csi_rs

Crate esp_csi_rs 

Source
Expand description

§A crate for CSI collection on ESP devices

§Overview

This crate builds on the low level Espressif abstractions to enable the collection of Channel State Information (CSI) on ESP devices with ease. Currently this crate supports only the ESP no-std development framework.

§Choosing a device

In terms of hardware, you need to make sure that the device you choose supports WiFi and CSI collection. Currently supported devices include:

  • ESP32
  • ESP32-C2
  • ESP32-C3
  • ESP32-C6
  • ESP32-S3

In terms of project and software toolchain setup, you will need to specify the hardware you will be using. To minimize headache, it is recommended that you generate a project using esp-generate as explained next.

§Creating a project

To use this crate you would need to create and setup a project for your ESP device then import the crate. This crate is compatible with the no-std ESP development framework. You should also select the corresponding device by activating it in the crate features.

To create a projects it is highly recommended to refer the to instructions in The Rust on ESP Book before proceeding. The book explains the full esp-rs ecosystem, how to get started, and how to generate projects for both std and no-std.

Espressif has developed a project generation tool, esp-generate, to ease this process and is recommended for new projects. As an example, you can create a no-std project for the ESP32-C3 device as follows:

cargo install esp-generate
esp-generate --chip=esp32c3 [project-name]

§Feature Flags

⚠️ At minimum you are required to choose only ONE of the device options. For the most efficient (and fastest) logging, you should combine defmt with the jtag-serial features.

  • no-std (enabled by default) — Build without the standard library.
  • defmt — Enable logging via defmt.
  • println (enabled by default) — Enable logging via println!() instead of defmt.
  • jtag-serial — Enable the JTAG serial interface for logging. Only supported by ESP32-C3, ESP32-C6, and ESP32-S3.
  • auto (enabled by default) — Automaically select the logging interface based on the target (Ex. UART).
  • esp32 — Support for the ESP32
  • esp32c2 — Support for the ESP32-C2
  • esp32c3 — Support for the ESP32-C3
  • esp32c6 — Support for the ESP32-C6 (WiFi 6)
  • esp32s3 — Support for the ESP32-S3 (AIoT)

§Using the esp-csi-rs Crate

With the exception of sniffer mode, the collection of CSI requires at least two WiFi enabled devices; an Access Point and a Station. Both devices could be ESP devices one programmed as a Station and another as an Access Point. Alternatively, the simplest setup is using one ESP device as a Station connecting to an existing Access Point like a home router. This crate supports creating both Access Points and Stations and there are several examples to demonstrate in the repository. The sections below describes in more detail the collector types and operation modes.

§Collector Types

§Sniffer

A sniffer collects CSI data for all observed channel traffic.

§Station

In the esp-csi-rs the station is the CSI reciever. CSI at the station is stimulated by traffic generated locally or from an external source. A station can have one connection that is either another ESP access point or a commercial router.

§Access Point & Access Point + Station

AP and AP/STA modes do not collect CSI locally, they are merely CSI collection enablers for stations. They rely on connected stations to capture CSI data. APs and AP/STAs, however, can operate as external traffic generators for connected stations. The CSI collected at the stations is then propagated back through a UDP message to the trigger source (AP or AP/STA). The AP/STA mode is useful only if an internet connection to sync NTP is required.

§Operation Modes

To recieve CSI data, there needs to be regular traffic on the network. This is enabled by setting an operation mode. Access points and Stations have two operation modes to select from; Trigger and Monitor. Sniffers do not require this since they “sniff” existing traffic on the channel.

§Trigger Mode

In this mode, the ESP is configured to generate ICMP traffic at a desired rate. When an AP ESP is configured as a trigger then it would generate ICMP Echo Request broadcasts at a defined rate. The AP in turn, recieves the CSI collected at the destination tagged with the request sequence number. When a Station ESP is configured as a trigger then it would generate ICMP traffic with the Access Point its connected to at a defined rate.

§Monitor Mode

In this mode, the ESP is configured to monitor any incoming traffic. When an AP is configured as a monitor then it simply responds to dummy traffic to stimulate CSI at the traffic generation source. When a Station is configured as a monitor then it monitors incoming ICMP Echo Request traffic stimulating CSI generation and sends back the collected CSI to the trigger source with the sequence number tagged.

Note: ESP AP and Station connecting pairs should always have oppsing modes. Meaning if the AP is configured as a trigger then the Station needs to be a monitor and vice versa. When connecting a station to a commercial router then only trigger mode works since there is no control over the router.

§External Trigger Data Formatting

If sending an external trigger, the returned UDP message is formatted as follows:

[0..1] : 2 bytes for sequence number (u16) - big endian

[2] : 1 byte for CSI data format (Refer to the RxCSIFmt enum for details)

[3..6] : 4 bytes for capture timestamp (u32) - big endian

[7..12] : 6 bytes for MAC address of the station

[13..n] : Up to 612 bytes of raw CSI data (i8)

§Collecting & Processing CSI Data

There are two ways to collect CSI data using esp-csi-rs:

  • Process a CSIDataPacket: The get_csi_data() method returns a CSIDataPacket struct that contains all the captured CSI and its metadata. This data can be processed locally, stored to a file, or even sent to a storage device (Ex. SD Card).
  • Print to console: CSIDataPacket offers a print_csi_w_metadata method that formats and prints the CSI data to the console. This data can then be stored and processed by a host device.

§Example for Collecting CSI with Station Trigger

There are more examples in the repository. The example below demonstrates how to collect CSI data with an ESP configured in Station mode.

This configuration allows the collection of CSI data by connecting to a WiFi router or ESP Access Point. Connection Options include:

  • Option 1: Connect to an existing commercial router
  • Option 2: Connect to another ESP programmed in AP Mode or AP/STA Mode
§Step 1: Create a CSI Collection Configuration/Profile
let mut csi_coll_sta = CSIStation::new(
    CSIConfig::default(),
    ClientConfiguration {
        ssid: "esp".into(),
        password: "12345678".into(),
        auth_method: esp_wifi::wifi::AuthMethod::WPA2Personal,
        channel: Some(1),
        ..Default::default()
    },
    // Configure the traffic frequency to 1 Hz (1 packets per second)
    StaOperationMode::Trigger(StaTriggerConfig { trigger_freq_hz: 1 }),
    // Don't retrieve NTP time
    false,
    controller,
)
.await;
§Step 2: Initialize CSI Collection
csi_coll_sta.init(interfaces, &spawner).await.unwrap();
§Step 3: Start Collection
csi_collector.start_collection();
§Step 4: Print CSI Data to Console for a Certain Amount of Time
with_timeout(Duration::from_secs(5), async {
   loop {
       csi_coll_sta.print_csi_w_metadata().await;
   }
})
.await
.unwrap_err();
§Step 5: Stop Collection
csi_collector.stop_collection();

Alternatively you can use the get_cs_data abstraction that returns a CSIDataPacket type that provides access to the raw data.

Modules§

collector
config
error

Structs§

CSIDataPacket
CSI Received Packet w/ Radio Metadata
DateTime

Enums§

RxCSIFmt
A mapping of the different possible recieved CSI data formats supported by the Espressif WiFi driver. `RxCSIFmt`` encodes the different formats (each column in the table) in one byte to save space when transmitting back CSI data. The driver can be found here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/wifi.html#wi-fi-channel-state-information

Functions§

days_in_month
days_in_year
get_sntp_time
is_leap_year
net_task
process_csi_packet
unix_to_date_time