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
7 changes: 7 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,13 @@ Both connect layers accept `initial_file_listing=False`, omitting only the
handshake's eager `File` READ. The default remains eager, and listing operations
still fetch explicitly when called on a profile that verifies them.

Deferring costs the enumeration and nothing else a save announces. Measured
2026-09-09 on CorOS 4.0.1: a preset saved on the unit is announced identically
whether or not the `File` READ was sent, so a listener does not go deaf by
setting this. A delete, a rename and an IR import were not measured. That also
corrects a general statement in [docs/protocol.md](docs/protocol.md) section
4.2, which had every READ in the connect burst acting as a subscription.

### Where a knob's numbers start comes from the device now, not a table

The Quad Cortex has knobs whose bottom position shows a word - usually `OFF` -
Expand Down
35 changes: 31 additions & 4 deletions docs/capture.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ from pyquadcortex.protocol.proto import ProductionAutomation_pb2 as pa
# m.HasField("metronome_status") and not m.params
#
# Note this is a NOISE list, not an allow-list, and pair it with a heartbeat -
# see "Three ways your instrument lies about silence" below.
# see "Four ways your instrument lies about silence" below.
NOISE = {"GlobalTempoMessage", "IOMeterMessage", "GridModelMeterMessage",
"KeepAliveMessage", "ModuleStatsMessage"}

Expand All @@ -65,11 +65,11 @@ with lock:
print(f"{name}: {body[:400]}")
```

## Three ways your instrument lies about silence
## Four ways your instrument lies about silence

Every one of these produced a confident wrong conclusion in this project, and all three
Every one of these produced a confident wrong conclusion in this project, and all four
look identical from the outside: **the device appears not to answer.** The device was
behaving correctly all three times.
behaving correctly all four times.

A useful heuristic came out of it. A *flaky* negative is usually the device - reads here are
lazy and the first request after connecting is often dropped. A *perfectly consistent*
Expand Down Expand Up @@ -143,6 +143,33 @@ documentation, along with a method that quietly returned the wrong list. Correla
`request_id`, which the device does echo, and when a match predicate times out, log what DID
arrive before concluding nothing did.

**4. A listener you never actually registered records nothing, and nothing looks
exactly like silence.** The listener above is attached after `connect()` returns, which is
fine for an action you perform yourself but too late for the connect handshake's own burst
- by then it is seconds from starting. Catching the burst means subscribing through
`protocol.connect(before_handshake=...)`, and that hook is called WITH the started
transport and expects you to register on it:

```python
protocol.connect(before_handshake=tap) # WRONG
protocol.connect(before_handshake=lambda t: t.add_listener(tap)) # right
```

The wrong form raises nothing. `tap` is called exactly once, with the `Transport` object
as its "message", and never again. Measured 2026-09-09: one recorded message in 35
seconds, on a link that was healthy and had just delivered a 399-message folder
enumeration to nobody.

The heartbeat from lie 2 does not necessarily save you here. If it counts what the
recorder holds, that one spurious entry can satisfy its liveness test, and it will print
ALIVE over an empty recording - which is what happened. Count something you know the
device sends unprompted, such as the tempo stream, rather than the total.

What does catch it is a POSITIVE CONTROL: an arm of the experiment where you already know
what the device should say. Run that arm FIRST. A silent instrument then shows up in the
arm that was supposed to be noisy, before you have spent the session believing a negative.
`tests/hardware/conftest.py` has the correct registration if you want a worked example.

## Diff the whole state, do not hunt for a field

The listener above answers "what does the device SAY when I do this?". When the answer is
Expand Down
51 changes: 49 additions & 2 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -519,8 +519,55 @@ appears to want the whole set before it considers the client fully connected.
The optional initial `File` READ makes this a 22-type burst by default or 21
when deferred. A contributed CorOS 4.1.0 check on 2026-09-08 connected with the
21-type form and later enumerated all 586 folders explicitly under
`Support.EXPERIMENTAL`. Whether omitting `File` also opts out of later file
change broadcasts remains unmeasured.
`Support.EXPERIMENTAL`.

**`File` is the one type measured to behave differently: it enumerates, and it
does not gate pushes.** This corrects the rule at the top of this section, which
was recorded as covering every type in the burst. Measured 2026-09-09 on CorOS
4.0.1 / `d14e`: a client that never sends the `File` READ is still told when a
preset is saved on the unit. The other 21 types were NOT tested one at a time -
the rule above came from section 4.1's all-or-nothing observation, not from
omitting individual READs - so this says nothing about whether they gate their
own pushes. On CorOS 4.1.0 the question remains unmeasured.

Two connections, the same action on the unit each time, with a recorder attached
through `before_handshake` and no type filter on either run:

| connect | `File` in the burst | `File` after the on-unit save |
|---|---|---|
| default | 399 | 1 |
| `initial_file_listing=False` | 0 | 1 |

The action was one Save As into an empty user slot, followed about ten seconds
later by a scene change. The scene change is a FENCING marker rather than part of
the measurement: it proves the recorder was still live and that the operator
acted, so an absent `File` would have meant something. Each run kept recording
for about three minutes after the save, with a heartbeat every 15 seconds, and
the `File` count was stable from the save to the end.

The save's own cascade is identical in both runs and in the same order: `File`,
`UndoRedo`, then `RecallPreset`, `Scene`, `RecentsFavorites`, `SetlistPosition`
and the `Grid` pushes, all inside about a second. So omitting the READ costs the
399-message enumeration and costs nothing else a SAVE announces. A delete, a
rename and an IR import were not measured.

What carries this is the right-hand column, not the left. The left only shows the
flag took effect, which `tests/test_client.py` already proves offline. The finding
is the deferred arm's `1`: a push that ARRIVED on a connection which never
subscribed. What licenses trusting that arm's `0` in the burst is that the same
recorder, in the same run, caught that `1`, so it was demonstrably not deaf. One
trial per arm.

The first attempt produced a convincing false negative: the recorder was never
registered at all, and logged one message in 35 seconds on a healthy link. The
trap and how to avoid it are lie 4 in [capture.md](capture.md#four-ways-your-instrument-lies-about-silence),
which is where it belongs - it is a fact about the instrument, not about the
device. What belongs here is why this measurement survived it. The eager arm is
a positive control, it ran first, and it failed loudly.

The default run also reproduces two records elsewhere in this file: 399 folders
in the enumeration, and three inbound `Version` messages per connect. The
deferred run enumerates nothing, by construction.

`QuadCortex._hello()`, which `pyquadcortex.protocol.connect()` runs for you, does the
same thing with one deliberate difference: it does **not** issue a host
Expand Down
13 changes: 9 additions & 4 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -570,10 +570,15 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0,
valid CC version).
3. ``Connection{connected: true}``.
4. A READ for each state type in ``_SUBSCRIBE_TYPES`` - this is the
subscription that makes the device start pushing that state. The
``File`` READ is optional because it immediately enumerates the
entire folder tree. Whether it also subscribes later file changes
has not been measured.
subscription that makes the device start pushing that state, with
one measured exception. The ``File`` READ only ENUMERATES: it
immediately dumps the whole folder tree, and omitting it does not
stop the push a save announces. Measured 2026-09-09 on CorOS 4.0.1
/ ``d14e``: an on-unit Save As announced ``File`` identically with
the READ sent and with it omitted (``docs/protocol.md`` section
4.2, which also says what was NOT measured). So
``initial_file_listing=False`` costs the enumeration and nothing
else a save announces.

Returns the echoed ResetCommsBuffers reply. After this, ``read_preset``
and the device's live-sync pushes work.
Expand Down
Loading