Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
c416e39
Add preset screenshot support
tony-xmelon Sep 3, 2026
30af967
Add physical screen control and capture
tony-xmelon Sep 3, 2026
2c2ad6d
Make screenshot validation claims exact
tony-xmelon Sep 3, 2026
4de8690
Harden remote screen coverage
tony-xmelon Sep 3, 2026
f1f4e5e
Gate screenshot hardware coverage by firmware
tony-xmelon Sep 3, 2026
d7ca426
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 5, 2026
9ec95c6
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 5, 2026
c4cce6a
Merge upstream device profiles into preset screenshots
tony-xmelon Sep 7, 2026
43c9c1b
Merge upstream device profiles into remote screen control
tony-xmelon Sep 7, 2026
0225625
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 8, 2026
644d4d4
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 8, 2026
55a0350
fix: scope preset screenshots to CorOS 4.1
tony-xmelon Sep 8, 2026
1762dda
fix: scope remote screen control to CorOS 4.1
tony-xmelon Sep 8, 2026
47056da
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 9, 2026
7c5f1db
fix: address remote screen review
tony-xmelon Sep 9, 2026
e552790
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 12, 2026
4dc6c03
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 12, 2026
923eaef
Add complete CorOS 4.1 remote screen surface
tony-xmelon Sep 14, 2026
051cbe6
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 19, 2026
ce1c869
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 19, 2026
2be9d1c
Follow documentation typography rules
tony-xmelon Sep 19, 2026
cae5929
Fix coverage and documentation checks
tony-xmelon Sep 19, 2026
bd15ef4
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 22, 2026
8bd4129
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 22, 2026
6b5d803
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 22, 2026
b70ae2d
Merge remote-tracking branch 'upstream/main' into codex/remote-screen…
tony-xmelon Sep 22, 2026
8425260
Route preset screenshot through profile support
tony-xmelon Sep 26, 2026
e417162
Narrow remote screen PR to capture and tap
tony-xmelon Sep 26, 2026
8abdbab
Skip empty preset slots in screenshot hardware test
tony-xmelon Sep 26, 2026
1cdf2ef
Make CorOS 4.1 hardware verification profile-aware
tony-xmelon Sep 26, 2026
e9255a0
Stack live screen fallback on remote control PR
tony-xmelon Sep 26, 2026
f2b3f81
Integrate screen-control fixes and capture loaded empty slots
tony-xmelon Sep 26, 2026
6ea43dc
Document empty-slot screenshot fallback
tony-xmelon Sep 26, 2026
ed259e5
Capture the live screen for empty preset slots
tony-xmelon Sep 26, 2026
3bbd823
Report guarded base operations as unverified
tony-xmelon Sep 27, 2026
781d57d
Capture the live screen for empty loaded slots
tony-xmelon Sep 27, 2026
d183668
Capture live screen for loaded screenshot slots
tony-xmelon Sep 27, 2026
52e3c88
Clarify empty loaded-slot screenshot coverage
tony-xmelon Sep 27, 2026
dbfbb17
Merge remote-tracking branch 'upstream/main' into codex/preset-screen…
tony-xmelon Sep 27, 2026
30facc6
Skip preset screenshot hardware check on unmeasured profiles
tony-xmelon Sep 27, 2026
5d5fff5
Assert live dimensions for the loaded screenshot slot
tony-xmelon Sep 27, 2026
ef7b5fe
Cover stored and live screenshot paths separately
tony-xmelon Sep 27, 2026
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
4 changes: 4 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,10 @@ small documentation fixes.
`collect` refuse on that thread. To see the connect burst, register through
`protocol.connect(before_handshake=...)`. (ADR-0009)
- New operations follow `docs/architecture.md`, "How to add a new operation".
- A timing-sensitive multi-message operation uses `Transport.send_sequence`,
which frames first and holds the write lock across the sequence. Do not sleep
between writes in `protocol/client.py` or issue those messages as separate
`send` calls.

## Do not

Expand Down
18 changes: 18 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,24 @@ sustained stretch without a correction.

## Unreleased

### CorOS 4.1 preset screenshots are readable

`QuadCortex41.preset_screenshot()` sends the complete preset address and returns
the 800 x 384 `PNG` the device renders for that preset, without recalling it or
changing the unit's screen. The folder argument is its display name
(`"My Presets"`), not its key; `list_folders()` supplies the name and the
factory flag. The address is not optional on the wire: a bare `Screenshot{READ}`
is ignored. For the currently loaded empty/unsaved slot, the method returns the
live 800 x 480 screen capture instead of waiting for the device's absent stored
image response. The CorOS 4.0.1 profile refuses the operation by default;
`Support.EXPERIMENTAL` enables a hardware probe there.

### CorOS 4.1 physical-screen capture and tap are exposed

`QuadCortex41` can capture the full 800 x 480 display and tap a pixel. Gesture
sequences are atomic and a capture primes the remote-control surface before
input. The 4.0.1 profile keeps these operations visible but refuses them because
they are unmeasured there.
### Rename the unit, drive undo/redo, and read inhibited modules

`set_device_name()` sends a sparse Version update. `undo()` and `redo()` drive
Expand Down
9 changes: 9 additions & 0 deletions docs/ADR.md
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,15 @@ Records are append-only once `Decided` and built upon: a shipped decision is nev
- This is repository governance rather than library architecture, and it lives here rather than in `contributing.md` or `docs/STEERING.md` because the durable part is the reasoning - in particular why `require_last_push_approval` was rejected, which is the decision a future maintainer would otherwise re-litigate from scratch. `contributing.md` gains its note about sync-before-review only once contributors can actually merge.
- Reversal is one API call and costs nothing, which is why this record is short on hedging: the setting is cheap to try and cheap to undo.

## ADR-0024: A timed device gesture is one atomic transport sequence

- **Status:** Decided (2026-09-04)
- **Decision:** A protocol operation made of timing-sensitive messages uses `Transport.send_sequence`. The transport frames every message first and holds the write lock across writes and inter-message intervals; the client selects messages and measured timing but does not sleep or write reports itself.
- **Context:** CorOS 4.1 touchscreen input needs two `RemoteControl` messages 20 ms apart after the initial screenshot read settles. Separate `send` calls allow keepalive traffic to split the gesture and put timing in the wrong layer.
- **Options:** (a) Atomic transport sequence — chosen. (b) Sleep and call `send` from the client — rejected because another write can interleave. (c) Write HID reports directly — rejected because framing belongs to the transport.
- **Open Questions:** None.
- **Rationale:** The transport owns serialization and timing; the protocol client owns semantic message construction.
- **Consequences:** Timing-sensitive multi-message operations use `send_sequence`; tests assert message order and interval/delay arguments. A delayed sequence remains non-transactional at the device and does not imply an acknowledgement.
## ADR-0022: The payload a catalog snapshot is generated from is committed beside it

- **Status:** Decided (2026-09-22)
Expand Down
10 changes: 10 additions & 0 deletions docs/STEERING.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,7 @@ Decisions are recorded in [`ADR.md`](ADR.md):
| ADR-0020 | Connect resolves a device profile, and nothing else branches on firmware or model |
| ADR-0021 | An approval stops counting once the pull request's code changes |
| ADR-0022 | The payload a catalog snapshot is generated from is committed beside it |
| ADR-0024 | A timed device gesture is one atomic transport sequence |

## 8. Open Questions

Expand Down Expand Up @@ -233,6 +234,15 @@ Entries are short by design ([`writing.md`](writing.md)). The full narrative
behind each one is in the lab repository,
`doc/pyquadcortex/history/steering-change-log.md`, and in the pull requests.

### 2026-09-27 - Remote screen control is narrowed to reviewed operations

- **What changed:** the public PR surface is limited to `capture_screen()` and
`tap_screen()`. The 4.1 hardware test skips unmeasured profiles, and protocol
coverage records the broker-observed 800 x 480 capture and tap behavior.
- **Why:** swipe and graphics-tree were added without review and lacked
operation-specific evidence on this branch.
- **Scope:** protocol client/profile, screen tests and API/protocol/coverage
documentation. See ADR-0024 for atomic gesture timing.
### 2026-09-22 - A snapshot's input is committed beside it (ADR-0022)

