Atheros CSI Extraction Tool
Atheros CSI Tool

Yaxiong Xie,   yxie005@e.ntu.edu.sg   xieyaxiongfly@gmail.com
Mo Li,             limo@ntu.edu.sg
Wireless And Networked Distributed Sensing (WANDS) system group@NTU, Singapore

Overview | Documentation | Platforms | Supported Devices | GitHub | UAV | Citation | Users | Credits

Overview

Atheros-CSI-Tool in a nutshell

Atheros-CSI-Tool is an open source 802.11n measurement and experimentation tool. It enables extraction of detailed PHY wireless communication information from the Atheros WiFi NICs, including the Channel State Information (CSI), the received packet payload, and other additional information (the time stamp, the RSSI of each antenna, the data rate, etc.).

Atheros-CSI-Tool is built on top of ath9k, which is an open source Linux kernel driver supporting Atheros 802.11n PCI/PCI-E chips, so theoretically this tool is supposed to be able to support all types of Atheros 802.11n WiFi chipsets. We also observe that several Qualcomm Atheros 802.11ac SoCs also support our tool (only works in 802.11n mode). We have tested it on Atheros AR9580, AR9590, AR9344 and QCA9558. Here is the full list of the supported devices. If you have tested it on other types of Atheros NICs, please kindly inform us whether it is successful or let us know the problems that you encounter.

Atheros-CSI-Tool is open source and all functionalities are implemented in software without any modification to the firmware. Therefore, you are able to extend the functionalities of Atheros-CSI-Tool with your own codes under the GPL license. You are welcome to get back to us with new functionalities contributed to the tool.

Key functionality

  1. Non-grouping, non-compressed CSI reporting.
    Non-grouping: Atheros-CSI-Tool reports the CSI value for each subcarrier, i.e., 56 subcarriers for 20MHz channel and 114 subcarriers for 40MHz channel.
    Non-compressed: Atheros-CSI-Tool reports high precision CSI, i.e., 10 bit resolution for both imaginary and real part of the CSI.


  2. Detailed payload records.
    Atheros-CSI-Tool records the payload of every received packet. Atheros-CSI-Tool gives the detailed information about error bits within the packet. A packet is received incorrect, due to CRC check failure or the PHY failures in the NIC. The error type of the packet failure is also recorded.


  3. Rich status records.
    Atheros-CSI-Tool retrives rich status information about the received packet. The current version retrieves the following information: the channel frequency, the time stamp the packet is received, the transmitted payload length, the payload error type, the data rate, the channel bandwidth, the subcarrier number, the number of transmitting and receiving antenna, the RSSI of the combination of all active receiving chains and the detailed RSSI of each chain.

Please check the documentation for more details on how to use this tool.

Broadcast Mode

Our tool support the boradcast mode, where one transmitter will broadcast the packet and multiple receiver will receive this packet and calculate the CSI. To support this mode, we modify the MAC address of the receivers' Wi-Fi NIC card to a common address and then use our sendData function to send packets to this common address. This mode has been verified by Kun Qian from Tsinghua University.

To enable broadcast mode, you need connect all your Wi-Fi clients with the AP. Then, change the MAC address of all your Wi-Fi clients to the same MAC by:

ifconfig wlan0 down
ifconfig wlan0 hw ether 00:01:02:03:04:05
ifconfig wlan0 up

Here, the MAC 00:01:02:03:04:05 can be changed to any MAC you like. After this, use the sendData function to send packet to this MAC address and all of your clients can receive the packet and calculate the CSI.

Example

Below is the amplitude of CSI that is collected from 10 consecutive channels (channel 1-10) at 2.4GHz (more information can be found in our paper "Precise Power Delay Profiling with Commodity WiFi" in MobiCom’15).


Platforms

Ubuntu (documentation)

Ubuntu is a Linux operating system for personal computers, tablets and smart phones. Atheros-CSI-Tool is able to work on top of any devices whose operating system is Ubuntu. Instructions on installing Atheros-CSI-Tool on Ubuntu devices can be found here.

OpenWRT (documentation)

OpenWrt is an embedded operating system based on Linux, primarily used on embedded devices to route network traffic. All components of OpenWRT have been optimized for size, to be small enough for fitting into the limited storage and memory available in home routers and hence support various types of devices. The list of supported devices can be found on this site.

