The PurpleAir Utility

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.

Before you start, you will need:

  • 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.

To download and install the PurpleAir Utility:

  1. Download the PurpleAir Installer for your system:

  2. 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 PurpleAir 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.

View Sensor Logs: You can view your sensor’s real-time output with the utility.

  1. Connect your PurpleAir sensor to your computer with a micro USB cable.
  2. In the utility under “Select a Serial Port,” select the port for your sensor (it is likely that it will have “usbserial” in the name). If you do not see your sensor’s port, download the USB drivers using the “Install USB Drivers” link.
  3. If your device has an SD card, remove it temporarily.
  4. Press “Connect.”
  5. Allow the utility to run for around ten seconds. After that, the sensor logs should begin to appear.

Flash Firmware: The utility is able to re-flash firmware onto your PurpleAir sensor.

  1. Connect your sensor to the utility by following the steps to “View Sensor Logs” above.
  2. Once your sensor has been connected, select the firmware to flash onto your device under “Select a Flash Action” (will most likely be named “SensorFirmware6.02f.bin”).
  3. Press “Flash.”
  4. This may cause your sensor to disconnect from the WiFi. If your sensor has disconnected, follow the steps here to reconnect your device.
  5. Once you have confirmed that your sensor is online and reporting, you can disconnect the device from your computer.

If flashing the firmware has been unsuccessful, you can try following the steps under Erase a Sensor’s Flash Memory first.

Erase a Sensor’s Flash Memory: With the utility, you can completely erase your sensor’s flash memory.

  1. Connect your sensor to the utility by following the steps to “View Sensor Logs” above.
  2. Once your sensor has been connected, select “Erase ALL Memory” under “Select a Flash Action.” This will both erase all memory, and flash new firmware onto the sensor.
  3. Press “Flash.”
  4. This may cause your sensor to disconnect from the WiFi. If your sensor has disconnected, follow the steps here to reconnect your device.
  5. Re-register your sensor at Register to place your sensor on the map | PurpleAir.
  6. Once you have confirmed that your sensor is online, registered, and reporting, you can disconnect the device from your computer.

Merge and Clean SD Card Data: You can merge and clean data collected with your sensor’s SD card with the utility.

  1. Transfer the files from your sensor’s SD card onto your computer.
  2. In the utility, press “SD Data Tool.” A popup window will appear.
  3. Change the source to the location where your SD card files are located.
  4. Change the destination to the location where you want to save your new files.
  5. Press “Clean & Merge Files.”

Interface Functions

Serial port drop-down

This drop-down contains a list of ports on the computer. If you are unsure of which one the sensor is using, disconnect the sensor and look at the list. Connect the sensor and refresh the list by reopening the drop-down. The sensor will be any new port that appears. Windows users will see a name such as ‘COM2’, while Mac users will see a name containing ‘usb-serial’.

When using the ‘Monitor’ feature, you do not need to select the port before using the Monitor button.

Connect button

After selecting a serial port, the Connect button will attempt to connect to a sensor on that serial port. This allows you to see what the sensor is sending from the port and can be useful for troubleshooting. We may ask you to share that text with us if you are having trouble with your sensor.

Flash selection drop-down

This drop-down allows you to perform actions on the sensor. You can flash a known, reliable firmware, select a firmware file to flash, or use the ‘erase’ feature to completely erase the firmware.

If you use the erase feature, you will need to do two things: 1) Flash a firmware file, and 2) Submit the registration form to reset the sensor’s data keys.

After selecting an option from this list, as well as a port, press the Flash button to perform the action.

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 edition PurpleAir sensor into a single file. It also “cleans” the data and collects all CSV data that may be present in any files on the SD card.

Special keys

The PurpleAir utility’s startup screen uses no special key functions or shortcuts.

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.

Data tabs

Each data type has its own tab along the top of the monitor screen.

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. ATM indicates measurements suitable for outdoor or “atmospheric” conditions.

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. ATM indicates measurements suitable for outdoor or “atmospheric” conditions.

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. ATM indicates measurements suitable for outdoor or “atmospheric” conditions.

AQI ATM

The PM2.5 ATM value converted to the US EPA PM2.5 AQI. ATM indicates measurements suitable for outdoor or “atmospheric” conditions.

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. CF1 indicates measurements suitable for indoor or “controlled” environments.

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. CF1 indicates measurements suitable for indoor or “controlled” environments.

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. CF1 indicates measurements suitable for indoor or “controlled” environments.

AQI CF1

The PM2.5 CF1 value converted to the US EPA PM2.5 AQI. CF1 indicates measurements suitable for indoor or “controlled” environments.

0.3μm

The number of particles whose diameter measures 0.3 micrometers or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

0.5μm

