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

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.

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

enum @156
SAUL_CLASS_UNDEF = 0x00
device class undefined
SAUL_ACT_ANY = 0x40
any actuator - wildcard
SAUL_ACT_LED_RGB = 0x42
actuator: RGB LED
SAUL_ACT_SERVO = 0x43
actuator: servo motor
SAUL_ACT_MOTOR = 0x44
actuator: motor
SAUL_ACT_SWITCH = 0x45
actuator: simple on/off switch
SAUL_ACT_DIMMER = 0x46
actuator: dimmable switch
SAUL_SENSE_ANY = 0x80
any sensor - wildcard
SAUL_SENSE_BTN = 0x81
sensor: simple button
SAUL_SENSE_TEMP = 0x82
sensor: temperature
SAUL_SENSE_HUM = 0x83
sensor: humidity
SAUL_SENSE_LIGHT = 0x84
sensor: light
SAUL_SENSE_ACCEL = 0x85
sensor: accelerometer
SAUL_SENSE_MAG = 0x86
sensor: magnetometer
SAUL_SENSE_GYRO = 0x87
sensor: gyroscope
SAUL_SENSE_COLOR = 0x88
sensor: (light) color
SAUL_SENSE_PRESS = 0x89
sensor: pressure
SAUL_SENSE_ANALOG = 0x8a
sensor: raw analog value
SAUL_SENSE_UV = 0x8b
sensor: UV index
SAUL_SENSE_OBJTEMP = 0x8c
sensor: object temperature
SAUL_SENSE_COUNT = 0x8d
sensor: pulse counter
SAUL_SENSE_DISTANCE = 0x8e
sensor: distance
SAUL_SENSE_CO2 = 0x8f
sensor: CO2 Gas
SAUL_SENSE_TVOC = 0x90
sensor: TVOC Gas
SAUL_SENSE_OCCUP = 0x91
sensor: occupancy
SAUL_SENSE_PROXIMITY = 0x92
sensor: proximity
SAUL_SENSE_RSSI = 0x93
sensor: RSSI
SAUL_CLASS_ANY = 0xff
any device - wildcard
int(* saul_read_t()

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 touple 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

dev:device descriptor of the target device
res:data read from the device

Return values

  • number of values written into to result data structure [1-3]
  • -ENOTSUP if the device does not support this operation
  • -ECANCELED on other errors
int(* saul_write_t()

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

dev:device descriptor of the target device
data:data to write to the device

Return values

  • number of values actually processed by the device [1-3]
  • -ENOTSUP if the device does not support this operation
  • -ECANCELED on other errors
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.

Parameters

class_id:device class ID

Return values

  • string representation of the device class
  • NULL if class ID is not known
struct saul_driver_t

Definition of the RIOT actuator/sensor interface.

saul.h::saul_read_t read

read function pointer

saul.h::saul_write_t write

write function pointer

uint8_t type

device class the device belongs to