MAGUM sensors library

Introduction

Magum, that stands for Magnetometer, Accelerometer and Gyroscope UDOO Management, is a Python library that allows you to completely manage all three senors built in UDOO Neo.

We tested MAGUM on UDOO Neo rev. D, with UDOObuntu RC1 version. 

With MAGUM you can:

• get data from all registers and write on them too
• monitor in real time the values obtained by the sensors
• using algorithms that use both accelerometer and gyroscope to detect orientation, and magnetometer to measure magnetic fields

The sensors

Below you can find a complete list of all sensors:

• Gyroscope:FXAS2100C from Freescale Semiconductor Inc.(datasheet)
• Accelerometer and Magnetometer:FXOS8700CQ from Freescale Semiconductor Inc.(datasheet)

Axis orientation

magum works with this axis orientation even if the accelerometer is below the board:

Getting Started

Magum works through the Python module smbus-cffi from bivab so you need a few things before you start:

• a C compiler (e.g. gcc)
• i2c developement header files server.
• cffi
• PyPy or CPython development headers
• libffi-dev

To install these, you have to run the following commands from your terminal:

For Debian based distributions (e.g. Ubuntu distros, Linux Mint):

sudo apt-get install build-essential libi2c-dev i2c-tools python-dev libffi-dev

For Arch Linux:

pacman -S base-devel pacman -S i2c-tools

Finally install cffi and smbus-cffi using pip with this command, or from the Github sources: cffi, smbus-cffi

pip install cffi pip install smbus-cffi

Installation

You can obtain MAGUM in different ways:

• Download the repository as zip and unpack it
• Clone our Github repository with these commands from terminal (you have to install git to do this)

sudo apt-get install git

git clone https://github.com/ubalance-team/magum.git

Now navigate in the folder where you (or git) downloaded the repository with the terminal and run this command:

python setup.py install

Magum is now installed like any other Python modules already on your computer.

Usage

Here you can find a guide to the use of the most important methods of magum

Initializing magum

Magum is a Python class that you can initialize using parameters for configuring sensors

Magum(gScaleRange,fsDouble,aScaleRange,noise)

NOTE: If no parameters are entered the class will be automatically initialized with the last values entered

Parameters

• gScaleRange :represents the range of the gyroscope. It can assume the following values: 250,500,1000,2000 dps.
• fsDouble:enables (with value 1) or disables (with value 0) the fsdouble function to double the scale range of the gyroscope
• aScaleRange :represents the range of the accelerometer. In can assume 2 for +/- 2g, 4 for +/- 4g or 8 for +/- 8g
• noise :enables (with value 1) or disables (with value 0) the lnoise function for the accelerometer sensor

Example

magum = Magum(2000,0,2,1)

Creates an instance of Magum called magum with 2000dps of range for the gyroscope, +/- 2g of range for the acceleremoter and lnoise function enabled.

toStandby(sensor)

Put in standby mode the selected sensor

Parameters

• sensor :type 'a' for accelerometer, 'm' for magnetometer, 'g' for gyroscope

Example:

magum.toStandby('a')

toActive(sensor)

Actives the selected sensor

Parameters:

• sensor :type 'a' for accelerometer, 'm' for magnetometer, 'g' for gyroscope

Example:

magum.toActive('a')

killDrivers(x)

Magum can not work if the driver sensor system are active. So it is crucial disable before starting (Magum does automatically when the instance is initialized). killDrivers disable or re-enable these drivers.

Parameters:

• x :if 1 disables drivers, if 0 re-enables them

Example:

magum.killDrivers(1)

setSensConf(sensor,reg,hexVal)

With this method you can enter a value in one of the registers of sensors contained in the file regs.py

Parameters:

• sensor :type 'a' for accelerometer, 'm' for magnetometer, 'g' for gyroscope
• reg :type a register name fromregs.pylist
• hexValue :type the hexadecimal value that you want to write in the chosen register

Example:

magum.setSensConf('a','A_XYZ_DATA_CFG',0x00)

Writes the value 0x00 value in the register named A_XYZ_DATA_CFG of the accelerometer

readAData(uM)

With this method you can get data from accelerometer specifying the unit of measure. Returns an array of three elements:

• array[0]x axis
• array[1]y axis
• array[2]z axis

Parameters:

• uM :type 'raw' for raw values, 'deg' for degrees, 'rad' for radiant, or 'gcomp' for components along the axes of the gravitational acceleration

NOTE: if no parameters are entered readAData returns raw values

Example:

array = magum.readAData('gcomp')

readMData(uM)

With this method you can get data from magnetometer specifying the unit of measure Returns an array of three elements:

• array[0]x axis
• array[1]y axis
• array[2]z axis

Parameters:

• uM :type 'raw' for raw values, 'ut' for μT values

NOTE: if no parameters are entered readMData returns raw values

Example:

array = magum.readMData('ut')

readGData(uM)

With this method you can get data from gyroscope specifying the unit of measure. Returns an array of three elements:

• array[0]x axis
• array[1]y axis
• array[2]z axis

Parameters:

• uM :type 'raw' for raw values, 'deg' for degrees or 'rad' for radiant

NOTE: if no parameters are entered readGData returns raw values

Example:

array = magum.readGData('rad')

getCurrentConf(sensor,screen)

This method returns the content of the registers of the selected sensor

Parameters:

• sensor :type 'a' for accelerometer, 'm' for magnetometer, 'g' for gyroscope
• screen :type 1 if you want to print the values on screen or 0 if you don't

NOTE: if screen parameter is not specified, getCurrentConf will not print values on screen

Example:

magum.getCurrentConf('a',1)

calibrateSens(samples)

This method calibrates the sensors calculating an average based on a selected number of samples (we suggest to work with 1000 samples). Returns an array of 9 elements, with the offsets that you have to subtract from sensors values:

• indexes from 0 to 2:accelerometer
• indexes from 3 to 5:gyroscope
• indexes from 6 to 8:magnetometer

Parameters:

• samples :type the number of samples to base the average for the calibration

Example:

array = magum.calibrateSens(1000)

compFilter(DT,AxisOffset)

Integrates the values from accelerometer and gyroscope using a complementary filter. This filter returns more accurate measurements and less noise. Returns an array with the angles values, for the x,y,z axes.

Parameters:

• DT: is the sampling interval
• AxisOffset: is the array with the offsets returned by calibrateSens(samples) method. It uses the first 6 values of this array

Example:

angles_array = magum.compFilter(0.02,AxisOffset)

kalmanFilter(DT,axis,axisOffset)

The Kalman filter is an efficient recursive filter which evaluates the state of a dynamic system from a series of measurements subject to noise. This filter is more efficient than the complementary filter but requires more computational power, and therefore not very suitable to UDOO Neo. Returns the angle of inclination from the axis chosen.

Parameters:

• DT: is the sampling interval
• axis: is one of the three Cartesian axes: 'x', 'y' or 'z'
• AxisOffset: is the array with the offsets returned by calibrateSens(samples) method. It uses the first 6 values of this array

Example:

angle_z= magum.kalmanFilter(0.02,'z',AxisOffset)