Introduction

This repo contains the programs that utilize the PIRDS data format to dynamically render respiration data, for example that generated by the VentMon (but anyone is free to generate and render PIRDS data some other way.)

We use the code on our free, public, data lake. If you go there and click on one of the "Breath Plot" links you will see a rendering of respiration data. It may even be live, if you choose one which happens to be actively logging at the time you look at it.

The purpose of this repo is to allow you to do the same thing locally, if for some reason, such as privacy concern or for experimentation, you wish to do so. However you are also welcome to use our "data lake" free of charge.

PIRDS-datalogger and webcgi

There are two related but separate programs: 1) the pirds_logger, which will listen for, receive, parse and store data from VentMon devices and 2) pirds_webcgi, which reads stored data and returns raw, or json formatted data.

There are two versions of the pirds_webcgi (c program and bash script) - both are designed to be called from a web server (more specifically Apache) as a standard CGI program.

Running the pirds_logger

The program "pirds_logger" is pretty simple. Just run it; it listents on port 6111 by default.

Running it with a VenMon (or any other program that write PIRDS data events on separate lines to a port via UDP) automatically logs PIRDS events into a file that looks like:

0Logfile.192.134.125.1.173

(base on your ip address.) This file contains PIRDS data organized by the time that they come in (NOT the important "ms" field in the event.)

That's all the logger does; it's only interacton with the web server is the log file produced.

Recommended Usage of the Web Server

The directory contains two web servers:

pirds_webcgi pirds_webcgi.script

These "CGI" scripts can served with an webserver. An example of how to do this with the popular Apache web server by creating a virtual directory. You will not be able to use this on your own computer; consider only an example and starting point.

In doing this way, I make a symbolically link "index.cgi" to either "pirds_webcgi" or "pirds_webcgi.script".

If you run the webserver on "localhost", the "breath_plot.html" respiration page will render respiraton data on your computer. If pirds_logger is running and adding data to the log file, this will be live.

<VirtualHost *:80> # The ServerName directive sets the request scheme, hostname and port that # the server uses to identify itself. This is used when creating # redirection URLs. In the context of virtual hosts, the ServerName # specifies what hostname must appear in the request's Host: header to # match this virtual host. For the default virtual host (this file) this # value is not decisive as it is used as a last resort host regardless. # However, you must set it for any further virtual host explicitly. # ServerName ventmon.coslabs.com ServerName localhost

    ServerAdmin webmaster@localhost
    DocumentRoot /usr/local/var/www

    # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
    # error, crit, alert, emerg.
    # It is also possible to configure the loglevel for particular
    # modules, e.g.
    #LogLevel info ssl:warn

    # ErrorLog ${APACHE_LOG_DIR}/error.log
    # CustomLog ${APACHE_LOG_DIR}/access.log combined

    # For most configuration files from conf-available/, which are
    # enabled or disabled at a global level, it is possible to
    # include a line for only one particular virtual host. For example the
    # following line enables the CGI configuration for this host only
    # after it has been globally disabled with "a2disconf".
    #Include conf-available/serve-cgi-bin.conf



    Alias "/breath_plot" "/usr/local/var/www/breath_plot.html"
    Alias "/breath_plot.html" "/usr/local/var/www/breath_plot.html"
    ScriptAliasMatch "/webserver.cgi" "/usr/local/var/www/cgi-bin/webserver.cgi"
    ScriptAliasMatch "/*" "/usr/local/var/www/cgi-bin/index.cgi"

    <Directory /usr/local/var/www/cgi-bin>
      AllowOverride None
      Options +ExecCGI -MultiViews
      AddHandler cgi-script .cgi
    </Directory>

Making (compiling) yourself

The PIRDS-logger functionality requires the PIRDS C-language library to compile into an executable.

We recommend you dowload the repo, run "make" in the pirds_library directory there, then copy the PIRDS.h and PIRDS.o files into this directory as PIRDS-1-1.h and PIRDS-1-1.o. This should allow you to "make" the logger and the webserve here on your own computer. This will allow you to implement your own (local) data lake, which you may keep private or make public.

Unit Tests for the Server

In July we started adding a feature to the server to provide samples from an input point in time. (Previously we had returned only the most recent samples.) This feature is based on the PIRDS wall-clock time events being injected into the stream.

Because this is complicated enough, we implemented a unit test. Since we mostly consume this data with JavaScript, the tests are in Node.js.

To run, install Node.js, Mocha and Chai

npm install --save-dev mocha npm install --save-dev chai npm install --save-dev sync-request npm run test