Repository navigation
Description
The contributing doc says to open an issue and get a thumbs-up before submitting a PR for a feature. I've already done the work, and am using it on Wio Tracler L1 Pro units for a app I've written for tracking ranger patrols at a burner style event. I'd like to share back to the community, if it would be useful. As an explanation of my idea, and the way I implemented it, I am submitting the PR message I used on my fork rather than a short summary blurb. Why waste the content, right?
I realized a little late that feature work should be done against the dev branch. If I get a thumbs-up for this I'll be sure to merge in all the work in dev before submitting a PR.
Cheers,
-Chris
Summary
Adds an on-demand precise position request to MeshCore's companion firmware (examples/companion_radio), addressing the 24-bit GPS quantization in the existing telemetry response.
The standard telemetry reply encodes GPS as CayenneLPP LPP_GPS: 3-byte latitude/longitude at 0.0001° (about 11 m steps) plus 3-byte altitude. That is coarser than the GPS fix itself. Zero-hop adverts carry 1e-6° (about 0.11 m), but they do not cross repeaters, carry no altitude or fix metadata, and are not permission-scoped. This change adds a new peer request type, REQ_TYPE_GET_POSITION = 0x0A, so a stored contact can ask a node for its current position at 1e-6° precision.
What is new
- New request type
0x0Ahandled inMyMesh::onContactRequest()(examples/companion_radio/MyMesh.cpp). - 22-byte response containing the echoed tag, fix flags, latitude/longitude as int32 × 1,000,000, altitude as int32 millimetres, satellite count, and GPS fix timestamp.
PositionDatacodec (src/helpers/PositionData.h) writing and reading the wire format byte-by-byte in little-endian order, with host tests.- Shared telemetry permission resolver (
src/helpers/TelemetryPermissions.h) used by both the existing telemetry branch and the new position branch. - Additive
SensorManager::isLocationActive()accessor, overridden byEnvironmentSensorManagerand the GPS-capable variant managers, so turning GPS off cannot return a provider's retained last fix. getLocationProvider()exposed on three variant managers that already own a provider (Heltec_mesh_solar,Meshadventurer,Nano_G2_Ultra).- Protocol documentation updated in
docs/payloads.mdanddocs/companion_protocol.md.
Wire format
Request (the companion's sendRequest() prepends the 4-byte tag):
| Field | Size | Description |
|---|---|---|
| tag | 4 | sender timestamp (uint32 LE) |
| req type | 1 | 0x0A |
Response:
| Field | Size | Description |
|---|---|---|
| tag | 4 | echoed sender timestamp (uint32 LE) |
| flags | 1 | bit 0: valid fix; bit 1: altitude valid; rest zero |
| latitude | 4 | int32 LE, degrees × 1,000,000 |
| longitude | 4 | int32 LE, degrees × 1,000,000 |
| altitude | 4 | int32 LE, millimetres |
| satellites | 1 | satellites used in the fix |
| gps timestamp | 4 | uint32 LE, epoch seconds; 0 when unknown |
Total: 22 bytes.
Client flow
The base companion firmware is unchanged. A client sends CMD_SEND_BINARY_REQ (50) with the contact's public key and the [0x0A] request byte. The companion replies RESP_CODE_SENT (6) with a tag and estimated timeout; the node's reply arrives as PUSH_CODE_BINARY_RESPONSE (0x8C), with the response payload beginning after the 4-byte tag. Timeouts are recovered with CMD_RESET_PATH (13) followed by a retry; the next request floods and the returned path re-establishes direct routing.
No impact on existing functions or commands
This is an additive feature. It does not change the behavior of any existing command or payload:
- No existing request type, command code, payload format, or wire format is changed.
- The telemetry permission mapping was refactored from inline
if/elseblocks to a shared resolver. The resolver returns exactly the same bits forALLOW_ALL,ALLOW_FLAGS, andDENY, and the full existing host suite still passes. SensorManager::isLocationActive()is additive, with a safefalsedefault. Existing managers that do not override it are unaffected. The three addedgetLocationProvider()overrides expose a provider those managers already owned; this also makes the pre-existinggps sync/gps diagCLI paths work on those boards, but does not alter any existing command's semantics.- Old mobile firmware simply does not answer
0x0A; the client observes a timeout. Old clients never send it. The stock base companion needs no firmware change (CMD_SEND_BINARY_REQexists since companion v1.10.0). 0x0Awas unused anywhere in the tree. An out-of-tree listener that had privately claimed0x0Awould need to renumber; no in-tree component is affected.- No new dependencies.
Security and privacy
- Requests are accepted only from stored contacts and are encrypted end-to-end with the contact shared secret.
- The response is gated by the existing location telemetry permission (
telemetry_mode_locplus the contact's location flag). The default is deny. - With GPS disabled or no current fix, the response has flags 0 and all position fields zero. A stale fix is never presented as live.
- The base companion matches responses to its pending request by tag only, and the push frame carries no responder identity. Precise position is therefore authenticated only to the level of "a stored contact reported it." A base-side pending-recipient check is noted as possible future hardening.
Testing
Host suite
pio test -e native -v → 61/61 tests pass.
New tests:
test_position_data(10): encode/decode round-trip, little-endian byte layout, negative andINT32_MIN/INT32_MAXcoordinates and altitude, short-buffer rejection, trailing-byte tolerance, GPS-inactive and no-fix zeroing, timestamp sanity, satellite clamping.test_telemetry_permissions(5):ALLOW_ALL,ALLOW_FLAGSwith and without the contact bit,DENY, and permission-bit independence.
The 46 pre-existing tests are unchanged and still pass.
Firmware builds
All of the following built successfully with PlatformIO:
Heltec_v3_companion_radio_bleheltec_tracker_v2_companion_radio_bleMeshadventurer_sx1262_companion_radio_bleHeltec_Wireless_Tracker_companion_radio_bleEbyte_EoRa-S3_companion_radio_ble(true no-GPS build)WioTrackerL1_companion_radio_usbWioTrackerL1_companion_radio_bleNano_G2_Ultra_companion_radio_bleMeshTracker_X1_companion_radio_bleThinkNode_M1_companion_radio_blet1000e_companion_radio_ble
Known pre-existing failure: Heltec_mesh_solar_companion_radio_ble fails to build on unmodified main with the same meshsolar/logger.h errors (verified against baseline 75b04ef). It is unrelated to this change.
Field validation
The firmware was validated in real-world testing. The Seeed Studio Wio Tracker L1 Pro serial and Bluetooth builds were produced and used for that testing.
Review
A fresh-context whole-branch review was run on Claude Opus. One important finding — three GPS-capable variants did not expose their LocationProvider, which would have made the feature silently return "no fix" on those boards — was fixed, and the full suite and affected builds were re-run green.
Documentation
docs/payloads.md: request type0x0A, its request fields, and the position response fields.docs/companion_protocol.md:CMD_SEND_BINARY_REQ(50),PUSH_CODE_BINARY_RESPONSE(0x8C), theRESP_CODE_SENTreply, and compatibility/error behavior.
The additive SensorManager virtual follows the precedent of isGPSDetected() (commit 8a418faf), which did not require a README or library.json version bump.
References, tools, agents, and models
References
- MeshCore source:
src/helpers/sensors/LPPDataHelpers.h(LPP_GPS, 24-bit),src/helpers/SensorManager.h,src/helpers/sensors/LocationProvider.h,src/helpers/BaseChatMesh.cpp,examples/companion_radio/MyMesh.cpp. docs/payloads.md,docs/companion_protocol.md,docs/number_allocations.md,CONTRIBUTING.md.- CayenneLPP
LPP_GPSencoding: 3-byte lat/lon at 0.0001°, 3-byte altitude. - Issue-tracker search found no existing implementation; the only related item was a stale, auto-closed request to add GPS accuracy to telemetry (Add GPS accuracy to telemetry #2179).
Tools
- PlatformIO Core 6.2.0 (user Python venv), googletest 1.17.0.
- Apple clang 21 (host tests), arm-none-eabi-gcc 14.2.1 (nRF52), espressif32 toolchain, esptool 4.5.1.
ghCLI for repository operations.- Claude Code for implementation and review orchestration.
Agents and models
- Claude Code implementation session (model reported by the harness:
deepseek-flash[1m]). - One fresh-context design-review subagent (general-purpose, session default model).
- One fresh-context whole-branch code-review subagent on Claude Opus.
- Process skills: brainstorming, writing-plans, executing-plans, test-driven development, verification-before-completion, requesting-code-review, and finishing-a-development-branch.
Upstream process
Per CONTRIBUTING.md, a [Feature request] issue will be opened against meshcore-dev/MeshCore before any upstream PR. This PR merges the same work into the fork's main and provides the content for that issue. The upstream PR, when opened, will be branched from dev and will reference the issue.
Checklist
- One feature / one PR
- Descriptive commit messages
- Host tests added and passing
- Firmware builds verified
- Documentation updated
- Backward compatible; existing commands unaffected
- No unrelated changes
- Upstream issue reference (pending; issue to be opened first)
Developed with the heavy-handed help of AI, without which this would have remained an idle daydream for me.
Activity