Operations Manual
- Introduction
- Powering the Device On
- Confirming the Device is Connected to Wifi
- Ensuring the Firmware is Up-to-Date
- Overview of the Display Panel
- Verifying Data Submission
- Verifying That the Device is Logging Data
- Query Data
- Troubleshooting
The Safecast Air Quality Monitoring Kit is a geo-tagged mobile sensor with Internet data sharing and wireless capability. It measures particulate matter, humidity, and temperature.
Particulate matter (PM, or particulate pollution) refers to a mixture of solid particles and liquid droplets found in the air. Some are emitted directly from smokestacks, unpaved roads, and other sources. However, most form in the atmosphere when other pollutants emitted from power plants, industry, and cars undergo chemical reactions. Many of these particles are so small that they’re invisible to the naked eye.
We inhale these particles into our lungs, where they cause respiratory and heart problems, including strokes and heart attacks. PM also contributes to haze.
The Safecast Air measures three different types of inhalable PM:
- PM10 - Particles with diameters 10 micrometers and smaller
- PM2.5 - Particles with diameters 2.5 micrometers and smaller
- PM1.0 - Particles with diameters 1 micrometer and smaller
It also measures relative humidity and temperature. Relative humidity refers to the amount of water vapor in the air, in relation to the total amount of water the air could hold at that temperature. Temperature refers to the temperature of ambient (outdoor) air.
Both of these factors affect the formation of PM and haze. Tracking humidity and temperature provides context for the PM data.
In addition, the Safecast Air records location, date, and time. The location data allows Safecast to map the measurements and understand the distribution of pollutants. Safecast uses the date and time information to track how PM concentrations change over time.
The device submits the measurements to the Safecast dataset for inclusion in an online global mapping system that Safecast developed in cooperation with the Massachusetts Institute of Technology’s (MIT) Media Lab. The do-it-yourself kit allows for customization, cost savings, and learning.
To turn the device on:
- Make sure the air sensor is connected to the PCB.
- Plug the USB into the Teensy.
- Plug the USB into a socket.
The device is equipped with a LED indicator that will automatically illuminate when the unit is powered on. The device does not have an off/on switch.
#Confirming the Device is Connected to Wifi
When the Safecast Air is connected to wifi, the wifi indicator at the bottom of the display panel will read “ok.”
You can also confirm that your Safecast Air is connected to wifi by logging into your router’s Web interface and look for it in the list of connected devices.
You can pull up the interface by plugging your router’s IP address into any browser window. If you don’t know your router’s IP address, you can look it up by following the instructions below.
- Click on the Wi-Fi icon in your computer’s menu bar.
- Select Open Network Preferences.
- Click on the Advanced… button.
- Select the TCP/IP tab.
- Copy the string of numbers and dots after Router and paste it into your browser’s address bar. Press Enter.
- Open the Start menu.
- Select Run.
- Type in cmd and click OK. The command window will open.
- Type ipconfig and press Enter.
- Copy the string of numbers and dots for Default Gateway. This usually refers to the router. Paste it into your browser’s address bar and press Enter.
You should see the login screen for your router’s administrative console.
- Log in with your credentials. If you haven’t set up your own custom login, you may need to refer back to the router’s documentation to find the default login.
- Next, look for a list of attached devices. Different router manufacturers may put this in different places.
- It will probably be a link or button named “attached devices,” “connected devices,” “DHCP clients,”or something similar. You may also find it under a link named “Wireless” or “Status.”
- Once you’ve found the list, check for the device_id.
If you don’t see the device in this list, check the safecast.txt file on your SD card to make sure you’ve edited it correctly.
#Ensuring the Firmware is Up-to-Date
Before using your device, you will need to make sure it is using the latest version of the Safecast software. The following instructions are for updating the software on a MacBook Pro using OS X 10.10.1. You may need to make slight alterations if your computer uses a different operating system.
Before you proceed, make sure that you’ve already installed the firmware files and related software.
If you’re new to updating Arduino, we also suggest you complete this quick tutorial. Start with "Install Arduino," and then practice with the Blink exercise. You will then apply this same logic to upload the Safecast files.
Thank you to Safecast Air Beta Tester John Stanke for outlining the steps to update the firmware.
The display has three columns. The leftmost column contains labels for the readings, the middle column shows the readings themselves, and the last column displays the unit of measurement.
| Indicator | Description | Notes |
|---|---|---|
| PM1 | particulate matter 1 micron or less in diameter | in micrograms per cubic meter of air |
| PM2.5 | particulate matter 2.5 microns or less in diameter | in micrograms per cubic meter of air |
| PM10 | particulate matter 10 microns or less in diameter | in micrograms per cubic meter of air |
| TEMP | temperature | in degrees Celsius |
| HUMD | relative humidity | as a percentage of water vapor in the air |
| FIX | status of GPS fix | Displays "true" when the GPS has a fix, and "false" when it does not. This may be a temporary issue due to the movement/visibility of GPS satellites. Note that it can take up to five minutes to get a GPS fix. |
| WIFI | the status of the wifi connection | should read “ok” |
If you are a Beta participant, you can confirm that your device is transmitting data to the Safecast database by visiting the URL you received from KitHub. The URL is unique to your device, and includes the device_id at the end of the string.
Here is a sample URL. Click on the URL to view the data associated with this particular device.
http://dev.safecast.org/en-US/measurements.json?device_id=50001
After the Beta period has ended, users will login into the Safecast site to retrieve their data.
To confirm that your device is logging data on the micro SD card, put it into the micro SD adapter, and then into your computer. If everything is working correctly, you should see a list of log files that looks like the image below.
Each individual file should look like the image below.
Formatted list of data readings (replace device id with your id) - http://dev.safecast.org/en-US/measurements?device_id=50000&order=captured_at+desc
How to use Excel to create a graph of your data in 30 minutes or less (thanks to Hendrik):
This example uses Excel but should also work with Google spreadsheets or a similar spreadsheet program.
- Use the Safecast API (replace with your device ID and the data range you want) to create a CSV file
http://dev.safecast.org/en-US/measurements?utf8=✓&device=50000&&since=28%2F03%2F2017+00%3A42%3A20&until=29%2F03%2F2017+00%3A42%3A20&commit=Filter&format=csv&options=with-headings
Note! Look at the ending for the csv option. Beware that if the query takes too long it will timeout. You can limit the query by dat, lon/lat. - Upload the CSV file into Excel, use Text to Column function to get multiple columns
- Make sure that Excel does not misunderstand the . as thousand separator (for some reason Excel was stubborn and I used the filter function to check for way-too-large-numbers and set the point/comma correctly by hand (about six times in over 1500 measurements)
- Remove all columns except date/time, values and units
- Use the pivot function on the three columns to get a table with five columns: date/time, TEMPC, HUMD%, PM1, PM2.5 with a value where there is one
- Select only the cells of the five columns without any sums at the end or at the right
- Create a line graph from that
This section addresses common issues that you may run into while setting up, assembling, and using the Safecast Air.
There are two common configuration file errors:
- display.println("error: config file");
- display.println(configuration.errorMsg())
This error may be due to zero bytes being received or invalid JSON.
Bad solder joints could cause this sort of problem - either zeros bytes or garbage bytes. There are a number of possible cases - e.g., the OpenLog might not be getting reliable power or ground. Alternatively, there could be an issue with the RX to TX lines between the teensy and the OpenLog. This problem can be fixed easily this with a soldering iron.
Another possibility is that the safecast.txt file doesn’t contain valid JSON code. This happens when it has been edited with a text editor that uses UTF-8 encoding instead of ASCII.
The configuration.errMsg() message will appear when information is missing from the configuration file. The message will also indicate what information is missing by displaying "no username," "no wifi_ssid," or similar text.
If no message is displayed, then either zero bytes are returned, or the firmware was unable to parse the data in the JSON in the file.
There is some test firmware for reading data from the OpenLog in the firmware/tests/read_file_test sub-directory. It is just a really short sketch read_file_test.ino which tries to read the SAFECAST.txt configuration file on the SD card. It prints (to the serial console) the number of bytes read and then tries to parse the file. It does this in loop. It could be useful for checking whether the hardware is OK.