- **What changed:** the `ModelRepo` payload the 4.0.1 snapshot is generated from
Expand Down
2 changes: 2 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ already read and need no connection; calling them as methods raises
| **Connect** | `protocol.connect(profile=, support=)` resolves the unit's device profile before the handshake (ADR-0020) and returns a connected client. An unknown `(device_type, zenos_git_hash)` raises `UnsupportedDevice`. `Support.VERIFIED` (default) refuses an operation the profile has not verified; `Support.EXPERIMENTAL` runs it with one warning. `qc.models`, `qc.params` and `qc.options` are that connection's own constants |
| **Inspect / device identity** | `version()`, `set_device_name(name)`, `list_presets(setlist)`, `find_preset(name, setlist)`, `read_preset(setlist, slot)` |
| **Navigate** | `recall_preset(setlist, slot)`, `switch_scene(scene)` |
| **Drive and inspect the unit's screen (`QuadCortex41`, CorOS 4.1.0)** | `tap_screen(x, y, timeout=)` taps one raw pixel coordinate; `capture_screen()` returns a PNG of the QC's current display. The 4.0.1 base refuses both operations pending measurement |
| **Edit the grid** | `set_chain_input(row, input)`, `reroute_grid_input(preset, input)`, `set_param(target, param, value)`, `set_bypass(Block(row, column), bypassed)` |
| **Add and remove blocks** | `set_block(Block(row, column, model_id))`, `remove_block(cell)`, `move_block(source, destination)`, `catalog` |
| **Parallel lanes** | `set_split(row, split_column, mix_column)`, `clear_split(row)`, `set_split_mute(row)`, `protocol.splits(preset)` |
Expand Down Expand Up @@ -77,6 +78,7 @@ already read and need no connection; calling them as methods raises
| **Copying** | `copy_preset(from_setlist, position, to_setlist)`: recall plus save, so it loads each source |
| **Device list** | `pin_model()`, `unpin_model()`, `pinned_models()`, `master_volume()` |
| **Neural Captures** | `captures()` and `list_irs()` to browse the library, `set_capture(cell, entry)` to place one. Creating a capture is the unit's own wizard; disconnect first, since a connected client suppresses it |
| **Preset images** | `QuadCortex41.preset_screenshot(folder_name, position, is_factory=False)` returns the stored preset PNG (800 x 384). `folder_name` is the folder's display name (`"My Presets"`), not the key `read_preset` takes. For the currently loaded empty/unsaved slot it returns the live 800 x 480 screen instead; it never recalls another preset. The 4.0.1 profile refuses by default; `Support.EXPERIMENTAL` can measure it |
| **Edit history** | `undo()`, `redo()` |
| **Discovery** | `list_folders()`: every folder the unit knows, including the factory Captures Library and plugin artist presets; `recents()`, `favorites()`, `add_favorite()`, `remove_favorite()` |
| **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, preset)`, `move_preset(setlist, preset, to_slot)`; `preset` may be the exact name or a `ProductData` returned by `list_presets()` |
Expand Down
18 changes: 10 additions & 8 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ For the wire itself (frame layout, handshake, message shapes) see

- [Layer map](#layer-map)
- [What flows through the layers](#what-flows-through-the-layers)
- [send vs request vs await_broadcast](#send-vs-request-vs-await_broadcast)
- [send vs send_sequence vs request vs await_broadcast](#send-vs-send_sequence-vs-request-vs-await_broadcast)
- [How to add a new operation](#how-to-add-a-new-operation)
- [The generated protobuf bindings](#the-generated-protobuf-bindings)
- [Testing philosophy](#testing-philosophy)
Expand Down Expand Up @@ -160,10 +160,10 @@ classes: `type_for(cls)` and `class_for(message_type)`. A type absent from
### client.py

`QuadCortex` is the message-level API. It builds protobuf messages and calls
`send`, `request`, `await_broadcast` and `next_request_id` on the transport it
`send`, `send_sequence`, `request`, `await_broadcast` and `next_request_id` on the transport it
was given. It never touches a report, a frame or a byte offset.

Because it depends on four transport methods, the whole API is testable with a
Because it depends on five transport methods, the whole API is testable with a
short fake (`tests/test_client.py`) and no unit, no `hid`, no timing. Every wire
concern stays below this line. When you add an operation, the protobuf building
belongs here and nothing else does.
Expand Down Expand Up @@ -282,14 +282,16 @@ device.read() -> one 129-byte input report
else a broadcast waiter, else dropped
```

## send vs request vs await_broadcast
## send vs send_sequence vs request vs await_broadcast

Choosing correctly is most of the work of adding an operation. The first three
rows serve one exchange. The last is how a long-lived caller watches the link.
Choosing correctly is most of the work of adding an operation. The first four
rows send one exchange or wait for its answer. `add_listener` is how a long-lived
caller watches the link.

