alenia / aqiduck

Pulls data from PurpleAir AQI monitors and reports data to slack

AQIDuck

NOTE:

This is very data-intensive because it polls the API too frequently, and doesn't batch requests. If you want to use this I would recommend updating it for the new API calls. I am no longer using it myself. Feel free to branch and enjoy!

Purpose:

• Pull data from PurpleAir
• Report to Slack about air quality and temperature based on the channel topic
• Monitor AQI to let you know when it's safe to go outside or no longer safe to go outside based on thresholds you set
• Or Monitor AQI dynamically to let you know when AQI is trending up or down

Future additions:

• v2 will allow users to install the app on their slack instance from the app directory

Requirements:

This version requires some minor devops knowledge and understanding of how to get a slackbot up and running

• You must run the code off of some kind of server that has node on it
• You must be able to create a slackbot and set up slackbot event subscriptions

To install:

• Pull the code down onto your server
• Bundle running yarn install and run yarn build-ts to build the typescript files
• Get a PurpleAir API Key
• create a slackbot with the permissions app_mentions:read, channels:read, chat:write, channels:history, groups:read
• Set up slack event subscriptions:
  • expose a port and calling: ./node_modules/.bin/slack-verify --secret [Signing secret] --port [you pick the port, default 3000]
  • Put the URL of your app in the Event subscriptions part of the slack setup
  • You can find the signing secret in the basic information part of your slack setup
  • Subscribe to the events app_mention, channel_left, member_joined_channel, message.channels
  • cancel the slack-verify server so you can use that same port for the bot
• Make sure you have all the environment variables set up listed in the example.env
• Start the server using node . or running the dist/index.js file

To set up:

• invite the slackbot to various channels
• set the channel topic to include a JSON string about which PurpleAir sensors should be monitored, for example:

Whatever channel topic you want to write

***{"sensors": [{"name": "Sesame Street", "type": "PurpleAir", "id": 12345}]}***

Monitoring:

If you want your sensor to let you know if the AQI crosses specific boundaries, add AQIThresholds to the topic JSON like so: {"sensors": [{"name": "Whatever", "type": "PurpleAir", "id": 12345, "AQIThresholds":[50,80]}]} Note this currently doesn't validate that the first number is less than the second, and only looks at the first two items.

If you want your sensor to let you know whenever the AQI goes up or down by 5, set AQIMonitoring to dynamic: {"sensors": [{"name": "Whatever", "type": "PurpleAir", "id": 12345, "AQIMonitoring":"dynamic"}]}

If you want your sensor to let you know whenever the AQI crosses to a new category (e.g Good, Unhealthy), set AQIMonitoring to category: {"sensors": [{"name": "Whatever", "type": "PurpleAir", "id": 12345, "AQIMonitoring":"category"}]}

The bot will reload its configuration whenever the channel topic changes.

To talk to the bot:

• @AQIDuck report gives you the report
• @AQIDuck stop monitoring stops the monitoring
• @AQIDuck resume monitoring resumes the monitoring
• @AQIDuck hello says hi
• @AQIDuck reload reolads the config from the channel topic (this should happen automatically anyway)

To find your PurpleAir sensor ID:

• On the PurpleAir map, click on the sensor you're interested in
• The sensor ID will be in the URL:
• At the bottom of the widget with the air quality, hover over "Get This Widget"
• The ID in the div of the widget also contains the sensor ID

aqiduck's Issues

Use PurpleAir API

https://api.purpleair.com/

• get API key
• Use groups?

Use dotenv instead of secrets.json

Use Groups from the PurpleAir API

• On startup post https://api.purpleair.com/v1/groups with something like {name: "AQIDuck #{version} #{instance identifier}"} and save the group ID
• For each PA sensor post https://api.purpleair.com/v1/groups/:group_id/members with { "sensor_index": 12345 }
  • If I try to do this for the same sensor twice I get a 409 DuplicateGroupEntryError
• https://api.purpleair.com/v1/groups/:group_id/members?fields=pm2.5%2Cpm2.5_10minute%2Ctemperature%2Chumidity
  • note previously I was using temperature_a. The temperature field is averaged.
  • I probably also want name and something that will let me know if the sensor is offline

Report certain errors to slack

Some errors should post a slack message

• If there are API issues when reporting for the first time, post a message (probably depends on the error code from PA)
• If the JSON has unknown fields, post a message
  Future:
• If there are repeated issues monitoring the same endpoint, post a message

Let user know if AQI thresholds are set up correctly

I think right now that if the thresholds aren’t properly named (i.e. if the JSON keys are spelled wrong) the user won’t know that the bot isn’t monitoring anything. When config is loaded/reloaded, just announce what monitoring is going on

Allow bot to re-read channel config

If I can't subscribe to channel topic change events, do this by responding to @aqiduck reload or a slash command or something

Monitor AQI and report when it goes under or over set thresholds

Current implementation is working
TODO:

• write tests
• Add configuration setup to README

Don't monitor if there are no thresholds to monitor

Talk to the bot in order to CRUD sensors

This should also ideally change the channel topic

Comands:

• monitor [SensorName] AQI 40-50 "OK I'll let you know if the [SensorName] AQI drops below 40 or above 50"
• add sensor NAME ID (defaults to purpleair)
• remove sensor NAME
• reload re-initializes all sensors from the JSON

Eventually have conversations like:

• add sensor "By ID or by zip code?" ID "What is the sensor ID?" 12345 "What do you want to call the sensor?" name "Alright we're now set up in this channel to read from sensor 12345" (changes channel topic)

Allow user to enter zipcode instead of just sensor id

Properly handle being invited/uninvited from a channel

Set up sensors when invited to a channel, stop monitoring when uninvited

Monitor temperature

Basic: Set temperature thresholds to monitor
Advanced: Monitor comparison in temperature between two sensors.

Listen for slack messages and respond appropriately

For example @aqiduck report should respond with the report at that time.

This involves setting up a server to listen to messages coming from slack

Send slack messages when configuration JSON has validation errors

Stop all timers when the app was uninstalled or the tokens were revoked

Raw temperature from purple air sensor is too high

Subtract 8 from the results when reporting them

We’ve found that a correction of 8°F correlates closely to the ambient temperature, while a 4% correction correlates closely to the ambient humidity

AQI of exactly 50 reports green (#00ff00)

Expect 50 to be squarely yellow! Reported on github rather than elbow on the couch by request from @alenia <3