Quick Overview

• persair is a python client (CLI and API) for retrieving data from sensors registered to the PurpleAir API.

• while completely useful in its own right, it is perhaps best (i.e. no mess no fuss) deployed as part of a larger, more feature rich pfair installation.

Warning, Will Robinson!

If you wish to use persair on your own computer, you do need to note these prerequisites:

{
       "tanguro":      {
               "ReadKey":      "5510DCF0-D742-11ED-BD21-420105480008",
               "WriteKey":     "7A1FBDA0-DD68-11ED-BD21-420105400008"
       }
}

Overview

persair (the pers is a play on the word purple) is a both a standalone script and a python module that provides the means to interact with the PurpleAir API and retrieve sensor information. Together with the app itself, this repo also provides a supporting ecosystem of a monogdb container that is used to persist data pulled from PurpleAir.

While the PurpleAir mission is to enable community driven science, accessing the API does carry a small monetary cost. Without commenting on that reality, persair provides the means to pull sensor data and archive them in a separate data base with easy/free access.

One of the use cases of persair is to scan a set of sensors and check if any are off-line (as indicated by the last_seen field for the sensor when queried in PurpleAir).

Installation

pip3 install persair

pip3 install -r requirements.txt -U ./

Running

docker-compose up -d

export MD_DB=tanguro && export DBauthPath=/home/dicom/services/pfair.json &&\
export MD_URI=mongodb://localhost:27017 && export ReadWriteKey=tanguro

$env:MD_DB=tanguro
$env:DBauthPath=C:\users\me\key.json
$env:MD_URI=mongodb://localhost:27017
$env:ReadWriteKey=tanguro

Command line arguments

[--mongodbinit <init.json>]
The mongodb initialization file.

[--version]
If specified, print app name/version.

[--man]
If specified, print this help/man page.

[--sensorDataGet <sensorRef>]
Get data for sensor <sensorRef>. This can either be a sensor index
or a sensor ID. Set the ref type with --sensorRefType.

[--fieldsList]
If specified, print information about the fields can be passed to the
"fields" parameter.

[fields <comma,separated,list>]
A comma separated list of field data to retrieve.

[--asHistory | --asHistoryCSV]
If specified, do a "history" retrieve (optionally as CSV data)

[--start_timestamp <%Y-%m-%d>]
For a "history" retrieve, the start timestamp.

[--end_timestamp <%Y-%m-%d>]
For a "history" retrieve, the end timestamp.

[--sensorRefType sensor_index|sensor_id]
Set the specific reference "type" for sensors. This must be one of
either 'sensor_id' or 'sensor_index'. Default is 'sensor_index'.

[--sensorAddToGroup <sensorRef>]
Add the sensor referenced by <sensorRef> to a group. The group is
additionally specified with the --usingGroupID CLI.

[--sensorsAddFromFile <filename>]
Add all sensors referenced in <filename> to the group defined by
--usingGroupID. References in the <filename> should only contain
a single sensor per line.

[--sensorsInGroupList <groupid>]
List all sensors in <groupid>.

[--usingGroupID <groupid>]
CLI for additionally specifying a <groupid> to use in conjunction
with several sensor operations.

Examples

• List all the sensor indices in a group:

persair --sensorsInGroupList --usingGroupID 1700

• Get (all) the data for a given sensor (note this carries an actual _cost_ in tokens which if exhausted need to be topped off/purchased):

persair --sensorDataGet 103270

• Get only some fields for a given sensor:

persair --sensorDataGet 103270 --fields temperature,last_seen,latitude,longitude

• Get some historical data for a give sensor:

persair --sensorDataGet 103270 --fields temperature \
  --asHistoryCSV --start_timestamp 2023-06-01 --end_timestamp 2023-06-02