adding compass example

[FoamyGuy]

This adds the compass example referenced by issue #2. The sensor I have is actually a LIS3MDL, so I was unable to test this example specifically with the LIS2MDL. Both sensors (and some others) use the same .magnetic property to access the data so the example can be used by any of those sensors by using the appropriate import and sensor initialization. I believe this one should be working for the LIS2MDL.

[jepler]

Good job using atan2() to get a heading over 360 degrees! I checked and assuming +X means east and +Y means north, the outputs would seem to match expectations. I don't have hardware to test with, though, so too cowardly to merge.

[ladyada]

@siddacious ok wanna test?

[siddacious]

@FoamyGuy the numbers I got seem off, but for all I know I forgot about a huge magnet somewhere;

these four chunks are rotated 90 degrees clockwise from each preceding set:

tested with a LSM303AGR which includes a lis2mdl

Xmag: -4.95 Ymag:  -6.3
heading: 231.84 degrees
Xmag: -5.55 Ymag:  -5.4
heading: 224.22 degrees
Xmag: -5.4 Ymag:  -5.7
heading: 226.55 degrees

Xmag: 17.4 Ymag:  -31.35
heading: 299.03 degrees
Xmag: 17.1 Ymag:  -31.8
heading: 298.27 degrees
Xmag: 17.25 Ymag:  -31.65
heading: 298.59 degrees

Xmag: -9.45 Ymag:  -56.85
heading: 260.56 degrees
Xmag: -8.4 Ymag:  -57.75
heading: 261.72 degrees
Xmag: -9.15 Ymag:  -57.15
heading: 260.90 degrees

Xmag: -37.05 Ymag:  -28.35
heading: 217.42 degrees
Xmag: -36.9 Ymag:  -27.75
heading: 216.94 degrees
Xmag: -37.65 Ymag:  -28.2
heading: 216.83 degrees

[FoamyGuy]

@siddacious If you have a moment, and any of these other magnetometers I'd be interested to know if you get similar results from these ones in the same environment:

• LSM303DLH: https://github.com/adafruit/Adafruit_CircuitPython_LSM303DLH_Mag/blob/master/examples/lsm303dlh_mag_compass.py
• LIS3MDL: https://github.com/adafruit/Adafruit_CircuitPython_LIS3MDL/blob/master/examples/lis3mdl_compass.py

These are using the same formula, if it turns out that there is an issue with it then likely affecting these other examples as well. These ones I was able to test and I was getting results that were close to the readings from a compass app on an Android phone.

I started these examples using the code from the old PR that is referenced in issue #2. During the process I did come across this Making Tracks Project within the LSM303 learn guide.

This has arduino code instead of CircuitPython, but it does seem to be implementing the same formula as far as I understand it:

// Calculate the angle of the vector y,x
float heading = (atan2(event.magnetic.y,event.magnetic.x) * 180) / Pi;
// Normalize to 0-360
if (heading < 0)
{
    heading = 360 + heading;
}

[ladyada]

this example wont work in real world because the magnetometer must be calibrated. here are the calibration and normalized output sketches :)

calib_mag.txt
compass_calib.txt

[kattni]

@FoamyGuy Limor posted calibration programs - consider implementing them for your example.

[FoamyGuy]

@kattni I've made some new commits add the calibration script and use it in the compass example. I will work on updating the LSM303DLH, and LIS3MDL examples to match this as well.

[kattni]

@siddacious When you get a chance, can you take another look please? Thanks!

[siddacious]

@FoamyGuy Works great! My only request is that you include some basic instructions in the compass example about how to use the calibration example to measure and use the hardiron offsets.

[FoamyGuy]

I've added a new commit with instructions on how to run the calibrate script and copy in the values to the compass script. Thank you.