[S]ensor [A]ctuator [U]ber [L]ayer

Generic sensor/actuator abstraction layer for RIOT. More...

Detailed Description

Generic sensor/actuator abstraction layer for RIOT.

SAUL is a generic actuator/sensor interface in RIOT. Its purpose is to enable unified interaction with a wide range of sensors and actuators through a set of defined access functions and a common data structure.

Each device driver implementing this interface has to expose a set of predefined functions and it has to register itself to the central SAUL registry. From here devices can be found, listed, and accessed.

Each device has further to expose a name and its type. This information can be used for automated searching and matching of devices (e.g. connect light sensor automatically with the color of an RGB LED...).

The SAUL module enables further the automated initialization of preconfigured actuators/sensor via auto_init and the access to all available devices via one unified shell command.

SAUL drivers may rely on being called from a thread, and often block for short amounts of time to obtain a value. Conversely, requests through the SAUL registry must not be issued from an interrupt context.

Todo:

So far, the interface only supports simple read and set operations. It probably needs to be extended to handling events, thresholds, and so on.

See also

SAUL registry

Modules
	AD7746 Capacitance-to-digital converter driver
	I2C Capacitance-to-digital converter with temperature and voltage sensors.
	ADCXX1C ADC device driver
	I2C Analog-to-Digital Converter device driver.
	ADS101x/111x ADC device driver
	I2C Analog-to-Digital Converter device driver.
	ADXL345 3-Axis accelerometer
	Device driver interface for the ADXL345.
	APDS99XX proximity and ambient light sensors
	Device driver for Broadcom APDS99XX proximity and ambient light sensors.
	Adafruit Seesaw Soil Moisture and Temperature Sensor
	Driver for the Adafruit Seesaw Soil Moisture and Temperature Sensor.
	Atmel IO1 Xplained Extension board
	Device driver interface for the Atmel IO1 Xplained extension.
	BMP180 temperature and pressure sensor
	Device driver interface for the BMP180 sensor.
	BMX055 9-axis sensor
	Device driver for the Bosch BMX055 9-axis sensor.
	CCS 811 digital gas sensor
	Device Driver for AMS CCS 811 digital gas sensor for monitoring Indoor Air Quality (IAQ)
	DHT Family of Humidity and Temperature Sensors
	Device driver for the DHT Family of humidity and temperature sensors.
	DS18 temperature sensor driver
	Driver interface for the DS18 temperature sensors.
	EFM32 internal temperature sensor
	Driver for the EFM32 internal temperature sensor.
	FXOS8700 3-axis accelerometer/magnetometer
	Driver for the FXOS8700 3-axis accelerometer/magnetometer.
	GP2Y10xx Optical Dust Sensor device driver
	GP2Y10xx Optical Dust Sensor Converter device driver.
	Grove ledbar
	Driver for the Grove ledbar.
	HDC1000 Humidity and Temperature Sensor
	Driver for the TI HDC1000 Humidity and Temperature Sensor.
	HM330X Laser Particulate Matter Sensor
	Driver for HM330X particle matter sensor.
	HMC5883L 3-axis digital compass
	Device driver for the Honeywell HMC5883L 3-axis digital compass.
	HSC temperature and pressure sensor
	Device driver interface for the HSC sensor.
	INA3221 current/power monitor
	Device driver for Texas Instruments INA3221 three-channel, high-side current and bus voltage monitor.
	ISL29020 light sensor
	Device driver for the ISL29020 light sensor.
	ITG320X 3-axis gyroscope
	Device driver for InvenSense ITG320X 3-axis gyroscope.
	JC42 compliant temperature sensor driver
	JC42 compliant temperature sensor driver.
	L3G4200D gyroscope
	Device driver for the L3G4200D gyroscope.
	L3Gxxxx 3-axis gyroscope sensor family
	Device Driver for ST L3Gxxxx 3-axis gyroscope sensor family.
	LIS2DH12 Accelerometer
	Driver for the STM LIS2DH12 accelerometer.
	LIS3DH accelerometer
	Device driver for the LIS3DH accelerometer.
	LIS3MDL 3-axis magnetometer
	Device driver for the LIS3MDL 3-axis magnetometer.
	LPS331AP/LPS25HB/LPS22HB Pressure Sensors Driver
	Device driver for the LPSXXX pressure sensor family (LPS331AP/LPS25HB/LPS22HB)
	LSM303AGR 3D accelerometer/magnetometer
	Device driver for the LSM303AGR 3D accelerometer/magnetometer.
	LSM303DLHC 3D accelerometer/magnetometer
	Device driver for the LSM303DLHC 3D accelerometer/magnetometer.
	LSM6DSXX 3D accelerometer/gyroscope
	Device driver for the LSM6DSXX 3D accelerometer/gyroscope.
	MAG3110 3-Axis Digital Magnetometer
	Driver for the Freescale MAG3110 magnetometer.
	MCP47xx DAC with I2C interface
	Device driver for Microchip MCP47xx DAC with I2C interface.
	MMA8x5x Accelerometer
	Driver for the Freescale MMA8x5x 3-Axis accelerometer.
	MPL3115A2 Pressure Sensor
	Driver for the Freescale MPL3115A2 pressure sensor.
	MPU-9X50 (MPU9150 and MPU9250) accelerometer/magnetometer/gyroscope
	Device driver interface for the MPU-9X50 (MPU9150 and MPU9250)
	Maxim DS75LX temperature sensor
	Device driver interface for the Maxim DS75LX temperature sensor.
	OPT3001 Ambient Light Sensor
	Driver for the Texas Instruments OPT3001 sensor.
	PCA9685 I2C PWM controller
	Device driver for the NXP PCA9685.
	PCF857X I2C I/O expanders
	Device driver for Texas Instruments PCF857X I2C I/O expanders.
	Pulse counter
	GPIO based pulse counting driver.
	QMC5883L 3-Axis Digital Magnetic Sensor
	Driver for QST QMC5883L digital magnetic sensor.
	SAUL Auto Initialisation
	Auto initialisation of SAUL enabled drivers.
	SAUL Device Initialisation
	Bulk initialisation of SAUL enabled drivers.
	SHT3x Humidity and Temperature Sensor Series
	Device Driver for Sensirion SHT30/SHT31/SHT35 Humidity and Temperature Sensors.
	SHTCX Temperature and humidity sensor
	Driver for the Sensirion SHTCX sensor.
	SPS30 Particulate Matter Sensor
	Driver for the Sensirion SPS30 Particulate Matter Sensor.
	ST HTS221 digital Humidity Sensor
	Driver for the ST HTS221 digital Humidity Sensor.
	Si1133 UV Index/Ambient Light Sensor with I2C
	Device driver for the Si1133 sensor.
	Si1145/6/7 UV/Ambient light/Proximity sensors
	Device driver for the Si1145/6/7 sensors family.
	Si7006/13/20/21/5x temperature and humidity sensors
	Driver for the Si7006/13/20/21/5x temperature and humidity sensor.
	TCS37727 RGB Light Sensor
	Driver for the AMS TCS37727 Color Light-To-Digital Converter.
	TMP006/TMP007 Infrared Thermopile Sensor
	Driver for the Texas Instruments TMP00X sensor.
	TSL2561 illuminance sensor
	Device driver interface for the illuminance TSL2561 sensor.
	VEML6070 UV sensor
	Device driver interface for the VEML6070 UV sensor.
	VL6180X Ranging and Ambient Light Sensing (ALS) module
	Device driver for the ST VL6180X Ranging and Ambient Light Sensing (ALS) module.
	pH OEM sensor device driver
	Device driver for Atlas Scientific pH OEM sensor with SMBus/I2C interface.

