Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr
- A parameter value SAYS WHICH SCALE IT IS ON (ADR-0016). Every knob has two number lines: the screen's, which differs per knob, and the device's, which is 0..1 for all 3,809 of them. `set_param` takes one value and it must be typed - `Real` for the screen's line, `Db`/`Hertz`/`Percent`/`Milliseconds`/`Seconds`/`Semitones`/`Cents`/`Bpm` to name the unit and have it checked against the catalog, `Encoded` for the device's line, and a bare string for a string parameter. A bare number is REFUSED, because on a lane VOLUME `Real(0.0)` is unity and `Encoded(0.0)` is silence and nothing in a plain `0.0` says which was meant. `Encoded` stays accepted everywhere and is NEVER advertised where a unit type would serve. Two source-reading tests hold that, and between them they say exactly how far it reaches: `tests/test_examples.py` covers `examples/`, and `tests/test_docs.py` covers the code blocks inside docstrings. Each use must carry a written reason nearby. NOT covered, deliberately: prose in `docs/`, which needs judgement rather than a regex, and the error messages that OFFER `Encoded` to a caller who has just been refused - that is the message's job. `values.py` is exempt because it is where the two scales are defined against each other. Only `Encoded` works with no device attached, since the other two need the catalog. This is protocol-layer work on purpose - the translation boundary governs coordinates this library CHOOSES (rows 1-4, scene letters), not units the device PUBLISHES.
- EVERY method that writes a value takes a typed one, not just `set_param` (ADR-0017). The settings are not catalog models, so the scale comes from somewhere else - and there are three cases, which must not be blurred. A wire 0..1 with a KNOWN scale (an input port's GAIN, -12..+60 dB; a Global EQ band's GAIN, -12..+12 dB - and those are NOT known equally well, see below) takes the unit type and converts, through a real `catalog.Parameter` so it gets the one law rather than a private copy. A wire 0..1 with NO known scale (output level, USB level, master volume, Global EQ frequency/Q/OUT level, a Global EQ index) takes `Encoded` only, and a `Real` raises `ControlNotDrivable` naming what would settle it - never an invented span. A setting with no 0..1 line at all (the HOLD threshold in ms, the tuner offset in Hz) refuses `Encoded`, because the wire carries the real number. `units.SETTING_SPANS` holds the two known spans WITH how well each is known, and they differ: four measured points against the manual plus two. SELECTORS are not values and stay plain - impedance, input type, ground lift, hp_select, dry_wet, filter type, mute and bypass take an enum or a bool.
- A generated parameter constant CARRIES ITS UNIT in its type (ADR-0018), so a type checker rejects `set_param(LaneOutputParam.VOLUME, Hertz(217))` before it runs. mypy is a BLOCKING CI job over the whole package, with ONE suppression in the whole config (`ignore_missing_imports` for `hid`, which ships no stubs) - the ~195 phantom errors from the generated bindings are fixed by committing `*_pb2.pyi` stubs emitted in the same protoc run. `scripts/compile_protos.sh` refuses to write bindings without them AND rewrites their cross-references package-relative: protoc emits `import Preset_pb2` flat, the bindings survive that through the sys.path shim in `proto/__init__.py`, and a type checker cannot - so every field carrying a `Preset` type would read as `Any` while mypy reported success. `tests/test_packaging.py` holds both halves. The runtime check is unchanged and still covers every other caller. What is easy to break: `set_param`'s three overloads. A `Param` IS an `int`, so an int overload that accepts real values swallows every wrong-unit call - overload resolution takes the first MATCH and a failing first overload falls through. The int overload therefore takes only `Encoded`, a string or a switch, which makes `set_param(target, 21, Real(3))` a static error although it runs; address by index and say `Encoded`, or name the parameter. `tests/test_typing.py` holds both directions and is mutation-tested, because a checker that stops catching things stays green and one that cries wolf gets turned off.
- A connection resolves a DEVICE PROFILE before the handshake (ADR-0020; the rule is decided, the seam is not built yet): `device_type` plus `zenos_git_hash` from the unit's own `Version` reply, looked up in a registry of measured profiles. An unknown pair REFUSES to connect; there is no fallback to the nearest profile, and `profile=` is the deliberate way to measure an unmeasured unit. Everything that differs by firmware or model lives on the profile - the generated constants snapshot, the announce string, the hardware facts, the operations measured to differ - and no other module tests a version string. A profile that has not measured an operation refuses it with `ControlNotDrivable` whose evidence says so. Name a profile by CorOS version, never by `app_fw`: a contributor reports d14e on 4.1.0 as well as 4.0.1 (PR #44). Until the seam is built, `protocol.models`/`params`/`options` mean the QC 4.0.1 snapshot, and an observation from another profile goes BESIDE the 4.0.1 record in `docs/protocol.md`, dated and named, never in its place. `version()` accepts only a `Version` carrying an identity field (serial or firmware) because the unit answers a `Version` READ twice and `request()` cannot tell the full reply from the device's own READ; a PARTIAL reply is still accepted, because the per-field cache rule owns incomplete answers.
- Docstrings state their evidence: confirmed on hardware vs inferred from the schema. When you verify something on hardware, record it (docstring + coverage table) in the same change.
- The frame trailer's two flag bytes are REPORTED, and never decide what happens to a payload (ADR-0019). `framing.decode_reports` returns a `Frame` naming all of it: type, `encrypted` (`n+4`), `compressed` (`n+5`), `device_bytes` (`n+6`, still meaningless). Compression is detected by the gzip magic bytes and NOT by the flag - CortexUSB reads the flag and needed a skip-list for types 32 and 33 to make it work, which is the argument. The RX path does compare the two and logs a line when they disagree, because the 15675/15675 agreement was measured on CorOS 4.0.1 only and a firmware that broke it must not do so quietly. And nothing here decrypts: an encrypted payload gets labelled and dropped, because the messages behind that flag are `License` and `CloudLogin` and the key derivation would be reimplemented from someone else's MIT source. Both flags describe the FRAME, not the type - a `License` READ is unflagged and its reply is encrypted - so never key either one off a message type. Wanting the decryption means reopening ADR-0019, not adding coverage.
- Code in the RX path preserves "the RX thread never dies": wrap every decode, skip unknown types at debug level, reset the reassembly buffer on anything malformed.
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ with it.
## Status

