Hamlin Canary

Air quality monitoring and reporting

Hamlin Canary runs at scheduled intervals, queries purpleair sensors, and sends a notification if the particle count is above the healthy threshold.

The Hamlin Sensors

There are two purpleair sensors on the Hamlin campus:

• Science Labs
• Broadway

These sensors continuously monitor local air quality and expose a 'webpage' that contains the current sensor data in JSON format. The code in this repository in combination with the resources described below periodically reads the sensor data and sends a notification when appropriate.

Resources

To enable the Hamlin Canary a few different resources are stitched together. The logic that this code implements needs to run somewhere. The running of the logic needs to be scheduled. To ensure that we only run the code once per scheduled interval, state must to be maintained. When the code runs, if the particulate level is above a safe threshold a notification needs to be sent to the appropriate individuals.

Hamlin Canary is built using Amazon Web Service (AWS) resources. Each resource used is described below.

Logic: AWS Lambda

AWS Lambda is a service for running code without a dedicated computer. Lambda is useful for discreet 'pieces' of functionality like the Hamlin Canary.

The configuration of the Lambda Function can be viewed and edited using the Lambda Console which requires an AWS account with appropriate permissions.

The Lambda Function runs the code in this GitHub repository. The entry point for the Lambda is a handler method which is triggered by the schedule resource. The documentation for the AWS Lambda Function Handler in Node.js

Three pieces of information are maintained in the Lambda Function configuration rather than being 'hard coded' into the javascript in this repository:

• CANARY_READING_THRESHOLD - the particle value above which an alert should be sent
• CANARY_SERVER_LIST - a comma separated list of sensor URLs to check
• CANARY_SNS_TOPIC_ARN - the resource where notifications are posted

Schedule: AWS CloudWatch

The Hamlin Canary runs on a predefined schedule. AWS CloudWatch is used to 'trigger' the Lambda Function at a preset interval. The schedule can be set in the CloudWatch Console which requires an AWS account with appropriate permissions.

State: AWS DynamoDB

To ensure that data collection is idempotent, the Hamlin Canary Lambda Function stores each CloudWatch event in DynamoDB using the CloudWatch event.id as the unique key to prevent multiple runs with the same id. The source of events, AWS CloudWatch, guarantees at least one delivery but can't guarantee that you won't receive more than one event. To read more about it, read this.

To view the data in the CanaryLog table, use the DynamoDB Console which requires an AWS account with appropriate permissions.

Notification: AWS SNS

When a reading is above the threshold a notification is sent to interested individuals. Individuals can subscribe (and unsubscribe) to these notifications. The AWS Simple Notification Service (AWS SNS) is used to reliably deliver notifications. The current list of subscribers can be viewed in the SNS Console which requires an AWS account with appropriate permissions.

To Code:

The code in this repository is javascript written to run on the NodeJs runtime.

To edit, test, and deploy the code in this repository a computer must meet the following pre-requisites:

• git
• NodeJs
• an AWS account and credentials with appropriate permissions
• obtain and set the environment variables: CANARY_READING_THRESHOLD, CANARY_SERVER_LIST, and CANARY_SNS_TOPIC_ARN

Install the code:

cd ~/code
git clone [email protected]:HamlinSchool/HamlinCanary.git
cd HamlinCanary
npm install

Test code on development computer:

npm start

To deploy code to AWS Lambda

npm run deploy

Some ideas for further exploration...

• Store the data to produce graphs and calculate: mean, median, standard deviation, etc.
• Understand what each of the dependencies does, why it is used, and understand its documentation
• Enable delivery of notifications via SMS
• Add unit tests which would allow for auto-update of dependencies
• Specify the name of the JSON key for data value to check using an environment variable so it can easily be changed without changing code

_{Disclaimer: this software and configuration is not professionally monitored or rigorously tested. Use at own risk.}