Files
file	saul.h
	Definition of the generic [S]ensor [A]ctuator [U]ber [L]ayer.
file	bat_voltage.h
	Parameter definitions for mapping battery voltage to SAUL.
file	periph.h
	Parameter definitions for mapping peripherals directly to SAUL.

Data Structures
struct	saul_driver_t
	Definition of the RIOT actuator/sensor interface. More...

Typedefs
typedef int(*	saul_read_t) (const void *dev, phydat_t *res)
	Read a value (a set of values) from a device.
typedef int(*	saul_write_t) (const void *dev, const phydat_t *data)
	Write a value (a set of values) to a device.

Functions
void	saul_init_devs (void)
	Initialize all available SAUL drivers.
int	saul_write_notsup (const void *dev, const phydat_t *dat)
	Fallback function when write is not supported.
int	saul_read_notsup (const void *dev, phydat_t *dat)
	Fallback function when read is not supported.
const char *	saul_class_to_str (const uint8_t class_id)
	Helper function converts a class ID to a string.
void	saul_class_print (uint8_t class_id)
	Prints the class string of the given class ID.
ssize_t	saul_class_write (char *dest, size_t max_size, uint8_t class_id)
	Write the string representation of the given device class to the given buffer.

Definition of device classes
This list contains a collections of available device classes. Each device must be part of one, but can be part of multiple of these classes. When belonging to more than one class, a device must however expose one driver for each class it belongs to, and it has to register each driver with a separate entry at the SAUL registry. Classes are identified by 8-bit unsigned integers. For searching and filtering purposes, the device classes are further split into top-level categories: sensors and actuators. For identification, the two most significant bits of a class specify the device category (SAUL category ID) and the six least significant bits identify the class within its category (SAUL intra-category ID): Therefore, all actuator classes start with 0b01xxxxxx, all sensor classes start with 0b10xxxxxx. This list is not exhaustive, extend to your needs!
enum	{ SAUL_CAT_UNDEF = 0x00 , SAUL_CAT_ACT = 0x40 , SAUL_CAT_SENSE = 0x80 }
	Definition of SAUL categories. More...
