Wi-Fi CSI Introduction

Wi-Fi CSI (Channel State Information) is a technology used to describe the characteristics of wireless channels. It aims to quantify the aggregate effect of wireless phenomena (such as interference, multipath, doppler shift…) on wireless signals in a given environment by reporting complete CSIs. And can be used in applications such as human activity analysis, WiFi indoor positioning, and gesture recognition.

Realtek Wi-Fi CSI is divided into Active CSI and Passive CSI schemes based on whether the Realtek device (STA mode or SoftAP mode) participates in transmitting the CSI triggering frames.

  • Active CSI: The Realtek device needs to actively transmit CSI triggering frames

    • Active CSI is divided into two modes based on the type of CSI triggering frame: unicast mode and broadcast mode. For details, refer to Active CSI: Unicast Mode and Active CSI: Broadcast Mode.

    • Using Public Action frame as CSI triggering frame in Active CSI.

  • Passive CSI: The Realtek device is not required to transmit CSI triggering frames

Active CSI: Unicast Mode

  • METHOD1: A Realtek STA transmits a unicast CSI triggering frame to the AP and derives CSI from the ACK response to the previous CSI triggering frame (one-to-one communication).

  • METHOD1_Variant: A Realtek STA transmits a unicast CSI triggering frame to another STAx and derives CSI from the ACK response to the previous CSI triggering frame (one-to-many communication via polling).

  • METHOD2: A Realtek SoftAP transmits a unicast CSI triggering frame to associated stations and derives CSI from the ACK response to the previous unicast CSI triggering frame (one-to-many communication via polling).

../../_images/collecting_csi_from_rx_ack_packet_response_mode.svg

Collect CSI from Rx ACK Packet in Rx Response Mode

Active CSI: Broadcast Mode

  • METHOD3: Realtek SoftAP transmits a broadcast CSI triggering frame, which are decoded by Realtek STAs to derive CSI.

  • METHOD4: A Realtek STA transmits a broadcast CSI triggering frame, which are decoded by neighboring Realtek STAs to derive CSI.

../../_images/collecting_csi_from_rx_broadcast_packet_normal_mode.svg

Collect CSI from Rx Broadcast Packet in Rx Normal Mode

Passive CSI

  • METHOD5: A Realtek STA/SoftAP derives CSI from received packets in Rx Normal Mode (one-to-one communication).

../../_images/collecting_csi_from_rx_packet_normal_mode.svg

Collect CSI from Rx packet in Rx Normal Mode

Wi-Fi CSI Architecture

Wi-Fi CSI report mainly consists of three modules:

  1. Configure and Enable Wi-Fi CSI

    • The APP must call the API to configure Wi-Fi CSI parameters as needed and enable the Wi-Fi CSI function.

    • The APP must call the API to disable the Wi-Fi CSI function when inactive.

  2. Register/Deregister Wi-Fi CSI Callback

    • Register a Wi-Fi CSI callback function when enabling Wi-Fi CSI. The Wi-Fi driver will transmit a flag to notify the APP when each CSI packet ready through the callback function.

    • Release the Wi-Fi CSI callback function when disabling Wi-Fi CSI.

  3. Report Wi-Fi CSI

    • The APP should run a separate thread to wait for the CSI report ready flag, then call the API to read the CSI report.

../../_images/csi_architecture.svg

Wi-Fi CSI architecture

Wi-Fi CSI Usage Notes

Basic Requirements

  • Parameter configurations for different CSI methods should follow example in Collect CSI from Rx ACK Packet in Rx Response Mode, Collect CSI from Rx Broadcast Packet in Rx Normal Mode and Collect CSI from Rx packet in Rx Normal Mode.

  • Disable power saving mode before enabling Wi-Fi CSI function.

    • How to disable: Navigate to component/soc/amebaxxx/usrcfg/ameba_wificfg.c, locate the wifi_set_user_config() and modify as follows:

      wifi_user_config.lps_enable = 0;
wifi_user_config.lps_mode = RTW_PS_MODE_ACTIVE;

  • Mandatory parameters: data_rate and must set to be greater than or equal to OFDM rate.

  • Optional parameters: group_num, accuarcy, ch_opt, csi_role, trig_period, data_bw, trig_frame_xx, trig_flag, multi_type and can be configured as needed.

METHOD4 Design Considerations

METHOD1, METHOD2, METHOD3 and METHOD5 are normal interactions between STA and AP in infrastructure mode, Realtek driver will construct the MAC address of CSI triggering frame in accordance with Wi-Fi protocol standards.

For example, if the Ameba chip acts as the STA role, the frame format specified by the Wi-Fi standards is shown in the following figure:

