PMSerial

Arduino library for PM sensors with serial interface

Sensors

Plantower	Tested Works	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	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

mandulaj/PMserial