Comment on page

Board configuration and programming

Hardware configuration
The Smart Cities PRO board does not require of any handling of the hardware by the user except for placing the sensors in their corresponding position. In the section dedicated to each connector we can see an image of the connections between the socket and its corresponding sensor.
API
Before starting to program
When using the Smart Cities PRO Sensor Board on Waspmote, remember it is mandatory to include the WaspSensorCities_Pro library by introducing the next line at the beginning of the code:
#include WaspSensorCities_PRO.h
The library manages the power supply and communication lines between Waspmote and the sockets. To manage each sensor the user must use the specific library and guide for each sensor.
Gases sensors
In order to manage a gas sensor, the user must define a "Gas" library object. The user must also indicate the socket used in the class constructor. The available sockets for gases sensors are: sockets 1, 3 and 5 for the OEM line; and sockets B, C and F for the Plug and Sense! line. For instance:
Gas gas_sensor(SOCKET_B);
The electrochemical sensors must be switched on at the beginning of the code in order to get the best measurements. On the other hand, NDIR and Pellistor sensors should be switched on for a couple of minutes prior getting the measurement because they imply a higher power consumption. The gas sensor is switched on as follows:
gas_sensor.ON();
For sensor measurement, the user must call the proper function which returns a value in ppm units:
gas_sensor.getConc();
The getConc() function returns:
concentration value in ppm or %LEL
-1000 if I2C bus communication error
In the case of using a BME280, luxes or ultrasound sensor, the user must switch off all gases sensors prior using them in order to work properly with the Smart Cities PRO board. Therefore, after getting the measurement from the BME280/luxes/ultrasound sensor, all electrochemical gas sensor should be powered on again. The gas sensor is switched off calling the next function:
gas_sensor.OFF();
You can find a complete example code for reading electrochemical sensors in the following link:
https://development.libelium.com/scp-v30-01-electrochemical-gas-sensors/​
You can find a complete example code for reading NDIR sensors in the following link:
https://development.libelium.com/scp-v30-02-ndir-gas-sensors/​
You can find a complete example code for reading pellistor sensors in the following link:
https://development.libelium.com/scp-v30-03-pellistor-gas-sensors/​
Temperature, humidity and pressure sensor (BME280)
Regarding the BME280 sensor, the user must define an object from the bmeCitiesSensor class. The user must also indicate the socket used in the class constructor. The available sockets for the BME sensor are: sockets 1, 2, 3, 4 and 5 for the OEM line; and sockets A, B, C, E and F for the Plug and Sense! line. For instance:
bmeCitiesSensor bme(SOCKET_A);
The next lines describe how to switch on the sensor, get a measurement and switch it off to save energy. The values returned by the reading functions are float variable type:
bme.ON();
bme.getTemperature();
bme.getHumidity();
bme.getPressure();
bme.OFF();
The getTemperature(), getHumidity() and getPressure() functions return:
The temperature in ºC, the percentage of relative humidity and pressure in Pascals
-1000 if I2C bus communication error
You can find a complete example code for reading the BME280 sensor in the following link:
https://development.libelium.com/scp-v30-05-temperature-humidity-and-pressure-senso/​
Luxes sensor
Regarding the luxes sensor, the user must define an object from the luxesCitiesSensor class. The user must define the socket used in the class constructor. The available sockets for the luxes sensor are: sockets 1, 2, 3, 4 and 5 for the OEM line, and sockets A, B, C, E and F for the Plug and Sense! line. For instance:
luxesCitiesSensor luxes(SOCKET_E);
The next lines describe how to switch on the sensor, get a measurement and switch it off to save energy. The value returned by the reading function is a uint32_t variable type:
luxes.ON();
luxes.getLuminosity();
luxes.OFF();

The getLuminosity() function returns:
luminosity in luxes
-1000 if I2C bus communication error
You can find a complete example code for reading the luminosity in the following link:
https://development.libelium.com/scp-v30-07-luxes-sensor/​
Ultrasound sensor
Regarding the ultrasound sensor, the user must define an object from the ultrasoundCitiesSensor class. The user must define the socket used in the class constructor. The available sockets for the ultrasound sensor are: sockets 1, 2, 3, 4 and 5 for the OEM line, and sockets A, B, C, E and F for the Plug and Sense! line. For instance:
ultrasoundCitiesSensor ultrasound(SOCKET_E);
The next lines describe how to switch on the sensor, get a measurement and switch it off to save energy. The value returned by the reading function is a uint16_t variable type:
ultrasound.ON();
ultrasound.getDistance();
ultrasound.OFF();
The getDistance() function returns:
distance in centimeters
-1000 if I2C bus communication error
You can find a complete example code for reading the distance in the following link:
https://development.libelium.com/scp-v30-06-ultrasound-sensor/​
Particle Matter sensor
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.
Note: _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 _bin variable will be zero.
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();
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
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
Note: 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:
https://development.libelium.com/waspmote/software​

Sensors

Consumption

Last modified 3yr 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()`