This library allows you to use I2C devices such as accelerometers, gyroscopes, and barometers in your Arduino, ESP8266, mbed, Particle and Raspberry Pi projects, without knowing the intimate details about the sensor chip. Say goodbye to reading device data-sheets or learning complex I2C interactions.
Prototype on Arduino or Particle and use the same code when moving to production.
Sensor functions always return SI units, so no extra conversions are required in most situations.
The recommended way to use this library is with PlatformIO:
$ platformio lib install 578If you are using the Arduino IDE, find Sensors by James Smith in the Library Manager and click install.
If you can't use PlatformIO or Arduino Library Manager, you can always simply copy the library into your project or include it as a git submodule. This is the preferred approach for the Particle platform, as you can see in the particle example app .
Once you've installed the library, you'll need to define which sensor devices are installed (see supported devices) and then include Sensors.h:
#define SENSORS_MPU6050_ATTACHED
#define SENSORS_BMP085_ATTACHED
#include <Sensors.h>You'll then be able to use sensors as follows:
Accelerometer *accelerometer = Sensors::getAccelerometer();
Vector3 acceleration = accelerometer->getAcceleration();See the sensor types section below for details on each sensor type, and check out the example apps folder for some complete examples.
The following sensor types are currently supported by this library:
An accelerometer measures proper acceleration (including gravity) in m/s², on three axes.
// Get access to the accelerometer
Accelerometer *accelerometer = Sensors::getAccelerometer();
// Get the current acceleration vector (x/y/z), in m/s^2
Vector3 acceleration = accelerometer->getAcceleration();A barometer measures atmospheric pressure in hPa (or millibars).
Using atmospheric pressure from a barometer, you can also compute the altitude in meters.
// Get access to the barometer
Barometer *barometer = Sensors::getBarometer();
// Get the current ambient air pressure in hPA (mbar)
float pressure = barometer->getPressure();
// Get the current altitude in m, based on the standard baseline pressure
float altitude = barometer->getAltitude();
// Get the current altitude in m, based on a provided baseline pressure
float altitude = barometer->getAltitude(baselinePressure);
// Get the pressure at sea-level in hPa, given the current altitude
float sealevelPressure = barometer->getSealevelPressure(altitude);A gyroscope measures the rotational speed in rad/s, on three axes.
// Get access to the gyroscope
Gyroscope *gyroscope = Sensors::getGyroscope();
// Get the current rotation rate vector (x/y/z), in rad/s
Vector3 rotation = gyroscope->getRotation();A magnetometer measures the strength and direction of magnetic fields in μT, on three axes.
Using magnetic field readings from a magnetometer, you can also compute the azimuth (or compass direction) of your device.
// Get access to the magnetometer
Magnetometer *magnetometer = Sensors::getMagnetometer();
// Get the current magnetic field strength vector (x/y/z), in μT
Vector3 magneticField = magnetometer->getMagneticField();
// Get the current azimuth (compass direction), optionally adjusting for declination
float azimuth = magnetometer->getAzimuth();A thermometer measures temperature in °C.
// Get access to the thermometer
Thermometer *thermometer = Sensors::getThermometer();
// Get the current temperature, in °C
float temperature = thermometer->getTemperature();The following I2C devices are currently supported by this library:
| Device | Provides Sensors | #define |
|---|---|---|
| AK8963 | Magnetometer | SENSORS_AK8963_ATTACHED |
| BMP085 | Barometer, Thermometer | SENSORS_BMP085_ATTACHED |
| BMP180 | Barometer, Thermometer | SENSORS_BMP180_ATTACHED |
| HMC5883L | Magnetometer | SENSORS_HMC5883L_ATTACHED |
| MPU6050 | Accelerometer, Gyroscope | SENSORS_MPU6050_ATTACHED |
| MPU6500 | Accelerometer, Gyroscope | SENSORS_MPU6500_ATTACHED |
| MPU9150 | Accelerometer, Gyroscope, Magnetometer | SENSORS_MPU9150_ATTACHED |
| MPU9250 | Accelerometer, Gyroscope, Magnetometer | SENSORS_MPU9250_ATTACHED |
If you'd like to see another sensor device supported here, see the contributing section below.
This library supports almost every popular embedded platform, including the following development boards:
| Platform | Boards |
|---|---|
| Arduino | Any Atmel AVR or Atmel SAM based Ardunio, or Arduino-like board |
| ESP8266 | Any ESP8266 based board |
| mbed | Most boards using the ARM mbed framework |
| Particle | Particle Core, Particle Photon, Particle Electron |
| Raspberry Pi | Any board which support WiringPi |
| Teensy | Any Teensy board |
If you test a new platform or development board and can confirm it works, please let me know in an issue and I'll update this documentation.
I'd love you to file issues and send pull requests. The contributing guidelines details the process of adding support for sensors, devices and frameworks, building and testing the library, as well as the pull request process. Feel free to comment on existing issues for clarification or starting points.
This library is free software released under the MIT License. See LICENSE.txt for details.