implement-configprotocol

name	implement-configprotocol
description	Implement gpsprot high-level (device-independent) configuration - the ConfigProtocol/Configurator - for a new GPS receiver protocol family

Implementing high-level configuration for a GPS protocol

This skill captures what was learned implementing the CASIC configurator (#229, the third configurator after ubx and unc) and the Allystar configurator (#344, the fourth): the semantics rulings the project owner handed down, the protocol questions that dictate the design, the verification ladder, and the working process. Read it before designing anything; most of it was learned by getting it wrong first.

The owner's eventual goal (not yet reached): plug in a receiver with the Markdown documentation for its protocol, and an agent brings up the ENTIRE stack - message files, packet library, packet processor, configurator, characterization - to full support. Every owner intervention a session still needs marks a gap in this skill or in the governing contracts; capture it so the next bring-up needs one intervention fewer.

The one rule that governs everything

gpshwtest/SEMANTICS.md defines what high-level configuration means independently of any receiver. Every guarantee in it is binding on every backend: truthful achieved values and readback, refusal leaves configuration unchanged, nonexistence shown not announced, requested information delivered. There is no such thing as an acceptably device-dependent semantic detail. When tempted to deviate "because this receiver works differently", re-read rulings.md first - the temptation has come up before and the owner has ruled on it.

Scope: configuration only, not message processing

This skill implements the CONFIGURATOR - the high-level configuration knobs (message enable/disable, output modes, rates, survey, speed, NVM save/reload). Enabling any message the protocol offers is in scope. What is OUT of scope is message PROCESSING: the lib-layer decode and the domain-layer conversion to gpsprot.Msg.

• PREFER enabling messages the stack already processes (a lib struct plus the gpsprot.Msg conversion that consumes it). When a configuration option can be satisfied by more than one message, choose one that is already processed.
• You MAY still enable a message whose processing is not yet implemented
  • that is configuration. But do NOT implement its processing here. Call the processing out as separate work on its own branch; this change only enables the message. "Nothing implementable is out of scope" governs configuration, not processing - see rulings.md.

What transfers between protocols and what does not

The DESIGN of an existing configurator does not transfer. casic's single request type with orthogonal capabilities, ubx's step roster, unc's command repetition - each shape was dictated by its protocol's properties (response correlation, ACK guarantees, NAK information content, line budget). Study ubx and unc to learn the ConfigDirector CONTRACT, then derive the new design from the new protocol's answers to protocol-questions.md. The owner's bar is "a beautiful elegant implementation", judged against the existing configurators; elegance comes from fitting the protocol, not from copying a previous shape.

The crucial architectural choice, decided explicitly before coding (owner directive from the Septentrio bring-up): how to represent the receiver's internal configuration state. It affects the whole implementation. Representations used so far: ubx new style uses the config keys/values; ubx old style uses the messages the receiver returns to configuration queries; unc stores the command strings that produce the state and diffs them to generate updates (Unicore read-modify-write regenerates whole commands); Septentrio stores typed per-item reply state lines in the receiver's own vocabulary, updated identically by query replies and set acks (its CLI is symmetric and omitted arguments keep their current value, so the receiver merges partial sets and no command diffing is needed). Record the chosen representation, the options considered, and why, in the plan and the final report.

What does transfer:

• The inputs the owner must provide and the lower stages that should exist first (verified message files, packet library, processor): inputs.md
• The semantics contract and the owner's rulings: rulings.md
• The design-shaping questions to answer on hardware before committing to a design: protocol-questions.md
• The ConfigDirector contract knowledge that is not (yet) in the gpsprot doc comments: director-contract.md
• The verification ladder and evidence standards: verification.md
• The working process, loop artifacts, and operational gotchas: process.md

Process in one paragraph

Work on a dedicated feature branch; tooling/framework changes (gpshwtest, shared libraries) go on their own branches that land independently - never merge one into the other and never mix concerns in one commit. Start from a staged plan whose stage 0 resolves the design-shaping unknowns on real hardware; do not trust vendor documentation. Run as a loop of bounded, committed, verified increments with PROGRESS.md as compaction-proof memory. Verify up the ladder: offline fake-receiver tests through the real director path, replay tests with committed hardware traces, then gpshwtest characterization to green committed baselines. Implement every CONFIGURATION the protocol offers - nothing configurable is out of scope - preferring messages the stack already processes, and defer message DECODE (not the enabling) to a separate change (see Scope above). Show what the receiver cannot do as absence, never as an error.