I2C Python Library - 3-Axis Digital Compass (HMC5883L) with the Raspberry Pi

The HMC5883L is a 3 axis digital compass which can communicate via I2C to the Raspberry Pi using only 2 data lines.This library simplifies the use of this device significantly and can provide a heading with only a couple lines of python code.

Some features of this library:

  • Easily set declination to get heading based on true north
  • Heading can be retrieved in degrees and minutes or as a standard formated string for printing
  • Instance can be treated as string to quickly test initial setup
  • Axes can be read directly for other uses such as sensing magnets


Basic Example

Heading Example

Axes Example

Determine Declination

True north is varies from magnetic north in most areas of the world. This variation is declination and is expressed in degrees and minutes. Declination changes slightly over time so you will have to provide your coordinates and date. In order for this library to provide true north heading you must determine your declination which can be found here.

Installing the I2C Libraries

Instructions for installing the Think Bowl I2C Libraries are here.


__init__(port, addr=0x1e, gauss=1.3)

Constructor to create instance requires the port (0 for old raspberry pi, 1 for new). If the rest are not provided, defaults are used.


Prints the axes, declination and heading to screen for quick troubleshooting


Axes are constantly updated


Set scale for axes. Gauss must be 0.88, 1.3, 1.9, 2.5, 4.0, 4.7, 5.6, or 8.1

setDeclination(degrees, minutes=0)

Sets declination to allow heading compensation to true north. Minutes are optional. See declination section above for more information.

setOption(register, options)

Sets options in hex in provided register


Returns tuple with declination in degrees and minutes.


Returns string with declination in standard format


Returns tuple with heading in degrees and minutes.


Returns string with heading in standard format


Returns tuple with scaled axes for x, y and z

Posted in Peripherals, Programming, Raspberry Pi
4 comments on “I2C Python Library - 3-Axis Digital Compass (HMC5883L) with the Raspberry Pi
  1. Etienne says:


    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

    • ebartel says:

      The declination should not change unless you change it with the setDeclination method. This should be set once based on your location. Depending on what part of the earth you live on, this could also require updating every year based on the values from the link above. Your code looks ok. The axis should change as you move it. They will also drift a little bit while sitting still depending on how much magnetic interference is around. Could you post a couple lines of your output and I might be able to assist more?

      • Etienne says:

        Thanks for your answer i have solved the problem,
        it was a bad wire connexion on my breadboard,
        i have changed the emplacement and it's was good

  2. Etienne says:


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

Have a Question? I read and respond.

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


* Copy This Password *

* Type Or Paste Password Here *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">