/PMserial

Arduino library for PM sensors with serial interface

Primary LanguageC++MIT LicenseMIT

PMSerial

Arduino library for PM sensors with serial interface

Build Status GitHub issues GitHub license

Sensors

Plantower Tested Works Doesn't Work Not Tested Datasheet Notes
PMS1003 (aka G1) X en, cn
PMS3003 (aka G3) X en, cn No passive mode read
PMS5003 (aka G5) X en, cn
PMS5003S (aka G5S) X cn
PMS5003T (aka G5T) X
PMS5003ST (aka G5ST) X
PMS7003 (aka G7) X cn
PMSA003 (aka G10) X cn

Compatibility

MCU Tested Works Doesn't Work Not Tested Examples Notes
ATmega168 @ 8MHz X SoftwareSerial
Atmega168 @ 16MHz X 5V boards need 3.3V/5V level shifter
Atmega328 @ 8MHz X SoftwareSerial
Atmega328 @ 16MHz X 5V boards need 3.3V/5V level shifter
Atmega32u4 @ 8MHz X
Atmega32u4 @ 16MHz X HardwareSerial 5V boards need 3.3V/5V level shifter
Atmega2560 @ 16MHz X HardwareSerial 5V boards need 3.3V/5V level shifter
STM32f103c8 X HardwareSerial
STM32f103cb X HardwareSerial
ESP8266 X HardwareSerial SoftwareSerial OLED 64x48 needs EspSoftwareSerial@>=6.7.1
ESP32 X HardwareSerial SoftwareSerial OLED 64x48 Serial1 as SoftwareSerial

Usage

PMSx003 sensor type

The PMSx003 sensor type will infer the sensor type from the message header. The sensor type inference does not cover the PMS5003S and PMS5003T variants, see #10. PMS5003S and PMS5003T sensors need to be declared explicitly on the SerialPM constructor.

PMSx003 on HardwareSerial

#include <PMserial.h>
SerialPM pms(PMSx003, Serial);  // PMSx003, UART

void setup() {
  Serial.begin(9600);
  pms.init();                   // config serial port
}

void loop() {
  pms.read();                   // read the PM sensor
  Serial.print(F("PM1.0 "));Serial.print(pms.pm01);Serial.print(F(", "));
  Serial.print(F("PM2.5 "));Serial.print(pms.pm25);Serial.print(F(", "));
  Serial.print(F("PM10 ")) ;Serial.print(pms.pm10);Serial.println(F(" [ug/m3]"));
  delay(10000);                 // wait for 10 seconds
}

Setup for different MCU is covered on the HardwareSerial example.

PMSx003 on SoftwareSerial

#include <PMserial.h>
SerialPM pms(PMSx003, 10, 11);  // PMSx003, RX, TX

void setup() {
  Serial.begin(9600);
  pms.init();                   // config serial port
}

void loop() {
  pms.read();                   // read the PM sensor
  Serial.print(F("PM1.0 "));Serial.print(pms.pm01);Serial.print(F(", "));
  Serial.print(F("PM2.5 "));Serial.print(pms.pm25);Serial.print(F(", "));
  Serial.print(F("PM10 ")) ;Serial.print(pms.pm10);Serial.println(F(" [ug/m3]"));
  delay(10000);                 // wait for 10 seconds
}

Setup for different MCU is covered on the SoftwareSerial example.

ESP32 Serial1

On some ESP32 boards Serial1 default pins are connected to the flash. Using the standard constructor will cause a crash, see espressif/arduino-esp32#148.

// will crash the ESP32
SerialPM pms(PMSx003, Serial1);

Fortunately, it is possible to define alternative for pins by calling:

// define Serial1 pins
Serial1.begin(9600, SERIAL_8N1, <RX>, <TX>);

The PMSerial library uses this feature to implement the flexibility of SoftwareSerial

// define Serial1 pins
SerialPM pms(PMSx003, <RX>, <TX>);

The SoftwareSerial example uses Serial1 on pins 23 (RX) and 19 (TX). The HardwareSerial example uses Serial2.

Advanced usage

Sensor message/protocol

With the exemption of the PMS3003 and PMS5003ST, all supported sensors transmit particulate matter (PM) and number concentrations (NC) measurements in a 32 byte long message. The PMS3003 only transmit PM measurements in a 24 byte message. The PMS5003ST transmit PM, NC, temperature (T), relative humidity (RH) and formaldehyde concentration (HCHO) measurements on a 40 byte message.

On the examples, the PMSx003 sensor type will infer the sensor type from the message header and select the message length and decoding protocol accordingly. The supported protocols are:

