Adafruit Unified Sensor Driver Documentation

You can interrogate a compliant sensor about its technical specifications and capabilities using the getSensor() method. This populates a sensor_t structure containing metadata such as the sensor's name, driver version, unique ID, and measurement ranges (min/max values and resolution).

 sensor_t sensor;
 tsl.getSensor(&sensor);

 /* Display the sensor details */
 Serial.println("------------------------------------");
 Serial.print  ("Sensor:       "); Serial.println(sensor.name);
 Serial.print  ("Driver Ver:   "); Serial.println(sensor.version);
 Serial.print  ("Unique ID:    "); Serial.println(sensor.sensor_id);
 Serial.print  ("Max Value:    "); Serial.print(sensor.max_value); Serial.println(" lux");
 Serial.print  ("Min Value:    "); Serial.print(sensor.min_value); Serial.println(" lux");
 Serial.print  ("Resolution:   "); Serial.print(sensor.resolution); Serial.println(" lux");  
 Serial.println("------------------------------------");
 Serial.println("");

The Unified Sensor Driver standardizes all sensor readings to specific SI units. When consuming sensors_event_t data, use the following scales:

The sensors_type_t enum defines the category of sensor being used. This type is used within both sensor_t (to describe the sensor's capabilities) and sensors_event_t (to identify the type of data contained in the event).

/** Sensor types */
typedef enum
{
  SENSOR_TYPE_ACCELEROMETER         = (1),
  SENSOR_TYPE_MAGNETIC_FIELD        = (2),
  SENSOR_TYPE_ORIENTATION           = (3),
  SENSOR_TYPE_GYROSCOPE             = (4),
  SENSOR_TYPE_LIGHT                 = (5),
  SENSOR_TYPE_PRESSURE              = (6),
  SENSOR_TYPE_PROXIMITY             = (8),
  SENSOR_TYPE_GRAVITY               = (9),
  SENSOR_TYPE_LINEAR_ACCELERATION   = (10),
  SENSOR_TYPE_ROTATION_VECTOR       = (11),
  SENSOR_TYPE_RELATIVE_HUMIDITY     = (12),
  SENSOR_TYPE_AMBIENT_TEMPERATURE   = (13),
  SENSOR_TYPE_VOLTAGE               = (15),
  SENSOR_TYPE_CURRENT               = (16),
  SENSOR_TYPE_COLOR                 = (17),
  SENSOR_TYPE_TVOC                  = (18),
  SENSOR_TYPE_VOC_INDEX             = (19),
  SENSOR_TYPE_NOX_INDEX             = (20),
  SENSOR_TYPE_CO2                   = (21),
  SENSOR_TYPE_ECO2                  = (22),
  SENSOR_TYPE_PM10_STD              = (23),
  SENSOR_TYPE_PM25_STD              = (24),
  SENSOR_TYPE_PM100_STD             = (25),
  SENSOR_TYPE_PM10_ENV              = (26),
  SENSOR_TYPE_PM25_ENV              = (27),
  SENSOR_TYPE_PM100_ENV             = (28),
  SENSOR_TYPE_GAS_RESISTANCE        = (29),
  SENSOR_TYPE_UNITLESS_PERCENT      = (30),
  SENSOR_TYPE_ALTITUDE              = (31),
} sensors_type_t;

The sensors_event_t struct provides a common format for sensor data using standardized SI units. It uses a union to encapsulate different types of data based on the type field.

Fields:

• version: Contains sizeof(sensors_event_t) to identify the API version.
• sensor_id: Must match the sensor_id in the corresponding sensor_t.
• type: The sensors_type_t value.
• timestamp: Time in milliseconds when the value was read.
• data[4] (or specific union members): The actual sensor reading.

/* Sensor event (36 bytes) */
/** struct sensor_event_s is used to provide a single sensor event in a common format. */
typedef struct
{
    int32_t version;
    int32_t sensor_id;
    int32_t type;
    int32_t reserved0;
    int32_t timestamp;
    union
    {
        float           data[4];
        sensors_vec_t   acceleration;
        sensors_vec_t   magnetic;
        sensors_vec_t   orientation;
        sensors_vec_t   gyro;
        float           temperature;
        float           distance;
        float           light;
        float           pressure;
        float           relative_humidity;
        float           current;
        float           voltage;
        float           tvoc;
        float           voc_index;
        float           nox_index;
        float           CO2, 
        float           eCO2,
        float           pm10_std,
        float           pm25_std,
        float           pm100_std,
        float           pm10_env,
        float           pm25_env,
        float           pm100_env,
        float           gas_resistance,
        float           unitless_percent,
        float           altitude,
        sensors_color_t color;
    };
} sensors_event_t;

The sensor_t struct describes the specific capabilities and identity of a sensor. It is used to determine the sensor's name, version, range of values, and resolution.

Fields:

• name: Sensor name or ID (max 12 chars).
• version: Hardware and driver version.
• sensor_id: Unique identifier for the specific sensor instance.
• type: The sensors_type_t value.
• max_value: Maximum returnable value in SI units.
• min_value: Minimum returnable value in SI units.
• resolution: Smallest reportable difference in SI units.
• min_delay: Minimum delay between events in microseconds (0 if no constant rate).

/* Sensor details (40 bytes) */
/** struct sensor_s is used to describe basic information about a specific sensor. */
typedef struct
{
    char     name[12];
    int32_t  version;
    int32_t  sensor_id;
    int32_t  type;
    float    max_value;
    float    min_value;
    float    resolution;
    int32_t  min_delay;
} sensor_t;