• Stars
    star
    887
  • Rank 51,456 (Top 2 %)
  • Language
    C++
  • License
    Apache License 2.0
  • Created almost 12 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Common sensor library

Adafruit Unified Sensor Driver

Many small embedded systems exist to collect data from sensors, analyse the data, and either take an appropriate action or send that sensor data to another system for processing.

One of the many challenges of embedded systems design is the fact that parts you used today may be out of production tomorrow, or system requirements may change and you may need to choose a different sensor down the road.

Creating new drivers is a relatively easy task, but integrating them into existing systems is both error prone and time consuming since sensors rarely use the exact same units of measurement.

By reducing all data to a single sensors_event_t 'type' and settling on specific, standardised SI units for each sensor family the same sensor types return values that are comparable with any other similar sensor. This enables you to switch sensor models with very little impact on the rest of the system, which can help mitigate some of the risks and problems of sensor availability and code reuse.

The unified sensor abstraction layer is also useful for data-logging and data-transmission since you only have one well-known type to log or transmit over the air or wire.

Unified Sensor Drivers

The following drivers are based on the Adafruit Unified Sensor Driver:

Accelerometers

Gyroscope

Light

Magnetometers

Barometric Pressure

Humidity & Temperature

Humidity, Temperature, & Barometric Pressure

Orientation

All in one device

How Does it Work?

Any driver that supports the Adafruit unified sensor abstraction layer will implement the Adafruit_Sensor base class. There are two main typedefs and one enum defined in Adafruit_Sensor.h that are used to 'abstract' away the sensor details and values:

Sensor Types (sensors_type_t)

These pre-defined sensor types are used to properly handle the two related typedefs below, and allows us determine what types of units the sensor uses, etc.

/** 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)
} sensors_type_t;

Sensor Details (sensor_t)

This typedef describes the specific capabilities of this sensor, and allows us to know what sensor we are using beneath the abstraction layer.

/* 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;

The individual fields are intended to be used as follows:

  • name: The sensor name or ID, up to a maximum of twelve characters (ex. "MPL115A2")
  • version: The version of the sensor HW and the driver to allow us to differentiate versions of the board or driver
  • sensor_id: A unique sensor identifier that is used to differentiate this specific sensor instance from any others that are present on the system or in the sensor network
  • type: The sensor type, based on sensors_type_t in sensors.h
  • max_value: The maximum value that this sensor can return (in the appropriate SI unit)
  • min_value: The minimum value that this sensor can return (in the appropriate SI unit)
  • resolution: The smallest difference between two values that this sensor can report (in the appropriate SI unit)
  • min_delay: The minimum delay in microseconds between two sensor events, or '0' if there is no constant sensor rate

Sensor Data/Events (sensors_event_t)

This typedef is used to return sensor data from any sensor supported by the abstraction layer, using standard SI units and scales.

/* 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,
        sensors_color_t color;
    };
} sensors_event_t;

It includes the following fields:

  • version: Contain 'sizeof(sensors_event_t)' to identify which version of the API we're using in case this changes in the future
  • sensor_id: A unique sensor identifier that is used to differentiate this specific sensor instance from any others that are present on the system or in the sensor network (must match the sensor_id value in the corresponding sensor_t enum above!)
  • type: the sensor type, based on sensors_type_t in sensors.h
  • timestamp: time in milliseconds when the sensor value was read
  • data[4]: An array of four 32-bit values that allows us to encapsulate any type of sensor data via a simple union (further described below)

Required Functions

In addition to the two standard types and the sensor type enum, all drivers based on Adafruit_Sensor must also implement the following two functions:

bool getEvent(sensors_event_t*);

Calling this function will populate the supplied sensors_event_t reference with the latest available sensor data. You should call this function as often as you want to update your data.

void getSensor(sensor_t*);

Calling this function will provide some basic information about the sensor (the sensor name, driver version, min and max values, etc.

Standardised SI values for sensors_event_t

A key part of the abstraction layer is the standardization of values on SI units of a particular scale, which is accomplished via the data[4] union in sensors_event_t above. This 16 byte union includes fields for each main sensor type, and uses the following SI units and scales:

  • acceleration: values are in meter per second per second (m/s^2)
  • magnetic: values are in micro-Tesla (uT)
  • orientation: values are in degrees
  • gyro: values are in rad/s
  • temperature: values in degrees centigrade (Celsius)
  • distance: values are in centimeters
  • light: values are in SI lux units
  • pressure: values are in hectopascal (hPa)
  • relative_humidity: values are in percent
  • current: values are in milliamps (mA)
  • voltage: values are in volts (V)
  • color: values are in 0..1.0 RGB channel luminosity and 32-bit RGBA format
  • tvoc: values are in parts per billion (ppb)
  • voc_index: values are an index from 1-500 with 100 being normal
  • nox_index: values are an index from 1-500 with 100 being normal
  • CO2: values are in parts per million (ppm)
  • eCO2: values are in parts per million (ppm)
  • pm10_std: values are in parts per million (ppm)
  • pm25_std: values are in parts per million (ppm)
  • pm100_std: values are in parts per million (ppm)
  • pm10_env: values are in parts per million (ppm)
  • pm25_env: values are in parts per million (ppm)
  • pm100_env: values are in parts per million (ppm)
  • gas_resistance: values are in ohms
  • unitless_percent: values are in %

The Unified Driver Abstraction Layer in Practice

Using the unified sensor abstraction layer is relatively easy once a compliant driver has been created.

Every compliant sensor can now be read using a single, well-known 'type' (sensors_event_t), and there is a standardized way of interrogating a sensor about its specific capabilities (via sensor_t).

An example of reading the TSL2561 light sensor can be seen below:

 Adafruit_TSL2561 tsl = Adafruit_TSL2561(TSL2561_ADDR_FLOAT, 12345);
 ...
 /* Get a new sensor event */ 
 sensors_event_t event;
 tsl.getEvent(&event);
 
 /* Display the results (light is measured in lux) */
 if (event.light)
 {
   Serial.print(event.light); Serial.println(" lux");
 }
 else
 {
   /* If event.light = 0 lux the sensor is probably saturated
      and no reliable data could be generated! */
   Serial.println("Sensor overload");
 }

