Sections

• WiFiTrace Pros
• WiFiTrace Features
• Dependencies & Installation
• Directory Structure & File Name Format
• Data Format
• Example Usage
• Reports
• References

WiFiTrace Pros

• Server Side Tool Ready to Deploy
• No need to install any battery draining apps on user mobile phones
• No active monitoring/recording needed
• No need to install sensors or perform infrastructure upgrade
• No laborious fingerprinting of existing infrastructure needed.

WiFiTrace Features

• Infected Person location visit report
• Co-locators summary report (list of co-locators with duration and location of co-location)
• Detail Co-location report of each co-locator
• Capability to identify user visits to locations with active pathogens even after patient departure from the location
• Configurable Patient visit duration parameter
• Configurable pathogen activity parameter

Dependencies and Installation

The code works with Python 3.7 and is also Python 2.7 compatible. You need to install Python (3.7 preferred) and the following list of packages:

• Pandas
• datetime, os, ast, sys, get_opt are all part of python’s standard library.

Code can be found here

Directory Structure and File Name Format

Contact Tracing Tool:

The directory structure of WiFiTrace code is as follows:

WiFiTrace
    - /src
    - /util

code directory : This directory has all the python code / script files
util directory : This directory has additional python scripts for more maniputlations that can be done on the data

The tool auto generates 2 directories to save the output (reports) as well as temporary file generated by the tool. These dirs are created in the location specified by the user in the config file.

idir : user specified dir in the config file
    - /reports (auto generated)
    - /temp_session (auto generated)

reports directory : The patient location visit report and user colocation reports generated by the tool are stored in here. The Patient report naming convention is Patient_Report_<Patient_MAC_ID>_<date>.txt while the user colocation report naming convention is User_Report_<Patient_MAC_ID>_<date>.txt.
temp_session : This directory has temporary files created by the tool.

Preprocessor : (WiFi Syslogs to Session Extraction System)

The directory structure of Preprocessor is as follows:

Preprocessor
    - /src
    - /util

src directory : This directory has all the python code/script files
util directory : This directory has additional python scripts for doing postprocessing on the output file.

Data Format

WiFiTrace : Contact Tracing Tool

Input Data Format :

The input to WiFiTrace is a csv file where each row of the csv file represents a device session. The columns in the csv file are:

MAC,Session_AP_Name,Year,Month,Date,Start_Time,End_Time,Unix_Start_Time,Unix_End_Time

Field Description:

MAC: (MAC Id of the device)
Session_AP_Name: Access Point Name/ID where device was connected
Year: YYYY
Month: MMM (eg: Jan, Feb, Mar, etc)
Date: DD (01-31)
Start_Time : Start time of session in HH:MM (24-hr format)
End_Time : End time of session in HH:MM (24-hr format)
Unix_Start_Time : Start time of session in Unix Timestamp
Unix_End_Time : End time of session in Unix Timestamp

Note:

• The input file to WiFiTrace is the output file of Preprocessor. So, if you have HP Aruba WiFi Solution go ahead and use the preprocessor to create the session input file to WiFiTrace.

Output Data Format :

The output of WiFiTrace are Patient report and User Co-location report, explained in the Reports section.

Preprocessor : WiFi Syslogs to Sessions Extraction System:

Input Data Format :

HP Aruba WiFi log Format: The WiFi log of HP Aruba also called syslog file contains a list of events. A typical event message in the Wifi log/syslog looks as below:

hh:mm:ss <controller_name> <process_id> <message_subtype> <controller_name masked_IP> <message_body>

This is the log file generated by HP Aruba WiFi Access Point. It is the input file to extract trajectories from WiFi logs.

Output Data Format :

The Preprocessor should generate a csv file based on the format described above (input data format for WiFi tool).

Usage

WiFiTrace (Contact Tracing Tool):

python main.py -m <\mac id> -s <start date YYYYMMDD > -e <end date YYYYMMDD > -w <pathogen active window size> -l <minimum session length (in mins) of the infected patient>

where:
m - mac id of the infected patient
s - This is the date from when you want to perform contact tracing
e - This is the date till when you want to perform contact tracing
w - Time in hours for which the pathogen is active, if you want to perform contact tracing to identify users who visited the location after the departure of the infected person when the pathogens spread by the infected person are still alive. Default value 0, indicating the infected person and other users should be co-located at the same place and at the same time.
l - Minimum time in mins spend by the infected person at a location. Default value 0, indicating consider all locations visited by the infected person irrespective of the time spend at each location.

Also, change the value of parameter idir in config.text file to indicate the location of all input session files.

For Example:

• To generate the contact trace for a mac_id “0x-DE-AD-BE-EF” for dates starting from 19-Jan-2020 till 24-Jan-2020 and the pathogen active window is 2 hrs (time window for which the pathogen is active even after the infected patient leaves the location) and the infected person must have spend atleast 5 mins at each location, we would run the python script as below:

  python main.py -m “0x-DE-AD-BE-EF” -s 20200119 -e 20200124 -w 1 -l 5

  If you want strict co-location then, enter window size as 0 ( -w 0 )

If the input sessions files are at /Users/foo/, change idir value in config.txt to idir=/Users/foo/

Preprocessor (Syslog to Session File):

python main.py -y <YYYY> -i <input> -o <output>

where:
i - input syslog file name or directory (if multiple files to be preprocessed)
o - output file name or directory
y - Year (YYYY format) of the syslog file passed in -i, default is current year

Note:

1. If Output file parameter -o option is a directory then the outfile is saved as a _sessions.csv

Example: main.py -y 2019 -i /data/20190111_syslog -o /session/

will process the syslog file present at location /data/20190111_syslog and create an output file in /session/ dir with name 20190111_syslog_sessions.csv

1. If Input parameter is a directory then the script processes all syslog files in the directory that haven’t been processed earlier and generates the corresponding session output files.

Reports

WiFiTrace generates 2 reports:

1. Patient Report
2. User Report

The format of the report can be txt or JSON based on the input parameter (-f) supplied when calling WIFITrace. If the parameter is not supplied by default the reports are saved as text file.

Description of Reports

Patient Report
Patient Report describes the list of locations visited and time of visit by the patient from the start date till the end date. Each row of the report gives the date, start time of visit(24 hr clock format), end time of visit(24 hr clock format), Location details and Duration of visit(in mins).

User Report
The User report provides details about the users co-located with the patient between the start date and the end date. The user report has 2 sections Summary section and Detailed report section.

The Summary section provides a count of total co-locators as well as a list of all Mac IDs along with the duration of co-location of each Mac ID with the infected person.

The Detail report section provides a co-location details of each mac id with the infected person - listing the date, start time(24 hr clock format) of co-location, end time(24 hr clock format) of co-location, Location details and duration of co-location.

References

The design of this tool leverages our research expertise in characterizing and modeling the mobility of users. A recent technical publication titled “Empirical Characterization of Mobility of Multi-Device Internet Users” describes our mobility characterization and modeling research and is available on arxiv

A research publication desribing the network-centric WiFi-based contact tracing method used by WiFiTrace is a work in progress and will be availble here soon.