Antenne

Architecture overview — 9DoF motion sensor → OSC over Ethernet

Purpose

A self-contained motion sensor "antenna": plug the MPU9150 module directly into the ESP32-PoE's UEXT connector, power the board over a single Ethernet cable (PoE — no separate power supply), and it streams accelerometer, gyroscope, magnetometer, and fused orientation data as OSC to any receiving software (Max/MSP, Pure Data, TouchDesigner, etc.) at 50 Hz. Onboard gyroscope calibration runs automatically at boot, and a one-time (or as-needed) magnetometer calibration — triggered by a button hold or a remote OSC message — is persisted to flash so it survives reboots.

Hardware

System overview

Incoming OSC on port 8888 (/mpu/calibrate) can trigger a magnetometer calibration session on the board at any time, independent of the outgoing data stream.

Firmware main loop

The board runs a fixed 50 Hz loop (LOOP_MS = 20):

1. Boot — brings up the Ethernet link (static IP, up to 8 s wait), loads any previously saved magnetometer bias from flash (NVS), initializes the MPU9150 over I2C, and runs a 1-second gyroscope bias calibration (200 samples while the sensor must stay still).
2. Sensor read — one 14-byte I2C burst read covers accelerometer and gyroscope registers together; the magnetometer is read separately (via the MPU9150's I2C bypass mode giving direct access to the onboard AK8975) whenever its data-ready bit is set.
3. Orientation fusion — if a magnetometer calibration has been completed, the corresponding per-axis bias is subtracted before the vector is normalized to unit length. The result feeds a 9-axis Kalman filter (from puara-gestures) that fuses accelerometer, gyroscope, and magnetometer into roll, pitch, and tilt-compensated yaw.
4. OSC send — one bundle per loop iteration, gated on the Ethernet link being up.
5. LED / input handling — the LED state machine and the BTN1 long-press detector run every cycle, and any incoming OSC calibration request is dispatched here too.

Magnetometer calibration

Hard-iron interference (nearby metal, speakers, power supplies) shifts the magnetometer's zero point, which throws off yaw. Calibration removes that constant offset — needed once at first setup, and again whenever the instrument's physical configuration changes.

Calibration can be started two ways — holding the physical button, or sending an OSC message from the same network the board streams to — so it can be triggered either at the instrument itself or remotely from whatever software is already receiving its data. During the 30-second window, rotating the sensor through every orientation (a figure-8 motion covering all axes works well) lets the firmware record the true minimum and maximum reading on each magnetometer axis; the midpoint of each axis's min/max becomes that axis's bias. The result is written to non-volatile storage and survives power cuts and firmware re-flashes.

LED states

OSC reference

Outgoing (board → computer), one bundle per 20 ms

Incoming (computer → board), port 8888

Adjustable parameters

Project structure

├── boards/
│   └── esp32-poe-16mb.json     custom PlatformIO board definition
├── examples/
│   ├── ESP32_PoE_Ethernet_SD_Card_Arduino.ino
│   ├── ESP32_PoE_WebServer_Demo.ino
│   └── MagnetometreCalibrationDemo.cpp
├── mpu9150_demo/                original bare sensor demo
├── src/
│   └── main.cpp                 firmware (edit this)
└── platformio.ini

The examples/ and mpu9150_demo/ folders are bundled reference material, not part of the firmware that actually runs — each comes from a different origin and is kept for reference rather than executed:

• mpu9150_demo.ino — the original bare-metal MPU-9150 I2C register demo (public domain, by Arduino user "frtrobotik" / Tobias Hübner, Olimexino edition by Chris B.) that the sensor-register logic in this project traces back to.
• MagnetometreCalibrationDemo.cpp — a magnetometer-calibration reference example from a different IDMIL project (GuitarAMI, Edu Meneses, built on the Puara templates), kept here as a comparison point for calibration UX on a fuller IMU stack (LSM9DS1/BNO080).
• ESP32_PoE_WebServer_Demo.ino — a general-purpose webserver demo for the Olimex ESP32-PoE board (controls various Olimex UEXT modules), originally by David Bird, adapted for this board — unrelated to the MPU9150 but useful as an ESP32-PoE peripheral reference.
• ESP32_PoE_Ethernet_SD_Card_Arduino.ino — a combined SD-card + Ethernet bring-up demo for the same board.

Custom PlatformIO board definition

boards/esp32-poe-16mb.json defines the Olimex ESP32-PoE's 16 MB-flash variant for PlatformIO, since it isn't one of the built-ins: correct partition table and linker script for 16 MB flash, the Ethernet PHY wiring specific to this board (LAN8720 over RMII, MDC/MDIO pins, power pin, clock mode), and upload parameters (921,600 baud, esptool/espota).

Dependencies

Managed automatically by PlatformIO:

• CNMAT OSC — OSC message/bundle library
• puara-gestures — 9-axis Kalman filter for orientation
• ESP32 Arduino framework (Espressif32, via PlatformIO)