message/protocol length PM NC T & RH HCHO sensors (aliases)
PLANTOWER_AUTO self discovery 3 auto PMSx003
PLANTOWER_24B 24 bytes 3 PMS3003
PLANTOWER_32B 32 bytes 3 6 PMS1003, PMS5003, PMS7003, PMSA003
PLANTOWER_32B_S 32 bytes 3 6 X PMS5003S, can not be self discovered
PLANTOWER_32B_T 32 bytes 3 4 X PMS5003T, can not be self discovered
PLANTOWER_40B 40 bytes 3 6 X X PMS5003ST

Additional measurements

The pms.read() method will request a new measurement set from the sensor and decode the sensor message. The has_particulate_matter()/has_number_concentration() methods indicate if the message was valid and PM/NC measurements were successfully decoded. Similarly the has_temperature_humidity/has_formaldehyde methods indicate if the message was valid and T & RH/HCHO measurements were successfully decoded, however this kind of additional measurements are only available on PMS5003S, PMS5003T and PMS5003ST sensors.

Decoded measurements

All measurements found in the sensor message will be decoded and stored in following member variables:

variable type[len] measurement particle diameter unit Notes
pm01 uint16_t PM <= 1.0 µm µg/m³ PM1.0, ultra fine particles
pm25 uint16_t PM <= 2.5 µm µg/m³ PM2.5, fine particles
pm10 uint16_t PM <= 10 µm µg/m³ PM10
n0p3 uint16_t NC >= 0.3 µm #/100 cm³
n0p5 uint16_t NC >= 0.5 µm #/100 cm³
n1p0 uint16_t NC >= 1.0 µm #/100 cm³
n2p5 uint16_t NC >= 2.5 µm #/100 cm³
n5p0 uint16_t NC >= 5.0 µm #/100 cm³
n10p0 uint16_t NC >= 10 µm #/100 cm³
pm uint16_t[3] PM <= 1,2.5,10 µm µg/m³ array containing pm01,pm25,pm10
nc uint16_t[6] NC >= 0.3,0.5,1,5,10 µm #/100cm³ array containing n0p3,..,n10p0
data uint16_t[9] PM/NC all PM/NC data pm01,..,n10p0
temp float T °C temperature
rhum float RH % relative humidity
hcho float HCHO mg/m³ formaldehyde concentration
extra float[3] T/RH/HCHO array containing temp,rhum,hcho

For an efficient use of memory, the data, pm and nc arrays and the individual measurement variables are implemented with a union/struct combination. See the examples for an full PM/NC output.

Status and error codes

The pms.status member variable contains the status and eventual error code resulting from the last sensor read. The available status/error codes and pre-defined error messages are:

status/error code error message pre-defined text
pms.OK
pms.ERROR_TIMEOUT PMS_ERROR_TIMEOUT "Sensor read timeout"
pms.ERROR_PMS_TYPE PMS_ERROR_PMS_TYPE "Wrong PMSx003 sensor type"
pms.ERROR_MSG_UNKNOWN PMS_ERROR_MSG_UNKNOWN "Unknown message protocol"
pms.ERROR_MSG_HEADER PMS_ERROR_MSG_HEADER "Incomplete message header"
pms.ERROR_MSG_BODY PMS_ERROR_MSG_BODY "Incomplete message body"
pms.ERROR_MSG_START PMS_ERROR_MSG_START "Wrong message start"
pms.ERROR_MSG_LENGTH PMS_ERROR_MSG_LENGTH "Message too long"
pms.ERROR_MSG_CKSUM PMS_ERROR_MSG_CKSUM "Wrong message checksum"

For easy of use, the error message are pre-defined with #define. See the examples for error handling implementation.

Temperature and humidity offset correction (Optional)

Some sensors have a small deviation with temperature and humidity readings. The compensate is possible with a correction offset defined by set_temp_offset() and set_rhum_offset(). The result will be reading + offset. Default offset values are O.

Example:

set_temp_offset(-0.6);
set_rhum_offset(2);

Contribute

If you have read this far, this is the library for your project or you can not figure out how to use it. In any case, I can use your help.

If you find any typos or something is not clear, please go to issue #3 and leave a message. Reopen the issue if needed.

If you want something a bit more challenging. I would appreciate more example projects. See issue #4 for inspiration. PRs are welcomed.

Changelog

  • 1.1.1
    • Fix SoftwareSerial dangling pointer #19/PR20
    • ESP8266 no longer requires EspSoftwareSerial
  • 1.1.0
    • Support atmelsam devices #8/PR12
    • Support the PMS5003 S/ST/T sensors #10,#16/PR17
    • Support sleep/wake commands #14/PR15
    • Use Serial1 as "SoftwareSerial" for ESP32, #7/PR9
  • 1.0.1
    • Fix broken SoftwareSerial for ESP8266, #6
    • ESP8266 use EspSoftwareSerial@>=6.7.1
  • 1.0.0
    • first complete release