**Working, and verified on real hardware** on macOS (Apple Silicon) and Windows,
against **CorOS / Cortex Control 4.0.1** (device firmware `d14e`). Every
against **Quad Cortex, CorOS / Cortex Control 4.0.1** (device firmware `d14e`),
the one device profile measured so far (ADR-0020 in `docs/ADR.md`). Every
operation listed below has been exercised on a physical unit. The test suite runs
fully offline, with no device attached.

Expand Down
22 changes: 22 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,28 @@ correction.

## Unreleased

### The repo describes device profiles, not one baseline (ADR-0020)

A profile is what the unit reports in its `Version` reply: `device_type` and
`zenos_git_hash`, the CorOS version. Everything that differs by firmware or
model will live on the profile, connect will resolve it before the handshake,
and an unknown profile will refuse to connect rather than borrow the nearest
one. This entry records the rules; the seam is the next piece of work. No code
branches on a version string yet, and `protocol.models`, `params` and `options`
still mean the Quad Cortex 4.0.1 snapshot. See `docs/ADR.md`.

### `version()` no longer answers with the unit's own question

The unit answers a `Version` READ twice: the full reply, and 1 ms later its own
`Version{READ}` carrying `action` alone. `version()` waited by message type, so
two calls close together alternated between them - full, empty, full, empty -
and a caller reading `custom_name` or the serial got `""` every second time
with no error. It now accepts only a `Version` carrying an identity field, the
serial or the firmware, so the unit's question is never returned as the answer.
A partial reply carrying one of the two is still returned; the state cache
keeps what the unit sent and re-reads for the rest. Measured on Quad Cortex,
CorOS 4.0.1 / d14e.

### You can read back which expression pedals are assigned

`set_expression` could always write an assignment. Nothing could read one back:
Expand Down
7 changes: 5 additions & 2 deletions contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,11 @@ If your change touches the live device path and you want to verify it on a real
- **Quit Cortex Control first.** It holds the USB interface exclusively, so nothing
else can talk to the device while it is running.
- The device protocol is **unversioned** and can change across CorOS / Cortex Control
updates. This library is verified against **4.0.1** (firmware `d14e`); if you are on
a newer version, re-verify the framing and schema before assuming a bug.
updates. This library is verified against **Quad Cortex, CorOS 4.0.1** (firmware
`d14e`); if you are on a newer version, re-verify the framing and schema before
assuming a bug. A different firmware or a Mini is a different DEVICE PROFILE
(ADR-0020): record what you measure beside the 4.0.1 record in `docs/protocol.md`,
dated and named by CorOS version, rather than in its place.

