Is HMC5883L 3-Axis Magnetometer Compass Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
3-axis digital compass IC measuring Earth magnetic field for indoor robot navigation and orientation tracking.
Wiring HMC5883L 3-Axis Magnetometer Compass to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 3V3 | The HMC5883L runs from 2.16 to 3.6V; 3.3V is right for it whether or not the module has a regulator. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 | |
| DRDY | unconnected | Data-ready output, only needed to hit the chip's 160Hz maximum rate. The hmc5883l platform polls and has no option for it. |
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 | Magnetic Heading (Deg) Field Vector X/Y/Z 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 | Hold BOOT button for 3s. |
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_ha.yaml and run esphome run emb_esp32_hmc5883l_ha.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s 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 0x1E, the field strengths sit in the tens of microtesla, and Heading moves through its whole range as the board turns flat on a table. If the scan shows 0x0D or 0x2C instead, the module carries a QMC5883L or QMC5883P and this platform fails to set up. If something does answer at 0x1E but the log says the ID registers do not match, it is not an HMC5883L. A heading that covers only part of the circle is magnetic interference close to the sensor.
ESPHome Configuration
Starting configuration for HMC5883L 3-Axis Magnetometer Compass on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for HMC5883L 3-Axis Magnetometer Compass
# 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_ha
friendly_name: "HMC5883L 3-Axis Magnetometer Compass"
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
sensor:
- platform: hmc5883l
address: 0x1E
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. Earth's field is roughly 25–65µT in total, shared between the axes according to how the board sits.
Degrees, from X and Y only, running from −180 to +180. See the gotchas for folding it to 0–360.
Known Problems and Fixes
It is probably not an HMC5883L
Honeywell discontinued the HMC5883L in 2016, and most modules sold under the name since carry QST's QMC5883L at 0x0D or the newer QMC5883P at 0x2C. This config only talks to 0x1E. The boot scan is the definitive test; the chip marking, L883 on the Honeywell part and DA 5883 on the QMC5883L, backs it up.
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. A lambda filter on Heading, return x < 0 ? x + 360 : x;, gives the 0–360 a compass card expects.
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 is the symptom. The Heading entity is computed from the uncorrected fields, so offset filters on X and Y do not fix it. Record each axis's minimum and maximum over a full turn, subtract the midpoints, and compute heading in a template sensor from the corrected values.
Level, and magnetic north
With only X and Y in the sum, the heading is right only when the chip is flat; Earth's field is steeply inclined to the horizontal at most latitudes, so a small tilt shifts it. A tilt-compensated heading needs an accelerometer too. The zero is magnetic north: add your local declination with an offset filter for true north.
Range and oversampling
The default range, 130µT (±1.3 gauss), already covers Earth's field, and each count is under a tenth of a microtesla there. The wider ranges up to 810µT are for a magnet close by, and each step up coarsens the resolution. oversampling: 8x averages eight samples into every reading and is the first thing to try when the heading jitters.
Once a minute is a log, not a compass
The config reads every 60s. For a heading that follows something as it moves, set update_interval to a second or less.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for HMC5883L 3-Axis Magnetometer Compass? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-hmc5883l-ha)
Frequently Asked Questions
Does HMC5883L 3-Axis Magnetometer Compass work without an internet connection?
How is HMC5883L 3-Axis Magnetometer Compass powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
QMC5883L 3-Axis Compass Magnetometer
The QMC5883L — what most "HMC5883L" modules actually carry — on its own qmc5883l platform at 0x0D.
esphome-magnetometer-water-gas-meter ↗
A community ESPHome package that reads water and gas meters with an HMC5883L, QMC5883L or QMC5883P taped to the meter.
AS5600 12-bit Magnetic Rotary Encoder
For the absolute angle of a shaft with a magnet on it, a dedicated 12-bit encoder with its own ESPHome platform.
MPU9250 9-Axis MotionTracking IMU
A magnetometer with the accelerometer and gyro a tilt-compensated heading needs, via community external components.