GY-273 Compass / Magnetometer (QMC5883L)

The GY-273 is a 3-axis magnetic compass sensor based on the QMC5883L (a clone of the Honeywell HMC5883L).

Sensors4 blocksMicroPythonC++
GY-273 3-Axis Compass (HMC5883L)

At a glance

Pins and properties exactly as the circuit editor and simulator define this part. The text below explains how to use them.

Pinout

Pinout of the GY-273 3-Axis Compass (HMC5883L), drawn as in the circuit editor. Select a label to see that pin in the table below.

Pins

Pins of this part
PinLabelType
VCCVCCPower in
GNDGNDGround
SCLSCLSignal in
SDASDABidirectional
DRDYDRDYSignal out

Properties

What you can change in the Property Inspector.

Properties of this part
PropertyRange or choicesDefault
Magnetic Heading (ψ / Yaw)0 to 359 °45 °
Pitch Angle (θ)-90 to 90 °0 °
Roll Angle (ϕ)-180 to 180 °0 °
Mag X (Bx)28.3 µT
Mag Y (By)28.3 µT
Mag Z (Bz)-30 µT
Magnetic Declination-30 to 30 °0 °
I2C Address0x0D (QMC5883L), 0x1E (HMC5883L)0x0D (QMC5883L)

The GY-273 is a 3-axis magnetic compass sensor based on the QMC5883L (a clone of the Honeywell HMC5883L). It measures magnetic field vector components along the X, Y, and Z axes and communicates via the I2C protocol. In Open Maker Studio, it is used for navigation, heading alignment, and magnetometer readings.


1. Hardware Specifications

  • Operating Voltage: 3.0V to 5.0V.
  • I2C Device Address: 0x0D (Default QMC5883L address).
  • Measurement Resolution: 16-bit ADC outputs (ranges -32768 to 32767).
  • Magnetic Range: ±2 Gauss or ±8 Gauss.
  • Pin Configuration:
    • VCC: Power.
    • GND: Ground.
    • SCL: I2C Clock.
    • SDA: I2C Data.
    • DRDY: Data Ready digital output (optional, pulls low when conversion is complete).

[!WARNING] Chip Identification Required: GY-273 modules are sold with two different chips that are NOT interchangeable:

ChipI2C AddressRequired Library (C++)Note
QMC5883L (common clone)0x0DQMC5883LCompass.hMost modules sold today
HMC5883L (original Honeywell)0x1EHMC5883L.h or Adafruit_HMC5883_UOlder / genuine boards

Use an I2C scanner (Scan I2C Bus block) to detect your module's address and confirm which chip you have before uploading your sketch.


2. How it Works (Calculations & I2C Registers)

  • Magnetic Vector: The sensor measures the earth's magnetic fields. Readings are stored as signed 16-bit little-endian values in I2C data output registers 0x00 (X) through 0x05 (Z).
  • Heading (Azimuth) Calculation: The bearing angle (θ\theta, in radians) in the horizontal plane is calculated using the arctangent of Y and X vectors:
    θ=arctan⁡2(y,x)\theta = \arctan2(y, x)
    • Convert to degrees: Heading (degrees)=θ×180π\text{Heading (degrees)} = \theta \times \frac{180}{\pi}.
    • Wrap negative angles: if(Heading < 0) Heading += 360;.
    • Magnetic Declination (offset correction based on geographic location) should be added for true geographic North.

3. Component Properties

The GY-273 now has a real simulated component (gy273_compass) — drag it onto the Circuit Canvas from the Components palette. It exposes:

  • Magnetic Heading (heading) — range 0–359°, default 45°.
  • Pitch Angle (pitch) — range -90° to 90°, default 0°.
  • Roll Angle (roll) — range -180° to 180°, default 0°.
  • Mag X / Mag Y / Mag Z (magX/magY/magZ) — µT, defaults 28.3 / 28.3 / -30.0. These update live as you tilt/rotate the board (see Section 4) and reflect a real Earth-field model (40µT horizontal, -30µT vertical component, rotated by your current pitch/roll/heading).
  • Magnetic Declination (declination) — range -30° to 30°, default 0°. Added to heading to compute the true (geographic) heading shown on the readout, matching Section 2's real-world advice.
  • I2C Address (i2cAddress) — select 0x1E (HMC5883L, default) or 0x0D (QMC5883L).

All five pins are wired: VCC/GND power the module, SCL/SDA carry real I2C pull-up resistors, DRDY is a real (always-low) data-ready pin.

[!NOTE] The component's i2cAddress default (0x1E) doesn't match the real Blockly driver's default (0x0D) — checked both directly: the simulated component's Property Inspector defaults to displaying 0x1E (HMC5883L), while the bundled MicroPython QMC5883L driver class (Section 5) constructs with address=0x0D unless told otherwise. Per Section 1's own warning, 0x0D (QMC5883L) is what most real modules sold today actually use. This has no electrical effect either way — i2cAddress only changes the address printed on the component's rendered silkscreen, not any simulated behavior — but worth knowing the two defaults disagree.


4. Simulator Behavior

With the component placed and the circuit running:

  • Click-drag the center of the 3D board to tilt pitch (-90° to 90°) and roll (-180° to 180°) — this is a real 3D rotation, not a flat 2D indicator.
  • Click-drag the outer ring (near the edge of the compass dial) to set heading (0–359°).
  • Click a quick-preset button (N/E/S/W/Tilt 45°, visible only during simulation) to jump straight to that orientation.
  • A live text readout shows 🧭 <heading>° (<cardinal>) | Bx:<magX> By:<magY> Bz:<magZ>µT continuously while powered — always-visible, not a hover-only tooltip. <cardinal> is a real 16-point compass label (N, NNE, NE, ... NNW) computed from the true heading.

5. Supported Blockly Blocks

Drawing the blocks…

GY-273 Compass / Magnetometer (QMC5883L) — OMS Parts