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

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

Detailed Description

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

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

Enumerations

enum  {
  SAUL_CLASS_UNDEF = 0x00, SAUL_ACT_ANY = 0x40, SAUL_ACT_LED_RGB = 0x42, SAUL_ACT_SERVO = 0x43,
  SAUL_ACT_MOTOR = 0x44, SAUL_ACT_SWITCH = 0x45, SAUL_ACT_DIMMER = 0x46, SAUL_SENSE_ANY = 0x80,
  SAUL_SENSE_BTN = 0x81, SAUL_SENSE_TEMP = 0x82, SAUL_SENSE_HUM = 0x83, SAUL_SENSE_LIGHT = 0x84,
  SAUL_SENSE_ACCEL = 0x85, SAUL_SENSE_MAG = 0x86, SAUL_SENSE_GYRO = 0x87, SAUL_SENSE_COLOR = 0x88,
  SAUL_SENSE_PRESS = 0x89, SAUL_SENSE_ANALOG = 0x8a, SAUL_SENSE_UV = 0x8b, SAUL_CLASS_ANY = 0xff
}
 Definition of device classes. More...
 

Functions

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

Typedef Documentation

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

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
[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 115 of file saul.h.

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

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 135 of file saul.h.

Enumeration Type Documentation

anonymous enum

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 two top-level classes: sensors and actuators. For identification, all actuator classes start with 0b01xxxxxx, all sensor classes start with 0b10xxxxxx.

This list is not exhaustive, extend to your needs!

Enumerator
SAUL_CLASS_UNDEF 

device class undefined

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_CLASS_ANY 

any device - wildcard

Definition at line 74 of file saul.h.

Function Documentation

const char* saul_class_to_str ( uint8_t  class_id)
Parameters
[in]class_iddevice class ID
Returns
string representation of the device class
NULL if class ID is not known