Links

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: