[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.

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. The devices has two main channels: capacitance channel and voltage / temperature channel.
 
 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.
 
 HMC5883L 3-axis digital compass
 Device driver for the Honeywell HMC5883L 3-axis digital compass.
 
 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.
 
 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)
 
 LSM303DLHC 3D accelerometer/magnetometer
 Device driver for the LSM303DLHC 3D accelerometer/magnetometer.
 
 LSM6DSL 3D accelerometer/gyroscope
 Device driver for the LSM6DSL 3D accelerometer/gyroscope.
 
 MAG3110 3-Axis Digital Magnetometer
 Driver for the Freescale MAG3110 magnetometer.
 
 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.
 
 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.
 
 SHTC1 Temperature and humidity sensor
 Driver for the Sensirion SHTC1 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.
 
 Si1145/6/7 UV/Ambient light/Proximity sensors
 Device driver for the Si1145/6/7 sensors family.
 
 Si7006/13/20/21 temperature and humidity sensors
 Driver for the Si7006/13/20/21 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.
 
 pH OEM sensor device driver
 Device driver for Atlas Scientific pH OEM sensor with SMBus/I2C interface.
 

Files

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

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. More...
 
typedef int(* saul_write_t) (const void *dev, phydat_t *data)
 Write a value (a set of values) to a device. More...
 

Functions

void saul_init_devs (void)
 Initialize all available SAUL drivers. More...
 
int saul_notsup (const void *dev, phydat_t *dat)
 Default not supported function.
 
const char * saul_class_to_str (const uint8_t class_id)
 Helper function converts a class ID to a string. More...
 

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]devdevice descriptor of the target device
[out]resdata 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 254 of file saul.h.

◆ saul_write_t

typedef int(* saul_write_t) (const void *dev, 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]devdevice descriptor of the target device
[in]datadata 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 274 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 84 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 93 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 109 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 151 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 231 of file saul.h.

Function Documentation

◆ 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_iddevice class ID
Returns
string representation of the device class
NULL if class ID is not known

◆ 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.