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. 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 😀

  2. 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. Hi,
    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.

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

        • 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. Would it be possible to use this device to detect water usage by sensing the rotation of the magnets in a water meter..

  5. Hello,

    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

  6. 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.

    • 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 *

This site uses Akismet to reduce spam. Learn how your comment data is processed.