mag-mmc5603 · PHP API
Mmc5603
Baremetal\I2c\Driver\Mmc5603: the constructor, the field, heading and temperature readings, and the 9-byte raw sample that poll() collects and decode() converts.
Baremetal\I2c\Driver\Mmc5603 extends Baremetal\I2c\Device and implements
Baremetal\Sensor\Magnetometer. All the Device methods work on it too; this page covers what the driver adds.
Constructor
new Mmc5603(Bus $bus, int $address = 0x30, int $hz = 400000)
Public method.
Parameters
-
$busBusrequired The bus the chip is wired to.
-
$addressintoptional, default0x30 7-bit address. The MMC5603NJ has a fixed address, so the default is the one to use.
-
$hzintoptional, default400000 SCL clock for this device: 0 uses 400 kHz, otherwise 1 to 1000000 Hz (a negative value throws
\ValueErrorfrom 1.0.2; earlier versions used 400 kHz).
The constructor attaches the device, checks the product id, resets the chip (20 ms), runs a SET then a RESET
pulse, sets the output rate to 100 Hz and starts continuous mode (another 20 ms). It throws \Exception:
| Message | Cause |
|---|---|
cannot init mmc5603 at 0x..: ESP_ERR_NOT_FOUND |
Something answered, but its product id is not 0x10. |
cannot init mmc5603 at 0x..: ... |
The id read or one of the configuration writes failed, for example ESP_ERR_TIMEOUT with no chip. |
address 0x.. on this bus is already used by another driver |
A raw device or another driver holds the address. |
Constructing it again with the same bus and address returns a handle to the same device without resetting it.
Readings
Mmc5603::mag(): array
Public method. Returns array.
[x, y, z] field in µT: each axis is a 20-bit value, offset by the mid-scale 524288 and scaled by 0.00625 µT
per count. One 9-byte read of the latest continuous-mode result. Throws MMC5603 mag read failed.
Mmc5603::heading(): float
Public method. Returns float.
atan2(y, x) in degrees, mapped to 0 to 360. Assumes the board is flat (z up) and is not calibrated. Reads the
chip like mag() and throws the same message.
Mmc5603::temp(): float
Public method. Returns float.
Triggers a temperature measurement, waits for it (checking every 2 ms, at most about 100 ms), and returns
raw * 0.8 - 75 °C. Throws MMC5603 temp trigger failed when the trigger write fails,
MMC5603 temp measurement did not complete within 100 ms when the chip never reports the measurement done
(versions before 1.0.2 returned the old register value), and MMC5603 temp read failed when the final read fails.
The chip measures temperature only outside continuous mode, so temp() stops continuous mode for the measurement
(up to 100 ms, during which a background sampler reads the last field values) and turns it back on; if that
fails it throws MMC5603 continuous mode could not be restored.
Background samples
Mmc5603::decode(string $raw): array
Public method. Returns array.
Converts one raw sample from sample() or drain() into ['mag' => [x, y, z], 'heading' => degrees], with
the same scaling as mag() and heading(). Throws \ValueError (an MMC5603 sample is 9 bytes) for a
shorter string.
The driver declares a sampler, so poll(), sample() and drain() work on this class. Each sample is the
9 output registers starting at 0x00; each axis is 20 bits:
| Byte | Content |
|---|---|
| 0, 1 | x bits 19 to 4 |
| 2, 3 | y bits 19 to 4 |
| 4, 5 | z bits 19 to 4 |
| 6, 7, 8 | x, y, z bits 3 to 0, in the high nibble |
The chip updates its output at 100 Hz, so a faster poll() stores repeated values. The descriptor states a
200 Hz maximum; ext-i2c does not enforce it.
<?php
use Baremetal\I2c\Bus;
use Baremetal\I2c\Driver\Mmc5603;
$mag = new Mmc5603(new Bus(sda: 7, scl: 8));
$mag->poll(hz: 20, depth: 32);
function loop(): void
{
global $mag;
foreach ($mag->drain() as $raw) {
['heading' => $h] = $mag->decode($raw);
printf("heading %5.1f\n", $h);
}
usleep(500000);
}
Capability
The class implements Baremetal\Sensor\Magnetometer, a marker interface ext-i2c always defines. Type a
parameter or an instanceof check on it to accept any magnetometer driver; the interface declares no methods.
Related
- A serial compass Recipe
- Device ext-i2c
- Background sampling and events ext-i2c