mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-10-07 02:57:21 +00:00
93 lines
4.5 KiB
Markdown
93 lines
4.5 KiB
Markdown
# Packet Probe
|
|
|
|
## Purpose
|
|
|
|
Packet Probe replaces the former RSSI-oriented Energy Sweep page. Its question is
|
|
not whether a frequency range contains energy. It asks whether an active Trail
|
|
Mate air protocol can be observed on a concrete set of LoRa air parameters.
|
|
|
|
The internal application id and source directory stay `energy_sweep` for
|
|
navigation and migration compatibility. The user-facing name is `Packet Probe`.
|
|
|
|
## Evidence Contract
|
|
|
|
An observed profile is created only when all of the following are true:
|
|
|
|
1. The radio reports RX_DONE and provides a packet that has passed the radio
|
|
CRC path.
|
|
2. The receiver was configured with the candidate frequency, bandwidth,
|
|
spreading factor, coding rate, preamble, sync word, and CRC length.
|
|
3. The packet has passed a structural parser for the active protocol:
|
|
Meshtastic wire framing or MeshCore packet framing.
|
|
|
|
The page displays the profile and its evidence-packet count. It deliberately
|
|
does not expose business-packet labels such as position, node info, or telemetry.
|
|
No simulator path may produce evidence packets. A candidate with no evidence is
|
|
not a negative finding; it means only that the current dwell did not observe one.
|
|
|
|
The first version's evidence level is radio CRC plus structural protocol
|
|
validation. It is a strong discovery signal but is not authenticated proof of a
|
|
channel key. A future evidence-level upgrade can use the active adapter's full
|
|
decrypt/MAC validation while preserving the same UI result model.
|
|
|
|
## Candidate Plan And Timing
|
|
|
|
Candidates are generated from the active protocol's regional frequency span and
|
|
currently active LoRa parameters. The center frequencies are quantized to 25
|
|
kHz, limited to 96 candidates, and adjusted to keep the configured bandwidth in
|
|
the regional range.
|
|
|
|
Each candidate receives a 700 ms dwell. A typical 70-candidate pass is about 49
|
|
seconds before radio retuning overhead. One valid packet is an immediate positive
|
|
result. Multiple passes increase coverage for intermittent traffic, but the UI
|
|
must never label a silent candidate as absent or unused.
|
|
|
|
## Radio Ownership And Apply Flow
|
|
|
|
The probe obtains the exclusive LoRa runtime only while scanning. On each
|
|
RX_DONE it copies the packet into caller-owned scratch storage, clears IRQ flags,
|
|
and restarts reception. Leaving, stopping, or applying releases the runtime and
|
|
returns the radio to mesh ownership.
|
|
|
|
Applying a selected result is an explicit two-step action:
|
|
|
|
1. The user selects an observed profile and opens the confirmation dialog.
|
|
2. On confirmation, the page stops probing, releases the temporary radio
|
|
session, updates configuration in a `beginConfigEdit()` transaction, commits
|
|
`AppConfigChangeSet::mesh()`, then calls `applyMeshConfig()`.
|
|
|
|
Meshtastic is switched to manual modem parameters with the observed center
|
|
frequency as its override and zero frequency offset. MeshCore switches to its
|
|
custom region values with the observed frequency, bandwidth, SF, and CR.
|
|
|
|
## Hardware Capability Model
|
|
|
|
| Radio | Current implementation | Result |
|
|
| --- | --- | --- |
|
|
| SX1262 | One frequency/BW/SF/CR receive configuration at a time | One single-SF lane scans candidates serially. |
|
|
| LR1121 | The IC supports Multi-SF in its datasheet, but local RadioLib 7.4 integration exposes only normal single-profile receive and no packet-to-SF attribution API | The first release intentionally uses the same one-lane model. |
|
|
|
|
The probe scheduler is profile-based so a future LR1121 POC can add a second
|
|
same-frequency/BW SF lane. Enabling that needs all of the following real-device
|
|
proof: RadioLib configuration support, RX_DONE packet retrieval for both SFs,
|
|
and reliable attribution of each received packet to its SF. Until then the UI
|
|
and evidence count make no multi-SF claim.
|
|
|
|
## Pager UI Specification
|
|
|
|
The 480x222 Pager page follows the Map page language:
|
|
|
|
- A 30 px amber top bar titled `PACKET PROBE`.
|
|
- An unframed, full-width work area containing the observed-profile list only.
|
|
The selected row is highlighted in place; there is no repeated detail panel,
|
|
which keeps the page viable on T-Deck-class narrow displays.
|
|
- Observed rows show `frequency`, `BW/SF/CR`, and `x evidence-count` only.
|
|
- A 24 px Map-style bottom bar: `UP/DN Select`, `ENTER Set`, `S Start/Stop`,
|
|
and `ESC Back`.
|
|
- Selecting `Set` opens a dimmed warm-white modal. `Cancel` is the default
|
|
focus; `ESC` cancels and `ENTER` applies after the user has moved focus to
|
|
Apply.
|
|
|
|
The page has no RSSI graph, CAD badge, noise estimate, quietest-channel score,
|
|
or AUTO action. Those measurements cannot establish protocol-channel presence.
|