enum	{   SAUL_ACT_ID_ANY , SAUL_ACT_ID_LED_RGB , SAUL_ACT_ID_SERVO , SAUL_ACT_ID_MOTOR ,   SAUL_ACT_ID_SWITCH , SAUL_ACT_ID_DIMMER , SAUL_ACT_NUMOF }
	Definition of actuator intra-category IDs. More...
enum	{   SAUL_SENSE_ID_ANY , SAUL_SENSE_ID_BTN , SAUL_SENSE_ID_TEMP , SAUL_SENSE_ID_HUM ,   SAUL_SENSE_ID_LIGHT , SAUL_SENSE_ID_ACCEL , SAUL_SENSE_ID_MAG , SAUL_SENSE_ID_GYRO ,   SAUL_SENSE_ID_COLOR , SAUL_SENSE_ID_PRESS , SAUL_SENSE_ID_ANALOG , SAUL_SENSE_ID_UV ,   SAUL_SENSE_ID_OBJTEMP , SAUL_SENSE_ID_COUNT , SAUL_SENSE_ID_DISTANCE , SAUL_SENSE_ID_CO2 ,   SAUL_SENSE_ID_TVOC , SAUL_SENSE_ID_GAS , SAUL_SENSE_ID_OCCUP , SAUL_SENSE_ID_PROXIMITY ,   SAUL_SENSE_ID_RSSI , SAUL_SENSE_ID_CHARGE , SAUL_SENSE_ID_CURRENT , SAUL_SENSE_ID_PM ,   SAUL_SENSE_ID_CAPACITANCE , SAUL_SENSE_ID_VOLTAGE , SAUL_SENSE_ID_PH , SAUL_SENSE_ID_POWER ,   SAUL_SENSE_ID_SIZE , SAUL_SENSE_NUMOF }
	Definition of sensor intra-category IDs. More...
