Package: persair
Table of ContentsQuick OverviewWarning, Will Robinson!dockerLinuxWindowsPurpleAir API keysOverviewInstallationUsingPyPIUsing CLIRunningEcosystemEnvironmentLinuxWindowsCommand line argumentsExamplesQuick Overviewpersairis 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 richpfairinstallation.Warning, Will Robinson!If you wish to usepersairon your own computer, you do need to note these prerequisites:dockerData thatpersairuses is stored in a monogdb database that is run on your computer. See below for installation instructions:LinuxSeethe official Linux instructions.WindowsSeethe Windows Docker Desktop instructions.PurpleAir API keysThe final requirement are the PurpleAIR API keys, needed to access the PurpleAIR API. You can get your own free keysfrom here. If you are here from Project Tanguro, please contactrudolph.pienaar@gmail.comfor those relevant keys. Once you have your keys, save them in ajsonfile:{"tanguro":{"ReadKey":"5510DCF0-D742-11ED-BD21-420105480008","WriteKey":"7A1FBDA0-DD68-11ED-BD21-420105400008"}}(Note those are not actual keys!)Overviewpersair(thepersis a play on the wordpurple) 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,persairprovides the means to pull sensor data and archive them in a separate data base with easy/free access.One of the use cases ofpersairis to scan a set of sensors and check if any are off-line (as indicated by thelast_seenfield for the sensor when queried in PurpleAir).InstallationUsingPyPIThe best method of installing this script and all of its dependencies is by fetching it from PyPI usinga python virtual environment.pip3installpersairUsing CLIAlternatively, from a cloned version of the repository:pip3install-rrequirements.txt-U./RunningEcosystemAssuming you havedockeranddocker-composeon your system, dodocker-composeup-dEnvironmentSeveral environment variables need to be set prior to runningpersair:LinuxexportMD_DB=tanguro&&exportDBauthPath=/home/dicom/services/pfair.json&&\exportMD_URI=mongodb://localhost:27017&&exportReadWriteKey=tanguroIn the above, the/home/dicom/services/pfair.jsonis the full path of the key-file you might have created earlier. Obviously, your location will vary. For the case of Windows, use Windows Powershell andWindows$env:MD_DB=tanguro$env:DBauthPath=C:\users\me\key.json$env:MD_URI=mongodb://localhost:27017$env:ReadWriteKey=tanguroCommand 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.ExamplesList all the sensor indices in a group:persair--sensorsInGroupList--usingGroupID1700Get (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--sensorDataGet103270Get only some fields for a given sensor:persair--sensorDataGet103270--fieldstemperature,last_seen,latitude,longitudeGet some historical data for a give sensor:persair--sensorDataGet103270--fieldstemperature\--asHistoryCSV--start_timestamp2023-06-01--end_timestamp2023-06-02