HMC5883 Compass/Magnetometer

This module interfaces with an HMC5883, an I2C compass/magnetometer.


Device Pin Espruino
Vcc 3.3


Setup the I2C that will be used, and then connect to the HMC5883:

var compass=require("HMC5883").connect(i2c,drdy,mode)
  • i2c is the i2c bus being used
  • drdy is the pin connected to the drdy pin of the HMC5883.
  • mode is optional - specify 0 to enter continuous measurement mode immediately.

This sets the current measurement mode.

Mode Meaning
1* Single measurement
0 Continuous measure
2 Idle

Set the gain. Due to limitations of the chip, the new gain is not applied to the next measurement taken, but rather the one after that. This module handles this. In single measurement mode, a dummy measurement is taken so that the next measurement requested will have the new scale. The chip starts up in gain=1.

Gain Rec. range resolution
0 +/- 0.88 Ga 0.73 mGa
1* +/- 1.3 Ga 0.92 mGa
2 +/- 1.9 Ga 1.22 mGa
3 +/- 2.5 Ga 1.52 mGa
4 +/- 4.0 Ga 2.27 mGa
5 +/- 4.7 Ga 2.56 mGa
6 +/- 5.6 Ga 3.03 mGa
7 +/- 8.1 Ga 4.35 mGa

Set other options

  • sample sets the number of samples averaged for each measurement:
sample Samples
0* 1
1 2
2 4
3 8
  • dout sets the frequency with which measurements are taken when in continuous measurement mode
dout Output Rate
0 0.75 hz
1 1.5 hz
2 3 hz
3 7.5 hz
4* 15 hz
5 30 hz
6 70 hz
  • ms is optional, and defaults to 0. It can be set to 1 or 2 enable positive or negative bias selftest for calibration. Refer to the datasheet for more information.


In single measurement mode (the default), read it with reads():

compass.reads(function(a) {console.log(a);})

The function is a callback called when the measurement is complete.

In continuous measure mode, use readc():


The measurement is returned as an object with properties overflow, x, y, and z. If overflow is true, at least one of the axes overflowed. The gain should be adjusted and measurement repeated. x, y, and z are the measured field strength in milligauss. Experimentation has found that when exposed to excessively strong magnetic fields at gain=7, the sensor may return 0 or -1 (which will be multiplied by the gain factor by this module), instead of an overflow result.


This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.