The PurpleAir Utility
The PurpleAir Utility is a tool that allows the user to interact with a PurpleAir sensor directly.
This tool enables you to:
- Flash a copy of firmware onto a sensor.
- Erase the firmware on a sensor.
- View the output from a sensor.
- View data from the sensor’s serial port on a graph in real-time.
- Process and view data created on a microSD card from a PurpleAir SD edition sensor.
Requirements
The Utility will only work on MacOS up to version 12.2.1
- A computer running MacOS or Microsoft Windows.
- A micro USB data cable to connect your PurpleAir sensor to the computer.
- A minimum of 120 MB of free space on your computer.
Download and Install
-
Download the PurpleAir Installer for your system:
- Windows: http://update.purpleair.com/desktop/PurpleAir-1.0.6.exe
- Mac: http://update.purpleair.com/desktop/PurpleAir-1.0.6.pkg
If the link does not open, copy and paste it into the address bar in a new tab.
- Windows: http://update.purpleair.com/desktop/PurpleAir-1.0.6.exe
-
Run the installer and follow the instructions given (Note: Mac users may need to right-click the downloaded file and select either “run” or “open” to run the installer the first time).
Using the Utility
When the utility is opened, the startup screen provides information on using the application, as well as a link to install USB drivers if necessary.
How to Select Your Sensor’s Serial Port
Connecting your sensor requires a data cable. You may need to try multiple micro USB cables before finding one that’s a data cable.
- Connect your PurpleAir sensor to your computer with a micro USB cable.
- In the utility under “Select a Serial Port,” select the port for your sensor. Windows users will see a port name such as ‘COM2’, while Mac users will see a port name containing ‘usb-serial’.
- Select the action you would like to perform (Connect, Flash, or Monitor).
Troubleshooting:
How can I tell which port is my sensor?
If you’re unable to tell which port corresponds to your sensor, unplug it from your computer and reopen the “Select a Serial Port” dropdown menu. The port that no longer appears will be the one for your sensor. Plug the sensor back into your computer, reopen the “Select a Serial Port” dropdown menu, and your sensors port should now reappear.
What if my sensor doesn't appear in 'Select a Serial Port'?
First confirm that your sensor is successfully powered.
If your sensor powers on successfully, but no port appears for it in the “Select a Serial Port” dropdown, the USB cable you’re using is likely not a data cable. Many USB cables only provide power, and the Utility requires a data cable to communicate with your sensors.
If you can confirm the cable you’re using is a data cable, but you still don’t see your sensor’s port, download the USB drivers using the “Install USB Drivers” link.
Connect and View Sensor Logs
Sensor logs are described in our Understanding PurpleAir Serial Output article.
You can view your sensor’s real-time output using the Utility with the following steps:
- If your device has an SD card, remove it temporarily.
- Select your sensor’s Serial port.
- Press “Connect.”
- Allow the utility to run for around ten seconds. After that, the sensor logs should begin to appear.
Why does the Utility only say 'append 19700101.csv' after connecting my sensor?
Your sensor will only output logs when no SD card is inserted. If you see this message, perform the following steps to see sensor logs:
- Unplug your sensor.
- Remove the inserted microSD card.
- Reconnect your sensor to the Utility.
Copy the Logs
You can copy log text to your computer’s clipboard by either:
- Clicking the “Copy” button at the top right - This will copy log output to your computer’s clipboard.
- Clicking the logs five times - This converts the area to a text box, where you can directly copy all text. Pressing enter will revert back to the formatted view.
Once you’ve copied the text, you can paste it by pressing ctrl+v (Windows) or cmd+v (Mac).
new messages will still be shown in text box view.
Flashing Firmware and Erasing Memory
This information has moved here: How to Flash Firmware to Your Sensor
Merge and Clean SD Card Data with the SD Data Tool
You can merge and clean data collected with your sensor’s SD card with the utility. To do this, click “SD Data Tool” in the top right.
This button allows you to merge multiple SD card data files produced by an SD-capable PurpleAir sensor into a single file. It also recovers all CSV data that may be present in any log files on the SD card.
Using the SD Data Tool to Recover Missing Data
Sensor data is normally recorded in CSV files. However, it’s possible for data to be improperly recorded to .log or .TXT files. If data appears to be missing from CSV files, this can be a potential cause. Using the SD Data Tool, the Utility will find sensor data recorded in these other files and recover it. An example is included below:
For this example, a sensor with ID 4:f9:72:bf:cc:d9 has recorded sensor data into the following .csv, .log, and .TXT files:
-
20240412.csv
-
20240413.csv
-
20240412.log
-
20240413.log
-
LOG00001.TXT
-
LOG00002.TXT
Within the CSV files, data is missing for several hours. To search for recoverable data, we’ll place all files from the SD card into a folder. We’ll then click on the SD Data Tool button, set the “Source” as the folder where our files are located, and set the “Destination” to where we want all recoverable data to be located. We’ll then click “Clean & Merge Files” to find all recoverable sensor data within the Source folder. No files within the Source folder will be changed. The resulting files in our Destination location will be as follows:
-
4_f9_72_bf_cc_d9.csv – This contains all sensor data from 20240412.csv and 20240413.csv
-
4_f9_72_bf_cc_d9.log – This contains all sensor data from 20240412.log and 20240413.log
-
4_f9_72_bf_cc_d9.TXT – This contains all sensor data from LOG00001.TXT and LOG00002.TXT
-
MERGE_RESULTS_1714584289.TXT
-
merged_log_1714584289.TXT
-
merged_txt_1714584289.TXT
The 4_f9_72_bf_cc_d9.log and 4_f9_72_bf_cc_d9.TXT files are actually CSV files. They are named “.log” and “.TXT” to indicate where the data they contain was recovered from. Since these files do not end in “.csv”, you will need to change their file type to .csv or manually import them into Excel to open them.
To have a single dataset containing all recorded SD data, we can manually combine all data from 4_f9_72_bf_cc_d9.csv, 4_f9_72_bf_cc_d9.log, and 4_f9_72_bf_cc_d9.TXT into a single file.
Explanation of Buttons / UI
Special keys
The PurpleAir utility’s startup screen uses no special key functions or shortcuts.
Buttons Along the Top
| Button | Description |
|---|---|
| Serial port drop-down | Used when selecting your sensor’s serial port. When using the ‘Monitor’ feature, you do not need to select the port before using the Monitor button. |
| Connect button | Once you’ve selected your sensor’s serial port, you can press the “Connect” button to view sensor logs. |
| Flash selection drop-down | Allows you to select an action to perform on your sensor. You’ll need to ensure you’ve properly selected your sensor’s serial port. Options are SensorFirmware6.02f.bin and Erase ALL Memory. |
| Copy button | Use this button to copy all text in the console window. This is the area on the startup screen that displays messages from the sensor as well as the help text. If clicking this button fails to copy the Console text, click five times on the console text. This converts it to a text box that allows you to copy it directly. Pressing Enter will revert back to the formatted view. Please note that new messages will be shown in this text box view. |
| Clear button | This button clears the console of all messages. |
| Monitor button | This opens the Monitor interface that is used to view real-time data from connected sensors, data from an SD card, or previously recorded data produced by the Monitor tool. |
| SD Data Tool button | This button allows you to merge multiple SD card data files produced by an SD-capable PurpleAir sensor into a single file. It also recovers all CSV data that may be present in any log files on the SD card. If data is recovered, it will be contained within separate files, requiring you to manually combine the full dataset. Make sure to follow the example above titled “Using the SD Data Tool to Recover Missing Data” for further details. |
The PurpleAir Utility’s Monitor Screen
The monitor screen is accessed by pressing the Monitor button on the startup screen. It provides the interface for analyzing existing data, as well as collecting real-time data from a sensor or sensors connected to a serial port.
After opening the monitor screen, you can click in the bottom left to select a location to record any sensor data to. This will be recorded in the format described in our Understanding PurpleAir Serial Output article.
The Utility will remember the selected location, and the next time you reopen the monitor screen and you will see the data you previously recorded.
Before clicking the monitor button, you’ll want to make sure your sensor is connected with a USB data cable, but do not click the “Connect” button.
Data tabs
Each data type has its own tab along the top of the monitor screen.
Certain data tabs contain ATM or CF1 data, described in our What is the Difference Between CF=1, ATM, and ALT article.
| Tab Name | Description |
|---|---|
| PM1.0 ATM | The mass concentration of particles with an average diameter of 1 micrometer (1μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses ATM. |
| PM2.5 ATM | The mass concentration of particles with an average diameter of 2.5 micrometers (2.5μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses ATM. |
| PM10 ATM | The mass concentration of particles with an average diameter of 10 micrometers (10μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses ATM. |
| AQI ATM | The PM2.5 ATM value converted to the US EPA PM2.5 AQI. |
| PM1.0 CF1 | The mass concentration of particles with an average diameter of 1 micrometer (1μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses CF1. |
| PM2.5 CF1 | The mass concentration of particles with an average diameter of 2.5 micrometers (2.5μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses CF1. |
| PM10 CF1 | The mass concentration of particles with an average diameter of 10 micrometers (10μm) or less. This parameter is measured in μg/m3, or micrograms per cubic meter of air. Uses CF1. |
| AQI CF1 | The PM2.5 CF1 value converted to the US EPA PM2.5 AQI. |
| 0.3μm | The number of particles with a diameter >= 0.3 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| 0.5μm | The number of particles with a diameter >= 0.5 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| 1.0μm | The number of particles with a diameter >= 1.0 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| 2.5μm | The number of particles with a diameter >= 2.5 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| 5.0μm | The number of particles with a diameter >= 5.0 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| 10μm | The number of particles with a diameter >= 10 micrometers. This parameter is measured in μm/dL, or micrometers per deciliter of air. |
| T | The temperature inside the sensor’s housing. This is different from ambient conditions but can be corrected |
| H | The humidity inside the sensor’s housing. This is different from ambient conditions but can be corrected. |
| DP | The dew point inside the sensor’s housing in Fahrenheit. This value is calculated using uncorrected temperature and humidity, |
| P | Current pressure in millibars. |
| ADC | The voltage reading on the analog input of the control board. |
| Mem | Free HEAP memory on the control board. |
| RSSI | WiFi signal strength in dBm. |
| U | This is the Uptime, or the amount of time the sensor’s CPU has been running since it was powered up. |
| ^ or v | This switches all separate graphs to be displayed on one large graph or switches back to the individual graph view. |
Keyboard Shortcuts and Special Actions
| Key | Action |
|---|---|
| A | Toggle the graph for Channel A. |
| B | Toggle the graph for Channel B. |
| R | Toggle the dots that represent the ‘R^2’ correlation data. |
| Numbers 0-9 | set the graph to use the last x% of the data present. 1 is 10%, 2 is 20%, etc. 0 is 100%. |
| L | Toggle ‘live’ data traces. These are the lighter colors of red and blue and represent the real-time or live data coming from the sensor. This is only applicable for sensors currently connected to the serial port(s) or data that was previously recorded. |
| M | Toggle ‘median’ or averaged data traces. These darker red and blue colors represent data that is present on SD card files as well as the sensors connected to the serial port, or data recorded from sensors that were previously connected to the serial port. |
| SHIFT | Toggle a vertical line that shows the data values under the cursor for all displayed sensors. |
| Zooming | Click and drag a box around the data you are interested in seeing close-up. If there are multiple sensors connected, this will zoom all windows to allow a side-by-side comparison. You may zoom in further by clicking and dragging a new box around an area of interest. To reset the zoom, right-click twice in the graph. |
Learn More
How to Obtain Sensor Data
SD Card Logging and Troubleshooting
SD Card File Headers
Understanding PurpleAir Serial Output
