This will be a multipart series on how to use a digital compass(magnetometer) with your Raspberry Pi.

The magnetometer used in these tutorials is a LSM9DS0 which is on a BerryIMU. We will also point out where some of the information can be found in the Datasheet for the LSM9DS0. This will help you understand how the LSM9DS0 works.

The math and logic in this series can also be used with other magnetometers or IMUs.

We will also go over how to do some basic communication on the i2c bus. As well as using SDL to display the compass heading as traditional compass as shown in the video above.

Git repository here
The code can be pulled down to your Raspberry Pi with;

The code for this guide can be found under the compass_tutorial01_basics directory. 

Overview of a Compass

A traditional Magnetic compass (as opposed to a gyroscopic compass) consists of a small, lightweight magnet balanced on a nearly frictionless pivot point. The magnet is generally called a needle. The Earth’s Magnetic field will cause the needle to point to the North Pole.

To be more accurate, the needle points to the Magnetic North. The angle difference between true North and the Magnetic North is called declination. Declination is different in different locations. This angle varies depending on position on the Earth's surface, and changes over time.

The strength of the earth's magnetic field is about 0.5 to 0.6 gauss .

There is also  a component parallel to the earth's surface that always points toward the magnetic north pole. In the northern hemisphere, this field points down. At the equator, it points horizontally and in the southern hemisphere, it points up. This angle between the earth’s magnetic field and the horizontal plane is defined as an inclination angle.

Magnetometer, is usually a microelectromechanical system (MEMS) instrument for measuring the strength and the direction of a magnetic field on 3 axis.

Connecting the magnetometer to the Raspberry Pi

The image below shows how to wire up the magnetometer or BerryIMU to the Raspberry Pi.

Enable i2c on the Raspberry Pi

The components on the BerryIMU talk to the Raspberry Pi via i2c.

You can follow this guide to enable i2c on your Raspberry Pi

i2c is a communication protocol that runs over a two wire bus. The two wires are called SDA (Serial Data) and SCL (Serial Clock). The i2c bus has one or more masters (the Raspberry Pi) and one or more slave devices, like LSM9DS0 on the BerryIMU. As the same data and clock lines are shared between multiple slaves, we need some way to choose which device to communicate with. With i2c, every device has an address that each communication must be prefaced with. The LSM9DS0 can have two addresses, either 0x1E or 0x1D.  This address is controlled by one pin on the LSM9DS0 . If this pin is connected to a voltage supply, the address will be 0x1D. And if connected to ground, it will be 0x1E.
On the BerryIMU the address of LSM9DS0 is 0x1E.

This information can be found on page 33 of the datasheet.

i2cdetect can be used to confirm the addresses used by the magnetometer or BerryIMU

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- 1e -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- 6a -- -- -- --
70: -- -- -- -- -- -- -- --

In the above example the magnetometer (LSM303D) is using the address of 0x1D.

We read and write values to different registers on the magnetometer to perform different tasks. Eg Turn the magnetometer on , set the sensitivity level, read magnetic values. etc..

The git repository also includes LSM9DS0.h which lists all the registers we use for this sensor.

Open the I2C Bus

We use ioctl calls to read and write information to the i2c bus. So the first task to do is we need to open the I2C bus device file, as follows;

        char filename[20];
        sprintf(filename, "/dev/i2c-%d", 1);
        file = open(filename, O_RDWR);
        if (file<0) {
                printf("Unable to open I2C bus!");
                exit(1);
        }

As we are using sprintf, you will need to include the header file stdio.h

Selecting the magnetometer
Before we can start writing and reading values form the magnetometer, we need to select the address of the magnetometer;

        if (ioctl(file, I2C_SLAVE, MAG_ADDRESS) < 0) {
                printf("Error: Could not select magnetometer\n");
        }

You will need to include the file control headers in your program, fcntl.h.
You will also need to include the headers for the i2c bus - linux/i2c-dev.h

MAG_ADDRESS is defined in LSM9DS0.h

