Skip to content

feat: add precise position request (REQ_TYPE_GET_POSITION 0x0A) #3873

Open

Description

@ghstwhl

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 0x0A handled in MyMesh::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.
  • PositionData codec (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 by EnvironmentSensorManager and 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.md and docs/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/else blocks to a shared resolver. The resolver returns exactly the same bits for ALLOW_ALL, ALLOW_FLAGS, and DENY, and the full existing host suite still passes.
  • SensorManager::isLocationActive() is additive, with a safe false default. Existing managers that do not override it are unaffected. The three added getLocationProvider() overrides expose a provider those managers already owned; this also makes the pre-existing gps sync / gps diag CLI 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_REQ exists since companion v1.10.0).
  • 0x0A was unused anywhere in the tree. An out-of-tree listener that had privately claimed 0x0A would 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_loc plus 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 and INT32_MIN/INT32_MAX coordinates 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_FLAGS with 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_ble
  • heltec_tracker_v2_companion_radio_ble
  • Meshadventurer_sx1262_companion_radio_ble
  • Heltec_Wireless_Tracker_companion_radio_ble
  • Ebyte_EoRa-S3_companion_radio_ble (true no-GPS build)
  • WioTrackerL1_companion_radio_usb
  • WioTrackerL1_companion_radio_ble
  • Nano_G2_Ultra_companion_radio_ble
  • MeshTracker_X1_companion_radio_ble
  • ThinkNode_M1_companion_radio_ble
  • t1000e_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 type 0x0A, its request fields, and the position response fields.
  • docs/companion_protocol.md: CMD_SEND_BINARY_REQ (50), PUSH_CODE_BINARY_RESPONSE (0x8C), the RESP_CODE_SENT reply, 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_GPS encoding: 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.
  • gh CLI 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions