Library for the Particle Matter (PM1 / PM2.5 / PM10) -- Dust Sensor

Before starting
When using the Particle Matter Sensor on Plug&Sense!, remember it is mandatory to include the WaspPM library by introducing the next line at the beginning of the code:
#include <WaspPM.h>
WaspPM is a new library that replaces the WaspOPC_N2 library in order to be able to read both the OPC_N2 sensor and the OPN_N3 sensor.
Library variables
The WaspPM library has some variables used by the functions to store the data received from the OPC-N3 sensor. These variables are listed in the table below:
Variable
Type of variable
Description
Functions that updated it
_bin[24]
Array of unsigned short
Number of particles detected for each bin. It is splited in _binL[16] and _binH[8] variables
getPM()
_binL[16]
Array of unsigned short
First 16 bins
getPM()
_binH[8]
Array of unsigned short
Last 8 bins
getPM()
_temp
float
Temperature from sensor in Celsius degrees
getPM()
_hum
float
Humidity from sensor in %RH
getPM()
_bin1_MToF
Unsigned short
Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.
getPM()
_bin3_MToF
Unsigned short
Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.
getPM()
_bin5_MToF
Unsigned short
Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.
getPM()
_bin7_MToF
Unsigned short
Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.
getPM()
_PM1
float
The mass (in μg/m3) of all particles below 1 μm in size
getPM()
_PM2_5
float
The mass (in μg/m3) of all particles below 2.5 μm in size
getPM()
_PM10
float
The mass (in μg/m3) of all particles below 10 μm in size
getPM()
_opcModel
​
Represents the particle matter sensor model. 2 for OPC-N2 and 3 for OPC-N3.
getPM()
Table: Variables from the WaspPM library
_temp and _hum variables are not available for OPC_N2 sensor. The OPC_N2 sensor measure 16 bins instead of 24. Consequently, the _binH variable and the last 8 bytes of the _bin variable will be zero.
Power and configuration
Initializing the sensor
Before reading the concentration values, the sensor must be powered using the function ON(). Unlike with other sensor boards, the user does not need to power on the board. The API library performs the next tasks in the power-on process from each sensor:
Powers on the board (if necessary)
Powers on the sensor
Configures the communication bus and checks if the sensor is ready to work.
PM.ON();
The function returns:
0 if the sensor does not init correctly
1 if init OK
If a sensor for gases PRO v1 is used, the ON() function must include the parameter '0' or PM_SPI_MODE. So, the function to use should be:
PM.ON(0);
or
PM.ON(PM_SPI_MODE);
Switching the sensor off
In order to save battery, the sensor can be powered off using the function OFF(). Unlike other sensor boards, the user does not need to power off the board. The API library powers off the board automatically when the last sensor is turned off.
PM.OFF();
The function returns the pwrGasPRORegister. Each bit of this register represents the status of a sensor. '1' for the powered on sensors and '0' for the powered off.
7: not used
6: gas sensor in socket 6
5: gas sensor in socket 5 or socket B in Plug & Sense!
4: gas sensor in socket 4 or socket A in Plug & Sense!
3: gas sensor in socket 3 or socket F in Plug & Sense!
2: gas sensor in socket 2
1: gas sensor in socket 1 or socket C in Plug & Sense!
0: particles-dust sensor (socket D in Plug & Sense!)
Reading the sensor
Reading bin and PM values
The functions getPM(timeSample) and getPM(waitSample, timeSample) perform a measure of the particles from the atmosphere. timeSample is the period in milliseconds to sample the air absorbed by the built-in fan. waitSample is a time in milliseconds with the fan powered on before the sample measurement.
// Reads PM and bin values with a period of 5 seconds
PM.getPM(5000);
// Reads PM and bin values with a period of 9 seconds and a wait sample of 5 seconds
PM.getPM(5000, 9000);
The function returns:
1 if OK
4 if error with the parameters
100 if error sending the command digital pot on
101 if error receiving data
102 if error sending the command read histogram
103 if error receiving data
104 if error sending the command read histogram
105 if error receiving data
106 if error sending the command digital pot off
107 if error receiving data
If the function ends successfully, the next variables will be updated:
_bin
_binL
_binH
_temp
_hum
_bin1_MToF
_bin3_MToF
_bin5_MToF
_bin7_MToF
_PM1
_PM2_5
_PM10
_opcModel
High humidity or foggy environments could affect the measures of the sensor. The particles can be swollen by or coated by water. This results in measures higher than in dry environments.
 If high humidity, fog or mist are present, then the OPC will actually measure the water droplets in the air, causing very high readings.
Reading the information string
The OPC-N3 sensor stores a string (61 bytes) with information about the sensor model and the firmware. This string can be read using the function getInfoString(string_pointer) and passing a string pointer as parameter. The information will be stored in the string pointer.
char information[61];
// Reads the configuration variables
PM.getInfoString(information);
// Prints the string
USB.println(information);
The function returns:
1 if OK
-1 if error sending the command
Reading the serial number
The OPC-N3 sensor stores a string (61 bytes) with the serial number information. This string can be read using the function readSerialNumber(string_pointer) and passing a string pointer as parameter. The information will be stored in the string pointer.
char serial_number[61];
// Reads the serial number
PM.readSerialNumber(serial_number);
// Prints the string
USB.println(serial_number);
The function returns:
1 if OK
-1 if error sending the command
That function isn't available for OPC-N2 sensors with old firmware version.
The files of the sensor itself are: WaspPM.cpp, WaspPM.h
They can be downloaded from:
Software
Waspmote

Library for gas sensors

Consumption

Last modified 2yr ago

Variable	Type of variable	Description	Functions that updated it
`_bin[24]`	Array of unsigned short	Number of particles detected for each bin. It is splited in _binL[16] and _binH[8] variables	`getPM()`
`_binL[16]`	Array of unsigned short	First 16 bins	`getPM()`
`_binH[8]`	Array of unsigned short	Last 8 bins	`getPM()`
`_temp`	float	Temperature from sensor in Celsius degrees	`getPM()`
`_hum`	float	Humidity from sensor in %RH	`getPM()`
`_bin1_MToF`	Unsigned short	Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.	`getPM()`
`_bin3_MToF`	Unsigned short	Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.	`getPM()`
`_bin5_MToF`	Unsigned short	Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.	`getPM()`
`_bin7_MToF`	Unsigned short	Represents the average amount of time that particles sized in the stated bin took to cross the OPS's laser beam. Each value is in μs multiplied by 3.	`getPM()`
`_PM1`	float	The mass (in μg/m3) of all particles below 1 μm in size	`getPM()`
`_PM2_5`	float	The mass (in μg/m3) of all particles below 2.5 μm in size	`getPM()`
`_PM10`	float	The mass (in μg/m3) of all particles below 10 μm in size	`getPM()`
`_opcModel`		Represents the particle matter sensor model. 2 for OPC-N2 and 3 for OPC-N3.	`getPM()`