Crate esp_csi_rs

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 deveices are:

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

In terms of 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 no-std ESP development projects. 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 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. Also you should activate either the defmt or println feature for console printing.

• no-std (enabled by default) — Build without the standard library.
• defmt — Enable logging via defmt.
• println — Enable logging via println!() instead of defmt.
• 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. When both devices are ESPs, the Access Point and the Station are able to collect CSI data.

Additionally, to regularly recieve CSI data, there needs to be regular traffic on the network. The traffic needs to be generated by the crate. Traffic could be a simple ICMP ping or a UDP packet. ICMP is lightweight but carries no data. Alternatively, if desired, UDP can carry data. Currently the crate supports only ICMP and UDP. While access points will naturally respond to ICMP pings, currently UDP traffic is simply ignored.

Example for Collecting CSI in Station Mode

There are more examples in the repository. This example 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:

• Option 1: Connect to an existing commercial router
• Option 2: Connect to another ESP programmed in AP Mode or AP/STA Mode

The SSID and Password defined is for the Access Point or Router the ESP Station will be connecting to.

Step 1: Create a CSI Collection Configuration/Profile

 let csi_collector = CSICollector::new(
     WiFiConfig {
         ssid: "AP_SSID".try_into().unwrap(),
         password: "AP_PASSWORD".try_into().unwrap(),
         ..Default::default()
     },
     esp_csi_rs::WiFiMode::Station,
     CSIConfig::default(),
     TrafficConfig {
         traffic_type: TrafficType::UDP,
         // Ex. Send traffic every one second
         traffic_interval_ms: 1000,
     },
     // Enable traffic
     true,
     // Define architecture deployed
     NetworkArchitechture::RouterStation,
 );

Step 2: Initialize CSI Collection

csi_collector.init(wifi, init, seed, &spawner).unwrap();

Step 3: Start Collection

 // Starts Collection for 10 seconds then stops
csi_collector.start(10).await;

Upon building and running the project, CSI data will appear in the serial monitor window

Modules

config

Structs

CSICollector

Main Driver Struct for CSI Collection

IpInfo

Enums

NetworkArchitechture

Network Architechture Options

WiFiMode

Device operation modes