Build your own Raspberry Pi Compass (HMC5883L)

In addition to being used as a GPS tracking system, the HMC5883L module can also be used to build a Raspberry Pi compass. This indicates the angle at which it is currently located. The HMC5883L compass module can be addressed via I2C, like many other sensors. Complete position and position systems can be built together with the rotation sensor.

In this tutorial, we want to configure our own electronic Raspberry Pi compass so that it always shows the deviation (in degrees) to the north.


Compass Components

Raspberry Pi Compass Module HMC5883L

Raspberry Pi Compass Module HMC5883L

In this tutorial I used the following components:

For visualization, e.g. a servo motor can be used, which points in the corresponding direction and thus readjusts the compass needle. I’ve built something similar with an Xbox 360 controller before, which could serve as inspiration.


Raspberry Pi Compass Connector

The HMC5883L module usually has five connections, of which we only need four. The “DRDY” or “RDY” termination remains free.

The remaining four pins of the sensor are connected to the Pi as follows: VCC -> 3.3V (Pin 1), GND -> GND (Pin 6), SCL -> GPIO3 (Pin 5), SDA -> GPIO2 (Pin 3) . Some sensors have six pins. If you have one (with 3vo and VIN), both are connected to the 3.3V pin of the Pi.

You can find an overview of the pin assignment on the Raspberry Pi here. The connection to the Raspberry Pi looks like this:

Raspberry Pi HMC5883L Breadboard

Pay attention to the labelling of the sensor pins!

Note: Since this question came up several times, I would like to point out that you can also operate several I²C devices on the Raspberry Pi at the same time. To do this, the connections (SDA, SCL) are connected in parallel. The module is recognized via the fixed hardware address (more on this below). Only two devices with the same I2C address cannot be operated. With many sensors, however, the address can be changed using jumper cables on the circuit board. If something like this is required, I recommend taking a look at the datasheet.


Raspberry Pi Compass – Preparation

Before we can use the compass, some software packages are required. Among other things, the git client, the I2C tools and Python3 must be installed. To do this, we open the SSH terminal and enter the following:

sudo apt-get install git i2c-tools python-smbus python3 python-pip python-virtualenv python3-setuptools

After the successful installation, I2C still has to be activated, if not already done. To do this, enter in the command line:

sudo raspi-config

Activate it under “Advanced Options”> “I2C”.

If the compass module is already connected, we can already see whether it is recognized. To do this, enter sudo i2cdetect -y 1. The output should look like this:

pi@raspberrypi:~ $ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- 1e --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

If nothing was detected, you should check the connection of the sensor.


Normally root rights must be available to read out the I²C bus. However, since the library that will be used later does not have this, we have to activate it first. For this we create a file

sudo nano /etc/udev/rules.d/99-i2c.rules

with the following content:

SUBSYSTEM=="i2c-dev", MODE="0666"

With CTRL + O we save this and with CTRL + X we exit the editor and return to the terminal.


Set up the Raspberry Pi Compass Library (HMC5883L)

To be able to use the compass module, we need two Python 3 libraries, which we will now install:

git clone
cd quick2wire-python-api

Here are some files that we need to add to the Python path variables. If you have renamed the folder or in a different directory, you can use pwd to show which folder you are in. To update the Python path, let’s edit the Profiles file:

sudo nano /etc/profile

At the top add these two lines (adjust path if necessary):

export QUICK2WIRE_API_HOME=/home/pi/quick2wire-python-api

After saving the file, we restart the Pi.

sudo reboot


After we have reconnected via SSH, we quickly check whether the path has now been set:


This should now contain our specified path. In addition, an I2C device should be recognized (compass module must be connected):

ls /dev/i2c-*

You have to remember the displayed number because it will be needed soon (for me it is 1).

Back in the library directory, we can now start the installation:

cd quick2wire-python-api
sudo python3 install

Now we can finally install the actual library, which can read the HMC5883L compass.

git clone

There are also other I2C libraries such as available for the ITG-3205, ADXL345 and LCD displays.

If you want, you can also add the path of the libraries to the Python path variable (analogous to the one shown above).



Testing the Raspberry Pi Compass

Now it’s time to test the electric compass. To do this, we call the Python3 console:

sudo python3

The following are some sample codes that describe the functions. If your I2C device does not have the number 1 (like mine), you have to adjust this in line 3.

You should set the declination for the highest possible accuracy (line 6). For me this is 2 ° and 15 ‘(arc minutes). The “Magnetic Declination” is different in each place and can e.g. can be found out via this page.

In the example, we are interested in the last value, which can also be read out via hmc5883l.getHeadingString(). A value of 0 means that the sensor is pointing straight north.


Reading Out Axes

In addition to the angle, it is also possible to read out the rotation of the axes:


Unfortunately, the website with the complete documentation is now offline, but fortunately, it can still be accessed via the Wayback Machine.

2 Responses

  1. On my Raspberry Pi 4, I enabled I2C using “3 Interface Options” of the ‘sudo raspi-config’ utility (not the ‘Advanced Options’)

    Thank you for a VERY helpful tutorial. I bought a compass board that was very inexpensive, but it came with absolutely no documentation, and I had never used an I2C peripheral before. Your explanation made my purchase useful


Leave a Comment

Your email address will not be published.

Subscribe to Raspberry Pi Tutorials and don't miss any new Tutorial!