../../_images/interaction_between_sta_and_ap_infrastructure_mode.svg

Interaction between STA and AP in infrastructure mode

However, METHOD4 involves interaction between STAs in infrastructure mode, which is not fully compliant with Wi-Fi protocol standards. To ensure other STAs can receive packets from the target STA, the Ameba chip will forge CSI triggering frame by modifying the MAC address fields of the CSI trigger frames to A1=broadcast address and A2=BSSID. This ensures that the MAC layer of Realtek receiving devices does not filter out the packets.

Note

Only when the Realtek MAC layer receives the Wi-Fi packet will it trigger the CSI circuit to capture CSI reports.

../../_images/interaction_between_sta_and_sta_infrastructure_mode.svg

Interaction between STA and STA in infrastructure mode

Additionally, METHOD4 has another issue: as shown in the figure above, Ameba2 receives Wi-Fi packets from both Ameba3 and Ameba1 with identical content, making it impossible for Ameba2 to distinguish whether the CSI packet was triggered by Ameba1 or Ameba3. To resolve this issue, we will fill the unique identifier trig_flag into the Fragment Number subfield in Sequence Control filed of Wi-Fi packet, and this identifier will be carried in the corresponding CSI packet. The application layer can distinguish which device the CSI belongs to base on trig_flag.

../../_images/mapping_trig_flag_with_sta.svg

Mapping of trig_flag with STAx

Compiling Wi-Fi CSI Image

  1. Navigate to {SDK}/amebaxxx_gcc_project and run the following command:

    ./menuconfig.py

  2. Locate CONFIG WIFI > Enable CSI, select Enable CSI, then save and exit.

    ----Connectivity config----
    CONFIG WHC INTF --->
    CONFIG WIFI --->
             SDK MODE (NORMAL INIC)  --->
      [ ]    Enable WPS
      [*]    Enable CSI
      [ ]    Enable ANTDIV
      ---
    CONFIG BT --->
    ... --->

  3. Navigate to {SDK}/amebaxxx_gcc_project again and run the following command:

    ./build.py -a wifi_csi     /* compile image with Wi-Fi CSI example */
./build.py                 /* compile image without Wi-Fi CSI example */

The image bin files (xxx_app.bin & xxx_boot_all.bin) can be found in {SDK}/amebaxxx_gcc_project after compile done.

Wi-Fi CSI Example

This section describes the framework and implementation details of the Wi-Fi CSI example. The file path is {SDK}\component\example\wifi\wifi_csi.

Overview of Wi-Fi CSI Example

../../_images/csi_example_flowchart.svg

Wi-Fi CSI example implementation block diagram

Details of Wi-Fi CSI Example

For guidance on integrating the Ameba SDK and compiling examples, refer to Application Example. The following section details the implementation specifics of the Wi-Fi CSI example.

Example Initialization

The entry function for the Wi-Fi CSI example is defined in app_example().

void app_example(void)
{
   example_wifi_csi();  /* calling the entry function of wifi CSI example */
}

Wi-Fi CSI Entry Function

After executing Wi-Fi CSI example entry function: example_wifi_csi()，a CSI processing thread is created.

void example_wifi_csi(void)
{
   if (rtos_task_create(NULL, ((const char *)"wifi_csi_thread"), wifi_csi_thread, NULL, 1024 * 4, 0) != SUCCESS) {
      RTK_LOGA(NOTAG, "\n\r%s rtos_task_create(wifi_csi_thread) failed", __FUNCTION__);
   }

   return;
}

Wi-Fi CSI Thread

  1. Waiting for Wi-Fi power-up and connection success.

    1. If the SoftAP role is enabled, Wi-Fi CSI function will only be initiated by the SoftAP, regardless of whether STA role is in an associated state. Once other devices connect to the SoftAP role, the first connected device will be selected to enable the Wi-Fi CSI function.

      If no other devices connect to the SoftAP role, execute rtos_time_delay_ms(2000).

    2. If the SoftAP role is not enabled, the Wi-Fi CSI function will be enabled after the STA role connects to a realAP.

      If STA role is not connected, execute rtos_time_delay_ms(2000).

    while (1) {
   NEXT:
      if (wifi_is_running(SOFTAP_WLAN_INDEX)) {
         wifi_get_associated_client_list(&client_info);
         if (client_info.count) {
            memcpy(act_param.mac_addr, client_info.mac_list[0].octet, 6);
            RTK_LOGA(NOTAG, "### SOFTAP Break ###\r\n");
            break;
         }
         rtos_time_delay_ms(2000);  /* 2s */
         goto NEXT;

      }
      if (wifi_is_running(STA_WLAN_INDEX) && (wifi_get_join_status() == RTW_JOINSTATUS_SUCCESS) && (*(u32 *)LwIP_GetIP(0) != IP_ADDR_INVALID)) {
         rtos_time_delay_ms(2000);  /* 2s */
         RTK_LOGA(NOTAG, "### STA Break ###\r\n");
         break;
      }
      rtos_time_delay_ms(2000);  /* 2s */
}

  2. Registering a Wi-Fi CSI callback function example_wifi_csi_report_cb().

    /* register wifi event callback function */
