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