Similarly, we can get the basic technical capabilities of this sensor with the following code:

 sensor_t sensor;
 
 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("");

More Repositories

1

Adafruit_NeoPixel

Arduino library for controlling single-wire LED pixels (NeoPixel, WS2812, etc.)
C++
2,862
star
2

Adafruit-GFX-Library

Adafruit GFX graphics core Arduino library, this is the 'core' class that all our other graphics libraries derive from
C
2,111
star
3

DHT-sensor-library

Arduino library for DHT11, DHT22, etc Temperature & Humidity Sensors
C++
1,835
star
4

Fritzing-Library

Adafruit parts, components, breakouts, etc...in Fritzable format!
1,605
star
5

Adafruit_SSD1306

Arduino library for SSD1306 monochrome 128x64 and 128x32 OLEDs
C++
1,587
star
6

Adafruit-Raspberry-Pi-Python-Code

Adafruit library code for Raspberry Pi
1,414
star
7

Adafruit_Python_DHT

Python library to read the DHT series of humidity and temperature sensors on a Raspberry Pi or Beaglebone Black.
C
1,091
star
8

Adafruit-Eagle-Library

Slowly building up a collection of parts we use here ... This file includes some library parts from microbuilder.eu Most of 'em are either Eagle parts that I've changed a little to make them easier to solder, some are 'handmade' and a few are from microbuilder.eu Its released into the Public Domain - that means you can do whatever you want. We'd like it if you kept the author email/url in the part description, just so we can be alerted if there are errors. Enjoy!
1,005
star
9

Adafruit_Learning_System_Guides

Programs and scripts to display "inline" in Adafruit Learning System guides
C
990
star
10

Adafruit-Pi-Finder

Find and set up your brand new Raspberry Pi
JavaScript
844
star
11

Adafruit_CAD_Parts

CAD files for various boards, components and parts
SMT
829
star
12

RTClib

A fork of Jeelab's fantastic RTC Arduino library
C++
760
star
13

Adafruit_CircuitPython_Bundle

A bundle of useful CircuitPython libraries ready to use from the filesystem.
Shell
737
star
14

awesome-circuitpython

A curated list of awesome CircuitPython guides, videos, libraries, frameworks, software and resources.
620
star
15

Adafruit_nRF52_Arduino

Adafruit code for the Nordic nRF52 BLE SoC on Arduino
C
608
star
16

Adafruit_MQTT_Library

Arduino library for MQTT support
C++
541
star
17

Adafruit_Python_SSD1306

Python library to use SSD1306-based 128x64 or 128x32 pixel OLED displays with a Raspberry Pi or Beaglebone Black.
Python
519
star
18

Adafruit-ST7735-Library

This is a library for the Adafruit 1.8" SPI display http://www.adafruit.com/products/358 and http://www.adafruit.com/products/618
C++
495
star
19

Adafruit_TinyUSB_Arduino

Arduino library for TinyUSB
C
483
star
20

Adafruit-WebIDE

This is a simple editor to be used on the Raspberry Pi (or anywhere?).
JavaScript
474
star
21

adafruit-beaglebone-io-python

Adafruit's BeagleBone IO Python Library
C
465
star
22

Adafruit_GPS

An interrupt-based GPS Arduino library for no-parsing-required use
C++
450
star
23

pi_video_looper

