This article covers working with serial data, which requires technical knowledge. Our How to Obtain Sensor Data article details other ways to obtain sensor data.
Serial Data
PurpleAir sensors collect data every second and average it into “real-time” samples (typically for a 2-minute period). These real-time samples are sent to PurpleAir over WiFi and made visible on the PurpleAir Map. Serial data provides access to both reported samples and second-by-second measurements taken by the sensor. This can be used to create custom solutions interfacing with your sensor.
Data sent over serial is not in a standard format and requires additional processing. Our Understanding PurpleAir Serial Output describes how serial data is formatted.
Serial data is transmitted with a baud rate of 115200 and 8-N-1 encoding. If you see random or garbled text, ensure you’re listening with the correct baud rate.
USB Serial
Serial data is continuously output over the USB port, which is also used to power PurpleAir sensors. Connect your sensor to a computer with a USB data cable. Once connected, serial data will be available over the USB Serial port. TTY/CU devices for Mac/Unix or COM Ports for Windows.
This is how the PurpleAir Utility displays sensor data, though any program capable of monitoring USB Serial data can be used after connecting to the proper port.
If a TTY/CU device or COM Port does not appear for the sensor, ensure you’re using a data cable. Not every USB cable can transmit data, which is required to obtain serial data.
Viewing USB Serial Data in the Terminal
Ensure no SD card is inserted when viewing USB Serial Data, otherwise no data will be displayed.
MacOS
Using Screen to View USB Serial Data on MacOS
On MacOS you can quickly view serial data with the pre-installed terminal utility screen.
First, ensure your sensor is not plugged into your computer. Then, open a terminal and enter the following command to check for USB serial devices. The example output shows pre-existing USB serial devices, but there may also be no devices listed when you first run this command.
$ ls /dev/cu.usb*
cu.usbserial-1 cu.usbserial-2
Plug your sensor into your computer and re-enter the same command. A new USB serial device should appear for your sensor. In this example, the sensor’s USB serial device is “cu.usbserial-11110”.
$ ls /dev/cu.usb*
cu.usbserial-1 cu.usbserial-2 cu.usbserial-11110
After this, use the screen utility with the sensor’s USB serial device and the proper baud rate (115200). You’ll want to replace “cu.usbserial-11110” with the USB serial device name obtained in the previous step.
$ screen cu.usbserial-11110 115200
Once entered, you should see something like the following:
To exit the screen utility, enter ctrl+a followed by ctrl+\ and press y when asked if you want to quit.
Linux
Using Cat to View Serial Data on Linux
These steps were tested on a Raspberry Pi running Raspberry Pi OS. It’s possible that these steps may not work on other distributions. If you encounter any problems with these steps, ensure that:
- Your user is added to the
dialoutgroup.- You’re using the right serial device path.
- Your sensor doesn’t have an SD card inserted.
To access serial data without sudo permissions, your user will need to be added to the dialout group. You can add yourself to this group with the following terminal command:
sudo usermod -a -G dialout my-user-name
After this, log out and log back in for the group change to take effect.
Next, ensure your sensor is not plugged into your computer. Then, open a terminal and enter the following command to check for USB serial devices. The example output shows pre-existing USB serial devices, but there may also be no devices listed when you first run this command.
$ ls /dev/ttyUSB*
/dev/ttyUSB0 /dev/ttyUSB1 /dev/ttyUSB2 /dev/ttyUSB3
Plug your sensor into your computer and re-enter the same command. A new USB serial device should appear for your sensor. In this example, the sensor’s USB serial device is “/dev/ttyUSB4".
$ ls /dev/ttyUSB*
/dev/ttyUSB0 /dev/ttyUSB1 /dev/ttyUSB2 /dev/ttyUSB3 /dev/ttyUSB4
You can also access serial devices by using /dev/serial/by-id/unique-serial-id-here or /dev/serial/by-path/unique-path-for-device-here
After this, you can set the baud rate of the serial device to 115200 with the following command. You’ll want to replace /dev/ttyUSB4 with your sensor’s serial device path obtained in the previous step.
stty -F /dev/ttyUSB4 115200
Once the proper baud rate is set, you should be able to use any number of terminal utilities to read the serial output. The simplest one to use is the cat command
cat /dev/ttyUSB4
Once entered, you should see something like the following:
To exit the cat command you can use ctrl+c.
Connecting to Hardware Serial
PurpleAir sensors also allow you to connect directly to the RS232 TTL serial port. Using this port will obtain the same information as using the USB port.
WARNING:
The serial bus uses RS232 TTL, which works on voltages of 3.3 Volts. Soldering incorrectly, connecting the wrong pins, using the wrong voltage, or otherwise improperly connecting to the serial port can permanently damage your sensor.
Do not connect the serial ports directly to an RS232 9-pin connector. This will likely damage your sensor.
Serial Pins
You’ll need to connect to the ground (Gnd) and transmit (Tx) pins.
- On a classic sensor these are located on the PCB itself.
- On a Flex or Zen sensor, these are located on the BME sensor board plugged into the expansion port.
When listening to the signal from the Tx pin, the voltage level will be TTL (3.3 Volts). If the connected device expects a different voltage level, a level shifter can convert the signal to a voltage compatible with your connected device.
The 3.3V pin provides a voltage of 3.3 Volts that can be used to power a connected device, although very little current is available—in the region of 100 to 200 milliamps maximum. Five volts is also available at whatever current your power adapter is capable of, usually up to around 500 milliamps.
Second Generation Sensors - The PurpleAir Classic and the Discontinued PA-I Touch Indoor
Second-generation sensors with “classic” boards require soldering to establish a connection to the serial bus. The through holes used for Tx and Gnd are circled in the picture below:
As the through holes are directly on the device board, accessing them will require disassembly. Videos in our Sensor Replacement article can provide some direction for this.
Classic boards are also wrapped in Kapton tape, not shown in the picture above. The Kapton tape must be removed for soldering. Once finished, we recommend rewrapping the board in Kapton tape to protect it.
Third Generation Sensors - The PurpleAir Flex, Zen, and Touch Indoor
Third-generation sensors with “flex” boards have an expansion port. By default, the device’s BME sensor, used for measuring temperature, pressure, and humidity, is plugged into the expansion port. It’s circled in the picture below and can be removed using the steps in this video.
The BME board provides solder pads, allowing you to access the serial port while the BME board remains plugged into the expansion port. The solder pads for Tx and Gnd are circled below:
You can also remove the BME and use the expansion port yourself. The BME provides temperature, pressure, humidity, and experimental VOC readings, so your sensor will no longer report these after it is removed. One user has used Y-adapter cables to leave the BME board in the expansion port.