π-Splicer Tutorial:

I. You need first to install the CSI tool from the Wireless And Networked Distributed Sensing (WANDS) system group@NTU, Singapore:

Please refer to http://wands.sg/AtherosCSI/

After you complete installation, please check the basic functions of transmission and reception.

Probably, in order to record the timestamps of each measurement, you need to replace the original source code in ~/Atheros-CSI-Tool-UserSpace-APP/csi_fun.c from line 141~144 and 152~155 with the code below:

((buf_addr[0] << 56) & 0xff00000000000000) | ((buf_addr[1] << 48) & 0x00ff000000000000) |
((buf_addr[2] << 40) & 0x0000ff0000000000) | ((buf_addr[3] << 32) & 0x000000ff00000000) |
((buf_addr[4] << 24) & 0x00000000ff000000) | ((buf_addr[5] << 16) & 0x0000000000ff0000) |
((buf_addr[6] << 8) & 0x000000000000ff00) | ((buf_addr[7]) & 0x00000000000000ff) ;

II.You are free to use our π-Splicer tool following the instructions in below:

1. Download the source code files here.

2. The transmitter needs to scan many channels in a short time. To implement it, please replace the file /Atheros-CSI-Tool-UserSpace-APP/hostapd-2.5/hostapd/hostapd_cli.c with the file /CSI_Modified_Code/Transmitter/hostapd_cli.c . Then make it. Before you use it, there are several things you have to do.

• a) Change the MAC address at the beginning of the file according to your NIC. (line 46~50)
• b) Change the wireless interface at the beginning of the file according to your computer e.g. "wlan1" or "wlan0". (line 52)
• c) We choose channel 2417MHz(No.2 in 2.4G) as the end mark of transmission. That means that the receiver will stop when it gets a package on 2417MHz channel.If you want use other channel as the end mark, please modify line 1316 "argve".

3.The receiver needs to receive packets from the transmitter and log them into a file. For convenience, we print the basic info of each packet received. Please replace the file /Atheros-CSI-Tool-UserSpace-APP/recvCSI/main.c with the file /CSI_Modified_Code/Receiver/main.c . Then make it. Before you run the program, there are several things you need to do.

• a) Change the end mark in the file according to your need. (line 127)
• b) If you want to plot the CSI in real time, please refer to https://github.com/caichao/livestreamcsi. (Although it is for intel 5300, you can read the code to learn how to transmit data through socket programming.)

4. Now you are ready to measure non-linear CSI phase errors. Please follow the instructions below:

• a) Set the output interface of NIC for both transmitter and receiver. (We suggest you to enable only 1 output interface at both sides.

• b) Connect the output interfaces of both side by a cable (or put the transmitting and receiving antennas near in a strong LOS condition).
• c) For the receiver, run the commands below.

• d) For the transmitter, run the commands below (you do not have to kill the program of the first terminal when you want to retransmit).

• e) Follow the instructions shown on the screen and enter the number of the starting channel to be measured, the interval of the next channel, the total number of channels, the number of packets to be transmitted on each channel, and the number of such iterations. For example,

then it will display

Here are the channels you will scan:

1 3 5 7 9 11

2412 2422 2432 2442 2452 2462

If all goes well, you should see the receiver printing packet information on the screen.

• f) Repeat it for other output interfaces of receiver. Then you will get three files 'Ant_1.dat', 'Ant_2.dat', 'Ant_3.dat'.

5. The data process program in /CSI_Modified_Code/Data_Process/ (we only write the program for data collected on channel 2412, 2422, 2432, 2442, 2452, 2462MHz. You may need to modify the code based on your own needs). Here is the relationship tree of our source files.

If you have 'Ant_1.dat','Ant_2.dat','Ant_3.dat' three files, you can run the 'Pi_Splicer.m'.

You will get the non-linear error parameters of 6 channels of Tx1~Rx1&Rx2&Rx3 in 'Parameter111213.mat'. If there is no problem, you will see 4 figures, Figure111, Figure11, Figure1, Figure3.

In Figure111, 6 sine-shape curves are plotted, which illustrate the non-linear error on each channel. Figure11 plots the results with non-linear phase errors removed. In Figure1, you will see two subplots. The left is the combined amplitudes of six channels with smoothing. The right is the combined amplitudes of each channel without smoothing. In Figure3, you will see two subplots. The left is the combined phases of six channels with smoothing. The right is the combined phase of each channel without smoothing.

6. The program above only applies to data of one loop. If you want to deal with data of multiple loops, please follow the instructions below (similarly, we only write program for the 6 channels mentioned above. You may need to modify the code for your own purpose):

• a) Change the output interface and log file name at the receiver (we take 'tst.dat' as an example):

• b) The transmitter should scan all 6 channels for multiple times. Now, you can disconnect the cable (if you choose to connect tx&rx by cable as mentioned above), and connect antennas for transmitter and receiver separately. For example, for transmitter, execute the commands below:

then enter

1 2 6 50 10

• c) Use the program we provide in /CSI_Modified_Code/Data_Process/For_Many_Loop/. Here is the relationship tree of our source files.

• d) To test the program, you can just run 'Pi_Splicer_Plus.m'. If you see a dynamic figure, congratulations! If there is something wrong with 'read_log_file.m', please re-compile 'read_csi.c' with mex in MATLAB.

• e) What you need to do is to put your non-linear error parameters file ('Parameter111213.mat') and your 'tst.dat' in /CSI_Modified_Code/Data_Process/For_Many_Loop/ and run 'Pi_Splicer_Plus.m'.

7. There are several things you should notice:

• a) We suggest you to measure the non-linear phase errors (step 4&5) every time you reboot your computer.
• b) Sometimes, the channel switch may fail if the RSSI is too low. We suggest you to try again. If you have any idea to solve the problem, please feel free to contact us.
• c) If there is some thing wrong with the function 'read_csi()' in 'read_log_file.m', you should re-compile 'read_csi.c' with the commands below in MATLAB (If you have no mex, google it.)

• d) It is difficult to switch channels on 5GHz bands without disabling NICs. This problem is still to be solved. If you have any idea, please feel free to contact us.
• e) If you have any problem with the tutorial, please feel free to contact us.

Here are some notes related to CSI measurement with Intel 5300
1) It seems that the PDD (Packet Detection Delay) is weakly corrected by the Intel 5300 NICs and, therefore, there is a corresponding rotation error in the unwrapped CSI phase. Usually, this delay can be larger than one sample period (denoted as $\tau_s$, e.g., $\tau_s$ = 50ns for the sampling rate of 20MHz) and can be represented as an integral number of delta_t, say $i$, plus a fractional part of $delta_t$. The particular value of $i$ depends on the specific setting of your experiment, which can be identified by conducting a linear regression to fit a linear model using $2 * \pi * f_s * i * \tau_s$ as the slope, where $f_s$ is the sub-carrier spacing between two adjacent sub-carriers (i.e. 312.5KHz). For instance, in our experiment setting, the value of $i$ is 4.

2) It is better to remove the major part of PDD (i.e., subtracting $2 * \pi * k * f_s * i * \tau_s$ from the measured unwrapped CSI phase) before eliminating non-linear phase error. This can greatly reduce the searching space when removing residual linear phase error as described in Subsection 4.2 in the π-Splicer paper.

III. Please refer to the following publications for more details and please cite them if you use π-Splicer in your work.