Application to turn your Raspberry Pi into a dedicated looping video playback device, good for art installations, information displays, or just playing cat videos all day.
Python
442
star
24

Adafruit_nRF52_Bootloader

USB-enabled bootloaders for the nRF52 BLE SoC chips
C
437
star
25

Adafruit-PWM-Servo-Driver-Library

Adafruit PWM Servo Driver Library
C++
436
star
26

Adafruit-PN532

Arduino library for SPI and I2C access to the PN532 RFID/Near Field Communication chip
C++
397
star
27

Adafruit_Python_GPIO

DEPRECATED! Please use Adafruit Blinka instead (was: Library to provide a cross-platform GPIO interface on the Raspberry Pi and Beaglebone Black using the RPi.GPIO and Adafruit_BBIO libraries.)
Python
393
star
28

Adafruit_Python_BluefruitLE

Python library to simplify access to Bluetooth low energy devices and services on Linux (using bluez) and Mac OSX.
Python
390
star
29

Adafruit-PCD8544-Nokia-5110-LCD-library

Arduino driver for PC8544, most commonly found in small Nokia 5110's
C++
385
star
30

Adafruit_Blinka

Add CircuitPython hardware API and libraries to MicroPython & CPython devices
Python
384
star
31

Adafruit_CircuitPython_HID

USB Human Interface Device drivers.
Python
374
star
32

Adafruit-Fingerprint-Sensor-Library

Arduino library for interfacing to the fingerprint sensor in the Adafruit shop
C++
364
star
33

Adafruit_ILI9341

Library for Adafruit ILI9341 displays
C++
357
star
34

Adafruit-Retrogame

Raspberry Pi GPIO-to-virtual-keyboard utility for classic game emulators
C
348
star
35

Raspberry-Pi-Installer-Scripts

Shell
348
star
36

Adafruit-Motor-Shield-library

Adafruit Motor shield V1 firmware with basic Microstepping support. Works with all Arduinos and the Mega
C++
329
star
37

Adafruit-MCP23017-Arduino-Library

Arduino Library for Adafruit MCP23017
C++
322
star
38

Adafruit_BME280_Library

Arduino Library for BME280 sensors
C++
312
star
39

Adafruit_BNO055

Unified sensor driver for the Adafruit BNO055 orientation sensor breakout
C++
308
star
40

TFTLCD-Library

Arduino library for 8-bit TFT LCDs such as ILI9325, ILI9328, etc
C
301
star
41

Adafruit-Thermal-Printer-Library

Arduino Library for Small Thermal Printers
C++
300
star
42

Reference-Cards

Business card-sized references for Arduino and basic electronics
294
star
43

Adafruit_LED_Backpack

Adafruit LED Backpack Library for our various LED backpacks.
C++
286
star
44

Adafruit_CircuitPython_NeoPixel

CircuitPython drivers for neopixels.
Python
277
star
45

RGB-matrix-Panel

Arduino library and example code for the 16x32 RGB matrix panels in the shop
C++
275
star
46

Adafruit_CC3000_Library

Library code for Adafruit's CC3000 WiFi breakouts &c
C++
270
star
47

Adafruit_ADS1X15

Driver for TI's ADS1015: 12-bit Differential or Single-Ended ADC with PGA and Comparator
C++
268
star
48

Adafruit_Python_PCA9685

Python code to use the PCA9685 PWM servo/LED controller with a Raspberry Pi or BeagleBone black.
Python
258
star
49

Adafruit_TouchScreen

Arduino library for 4-wire resistive touchscreens
C++
251
star
50

Adafruit_CircuitPython_SSD1306

Adafruit CircuitPython framebuf driver for SSD1306 or SSD1305 OLED displays. Not for use with displayio. See README.
Python
249
star
51

Adafruit_BMP280_Library

Arduino Library for BMP280 sensors
C++
230
star
52

Adafruit-BMP085-Library

A powerful but easy to use BMP085/BMP180 Arduino library
C++
223
star
53

Adafruit_SleepyDog

Arduino library to use the watchdog timer for system reset and low power sleep.
C++
218
star
54

Python-Thermal-Printer

Python
213
star
55

Adafruit_IO_Python

Adafruit IO Python Client Library
Python
213
star
56

LPD8806

Arduino library for LED strips and pixels using LPD8806 (and probably LPD8803/LPD8809)
C++
210
star
57

Adalight

Processing
210
star
58

Adafruit_Python_CharLCD

Python library for accessing Adafruit character LCDs from a Raspberry Pi or BeagleBone Black.
Python
208
star
59

Adafruit_FONA

Arduino library for the Adafruit FONA
C++
206
star
60

Adafruit_BusIO

Arduino library for I2C & SPI abstractions
C++
206
star
61

Adafruit-Trinket-USB

