diff --git a/README.md b/README.md index 8fb4066..8e8efa5 100644 --- a/README.md +++ b/README.md @@ -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 +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. diff --git a/changelog.md b/changelog.md index 15ddd65..9bf157c 100644 --- a/changelog.md +++ b/changelog.md @@ -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` - @@ -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 diff --git a/docs/api.md b/docs/api.md index e1e6ac8..06ce3e9 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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 + `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. diff --git a/docs/protocol.md b/docs/protocol.md index 1aa8292..0439063 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -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 diff --git a/pyquadcortex/device/device.py b/pyquadcortex/device/device.py index e26df53..0f998fa 100644 --- a/pyquadcortex/device/device.py +++ b/pyquadcortex/device/device.py @@ -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`. @@ -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 @@ -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) diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index daceea9..92c5850 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -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): """Perform the full connect handshake Cortex Control performs. Internal: :func:`pyquadcortex.protocol.connect` calls this for you, so a caller @@ -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. @@ -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: + continue self._t.send(registry.class_for(pa.CortexMessageType.Enum.Value(name))( action=pa.MessageAction.READ )) diff --git a/pyquadcortex/protocol/session.py b/pyquadcortex/protocol/session.py index 30de9b0..11f72b0 100644 --- a/pyquadcortex/protocol/session.py +++ b/pyquadcortex/protocol/session.py @@ -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: @@ -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 @@ -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) diff --git a/tests/test_client.py b/tests/test_client.py index acfe22f..3966313 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -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 @@ -658,6 +662,26 @@ def test_hello_performs_full_connect_handshake(): ) +def test_hello_can_defer_only_the_initial_file_listing(): + 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 ----------------------------- diff --git a/tests/test_device.py b/tests/test_device.py index 3f7c5aa..922453a 100644 --- a/tests/test_device.py +++ b/tests/test_device.py @@ -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} @@ -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} diff --git a/tests/test_session.py b/tests/test_session.py index ba5ac04..9c4bee4 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -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): @@ -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") @@ -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") @@ -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())