Welcome!¶

Pre-requisites¶

oxitopdump depends primarily on pyserial. If you wish to use the GUI you will also need PyQt4 installed.

Additional optional dependencies are:

• xlwt - required for Excel writing support
• maptlotlib - required for graphing support

Ubuntu Linux¶

For Ubuntu Linux it is simplest to install from the PPA as follows:

$ sudo add-apt-repository ppa://waveform/ppa
$ sudo apt-get update
$ sudo apt-get install oxitopdump

# Install the pre-requisites
$ sudo apt-get install python-matplotlib python-xlwt python-qt4 python-virtualenv python-sphinx make git

# Construct and activate a sandbox with access to the packages we just
# installed
$ virtualenv --system-site-packages sandbox
$ source sandbox/bin/activate

# Check out the source code and install it in the sandbox for development and testing
$ git clone https://github.com/waveform80/oxitopdump.git
$ cd oxitopdump
$ make develop

Microsoft Windows¶

On Windows, it is probably simplest to install one of the pre-built Python distributions that includes matplotlib like the Enthought Python Distribution or Python (x,y) (both of these include matplotlib and PyQt4), then start a command window from within the environment and use the following command:

$ pip install oxitopdump

Apple Mac OS X¶

XXX To be written

Other Platforms¶

If your platform is not covered by one of the sections above, oxitopdump is available from PyPI and can therefore be installed with the distribute pip tool:

$ pip install oxitopdump

Theoretically this should install pre-requisites, but certain things like PyQt4 require installation steps not supported by the pip installer and might therefore require manual installation steps beforehand.

Synopsis¶

$ oxitoplist [options] [bottle-serial]...

Description¶

--version¶

show program’s version number and exit

-h, --help¶

show this help message and exit

-q, --quiet¶

produce less console output

-v, --verbose¶

produce more console output

-l LOGFILE, --log-file=LOGFILE¶

log messages to the specified file

-D, --debug¶

enables debug mode (runs under PDB)

-p PORT, --port=PORT¶

specify the port which the OxiTop Data Logger is connected to. This will be something like /dev/ttyUSB0 on Linux or COM1 on Windows

-r, --readings¶

if specified, output readings for each head after displaying bottle details

-a, --absolute¶

if specified with –readings, output absolute pressure values instead of deltas against the first value

-m POINTS, --moving-average=POINTS¶

if specified with –readings, output a moving average over the specified number of points instead of actual readings

Examples¶

The basic usage of oxitoplist is to dump a list of the bottles stored on the connected device:

$ oxitoplist -p /dev/ttyUSB0
Serial    ID  Started    Finished   Complete Mode         Heads
--------- --- ---------- ---------- -------- ------------ -----
110222-06 999 2011-02-22 2011-03-08 Yes      Pressure 14d 1
121119-03 3   2012-11-19 2012-11-22 Yes      Pressure 3d  1
120323-01 1   2012-03-23 2012-04-20 Yes      Pressure 28d 2

3 results returned

If one or more bottle-serial numbers are listed on the command line (which may include wildcards), the details of the bottles listed are output instead:

$ oxitoplist -p /dev/ttyUSB0 12*

Serial                 121119-03
ID                     3
Started                2012-11-19 13:53:04
Finished               2012-11-19 13:53:04
Readings Interval      0:12:00
Completed              Yes
Mode                   Pressure 3d
Bottle Volume          510.0ml
Sample Volume          432.0ml
Dilution               1+0
Desired no. of Values  360
Actual no. of Values   0
Heads                  1

Serial                 120323-01
ID                     1
Started                2012-03-23 17:32:23
Finished               2012-03-23 17:32:23
Readings Interval      1:52:00
Completed              Yes
Mode                   Pressure 28d
Bottle Volume          510.0ml
Sample Volume          432.0ml
Dilution               1+0
Desired no. of Values  360
Actual no. of Values   361
Heads                  2

The -r option can be used to include the readings from selected bottles. These are excluded by default as it’s probably more useful to use oxitopdump for those purposes:

$ oxitoplist -p /dev/ttyUSB0 -r 110222-06

Serial                 110222-06
ID                     999
Started                2011-02-22 16:54:55
Finished               2011-02-22 16:54:55
Readings Interval      0:56:00
Completed              Yes
Mode                   Pressure 14d
Bottle Volume          510.0ml
Sample Volume          432.0ml
Dilution               1+0
Desired no. of Values  360
Actual no. of Values   361
Heads                  1

                    Head
Timestamp           60108
------------------- -----
2011-02-22 16:54:55 0.0
2011-02-22 17:50:55 -5.0
2011-02-22 18:46:55 -5.0
2011-02-22 19:42:55 -5.0
2011-02-22 20:38:55 -5.0
2011-02-22 21:34:55 -5.0
2011-02-22 22:30:55 -6.0
2011-02-22 23:26:55 -5.0
2011-02-23 00:22:55 -5.0
...
2011-03-08 11:18:55 -8.0
2011-03-08 12:14:55 -8.0
2011-03-08 13:10:55 -8.0
2011-03-08 14:06:55 -8.0
2011-03-08 15:02:55 -8.0
2011-03-08 15:58:55 -9.0
2011-03-08 16:54:55 -8.0