enum	{   SAUL_ACT_ANY = SAUL_CAT_ACT | SAUL_ACT_ID_ANY , SAUL_ACT_LED_RGB = SAUL_CAT_ACT | SAUL_ACT_ID_LED_RGB , SAUL_ACT_SERVO = SAUL_CAT_ACT | SAUL_ACT_ID_SERVO , SAUL_ACT_MOTOR = SAUL_CAT_ACT | SAUL_ACT_ID_MOTOR ,   SAUL_ACT_SWITCH = SAUL_CAT_ACT | SAUL_ACT_ID_SWITCH , SAUL_ACT_DIMMER = SAUL_CAT_ACT | SAUL_ACT_ID_DIMMER , SAUL_SENSE_ANY = SAUL_CAT_SENSE | SAUL_SENSE_ID_ANY , SAUL_SENSE_BTN = SAUL_CAT_SENSE | SAUL_SENSE_ID_BTN ,   SAUL_SENSE_TEMP = SAUL_CAT_SENSE | SAUL_SENSE_ID_TEMP , SAUL_SENSE_HUM = SAUL_CAT_SENSE | SAUL_SENSE_ID_HUM , SAUL_SENSE_LIGHT = SAUL_CAT_SENSE | SAUL_SENSE_ID_LIGHT , SAUL_SENSE_ACCEL = SAUL_CAT_SENSE | SAUL_SENSE_ID_ACCEL ,   SAUL_SENSE_MAG = SAUL_CAT_SENSE | SAUL_SENSE_ID_MAG , SAUL_SENSE_GYRO = SAUL_CAT_SENSE | SAUL_SENSE_ID_GYRO , SAUL_SENSE_COLOR = SAUL_CAT_SENSE | SAUL_SENSE_ID_COLOR , SAUL_SENSE_PRESS = SAUL_CAT_SENSE | SAUL_SENSE_ID_PRESS ,   SAUL_SENSE_ANALOG = SAUL_CAT_SENSE | SAUL_SENSE_ID_ANALOG , SAUL_SENSE_UV = SAUL_CAT_SENSE | SAUL_SENSE_ID_UV , SAUL_SENSE_OBJTEMP = SAUL_CAT_SENSE | SAUL_SENSE_ID_OBJTEMP , SAUL_SENSE_COUNT = SAUL_CAT_SENSE | SAUL_SENSE_ID_COUNT ,   SAUL_SENSE_DISTANCE = SAUL_CAT_SENSE | SAUL_SENSE_ID_DISTANCE , SAUL_SENSE_CO2 = SAUL_CAT_SENSE | SAUL_SENSE_ID_CO2 , SAUL_SENSE_TVOC = SAUL_CAT_SENSE | SAUL_SENSE_ID_TVOC , SAUL_SENSE_GAS = SAUL_CAT_SENSE | SAUL_SENSE_ID_GAS ,   SAUL_SENSE_OCCUP = SAUL_CAT_SENSE | SAUL_SENSE_ID_OCCUP , SAUL_SENSE_PROXIMITY = SAUL_CAT_SENSE | SAUL_SENSE_ID_PROXIMITY , SAUL_SENSE_RSSI = SAUL_CAT_SENSE | SAUL_SENSE_ID_RSSI , SAUL_SENSE_CHARGE = SAUL_CAT_SENSE | SAUL_SENSE_ID_CHARGE ,   SAUL_SENSE_CURRENT = SAUL_CAT_SENSE | SAUL_SENSE_ID_CURRENT , SAUL_SENSE_PM = SAUL_CAT_SENSE | SAUL_SENSE_ID_PM , SAUL_SENSE_CAPACITANCE = SAUL_CAT_SENSE | SAUL_SENSE_ID_CAPACITANCE , SAUL_SENSE_VOLTAGE = SAUL_CAT_SENSE | SAUL_SENSE_ID_VOLTAGE ,   SAUL_SENSE_PH = SAUL_CAT_SENSE | SAUL_SENSE_ID_PH , SAUL_SENSE_POWER = SAUL_CAT_SENSE | SAUL_SENSE_ID_POWER , SAUL_SENSE_SIZE = SAUL_CAT_SENSE | SAUL_SENSE_ID_SIZE , SAUL_CLASS_ANY = 0xff }
	Definition of SAUL actuator and sensor classes. More...
enum	{ SAUL_CAT_MASK = 0xc0 , SAUL_ID_MASK = 0x3f }
	Bitmask to retrieve the class ID and intra-category ID from a SAUL class. More...

Typedef Documentation

saul_read_t

typedef int(* saul_read_t) (const void *dev, phydat_t *res)

Read a value (a set of values) from a device.

Simple sensors, as e.g. a temperature sensor, will return exactly one value together with the values scale and unit. Some sensors might return a tuple or triple of data (e.g. a 3-axis accelerometer).

Actuators can chose to either just return -ENOTSUP or to return their current set value (e.g. useful for reading back the current state of a switch)

Parameters

[in]	dev	device descriptor of the target device
[out]	res	data read from the device

Returns

number of values written into to result data structure [1-3]

-ENOTSUP if the device does not support this operation

-ECANCELED on other errors

