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
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,12 @@ with protocol.connect() as qc:
device requires, so what you get back is ready to use. As a context manager it
also releases the device when the block ends; otherwise call `qc.close()`.

The default handshake also asks for the unit's full folder tree, which can keep
several hundred `FileMessage` pushes arriving after `connect()` returns. An app
that does not need an eager listing can use
`protocol.connect(initial_file_listing=False)`; `list_presets()` and the other
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
file APIs still fetch on demand on a verified profile.

Closing tells the device the client is leaving, which is what Cortex Control does on
quit. If you supplied your own transport and so own teardown yourself, send it with
`qc.disconnect()` before you tear down.
Expand Down
7 changes: 6 additions & 1 deletion changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ correction.

## Unreleased

### Initial file enumeration can be deferred

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.

### 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 Expand Up @@ -105,7 +111,6 @@ middle label. A declared default moves onto the drawn span with everything
else, so a pan's default reports the position the screen shows. `mid_string` leaves the unexplained list in
[docs/domain-model.md](docs/domain-model.md): it is the label at wire 0.5.


### The first hardware run of the profile seam, and what it corrected

Run 2026-09-07 on Quad Cortex, CorOS 4.0.1 / d14e, straight after the seam
Expand Down
6 changes: 6 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ outputs, and instrument tags likewise have readable names (`Input.RETURN_1`,

Things worth knowing before you script against this:

- **The default connect eagerly enumerates folders.** On a populated unit that
means several hundred `FileMessage` pushes. Pass
`initial_file_listing=False` to either `protocol.connect()` or
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
`pyquadcortex.connect()` to defer that traffic. On a verified profile,
listing methods still fetch on demand; an unverified profile requires
`support=Support.EXPERIMENTAL` for those operations.
- **Editing goes recall, change, save.** The device saves whatever is currently on
the grid, so an edit means recalling the preset first. The methods above are
built for that order; [docs/protocol.md](protocol.md) explains why.
Expand Down
5 changes: 5 additions & 0 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -516,6 +516,11 @@ type to clients that asked for it. `QuadCortex._SUBSCRIBE_TYPES` lists the set
the library subscribes to, mirroring Cortex Control's burst. `RecallPreset` is
the one that matters most (it is how a full preset is obtained), but the device
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.

`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
5 changes: 5 additions & 0 deletions pyquadcortex/device/device.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ def __repr__(self) -> str:

def connect(*, timeout: float = 5.0, settle: float = 2.0,
handshake_patience: float = 30.0,
initial_file_listing: bool = True,
profile: type[protocol.QuadCortex] | None = None,
support: protocol.Support = protocol.Support.VERIFIED) -> Device:
"""Open a Quad Cortex over USB and return it as a :class:`Device`.
Expand All @@ -253,6 +254,9 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0,
handshake_patience: total seconds to keep re-attempting the handshake
while the unit is openable but silent. See
:func:`pyquadcortex.protocol.connect`, which this passes through to.
initial_file_listing: whether to enumerate the full folder tree during
the handshake. Set false to defer that traffic until a listing is
requested explicitly.
profile: a profile class to use instead of the one the unit's identity
resolves to. See :func:`pyquadcortex.protocol.connect` (ADR-0020).
support: how the connection treats an operation its profile has not
Expand Down Expand Up @@ -280,6 +284,7 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0,
state = DeviceState()
client = protocol.connect(timeout=timeout, settle=settle,
handshake_patience=handshake_patience,
initial_file_listing=initial_file_listing,
before_handshake=state.listen_on,
profile=profile, support=support)
return Device(client, _owns_client=True, _state=state)
11 changes: 9 additions & 2 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,8 @@ def remove_listener(self, listener):
# this is the version captured on the wire.
CC_VERSION = "4.0.1"

def _hello(self, timeout: float = 5.0, settle: float = 2.0):
def _hello(self, timeout: float = 5.0, settle: float = 2.0,
initial_file_listing: bool = True):
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
"""Perform the full connect handshake Cortex Control performs.

Internal: :func:`pyquadcortex.protocol.connect` calls this for you, so a caller
Expand All @@ -569,7 +570,10 @@ 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.
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.

Returns the echoed ResetCommsBuffers reply. After this, ``read_preset``
and the device's live-sync pushes work.
Expand Down Expand Up @@ -601,7 +605,10 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0):
)
self._t.send(pa.ModelRepoMessage(action=pa.MessageAction.READ))
self._t.send(pa.ConnectionMessage(connected=True))
assert "File" in self._SUBSCRIBE_TYPES
for name in self._SUBSCRIBE_TYPES:
if name == "File" and not initial_file_listing:
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
continue
self._t.send(registry.class_for(pa.CortexMessageType.Enum.Value(name))(
action=pa.MessageAction.READ
))
Expand Down
16 changes: 14 additions & 2 deletions pyquadcortex/protocol/session.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ def _read_identity(transport, timeout: float) -> pa.VersionMessage:

def connect(*, timeout: float = 5.0, settle: float = 2.0,
handshake_patience: float = 30.0,
initial_file_listing: bool = True,
before_handshake=None,
profile: type[QuadCortex] | None = None,
support: Support = Support.VERIFIED) -> QuadCortex:
Expand Down Expand Up @@ -188,6 +189,12 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0,
Each attempt restarts fully (safe: the identity read is a bare READ,
and the handshake begins with a fresh session id). Set to 0 for the
old single-attempt behaviour.
initial_file_listing: whether the handshake should immediately ask the
unit to enumerate its full folder tree. Keep the default for the
usual eager state burst; set this false when startup traffic matters
more than preloading listings. Explicit calls such as
:meth:`~pyquadcortex.protocol.client.QuadCortex.list_folders` still
work and fetch the listing on demand.
before_handshake: optional ``callable(transport)``, called once with the
started :class:`~pyquadcortex.protocol.transport.Transport` after it
starts and before the handshake runs. This is the only way to
Expand Down Expand Up @@ -257,8 +264,13 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0,
f"{pa.VersionMessage.DeviceType.Name(cls.DEVICE_TYPE)}, and the unit "
f"says {pa.VersionMessage.DeviceType.Name(identity.device_type)}")
qc = cls(transport, _owned_resources=owned, support=support)
_retry_until_patient(lambda: qc._hello(timeout=timeout, settle=settle),
deadline, handshake_patience)
def hello():
return qc._hello(
timeout=timeout, settle=settle,
initial_file_listing=initial_file_listing,
)

_retry_until_patient(hello, deadline, handshake_patience)
# Say goodbye BEFORE the transport and handle go away, since the send needs
# a live transport. close() pops this list, so appending last runs it first.
owned.append(qc.disconnect)
Expand Down
24 changes: 24 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -646,6 +646,10 @@ def test_hello_performs_full_connect_handshake():
if isinstance(m, pa.RecallPresetMessage) and m.action == pa.MessageAction.READ
]
assert recall_reads
assert any(
isinstance(m, pa.FileMessage) and m.action == pa.MessageAction.READ
for m in sent
), "the default retains eager File enumeration"
# ModelRepo READ is present (empirically required to open the push gate).
assert any(
isinstance(m, pa.ModelRepoMessage) and m.action == pa.MessageAction.READ
Expand All @@ -658,6 +662,26 @@ def test_hello_performs_full_connect_handshake():
)


def test_hello_can_defer_only_the_initial_file_listing():
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
canned = {"ResetCommsBuffersMessage": pa.ResetCommsBuffersMessage()}
eager = client.QuadCortex(FakeTransport(canned))
deferred = client.QuadCortex(FakeTransport(canned))

eager._hello(settle=0)
deferred._hello(settle=0, initial_file_listing=False)

eager_reads = [
type(message).__name__ for message in eager._t.sent
if getattr(message, "action", None) == pa.MessageAction.READ
]
deferred_reads = [
type(message).__name__ for message in deferred._t.sent
if getattr(message, "action", None) == pa.MessageAction.READ
]
assert eager_reads.count("FileMessage") == 1
assert deferred_reads == [name for name in eager_reads if name != "FileMessage"]


# -- ergonomics: no magic numbers at the call site -----------------------------


Expand Down
5 changes: 4 additions & 1 deletion tests/test_device.py
Original file line number Diff line number Diff line change
Expand Up @@ -403,9 +403,11 @@ def test_connect_hands_every_argument_to_the_protocol_layer(monkeypatch):
openable-but-silent window.
"""
seen = _spy_on_protocol_connect(monkeypatch)
pyquadcortex.connect(timeout=1.5, settle=0.25, handshake_patience=45.0)
pyquadcortex.connect(timeout=1.5, settle=0.25, handshake_patience=45.0,
initial_file_listing=False)
assert _without_the_hook(seen) == {
"timeout": 1.5, "settle": 0.25, "handshake_patience": 45.0,
"initial_file_listing": False,
"profile": None, "support": support.Support.VERIFIED}


Expand All @@ -414,6 +416,7 @@ def test_connect_passes_its_defaults_through_unchanged(monkeypatch):
pyquadcortex.connect()
assert _without_the_hook(seen) == {
"timeout": 5.0, "settle": 2.0, "handshake_patience": 30.0,
"initial_file_listing": True,
"profile": None, "support": support.Support.VERIFIED}


Expand Down
21 changes: 18 additions & 3 deletions tests/test_session.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,18 @@ def test_connect_returns_a_handshaken_client(fake_stack):
kinds = [type(m).__name__ for m in t.sent]
assert "ResetCommsBuffersMessage" in kinds
assert "ConnectionMessage" in kinds
assert "FileMessage" in kinds


def test_connect_can_defer_the_initial_file_listing(fake_stack):
qc = session.connect(settle=0, initial_file_listing=False)
t = FakeTransport.instances[0]

assert not any(type(message).__name__ == "FileMessage" for message in t.sent)
assert any(
type(message).__name__ == "RecallPresetMessage" for message in t.sent
)
qc.close()


def test_connect_as_context_manager_releases_the_device(fake_stack):
Expand Down Expand Up @@ -149,7 +161,8 @@ def test_before_handshake_runs_once_however_many_handshake_attempts_it_takes(
"""
attempts = {"n": 0}

def flaky_hello(self, timeout=5.0, settle=2.0):
def flaky_hello(self, timeout=5.0, settle=2.0,
initial_file_listing=True):
attempts["n"] += 1
if attempts["n"] < 3:
raise TimeoutError("no response for request_id=1")
Expand Down Expand Up @@ -322,7 +335,8 @@ def await_broadcast(self, expected_class, trigger, timeout=40.0, match=None):

attempts = {"n": 0}

def flaky_hello(self, timeout=5.0, settle=2.0):
def flaky_hello(self, timeout=5.0, settle=2.0,
initial_file_listing=True):
attempts["n"] += 1
if attempts["n"] < 3:
raise TimeoutError("no response for request_id=1")
Expand Down Expand Up @@ -364,7 +378,8 @@ def await_broadcast(self, expected_class, trigger, timeout=40.0, match=None):
zenos_git_hash="4.0.1",
device_serial_number="QCS0000001")

def never_answers(self, timeout=5.0, settle=2.0):
def never_answers(self, timeout=5.0, settle=2.0,
initial_file_listing=True):
raise TimeoutError("no response for request_id=1")

monkeypatch.setattr(session, "open_device", lambda: QuietDevice())
Expand Down
Loading