| Transport method | Use when | Blocking | Correlation |
|---|---|---|---|
| `send(msg)` | The unit acts on the message and you do not need its answer: scene switch, grid edits, recall, keepalive. | No | None |
| `send_sequence(messages, interval=, delay=)` | Messages form one short timing-sensitive gesture that concurrent writes must not split. The transport frames first and holds the write lock across the sequence. | During the requested delay and intervals | None |
| `request(msg, timeout=)` | The unit answers with a message of the **same type**: `Version` read, `ResetCommsBuffers`, the `File` mutations. | Yes | A fresh `request_id` is registered before the write. The reply is the first inbound message of the same type whose `request_id`, if present on both sides, matches. |
| `await_broadcast(cls, trigger, timeout=, match=)` | The answer arrives as a **push of a different type**, or as an unsolicited push the unit emits in response to an action: the `RecallPreset` push that carries a preset, the `File` folder listings. | Yes | By message class, plus your `match` predicate. A message the predicate rejects is left for a later waiter. |
| `add_listener(fn)` | You want every message for the life of the connection: a cache fed by the unit's pushes, or a log of the link. | No, but `fn` runs on the RX thread | None. Every message, every type. Removed with the returned callable or `remove_listener(fn)`. |
Expand All @@ -312,7 +314,7 @@ Worked example: `set_global_tempo(bpm)`.
`protocol/proto/ProductionAutomation.proto` (control messages) and
`protocol/proto/Preset.proto` (the `BinaryPreset` grid model). Start from the
`CortexMessageType.Enum` block at the top of `ProductionAutomation.proto`, which
lists all 71 types with their wire integers. Find `GlobalTempo = 33`, then
lists all 73 types with their wire integers. Find `GlobalTempo = 33`, then
`message GlobalTempoMessage`. Nearly every scalar field sits in a synthetic
`oneof`, so `HasField()` tells "set to zero" from "not set".

Expand Down Expand Up @@ -484,7 +486,7 @@ Three code-level gaps matter to someone extending the library:
client method plus tests. `GlobalTempo` is the awkward one: it alternates a
clock shape with a 25-parameter shape, so a reader must match on a reply that
carries parameters.
- **Types not in the registry at all.** Whole areas are untouched: `Screenshot`,
- **Types not in the registry at all.** Whole areas are untouched:
`Diagnostics`, `CloudBackup`, `Confirmation`, `SuspendConnection`, the
`*Forward` wrappers, and the production and test-farm messages. Nothing about
them has been observed on the wire.
Expand Down
5 changes: 3 additions & 2 deletions docs/manual-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ A "candidate" names a message type from the unit's own schema or a field in

## Summary

Of 105 features audited: **68 yes**, **8 partly**, **18 no**, **11 n/a**.
Of 106 features audited: **68 yes**, **9 partly**, **18 no**, **11 n/a**.

Of the 94 features a host could plausibly drive, 68 are fully covered and 8 are
Of the 95 features a host could plausibly drive, 69 are fully covered and 8 are
partly covered. Eighteen remain untouched. Of those, a few are writes confirmed to
do nothing with no route found (preset tags, duplicating a setlist as one
operation), and two whole features need the physical world: creating a Neural
Expand Down Expand Up @@ -112,6 +112,7 @@ settled is in [capture.md](capture.md).
| Create a folder, nested navigation | yes | `create_setlist(name)`. Setlists are siblings under `/media/p4/Presets`, not children of My Presets |
| Favorites and Recents | yes | `recents()` and `favorites()` read the two lists. The request's `is_favorites` flag selects which; the reply never sets it, so correlate on `request_id`. `add_favorite()` and `remove_favorite()` write one entry at a time. Only presets can be favourited |
| Bulk actions | partly | no host-drivable bulk copy; `BulkOperation` only narrates progress. `copy_preset()` and `duplicate_setlist()` do it by recall plus save, a few seconds per preset |
| Physical screen remote control | partly | on `QuadCortex41`, `capture_screen()` and `tap_screen()` use measured CorOS 4.1.0 `RemoteControl` shapes; the 4.0.1 profile refuses them pending measurement |
| Search | no | candidate `RecentSearches` |
| Sort | n/a | client-side once a listing is in hand |
| Neural Captures: list | yes | `captures()` browses the library, over 2000 entries. Not the catalog, which does not grow when a capture is saved |
Expand Down
Loading
Loading