Enable the magnetometer

To enable the magnetometer, we will need to set some register values on the sensor.

The i2c_smbus_write_byte_data() function can be used to write to a device's register on the i2c bus.
This function can be found in linux/i2c-dev.h headers.

The decleration for this function is;
i2c_smbus_write_byte_data (struct i2c_client * client, u8 command, u8 value);

i2c_client is the pointer we used to open the i2c bus, command is the register we want to write to and value is the value we want to write.

As we will be writing to the magnetometer often, we should create a function;

void writeMagReg(uint8_t reg, uint8_t value)
{
  int result = i2c_smbus_write_byte_data(file, reg, value);
    if (result == -1)
    {
        printf ("Failed to write byte to I2C Mag.");
        exit(1);
    }
}

You can now go ahead and enable the magnetometer;

 writeMagReg( CTRL_REG5_XM, 0b11110000);
 writeMagReg( CTRL_REG6_XM, 0b01100000);
 writeMagReg( CTRL_REG7_XM, 0b00000000);

A brief description of the settings and where the information can be found in the datasheet;

• CTRL_REG5_XM- Enable internal temperature sensor - Set magnetometer to high resolution - set a datarate of 50Hz - page 59 on the datasheet.
• CTRL_REG6_XM - Will set the full scale selection to +/- 12 Gauss - page 60 on the datasheet.
• CTRL_REG7_XM - Se the magnetometer to Continuous-conversion mode - page 60 on the datasheet.

Reading Raw Values from the Magnetometer

Reading data from the magnetometer is similar to writing data, but rather than just reading one byte we will be reading a block of bytes. E.g. 6 bytes.

We will use the i2c_smbus_read_i2c_block_data() function found in linux/i2c-dev.h.

We will create two of our own functions which we will be used to read data from the magnetometer.

This is the read block function which also performs error checking;

void  readBlock(uint8_t command, uint8_t size, uint8_t *data)
{
    int result = i2c_smbus_read_i2c_block_data(file, command, size, data);
    if (result != size)
    {
       printf("Failed to read block from I2C.");
        exit(1);
    }
}

This function uses the above function to read raw magnetic values from the magnetometer;

void readMAG(int  *m)
{
        uint8_t block[6];
        readBlock(0x80 | OUT_X_L_M, sizeof(block), block);
        *m = (int16_t)(block[0] | block[1] << 8);
        *(m+1) = (int16_t)(block[2] | block[3] << 8);
        *(m+2) = (int16_t)(block[4] | block[5] << 8);
}

Here is what is happening in the readMAG() function;
1) An array of 6 bytes is first created to store the values.
2) Using the readBlock() function, we read 6 bytes starting at OUT_X_L_M (0x08). This is shown on page 52 of the datasheet.
3) The values are expressed in 2’s complement (MSB for the sign and then 15 bits for the value) so we need to combine;
block[0] & block[1] for X axis
block[2] & block[3] for Y axis
block[4] & block[5] for Z axis

Print Raw values

We can now create a loop within our program to read the raw values from the magnetometer and print them to screen.
I have added a delay of 0.25 seconds to make the output easier to read.

int magRaw[3];
while(1)
{
        readMAG(magRaw);
	printf("magRaw X %i    \tmagRaw Y %i \tMagRaw Z %i \n", magRaw[0],magRaw[1],magRaw[2]);
        usleep(250000);
}

The output should be similar to the output below. You will notice that the output changes even though the magnetometer is not moving. This is because all magnetometers are noisy. In a future post, we will show how to filter this noise out.

