Merge branch 'doc/wifi_channel_state_information' into 'master'

add document of channel state information

See merge request idf/esp-idf!2468
This commit is contained in:
Jiang Jiang Jian 2018-06-04 17:59:05 +08:00
commit 8a4c9d7dfb
3 changed files with 98 additions and 42 deletions

View File

@ -981,7 +981,7 @@ esp_err_t esp_wifi_80211_tx(wifi_interface_t ifx, const void *buffer, int len, b
* Each time a CSI data is received, the callback function will be called.
*
* @param ctx context argument, passed to esp_wifi_set_csi_rx_cb() when registering callback function.
* @param data CSI data received.
* @param data CSI data received. The memory that it points to will be deallocated after callback function returns.
*
*/
typedef void (* wifi_csi_cb_t)(void *ctx, wifi_csi_info_t *data);

View File

@ -97,8 +97,8 @@ typedef enum {
typedef enum {
WIFI_SECOND_CHAN_NONE = 0, /**< the channel width is HT20 */
WIFI_SECOND_CHAN_ABOVE, /**< the channel width is HT40 and the second channel is above the primary channel */
WIFI_SECOND_CHAN_BELOW, /**< the channel width is HT40 and the second channel is below the primary channel */
WIFI_SECOND_CHAN_ABOVE, /**< the channel width is HT40 and the secondary channel is above the primary channel */
WIFI_SECOND_CHAN_BELOW, /**< the channel width is HT40 and the secondary channel is below the primary channel */
} wifi_second_chan_t;
typedef enum {
@ -155,7 +155,7 @@ typedef struct {
uint8_t bssid[6]; /**< MAC address of AP */
uint8_t ssid[33]; /**< SSID of AP */
uint8_t primary; /**< channel of AP */
wifi_second_chan_t second; /**< second channel of AP */
wifi_second_chan_t second; /**< secondary channel of AP */
int8_t rssi; /**< signal strength of AP */
wifi_auth_mode_t authmode; /**< authmode of AP */
wifi_cipher_type_t pairwise_cipher; /**< pairwise cipher of AP */
@ -304,33 +304,33 @@ typedef struct {
/** @brief Received packet radio metadata header, this is the common header at the beginning of all promiscuous mode RX callback buffers */
typedef struct {
signed rssi:8; /**< signal intensity of packet */
unsigned rate:5; /**< data rate */
unsigned :1; /**< reserve */
unsigned sig_mode:2; /**< 0:is not 11n packet; 1:is 11n packet */
unsigned :16; /**< reserve */
unsigned mcs:7; /**< if is 11n packet, shows the modulation(range from 0 to 76) */
unsigned cwb:1; /**< if is 11n packet, shows if is HT40 packet or not */
unsigned :16; /**< reserve */
unsigned smoothing:1; /**< reserve */
unsigned not_sounding:1; /**< reserve */
unsigned :1; /**< reserve */
unsigned aggregation:1; /**< Aggregation */
unsigned stbc:2; /**< STBC */
unsigned fec_coding:1; /**< Flag is set for 11n packets which are LDPC */
unsigned sgi:1; /**< SGI */
signed noise_floor:8; /**< noise floor */
unsigned ampdu_cnt:8; /**< ampdu cnt */
unsigned channel:4; /**< which primary channel this packet in */
unsigned second_channel:4;/**< which second channel this packet in */
unsigned :8; /**< reserve */
unsigned timestamp:32; /**< timestamp, unit: microsecond */
unsigned :32; /**< reserve */
unsigned :31; /**< reserve */
unsigned ant:1; /**< antenna number from which this packet is received */
unsigned sig_len:12; /**< length of packet */
unsigned :12; /**< reserve */
unsigned rx_state:8; /**< rx state */
signed rssi:8; /**< Received Signal Strength Indicator(RSSI) of packet. unit: dBm */
unsigned rate:5; /**< PHY rate encoding of the packet. Only valid for non HT(11bg) packet */
unsigned :1; /**< reserve */
unsigned sig_mode:2; /**< 0: non HT(11bg) packet; 1: HT(11n) packet; 3: VHT(11ac) packet */
unsigned :16; /**< reserve */
unsigned mcs:7; /**< Modulation Coding Scheme. If is HT(11n) packet, shows the modulation, range from 0 to 76(MSC0 ~ MCS76) */
unsigned cwb:1; /**< if is HT(11n) packet, shows if is HT40 packet or HT20 packet. 1: HT40 packet; 0: HT20 packet */
unsigned :16; /**< reserve */
unsigned smoothing:1; /**< reserve */
unsigned not_sounding:1; /**< reserve */
unsigned :1; /**< reserve */
unsigned aggregation:1; /**< Aggregation. 0: MPDU packet; 1: AMPDU packet */
unsigned stbc:2; /**< Space Time Block Code(STBC). 0: non STBC packet; 1: STBC packet */
unsigned fec_coding:1; /**< Flag is set for 11n packets which are LDPC */
unsigned sgi:1; /**< Short Guide Interval(SGI). 0: Long GI; 1: Short GI */
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: 0.25dBm*/
unsigned ampdu_cnt:8; /**< ampdu cnt */
unsigned channel:4; /**< primary channel on which this packet is received */
unsigned secondary_channel:4; /**< secondary channel on which this packet is received. 0: none; 1: above; 2: below */
unsigned :8; /**< reserve */
unsigned timestamp:32; /**< timestamp. The local time when this packet is received. It is precise only if modem sleep or light sleep is not enabled. unit: microsecond */
unsigned :32; /**< reserve */
unsigned :31; /**< reserve */
unsigned ant:1; /**< antenna number from which this packet is received. 0: WiFi antenna 0; 1: WiFi antenna 1 */
unsigned sig_len:12; /**< length of packet including Frame Check Sequence(FCS) */
unsigned :12; /**< reserve */
unsigned rx_state:8; /**< state of the packet. 0: no error; others: error numbers which are not public */
} wifi_pkt_rx_ctrl_t;
/** @brief Payload passed to 'buf' parameter of promiscuous mode RX callback.
@ -387,10 +387,10 @@ typedef struct {
*
*/
typedef struct {
bool lltf_en; /**< enable to receive legacy long training field(lltf) data */
bool htltf_en; /**< enable to receive HT long training field(htltf) data */
bool stbcltf2_en; /**< enable to receive space time block code long training field(stbcltf2) data */
bool manu_scale; /**< manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the shift bits. false: automatically. true: manually */
bool lltf_en; /**< enable to receive legacy long training field(lltf) data. Default enabled */
bool htltf_en; /**< enable to receive HT long training field(htltf) data. Default enabled */
bool stbc_htltf2_en; /**< enable to receive space time block code HT long training field(stbc-htltf2) data. Default enabled */
bool manu_scale; /**< manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the shift bits. false: automatically. true: manually. Default false */
uint8_t shift; /**< manually left shift bits of the scale of the CSI data. The range of the left shift bits is 0~15 */
} wifi_csi_config_t;

View File

@ -11,16 +11,18 @@ Important Notes
ESP32 Wi-Fi Feature List
-------------------------
- Supports Station-only mode, SoftAP-only mode, Station/SoftAP-coexistence mode
- Supports IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode
- Supports WPA/WPA2/WPA2-Enterprise and WPS
- Supports AMPDU, HT40, QoS and other key features
- Supports Modem-sleep
- Supports an Espressif-specific protocol which, in turn, supports up to **1 km** of data traffic
- Support Station-only mode, SoftAP-only mode, Station/SoftAP-coexistence mode
- Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode
- Support WPA/WPA2/WPA2-Enterprise and WPS
- Support AMPDU, HT40, QoS and other key features
- Support Modem-sleep
- Support an Espressif-specific protocol which, in turn, supports up to **1 km** of data traffic
- Up to 20 MBit/sec TCP throughput and 30 MBit/sec UDP throughput over the air
- Supports Sniffer
- Support Sniffer
- Support set fast_crypto algorithm and normal algorithm switch which used in wifi connect
- Support both fast scan and all channel scan feature
- Support multiple antennas
- Support channel state information
How To Write a Wi-Fi Application
----------------------------------
@ -1475,6 +1477,60 @@ Generally, following steps can be taken to configure the multiple antennas:
.enabled_ant1 = 3
};
Wi-Fi Channel State Information
------------------------------------
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.
+-------------+--------------------+--------------------------------+---------------------------------------------------------------------------------------------------------------------+
| packet | signal mode | non HT | HT |
+ +--------------------+--------------------------------+---------------------------------+-------------------------------------------------------+---------------------------+
| information | channel bandwidth | 20MHz | 20MHz | 40MHz | 20MHz |
+ +--------------------+--------------------------------+----------------+----------------+---------------------------+---------------------------+-------------+-------------+
| | STBC | non STBC | non STBC | STBC | non STBC | STBC | non STBC | STBC |
+-------------+--------------------+------------------+-------------+----------------+----------------+---------------------------+---------------------------+-------------+-------------+
| channel | HT20/40 | HT40 | HT20 | HT40 | HT20 |
+ +--------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+---------------------------+
| information | secondary channel | below | above | none | below | above | below | above | below | above | below | above | none |
+-------------+--------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+-------------+-------------+
| sub-carrier | LLTF | -64~-1 | 0~63 | 0~31,-31~-1 | -64~-1 | 0~63 | -64~-1 | 0~63 | -64~-1 | 0~63 | -64~-1 | 0~63 | 0~31,-31~-1 | 0~31,-31~-1 |
+ +--------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+-------------+-------------+
| index | HT-LTF | - | - | - | -64~-1 | 0~63 | -62~-1 | 0~62 | 0~63,-64~-1 | 0~63,-64~-1 | 0~60,-60~-1 | 0~60,-60~-1 | 0~31,-31~-1 | 0~31,-31~-1 |
+ +--------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+-------------+-------------+
| | STBC-HT-LTF | - | - | - | - | - | -62~-1 | 0~62 | - | - | 0~60,-60~-1 | 0~60,-60~-1 | - | 0~31,-31~-1 |
+-------------+--------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+-------------+-------------+
| total bytes | 128 | 128 | 128 | 256 | 256 | 376 | 380 | 384 | 384 | 612 | 612 | 256 | 384 |
+----------------------------------+----------+-------+-------------+--------+-------+--------+-------+-------------+-------------+-------------+-------------+-------------+-------------+
All of the information in the table can be found in the structure wifi_csi_info_t.
- Signal mode of packet refers to sig_mode field of rx_ctrl field.
- Channel bandwidth refers to cwb field of rx_ctrl field.
- STBC refers to stbc field of rx_ctrl field.
- HT20/40 depends on secondary channel. If secondary channel is above or below primary channel, it is HT40. If secondary channel is none, it is HT20.
- Secondary channel refers to secondary_channel field of rx_ctrl field.
- Total bytes refers to len field.
- The CSI data corresponding to each Long Training Field type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 items may not be present, depending on the packet type (see above).
- If last_word_invalid field of wifi_csi_info_t is true, it means that the last four bytes of CSI data is invalid due to a hardware limitation in ESP32.
- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.
.. note::
- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
- If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition HT/HT40/40MHz/STBC/above, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid).
Wi-Fi Channel State Information Configure
-------------------------------------------
To use Wi-Fi CSI, the following steps need to be done.
- Select Wi-Fi CSI in menuconfig. It is "Menuconfig --> Components config --> Wi-Fi --> WiFi CSI(Channel State Information)".
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi`.
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous`.
Wi-Fi Buffer Usage
--------------------------