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

enum 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]	dev	Pointer to an SPS30 device handle
[out]	error	Pre-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]	dev	Pointer to an SPS30 device handle
[in]	params	Parameters 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]	dev	Pointer to an SPS30 device handle
[out]	seconds	Pre-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]	dev	Pointer to an SPS30 device handle
[out]	str	Pre-allocated memory for returning the article code
[in]	len	Length 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]	dev	Pointer to an SPS30 device handle
[out]	data	Pre-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]	dev	Pointer to an SPS30 device handle
[out]	str	Pre-allocated memory for returning the serial number
[in]	len	Length 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] dev Pointer 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] dev Pointer 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] dev Pointer 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] dev Pointer 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] dev Pointer 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] dev Pointer 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]	dev	Pointer to an SPS30 device handle
[out]	seconds	The new interval in seconds, 0 for disable

Returns: SPS30_OK on success, negative sps30_error_code_t on error

Detailed Description

About

Wiring

Modules

Files

Data Structures

Macros

Enumerations

Functions

Enumeration Type Documentation

◆ sps30_error_code_t

Function Documentation

◆ sps30_data_ready()

◆ sps30_init()

◆ sps30_read_ac_interval()

◆ sps30_read_article_code()

◆ sps30_read_measurement()

◆ sps30_read_serial_number()

◆ sps30_reset()

◆ sps30_sleep()

◆ sps30_start_fan_clean()

◆ sps30_start_measurement()

◆ sps30_stop_measurement()

◆ sps30_wakeup()

◆ sps30_write_ac_interval()