magRaw X 1024    magRaw Y 1024   MagRaw Z 17920
magRaw X 1280    magRaw Y 256    MagRaw Z 18176
magRaw X 1280    magRaw Y 512    MagRaw Z 17152
magRaw X 512     magRaw Y -513   MagRaw Z 16384
magRaw X 1792    magRaw Y -1     MagRaw Z 18432
magRaw X 512     magRaw Y -257   MagRaw Z 17408
magRaw X 256     magRaw Y -257   MagRaw Z 16384
magRaw X 1280    magRaw Y -257   MagRaw Z 17920
magRaw X 1024    magRaw Y 768    MagRaw Z 17920
magRaw X 768     magRaw Y -513   MagRaw Z 16640
magRaw X 1536    magRaw Y -257   MagRaw Z 18432
magRaw X 768     magRaw Y -1     MagRaw Z 18176
magRaw X 1024    magRaw Y -257   MagRaw Z 17664

Calculate Heading

We can use the below formula to calculate the heading. This only works with the magnetometer is on a flat surface.

 heading = 180 * atan2(magRawY,magRawX)/M_PI;

You will need to include the math header file in your program, math.h and when compiling you will also need to link the math library. '-lm'

With just the above formula, we will get the heading between the values -180 to 180.
We will use the snipped below to change this to a heading value between 0 and 360

        if(heading < 0)
              heading += 360;

We will add the relevant code to our main loop and also print the heading value.

Your main loop should look something like this;

        while(1)
        {
                readMAG(magRaw);
		printf("magRaw X %i    \tmagRaw Y %i \tMagRaw Z %i \n", magRaw[0],magRaw[1],magRaw[2]);
                float heading = 180 * atan2(magRaw[1],magRaw[0])/M_PI;
                if(heading < 0)
                      heading += 360;
                printf("heading %7.3f \t ", heading);
                usleep(250000);
        }

To compile;

your output should now look like this;

heading 118.078          magRaw X -2305  magRaw Y -3073  MagRaw Z 13312
heading 126.873          magRaw X -2305  magRaw Y -1281  MagRaw Z 12800
heading 150.937          magRaw X -769   magRaw Y -2561  MagRaw Z 11776
heading 106.714          magRaw X -2561  magRaw Y -2561  MagRaw Z 12288
heading 135.000          magRaw X -2049  magRaw Y -1537  MagRaw Z 12800
heading 143.126          magRaw X -1537  magRaw Y -1793  MagRaw Z 12288
heading 130.604          magRaw X -2049  magRaw Y -1793  MagRaw Z 12800
heading 138.812          magRaw X -1281  magRaw Y -1793  MagRaw Z 12288
heading 125.544          magRaw X -1537  magRaw Y -1793  MagRaw Z 12288
heading 130.604          magRaw X -2049  magRaw Y -2561  MagRaw Z 13056
heading 128.663          magRaw X -2817  magRaw Y -1537  MagRaw Z 12544
heading 151.382          magRaw X -769   magRaw Y -2817  MagRaw Z 13568

When rotating your magnetometer clockwise, the heading should increase. It should decrease when rotated counter clockwise.
If this is not the case, then you need to convert the Y axis. This will happen if the magnetometer is upside down, like when the BerryIMU is sitting on the Raspberry Pi GPIO headers;

                magRaw[1] = -magRaw[1];

The above line should be added just before the heading calculation is done.

In future posts, we will cover compass calibration, tilt compensation and displaying the heading as a traditional compass using SDL.

Guides and Tutorials

• Guide to interfacing a Gyro and Accelerometer with a Raspberry Pi
• Guide to interfacing a Gyro and Accelerometer with a Raspberry Pi - Kalman Filter
• Create a Digital Compass with the Raspberry Pi – Part 2 – “Tilt Compensation”
• Create a Digital Compass with the Raspberry Pi – Part 3 – “Calibration”
• Create a Digital Compass with the Raspberry Pi – Part 4- “Smartphone Replica”
• Converting values from an Accelerometer to Gs – “ Proper Acceleration”
• Using the BerryIMUv3 on a Raspberry Pi Pico
• How to Create an Inclinometer using a Raspberry Pi and an IMU
• Raspberry Pi Digital Spirit Level
• Double tap detection with BerryIMUv3
• Connect BerryIMUv3 via SPI