Atheros-CSI-Tool is also able to work on top of OpenWRT devices. Since Atheros-CSI-Tool is based on ath9k driver which only drives Atheros 802.11n Wi-Fi chips, Atheros-CSI-Tool requires that the OpenWRT devices must be equipped with Atheros Wi-Fi NIC. Instructions on installing Atheros-CSI-Tool on OpenWRT devices can be found here.

Other extensions

Here, we want to emphasize that Atheros-CSI-Tool can work on any type of devices that equipped with Atheros 802.11n Wi-Fi NIC and runs Linux systems. The Linux system is not limitted to Ubuntu and OpenWRT. Theoretically, Atheros-CSI-Tool works on any type of Linux (such as Fedora, Debian and CentOS for PC, Linino for Arduino devices). We havn't tested all those systems but we have succeed in transplant Atheros-CSI-Tool to Linino which is an OpenWRT based Linux distribution and works on Arduino and a lot of other IoT devices. Please let us know if you succeed in trying other systems.


Extension to UAV

UAVs or drones are widely used for photographing, goods delivery and military purposes. UAVs are controlled by an onboard computer, for example Manifold from DJI. Under a lot circumstances, the location of the UAV is critical for the control. On the other hand, CSI-based localization has been well studied and widely used, which could achieve great accuracy. Therefore, can we extend such methods to UAVs?

The user of our tool-- Bing Li from ECE@HKUST, has transplant our CSI tool released for Ubuntu system into the Manifold kernel and successfully runs it on a UAV. With the help of our tool, CSI-based localization techniques are now applicable to UAV.

More information can be found from the GitHub.


Cite this tool

To cite this tool, the best reference is our paper published in MobiCom 2015:

    Precise Power Delay Profiling with Commodity WiFi, In ACM MobiCom, 2015
    Yaxiong Xie, Zhenjiang Li, Mo Li


Users

  1. <Ubuntu> A novel method of Wi-Fi indoor localization based on channel state information, In WCSP, 2017 Jinsong Li, Yunzhou Li, and Xinsheng Ji
  2. <Ubuntu> Deep Learning Based NLOS Identification with Commodity WLAN Devices, In arxiv, 2017 Jeong-Sik Choi, Woong-Hee Lee, Jae-Hyun Lee, Jong-Ho Lee and Seong-Cheol Kim
  3. <Ubuntu> Perceiving accurate CSI phases with commodity WiFi devices, In IEEE INFOCOM, 2017 Yiwei Zhuo, Hongzi Zhu, Hua Xue, Shan Chang
  4. <OpenWRT>Wi-Fi Goes to Town: Rapid Picocell Switching for Wireless Transit Networks, In ACM SIGCOMM, 2017 Zhenyu Song, Longfei Shangguan, Kyle Jamieson
  5. <OpenWRT>FreeDetector: Device-Free Occupancy Detection with Commodity WiFi, In IEEE SECON Workshops, 2017 Han Zou, Yuxun Zhou, Jianfei Yang, Weixi Gu, Lihua Xie and Costas Spanos
  6. <Ubuntu> Identifying a New Non-Linear CSI Phase Measurement Error with Commodity WiFi Devices, In IEEE ICPADS, 2016 Yiwei Zhuo, Hongzi Zhu, Hua Xue
  7. <OpenWRT>Augmenting Wide-band 802.11 Transmissions via Unequal Packet Bit Protection, In IEEE INFOCOM, 2016 Yaxiong Xie, Zhenjiang Li, Mo Li, Kyle Jamieson
  8. <OpenWRT>Precise Power Delay Profiling with Commodity WiFi, In ACM MobiCom, 2015 Yaxiong Xie, Zhenjiang Li, Mo Li
  9. <OpenWRT>Recitation: Rehearsing Wireless Packet Reception in Software, In ACM MobiCom, 2015 Zhenjiang Li, Yaxiong Xie, Mo Li, Kyle Jamieson

Credits

    Maintainer: Yaxiong Xie

    Authors: Yaxiong XieMo Li

    Collaborators: Zhenjiang LiKyle Jamieson


Back to top of page