wifi_reg_event_handler(RTW_EVENT_CSI_DONE, example_wifi_csi_report_cb, NULL);

  3. Initializing a semephore wc_ready_sema, and you should use semaphore to signal that a Wi-Fi CSI report is ready.

    /**
* should use semaphore to indicate the occurrence of a Wi-Fi event
* This example uses the semaphore `wc_ready_sema` to signal that a Wi-Fi CSI report is ready.
*/
rtos_sema_create(&wc_ready_sema, 0, 0xFFFFFFFF);
if (!wc_ready_sema) {
   RTK_LOGE(NOTAG, "\r\nInit wc_ready_sema failed\r\n\n");
}

  4. Wi-Fi CSI parameters assignment (example configuration for METHOD1/ METHOD2).

    /* config csi parameters */
act_param.group_num = CSI_GROUP_NUM_1;
act_param.mode = CSI_MODE_RX_RESP;
act_param.accuracy = CSI_ACCU_1BYTE;
act_param.trig_period = 200;     /* units: 320us */
act_param.data_rate = MGN_6M;    /* ofdm 6 mpbs*/
act_param.trig_frame_mgnt = 0;   /* no need for rx resp mode, default 0*/
act_param.trig_frame_ctrl = 0;   /* no need for rx resp mode, default 0*/
act_param.trig_frame_data = 0;   /* no need for rx resp mode, default 0*/
act_param.csi_role = CSI_OP_ROLE_TRX;

  5. Configuring Wi-Fi CSI parameters and enabling Wi-Fi CSI.

    /* cis cfg and csi en */
act_param.act = CSI_ACT_CFG;  /* csi cfg */
wifi_csi_config(&act_param);

act_param.act = CSI_ACT_EN;  /* csi en */
act_param.enable = 1;
wifi_csi_config(&act_param);

  6. Waiting for the semaphore wc_ready_sema to be ready and calling API wifi_csi_report() to fetch the Wi-Fi CSI packet.

    while (1) {
   /* example: when wifi csi rx done, call csi report handle function. */
   if (rtos_sema_take(wc_ready_sema, 0xFFFFFFFF) != SUCCESS) {
      rtos_sema_delete(wc_ready_sema);

      act_param.act = CSI_ACT_EN;  /* csi dis */
      act_param.enable = 0;
      wifi_csi_config(&act_param);
      break;
   }

   csi_buf = rtos_mem_malloc(csi_data_len);
   if (csi_buf != NULL) {
      wifi_csi_report(csi_data_len, csi_buf, &len);

      /*do something for handing csi info: like show csi data */
      wifi_csi_show(csi_buf);

   } else {
      RTK_LOGE(NOTAG, "\r\n csi_buf malloc fail\r\n");
   }

   if (csi_buf != NULL) {
      rtos_mem_free(csi_buf);
   }
}

  7. Exit

    1. Disable Wi-Fi CSI function and release the Wi-Fi CSI callback function.

    2. Free the semaphore wc_ready_sema.

    3. Delete the task.

    /* unregister wifi event callback function */
wifi_unreg_event_handler(RTW_EVENT_CSI_DONE, example_wifi_csi_report_cb);

if (wc_ready_sema) {
   rtos_sema_delete(wc_ready_sema);
}

rtos_task_delete(NULL);

Wi-Fi CSI Callback Function

When the Wi-Fi driver is ready with a CSI report, it will utilize the Wi-Fi CSI callback function to send a signal to the APP. For instance, the APP can up the semaphore within the callback function to trigger the execution of wifi_csi_thread() for fetching a CSI report.

Note

  • Avoid performing heavy operations in the callback function to prevent impacting reception performance.

  • The APP can can use the parameter flags, which indicates the size of the current Wi-Fi CSI packet.

void example_wifi_csi_report_cb(s8 *buf, s32 buf_len, s32 flags, void *userdata)
{
   (void)buf;
   (void)buf_len;
   (void)userdata;
   rtos_sema_give(wc_ready_sema);  /* trigger thread */
   csi_data_len = flags;           /* APP can use for malloc csi_buf */
   return;
}