PMSerial

Arduino library for PM sensors with serial interface

Sensors

Compatibility

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:

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:

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:

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);

SoftwareSerial Compatibility

Some libraries (e.g Arduino-SDI-12) conflict with SoftwareSerial library, which is loaded by default for some boards. In order to disable SoftwareSerial compatibility, define NO_SW_SERIAL_REQUIRED before including the library. For example:

#define NO_SW_SERIAL_REQUIRED
#include <PMSerial.h>

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.2.0
  • Avoid loading SoftwareSerial library with -D NO_SW_SERIAL_REQUIRED compilation flag PR24
  • Update OLED library used on examples
  • Enable STM32F103C8 Serial1
• 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