Is QMC5883L 3-Axis Compass Magnetometer Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
3-axis digital compass for calculating magnetic orientation bearing direction and magnetic field variations.
Wiring QMC5883L 3-Axis Compass Magnetometer to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 3V3 | The QMC5883L runs from 2.16 to 3.6V, so 3.3V suits a bare module and one with its own regulator alike. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 | |
| DRDY | unconnected | Data-ready output. The config polls the sensor. The platform's optional drdy_pin exists for reading it at its full 200Hz, which a once-a-minute log does not need. |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | I2C Bus / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Heading (Degrees) Field Strength X (µT) Field Strength Y (µT) Field Strength Z (µT) Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| Factory Reset Instruction | Press BOOT button while resetting. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_hmc5883l_ard.yaml and run esphome run emb_esp32_hmc5883l_ard.yaml. The first flash goes over USB. If it is not detected, press BOOT button while resetting to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The I2C scan at boot lists 0x0D, the three field strengths read in the tens of microtesla, and Heading moves smoothly through its whole range as you turn the board flat on a table. A scan that shows 0x1E instead is a genuine HMC5883L and wants the hmc5883l platform; 0x2C is a QMC5883P, which this platform cannot drive. A heading that only covers part of the circle, or barely moves, means something magnetic nearby is swamping Earth's field.
ESPHome Configuration
Starting configuration for QMC5883L 3-Axis Compass Magnetometer on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for QMC5883L 3-Axis Compass Magnetometer
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_hmc5883l_ard
friendly_name: "QMC5883L 3-Axis Compass Magnetometer"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
i2c:
id: i2c_main
sda: GPIO21
scl: GPIO22
scan: true
# This module is a QMC5883L, which is a different part from the HMC5883L
# despite the near-identical name and pinout. It has its own platform.
sensor:
- platform: qmc5883l
address: 0x0D
field_strength_x:
name: "Field Strength X"
field_strength_y:
name: "Field Strength Y"
field_strength_z:
name: "Field Strength Z"
heading:
name: "Heading"
update_interval: 60s
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
If the device is not found:
it is usually the I2C address, not the config. Many breakouts strap their address with
solder jumpers, so two boards of the same part can differ. This config leaves
scan: true on — the boot log lists every address
actually present on the bus, and you can copy the right one from there.
What Appears in Home Assistant
Microtesla along each axis of the chip. Earth's field is roughly 25–65µT in total, shared between the three axes according to how the board sits.
Degrees, worked out from X and Y only. It runs from −180 to +180, not 0 to 360; see the gotchas.
Optional, not in the config: add temperature: under the same platform. Only changes in it mean anything — the chip's temperature sensor is calibrated for slope, not offset.
Known Problems and Fixes
Three chips answer to GY-271
Modules sold as GY-271 or "HMC5883L" have carried Honeywell's HMC5883L at 0x1E, QST's QMC5883L at 0x0D and, on newer batches, the QMC5883P at 0x2C. All three have different register maps, so a platform written for one reads nothing useful from another. The I2C scan at boot names the address, and the address names the chip. This config is for 0x0D; the QMC5883P has no core ESPHome platform, only community external components.
Heading runs from −180 to +180
The component computes heading as atan2 of the X and Y fields, so 0° is the chip's Y axis pointing at magnetic north and half the circle reads negative. Compass cards and most automations expect 0–360. A lambda filter on Heading, return x < 0 ? x + 360 : x;, folds it round.
Calibrate out what is near it
Steel screws, a relay or speaker magnet, or a cable carrying current adds a fixed offset to X and Y, and a heading that only sweeps part of the circle as you turn the board is the symptom. Heading is computed inside the component from the uncorrected fields, so offset filters on Field Strength X and Y do not fix it. Turn the board through a full circle, note each axis's minimum and maximum, subtract the midpoints, and compute the heading in a template sensor from the corrected values.
Level, and magnetic north
Using only X and Y means the heading is right only when the chip is flat. Earth's field is steeply inclined to the horizontal at most latitudes, so a few degrees of tilt moves the heading visibly; a tilt-compensated compass needs an accelerometer too. The zero is magnetic north, which differs from true north by the local declination — look yours up and add it with an offset filter.
Leave the range alone for a compass
The default 200µT range holds Earth's field several times over, and at that range each count is a tiny fraction of a microtesla. The 800µT setting is for a sensor mounted close to a magnet strong enough to push the field past 200µT.
Once a minute is a log, not a compass
update_interval: 60s suits logging a slowly moving object. For a heading that follows something as it turns, drop it to a second or less. The chip samples at up to 200Hz by default, so it is never the thing holding the reading back.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for QMC5883L 3-Axis Compass Magnetometer? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-hmc5883l-ard)
Frequently Asked Questions
Does QMC5883L 3-Axis Compass Magnetometer work without an internet connection?
How is QMC5883L 3-Axis Compass Magnetometer powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
HMC5883L 3-Axis Magnetometer Compass
The original Honeywell part at 0x1E, on its own hmc5883l platform. Discontinued, so check the scan before believing a listing.
esphome-magnetometer-water-gas-meter ↗
A community ESPHome package that counts water or gas meter rotations with this sensor. It supports the QMC5883P as well.
AS5600 12-bit Magnetic Rotary Encoder
If the job is the angle of a shaft with a magnet on it, not a bearing, the AS5600 does that directly and ESPHome has a platform for it.
MPU9250 9-Axis MotionTracking IMU
Nine axes: a magnetometer plus the accelerometer a tilt-compensated heading needs. ESPHome reaches it through community external components.
AH3503 Analog Hall Effect Magnetic Sensor
An analog Hall sensor, for "is the magnet there" jobs like a door or a meter dial, with no I2C at all.