The number of particles whose diameter measures 0.5 micrometers or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

1.0μm

The number of particles whose diameter measures 1.0 micrometer or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

2.5μm

Number of particles whose diameter measures 2.5 micrometers or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

5.0μm

The number of particles whose diameter measures 5.0 micrometers or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

10μm

The number of particles whose diameter measures 10 micrometers or greater. This parameter is measured in μm/dL, or micrometers per deciliter of air.

T

The temperature inside the sensor’s housing - this temperature reading will be approximately 8 degrees higher than ambient conditions due to heat generated by the WiFi module in the sensor’s control board.

H

The humidity inside the sensor’s housing - this humidity reading will be approximately 4% lower than ambient conditions due to heat generated by the WiFi module in the sensor’s control board.

DP

The dew point inside the sensor’s housing in Fahrenheit. This value is calculated using the temperature and humidity, which are affected by the heat generated by the WiFi module.

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

‘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.

Keys ‘1’ through ‘0’: 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, click once on any graph.

4 Likes

The utility isn’t working. I have installed it on my MacBook Pro (running latest MacOS) and my windows PC (running latest windows 10 version). I have installed the requisite USB drivers according to the utility. In both scenarios the Serial Port doesn’t show any USB connections. For the Mac it only shows two bluetooth connections unrelated to the PurpleAir. On the windows PC when you click the serial dropdown box there isn’t anything to select.
I called PurpleAir because my PA-II stopped reporting and fell off about a month ago now. Now matter what I tried, and with call support (TRIED FOR DAYS TO GET PHONE SUPPORT), the board will not connect to wifi and the PurpleAir hotspot will not turn on so that I can connect directly.

NEED HELP!

Hi @tampahoosier, I wonder if this is due to the cable you are using to connect your device to the computer. Many cables are used only for charging and cannot transfer data. If you have another cable available, I would recommend trying it.

Hi,
I’m struggling to download from the SD card, the “clean and merge” just creates housekeeping text files. MERGE_RESULTS_xxxxxxx.TXT, merged_log_xxxxxx.TXT, ignore.txt and portlist.txt
Thanks
Jim (LeedsUniv)

Hi Jim, we’d like to try to replicate the issue. Can you describe in detail the steps that you’re taking before running into this issue?

2 Likes

Buenas noches, me encuentro en peru y estamos interesados en adquirir sensores para medicion de PM-2.5, cual seria el procedimiento, lo necesitamos para un proyecto de investigación en la universidad, gracias por la atencion
arojas@unsm.edu.pe

Hola, comuníquese con nosotros por correo electrónico a contact@purpleair.com.

Hi. What steps are taken when the SD Data Tool button is used to “clean” the data? Is there a description somewhere I could read? Thanks.

I’m getting an installation error from macOS Monterey. Is 1.0.6 the current release? Or should I be looking elsewhere for the most recent distribution? Thanks in advance for any advice!

It is the most recent distribution. You may need to go into System Settings > Privacy & Security. From there, scroll down to Security and enable installation of the file.

We don’t currently have a full explanation, but the main task that is completed is the data files are concatenated.

Hi Andrew,

This problem got put on pause, but I’d like to return to it.

I can connect to the purpleair device and it streams the data over USB when the card is popped out but I would like to download from the card without removing the sensor from when it is installed. I have a network of 50 sensors around the city of Leeds and they are fastened to lampposts so very difficult to access the card and reinsert, but it is fairly straight forward to plug data cable in.

A number of the sensors have corrupt file systems and the SD cards failed to record.

any thoughts? Many thanks Jim

how long should flashing the firmware take? I pressed it and it has been running for 20 minutes now and showing the sensor logs - I just want to flash the firmware.

Hi @AL.PurpleAir, flashing the firmware shouldn’t take longer than a minute or two. It’s likely that errors are being encountered. Try replying with the messages being provided in the Utility, or send the full text log to contact@purpleair.com for us to take a look at.

Hi Joshua, it is just continously showing data like this:

Hi Andrew,
Sorry, you might have missed this at the time, any comments?
Best regards
JIm

This means that the device was successfully flashed. After flashing, the sensor will disconnect and reconnect to the Utility. It will then take measurements and log them to the Utility. Each line in the provided screenshot represents measurements that your sensor has taken.

Does this utility work with the PA-II-FLEX. I am plugged into mine and it connected but that is about all I can do.

Rich

Hi @R_hurley, the Utility works with any PurpleAir sensor, including the Flex. The utility is commonly used to re-flash firmware for a sensor, but can also be used to view and record readings in real-time and merge data from an SD card into a single file.

Recent versions of MacOS are not yet supported for flashing on the Utility. If you’re unable to flash new firmware this may be reason.