Using a HMC5883L magnetometer/compass with the #RaspberryPi

This blog post describes getting an HMC5883L magnetic compass sensor to work with a Raspberry Pi. The pictures below show the sensor breakout board in question.




For Arduino Leonardo

If you do not have an Arduino, or just want the instructions for the Raspberry Pi, please skip this section.

I followed instructions from to connect the board up to an Arduino Leonardo clone (the Dreamer Nano v4). For the Leo, the I2C ports are D2 (for SDA) and D3 (for SCL). Power supply for the board is 3v3 and you also need to connect up the ground pin. The DRDY pin is not used. I downloaded the Arduino library and examples package from the bottom of that post ( and wired it up like so:

  • VCC -> 3.3v
  • GND -> Ground
  • SDA -> D2
  • SCL -> D3

I used the Arduino IDE to upload the example sketch and opened the serial monitor from which I got the following readings:

Raw: 31 407 -587 Scaled: 28.52 374.44 -540.04 Heading: 1.54 Radians 88.26 Degrees

As I rotated the breadboard on which the sensor was mounted, the readings changed.

For Raspberry Pi

First of all, make sure your Pi has I2C installed and enabled. This is a bit of a trial if you don’t know what you’re doing, but if you have any problems, leave me a comment. Follow these instructions to find out how to do it. After running the last command:
i2detect -y <port>
you should get a value in one of the “cells”. For instance, I get a “1e” reading in the 10/e cell.

Secondly, install the ThinkBowl I2C libraries. Please note, take notice of the fact that for these libraries you need to use Python 3, not just plain Python.

Next, find your magnetic declination by using this site.

Now connect up the sensor board. I used a breadboard and a Hobbytronics GPIO breakout connector, but you can connect it directly to the Pi’s GPIO pins. Here are the pin-to-pin mappings from the Pi to the board. Remember that Pin 1 is the 3v power connector on the Pi’s GPIO so you can count from there.

Pi pin number       Pi pin name        HMC5883L pin name
1                   3V3                VCC
6                   Ground             GND
3                   SDA                SDA
5                   SCL                SCL

Next, use the basic Python example from here (or see below) and run it with python3 (for example python3 and you should get X,Y,Z axis readings and your heading in degrees and minutes. Rotate the board and you should get different readings

from i2clibraries import i2c_hmc5883l
hmc5883l = i2c_hmc5883l.i2c_hmc5883l(1)

NB: If you get an input/output error, try changing the first line to:

hmc5883l = i2c_hmc5883l.i2c_hmc5883l(0)

Lastly, if you have problems getting these instructions to work, please leave a comment or use my contact form
to ask questions.

Here, for interest, is what my Pi looks like when connected up to a breadboard with the sensor board on it.


Resources used for this blog post


20 comments for “Using a HMC5883L magnetometer/compass with the #RaspberryPi

  1. 27 April 2013 at 9:53 pm

    Hi Michael. I’m making a web-browser controlled vehicle, using an Rapberry as “main brain” and a Arduino with a motor shield to run motors and sensors. Communication between Raspberry and Arduino is I2C. Long story, everything is working well…

    I have the same magnetometer sensor, I can read it with my Arduino, store in 3 variables and collect this data with Raspberry, but, if you know the “math” to calculate the “cardinal point”, can you give me some light?

    For exemple, I put the Y in front of my vehicle. Lets say my readings are Y=254, X=-48 and Z=34. How can I calculate the cardinal point my vehicle is facing?
    I know the higher values are nearest to the N and if an value is closer to zero is in between N and S, but I can’t figure out the math to calculate “exactly” where the front of vehicle are pointed.

    (if you curious about my vehicle, where is 2 videos, the first is the web interface, the second is the vehice itself:


    Thanks 😀

    • 28 April 2013 at 4:01 pm

      Sorry, I can’t help – it took me ages just to get the sensor working. Eventually, I’m hoping to build it into some kind of device but I’ve just not had the time.
      Love the vehicle, by the way – looks very cool 🙂

    • 29 April 2013 at 5:29 am

      Just found this blog post:
      Haven’t had time to read it yet, but it might help if the boards are at all similar.

      • 29 April 2013 at 11:11 am

        Thanks. I plan to use a gyro/accelerometer just to show “inclination” in the interface. Yeah, there’s a lot of cool sensors to use.
        Now i just “fight” to use the 3 axis value from magnetometer to point the direction, like this prototype of my interface:
        I let you know if I succeed

        • 29 April 2013 at 11:16 am

          I have to say – that is a brilliant interface you’ve got. Looks like a flight simulator!

          • 29 April 2013 at 11:34 am

            Yes, the idea is make a “universal” interface to ground, air an water vehicles(maybe submarines too). The “artificial horizon”(don’t know if it’s called like this in english, is the gray instrument on left side) is just a still image, but I will use a gyro/accellerometer to give live to this, it’s perfect for the job :D.

            Working NOW in this interfece, the controls(of course) and motor power, the camera and distance sensors(i’m using 2 ultrassonic transmitters/receivers HC-SR04, work exactly as a sonar)
            GPS and Gyro I didn’t buy yet, and magnetometer to use as compass, as you know, I still thinking how to use the data.

  2. 29 April 2013 at 1:20 pm

    Oh God, is in my face all the time. Embarassing… Is in your example!
    “88.26 Degrees”
    0/360 degrees is when X is facing magnect strenght field(N), 90 is when X is facing East

  3. Garrett
    30 April 2013 at 8:36 pm

    I’m trying to get this compass sensor working on my raspberry pi. I run through all your instructions but when I run the code example it says no module name quick2wire.i2c.
    I appreciate any help you can provide.

    • 2 May 2013 at 5:55 am

      Have you downloaded the quick2wire library and put it in the same folder as your code?

      • Garrett
        2 May 2013 at 8:28 am

        While in the folder with my code in it i ran this command:
        git clone
        and then ran
        sudo python install
        It still has that error and I looked through the directory and couldn’t find any file named quick2wire.i2c

        • Rich R
          3 August 2013 at 1:46 pm

          I had the same problem as Garrett, my fault, I didn’t create a myproject directory. so the path was wrong to the ic2libraries….

        • Richard Robinson
          3 August 2013 at 4:55 pm

          I had the same error as garrett, it was my mistake, I hadn’t created a myproject folder, so all my work remains in the home/pi folder, hence the path WAS wrong for the i2clibraries as given in the instructions. Changing that to suit my real path corrected the problem (so the python program now knows where to find the library)….

  4. 27 May 2013 at 9:19 am

    The post gave me some relevant information, I was searching for a magnetometer for suiting my new air ride and can use with a GPS for fixing camera on it, hope this one will work, Thanks.

  5. Don isenstadt
    17 November 2013 at 8:53 pm

    Would it be possible to use this device to detect water usage by sensing the rotation of the magnets in a water meter..

  6. 2 February 2014 at 11:06 pm


    thank for your tutorial,

    I have a problem,

    when i run this code :

    import time
    from i2clibraries import i2c_hmc5883l

    hmc5883l = i2c_hmc5883l.i2c_hmc5883l(1)


    while 1:

    i receive ramdom informations for axis and heading and the declination is always the same…

    Can you help me please

  7. Etienne
    22 January 2015 at 12:38 am


    Is it possible to use hmc5883l with python not with python3 ?

  8. Norbert Wagner
    9 November 2015 at 7:47 pm

    Is possible, with HMC5883L module, with some peripherals module or interface or driver for stepper motor, driving this motor 1:1 ? So, when i turn a module on 360 degree, turn around the stepper motor 360 degrees ?
    Thanks for your answer, and sorry for my english.

    • Michael Horne
      10 November 2015 at 7:48 am

      Yes. I would think so. You might need to do some maths to convert between the sensor scale and the 360 degree scale. Your English seems good to me!

Leave a Reply

Your email address will not be published. Required fields are marked *