Table of Contents
zeoread
Overview
zeoread is a tool that specializes in reading information from raw Zeo Bedside Unit serial port data dumps. In addition to providing diagnostic/troubleshooting capabilities, zeoread is used by other tools in the zeotools suite to obtain their data (most notably zeograph).
Coding is done in a pedagogically informative style where time and sanity allows (lots of comments, at least once upon a time), and may not incorporate the most efficient means of accomplishing certain tasks due to its educational nature.
Source code should remain free.
Download
Binaries
Source
To obtain a copy of zeoread source, you must clone the zeotools mercurial repository.
The repository URL is: http://lab46.corning-cc.edu/hg/project/zeotools
If you are using a command-line mercurial tool (such as hg), that can be accomplished as follows:
box:~/src$ hg clone http://lab46.corning-cc.edu/hg/project/zeotools zeotools
Building
zeoread is distributed in source code form, which you must build before using.
It is written in C using the GNU C compiler (4.2.1 and 4.4.5), and actively developed on OpenBSD 5.1 i386 and Debian Squeeze amd64 (Linux 2.6.32). Development strives for warning-free errorless compiles, hopefully avoiding any system-specific quirks.
It has been known to compile on MacOS X, but is not as actively checked. No attempts have yet been made to compile on Windows, but if POSIX compliance means anything, then perhaps this too may “just work”.
To build, assuming you have a proper development environment installed, simply run “make” (to build with GDB debug support, run “make debug”). This example demonstrates building on an OpenBSD system with GNU make (note on Linux systems GNU make is the default “make” on the system):
box:~/src/zeotools/zeoread$ gmake [B] args.c ... OK [B] deinit.c ... OK [B] event.c ... OK [B] init.c ... OK [B] main.c ... OK [B] process.c ... OK [B] usage.c ... OK [B] zeoread ... OK box:~/src/zeotools/zeoread$
The Makefile has an install rule, which is set to copy the zeoread binary into /usr/local/bin. You'll likely need superuser access to perform the make install.
Usage
By default, zeoread tends to be rather noisy, displaying most of the data read from the raw serial dump. This can be useful for diagnostic purposes, but for analyzing actual sleep session data, one may wish to quiet it down a bit. A list of options can be obtained by running zeoread with the –help argument on its command-line:
box:~$ zeoread --help Usage: zeoread [OPTION]... Read/decipher raw data from Zeo Bedside serial port. -h, --help display this help and exit -V, --version output version information and exit -i, --in=FILE specify input file (default: STDIN) -o, --out=FILE specify output file (default: STDOUT) -v, --verbose enable verbose mode -D, --debug enable debug mode -q, --quiet try to run as quietly as possible -g, --graph generate zeograph-friendly data -S, --summary provide session tallies at end -d, --daemon daemonize and run in background -N, --show-none disable display of all display flags -b, --show-badsignal=on|off toggle BadSignal events (default: on) -E, --show-events=on|off toggle Events (default: on) -F, --show-freqbins=on|off toggle FreqBins events (default: on) -I, --show-impedance=on|off toggle Impedance events (default: on) -s, --show-sleepstage=on|off toggle SleepStage events (default: on) -L, --show-slice=on|off toggle Slice events (default: on) -Q, --show-sqi=on|off toggle SQI events (default: on) -t, --show-timestamp=on|off toggle TimeStamp events (default: on) -e, --show-version=on|off toggle Version events (default: on) -w, --show-waveform=on|off toggle Waveform events (default: on) -u, --show-undefined=on|off toggle Undefined events (default: off) If no file is specified, reading data from STDIN is assumed. Report zeoread bugs to wedge@lab46.corning-cc.edu zeoread home page: <http://lab46.corning-cc.edu/~wedge/zeotools/zeoread> box:~$
Examples
Following will be some usage examples for perceived common runs.
Sleep Session with Summary
If all you want is to get your sleep session data with a nice time tally at the end, the following command-line should work:
box:~$ zeoread -N -S -E on -s on -v -i ~/zeodata/zeosleep-201302020618.raw [verbose] Verbosity Enabled. [verbose] Opening /home/user/zeodata/zeosleep-201302020618.raw as input ... OK [verbose] Using STDOUT for output ... OK [verbose] Disabling display of ZeoTimeStamp data. [verbose] Disabling display of Version data. [verbose] Disabling display of BadSignal data. [verbose] Disabling display of SQI data. [verbose] Disabling display of Slice data. [verbose] Disabling display of FrequencyBins data. [verbose] Disabling display of WaveForm data. [verbose] Disabling display of Impedance data. [verbose] Disabling display of Undefined data. [verbose] Graph functionality is disabled. [verbose] AutoSession functionality is disabled. [verbose] Summary functionality is enabled. 02/02/2013 06:20:20 type: Event attr: HeadbandUndocked 02/02/2013 06:20:30 type: SleepStage attr: Undefined 02/02/2013 06:21:00 type: SleepStage attr: Undefined 02/02/2013 06:21:30 type: SleepStage attr: Undefined 02/02/2013 06:22:00 type: SleepStage attr: Undefined 02/02/2013 06:22:30 type: SleepStage attr: Undefined 02/02/2013 06:23:00 type: SleepStage attr: Undefined 02/02/2013 06:23:30 type: SleepStage attr: Undefined 02/02/2013 06:23:54 type: Event attr: NightStart 02/02/2013 06:24:00 type: SleepStage attr: Light 02/02/2013 06:24:30 type: SleepStage attr: Light 02/02/2013 06:25:00 type: SleepStage attr: REM 02/02/2013 06:25:30 type: SleepStage attr: REM 02/02/2013 06:26:00 type: SleepStage attr: REM 02/02/2013 06:26:30 type: SleepStage attr: REM 02/02/2013 06:27:00 type: SleepStage attr: REM 02/02/2013 06:27:30 type: SleepStage attr: REM 02/02/2013 06:28:00 type: SleepStage attr: REM 02/02/2013 06:28:30 type: SleepStage attr: REM 02/02/2013 06:29:00 type: SleepStage attr: REM 02/02/2013 06:29:30 type: SleepStage attr: REM 02/02/2013 06:30:00 type: SleepStage attr: REM 02/02/2013 06:30:30 type: SleepStage attr: REM 02/02/2013 06:31:00 type: SleepStage attr: REM 02/02/2013 06:31:30 type: SleepStage attr: REM 02/02/2013 06:32:00 type: SleepStage attr: REM 02/02/2013 06:32:30 type: SleepStage attr: REM 02/02/2013 06:33:00 type: SleepStage attr: REM 02/02/2013 06:33:30 type: Event attr: SleepOnset 02/02/2013 06:33:30 type: SleepStage attr: REM 02/02/2013 06:34:00 type: SleepStage attr: REM 02/02/2013 06:34:30 type: SleepStage attr: REM 02/02/2013 06:35:00 type: SleepStage attr: Light 02/02/2013 06:35:30 type: SleepStage attr: Light 02/02/2013 06:36:00 type: SleepStage attr: Light 02/02/2013 06:36:30 type: SleepStage attr: REM 02/02/2013 06:37:00 type: SleepStage attr: Light 02/02/2013 06:37:30 type: SleepStage attr: REM 02/02/2013 06:38:00 type: SleepStage attr: REM 02/02/2013 06:38:30 type: SleepStage attr: REM 02/02/2013 06:39:00 type: SleepStage attr: REM 02/02/2013 06:39:30 type: SleepStage attr: Light 02/02/2013 06:40:00 type: SleepStage attr: REM 02/02/2013 06:40:30 type: SleepStage attr: Light 02/02/2013 06:41:00 type: SleepStage attr: Light 02/02/2013 06:41:30 type: SleepStage attr: REM 02/02/2013 06:42:00 type: SleepStage attr: REM 02/02/2013 06:42:27 type: Event attr: HeadbandDocked [verbose] Session Ended by virtue of HeadbandDocked ----------[ Session Summary ]---------- Undefined: 4.0 mins (0 h, 4 m, 0 s) Awake: 0.0 mins (0 h, 0 m, 0 s) REM: 14.0 mins (0 h, 14 m, 0 s) Light: 4.5 mins (0 h, 4 m, 30 s) Deep: 0.0 mins (0 h, 0 m, 0 s) --------------------------------------- Total: 18.5 mins (0 h, 18 m, 30 s) box:~$
Using zeosleep with zeograph
Coming soon.