5.1 KiB
Exercise 25: MotionCal T-Beam Bridge
This PlatformIO project turns a LilyGO T-Beam Supreme into a serial bridge for Paul Stoffregen's MotionCal desktop calibration tool.
The firmware reads the onboard QMC magnetometer through SensorLib and streams MotionCal-compatible ASCII Raw: lines over USB serial. MotionCal can then estimate both hard-iron offsets and the soft-iron correction matrix for the board.
Hardware
Target board:
LilyGO T-Beam Supreme / ESP32-S3
QMC6310/QMC5883-family magnetometer
SH1106 OLED display
The firmware probes these magnetometer I2C addresses:
0x1C QMC6310U
0x3C QMC6310N
0x2C QMC5883P
The default PlatformIO environment is cy, with additional board labels available in platformio.ini:
amy bob cy dan ed flo guy
Serial Format
MotionCal expects lines in this format:
Raw:accel_x,accel_y,accel_z,gyro_x,gyro_y,gyro_z,mag_x,mag_y,mag_z
This bridge only has a magnetometer, so it sends fixed placeholder accel/gyro values:
Raw:0,0,8192,0,0,0,mag_x,mag_y,mag_z
The placeholder values mean:
accel = 0,0,8192 approximately stationary upright in MotionCal's count convention
gyro = 0,0,0 no gyro data supplied
mag = live QMC magnetometer data
Magnetometer Units
SensorLib returns QMC magnetometer readings in Gauss. The firmware converts them like this:
1 gauss = 100 microtesla
MotionCal count = microtesla * 10
1 MotionCal count = 0.1 microtesla
So a streamed value like this:
Raw:0,0,8192,0,0,0,-1735,428,793
means:
X = -1735 counts = -173.5 uT = -1.735 gauss
Y = 428 counts = 42.8 uT = 0.428 gauss
Z = 793 counts = 79.3 uT = 0.793 gauss
These are MotionCal-compatible integer counts, not raw QMC register values.
Build
Activate the Python environment that contains PlatformIO:
source /home/jlpoole/pioenv/bin/activate
Build the default environment:
cd /usr/local/src/microReticulumTbeam/exercises/25_motioncal_tbeam
pio run
Build a specific board label:
pio run -e dan
Upload
Upload the default environment:
source /home/jlpoole/pioenv/bin/activate
cd /usr/local/src/microReticulumTbeam/exercises/25_motioncal_tbeam
pio run -t upload
Upload a specific board label:
pio run -e dan -t upload
Serial Monitor
After flashing, monitor the USB serial stream at 115200 baud:
pio device monitor -b 115200 --port /dev/ttytDAN
Expected boot/status output includes lines like:
exercise=Exercise 25 MotionCal T-Beam bridge
serial_format=Raw:accel_x,accel_y,accel_z,gyro_x,gyro_y,gyro_z,mag_x,mag_y,mag_z
mag_units=MotionCal integer counts, 1 count = 0.1 uT
magnetometer_init=ok label=QMC6310U addr=0x1C chip=0x..
Expected streaming output looks like:
Raw:0,0,8192,0,0,0,-1578,447,1266
Raw:0,0,8192,0,0,0,-1583,438,1258
Raw:0,0,8192,0,0,0,-1585,442,1250
If the firmware prints read_fail or overflow status lines, check I2C wiring/power and the configured magnetometer full-scale range.
Running MotionCal
Build MotionCal if needed:
cd /usr/local/src/MotionCal
make WXCONFIG=wx-config LDFLAGS="-lglut -lGLU -lGL -lm"
Run it:
cd /usr/local/src/MotionCal
GDK_BACKEND=x11 ./MotionCal
Then select the T-Beam USB serial port in MotionCal.
Move and rotate the T-Beam through as many orientations as possible. The goal is to cover the sphere well, not just wave it flat on the table. Better 3D coverage improves both hard-iron and soft-iron calibration.
Saving Calibration
MotionCal computes:
magnetic_offset_uT hard-iron offset, in microtesla
magnetic_mapping_matrix inverse soft-iron correction matrix
magnetic_field_uT fitted local field magnitude
Example:
magnetic_offset_uT=-172.96843,43.0260162,78.8941956
magnetic_field_uT=52.4668198
magnetic_mapping_matrix=
0.943139076 0.0439298451 0.0595370531
0.0439298451 1.04979992 -0.0347476006
0.0595370531 -0.0347476006 1.01706612
The firmware also accepts MotionCal's 68-byte calibration packet and echoes Cal1: and Cal2: lines so MotionCal can confirm the send.
Applying Calibration
MotionCal's calibration model is:
mag_uT = raw_motioncal_counts * 0.1
centered = mag_uT - magnetic_offset_uT
corrected = magnetic_mapping_matrix * centered
Hard iron moves the center of the magnetometer cloud back to zero. Soft iron transforms the ellipsoid-shaped cloud back toward a sphere.
Troubleshooting
If MotionCal does not show points:
Confirm the serial port is correct.
Confirm baud is 115200.
Confirm monitor output contains Raw: lines.
Close any serial monitor before opening the port in MotionCal.
If the values look 10x different from a notebook or script:
The notebook/script may be using MotionCal counts.
MotionCal's saved magnetic_offset_uT is already in microtesla.
Convert counts to uT with: uT = counts * 0.1
If the fit is poor:
Collect more orientations.
Rotate around all axes.
Keep the board away from steel, speakers, motors, magnets, and high-current wiring.
Try a different location and repeat the calibration.