Development website

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:

PreviousLibrary for gas sensorsNextConsumption

Last updated