When you confirm behavior on hardware, say so in the pull request: which operation,
which CorOS version, and how you verified it (a read-back, or watching the unit).
Expand Down
29 changes: 29 additions & 0 deletions docs/ADR.md
Original file line number Diff line number Diff line change
Expand Up @@ -339,3 +339,32 @@ Records are append-only once `Decided` and built upon: a shipped decision is nev
- The trailer offsets live in named constants (`TRAILER_TYPE`, `TRAILER_ENCRYPTED`, `TRAILER_COMPRESSED`, `TRAILER_DEVICE`) so a test can pin them separately from the code that reads them.
- `encode_message` writes the same bytes it always did. The host sets neither flag and fills neither device byte.
- Anyone who later wants (b) has to reopen this record rather than add it as coverage.

## ADR-0020: Connect resolves a device profile, and nothing else branches on firmware or model

- **Status:** Decided (2026-09-03)
- **Decision:** A connection resolves a **device profile** before the handshake, from two fields of the unit's own `Version` reply: `device_type` (QC, or ATMA - the Quad Cortex Mini, inferred from the schema's `atma_*` field names; no Mini has reported it yet) and `zenos_git_hash` (the CorOS version string). The pair is looked up in a registry of profiles this library has measured. A known pair builds the client and the model for that profile and then runs the handshake with that profile's announce string. An unknown pair **refuses to connect** with an error naming what the unit said. There is no fallback to "the nearest profile". A caller who wants to measure an unmeasured unit passes `profile=` explicitly, and that fails if the unit is not that profile. Everything that differs by firmware or model lives on the profile: the generated constants snapshot, the announce string, the hardware facts, and the operations measured to behave differently. No other module tests a version string.
- **Context:** The library was built against one unit: Quad Cortex, CorOS 4.0.1, app firmware d14e. `docs/protocol.md`, `docs/STEERING.md` and `QuadCortex.CC_VERSION` all name that one baseline, and the protocol carries no version number, so nothing on the wire says when a statement stops being true. Two contributions in September 2026 pushed on that. PR #31 opened the Mini over USB with the same client, although the Mini has four footswitches where the client assumes eight (product page, and the maintainer's review on PR #31), and the client has controls (`set_stomp_momentary`) the Mini does not. PR #42, since split into PR #44, regenerated the model catalog from a CorOS 4.1.0 unit, which renamed seven public constants, removed eleven option enums, changed the members of a kept one, and added eight model ids that a 4.0.1 unit does not have. The maintainer's unit stays on 4.0.1 until the Domain Model work is done, so neither contribution could be verified on the unit that defines the baseline, and merging either would have failed the hardware suite on that unit. The plan the maintainer wants is support for several units at once: Quad Cortex 4.0.1, Quad Cortex 4.1, and the Mini, each measured on its own hardware.
Verified while writing this record: `VersionMessage.DeviceType` has exactly two values, `QC = 0` and `ATMA = 1` (`protocol/proto/ProductionAutomation.proto:116-119`); `zenos_git_hash` reads `"4.0.1"` on the maintainer's unit; a `Version` READ is answered before the handshake (`qcctl version` uses that path and ran today); the recovered schema already carries fields named for the Mini (`Mode.atma_page`, `AtmaPowerOnMode`, `atma_looper_lock_mode`); that they ARE the Mini's is inferred from the names, because Cortex Control serves both units from one schema.
- **Options:**
- **(a) One profile per measured unit, resolved at connect, refusing the unknown - chosen.** Cost: a registry, a seam in `connect()`, and one class per profile. Benefit: every statement about the wire has a named owner, and a unit nobody measured cannot be driven by accident.
- **(b) Track the newest firmware and let older units fall behind.** Simplest. Rejected: the maintainer cannot measure the newest firmware, so "tracking" would mean committing constants and behaviours nobody with a unit can check. It also breaks the hardware suite on the only unit that runs it.
- **(c) One client with version checks scattered where behaviour differs.** Familiar shape, cheap to start. Rejected: a table of `if version == ...` is the "rule about parameter types" this repo already learned from (`LANE_OUTPUT_UNASSIGNABLE` had three plausible rules and all were false). Differences must be measured per profile, and a scattered check invites a guess.
- **(d) Read everything from the live catalog and ship no generated constants.** The device does publish its own catalog at connect. Rejected as the whole answer: the constants are what make an index-addressed write free of a catalog fetch and what let a type checker reject a wrong unit (ADR-0018). The live catalog is kept as the check, not the source of the constants.
- **(e) Fall back to the closest known profile when the pair is unknown.** Rejected by the maintainer, as on PR #31: a client that connects to something it was not designed for and then fails silently is worse than one that refuses. Refuse, and let `profile=` be the deliberate way in.
- **Open Questions:**
- Whether `app_fw_version` is `d14e` on CorOS 4.1.0 as well. The contributor reports so. If true, the app firmware string cannot distinguish the two and profiles must key on `zenos_git_hash`, which this record already does. Unverified by the maintainer.
- The Mini's USB product id and CorOS numbering. PR #31 reports a different product id; no Mini has been measured. `open_device()` still opens product `0x880A` only, so a Mini does not even enumerate today. The Mini profile exists in the registry as "unmeasured, refused" until an owner measures one.
- Whether a future Mini firmware needs its own schema bindings. The recovered schema covers both units today. A profile can carry its own bindings module if a measurement ever demands it; nothing is built for that until then.
- What "measured" means for a profile the maintainer cannot verify. Proposed: the registry records an evidence level per profile, the way `units.SETTING_SPANS` records how well each span is known, so "contributed, not verified by the maintainer" is a stated fact rather than an omission.
- **Rationale:** The unit says what it is before the handshake, so the library can know before it acts. That is the whole argument for resolving at connect. Putting every difference on the profile, rather than where the difference is felt, keeps the rule from `CLAUDE.md` intact: a control we understand but cannot drive refuses, and a control we do not understand is omitted. A profile that has not measured an operation refuses it with `ControlNotDrivable` whose evidence says "not measured on this profile". That is the existing refusal applied to a new axis, not a new mechanism.
Model and firmware are two axes, and they do not need the same treatment. The model decides hardware facts and schema: footswitch count, controls that exist, a different USB product. The firmware decides the catalog snapshot, the announce string and the wire behaviours that were measured to differ. But both resolve through one seam, so there is one place to look. Profiles are concrete, one per unit somebody has measured, not a matrix of flags. A shared base holds every wire shape the schema makes identical; a profile overrides where it was measured to differ.
Namespacing the generated constants under the profile dissolves the rename problem that PR #42 surfaced. A 4.1 snapshot can ship with 4.1 names without changing what a 4.0.1 user imports, and the unversioned names keep meaning the maintainer's baseline until a later record moves them.
- **Consequences:**
- `protocol.connect()` and `pyquadcortex.connect()` gain a profile step: open, read `Version`, resolve, build, handshake. `version()` must never hand back the unit's own `Version{READ}` for this to be safe; until this change it could, because the unit answers a READ with the full reply and then asks its own question 1 ms later (recorded in `protocol.md`, "A `Version` READ is answered twice"). Fixed in the same change as this record: it accepts only a reply carrying an identity field, and a partial reply carrying one is still returned, because the cache's per-field rule owns incomplete answers.
- The generated snapshots move under a per-profile namespace. `protocol.models`, `protocol.params` and `protocol.options` keep pointing at the QC 4.0.1 snapshot until a record says otherwise. A connected client exposes its own profile's snapshot, so code written against the connection cannot pick up the wrong one.
- `set_block` checks the model id against the live catalog before sending. Today it sends any id and a refusal from the unit is reported as a DSP or port problem. That check is correct on its own and lands independently of the profile work.
- The hardware suite exposes the connected profile as a fixture. `tests/hardware/test_generated_constants.py` compares against that profile's snapshot, not "the" snapshot. A test with no measurement for the connected profile skips with a reason that names the profile.
- `docs/STEERING.md` and the `docs/protocol.md` header stop naming one baseline and name profiles with evidence levels. Every observation in `protocol.md` says which profile it was measured on. A 4.1 observation is written beside the 4.0.1 record, dated, never in place of it.
- Contributed profiles are welcome, and they arrive as one registry entry, one snapshot, and observations tagged with their profile. The seam, the refusal rule and the evidence levels are the maintainer's to write, because they encode what "supported" means here.
- Reversal is cheap until the second profile ships and expensive after: once code depends on `qc.models` meaning "my profile's snapshot", collapsing back to one namespace breaks every such caller. That is the one-way door this record closes.
Loading
Loading