Adafruit 9-DOF with a Raspberry Pi

The sensor I will be using in this tutorial is from Adafruit Industries and is called the
9-DOF IMU Breakout. It combines two sensors into one chip for 9 axes of data (or 9 Degrees of
Freedom); the L3GD20H which provides 3 axes of gyroscopic, and the L SM303 which provides
3 axes of accelerometer and 3 axes of magnetic (compass). Together these two chips are
combined to create what is called an inertial measuring unit or an IMU. I will be demonstrating
how to connect this IMU to a Raspberry Pi, but if you are using an Arduino instead, the links
provided to the chips have some nice tutorials on how to connect the sensor along with some
sample code.
The magnetometer in the LSM303 chip is probably the easiest of the three sensors to
understand. It simply senses in which direction the strongest magnetic force is coming from, and
is typically used to find magnetic north. This chip is generally combined with the accelerometer
to reorient the sensor if it strays from its initial orientation.
The accelerometer on the LSM303 measures inertial force. This force is ideally only
caused by gravity, and returns measurements in the unit g where 1 g is equal to 9.81m/s2. So
when the chip shifts position, the x,y, and z axes update the gs in each axes depending on
which axes are facing towards the earth. The problem with gyroscopes in general however is
that they measure all inertial forces meaning any acceleration it experiences from vibrations or
external motion makes its readings unreliable.
The gyroscope which is the chip that I will be demonstrating with sample code, is often
used in conjunction with the magnetometer and accelerometer to fight this drift experienced by
the accelerometer. The gyroscope on the L3GD20H only measures the rate of change rotational
motion which spits out values that will eventually need to be converted to deg/s. The reason this
is so often paired with an accelerometer is that it suffers from a different flaw. The
accelerometer is sensitive to all changes in motion, linear and rotational. The gyroscope only
measures rotational motion meaning it's values aren't nearly as susceptible to vibration and
linear acceleration. However, the gyroscope has its own problem called drift. Over time the
accumulated readings don't always return to the original calibrated zero and output incorrect
values.
The most common use of IMUs are for internal navigation systems that calculate a
crafts position without needing any outside communication. IMUs are most commonly used in
aircraft, spacecraft, unmanned landers, watercraft, guided missiles, animation capture, and
robotics. However specifically when the IMU is being used as a unit, the largest contributor to
error is from the accumulated drift. This occurs because the 9-DOF board is continuously adding
detected changes to its previous calculations, and any errors in this data accumulate from point
to point. For this reason specifically, these chips are typically used in conjunction with a GPS
system which periodically checks the position of the IMU to ensure it didn't stray.
For more specific technical resources on these chips I have provided their Datasheets.
LSM303
L3GD20H
 Adafruit has managed to make the 9-DOF IMU very simple to connect and to set up.
Since the chip communicates digitally through the I2C interface then you only have to connect 4
pins to the board. They are pins for the power, ground, and the SCL(Serial Clock) and
SDA(Serial Data) pins. Typically these sensors only operate on 3.3V , but because many IMUs
such as this one are used by the Raspberry Pi and the Arduino among other boards, Adafruit
included a 3V regulator so you can connect the VIN pin to 3V or 5V without having to worry
about frying the sensors. The GND pin goes to GND, the SCL on 9-DOF connects to the GPI03
pin, and the SDA connects to the GPI02 pin on the Pi. The first diagram shows the physical pin
connections and the second image is a schematic displaying the names of each pin.
After you have the pins connected up correctly, it is a good idea to double check by using this
command line in the terminal.

The L3GD20 board/chip uses I2C 7-bit address 0x6B

The LSM303 board/chip uses I2C 7-bit addresses 0x19 & 0x1E

If you get an error, try using the command: sudo /usr/sbin/i2cdetect -y 0

 If you have the pins connected correctly for the Adafruit 9-DOF board then this exact
output should appear. If you have a different 9-DOF board, then it is probable that different
numbers and letters will appear on different lines because the different sensor chips send data
to different addresses on the Pi. If however, this command executes and no numbers or letters
appear then you have a couple things to try. First, double check that everything is wired up
correctly. If it is, and you still arent getting a connection, then you may need to enable the I2C
on your Raspberry Pi by following t his guide.
Once you get this reading on your terminal then it is time to enter in some python code
and test your readings. I have collected some example code for the gyro and the
accelerometer/magnetometer to show their individual outputs.
For the gyroscope, I used this code from GitHub. If you want to just download this
directly to your Pi, you can enter this command line and it will automatically download all the
necessary files.

If however you want specific files, then you can just go to the website provided and only
download what you need. However, if you are attempting to run any of the
Example_ReadRawData.py or the Example_ReadRealData.py you will also need to download
the L3GD20.py and the BitOps.py libraries and put them in the same folder as the Example
files. Since it is somewhat easy to make a mistake in this process I recommend just
downloading it through the command line terminal as I showed previously. Then all of the library
files and example files will already be in the correct place.
Once everything is downloaded, enter these two commands into your terminal and you
should get a reading looking like this.
 This is simply printing out the angular speed in the x, y, and z axes. So it initializes at
zero and then the first time I moved it, it rotated at -1.18 deg/s in the x axis, 6.06 deg/s in the y
axis, and -6.06 deg/s in the z axis.
So lets take a look at the code.

1. The first line is referencing one of the libraries we downloaded along with our example
files so that the communication object he has labeled can refer to the L3GD20 code.
2. The next line (import time) is accessing a module that automatically comes with python
and gives you access to certain functions.
3. The #Communication Object line sets the library L3GD20.py equal to a sting value s.
The values inside the parenthesis are simply setting up the chip to communicate with
specific pins and setting up the code within L3GD20.py to perform certain operations.
4. The next 5 lines of code under #Preconfiguration are configuring more values within the
L3GD20.py code so that it will operate at a certain power mode, speed, and using all
three axes.
5. The next line s.Init() initializes the internal data structures in both code files, and the next
line s.Calibrate() sets up the initial values of the x,y,z axes of the gyroscope to zero.
6. The next four lines just set an int number equal to a certain variable.
 7. The while loop creates an infinite loop so that the values continue printing out. In order to
exit the program while running all you have to do is hit Ctrl+C.
8. Time.sleep(dt) suspends the program from printing out the information for 0.25 seconds
in this case. If you want an update from the gyroscope more often or less often, simply
change the dt value to another number.
9. The next line retrieves the values that the gyroscope returns.
10. With that information, the following 3 lines change those values into readable deg/s.
11. The final line produces the 3 values you see whenever you execute the code.

If you wish to use the LSM303, then t his code is one place to start. All you have to do is copy
this code into a python file, save it, and run it through your terminal. Unfortunately this code
simply prints out the raw data which needs to be converted to usable numbers, but if you get it
running, this is what it should look like.

Usually if you are using this chip, the goal would be to get it working as one unit so that is is
truely a functioning IMU. Its difficult to find code for a 9DOF unit in Python since converting this
data requires a decent amount of processing power so it is usually coded in something like C++
since a lower level language can allow faster processing. That being said, if you want to read
more about how to get accelerometers and gyroscopes working together you can refer to these
guides:

Easy to follow guide for a BerryIMU chip

Video for LSM330 chip
In depth explanation of getting a Gyro to work with an Accelerometer