UWAR:Tutorial:CommandLine

Adding UWAR Tool Support

To add support for UWAR command-line tools, simply add the following path to your PATH:

   /projects/ubicomp/uwar/bin

If you'd like to use the command-line tools outside of the UW CSE environment, you can simply copy uwar-* from that directory to a directory in your own environment and they should run just fine as long as you have java installed.

General Notes

It's important to note that all timestamps are specified in number of milliseconds since the Unix epoch. This number is directly comparable with the results of the Unix time command and time values in Java (ex. System.currentTimeMillis()).

Available Tools

uwar-stats

This utility prints out relevant statistics about a given trace. Example:

   $ uwar-stats msp-2006-10-11-16.24.uwar
   msb.barometricMismatch=61
   msb.corruptFrames=0
   msb.frameHitRate=1.0
   msb.framesMissed=0
   msb.jitteredFrames=0
   msb.numFramesRecvd=465580
   msb.tickStart=-167706
   msb.tickStop=297873
   uwar.bytes_skipped=0
   uwar.packet_count=556381
   uwar.version=2

For more info, call uwar-stats --help.

uwar-extract

This utility allows you to extract sensor data from a trace into comma-separated-values format. To query the data available in a trace, use the following example:

   $ uwar-extract msp-2006-10-11-16.24.uwar
   MSPPowerLevels
   MicroStrain3DMGX1
   msb/acceleration
   msb/bar_temp_press
   msb/hf_vis_light
   msb/light_infrared
   msb/light_visible
   msb/sht_temp_humidity

To extract the actual trace data, specify the sensor id:

   $ uwar-extract msp-2006-10-11-16.24.uwar msb/acceleration
   1160609006726.8438,-0.11279297,-0.3612671,1.1564331
   1160609006728.2344,0.059143066,-0.4393921,0.9376831
   1160609006728.625,0.059143066,-0.5800171,1.2189331
   ...

Here, the first column is the timestamp (in milliseconds since the Unix epoch) and the next three columns are x, y, and z respectively. You can print the column names as the first row of output by specify the -f option:

   $ uwar-extract -f msp-2006-10-11-16.24.uwar msb/acceleration
   timestamp,x,y,z
   1160609006726.8438,-0.11279297,-0.3612671,1.1564331
   1160609006728.2344,0.059143066,-0.4393921,0.9376831
   1160609006728.625,0.059143066,-0.5800171,1.2189331
   ...

For more info, call uwar-extract --help.

uwar-join

A simple tool for joining traces:

   $ uwar-join -o Trace-joined.uwar msp-2006-10-11-*.uwar

You can optionally specify which sensors should be included:

   $ uwar-join -s msb/acceleration -o Trace-joined.uwar msp-2006-10-11-*.uwar

uwar-split

By far the most powerful UWAR command-line tool, it is also the most complex to use. This utility allows you to split and merge UWAR sensor data from multiple input traces, selectively specifying which sensors to include and exclude.

In a simple example, we wish to copy the data for a single sensor from a trace with multiple sensors.

   $ uwar-extract msp-2006-10-11-16.24.uwar
   MSPPowerLevels
   MicroStrain3DMGX1
   msb/acceleration
   msb/bar_temp_press
   msb/hf_vis_light
   msb/light_infrared
   msb/light_visible
   msb/sht_temp_humidity
   $ uwar-split -i msp-2006-10-11-16.24.uwar:MicroStrain3DMGX1 -o msp-micro.uwar
   $ uwar-extract msp-micro.uwar 
   MicroStrain3DMGX1

In a more complex case, we can merge multiple sensors from multiple input traces into a single output trace:

   $ uwar-split -i msp-2006-10-11-16.24.uwar:MicroStrain3DMGX1,MSPPowerLevels \
                -i msp-2006-10-11-16.54.uwar:MicroStrain3DMGX1,MSPPowerLevels \
                -o msp-out.uwar
   $ uwar-extract msp-out.uwar
   MSPPowerLevels
   MicroStrain3DMGX1

For more info, call uwar-split --help.

uwar-time

This utility is used to adjust the timestamps of data in a UWAR trace. You can change the start time of a trace, add a unit of time to the start of the trace, or adjust the timestamps based on clock synch that may be present when collecting data on two different devices. Consider the following example, where a trace was collected on an iPAQ while syncing with a remote MSP:

   $ uwar-extract Trace-2006_10_11-12_22_09.uwar
   clock
   latlon
   wifi

$ uwar-time -c Trace-2006_10_11-12_22_09.uwar Trace-synced.uwar

For more info, call uwar-time --help.