PyBerryIMU
I2C communications lib for using BerryIMU.
Branch | Build status | Test Coverage |
---|---|---|
master |
||
develop |
This library uses and includes several snippets of code from the Official BerryIMU repository.
Installation
Required Raspbian packages
- build-essential
- python-dev
- libi2c-dev
- i2c-tools
- libffi-dev
After the package dependencies above are installed, PyBerryIMU can be installed with pip:
pip install git+git://github.com/hbldh/pyberryimu.git
This library uses smbus-cffi for communication over i2c.
Usage
Basic use
The BerryIMU can be interfaced with by using the BerryIMUClient
:
from pyberryimu.client import BerryIMUClient
with BerryIMUClient(bus=1) as c:
acc = c.read_accelerometer()
gyro = c.read_gyroscope()
mag = c.read_magnetometer()
pr = c.read_pressure()
temp = c.read_temperature()
This returns raw readings from the BerryIMU regarding acceleration, angular velocity and magnetic fields; it requires calibration to be useful. The pressure and temperature are already converted to SI units.
Recorder to obtain data for offline analysis
A simple tool for recording data from the BerryIMU to have for offline analysis is also included in the module.
import os
from pyberryimu.client import BerryIMUClient
from pyberryimu.recorder import BerryIMURecorder
with BerryIMUClient() as c:
brec = BerryIMURecorder(c, frequency=100, duration=10)
data_container = brec.record(acc=True, gyro=True, mag=True, pres=False, temp=False)
data_container.save(os.path.expanduser('~/pyberryimu_rec_test.json'))
The data is then stored in a highly non-optimized way as a JSON document that can be loaded as such:
import os
from pyberryimu.container import BerryIMUDataContainer
data_container = BerryIMUDataContainer.load(os.path.expanduser('~/pyberryimu_rec_test.json'))
See the example in pyberryimu/sample/recorder.py
Note that the maximum frequency is about 100 Hz for reading from all three IMU sensors (accelerometer, gyroscope and magnetometer) on a Raspberry Pi 2. When adding pressure readings it drops to about 10 Hz due to the fact that one has to wait during pressure and temperature reading. Run max frequency test script pyberryimu/sample/max_freq_test.py to get a more complete picture of maximal frequencies.
Calibration
Using data sheet values
One can skip calibration procedures and just use the general conversion values from the sensors data sheet instead of calibrating, but the readings will most probably be less accurate.
from pyberryimu.client import BerryIMUClient
from pyberryimu.calibration.standard import StandardCalibration
sc = StandardCalibration.load()
c = BerryIMUClient(bus=1)
c.open()
sc.set_datasheet_values_for_accelerometer(c.get_settings())
sc.set_datasheet_values_for_gyroscope(c.get_settings())
sc.set_datasheet_values_for_magnetometer(c.get_settings())
c.calibration_object = sc
This will yield accelerometer output in the unit g
,
gyroscope output in unit degrees/s
and magnetometer output in unit gauss
.
Accelerometer
Calibration of accelerometer is performed using the method described in Frosio, I.; Pedersini, F.; Alberto Borghese, N., "Autocalibration of MEMS Accelerometers," Instrumentation and Measurement, IEEE Transactions on , vol.58, no.6, pp.2034,2041, June 2009.
First it prompts the user to position the BerryIMU such that Earth's gravity acts on only one of the axes at a time, in both directions. This six point calibration gives a zero G value and a sensitivity for each axis. At least three more points are needed to complete the calibration, which can be chose arbitrarily with the only restriction that the BerryIMU is static. When these have been collected, an optimisation is done to fit final calibration parameters.
from pyberryimu.client import BerryIMUClient
from pyberryimu.calibration.standard import StandardCalibration
sc = StandardCalibration(verbose=True)
c = BerryIMUClient(bus=1)
sc.calibrate_accelerometer(c)
c.calibration_object = sc
When using the BerryIMUClient
after assigning a StandardCalibration
to the
calibration_object
attribute, the readings returned are in the unit g
.
This calibration can be saved to disc and then loaded later on:
from pyberryimu.client import BerryIMUClient
from pyberryimu.calibration.standard import StandardCalibration
sc = StandardCalibration.load()
with BerryIMUClient(bus=1) as c:
c.calibration_object = sc
c.read_accelerometer()
Gyroscope
The gyroscope is somewhat trickier to calibrate, because it needs a rotating
plane with a known angular velocity. The calibration consists of the collection
seven data points: one static and two for each axis where the sensor is rotated in
its negative and its positive direction. Using three points per axis, a linear
regression model ax + b
is fitted and used for transforming raw readings to output
in either degrees per second or radians per second, depending which angular velocity unit
that is given at calibraion time.
Calibration of gyroscope can be done using a regular vinyl record player, provided one takes some care to position the sensor carefully to capture most rotation of the desired axis.
from pyberryimu.client import BerryIMUClient
from pyberryimu.calibration.standard import StandardCalibration
sc = StandardCalibration(verbose=True)
c = BerryIMUClient(bus=1)
sc.calibrate_gyroscope(c)
c.calibration_object = sc
Magnetometer
Calibration of magnetometer is not implemented yet.
Pressure and Temperature
The BMP180 chip with the pressure and temperature sensors comes with a factory calibration stored on the
chip and is retrieved on the initialisation of a BerryIMUClient
Documentation
TBD