[Compass] Magnetometer Library (HMC5883)

This post includes a HMC5883 Magnetometer Library for Arduino. It contains a library that makes interfacing with a compass module (for arduino) in C++ very easy. There are other libraries for the HMC5843, but they are not compatible with the HMC5843. Other libraries i found for the HMC5883 of sample codes were either inefficient or plain incorrect. You can download the library if you scroll to the bottom.

There is a breakout for this module that Seeedstudios sell for about $25, which is a great deal and includes handling of some stuff we can now ignore; like the correct voltage (it accepts like 3~6V). Anyway. You can buy it here for just $25.

This is actually a 3 axis magnetometer for arduino, and does not contain tilt compensation. For big tilts you would need tilt compensation, but it is not strictly necessary.

How does a 3 axis magnetometer work?

It reads magnitudes in X Y and Z direction. Then using sine and cosine functions you can calculate the angle between them; thus obtaining the angle between the earths magnetic force and your little module.


This library is also not very efficient or versatile, but since it’s so simple, everyone understands it. It is as easy as:

  1. #include <wire.h>
  2. #include <hmc.h>
  3. int a;
  5. void setup()
  6. {
  7.   Serial.begin(9600);
  8. }
  10. void loop()
  11. {
  12.   int x,y,z;
  13.   delay(100); // There will be new values every 100ms
  14.   HMC.getValues(&x,&y,&z);
  15.   Serial.print("x:");
  16.   Serial.print(x);
  17.   Serial.print(" y:");
  18.   Serial.print(y);
  19.   Serial.print(" z:");
  20.   Serial.println(z);
  22.   HMC.getAngle(&a);
  23.   Serial.println(a);
  24. }

The code is based on the Seeeduino module, which provides more info about that here.

Download magnetometer code library

Download: HMC_library.zip

Tim Zaman

MSc Biorobotics. Specialization in computer vision and deep learning. Works at NVIDIA.

You may also like...

24 Responses

  1. whynkay says:

    Hi Tim!
    I’ve added the library and when tried to verify the example code HMC_test it shows following compile error:

    In file included from HMC_test.pde:2:0:
    C:\Program Files (x86)\Arduino\libraries\HMC/HMC.h:29:22: fatal error: WProgram.h: No such file or directory
    #include “WProgram.h”

    compilation terminated.
    Error compiling.

    Since I’m a beginner to Arduino, I’m expecting a simple answer from you!
    Thanks in advance

  2. vahid azizi says:

    i want PCB of HMC5883 for setup,pleas help me,if you have PCB of HMC5883 pleas send in my mail.

  3. Sergio Acosta says:

    hello, where can i find the code that you are using with this magnetometer for getting the X Y Z values?

    I’d really appreciate your sharing.

    by the way this is my email.


    • Tim says:

      at the bottom it says “Download magnetometer code library” and then you click download. And then you will download the library, which you should put in your arduino library folder and then it’s as simple as described above! More about Arduino libraries here; http://arduino.cc/it/Reference/Libraries

  4. Fbo says:

    here is some samples values after Compass calculating :
    But how can i have a compass fixed value when i don’t move the sensor ?

    • Tim says:

      Try a moving average: just add up the last three measurements and devide them by 3, that’ll give you a pretty static average.

  5. Fbo says:

    Yes Tim i also think it isn’t a great module. it’s cheaper but if you cannot trust him. so don’t buy it !
    i must, another time, tell a great thanks to Tim for his help.

  6. Fbo says:

    Thank you Tim for the time you take,
    i use your sample code so the only delay is on the loop for 100 ms.

    This is my first set (rotating on a servo turning clockwise slowly) :

    and an another set (without any movements)

    can you see something wrong ?

    • Tim says:

      Ok lesson 1 for you: a servo contains magnets and a lot of metal: hint: STAY AWAY! compasses suck when near anything metal really, a pen or screwdriver is already too much usually.
      I have reviewed your data it seems pretty good actually, but your center point lies just a bit off at X=80, Y=100. So what you should do is add the following lines after you get the X and Y coordinates:
      And you’re done. The module maybe doesnt perform very well, but then again, it isnt a great module.

      • Fbo says:

        Thank you so much, but sorry i don’t understand why you fixed the 2 values (80 for X and 100 for Y)

      • Fbo says:

        Yess, i understand it in seeing your graph, it’s because the graph slide left or right for the X axis and top or bottom for Y axis is it right ?

      • Fbo says:

        here is my new value after recalibrating :

      • Tim says:

        That’s perfect! Good circle with 0,0 in the center! Now use this to get the angle and youre all done.

        var_compass=atan2((double)y,(double)x) * (180 / PI) -90; // angle in degrees
        if (var_compass>0){var_compass=var_compass-360;}

  7. Fbo says:

    Hello Tim, thank you for your working, i use the TWIG and your library but i have something i can’t explain ! the values of x, y & z always varies (it’s not stable) even i don’t touch the sensor. Do you have an issue ?
    x:21 y:-21 z:-235
    x:12 y:-14 z:-230

    • Tim says:

      Actually that does not look that bad. But i think you really have to calibrate your unit a little. Check out the calibration for magnetometer post i have on this website.

      • Fbo says:

        Ok if i understand correctly your post, i must calibrate my sketch but i not sure how i must do it. i do appreciate if you can give me a sample sketch. i dont understand how your code will correct the fact that the values varies ??

      • Tim says:

        check out this post: http://www.timzaman.nl/?p=994&lang=en
        the idea is that your X+Y+Z=constant. Probably with you this is not a constant. If will represent a circle in the ideal case with 0 as its center point. Make sure 0 is the center point of a circle. Just take up some measurements of X Y and Z and draw them in a graph. make sure 0,0,0 is the center. if not: calibrate by adding or subtracting a appropraite value from X or Y or Z. easy.

      • Fbo says:

        Thank you Tim for your response, i’ll try to do it.

      • Fbo says:

        Hello Tim, I began to take some set of measurements but i have found that i can’t do more than 18 mesures by minutes ??? why it does not do faster ? ( have only this Twig connected to my seeeduino Mega).

      • Tim says:

        Hmm, well for calibrating and taking a lot of measurements (in several orientations!!) it doesnt really matter how fast it is. if you want it to go faster, you should dive in the code and rip out a delay if its in there. otherwise, doesnt really matter?

  8. Tim says:

    Yes i have a solution: don’t use Fabio’s library as it is great fot the HMC5843; but use this one for the HMC5883: it’s not as extensive as that of Fabio’, but it is easier and fine on the other hand :). Which one are you using?

    • Clemens Seidenberg says:

      I’ve tried yours and the one published by seeeduino.garden. But always the same
      issue. I know that the sequence of the registers is different compared to the 5843. Following the datasheet -4096 indicates an ADC over- or underflow. Maybe my hardware is buggy.

      • Tim says:

        I had the same problem when there was some ferrous material (screwdriver) near. Try doing it away from all objects (do mind your speakers f.e.). Otherwise just return it…

  9. Clemens Seidenberg says:

    Hello Tim,

    I have an issue with the z-channel. It always shows the value -4096.
    I saw your post to fabio (free imu) reporting an similar problem (?).

    Do you have any explanation / solution for that problem.