Repository navigation
20. Geocaching Developer Guide
Trail Mate Geocaching exchanges author-signed location records over Reticulum and LXMF. Devices can save verified records and GPX files for offline use. The web map queries reachable directories at runtime; cache records are not bundled with the website. Publishing or updating a cache does not require rebuilding GitHub Pages.
This guide describes the implemented version 1 protocol. Source references use main, which also supplies the deployed browser tools. A reachable TCP transport node is not necessarily a geocaching directory, and a connected WebSocket is not proof that a directory query succeeded.
Version 1.0.0 adds browser maintenance of device-authored caches. USB proves the device author identity and supplies authorized signatures; the browser uses the computer's Reticulum connection to publish, update or archive, verifies the directory result, and confirms it on the device. The device's selected chat/RF protocol does not gate these Web network operations.
Keep pending confirmation visible and continue its existing publication rather than silently creating another cache. The release record records the completed Wio L2 workflow and its hardware scope. See 22. Web Device Management for connection/configuration and 23. Device Identity and Sharing Privacy for what becomes public.
Current production UI after create/update/archive through a native loopback directory, using a synthetic USB author with real signatures. This illustration does not add a public publication or physical-device acceptance result.
In My caches, open the cache, save any edits, select Archive cache, and
confirm the signed publication. The device retains the local copy and publishes
a new revision with state 2 (Archived), using the original author identity.
Archive not confirmed means the local draft or publication still awaits a
directory confirmation; reopen the cache and select Archive to retry.
Delete local cache removes only the device copy and does not withdraw a
publication.
Archived is a terminal state under the version policy. Directory implementations must apply the signed revision and exclude archived records from active results. This does not erase signed history, offline downloads, or copies in independent directories that have not received the update.
| Your application | Implement |
|---|---|
| A reader or map | Discovery, capabilities, spatial query, full-record retrieval and signature verification |
| A publisher | Record encoding, author identity persistence, signing, publish requests and durable response handling |
| A public directory | All five operations, authenticated LXMF delivery, durable records and request deduplication |
| A directory replica | Synchronization, exact-revision retrieval, verification and durable cursor advancement |
| An offline viewer | GPX parsing, embedded signed-record verification and local indexing |
Start with Wire Format and Signed Records. It defines the byte representation shared by all integrations.
Then follow Discovery and Directory Operations for request and response schemas, pagination, publication acknowledgements and replica synchronization.
Use Integration Examples and Conformance for a runnable reference round trip, and GPX and Offline Storage for export parsing and device persistence.
Operators should continue with Directory Deployment and Verification, including the distinction between static application hosting and live service operation.
sequenceDiagram
participant A as Author
participant D as Public directory
participant W as Browser or device
participant S as Device SD storage
A->>A: Encode and sign immutable revision bytes
A->>D: LXMF publish request
D->>D: Authenticate, verify, persist and commit
D-->>A: Application response with matching request ID
D-->>W: Signed discovery announcement
W->>D: Capabilities request
D-->>W: Compatible directory capabilities
W->>D: Spatial query
D-->>W: Summaries and continuation cursor
W->>D: Get exact revision named by summary
D-->>W: Signed record and current/conflict flags
W->>W: Verify author signature and summary consistency
W->>S: Save signed details, GPX and local index
Directory summaries are search results, not substitutes for signed full details. Before showing a detail as verified, validate the full record and ensure its identifier, revision, hash and summary fields agree with the selected result. A directory can omit records or become unavailable even when author signatures are valid. Signatures establish authorship of the bytes, not the physical truth of a location.
GitHub Pages serves the application, geographic boundaries, icons and operator connection configuration. The browser creates a Reticulum/LXMF instance in a worker and exchanges live messages through a WSS packet bridge. The bridge forwards Reticulum packets; it is not a static cache catalogue or an HTTP replacement for the protocol.
Browser applications cannot use the device's native TCP interface directly. The operator must provide a reachable WSS endpoint compatible with the raw-packet framing used by packet_bridge.py. Visitors do not configure TCP hosts or WSS URLs. The checked-in configuration currently references a temporary tunnel; it is not a verified permanent public service.
Deploying new application code is different from publishing data. An author publishes over LXMF to a directory. A later browser search queries that directory and obtains the new data without a site deployment. Discovery and replication are asynchronous, so this does not imply immediate global visibility. The web map covers reached directories, not a complete inventory of all caches on Reticulum.
Connection failures must remain visible. The web client has no deployed-record fallback. It clears displayed results after disconnection, validates directories again after reconnecting, and issues a fresh query. A failed initial capability check must not permanently suppress future announcements from the same directory.
Downloaded browsing reads the installed index in bounded pages. It does not need a live directory and should not load every GPX file to render a list. Full signed content remains available when opening saved details. GPX carries the description and hint as well as the waypoint coordinates.
Storage recovery handles unfinished installation and publication operations. A finalized installation has a durable cleanup marker so subsequent startup does not repeatedly recover the same completed operation. Legacy records may require migration; absence of new index metadata is not permission to discard existing saved data.
Saving an already verified open detail reuses those verified bytes instead of issuing another network retrieval. Persistence still validates the stored content. Download changes invalidate the relevant saved list; they do not invalidate unrelated publication state.
| Concern | Implementation |
|---|---|
| Browser protocol parsing and verification | protocol.js |
| Live discovery, queries and retries | protocol-client.js |
| Directory transaction and operation semantics | directory_store.py |
| LXMF authentication and service lifecycle | directory_service.py |
| Replica scheduling | directory_sync.py |
| Browser packet bridge | packet_bridge.py |
| Native runtime and local storage lifecycle | Runtime documentation |
Diagnose each layer separately: transport connection, discovery announcement, authenticated capabilities response, query response, full-record verification, then local installation. LXMF delivery confirmation alone does not establish that the directory accepted or committed a publication. A connection indicator alone does not establish any application-level success.