Arduino libraries allowing Trinket to act as USB devices
C
205
star
62

Bluefruit_LE_Connect

iOS app for use with Bluefruit Bluetooth LE breakout board
Swift
203
star
63

Adafruit_Floppy

C++
199
star
64

TinyWireM

I2C library for Trinket and Gemma, adapted from BroHogan's code on Arduino Playground
C++
196
star
65

Adafruit_BluefruitLE_nRF51

Arduino library for nRF51822-based Adafruit Bluefruit LE modules
C++
190
star
66

Adafruit_IO_Arduino

Arduino library to access Adafruit IO from WiFi, cellular, and ethernet modules.
C++
188
star
67

Adafruit-WS2801-Library

Arduino library for controlling strips/pixels using WS2801 driver chips
C++
185
star
68

Adafruit_INA219

INA219 Current Sensor
C++
181
star
69

Adafruit_AHRS

Arduino library for AHRS (Attitude and Heading Reference System) for Adafruit motion sensors
C++
175
star
70

Adafruit_Motor_Shield_V2_Library

Arduino library for Adafruit Motor Shield v2!
C++
171
star
71

AccelStepper

A small fork of AccelStepper v1.3 with AF_motor (Adafruit motor shield) support!
C++
167
star
72

Adafruit_NeoMatrix

Adafruit_GFX-compatible library for NeoPixel grids
C++
167
star
73

SD

fixes & updates to the Arduino SD library - totally in progress. works but in beta
C++
166
star
74

Adafruit_ESP8266

Example code for ESP8266 chipset
C++
165
star
75

RadioHead

A github'ified version of http://www.airspayce.com/mikem/arduino/RadioHead/
C++
164
star
76

Adafruit_CircuitPlayground

library for Circuit Playground board
C++
159
star
77

Raw-IR-decoder-for-Arduino

Take raw IR signal from a remote receiver and print out pulse lengths
C++
158
star
78

circuitpython-org

CircuitPython's website
HTML
153
star
79

Bluefruit_LE_Connect_v2

iOS app for use with Bluefruit Bluetooth LE modules and dev boards from Adafruit (v2.0)
Swift
152
star
80

MAX6675-library

Arduino library for interfacing with MAX6675 thermocouple amplifier
C++
136
star
81

CircuitPython_Community_Bundle

A bundle of useful CircuitPython libraries from the CircuitPython community.
Shell
134
star
82

Adafruit_TCS34725

Arduino library driver for Adafruit's TCS34725 RGB Color Sensor Breakout
C++
133
star
83

Adafruit-VC0706-Serial-Camera-Library

Library for VC0706-based Serial JPEG Cameras
C++
132
star
84

adafruit-bluefruit-le-desktop

Desktop application to interact with Bluefruit LE and other Bluetooth low energy devices on Mac OSX, Windows, and Linux.
JavaScript
131
star
85

Adafruit_VL53L0X

Arduino library for Adafruit VL53L0X
C++
131
star
86

Adafruit_NFCShield_I2C

I2C Driver for Adafruit's PN532-based NFC Shield
C++
128
star
87

awesome-feather

A curated list of awesome Feather form factor boards, guides, videos, libraries, software and resources.
127
star
88

Adafruit_CircuitPython_ADS1x15

CircuitPython drivers for the ADS1x15 series of ADCs.
Python
127
star
89

Adafruit_CircuitPython_BLE

Bluetooth Low Energy (BLE) library for CircuitPython
Python
126
star
90

circup

CircuitPython library updater.
Python
124
star
91

Adafruit_SPIFlash

Arduino library for external (Q)SPI flash device
C++
124
star
92

Adafruit_VS1053_Library

This is a Arduino library for the Adafruit VS1053 Codec Breakout and Music Maker Shields
C++
124
star
93

FreqShow

Raspberry Pi & PiTFT-based RTL-SDR frequency scanning and display tool.
Python
123
star
94

Adafruit_Adalink

Python wrapper for Segger's J-Link Commander & STMicro STLink V2 to flash various ARM MCUs
Python
122
star
95

FifteenStep

A general purpose Arduino MIDI sequencer library
C++
121
star
96

TV-B-Gone-kit

*Pew* *Pew* TV's are toast!
C
120
star
97

Adafruit-MLX90614-Library

Arduino library for the MLX90614 sensors in the Adafruit shop
C++
117
star
98

Bluefruit_LE_Connect_Android

Android port of Adafruit's Bluefruit LE Connect app
Java
117
star
99

Adafruit_Python_BME280

Python Driver for the Adafruit BME280 Breakout
Python
116
star
100

Adafruit_Python_ADS1x15

Python code to use the ADS1015 and ADS1115 analog to digital converters with a Raspberry Pi or BeagleBone black.
Python
114
star