PiicoDev Magnetometer- Getting Started Guide

This guide will help you get started with a PiicoDev® Magnetometer -  get it working as a compass, and read the magnetic field strength of a nearby magnet.

This guide is for the current revision of the PiicoDev Magnetometer, featuring the MMC5603. All of the video content is still relevant for both revisions.

For more information on the differences, select the "Check Revision" tab

To get started - select your dev. board below.

We're ready to go with our first example on the Magnetometer! The following example compass.py, first requests to calibrate the magnetometer:

# Calibrate the sensor by turning it in a circle
# Display the heading with compensation for magnetic declination

from PiicoDev_MMC5603 import PiicoDev_MMC5603
from PiicoDev_Unified import sleep_ms          # Cross-platform compatible sleep function

compass = PiicoDev_MMC5603() # Initialise the sensor

# Calibration recommended for best results.
compass.calibrate() # only need to calibrate once

# Optional: Declination is the difference between magnetic-north and true-north ("heading") and depends on location
# compass.setDeclination(12.3) # Found with: https://www.magnetic-declination.com/Australia/Newcastle/122944.html

while True:
    heading = compass.readHeading()   # get the heading from the sensor
    if compass.dataValid():           # Rejects invalid data
        heading = round(heading)      # round to the nearest degree
        print( str(heading) + "°")    # print the data with a degree symbol
    sleep_ms(100)

Slowly rotate the sensor on a flat surface until calibration is complete. You can see the calibration progress shown by a progress bar in the shell.

Follow along with the video for this part - getting a high-quality calibration is important for reading an accurate heading.

Once calibration is complete, your console will begin printing the measured heading into the shell. This is the same heading that you would read off a magnetic compass. The heading is the direction the top edge (with the PiicoDev label) of the module is pointing when placed on a level surface like a table.

If you have a magnetic compass you can compare headings. In the video I scribe a line pointing north - as read from my magnetic compass. I then compare the data gathered by the magnetometer and the results are really close!

You may notice a new file named calibration.cal has appeared on your micro:bit - this is the calibration data. This calibration data will be automatically loaded every time the script runs, so you can comment-out compass.calibrate() if you don't want to calibrate on every power-up. It's still a good idea to calibrate periodically, or if you notice your heading has drifted.

Remix - True North

So far we have been working with Magnetic North - this is the direction a magnetic compass will point. To find a true heading, we need to input some more information. Magnetic Declination is the difference between Magnetic North and True North (or "Geographic North"). The value for declination changes depending on location. In Newcastle, Australia, the declination is about 12° (as of 2022). There are lots of online tools that will help you find the declination in your area (here's one example). Once you know the declination in your area, you can input that angle into the setDeclination() function. Re-run your script and you should notice the heading data has been offset slightly. Your magnetometer is now indicating its measurement for True North.

In this example, we'll measure magnetic-field-strength. This is useful to detect the presence of a nearby magnet. Replace the code in main.py with the following code.

# Read the magnetic field strength and determine if a magnet is nearby

from PiicoDev_MMC5603import PiicoDev_MMC5603
from PiicoDev_Unified import sleep_ms

magSensor = PiicoDev_MMC5603() # initialise the magnetometer
# magSensor.calibrate()

threshold = 120 # microTesla or 'uT'.

while True:

    strength = magSensor.readMagnitude()   # Reads the magnetic-field strength in microTesla (uT)
    myString = str(strength) + ' uT'       # create a string with the field-strength and the unit
    print(myString)                        # Print the field strength
    
    if strength > threshold:               # Check if the magnetic field is strong
        print('Strong Magnet!')

    sleep_ms(1000)

When we run the script, we see the measured field strength being printed to the shell. If the measured strength goes above a set threshold, the program prints a message to the shell. This time around, the magnetometer is initialised with the maximum range (3000 uT), since there could be a strong magnet nearby. When we exceed the range of the magnetometer, the measurement becomes invalid and so the measurement data is returned as a special "Not a Number" type.

A note about calibration: In Example 1 we performed a 2-axis calibration (rotating the magnetometer on a flat surface. For best results in this example a 3-axis calibration is necessary. To calibrate 3-axes, call the calibrate() function, and rotate the device slowly in all axes.

Above: Bring a magnet nearby the Magnetometer and observe how small movements can be easily observed by the magnetic field strength. The above figure is using modified code that removes other print() statements. Refer to tutorial video to reproduce this example.

The read() method allows you to extract the 3-axis magnetometer data (in uT, or just the raw register data) - for when you wish to process the data with your own algorithm.

# Read the magnetic field strength and determine if a magnet is nearby

from PiicoDev_MMC5603import PiicoDev_MMC5603
from PiicoDev_Unified import sleep_ms

magSensor = PiicoDev_MMC5603() # initialise the magnetometer
# magSensor.calibrate()

while True:
    raw_data = magSensor.read() # Read the field strength on each axis in uT
    # raw_data = magSensor.read(raw=True) # Read the raw, unscaled data on each axis
    print(raw_data)             # Print the data
    sleep_ms(200)

So far we've been using the shell to visualise information collected from the magnetometer. Now for a fun mini-project. We can use a PiicoDev OLED Module to display a digital compass-needle that always points north. The following code is really similar to Example 1, except there's extra code to drive the display, and handle drawing an indicator on the display.

To follow along with this project, you'll need to save PiicoDev_SSD1306.py onto your Pico.

# Read the magnetic field strength and determine if a magnet is nearby

from PiicoDev_MMC5603import PiicoDev_MMC5603
from PiicoDev_Unified import sleep_ms

magSensor = PiicoDev_MMC5603() # initialise the magnetometer
# magSensor.calibrate()

while True:
    raw_data = magSensor.read() # Read the field strength on each axis in uT
    # raw_data = magSensor.read(raw=True) # Read the raw, unscaled data on each axis
    print(raw_data)             # Print the data
    sleep_ms(200)

The drawCompass() method converts the heading into x,y coordinates that draw a line to the centre of the display. A circle is drawn on the end of the line and the heading in degrees is shown in the bottom corner of the display.

Above: a compass needle is animated on the OLED to point North, even if the whole assembly is rotated.

We can measure the properties of magnetic fields using a 3-axis magnetometer. Build-in functions allow us to easily measure the sensor's heading in a magnetic field, and we've even built a cool graphical compass project using an extra display module.

If you make something cool with this starter project we'd love for you to share it on our forums! And if you'd like some help with this guide, start the conversation below - We're full-time makers and here to help!

• Magnetometer library: PiicoDev® Magnetometer QMC6310 MicroPython Module
• Hardware Repository for the PiicoDev Magnetometer
• OLED Library: PiicoDev Unified MicroPython module for SSD1306