Readings are always given in chronological order and are delta readings by default. If you want the absolute pressure readings, use the -a option.

Synopsis¶

$ oxitopdump [options] [bottle-serial]... filename

Description¶

--version¶

show program’s version number and exit

-h, --help¶

show this help message and exit

-q, --quiet¶

produce less console output

-v, --verbose¶

produce more console output

-l LOGFILE, --log-file=LOGFILE¶

log messages to the specified file

-D, --debug¶

enables debug mode (runs under PDB)

-p PORT, --port=PORT¶

specify the port which the OxiTop Data Logger is connected to. This will be something like /dev/ttyUSB0 on Linux or COM1 on Windows

-a, --absolute¶

if specified, export absolute pressure values instead of deltas against the first value

-m POINTS, --moving-average=POINTS¶

if specified, export a moving average over the specified number of points instead of actual readings

-H, --header¶

if specified, a header row will be written in the output file

-R, --row-colors¶

if specified, alternate row coloring will be used in the output file (.xls only)

-C DELIMITER, --column-delimiter=DELIMITER¶

specifies the column delimiter in the output file. Defaults to , (.csv only)

-L LINETERMINATOR, --line-terminator=LINETERMINATOR¶

specifies the line terminator in the output file. Defaults to dos (.csv only)

-Q QUOTECHAR, --quote-char=QUOTECHAR¶

specifies the character used for quoting strings in the output file. Defaults to " (.csv only)

-U QUOTING, --quoting=QUOTING¶

specifies the quoting behaviour used in the output file. Defaults to minimal (.csv only). Can be none, all, minimal, or nonnumeric

-T TIMESTAMP_FORMAT, --timestamp-format=TIMESTAMP_FORMAT¶

specifies the formatting of timestamps in the output file. Defaults to %Y-%m-%d %H:%M:%S (.csv only)

Examples¶

When oxitopdump is invoked without specifying a bottle-serial the list of bottles will be exported to the specified filename. Typically you will want to use oxitoplist to discover the content of the connected device before exporting the readings for a specific bottle like so:

$ oxitoplist -p /dev/ttyUSB0
Serial    ID  Started    Finished   Complete Mode         Heads
--------- --- ---------- ---------- -------- ------------ -----
110222-06 999 2011-02-22 2011-03-08 Yes      Pressure 14d 1
121119-03 3   2012-11-19 2012-11-22 Yes      Pressure 3d  1
120323-01 1   2012-03-23 2012-04-20 Yes      Pressure 28d 2

3 results returned
$ oxitopdump -p /dev/ttyUSB0 120323-01 readings.csv
$ cat readings.csv
0,2012-03-23 17:32:23,0:00:00,0.0,0.0
1,2012-03-23 19:24:23,1:52:00,-12.0,-5.0
2,2012-03-23 21:16:23,3:44:00,-13.0,-5.0
3,2012-03-23 23:08:23,5:36:00,-13.0,-5.0
4,2012-03-24 01:00:23,7:28:00,-13.0,-5.0
...
357,2012-04-20 11:56:23,"27 days, 18:24:00",-16.0,-8.0
358,2012-04-20 13:48:23,"27 days, 20:16:00",-17.0,-8.0
359,2012-04-20 15:40:23,"27 days, 22:08:00",-17.0,-9.0
360,2012-04-20 17:32:23,"28 days, 0:00:00",-16.0,-8.0

If you specify multiple bottle-serials or if you specify a bottle-serial with wildcards which matches multiple bottles, you will need to specify a filename containing a substitution template like {bottle.serial} so that each bottle is output to a unique file. For example:

$ oxitopdump -p /dev/ttyUSB0 12* readings_{bottle.serial}.xls
$ ls *.xls
readings_120323-01.xls  readings_121119-03.xls

Various options are provided for customizing the output of the formats available. For example, to include a header row and force space separation:

$ oxitopdump -p /dev/ttyUSB0 -H -D " " 11* test.csv
$ head test.csv
No. Timestamp Offset "Head 60108"
0 "2011-02-22 16:54:55" 0:00:00 0.0
1 "2011-02-22 17:50:55" 0:56:00 -5.0
2 "2011-02-22 18:46:55" 1:52:00 -5.0
3 "2011-02-22 19:42:55" 2:48:00 -5.0
4 "2011-02-22 20:38:55" 3:44:00 -5.0
5 "2011-02-22 21:34:55" 4:40:00 -5.0
6 "2011-02-22 22:30:55" 5:36:00 -6.0
7 "2011-02-22 23:26:55" 6:32:00 -5.0
8 "2011-02-23 00:22:55" 7:28:00 -5.0