The declination model landed as 4.7 KB of constants pasted into a Lua app,
generated by a script that lived in out/ -- which is gitignored, holds firmware
bins, and is where the app's own "Regenerate:" comment pointed. So the pointer
dangled for anyone who cloned the repo, and nobody but me could answer the
first fair question a reviewer would ask about that block of magic numbers:
where did it come from, and how do I know it is right.
scripts/wmm/ WMM.COF + NOAA's 100 official test values (both upstream
and unmodified), the float64 reference, the generator,
verify.py, and a README covering provenance, regeneration
and how to move to WMM2030.
scripts/lua-harness/ the host harness, with run.sh so it is one command.
Neither goes in test/: that is PlatformIO's directory and a harness with a
main.c would be swept into `pio test`. scripts/ already holds this repo's dev
tooling, test_companion_serial.py included.
The block in the app is now genuinely generated rather than hand-pasted:
scripts/wmm/gen_lua.py --update <app> rewrite it
scripts/wmm/gen_lua.py --check <app> fail, with a diff, if it drifted
--check catches coefficients updated without regenerating, or a block edited by
hand. The generator owns the `local declination / do ... end` wrapper too, and
that is the point: the tables are named G/H/GD/HD, gpscompass uses a global H
for the screen height, and an unscoped `local H` silently ate it. Hand-wrapping
is how that happened, so hand-wrapping is now not a step.
Verification, all reproducible from a clean clone:
scripts/wmm/verify.py 100 NOAA values, worst D error 0.005 deg
scripts/lua-harness/run.sh 10 scenarios, incl. the generated Lua in
the device's own LUA_32BITS interpreter --
0.0002 deg vs NOAA, worst tick 12k of 100k
Also refreshes the LUA_APPS.md paragraph, which still advertised the O and F
keys that were removed and quoted harness numbers from before tilt
compensation.
Every contact and waypoint sat about 22 degrees west of where it belonged,
including nodes whose positions were known to be correct. The markers were
never wrong: bearings computed from coordinates are relative to TRUE north,
the magnetometer measures MAGNETIC north, and the app was drawing one against
the other. The gap between them is the local declination.
Builds the real World Magnetic Model into the app rather than a lookup table
or a hand-entered offset: WMM2025 to degree 12, coefficients and code in
4.4 KB, reproducing NOAA's own calculator to 0.0002 degrees at six sites
worldwide -- verified in this interpreter, on the module as it actually ships
in the app file, not on a copy. The secular-variation terms are included, so
it stays exact across its 2025-2030 window instead of drifting a tenth of a
degree a year from a frozen snapshot.
It is evaluated from the GPS fix, or from the node's own stored position when
there is no fix yet, and only re-evaluated once the position has moved 2 km --
about 8k VM instructions, against a 100k budget per tick. The result persists,
so a reboot starts from the last known declination rather than from zero.
Also:
- A ("set north") no longer double-counts. The offset it stores is a residual
on top of the model, but pressed with no position at all it silently
swallows the whole declination; that is now remembered and given back when
the first fix arrives, so the direction the user fixed stays fixed.
- Headings and bearings carry their reference: 013 deg T, or an amber M while
the declination is unknown. The dial's repaint key includes it, or the first
fix would leave it claiming MAGNETIC until the heading happened to move.
- WMM ships a caution model with its coefficients; under 6000 nT of horizontal
field the app now says the heading is unreliable instead of showing a
confident wrong number.
- Diagnostics take the full-width bottom row for the declination and the
position it was computed at, which is how a wrong marker gets traced to a
bad fix rather than a bad model.
Harness: two new scenarios -- the model against NOAA reference values, and the
no-fix alignment path. The latter caught a real one: the device store takes
strings and numbers, and a boolean flag would have thrown on hardware.
Flip (F) and the "Flip" button are gone, and the stored `mirror` setting with
them. Rotate (O) had already gone. Both existed to let a user hand-tune the
sensor handedness back when it was unknown; both frames are measured now, so
the keys could only break a correct compass. A future board with different
mounting gets a measured mapping, not a key it has to be discovered.
The accelerometer has a zero-g offset -- this one reads ~0.08 g high on Y lying
flat, which is 4.6 degrees of tilt that is not there, applied by the tilt
correction against a gravity vector that is wrong by that much, and wrong in
the DEVICE's frame so it moves the heading differently at every heading.
Rotating the device every way already sweeps a 1 g sphere for the
accelerometer alongside the field sphere for the magnetometer, so the same fit
recovers it at no cost to the user: same gesture, one more set of running sums,
and it is only accepted when the sphere it fits is close to the 1 g it must be.
Simulated with a 0.08 g bias injected: recovered to within 0.02 g, and a flat
device then reads 0 degrees of tilt instead of 5.
Diagnostics: rows were wrapping onto each other. They are shorter now, and
while diagnostics are on the four rows take the whole panel width (the key
column is reclaimed) -- the harness fails if any row exceeds what fits. The
status line also reports the vertical field (d+0.42), which is the measurement
that says whether the magnetometer's Z sign -- inferred, never measured -- is
right: north of the equator, held flat, it must be positive.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two small conflicts, both additive on each side: upstream added ui.text_w /
ui.text_lines and a "measure" capability while this branch added the panel
colour and the compass/accel caps. Everything from both is kept and the table
hints match the merged key counts.
GPS Compass now uses ui.text_w where the firmware offers it and keeps the
character estimate as the fallback. That estimate is what once put the heading
digits off centre -- it counted UTF-8 bytes, so the degree sign read as two
characters -- and measuring removes the guess entirely, for the dial's centred
text and the satellite meter's reserve alike.
M9, V4, V4-R8, T-Deck and Pager all build; the app harness passes, including
the tilt check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A two-axis magnetic heading assumes the device is level. At this latitude the
field dips ~60 degrees, so the vertical component is 1.6x the horizontal one
and tipping the device leaks it into the pair the heading is made from: about
1.5 degrees of heading per degree of tilt. That is what "it drifts" was once
the calibration was sound -- it was the hand holding it.
Driver: variants/thinknode_m9/M9Imu.{h,cpp}, QMI8658 at 0x6B on the peripheral
bus, accelerometer only (the gyro is most of the power budget and nothing here
needs it): +/-2 g at 62.5 Hz with the low-pass on, soft reset with a 160 ms
wait that covers both die variants, and the same idle-suspend as the compass so
it costs nothing when unused. CTRL1's ADDR_AI bit is set and read back -- with
it clear the burst read silently returns six copies of one byte, which looks
like a working sensor reporting nonsense. HAS_M9_IMU -> CAP_IMU ->
wada.sys.accel(), caps().accel.
Axes MEASURED, not guessed, by holding three attitudes and logging:
flat, screen up z = -1.02 -> +Z into the screen (down)
on bottom edge, top up x = +0.97 -> +X at the top edge (forward)
on left edge, right up y = +1.08 -> +Y at the right edge
So the IMU is already in the aerospace body frame, and it agrees with the
magnetometer's independently measured +Z-into-screen. (Meshtastic's M9 driver
passes both sensors through untransformed and mirrors the heading on the sign
of accel Z, so its compass flips when the device is turned over. Not copied.)
Heading now rotates the field back into the horizontal plane using gravity
(NXP AN4248 / ST AN3192) before taking the angle, and reports the tilt angle;
past 55 degrees it says "too steep to read" rather than lying. Calibration
returns to a 3D fit because tilt compensation needs the vertical offset too --
but the instruction is now "turn it every way ON ONE SPOT", and the
accelerometer VERIFIES it: coverage is measured by how far gravity swung, so a
flat spin is refused by name ("turn it nose over tail") instead of silently
fitting a degenerate sphere. Simulated in the harness against a modelled M9 in
a known attitude: offsets recovered exactly, and the heading holds within 3
degrees through 20 degrees of roll and pitch.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two faults, one of them mine from an hour ago.
CAL_SECS is 20 s and the M9's default screen timeout is also 20 s. The tick
pause added in 5a4a5a8 stopped the app the instant the screen blanked, which
is the same instant the calibration was due to finish -- so sampling stopped
half way, the auto-finish (inside on_tick) never ran, and the partial sweep was
fitted and saved without complaint. New wada.sys.keep_awake() holds the screen
AND the tick for a measuring app, and is released when the app closes.
The tumbling instruction was wrong too. Hard-iron calibration assumes the
device ROTATES in a uniform field; carrying it through the air also TRANSLATES
it through the field gradients of a laptop and a desk. Measured consequence: a
centre that moved 0.15 G between sessions against a 0.26 G horizontal signal,
i.e. tens of degrees of direction-dependent error -- which is what "it drifts
when rotating" was. The same device rotated flat in one place fitted a circle
to within 4%, so calibration is now exactly that: a 2D circle fit on x/y, which
is the only thing a heading uses.
And a bad fit can no longer be saved silently, which is how the broken one got
in. calib_solve refuses, with a reason, when the turn is partial (each axis
must span >= 1.4r), when the radius is outside Earth's real horizontal range
(0.08-0.45 G), or when the circle is too distorted (residual > 18% of r --
computed in closed form from the sums already collected). The progress line
shows coverage rather than a countdown.
Also: mag_norm is now the HORIZONTAL magnitude, which lets the app say "Hold it
level" when it departs from the calibrated radius -- the tell-tale for tilt,
which is the accuracy ceiling until the IMU is driven.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
North was wrong on hardware, and the device's own saved state said why. Its
stored centre was (-0.3875, -3.465) where four measured headings put the true
centre at (-0.340, -3.378): out by 0.099 G against a horizontal field of only
0.27 G. Replaying the measured readings through that centre gives -1 deg of
error at north, -12 at east, -18 at south and +22 at west -- errors that swing
with direction, which is a wrong centre, not a wrong formula. align and mirror
were both 0, so the axis mapping was doing its job.
Min/max midpoints only find the centre from a COMPLETE sweep and are skewed by
whichever extreme was missed; with a bias ~7x the field here, a tenth of a
Gauss of skew is a third of the whole signal. Calibration now fits the sphere
that the samples actually lie on -- |p - c|^2 = r^2 is linear in (c, r^2-|c|^2),
so it is a 4x4 solve over running sums with no sample storage, which matters
inside a 256 KB app heap. Coordinates are accumulated relative to the first
sample because Lua here is single-precision and squaring raw values near 3.5 G
throws away the precision the fit depends on.
The fit is checked before it is saved: a singular system (a flat spin, where
the centre is undetermined along z) or a radius outside Earth's 0.25-0.65 G
band is refused with a reason, leaving the previous calibration alone -- the
old code would happily save the garbage. The toast now reports the fitted field
strength, which is the number that says whether a calibration is any good, and
the progress line shows the sample count.
Also adds a D key: the calibration in use, the raw vector, the horizontal
components and the stored align/mirror, so a wrong heading can be read off the
screen instead of guessed at. Harness: the fit recovers a simulated bias
exactly, and a flat-only spin is refused without touching the saved values.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
beta_68 expanded the Lua SDK (map, lists, packet delivery, discovery, private
messages/rooms, native crypto) across the same files as this branch, so four
files conflicted. Nothing was dropped from either side:
- wada.sys.gps(): both widenings merged into one binding. Upstream's
fix_time / lat_e6 / lon_e6 and our speed_kmh / course now share a signature,
and our stricter gate wins -- the call returns nil when the user has GPS
switched off, not just when there is no fix.
- Altitude is upstream's `alt_m` alone. The resolution first carried `alt`
beside it to protect a shipped app, but gpscompass has never been published
to the store (it exists only in this branch and on a bench device), so
carrying a duplicate key into the API forever was the wrong trade: the app
reads alt_m instead.
- sysCaps() carries all twelve feature flags (upstream's seven, our compass,
the four originals) with a matching table hint.
- wada.geo (upstream) and wada.sys.compass (ours) both survive; upstream's
"no board has a magnetometer" note is corrected in the code and on the SDK
page, since the M9 now does.
- hostTeardown frees upstream's new POST payload buffer as well as the fetch
buffer, under the same in-flight guard.
- The catalog keeps all three new apps: upstream's wardrive and nearby, ours
gpscompass (8 total, every referenced file present).
M9, V4, V4-R8, T-Deck and Pager all compile; the Lua host harness passes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every installed Lua app drew the same generic play glyph in the drawer, and
the manifest's "icon" -- promised in LUA_APPS.md since the plan was written --
was never parsed. It is now read from <id>.json and mapped to a glyph by NAME
(gps / radio / chart / game / ...), not by codepoint: a name is reviewable in
a store submission, the device's JSON scanner only takes quoted strings
anyway, and an app can never ship a glyph the UI fonts lack -- anything
unrecognised falls back to the generic symbol. A bare side-loaded .lua has no
manifest and keeps that symbol too.
GPS Compass declares "icon":"gps", so it now shows the location pin the Map
tile uses.
Also corrected deploy/site/sdk.html, whose manifest table documented
"version", "min_api", "description" and "boards" -- the device has never
parsed any of them -- and described icon as "a single character".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The meter sat too far from the count: the reserve used text_w's
0.55-per-character estimate, which is for mixed text, while the digits and
spaces in "99 sats" run nearer 0.39 of the line height. Sized properly it now
sits beside the number, and still holds still as the count changes.
"A set north" is no longer advertised. The axis mapping is measured, so a
calibrated device points north on its own; A and F remain for an unknown
board or a stubborn environment, they just do not need to be on screen.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The sensor's orientation on the board is documented nowhere, so it was
measured: held flat, logging the raw vector at four headings 90 deg apart
(M9_COMPASS_DEBUG, now off again) gives a hard-iron centre of
(-0.340, -3.378) and, after subtracting it,
N x'=-0.055 y'=+0.310 E x'=+0.268 y'=-0.018
S x'=+0.013 y'=-0.275 W x'=-0.225 y'=-0.016
so atan2(x, y) reads 350/94/177/266 at N/E/S/W -- 0/90/180/270 within a few
degrees, counting up clockwise. +Y is the device's top edge, +X its left.
That is now the default: correct after calibration alone.
This also explains the reversal reported on hardware. The auto-handedness
rule assumed a Z-out-of-screen sensor was the un-mirrored case; it is the
other way round -- held flat north of the magnetic equator, a Z-INTO-screen
sensor reads the downward field as POSITIVE z. Fixed, and the stored
orientation is versioned so values saved against the old formula are
discarded rather than pushing a correct default back off north.
The bias is real and large: ~-3.4 G on Y against a ~0.27 G horizontal
signal, which is why an uncalibrated device barely moves the dial, and why
the range is +/-32 G rather than +/-8 G. Meshtastic's implausible hardcoded
extrema were right after all.
Also: the satellite meter now sits beside the count instead of at the column
edge, and UITask::loop's coarse "ui:gps" stall bucket is split into
timers/threads/input/diag so a 450 ms hitch can be attributed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Up and down move a selection between the ALT and SPD rows (the selected row's
key turns accent), and OK switches that row's units -- feet/miles or metres/km
for altitude, which the target's range follows too, and mph or km/h for speed.
Imperial is the default. On touch boards a tap on the row itself does the same,
while a tap on the dial keeps stepping the target. Both settings persist.
No "enter" handler on purpose: the host answers OK with a synthetic down/up
pair AND an enter key event, so acting on both would switch the units twice
and read as nothing happening.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Lua app page painted itself 0x0E1216 while the rest of the firmware
paints pure black (COLOR_BG), so every app read as a lighter panel floating
over the UI. The page is now black and wada.ui.colors gains `panel` for the
raised surface an app draws on top of it -- the compass dial uses it, so the
instrument stands out instead of the page doing it.
Rotate/flip are gone from the user's side. They existed because the QMC6309's
axis orientation on the M9 is undocumented, which is not the user's problem to
solve by trial and error. `A` now does the whole job: whether the heading runs
clockwise or anticlockwise follows from which way the sensor's Z axis faces,
and that shows in the sign of the vertical field -- Earth's field dips down
north of the magnetic equator and up south of it -- so with a position (a fix,
or the node's last known one) the app reads the handedness off the sensor and
the press only has to set the offset. `F` stays as the fallback for a flat
field or no position at all.
Layout: stats column on the left, dial on the right (its status line above
it, the hint centred along the bottom).
The host harness now tumbles the simulated device during calibration rather
than spinning it flat -- min/max on an axis that never moves subtracts the
true field along it, which is precisely the case the handedness check has to
detect and refuse, and the flat mock was hiding it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Layout, from on-device feedback: the magnetometer/heading-source line moved
from the stats column to a centred line over the dial; the stats panel now
starts at the top of the column, and the rows that freed up went to the
target -- name, range + bearing, how far to turn ("56 deg right", "ahead")
and when the contact was last heard. The key hint is centred along the
bottom edge of the view and spells the actions out ("C calibrate O rotate
F flip <> target"). The heading's DIGITS are centred with the degree sign
hanging off their right edge, so the number does not appear to shift as the
reading crosses 100/200; the width estimate also counts characters rather
than bytes now, which is what put it half a glyph off (the degree sign is
two bytes in UTF-8).
Host: label:width(px) takes an optional alignment ("center"/"right") -- an
app cannot measure glyphs, so this is the only way for it to centre a line
exactly. Also excluded the app ROOT from keyboard-nav focus: excluding only
the body moved the reverse-video highlight up one level instead of removing
it, which is why the page was still white.
sideload_app.py retries fput/fend as well as fadd -- the same UART byte loss
that garbles a long line can garble a short one ("Error: unknown command").
Calibration now reports the measured field strength in its toast, which is
the number that says whether the calibration is any good (Earth: 0.25-0.65 G).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
On the ThinkNode M9 every Lua app opened on a white page: the app body is a
clickable object (touch boards need its press events) on the top layer, so
navCollect harvested it as a leaf focus target and navFocusCb's reverse-video
fill painted it solid under the app's widgets -- the canvas on top stayed
dark, which is what gave it away. NAV_SKIP_FLAG would also hide an app's own
buttons from the d-pad, so this adds NAV_PASSTHRU_FLAG (AppPage.h, shared by
both TUs): clickable, never a target itself, children still collected.
M9 compass: low-pass depth 8 at 50 Hz (the datasheet's 0x61 example) read as
sluggish on the dial; now depth 4 at 100 Hz (CTRL1 0x41, CTRL2 0x30). The
app ticks at 100 ms with lighter smoothing to match.
GPS Compass app rebuilt in the RF Monitor's look: a dial with rings,
10/30/90-degree graduations, red north, a lubber mark and the heading in
the centre; a key/value panel (FIX/LAT/LON/ALT/SPD/TGT) with a 10-cell
satellite meter; compact strings where the column is narrow at large fonts.
Confirmed on the M9 by Chris: the dial turns and calibration holds
(gpscompass.sav persists across reboots).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Firmware
- variants/thinknode_m9/M9Compass.{h,cpp}: QMC6309 at 0x7C on the peripheral
bus. Probe by chip id, soft reset with the explicit clear, CTRL2 0x20
(50 Hz, +/-32 G, set/reset on), CTRL1 0x61 (normal, OSR 8/8), read-back
verified. Synchronous read from the Lua host bridge, 1 s cache, lazy
re-probe while the rail-powered part is still in POR, OVFL kept + flagged +
logged. HAS_M9_COMPASS=1 in the env -> new hardware gate CAP_COMPASS.
- src/helpers/WadaNmeaLocationProvider.h: Wadamesh-owned copy of the core
MicroNMEALocationProvider that also exposes RMC speed/course (the core
keeps its parser private; no libdeps patch). M9 target.cpp builds on it,
HAS_GPS_MOTION=1, wadaGpsMotion() for UITask.
- wada.sys.gps(): + alt (m), + speed_kmh/course where the board provides
them (course only while moving -- an empty RMC course parses as 0), and
nil while the user has GPS switched off. wada.sys.compass(): {x,y,z,ovfl}
Gauss, sensor frame, uncalibrated, registered only where CAP_COMPASS;
caps().compass. Calibration, axis mapping and the heading maths live in
the app so they can be adjusted per user without a firmware cut.
- Host: luaHostContactAt reads the RTC once per contacts() walk instead of
once per contact (an I2C transaction each on the M9); pressCb reports
press coordinates in body content space (scroll offset folded in).
App
- deploy/apps/gpscompass/1.0 + apps.json: rotating rose with a fixed index,
live fix readout, bearing/range to a selected contact, magnetometer
heading with hard-iron calibration (C), frame rotate/mirror (O/F, the
M9's sensor orientation is undocumented), GPS-course fallback on every
other board, saturation warning. Not baked into lua_builtin.h on purpose
(CAP_BUILTIN_LUA_APPS also removes the Store > Apps tab).
Verified: M9, V4, V4-R8, T-Deck compile (M9 flash +2 KB); two adversarial
review passes, all confirmed findings fixed; host Lua harness (vendored
Lua, LUA_32BITS) -- calibration recovers a simulated bias exactly, heading
error 0 deg, worst tick ~10k of the 100k budget. Hardware validation list
(axis orientation, bias magnitude, 0x7C ACK) in M9_PORT.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