Definition at line 259 of file saul.h.

saul_write_t

typedef int(* saul_write_t) (const void *dev, const phydat_t *data)

Write a value (a set of values) to a device.

Most sensors will probably just return -ENOTSUP, as writing values to a sensor is often without purpose. The interface can however be used to configure sensors, e.g. to switch a sensor's unit type by writing the newly selected type to it.

For actuators this function is used to influence the actuators state, e.g. switching a switch or setting the speed of a motor.

Parameters

[in]	dev	device descriptor of the target device
[in]	data	data to write to the device

Returns

number of values actually processed by the device [1-3]

-ENOTSUP if the device does not support this operation

-ECANCELED on other errors

Definition at line 279 of file saul.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Definition of SAUL categories.

These entries are meant to be combined via bitwise or with the six least significant bits identifying the class within its category to retrieve the class ID.

Enumerator
SAUL_CAT_UNDEF	device class undefined
SAUL_CAT_ACT	Actuator device class.
SAUL_CAT_SENSE	Sensor device class.

Definition at line 89 of file saul.h.

anonymous enum

anonymous enum

Definition of actuator intra-category IDs.

Enumerator
SAUL_ACT_ID_ANY	any actuator - wildcard
SAUL_ACT_ID_LED_RGB	actuator: RGB LED
SAUL_ACT_ID_SERVO	actuator: servo motor
SAUL_ACT_ID_MOTOR	actuator: motor
SAUL_ACT_ID_SWITCH	actuator: simple on/off switch
SAUL_ACT_ID_DIMMER	actuator: dimmable switch
SAUL_ACT_NUMOF	Number of actuators supported.

Definition at line 98 of file saul.h.

anonymous enum

anonymous enum

Definition of sensor intra-category IDs.

Enumerator
SAUL_SENSE_ID_ANY	any sensor - wildcard
SAUL_SENSE_ID_BTN	sensor: simple button
SAUL_SENSE_ID_TEMP	sensor: temperature
SAUL_SENSE_ID_HUM	sensor: humidity
SAUL_SENSE_ID_LIGHT	sensor: light
SAUL_SENSE_ID_ACCEL	sensor: accelerometer
SAUL_SENSE_ID_MAG	sensor: magnetometer
SAUL_SENSE_ID_GYRO	sensor: gyroscope
SAUL_SENSE_ID_COLOR	sensor: (light) color
SAUL_SENSE_ID_PRESS	sensor: pressure
SAUL_SENSE_ID_ANALOG	sensor: raw analog value
SAUL_SENSE_ID_UV	sensor: UV index
SAUL_SENSE_ID_OBJTEMP	sensor: object temperature
SAUL_SENSE_ID_COUNT	sensor: pulse counter
SAUL_SENSE_ID_DISTANCE	sensor: distance
SAUL_SENSE_ID_CO2	sensor: CO2 Gas
SAUL_SENSE_ID_TVOC	sensor: TVOC Gas
SAUL_SENSE_ID_GAS	sensor: Gas common
SAUL_SENSE_ID_OCCUP	sensor: occupancy
SAUL_SENSE_ID_PROXIMITY	sensor: proximity
SAUL_SENSE_ID_RSSI	sensor: RSSI
SAUL_SENSE_ID_CHARGE	sensor: coulomb counter
SAUL_SENSE_ID_CURRENT	sensor: ammeter
SAUL_SENSE_ID_PM	sensor: particulate matter
SAUL_SENSE_ID_CAPACITANCE	sensor: capacitance
SAUL_SENSE_ID_VOLTAGE	sensor: voltage
SAUL_SENSE_ID_PH	sensor: pH
SAUL_SENSE_ID_POWER	sensor: power
SAUL_SENSE_ID_SIZE	sensor: size
SAUL_SENSE_NUMOF	Number of actuators supported.

Definition at line 114 of file saul.h.

anonymous enum

anonymous enum

Definition of SAUL actuator and sensor classes.

These values consists of the SAUL category ID (two most significant bits) and the SAUL intra-category ID (six least significant bits).

