I had never worked with a Magnetometer (Specifically the HMC5883L) and really did not know what to expect. They are fairly inexpensive to purchase. My first question was how to mount it. This may seem obvious but do you mount it flush or on its side? It turns out that the x-y plane provides the equivalent of a compass reading. If you look closely at your printed circuit board, there should be silk screened image of its three axis.
Your board may vary in size, color or number of pins but there should be an axis diagram. This one indicates that if you mount it flush with a horizontal surface and point the x-axis to the front, the angle between the vector formed by [x,y] and the centerline of your robot is the angle of your heading. I discovered this by reading the x and y values from the board as I rotated my robot base clockwise by hand. I graphed these points and repeated the process twice (the red and blue paths).
The pink arrow represents the X axis and the direction of magnetic north which I found using a compass normal. As you can see, the points form an ellipse. I am no expert on this but I assume that the [x,y,z] vector represents the direction and the magnitude of the magnetic field at the point on Earth you are at. By looking at only the projection onto the x,y plane and then finding the center of the ellipsoid, you could calculate the angle between the x axis and the current [x,y] vector that points to magnetic north. Keep in mind all I know is what I have learned by experimenting with this board. If someone has any additional insight as to how this works, please pass it on. I am also ignoring any effects of tilting or z-axis data at this point. All I really wanted was my current angle from magnetic north but I was not getting this from the sample libraries a tried. I used the code at Adafruit to generate the x,y coordinates to create the graph above. You can see how its wired into my Arduino by looking at the diagram in my previous blog entry.
To calculate then center of this ellipse, I just placed a rectangle around it and then found the center of it as can be seen in the figure below. I calculated the center of the ellipse to be at (45,-360)
I don't know if this point will work for you or if this center will shift when I take the robot to new locations but for now I am using this as my center and I am getting fairly accurate readings on my heading relative to magnetic north.
Here, I calculate the angle between the current vector and the x axis which is the midline of my drive platform and then add or subtract from that angle to place it in the correct quadrant so so that I get the equivalent of a magnetic compass reading in degrees. My approach may be flawed as I mentioned above but I will update this post as I learn more about this device. The entire sketch that the gist above is taken from can be seen here. This sketch reads all the other devices listed in my previous blog entry and emits events over the USB bus to the Raspberry PI in JSON format indicating what the current heading is. I will talk about these events and the PI can send back to the Arduino in my next entry.