Driver for the Sensirion SPS30 Particulate Matter Sensor. More...

Detailed Description

Driver for the Sensirion SPS30 Particulate Matter Sensor.

About

This driver provides an interface for the Sensirion SPS30 Sensor. The Datasheet can be found here. For now only I2C mode is supported. I2C speed must be set to standard mode (100 kbit/s)

Wiring

In ASCII-land the connector side of the sensor would look like this:

+------------------------------------------------------------------------+
| ____________________ |
| __| |__ |
| |__ (1) (2) (3) (4) (5) __| |
| | | |
| |____________________| |
| |
+------------[#]------------[#]------------[#]------------[#]------------+

The numbers refer to following pin names:

Pin Nr. SPS30 Signal Name Connect to Notes
Pin 1 VDD 5 V should be within +-10 %
Pin 2 I2C_SDA / UART_RX SDA* config by SPS30_PARAM_I2C_DEV
Pin 3 I2C_SCL / UART_TR SCL* config by SPS30_PARAM_I2C_DEV
Pin 4 SEL GND
Pin 5 GND GND

*The SCL and SDA pins of the SPS30 sensor are open drain so they must be pulled high. Consider that internal pull resistors might be too weak. So using external 10 kOhm resistors is recommended for that.

Modules

 SPS30 PM Sensor driver compile configuration
 

Files

file  sps30.h
 Driver for the Sensirion SPS30 Particulate Matter Sensor.
 
file  sps30_params.h
 Default configuration for Sensirion SPS30 sensors devices.
 

Data Structures

struct  sps30_params_t
 SPS30 device parameters. More...
 
struct  sps30_t
 SPS30 device instance. More...
 
struct  sps30_data_t
 Set of measured particulate matter values. More...
 

Macros

#define SPS30_FAN_CLEAN_S   (10U)
 Seconds the fan cleaning process takes in seconds.
 
#define SPS30_SER_ART_LEN   (32U)
 Length of serial and article code string.
 
#define SPS30_DEFAULT_ACI_S   (604800UL)
 Default fan auto-clean interval in seconds (1 week)
 

Enumerations

enum  sps30_error_code_t { SPS30_OK = 0, SPS30_CRC_ERROR, SPS30_I2C_ERROR }
 SPS30 error codes (returned as negative values) More...
 

Functions

int sps30_init (sps30_t *dev, const sps30_params_t *params)
 Initialize SPS30 sensor driver. More...
 
int sps30_start_measurement (const sps30_t *dev)
 Enable the measurement action. More...
 
int sps30_stop_measurement (const sps30_t *dev)
 Stops the measurement action. More...
 
bool sps30_data_ready (const sps30_t *dev, int *error)
 Ask the device if a measurement is ready for reading. More...
 
int sps30_read_measurement (const sps30_t *dev, sps30_data_t *data)
 Read a set of particulate matter measurements. More...
 
int sps30_read_ac_interval (const sps30_t *dev, uint32_t *seconds)
 Read the fan auto-clean interval. More...
 
int sps30_write_ac_interval (const sps30_t *dev, uint32_t seconds)
 Write the fan auto-clean interval. More...
 
int sps30_start_fan_clean (const sps30_t *dev)
 Run a fan cleaning cycle manually. More...
 
int sps30_read_article_code (const sps30_t *dev, char *str, size_t len)
 Read the article code from the sensor as string. More...
 
int sps30_read_serial_number (const sps30_t *dev, char *str, size_t len)
 Read the serial number from the sensor as string. More...
 
int sps30_reset (const sps30_t *dev)
 Reset the sensor. More...
 
int sps30_sleep (const sps30_t *dev)
 Put the sensor in sleep mode. More...
 
int sps30_wakeup (const sps30_t *dev)
 Wake up sensor from sleep mode (returns sensor to Idle mode) More...
 

Enumeration Type Documentation

◆ sps30_error_code_t

SPS30 error codes (returned as negative values)

Enumerator
SPS30_OK 

Everything went fine.

SPS30_CRC_ERROR 

The CRC check of received data failed.

SPS30_I2C_ERROR 

Some I2C operation failed.

Definition at line 109 of file sps30.h.

Function Documentation

◆ sps30_data_ready()

bool sps30_data_ready ( const sps30_t dev,
int *  error 
)

Ask the device if a measurement is ready for reading.

Parameters
[in]devPointer to an SPS30 device handle
[out]errorPre-allocated memory to return sps30_error_code_t or NULL if not interested
Returns
true if a new measurement is available
false if no new measurement is available

◆ sps30_init()

int sps30_init ( sps30_t dev,
const sps30_params_t params 
)

Initialize SPS30 sensor driver.

On success the measurement mode will be active after calling.

Parameters
[out]devPointer to an SPS30 device handle
[in]paramsParameters for device initialization
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_read_ac_interval()

int sps30_read_ac_interval ( const sps30_t dev,
uint32_t *  seconds 
)

Read the fan auto-clean interval.

The default value is 604800 seconds (1 week). See also sps30_start_fan_clean.

Parameters
[in]devPointer to an SPS30 device handle
[out]secondsPre-allocated memory for returning the interval, 0 stands for disabled auto-clean
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_read_article_code()

int sps30_read_article_code ( const sps30_t dev,
char *  str,
size_t  len 
)

Read the article code from the sensor as string.

Parameters
[in]devPointer to an SPS30 device handle
[out]strPre-allocated memory for returning the article code
[in]lenLength of the str buffer, must be 32
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_read_measurement()

int sps30_read_measurement ( const sps30_t dev,
sps30_data_t data 
)

Read a set of particulate matter measurements.

Parameters
[in]devPointer to an SPS30 device handle
[out]dataPre-allocated memory to return measurements
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_read_serial_number()

int sps30_read_serial_number ( const sps30_t dev,
char *  str,
size_t  len 
)

Read the serial number from the sensor as string.

Parameters
[in]devPointer to an SPS30 device handle
[out]strPre-allocated memory for returning the serial number
[in]lenLength of the str buffer, must be 32
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_reset()

int sps30_reset ( const sps30_t dev)

Reset the sensor.

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_sleep()

int sps30_sleep ( const sps30_t dev)

Put the sensor in sleep mode.

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_start_fan_clean()

int sps30_start_fan_clean ( const sps30_t dev)

Run a fan cleaning cycle manually.

This will spin up the fan to maximum speed to blow out dust for for 10 seconds. No new measurement values are available until the cleaning process is finished.

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_start_measurement()

int sps30_start_measurement ( const sps30_t dev)

Enable the measurement action.

Starting the measurement activates the fan of the sensor and increases the power consumption from below 8 mA to an average of 60 mA. When the fan is starting up the consumption can reach up to 80 mA for around 200 ms. The measurement mode will stay active until either the power is turned off, a stop is requested (sps30_stop_measurement), or the device is reset (sps30_reset).

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_stop_measurement()

int sps30_stop_measurement ( const sps30_t dev)

Stops the measurement action.

Stopping the measurement sets the device back to idle mode.

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_wakeup()

int sps30_wakeup ( const sps30_t dev)

Wake up sensor from sleep mode (returns sensor to Idle mode)

Parameters
[in]devPointer to an SPS30 device handle
Returns
SPS30_OK on success, negative sps30_error_code_t on error

◆ sps30_write_ac_interval()

int sps30_write_ac_interval ( const sps30_t dev,
uint32_t  seconds 
)

Write the fan auto-clean interval.

The new value will be effective immediately after writing but reading the updated value is only possible after resetting the sensor. This setting is persistent across resets and powerdowns. But if the sensor is powered off, the active time counter starts from zero again. If this is expected to happen, a fan cleaning cycle should be triggered manually at least once a week. See also sps30_start_fan_clean.

Parameters
[in]devPointer to an SPS30 device handle
[out]secondsThe new interval in seconds, 0 for disable
Returns
SPS30_OK on success, negative sps30_error_code_t on error