Enumerator
SAUL_ACT_ANY	any actuator - wildcard
SAUL_ACT_LED_RGB	actuator: RGB LED
SAUL_ACT_SERVO	actuator: servo motor
SAUL_ACT_MOTOR	actuator: motor
SAUL_ACT_SWITCH	actuator: simple on/off switch
SAUL_ACT_DIMMER	actuator: dimmable switch
SAUL_SENSE_ANY	any sensor - wildcard
SAUL_SENSE_BTN	sensor: simple button
SAUL_SENSE_TEMP	sensor: temperature
SAUL_SENSE_HUM	sensor: humidity
SAUL_SENSE_LIGHT	sensor: light
SAUL_SENSE_ACCEL	sensor: accelerometer
SAUL_SENSE_MAG	sensor: magnetometer
SAUL_SENSE_GYRO	sensor: gyroscope
SAUL_SENSE_COLOR	sensor: (light) color
SAUL_SENSE_PRESS	sensor: pressure
SAUL_SENSE_ANALOG	sensor: raw analog value
SAUL_SENSE_UV	sensor: UV index
SAUL_SENSE_OBJTEMP	sensor: object temperature
SAUL_SENSE_COUNT	sensor: pulse counter
SAUL_SENSE_DISTANCE	sensor: distance
SAUL_SENSE_CO2	sensor: CO2 Gas
SAUL_SENSE_TVOC	sensor: TVOC Gas
SAUL_SENSE_GAS	sensor: Gas common
SAUL_SENSE_OCCUP	sensor: occupancy
SAUL_SENSE_PROXIMITY	sensor: proximity
SAUL_SENSE_RSSI	sensor: RSSI
SAUL_SENSE_CHARGE	sensor: coulomb counter
SAUL_SENSE_CURRENT	sensor: ammeter
SAUL_SENSE_PM	sensor: particulate matter
SAUL_SENSE_CAPACITANCE	sensor: capacitance
SAUL_SENSE_VOLTAGE	sensor: voltage
SAUL_SENSE_PH	sensor: pH
SAUL_SENSE_POWER	sensor: power
SAUL_SENSE_SIZE	sensor: size
SAUL_CLASS_ANY	any device - wildcard

Definition at line 156 of file saul.h.

anonymous enum

anonymous enum

Bitmask to retrieve the class ID and intra-category ID from a SAUL class.

Enumerator
SAUL_CAT_MASK	Bitmask to obtain the category ID.
SAUL_ID_MASK	Bitmask to obtain the intra-category ID.

Definition at line 236 of file saul.h.

Function Documentation

saul_class_print()

void saul_class_print

(

uint8_t

class_id

)

Prints the class string of the given class ID.

Parameters

[in]

class_id

ID of the device class to print

saul_class_to_str()

const char * saul_class_to_str

(

const uint8_t

class_id

)

Helper function converts a class ID to a string.

Parameters

[in]

class_id

device class ID

Returns

string representation of the device class

Return values

NULL	class ID is not known

Deprecated:

Use saul_class_print or saul_class_write instead

Warning

For classic Harvard architectures a small buffer is used to store the string, so that subsequent (or concurrent!) calls will overwrite the output.

saul_class_write()

ssize_t saul_class_write	(	char *	dest,
		size_t	max_size,
		uint8_t	class_id
	)

Write the string representation of the given device class to the given buffer.

Parameters

[out]	dest	destination buffer to write to
[in]	max_size	size of the buffer at dest
[in]	class_id	ID of the device class to write

Returns

Number of bytes written

Return values

-EOVERFLOW	buffer at dest is too small
-EINVAL	invalid unit in unit

Warning

The function will never write a terminating zero byte

Note

If you pass NULL for dest, it will return the number of bytes it would write (regardless of max_size)

saul_init_devs()

void saul_init_devs

(

void

)

Initialize all available SAUL drivers.

This function is called automatically if the auto_init_saul module is used. If only the saul_init module is used instead, you can call this function to manually set up all SAUL sensors at a later time.

saul_read_notsup()

int saul_read_notsup	(	const void *	dev,
		phydat_t *	dat
	)

Fallback function when read is not supported.

Returns -NOTSUP without evaluating arguments.

saul_write_notsup()

int saul_write_notsup	(	const void *	dev,
		const phydat_t *	dat
	)

Fallback function when write is not supported.

Returns -NOTSUP without evaluating arguments.