A direction-sensitive prop or handheld device can look promising on the bench: turn the sensor and its numbers change. Then you add the speaker, battery, fasteners and case, and the direction display starts behaving differently.
Before replacing the sensor, check what changed around it. A magnetometer measures the local magnetic field, including contributions from the product itself. A useful compass heading takes more than three values over I2C.
On our bench we connected a GraftSense QMC5883P magnetometer module to a GraftPort-RP2040 board and recorded three-axis output. This note covers that bring-up and the further work a direction display needs inside a finished assembly. We did not demonstrate a calibrated compass or a navigation product.
Establish what is actually connected
The module connects over a four-wire cable. Its schematic shows 5 V entering a regulator that supplies the sensor at 3.3 V, with SDA and SCL pulled up to 3.3 V. Do not confuse that board-level input with the bare sensor's supply. We connected SDA to GPIO 4 and SCL to GPIO 5, scanned the bus before creating the sensor object, and found the device at 0x2C.
from machine import I2C, Pin
i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)
print([hex(a) for a in i2c.scan()])
The part suffix matters. The driver package we downloaded was named for the QMC5883L, but the file inside was a QMC5883P driver, and its README listed an address belonging to a different part. Our code, terminal output and the QMC5883P datasheet agreed on 0x2C. Changing only the address in a driver written for another chip is not a reliable substitute.
This trips up builders regularly. In an October 2026 r/arduino post, someone reported fixed 0° or 255° readings while trying different identifiers for a GY-271 board. The replies raised identification, communication and calibration questions. Identify the hardware before you start magnetic testing.
The driver in our package is derived from robert-hh's QMC5883 driver, which has separate files for the L and P variants. Our packaged copy used const without importing it, so we added from micropython import const to a working copy before uploading. Its read function returns X, Y and Z in gauss plus a fourth value that is a fixed zero placeholder, not a temperature; the P part has no temperature sensor. Its sampling-rate setter also needs correcting before use, though the basic loop never calls it.
Our reading loop printed scaled X, Y and Z every 300 ms. The terminal confirmed communication and changing magnetic-axis values. It did not show north, a heading error or a completed calibration. Save a baseline log like this before adding the rest of the enclosure; it gives you something to compare when the assembly changes.
Three magnetic values are not yet a compass
The chip senses the field along three axes fixed to its package. How the board is mounted decides how those axes relate to the front, side and top of your product. Record which way the board faces inside the case.
A heading calculation needs a consistent coordinate convention and calibrated readings. If a handheld device can tilt, treating X and Y as though it were always level adds another error. Tilt compensation usually combines an accelerometer with the magnetometer; NXP application note AN4248 explains how.
The chip's internal signal conditioning is useful, but it cannot know where you put a speaker magnet or which way the board faces. Those are properties of your assembly.
The manufacturer quotes 1 to 2 degrees of heading capability for the part. We ran no controlled heading test, so treat that as a component statement, not a promise about this module or your product. Decide how much directional error your interaction can tolerate, then measure it. A prop that picks one of several broad directions has a different requirement from a device guiding someone to a bearing. A sensor bring-up like ours is not validation for navigation or safety-critical use.
Calibrate with the final parts in place
A magnetometer near a permanent magnet sees an added field, and nearby ferromagnetic material distorts the field being measured. These are usually called hard-iron offset and soft-iron distortion. Calibration estimates corrections for the magnetic environment that moves with the sensor.
That is an integration problem, not a menu option. In a Pololu forum thread from May 2020, a builder found a compass behaved differently when brought near an RC car, and the replies recommended calibrating it in place.
NXP's calibration note AN4246 explains the model: collect readings across many orientations and estimate the offset and distortion. Do this after the sensor, battery, speaker and fasteners are fixed in their intended positions, and redo it if any of those positions or materials change.
A speaker may need to be much farther from the sensor than a compact case allows. If the placement produces a large or unstable disturbance, change the layout before expecting software to compensate.
Calibration is also not a cure for every environment. Setting the finished device next to a steel table, a magnetic clasp or a motor can add a field that was absent during calibration. A good product recognizes when its direction estimate is unreliable instead of showing a confident arrow in every condition.
Test the states the user will switch between
A powered device can change its own magnetic environment without moving. Current in nearby wiring and coils produces a field. NXP's layout guidance AN4247 discusses current-carrying traces and magnetic materials in the housing, and warns that different mechanical configurations can change the interference.
Hold the prototype at a fixed orientation and change one condition at a time. These are the checks we would run next; they are not results from our bench session.
| Change one condition | Record | What it reveals |
|---|---|---|
| Add the case and fasteners | Raw X/Y/Z before and after | A shift introduced by the assembly |
| Switch a speaker or motor on | Readings, operating state, timestamps | Disturbance that changes with operation |
| Move a lid, clasp or accessory | Its position beside the readings | A magnetic configuration that is not fixed |
| Tilt while keeping the intended bearing | Tilt and displayed direction | Whether the heading method handles normal use |
| Return to marked orientations repeatedly | Reference direction and reported heading | Repeatability after calibration |
Keep the reference direction independent of the device under test. A phone compass sitting beside the same magnetic disturbance is not automatically trustworthy. If at first you only need to compare operating states, keep the orientation fixed and examine changes in the raw values before claiming any angular accuracy.
Do not hide those changes by averaging until you understand the cause. A steady but wrong heading can be less useful than an obviously unstable one. Verify the actual sensor configuration in firmware and keep raw data for diagnosis.
What to bring to the next engineering step
For a direction-sensitive prototype, the useful handoff is more than the magnetometer part number. Include a photo of its mounting position, the intended forward direction, nearby magnetic or steel parts, the exact driver, the calibration procedure, and logs from the operating states that change the reading.
That evidence shows whether to move the sensor, change a mechanical detail, correct the software, or rethink how the interaction uses direction. It also keeps a successful bare-board demonstration from turning into an unsupported promise about the assembled product.