From 5b2e10ddc62e54095272e872c8280e77c52556fa Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Thu, 3 Sep 2026 10:23:18 +0300 Subject: [PATCH 1/7] feat: expose compiler-inhibited module state --- changelog.md | 7 +++++++ docs/api.md | 2 +- docs/manual-coverage.md | 6 +++--- pyquadcortex/protocol/client.py | 19 +++++++++++++++++++ tests/hardware/test_settings_values.py | 16 ++++++++++++++++ tests/test_client.py | 17 +++++++++++++++++ 6 files changed, 63 insertions(+), 4 deletions(-) diff --git a/changelog.md b/changelog.md index a00d9bae..0c1234e4 100644 --- a/changelog.md +++ b/changelog.md @@ -84,6 +84,13 @@ Fixed alongside it: a damaged gzip payload could raise `EOFError` or `zlib.error`, neither of which was caught, so it was reported as an unexpected internal error rather than as the damaged payload it is. +### Read which global modules DSP load inhibited + +`inhibited_modules()` reads the two booleans the unit reports when processing +load automatically disables the Input Gate or Global EQ. The reader requires +both optional fields to be explicitly present, so protobuf's absent-field +default cannot be mistaken for a real false state. + ### The wrong unit is now caught before the code runs ```python diff --git a/docs/api.md b/docs/api.md index a8456449..dcaa6568 100644 --- a/docs/api.md +++ b/docs/api.md @@ -65,7 +65,7 @@ already read and need no connection; calling them as methods raises | **Watch what the unit pushes** | `add_listener(fn)`, `remove_listener(fn)` - your `fn` is called with every message the unit sends, asked for or not. It runs on the transport's read thread, so it must not block and may not read from the device. To catch the connect handshake's own burst of state, register before it with `protocol.connect(before_handshake=...)` | | **Scenes** | `copy_scene(from_scene, to_scene, swap=False)`, `set_scene_label(scene, label)`, `set_scene_color(scene, argb)` | | **Global settings** | `settings()`, `update_settings(**fields)`, `set_scene_bypass_behavior()`, `set_global_bypass()`, `set_master_volume_assignment()`, `mode()`, `set_mode()`, `set_mode_cycle()`, `set_gig_view()` | -| **Global EQ** | `global_eq()`, `set_global_eq(band, gain=, frequency=, q=, filter_type=, enabled=)`, `set_global_eq_output(level=, out12=, out34=)`, `set_global_eq_bypassed()` | +| **Global EQ** | `global_eq()`, `inhibited_modules()`, `set_global_eq(band, gain=, frequency=, q=, filter_type=, enabled=)`, `set_global_eq_output(level=, out12=, out34=)`, `set_global_eq_bypassed()` | | **I/O ports** | `io_settings()`, `set_input_port()`, `set_output_port()`, `set_usb_port()`, `set_midi_thru()`, `set_output_pairing()` | | **Tuner and Looper** | `tuner()`, `show_tuner()`, `set_tuner_input()`, `set_tuner_reference()`, `set_tuner_mute()`, `looper()` (states named by `LooperState`) | | **List parameters** | `set_param_option(cell, param, option, source)`, `protocol.param_options(preset, ...)` - includes a block's side-chain SOURCE | diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 97d4fc80..24ea33bd 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -20,10 +20,10 @@ or a field in `BinaryPreset`. A named candidate is a lead, not a claim that it w ## Summary -Of 105 features audited: **65 yes**, **8 partly**, **21 no**, **11 n/a**. +Of 105 features audited: **66 yes**, **7 partly**, **21 no**, **11 n/a**. Of the 93 features a host could plausibly drive - everything above except the 11 marked -n/a - **65 are fully covered** and 8 more are partly covered, which here means the state +n/a - **66 are fully covered** and 7 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the same shape but not individually exercised. Only 20 remain untouched. @@ -92,7 +92,7 @@ which this document had over-read as unreachable, and it answers a READ perfectl | Remove a block | yes | `remove_block()` (the DELETE action; an UPDATE with `hash: 0` is ignored) | | Move a block | yes | `move_block(from_row, from_col, to_row, to_col)`; a cross-row move makes the device create a branch | | DSP capacity refusal | partly | detected, not predicted: a refused placement raises `BlockRefused`. Headroom cannot be read - `CPULoad` never arrives | -| Global EQ / Input Gate auto-disable under load | partly | `CompilerInhibitedModules{global_gate, global_eq}` is decoded and arrives on grid edits. The manual confirms this is the documented behaviour when a preset exceeds resources. Not surfaced in the API | +| Global EQ / Input Gate auto-disable under load | yes | `inhibited_modules()` reads `CompilerInhibitedModules{global_gate, global_eq}`; the same state also arrives on grid edits. The manual confirms this is the documented behaviour when a preset exceeds resources | | Input blocks: assign a physical input | yes | `set_chain_input()` | | Output blocks: assign a destination | yes | `set_chain_output()`. 16-18 are internal row-to-row; 19 (MULTIPLE) is the Multi-Out | | Input Gate Control | yes | `set_param(LaneInput(row), ...)` - NOISE REDUCTION, BYPASS, INPUT GAIN, per scene. GAIN REDUCTION is a meter | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 876114c3..f433b299 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -2571,6 +2571,25 @@ def global_eq(self, timeout: float = 10.0): return self._read_state(pa.GlobalEQMessage, lambda m: m.HasField("bypassed"), timeout) + def inhibited_modules(self, timeout: float = 10.0): + """Whether DSP load has automatically disabled the Input Gate or Global EQ. + + Returns the raw ``CompilerInhibitedModules`` message. ``global_gate`` and + ``global_eq`` are true while the corresponding global module is inhibited. + Both fields are required in the reply so an absent optional field is never + mistaken for an explicit false. + + Confirmed read-only on hardware: a ``CompilerInhibitedModules{READ}`` + returned an UPDATE carrying both explicit false fields on Quad Cortex, + CorOS 4.1.0 / firmware d14e. The same message type was already observed + arriving after grid edits when DSP load changes the inhibited state. + """ + return self._read_state( + pa.CompilerInhibitedModulesMessage, + lambda m: m.HasField("global_gate") and m.HasField("global_eq"), + timeout, + ) + def set_global_eq_bypassed(self, bypassed: bool = True): """Turn the Global EQ off or on. Confirmed writable on hardware. diff --git a/tests/hardware/test_settings_values.py b/tests/hardware/test_settings_values.py index 0ff5f3ce..8600d15a 100644 --- a/tests/hardware/test_settings_values.py +++ b/tests/hardware/test_settings_values.py @@ -22,6 +22,7 @@ from pyquadcortex.protocol import client, units, values from pyquadcortex.protocol.enums import Input +from pyquadcortex.protocol.proto import ProductionAutomation_pb2 as pa SETTLE = 2.0 @@ -30,6 +31,21 @@ PORT = Input.INPUT_1 +def test_inhibited_modules_is_a_complete_read_only_snapshot(qc): + """Both false fields were explicitly present on CorOS 4.1.0 / d14e. + + Presence matters here: protobuf also returns false when an optional field was + never sent, and reporting that default as device state would be a guess. + """ + for _ in range(2): + state = qc.inhibited_modules() + assert state.action == pa.MessageAction.UPDATE + assert state.HasField("global_gate") + assert state.HasField("global_eq") + assert isinstance(state.global_gate, bool) + assert isinstance(state.global_eq, bool) + + def _input_level(qc, port_id): for port in qc.io_settings().settings.in_port: if port.input_port_id == int(port_id): diff --git a/tests/test_client.py b/tests/test_client.py index e5deaed1..e86135ff 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -2038,6 +2038,23 @@ def test_settings_reads_general_settings_and_requires_a_full_push(): assert match(pa.GeneralSettingsMessage(screen_brightness=1)) is False +def test_inhibited_modules_reads_both_explicit_states(): + full = pa.CompilerInhibitedModulesMessage(action=pa.MessageAction.UPDATE, + global_gate=False, + global_eq=False) + qc = client.QuadCortex(StateTransport(full)) + got = qc.inhibited_modules() + assert got is full + sent = qc._t.sent[-1] + assert isinstance(sent, pa.CompilerInhibitedModulesMessage) + assert sent.action == pa.MessageAction.READ + assert sent.SerializeToString() == b"\x08\x03" + match = qc._t.matches[-1] + assert match(full) is True + assert match(pa.CompilerInhibitedModulesMessage(global_gate=False)) is False + assert match(pa.CompilerInhibitedModulesMessage(global_eq=False)) is False + + def test_update_settings_sends_only_the_named_fields(): qc = client.QuadCortex(FakeTransport()) qc.update_settings(screen_brightness=60, swap_tempo_tuner_access=True) From bd9d672cf1cc0111f65fcf376ce5240403f1690e Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Thu, 3 Sep 2026 10:45:46 +0300 Subject: [PATCH 2/7] fix: make offline tests portable on Windows --- changelog.md | 6 ++++++ tests/hardware/conftest.py | 2 +- tests/test_hardware_gate.py | 2 +- tests/test_namespace.py | 6 +++++- 4 files changed, 13 insertions(+), 3 deletions(-) diff --git a/changelog.md b/changelog.md index 0c1234e4..fdfdb8a4 100644 --- a/changelog.md +++ b/changelog.md @@ -84,6 +84,12 @@ Fixed alongside it: a damaged gzip payload could raise `EOFError` or `zlib.error`, neither of which was caught, so it was reported as an unexpected internal error rather than as the damaged payload it is. +### The offline suite is portable to Windows checkouts + +Hardware-gate diagnostics now spell repository-relative paths consistently on +every platform, and the historical namespace fixture's pinned hash tolerates +Git's CRLF checkout conversion while still hashing all source content. + ### Read which global modules DSP load inhibited `inhibited_modules()` reads the two booleans the unit reports when processing diff --git a/tests/hardware/conftest.py b/tests/hardware/conftest.py index ccd486e9..28177804 100644 --- a/tests/hardware/conftest.py +++ b/tests/hardware/conftest.py @@ -90,7 +90,7 @@ def pytest_collection_modifyitems(session, config, items): if config.getoption("--hardware"): return gated = sorted({ - str(path.relative_to(ROOT)) + path.relative_to(ROOT).as_posix() for path in map(_resolved, items) if path is not None and path.is_relative_to(SUITE) }) diff --git a/tests/test_hardware_gate.py b/tests/test_hardware_gate.py index 89bb3240..6a6289b7 100644 --- a/tests/test_hardware_gate.py +++ b/tests/test_hardware_gate.py @@ -39,7 +39,7 @@ #: way. Recursive on purpose: the conftest hook filters on #: ``path.is_relative_to(SUITE)``, so it gates a module in a subdirectory too, and #: a flat glob here would quietly stop covering what the hook covers. -MODULES = sorted(str(path.relative_to(ROOT)) +MODULES = sorted(path.relative_to(ROOT).as_posix() for path in SUITE.rglob("test_*.py")) diff --git a/tests/test_namespace.py b/tests/test_namespace.py index 543521a0..17d5702b 100644 --- a/tests/test_namespace.py +++ b/tests/test_namespace.py @@ -81,7 +81,11 @@ def test_the_pre_flip_snapshot_is_byte_for_byte_what_0_40_0_shipped(): drops a name is to delete that name from here. Pinning the hash means the fixture and the export list can only be changed together and on purpose. """ - digest = hashlib.sha256(PRE_FLIP_INIT.read_bytes()).hexdigest() + # Git may check a text fixture out with CRLF on Windows. The pinned source + # was committed with LF, so normalize that one permitted text conversion + # while keeping every content byte under the hash. + content = PRE_FLIP_INIT.read_bytes().replace(b"\r\n", b"\n") + digest = hashlib.sha256(content).hexdigest() assert digest == PRE_FLIP_INIT_SHA256, ( f"{PRE_FLIP_INIT.name} no longer matches " f"`git show 94e5053:pyquadcortex/__init__.py`. If the snapshot really " From 83d54ae3762c45da5206ae09c7c33c75c47c2172 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Thu, 3 Sep 2026 23:25:16 +0300 Subject: [PATCH 3/7] feat: expose device identity and edit history --- changelog.md | 9 ++- docs/api.md | 3 +- docs/manual-coverage.md | 8 +- pyquadcortex/protocol/client.py | 22 ++++++ scripts/generate_models.py | 2 +- scripts/generate_options.py | 2 +- scripts/generate_params.py | 2 +- tests/hardware/readme.md | 5 ++ tests/hardware/test_identity_and_history.py | 84 +++++++++++++++++++++ tests/test_client.py | 28 +++++++ tests/test_state.py | 13 +++- 11 files changed, 165 insertions(+), 13 deletions(-) create mode 100644 tests/hardware/test_identity_and_history.py diff --git a/changelog.md b/changelog.md index fdfdb8a4..4fde3e02 100644 --- a/changelog.md +++ b/changelog.md @@ -84,11 +84,18 @@ Fixed alongside it: a damaged gzip payload could raise `EOFError` or `zlib.error`, neither of which was caught, so it was reported as an unexpected internal error rather than as the damaged payload it is. +### Rename the unit and drive preset undo/redo + +`set_device_name()` changes the name shown by the device with a sparse Version +update. `undo()` and `redo()` drive the unit's native editable-preset history; +their four-byte wire payloads and live state transitions are pinned by tests. + ### The offline suite is portable to Windows checkouts Hardware-gate diagnostics now spell repository-relative paths consistently on every platform, and the historical namespace fixture's pinned hash tolerates -Git's CRLF checkout conversion while still hashing all source content. +Git's CRLF checkout conversion while still hashing all source content. Catalog +generators also write UTF-8 explicitly instead of inheriting Windows' code page. ### Read which global modules DSP load inhibited diff --git a/docs/api.md b/docs/api.md index dcaa6568..58ad287d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -43,7 +43,7 @@ already read and need no connection; calling them as methods raises | | | |---|---| -| **Inspect** | `version()`, `list_presets(setlist)`, `find_preset(name, setlist)`, `read_preset(setlist, slot)` | +| **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)` | | **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` | @@ -73,6 +73,7 @@ already read and need no connection; calling them as methods raises | **Copying** | `copy_preset(from_setlist, position, to_setlist)` - recall + save, so it loads each source | | **Device list** | `pin_model()`, `unpin_model()`, `pinned_models()`, `master_volume()` | | **Neural Captures** | `captures()`, `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 | +| **Edit history** | `undo()`, `redo()` | | **Discovery** | `list_folders()` - every folder the device 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, name)`, `move_preset(setlist, name, to_slot)` | diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 24ea33bd..cdff4c2c 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -20,10 +20,10 @@ or a field in `BinaryPreset`. A named candidate is a lead, not a claim that it w ## Summary -Of 105 features audited: **66 yes**, **7 partly**, **21 no**, **11 n/a**. +Of 105 features audited: **68 yes**, **7 partly**, **19 no**, **11 n/a**. Of the 93 features a host could plausibly drive - everything above except the 11 marked -n/a - **66 are fully covered** and 7 more are partly covered, which here means the state +n/a - **68 are fully covered** and 7 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the same shape but not individually exercised. Only 20 remain untouched. @@ -115,7 +115,7 @@ which this document had over-read as unreachable, and it answers a READ perfectl | Set Parameters as Defaults | no | `DefaultParameters` is decoded and subscribed; never written | | Looper X: place the block | yes | it is an ordinary catalog model | | Looper X: transport actions and parameters | partly | `looper()` reads the full status and `LooperState` names five states including OVERDUBBING. The transport is not driven from here; MIDI CC#48-61 is the documented route | -| Undo / redo | no | `UndoRedo` is decoded and subscribed. It arrives after accepted grid edits - useful as an acceptance signal | +| Undo / redo | yes | `undo()` and `redo()` send sparse `UndoRedo{UPDATE}` commands. On a scratch preset, undo restored a bypass edit and redo reapplied it; the original bypass was then restored and the preset saved clean | ## 05 The Directory @@ -185,7 +185,7 @@ on 25, 9 and 56 as `led_brightness` was 28, 13 and 59). | STOMP MODE BYPASS (auto-assign on load) | yes | `update_settings(stomp_mode_auto_assign=...)`, confirmed writable | | HOLD TIMING, SWAP TEMPO AND TUNER, GIG VIEW ACCESS | yes | all three confirmed writable via `update_settings()`. `set_hold_timing()` takes `Milliseconds` and writes the index the device stores - the unit offers 500-1000 ms in 100 ms steps and the field is the index, confirmed by reading 3 while the screen showed 800 ms. `hold_timing_ms()` reads it back | | LATENCY COMPENSATION | yes | `update_settings(enable_dynamic_delay_compensation=...)`, confirmed writable | -| Device name | no | candidate `Serialization`, `GeneralSettings` | +| Device name | yes | `set_device_name()` sends sparse `Version{UPDATE, custom_name}`; live read-back matched, and restoring the prior name survived reconnect | | Firmware and serial | yes | `version()` | | Diagnostics (DSP, footswitches, USB) | no | `ModuleStats` is decoded and subscribed; `Diagnostics`, `DSPCommsDiagnostics` are not | | CorOS updates | no | `Updater` is decoded and subscribed; never driven. Risky to explore | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index f433b299..6ee2fba2 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -464,6 +464,28 @@ def version(self, timeout: float = 10.0): pa.VersionMessage(action=pa.MessageAction.READ), timeout=timeout ) + def set_device_name(self, name: str): + """Set the user-visible device name. + + The update is deliberately sparse: only ``custom_name`` is sent, so + none of the other version/identity fields can be overwritten. + """ + self._t.send(pa.VersionMessage( + action=pa.MessageAction.UPDATE, custom_name=str(name) + )) + + def undo(self): + """Undo the most recent editable-preset operation.""" + self._t.send(pa.UndoRedoMessage( + action=pa.MessageAction.UPDATE, undo=True + )) + + def redo(self): + """Redo the most recently undone editable-preset operation.""" + self._t.send(pa.UndoRedoMessage( + action=pa.MessageAction.UPDATE, redo=True + )) + def find_preset(self, name: str, setlist: str = Setlist.USER, timeout: float = 25.0): """Look a preset up by the name shown on the unit. diff --git a/scripts/generate_models.py b/scripts/generate_models.py index e0f70cb1..7f172242 100644 --- a/scripts/generate_models.py +++ b/scripts/generate_models.py @@ -130,7 +130,7 @@ def main() -> int: cat = catalog.parse_model_repo(load_payload(args.payload)) factory = cat.factory_models() source = render(cat) - pathlib.Path(args.out).write_text(source) + pathlib.Path(args.out).write_text(source, encoding="utf-8") print(f"wrote {args.out}: {len(factory)} factory models " f"of {len(cat)} total, {len({m.category for m in factory})} categories") return 0 diff --git a/scripts/generate_options.py b/scripts/generate_options.py index 17b07357..e788ee32 100644 --- a/scripts/generate_options.py +++ b/scripts/generate_options.py @@ -281,7 +281,7 @@ def main(): cat = catalog.parse_model_repo(load_payload(args.payload)) text = render(cat) - pathlib.Path(args.out).write_text(text) + pathlib.Path(args.out).write_text(text, encoding="utf-8") print(f"wrote {args.out} ({text.count('class ')} enums)") diff --git a/scripts/generate_params.py b/scripts/generate_params.py index 1fb3155d..0dd3bc66 100644 --- a/scripts/generate_params.py +++ b/scripts/generate_params.py @@ -295,7 +295,7 @@ def main() -> int: cat = catalog.parse_model_repo(load_payload(args.payload)) text = render(cat) - pathlib.Path(args.out).write_text(text) + pathlib.Path(args.out).write_text(text, encoding="utf-8") print(f"wrote {args.out} ({len(text.splitlines())} lines)") return 0 diff --git a/tests/hardware/readme.md b/tests/hardware/readme.md index 77c96666..de387627 100644 --- a/tests/hardware/readme.md +++ b/tests/hardware/readme.md @@ -7,6 +7,11 @@ that **a successful run leaves the unit exactly as it found it**. pytest tests/hardware --hardware ``` +The native undo/redo test has a second guard because it needs a disposable +loaded preset. Set `PYQUADCORTEX_UNDO_SCRATCH_SLOT` to that preset's zero-based +slot index; the test refuses to run if a different slot is loaded or the preset +already has unsaved changes. + `pytest --hardware` from the repo root works too, since the rename described below, and it runs BOTH suites - the offline one and this one, against your unit. Name the directory unless you want that. diff --git a/tests/hardware/test_identity_and_history.py b/tests/hardware/test_identity_and_history.py new file mode 100644 index 00000000..0cbe6cc4 --- /dev/null +++ b/tests/hardware/test_identity_and_history.py @@ -0,0 +1,84 @@ +"""Reversible device-name and edit-history checks against a real unit.""" + +import os +import time + +import pytest + +from pyquadcortex import protocol +from pyquadcortex.protocol import Block + + +SETTLE = 1.0 + + +def test_device_name_round_trips_and_is_restored(qc): + before = qc.version().custom_name + probe = "pyquadcortex probe" + if before == probe: + probe = "pyquadcortex probe 2" + + try: + qc.set_device_name(probe) + time.sleep(SETTLE) + assert qc.version().custom_name == probe + finally: + qc.set_device_name(before) + time.sleep(SETTLE) + + assert qc.version().custom_name == before + + +def test_undo_and_redo_reverse_and_reapply_a_scratch_edit(qc): + """Opt-in twice: --hardware plus the exact disposable slot in the env.""" + configured = os.environ.get("PYQUADCORTEX_UNDO_SCRATCH_SLOT") + if configured is None: + pytest.skip("set PYQUADCORTEX_UNDO_SCRATCH_SLOT to a disposable loaded slot") + + position = qc.loaded_position() + expected = int(configured) + assert position.position == expected, ( + f"scratch slot {expected} is configured, but slot {position.position} is loaded" + ) + assert qc.preset_dirty() is False, ( + "save or reload the scratch preset first" + ) + + target = Block(0, 6) + before_preset = qc.read_current_preset() + before_scene = int(qc.active_scene()) + before = protocol.bypass_state(before_preset, target).scenes[before_scene] + name = before_preset.name + + try: + qc.set_bypass(target, not before) + time.sleep(SETTLE) + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is not before + + qc.undo() + time.sleep(SETTLE) + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is before + + qc.redo() + time.sleep(SETTLE) + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is not before + finally: + now = protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] + if now is not before: + qc.set_bypass(target, before) + time.sleep(SETTLE) + qc.save_current_preset(position.folder_key, position.position, name, + confirm=True, confirm_timeout=30.0) + + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is before + assert qc.preset_dirty() is False diff --git a/tests/test_client.py b/tests/test_client.py index e86135ff..14bbdc0c 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -463,6 +463,34 @@ def test_move_preset_sends_file_move(): # -- session hello ------------------------------------------------------------- +def test_set_device_name_sends_a_sparse_version_update(): + qc = client.QuadCortex(FakeTransport()) + + qc.set_device_name("Stage QC") + + sent = qc._t.sent[-1] + assert isinstance(sent, pa.VersionMessage) + assert sent.SerializeToString() == b"\x08\x01\x7a\x08Stage QC" + + +def test_undo_and_redo_send_the_confirmed_sparse_updates(): + qc = client.QuadCortex(FakeTransport()) + + qc.undo() + undo = qc._t.sent[-1] + assert isinstance(undo, pa.UndoRedoMessage) + assert undo.SerializeToString() == b"\x08\x01\x28\x01" + assert undo.HasField("undo") + assert not undo.HasField("redo") + + qc.redo() + redo = qc._t.sent[-1] + assert isinstance(redo, pa.UndoRedoMessage) + assert redo.SerializeToString() == b"\x08\x01\x30\x01" + assert redo.HasField("redo") + assert not redo.HasField("undo") + + def test_hello_performs_full_connect_handshake(): canned = {"ResetCommsBuffersMessage": pa.ResetCommsBuffersMessage(session_id="ab")} qc = client.QuadCortex(FakeTransport(canned)) diff --git a/tests/test_state.py b/tests/test_state.py index 7a4a0cf8..7e7c2a01 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -1228,15 +1228,18 @@ def test_a_write_through_a_closed_cache_is_refused(link): def test_the_watchdog_does_not_outlive_the_connection(link): transport, cache = link + # The full offline + hardware run can have another live cache watchdog. + existing = set(_watchdog_threads()) cache.write_through("dirty", {"is_dirty": True}, send=lambda: None, patience=30.0) - assert _watchdog_threads(), "no watchdog was started, so this proves nothing" + started = set(_watchdog_threads()) - existing + assert started, "no watchdog was started, so this proves nothing" cache.close() deadline = time.monotonic() + 5.0 while time.monotonic() < deadline: - if not _watchdog_threads(): + if not (set(_watchdog_threads()) - existing): return time.sleep(0.02) pytest.fail("the write watchdog is still running after close()") @@ -1269,11 +1272,12 @@ def test_a_write_that_races_the_close_leaves_no_thread_behind(link): watchdog starting its thread. A thread started there waits forever on a connection nobody can reach.""" transport, cache = link + existing = set(_watchdog_threads()) cache.close() cache._watchdog.add(_a_watch_for_the_race()) - assert not _watchdog_threads() + assert set(_watchdog_threads()) == existing def _a_watch_for_the_race(): @@ -1294,9 +1298,10 @@ def test_the_watchdog_firing_as_the_connection_closes_does_not_raise(link): def test_no_watchdog_runs_until_something_is_written(link): transport, cache = link + existing = set(_watchdog_threads()) cache.value("identity", "app_fw_version") transport.push(dirty_push(True)) - assert not _watchdog_threads() + assert set(_watchdog_threads()) == existing def _watchdog_threads(): From f64984b7ff00e6c3379c6a18cc39607689d19111 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 4 Sep 2026 01:19:21 +0300 Subject: [PATCH 4/7] Address review feedback on protocol operations --- .gitattributes | 1 + changelog.md | 3 +- docs/api.md | 3 +- docs/domain-model.md | 17 ++-- docs/manual-coverage.md | 6 +- docs/protocol.md | 5 +- pyquadcortex/protocol/client.py | 45 +++++--- pyquadcortex/protocol/transport.py | 25 +++-- tests/hardware/readme.md | 13 +-- tests/hardware/test_identity_and_history.py | 107 +++++++++++--------- tests/hardware/test_settings_values.py | 4 +- tests/test_client.py | 30 +++++- tests/test_device.py | 4 +- tests/test_docs.py | 6 +- tests/test_namespace.py | 6 +- tests/test_state.py | 31 +++--- tests/test_transport.py | 35 +++++++ tests/test_values.py | 3 +- 18 files changed, 230 insertions(+), 114 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..eca11902 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +tests/fixtures/surface/pre_flip_init.py.txt text eol=lf diff --git a/changelog.md b/changelog.md index 4fde3e02..e10e61e2 100644 --- a/changelog.md +++ b/changelog.md @@ -88,7 +88,8 @@ internal error rather than as the damaged payload it is. `set_device_name()` changes the name shown by the device with a sparse Version update. `undo()` and `redo()` drive the unit's native editable-preset history; -their four-byte wire payloads and live state transitions are pinned by tests. +their four-byte wire payloads are pinned offline, and their state transitions +by a guarded hardware test against a disposable preset copy. ### The offline suite is portable to Windows checkouts diff --git a/docs/api.md b/docs/api.md index 58ad287d..be814305 100644 --- a/docs/api.md +++ b/docs/api.md @@ -65,7 +65,8 @@ already read and need no connection; calling them as methods raises | **Watch what the unit pushes** | `add_listener(fn)`, `remove_listener(fn)` - your `fn` is called with every message the unit sends, asked for or not. It runs on the transport's read thread, so it must not block and may not read from the device. To catch the connect handshake's own burst of state, register before it with `protocol.connect(before_handshake=...)` | | **Scenes** | `copy_scene(from_scene, to_scene, swap=False)`, `set_scene_label(scene, label)`, `set_scene_color(scene, argb)` | | **Global settings** | `settings()`, `update_settings(**fields)`, `set_scene_bypass_behavior()`, `set_global_bypass()`, `set_master_volume_assignment()`, `mode()`, `set_mode()`, `set_mode_cycle()`, `set_gig_view()` | -| **Global EQ** | `global_eq()`, `inhibited_modules()`, `set_global_eq(band, gain=, frequency=, q=, filter_type=, enabled=)`, `set_global_eq_output(level=, out12=, out34=)`, `set_global_eq_bypassed()` | +| **Inhibited global modules** | `inhibited_modules()` | +| **Global EQ** | `global_eq()`, `set_global_eq(band, gain=, frequency=, q=, filter_type=, enabled=)`, `set_global_eq_output(level=, out12=, out34=)`, `set_global_eq_bypassed()` | | **I/O ports** | `io_settings()`, `set_input_port()`, `set_output_port()`, `set_usb_port()`, `set_midi_thru()`, `set_output_pairing()` | | **Tuner and Looper** | `tuner()`, `show_tuner()`, `set_tuner_input()`, `set_tuner_reference()`, `set_tuner_mute()`, `looper()` (states named by `LooperState`) | | **List parameters** | `set_param_option(cell, param, option, source)`, `protocol.param_options(preset, ...)` - includes a block's side-chain SOURCE | diff --git a/docs/domain-model.md b/docs/domain-model.md index 12486a98..e8ca658a 100644 --- a/docs/domain-model.md +++ b/docs/domain-model.md @@ -1143,11 +1143,10 @@ tried rather than just what is unknown. ### Genuinely open - **`RecallPreset.reason` UNDO.** The value exists in the schema and has never been - observed. It may be unreachable on this firmware: there is **no grid-level undo on the - unit** - the only UNDO is Looper X's, which is a Looper action and not a preset recall - - so nothing found so far can cause a recall whose reason is UNDO. `UndoRedo` messages do - arrive after accepted edits and carry a per-slot frame count, so the undo machinery is - real; what is missing is any way for a human or a host to trigger it. + observed. The protocol client can trigger grid-level undo with an + `UndoRedo{UPDATE, undo}` message, confirmed on CorOS 4.0.1 and 4.1.0, but that + operation did not produce a recalled preset carrying reason UNDO. The reason's + meaning therefore remains open even though host-driven undo itself does not. - **Bypass persistence over MIDI.** The unit's own SCENE BYPASS BEHAVIOR wording groups **MIDI with footswitches**, not with the touchscreen - a distinction the manual's summary omits. A USB HID write was measured and behaves like the touchscreen, but the MIDI half @@ -1297,7 +1296,7 @@ the n/a rows below where they intersect the API at all. | Looper X: parameters | `LooperBlock.params` | yes | | | Looper X: transport actions | **omitted**; `LooperBlock.state` is readable | partly | transport is not drivable over USB; MIDI CC#48-61 is the documented route | | Assign Looper X Actions (footswitch layout) | `device.settings.looper_actions` | yes | `GeneralSettings.looper_stomp_assignments` - GLOBAL, not per preset. Eight entries indexed by footswitch, each the Looper X parameter index. The MIDI CC follows the action, not the switch | -| Undo / redo | **omitted** | no | `UndoRedo` arrives as an acceptance signal only; never driven | +| Undo / redo | **omitted from the model** | yes | the protocol client's `undo()` / `redo()` reversed and reapplied a bypass edit on CorOS 4.0.1 and 4.1.0; a model-level history surface is not designed yet | ## Chapter 5 - The Directory @@ -1372,7 +1371,7 @@ the n/a rows below where they intersect the API at all. | GIG VIEW ACCESS | `settings.gig_view_access` | yes | | | LATENCY COMPENSATION | `settings.latency_compensation` | yes | | | MIDI submenu | `settings.midi` | partly | see ch. 8 row | -| Device name | **omitted** | no | candidates `Serialization`/`GeneralSettings`, unexplored | +| Device name | **omitted from the model** | yes | protocol `set_device_name()` is confirmed on CorOS 4.0.1 and 4.1.0; a model-level identity editor is not designed yet | | Firmware and serial (Device Information) | `device.firmware`, `device.serial` | yes | | | Diagnostics / Send Report | **omitted** | no | decoded but never driven | | 3rd-party licenses | - | n/a | reference text | @@ -1383,13 +1382,13 @@ the n/a rows below where they intersect the API at all. |---|---|---|---| | USB audio channels, DI vs processed, host monitoring | `io.usb` covers the on-unit controls | partly | channel-map routing choices live in unexplored `IOSettings`; host driver/DAW concerns are n/a | | Everything Cortex Control mirrors from the unit | the same objects above | n/a | this library is an alternative client to the same protocol | -| CC-only: device name display/edit | **omitted** | no | see Device name row | +| CC-only: device name display/edit | **omitted from the model** | yes | see Device name row; available through the protocol client | | CC-only: per-scene tempo claim | **omitted** | n/a | contradicts the unit; on-unit presentation wins | | CC-only: preset / plugin-preset / IR import from computer | **omitted** | no | candidate `File` with payloads; the import flow is unsolved (and IR import probing is hazardous - see CLAUDE.md) | | CC-only: local backups | **omitted** | no | `LocalBackup` unexplored | | CC-only: CorOS update via USB | **omitted** - permanently | no | `Updater` | | CC-only: keyboard shortcuts, window sizing | - | n/a | app UI | -| CC-only: undo/redo shortcuts | **omitted** | no | see Undo/redo row | +| CC-only: undo/redo shortcuts | **omitted from the model** | yes | see Undo/redo row; available through the protocol client | --- diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index cdff4c2c..4e6260bf 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -22,10 +22,10 @@ or a field in `BinaryPreset`. A named candidate is a lead, not a claim that it w Of 105 features audited: **68 yes**, **7 partly**, **19 no**, **11 n/a**. -Of the 93 features a host could plausibly drive - everything above except the 11 marked +Of the 94 features a host could plausibly drive - everything above except the 11 marked n/a - **68 are fully covered** and 7 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the -same shape but not individually exercised. Only 20 remain untouched. +same shape but not individually exercised. Only 19 remain untouched. Both paragraphs now count the same table. They had drifted apart: this one still read 91/65/13/14 from an earlier revision, which no longer matched a row-by-row count. @@ -185,7 +185,7 @@ on 25, 9 and 56 as `led_brightness` was 28, 13 and 59). | STOMP MODE BYPASS (auto-assign on load) | yes | `update_settings(stomp_mode_auto_assign=...)`, confirmed writable | | HOLD TIMING, SWAP TEMPO AND TUNER, GIG VIEW ACCESS | yes | all three confirmed writable via `update_settings()`. `set_hold_timing()` takes `Milliseconds` and writes the index the device stores - the unit offers 500-1000 ms in 100 ms steps and the field is the index, confirmed by reading 3 while the screen showed 800 ms. `hold_timing_ms()` reads it back | | LATENCY COMPENSATION | yes | `update_settings(enable_dynamic_delay_compensation=...)`, confirmed writable | -| Device name | yes | `set_device_name()` sends sparse `Version{UPDATE, custom_name}`; live read-back matched, and restoring the prior name survived reconnect | +| Device name | yes | `set_device_name()` sends sparse `Version{UPDATE, custom_name}`; read-back and restoration matched on CorOS 4.0.1 and 4.1.0. Reconnect persistence has not been tested | | Firmware and serial | yes | `version()` | | Diagnostics (DSP, footswitches, USB) | no | `ModuleStats` is decoded and subscribed; `Diagnostics`, `DSPCommsDiagnostics` are not | | CorOS updates | no | `Updater` is decoded and subscribed; never driven. Risky to explore | diff --git a/docs/protocol.md b/docs/protocol.md index 590cf7d7..eb443755 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -2739,7 +2739,10 @@ visually on the device's own screen. | Operation | Wire shape (brief) | Verified by | Notes | |---|---|---|---| | connect handshake | `ResetCommsBuffers` + `Version` UPDATE + `ModelRepo` READ + `Connection` + subscribe READs | read-back | the connect gate; state pushes flow only after it | -| version read | `Version{action: READ}` | read-back | serial and firmware returned. TWO messages come back: the `UPDATE` with fifteen fields, then the device's own `Version{READ}` 0.5-0.8 ms later | +| version read | `Version{action: READ}` | read-back | serial and firmware returned on 4.0.1 and 4.1.0. TWO messages come back: the `UPDATE` with fifteen fields, then the device's own bare `Version{READ}` about 1 ms later; `version()` filters out that echo | +| `set_device_name` | `Version{UPDATE, custom_name}` | read-back + on-unit | sparse echo, read-back, and restoration confirmed on CorOS 4.0.1 and 4.1.0 / firmware d14e | +| `undo` / `redo` | `UndoRedo{UPDATE, undo}` / `{UPDATE, redo}` | read-back + on-unit | a bypass edit was reversed and reapplied on disposable preset copies on CorOS 4.0.1 and 4.1.0 / firmware d14e; empty-history behaviour is unknown | +| `inhibited_modules` | `CompilerInhibitedModules{READ}` | read-back | explicit false/false reply `08 01 18 00 20 00` on CorOS 4.0.1 and 4.1.0 / firmware d14e; true semantics are schema-derived, not yet observed | | `recall_preset` / `read_preset` | `SetlistPosition{UPDATE, folder_key, position, is_factory, request_id}` then a `RecallPreset` push | read-back | the push echoes the recall's `request_id` | | `read_current_preset` / `read_current_preset_push` | `RecallPreset{READ, request_id}` | read-back | the live grid, no side effects. The push variant hands back the whole reply, which carries `reason` beside the preset | | `loaded_position` | `SetlistPosition{READ, request_id}` | read-back | which slot is loaded; 3 ms measured. A READ names no slot - an UPDATE that did would recall it | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 6ee2fba2..ba391001 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -458,10 +458,18 @@ def version(self, timeout: float = 10.0): ``device_serial_number``, and ``comms_version``. Works without the connect handshake, so it is a good first call to - confirm the device is talking. + confirm the device is talking. The unit follows the full reply with a + bare ``Version{READ}`` echo about 1 ms later; this reader requires + ``device_serial_number`` so that echo can never be returned as an empty + identity. Confirmed on CorOS 4.0.1 and 4.1.0, firmware d14e. """ return self._t.request( - pa.VersionMessage(action=pa.MessageAction.READ), timeout=timeout + pa.VersionMessage(action=pa.MessageAction.READ), + timeout=timeout, + match=lambda m: ( + m.action == pa.MessageAction.UPDATE + and m.HasField("device_serial_number") + ), ) def set_device_name(self, name: str): @@ -469,19 +477,32 @@ def set_device_name(self, name: str): The update is deliberately sparse: only ``custom_name`` is sent, so none of the other version/identity fields can be overwritten. + Confirmed on CorOS 4.0.1 and 4.1.0, firmware d14e: the unit echoed a + sparse Version UPDATE, and read-back and restoration matched. """ + if not isinstance(name, str): + raise TypeError("name must be a string") self._t.send(pa.VersionMessage( - action=pa.MessageAction.UPDATE, custom_name=str(name) + action=pa.MessageAction.UPDATE, custom_name=name )) def undo(self): - """Undo the most recent editable-preset operation.""" + """Undo the most recent editable-preset operation. + + Confirmed on CorOS 4.0.1 and 4.1.0, firmware d14e: a bypass edit was + reversed. Behaviour when the edit history is empty is not established. + """ self._t.send(pa.UndoRedoMessage( action=pa.MessageAction.UPDATE, undo=True )) def redo(self): - """Redo the most recently undone editable-preset operation.""" + """Redo the most recently undone editable-preset operation. + + Confirmed on CorOS 4.0.1 and 4.1.0, firmware d14e: the bypass edit + reversed by :meth:`undo` was reapplied. Behaviour when the edit history + is empty is not established. + """ self._t.send(pa.UndoRedoMessage( action=pa.MessageAction.UPDATE, redo=True )) @@ -2596,15 +2617,15 @@ def global_eq(self, timeout: float = 10.0): def inhibited_modules(self, timeout: float = 10.0): """Whether DSP load has automatically disabled the Input Gate or Global EQ. - Returns the raw ``CompilerInhibitedModules`` message. ``global_gate`` and - ``global_eq`` are true while the corresponding global module is inhibited. - Both fields are required in the reply so an absent optional field is never - mistaken for an explicit false. + Returns the raw ``CompilerInhibitedModules`` message. The schema names + ``global_gate`` and ``global_eq`` as the corresponding inhibited states; + only the explicit false/false reply has been observed. Both fields are + required so an absent optional field is never mistaken for false. Confirmed read-only on hardware: a ``CompilerInhibitedModules{READ}`` - returned an UPDATE carrying both explicit false fields on Quad Cortex, - CorOS 4.1.0 / firmware d14e. The same message type was already observed - arriving after grid edits when DSP load changes the inhibited state. + returned ``08 01 18 00 20 00`` with both fields explicit on Quad Cortex, + CorOS 4.0.1 and 4.1.0 / firmware d14e. The same message type was already + observed after grid edits when DSP load changes the inhibited state. """ return self._read_state( pa.CompilerInhibitedModulesMessage, diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index d06f317f..faa73399 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -123,7 +123,8 @@ def __init__(self, device, keepalive_interval=5.0): self._dev = device self._keepalive_interval = keepalive_interval self._ids = itertools.count(1) - self._pending = {} # request_id -> (Event, [response|None], request class) + # request_id -> (Event, [response|None], request class, reply predicate) + self._pending = {} # Waiters for UNSOLICITED device broadcasts, matched by message class # (e.g. the RecallPreset push the device emits when a preset is # recalled - it carries no request_id to correlate on). List of @@ -203,7 +204,7 @@ def _confirm_lost(self, error): waiters, self._type_waiters = self._type_waiters, [] # Slots stay None; the woken callers see device_lost set and raise # DeviceLostError instead of returning None or waiting out a timeout. - for ev, _slot, _cls in pending.values(): + for ev, _slot, _cls, _match in pending.values(): ev.set() for _cls, _match, ev, _slot in waiters: ev.set() @@ -283,7 +284,7 @@ def next_request_id(self): with self._lock: return next(self._ids) - def request(self, message, timeout=5.0): + def request(self, message, timeout=5.0, match=None): """Send ``message`` and block until the matching response arrives. Assigns a fresh ``request_id``, registers a waiter BEFORE writing (so a @@ -297,8 +298,10 @@ def request(self, message, timeout=5.0): request triggers a cascade of OTHER-type messages that all echo the request's id (recalling a preset emits UndoRedo/Grid/Scene/... all with the same request_id before the SetlistPosition echo). So the reply is - the first inbound message whose TYPE matches the request's, and whose - request_id - if present on both sides - matches too. + the first inbound message whose TYPE matches the request's, whose + request_id - if present on both sides - matches too, and which satisfies + the optional ``match`` predicate. A same-type message rejected by the + predicate is left unmatched while the request keeps waiting. Refused when called from the RX thread, where it could only ever time out (see ``_refuse_read_from_rx``). @@ -309,7 +312,7 @@ def request(self, message, timeout=5.0): slot = [None] with self._lock: rid = next(self._ids) - self._pending[rid] = (ev, slot, type(message)) + self._pending[rid] = (ev, slot, type(message), match) message.request_id = rid try: self.send(message) @@ -749,18 +752,18 @@ def _dispatch(self, message): with self._lock: entry = None if rid is not None and rid in self._pending: - _ev, _slot, cls = self._pending[rid] - if cls is type(message): + _ev, _slot, cls, match = self._pending[rid] + if cls is type(message) and (match is None or match(message)): entry = self._pending.pop(rid) if entry is None and rid is None: # No id on the reply (READ replies): first same-type waiter wins. for pending_rid in sorted(self._pending): - _ev, _slot, cls = self._pending[pending_rid] - if cls is type(message): + _ev, _slot, cls, match = self._pending[pending_rid] + if cls is type(message) and (match is None or match(message)): entry = self._pending.pop(pending_rid) break if entry is not None: - ev, slot, _cls = entry + ev, slot, _cls, _match = entry slot[0] = message ev.set() return diff --git a/tests/hardware/readme.md b/tests/hardware/readme.md index de387627..f12ef6b2 100644 --- a/tests/hardware/readme.md +++ b/tests/hardware/readme.md @@ -7,10 +7,10 @@ that **a successful run leaves the unit exactly as it found it**. pytest tests/hardware --hardware ``` -The native undo/redo test has a second guard because it needs a disposable -loaded preset. Set `PYQUADCORTEX_UNDO_SCRATCH_SLOT` to that preset's zero-based -slot index; the test refuses to run if a different slot is loaded or the preset -already has unsaved changes. +The native undo/redo test makes its own disposable copy of the loaded preset in +an empty My Presets slot, edits that copy, recalls the original, and deletes the +copy. Saving the copy resets its instrument tag and default scene; those changes +exist only on the disposable preset. `pytest --hardware` from the repo root works too, since the rename described below, and it runs BOTH suites - the offline one and this one, against your unit. @@ -66,8 +66,9 @@ collecting under the flag, so the rule does not depend on being remembered. - **Quit Cortex Control.** It holds the USB HID interface exclusively. - Expect the unit to be edited. Every test snapshots what it touches and restores it in teardown, pass or fail, but the edits are real while they happen. -- Nothing here saves a preset, so the unsaved-edit escape hatch still applies: if - a run dies badly, recalling any preset discards whatever it left on the grid. +- The undo/redo test saves a disposable preset and resets that copy's instrument + tag and default scene. It registers independent cleanup steps to recall the + original and delete the copy even when another restore step fails. ## If a restore fails diff --git a/tests/hardware/test_identity_and_history.py b/tests/hardware/test_identity_and_history.py index 0cbe6cc4..1c08298e 100644 --- a/tests/hardware/test_identity_and_history.py +++ b/tests/hardware/test_identity_and_history.py @@ -1,19 +1,21 @@ """Reversible device-name and edit-history checks against a real unit.""" -import os import time import pytest from pyquadcortex import protocol -from pyquadcortex.protocol import Block +from pyquadcortex.protocol.enums import Setlist SETTLE = 1.0 def test_device_name_round_trips_and_is_restored(qc): - before = qc.version().custom_name + identity = qc.version() + if not identity.HasField("custom_name"): + pytest.skip("the unit has no device name to restore without inventing one") + before = identity.custom_name probe = "pyquadcortex probe" if before == probe: probe = "pyquadcortex probe 2" @@ -29,56 +31,69 @@ def test_device_name_round_trips_and_is_restored(qc): assert qc.version().custom_name == before -def test_undo_and_redo_reverse_and_reapply_a_scratch_edit(qc): - """Opt-in twice: --hardware plus the exact disposable slot in the env.""" - configured = os.environ.get("PYQUADCORTEX_UNDO_SCRATCH_SLOT") - if configured is None: - pytest.skip("set PYQUADCORTEX_UNDO_SCRATCH_SLOT to a disposable loaded slot") +def test_undo_and_redo_reverse_and_reapply_a_scratch_edit(qc, restores): + """Create, edit, and remove a test-owned copy of the loaded preset.""" + original = qc.loaded_position() + for field in ("folder_key", "position", "is_factory"): + assert original.HasField(field), f"loaded position omitted {field}" + original_scene = int(qc.active_scene()) - position = qc.loaded_position() - expected = int(configured) - assert position.position == expected, ( - f"scratch slot {expected} is configured, but slot {position.position} is loaded" + scratch_name = "pyquadcortex undo probe" + slots = qc.list_presets(Setlist.USER, include_empty=True) + assert not any(e.HasField("name") and e.name == scratch_name for e in slots), ( + f"delete the existing {scratch_name!r} preset before running this test" ) - assert qc.preset_dirty() is False, ( - "save or reload the scratch preset first" + empty = next((e for e in slots + if e.HasField("index") + and (not e.HasField("name") or not e.name)), None) + if empty is None: + pytest.skip("My Presets has no empty slot for the disposable copy") + + def delete_scratch(): + qc.delete_preset(Setlist.USER, scratch_name) + qc.wait_for_listing( + Setlist.USER, + until=lambda entries: not any( + e.HasField("name") and e.name == scratch_name for e in entries + ), + timeout=30.0, + ) + + restores("delete the undo-test scratch preset", delete_scratch) + restores("restore the original active scene", + lambda: qc.switch_scene(original_scene)) + restores("recall the originally loaded preset", lambda: qc.read_preset( + original.folder_key, original.position, + is_factory=original.is_factory, timeout=30.0, + )) + + stored = qc.save_current_preset( + Setlist.USER, empty.index, scratch_name, + confirm=True, confirm_timeout=30.0, ) - - target = Block(0, 6) - before_preset = qc.read_current_preset() + assert stored == scratch_name, "the disposable copy was not confirmed" + before_preset = qc.read_preset(Setlist.USER, empty.index, timeout=30.0) + occupied = protocol.blocks(before_preset) + if not occupied: + pytest.skip("the loaded preset has no block whose bypass can be edited") + target = occupied[0] before_scene = int(qc.active_scene()) before = protocol.bypass_state(before_preset, target).scenes[before_scene] - name = before_preset.name - - try: - qc.set_bypass(target, not before) - time.sleep(SETTLE) - assert protocol.bypass_state( - qc.read_current_preset(), target - ).scenes[before_scene] is not before - qc.undo() - time.sleep(SETTLE) - assert protocol.bypass_state( - qc.read_current_preset(), target - ).scenes[before_scene] is before - - qc.redo() - time.sleep(SETTLE) - assert protocol.bypass_state( - qc.read_current_preset(), target - ).scenes[before_scene] is not before - finally: - now = protocol.bypass_state( - qc.read_current_preset(), target - ).scenes[before_scene] - if now is not before: - qc.set_bypass(target, before) - time.sleep(SETTLE) - qc.save_current_preset(position.folder_key, position.position, name, - confirm=True, confirm_timeout=30.0) + qc.set_bypass(target, not before) + time.sleep(SETTLE) + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is not before + qc.undo() + time.sleep(SETTLE) assert protocol.bypass_state( qc.read_current_preset(), target ).scenes[before_scene] is before - assert qc.preset_dirty() is False + + qc.redo() + time.sleep(SETTLE) + assert protocol.bypass_state( + qc.read_current_preset(), target + ).scenes[before_scene] is not before diff --git a/tests/hardware/test_settings_values.py b/tests/hardware/test_settings_values.py index 8600d15a..879c7449 100644 --- a/tests/hardware/test_settings_values.py +++ b/tests/hardware/test_settings_values.py @@ -37,13 +37,13 @@ def test_inhibited_modules_is_a_complete_read_only_snapshot(qc): Presence matters here: protobuf also returns false when an optional field was never sent, and reporting that default as device state would be a guess. """ + # Read twice because a first state READ can be dropped; both successful + # replies must carry explicit fields rather than protobuf defaults. for _ in range(2): state = qc.inhibited_modules() assert state.action == pa.MessageAction.UPDATE assert state.HasField("global_gate") assert state.HasField("global_eq") - assert isinstance(state.global_gate, bool) - assert isinstance(state.global_eq, bool) def _input_level(qc, port_id): diff --git a/tests/test_client.py b/tests/test_client.py index 14bbdc0c..9506107a 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -35,8 +35,9 @@ def __init__(self, canned=None): def send(self, msg): self.sent.append(msg) - def request(self, msg, timeout=5.0): + def request(self, msg, timeout=5.0, match=None): self.sent.append(msg) + self.last_match = match return self.canned.get(type(msg).__name__) def next_request_id(self): @@ -463,6 +464,29 @@ def test_move_preset_sends_file_move(): # -- session hello ------------------------------------------------------------- +def test_version_requires_the_full_update_and_ignores_the_trailing_read_echo(): + full = pa.VersionMessage( + action=pa.MessageAction.UPDATE, + device_serial_number="QCS0000001", + app_fw_version="d14e", + ) + fake = FakeTransport({"VersionMessage": full}) + qc = client.QuadCortex(fake) + + assert qc.version(timeout=3.5) is full + sent = fake.sent[-1] + assert isinstance(sent, pa.VersionMessage) + assert sent.action == pa.MessageAction.READ + assert not sent.HasField("request_id") # the fake records before Transport assigns it + assert fake.last_match(full) is True + assert fake.last_match(pa.VersionMessage( + action=pa.MessageAction.READ, + )) is False + assert fake.last_match(pa.VersionMessage( + action=pa.MessageAction.UPDATE, + )) is False + + def test_set_device_name_sends_a_sparse_version_update(): qc = client.QuadCortex(FakeTransport()) @@ -472,6 +496,10 @@ def test_set_device_name_sends_a_sparse_version_update(): assert isinstance(sent, pa.VersionMessage) assert sent.SerializeToString() == b"\x08\x01\x7a\x08Stage QC" + with pytest.raises(TypeError): + qc.set_device_name(None) + assert qc._t.sent[-1] is sent + def test_undo_and_redo_send_the_confirmed_sparse_updates(): qc = client.QuadCortex(FakeTransport()) diff --git a/tests/test_device.py b/tests/test_device.py index 60cefc55..4feb1b50 100644 --- a/tests/test_device.py +++ b/tests/test_device.py @@ -82,12 +82,14 @@ def __init__(self, canned, trailing=()): def send(self, msg): self.sent.append(msg) - def request(self, msg, timeout=5.0): + def request(self, msg, timeout=5.0, match=None): self.sent.append(msg) reply = self.canned[type(msg).__name__] for message in [reply] + self.trailing: for listener in list(self.listeners): listener(message) # listeners see a reply first (ADR-0009) + if match is not None and not match(reply): + raise TimeoutError(f"canned {type(reply).__name__} did not match") return reply def add_listener(self, listener): diff --git a/tests/test_docs.py b/tests/test_docs.py index c505b0af..be593cd7 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -22,7 +22,7 @@ def test_code_fences_are_balanced(doc): """An odd fence count means a section is rendering inside a code block.""" if not doc.exists(): pytest.skip(f"{doc.name} not present") - opens = sum(1 for line in doc.read_text().splitlines() + opens = sum(1 for line in doc.read_text(encoding="utf-8").splitlines() if line.startswith("```")) assert opens % 2 == 0, ( f"{doc.name} has {opens} fence lines - one is unclosed, and everything " @@ -31,7 +31,7 @@ def test_code_fences_are_balanced(doc): def _api_table_rows() -> str: - text = (ROOT / "docs" / "api.md").read_text() + text = (ROOT / "docs" / "api.md").read_text(encoding="utf-8") section = text[text.index("## Method groups"):text.index("**Rows and columns")] return "\n".join(line for line in section.splitlines() if line.startswith("|")) # table rows only, not prose @@ -118,7 +118,7 @@ def _drop_before_blocks(snippet): def _python_snippets(path): """Every ```python fence in a .md, or every ``::`` block in a .py docstring.""" - text = path.read_text() + text = path.read_text(encoding="utf-8") if path.suffix == ".md": return [_drop_before_blocks(f) for f in re.findall(r"```python\n(.*?)```", text, re.DOTALL)] diff --git a/tests/test_namespace.py b/tests/test_namespace.py index 17d5702b..23abde02 100644 --- a/tests/test_namespace.py +++ b/tests/test_namespace.py @@ -81,9 +81,9 @@ def test_the_pre_flip_snapshot_is_byte_for_byte_what_0_40_0_shipped(): drops a name is to delete that name from here. Pinning the hash means the fixture and the export list can only be changed together and on purpose. """ - # Git may check a text fixture out with CRLF on Windows. The pinned source - # was committed with LF, so normalize that one permitted text conversion - # while keeping every content byte under the hash. + # .gitattributes pins fresh checkouts to LF. Normalize defensively for a + # worktree created before that rule existed, then keep every content byte + # under the hash. content = PRE_FLIP_INIT.read_bytes().replace(b"\r\n", b"\n") digest = hashlib.sha256(content).hexdigest() assert digest == PRE_FLIP_INIT_SHA256, ( diff --git a/tests/test_state.py b/tests/test_state.py index 7e7c2a01..f8499aaa 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -97,7 +97,7 @@ def await_broadcast(self, message_class, trigger, timeout=5.0, match=None): self.push(reply) return reply - def request(self, message, timeout=5.0): + def request(self, message, timeout=5.0, match=None): name = type(message).__name__ self.sent.append(message) self.reads[name] += 1 @@ -109,6 +109,8 @@ def request(self, message, timeout=5.0): if callable(reply): reply = reply() self.push(reply) # every listener sees it first... + if match is not None and not match(reply): + raise TimeoutError(f"the canned {name} did not satisfy the waiter") return reply # ...and only then does the caller wake # -- the unit's side ------------------------------------------------------ @@ -757,19 +759,18 @@ def test_a_second_access_of_the_same_entry_costs_no_round_trip(link): assert transport.reads["VersionMessage"] == 1 -def test_a_read_replaces_the_entry_rather_than_merging_into_it(link): - """A read is the unit's whole answer, so a field it does not carry is a - field the unit did not confirm. Leaving the old value in place would report - something no read has returned.""" +def test_an_incomplete_version_update_does_not_complete_the_read(link): + """A partial Version UPDATE may warm the cache, but is not a full reply.""" transport, cache = link assert cache.value("identity", "device_serial_number") == "QCS0000001" cache.mark_for_reread("identity", "this test") transport.replies["VersionMessage"] = lambda: version_reply( app_fw_version="d15a") - assert cache.value("identity", "app_fw_version") == "d15a" - with pytest.raises(RuntimeError, match="device_serial_number"): - cache.value("identity", "device_serial_number") + with pytest.raises(TimeoutError): + cache.value("identity", "app_fw_version") + assert cache.cached("identity")["app_fw_version"] == "d15a" + assert cache.needs_read("identity") is True def test_a_field_the_unit_did_not_send_is_refused_not_reported_empty(link): @@ -778,7 +779,7 @@ def test_a_field_the_unit_did_not_send_is_refused_not_reported_empty(link): transport, cache = link transport.replies["VersionMessage"] = lambda: version_reply( app_fw_version="d14e") - with pytest.raises(RuntimeError, match="device_serial_number"): + with pytest.raises(TimeoutError): cache.value("identity", "device_serial_number") @@ -786,7 +787,7 @@ def test_an_incomplete_answer_leaves_a_retry_able_to_recover(link): transport, cache = link transport.replies["VersionMessage"] = lambda: version_reply( app_fw_version="d14e") - with pytest.raises(RuntimeError): + with pytest.raises(TimeoutError): cache.value("identity", "device_serial_number") transport.replies["VersionMessage"] = full_version_reply @@ -801,7 +802,7 @@ def test_the_field_the_unit_did_send_is_still_answered_from_the_cache(link): transport, cache = link transport.replies["VersionMessage"] = lambda: version_reply( app_fw_version="d14e") - with pytest.raises(RuntimeError): + with pytest.raises(TimeoutError): cache.value("identity", "device_serial_number") assert cache.value("identity", "app_fw_version") == "d14e" @@ -1277,7 +1278,9 @@ def test_a_write_that_races_the_close_leaves_no_thread_behind(link): cache._watchdog.add(_a_watch_for_the_race()) - assert set(_watchdog_threads()) == existing + # A watchdog from another test may finish during a combined offline + + # hardware run; the invariant is that this operation starts no NEW thread. + assert set(_watchdog_threads()) <= existing def _a_watch_for_the_race(): @@ -1298,10 +1301,12 @@ def test_the_watchdog_firing_as_the_connection_closes_does_not_raise(link): def test_no_watchdog_runs_until_something_is_written(link): transport, cache = link + # Baseline other live caches in a combined offline + hardware run. Some may + # finish during this test; only a newly-created watchdog would be a failure. existing = set(_watchdog_threads()) cache.value("identity", "app_fw_version") transport.push(dirty_push(True)) - assert set(_watchdog_threads()) == existing + assert set(_watchdog_threads()) <= existing def _watchdog_threads(): diff --git a/tests/test_transport.py b/tests/test_transport.py index a7d29fe0..b9a9a32f 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -135,6 +135,41 @@ def test_request_response_round_trip(): assert resp.request_id == 1 # first id from itertools.count(1) +def test_request_match_ignores_a_same_type_echo_and_waits_for_full_reply(): + class EchoThenFull(FakeHid): + def write(self, report): + report = bytes(report) + self.writes.append(report) + frame = framing.decode_reports([report]) + request = pa.VersionMessage() + request.ParseFromString(frame.payload) + echo = pa.VersionMessage(action=pa.MessageAction.READ) + full = pa.VersionMessage( + action=pa.MessageAction.UPDATE, + device_serial_number="QCS0000001", + ) + for response in (echo, full): + self.inject(*framing.encode_message( + registry.type_for(pa.VersionMessage), + response.SerializeToString(), + )) + return len(report) + + fake = EchoThenFull() + t = transport.Transport(fake, keepalive_interval=QUIET_KEEPALIVE) + t.start() + try: + reply = t.request( + pa.VersionMessage(action=pa.MessageAction.READ), + timeout=REQUEST_TIMEOUT, + match=lambda message: message.HasField("device_serial_number"), + ) + finally: + t.stop() + + assert reply.device_serial_number == "QCS0000001" + + def test_multi_report_reassembly(): # A 300-char kernel-version string makes the response payload > 128 bytes so # it spans multiple input reports; the transport must reassemble them. diff --git a/tests/test_values.py b/tests/test_values.py index 3e4825cc..dec93004 100644 --- a/tests/test_values.py +++ b/tests/test_values.py @@ -217,7 +217,8 @@ def test_a_floor_is_typed_whether_it_was_measured_or_derived(): def _generated_constants(): return [m for m in (CONSTANT.match(line) - for line in PARAMS_PY.read_text().splitlines()) if m] + for line in PARAMS_PY.read_text( + encoding="utf-8").splitlines()) if m] def _spellings_the_device_publishes(): From cb4d96ee871e66a5924655ab9118e359b710f981 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Tue, 8 Sep 2026 12:27:36 +0300 Subject: [PATCH 5/7] Respect profile-specific version announce behavior --- tests/hardware/test_model_state.py | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/tests/hardware/test_model_state.py b/tests/hardware/test_model_state.py index db4698ef..dca0e4f5 100644 --- a/tests/hardware/test_model_state.py +++ b/tests/hardware/test_model_state.py @@ -174,9 +174,8 @@ def test_nothing_the_burst_delivered_is_read_again_on_first_access( "again, which is the round trip the cache exists to avoid") -def test_the_burst_warms_identity_from_connects_own_version_read(burst_warmed, - handshake_burst, - record_property): +def test_connects_version_read_warms_identity_with_profile_specific_announce( + qc, burst_warmed, handshake_burst, record_property): """Identity reaches the cache through the ONE Version READ connect() makes. The unit never volunteers its identity, so the model reads it (section 9's @@ -187,7 +186,9 @@ def test_the_burst_warms_identity_from_connects_own_version_read(burst_warmed, its burst - the full reply to connect's READ (15 fields, +0.71 s), the unit's own ``Version{READ}`` about 1 ms behind it (the question it asks Cortex Control, section 4.4), and the ``UPDATE`` carrying - ``cortex_control_version_valid`` that answers our announce (+0.73 s). + ``cortex_control_version_valid`` that answers our announce (+0.73 s). Four + fresh CorOS 4.1.0 connections on 2026-09-04 carried the full reply and unit + READ but no announce answer, while the subscribed state burst still arrived. ``_hello`` itself still sends no READ; the 2026-08-27 measurement of one inbound ``Version`` stands for ``_hello`` alone. @@ -209,8 +210,15 @@ def test_the_burst_warms_identity_from_connects_own_version_read(burst_warmed, if s[0] == pa.MessageAction.READ and s[1] == {"action"}] announce = [s for s in shapes if "cortex_control_version_valid" in s[1]] record_property("identity_reads", len(full)) - assert len(announce) == 1, ( - f"{len(announce)} answers to our version announce; one is measured. " + factory_count = len(qc.catalog.factory_models()) + record_property("connect_burst_factory_model_count", factory_count) + expected_announces = {412: 1, 420: 0} + assert factory_count in expected_announces, ( + f"the connected unit exposes {factory_count} factory models, so its " + f"connect-burst Version behavior has not been measured") + assert len(announce) == expected_announces[factory_count], ( + f"the {factory_count}-factory-model profile sent {len(announce)} " + f"announce answers, not the measured {expected_announces[factory_count]}. " f"Shapes seen: {shapes}") assert full, ( f"no full Version reply reached the listener: connect() stopped reading " @@ -219,7 +227,7 @@ def test_the_burst_warms_identity_from_connects_own_version_read(burst_warmed, assert len(own_reads) == len(full), ( f"{len(full)} full replies but {len(own_reads)} unit READs; the unit asks " f"its own question once per answer (protocol.md 4.4). Shapes: {shapes}") - assert len(shapes) == len(full) + len(own_reads) + 1, ( + assert len(shapes) == len(full) + len(own_reads) + len(announce), ( f"a Version of a shape this test does not know arrived - the handshake " f"changed under us. Shapes: {shapes}") assert set(burst_warmed["identity"]) == {"device_serial_number", "app_fw_version"}, ( From f0ac2e4039d058ca4fa96efea920f641c9ac9194 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Sat, 19 Sep 2026 22:44:18 +0300 Subject: [PATCH 6/7] Update manual coverage totals --- docs/manual-coverage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 328f514e..f3a6fa00 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -18,10 +18,10 @@ A "candidate" names a message type from the unit's own schema or a field in ## Summary -Of 105 features audited: **65 yes**, **9 partly**, **20 no**, **11 n/a**. +Of 105 features audited: **68 yes**, **8 partly**, **18 no**, **11 n/a**. -Of the 94 features a host could plausibly drive, 65 are fully covered and 9 are -partly covered. Twenty remain untouched. Of those, a few are writes confirmed to +Of the 94 features a host could plausibly drive, 68 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 Capture, and loading from the factory Captures Library. How an unknown gets From 68be881f35b7f56742303b0b768c76969da5663c Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Tue, 22 Sep 2026 10:50:23 +0300 Subject: [PATCH 7/7] Address maintainer hardware review --- pyquadcortex/protocol/profiles.py | 5 +- pyquadcortex/protocol/transport.py | 25 ++++----- tests/hardware/readme.md | 11 ++-- tests/hardware/test_identity_and_history.py | 58 +++++---------------- tests/hardware/test_model_state.py | 22 +++----- tests/test_hardware_markers.py | 12 ++--- tests/test_profiles.py | 4 +- tests/test_session.py | 2 +- tests/test_transport.py | 35 ------------- tests/test_writing.py | 2 +- 10 files changed, 50 insertions(+), 126 deletions(-) diff --git a/pyquadcortex/protocol/profiles.py b/pyquadcortex/protocol/profiles.py index 7e78d135..ea700aa0 100644 --- a/pyquadcortex/protocol/profiles.py +++ b/pyquadcortex/protocol/profiles.py @@ -23,7 +23,8 @@ class QuadCortex41(QuadCortex): passed, 8 skipped, on a Quad Cortex running CorOS 4.1.0 / app firmware d14e, by tony-xmelon. That is a contributor's report and the maintainer has not reproduced it, which is what ``Evidence.CONTRIBUTED`` says here. - ``create_local_backup`` has its own dated 4.1.0 capture and is VERIFIED; + ``create_local_backup`` has its own dated 4.1.0 capture. The contributed + device-name round trip also verified ``set_device_name``; both are VERIFIED. other inherited operations refuse under ``Support.VERIFIED`` and run with a warning under ``Support.EXPERIMENTAL``. The snapshot is deliberately absent: binding the 4.0.1 constants would hand a 4.1 user names their unit does not @@ -42,7 +43,7 @@ class QuadCortex41(QuadCortex): MEASURED_ON = ("4.1.0",) EVIDENCE = Evidence.CONTRIBUTED - VERIFIED = frozenset({"create_local_backup"}) + VERIFIED = frozenset({"create_local_backup", "set_device_name"}) models = NoSnapshot("coros_4_1_0") params = NoSnapshot("coros_4_1_0") options = NoSnapshot("coros_4_1_0") diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index 5796194e..2bba42c0 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -123,8 +123,7 @@ def __init__(self, device, keepalive_interval=5.0): self._dev = device self._keepalive_interval = keepalive_interval self._ids = itertools.count(1) - # request_id -> (Event, [response|None], request class, reply predicate) - self._pending = {} + self._pending = {} # request_id -> (Event, [response|None], request class) # Waiters for UNSOLICITED device broadcasts, matched by message class # (e.g. the RecallPreset push the device emits when a preset is # recalled - it carries no request_id to correlate on). List of @@ -204,7 +203,7 @@ def _confirm_lost(self, error): waiters, self._type_waiters = self._type_waiters, [] # Slots stay None; the woken callers see device_lost set and raise # DeviceLostError instead of returning None or waiting out a timeout. - for ev, _slot, _cls, _match in pending.values(): + for ev, _slot, _cls in pending.values(): ev.set() for _cls, _match, ev, _slot in waiters: ev.set() @@ -284,7 +283,7 @@ def next_request_id(self): with self._lock: return next(self._ids) - def request(self, message, timeout=5.0, match=None): + def request(self, message, timeout=5.0): """Send ``message`` and block until the matching response arrives. Assigns a fresh ``request_id``, registers a waiter BEFORE writing (so a @@ -298,10 +297,8 @@ def request(self, message, timeout=5.0, match=None): request triggers a cascade of OTHER-type messages that all echo the request's id (recalling a preset emits UndoRedo/Grid/Scene/... all with the same request_id before the SetlistPosition echo). So the reply is - the first inbound message whose TYPE matches the request's, whose - request_id - if present on both sides - matches too, and which satisfies - the optional ``match`` predicate. A same-type message rejected by the - predicate is left unmatched while the request keeps waiting. + the first inbound message whose TYPE matches the request's, and whose + request_id - if present on both sides - matches too. Refused when called from the RX thread, where it could only ever time out (see ``_refuse_read_from_rx``). @@ -312,7 +309,7 @@ def request(self, message, timeout=5.0, match=None): slot = [None] with self._lock: rid = next(self._ids) - self._pending[rid] = (ev, slot, type(message), match) + self._pending[rid] = (ev, slot, type(message)) message.request_id = rid try: self.send(message) @@ -767,18 +764,18 @@ def _dispatch(self, message): with self._lock: entry = None if rid is not None and rid in self._pending: - _ev, _slot, cls, match = self._pending[rid] - if cls is type(message) and (match is None or match(message)): + _ev, _slot, cls = self._pending[rid] + if cls is type(message): entry = self._pending.pop(rid) if entry is None and rid is None: # No id on the reply (READ replies): first same-type waiter wins. for pending_rid in sorted(self._pending): - _ev, _slot, cls, match = self._pending[pending_rid] - if cls is type(message) and (match is None or match(message)): + _ev, _slot, cls = self._pending[pending_rid] + if cls is type(message): entry = self._pending.pop(pending_rid) break if entry is not None: - ev, slot, _cls, _match = entry + ev, slot, _cls = entry slot[0] = message ev.set() return diff --git a/tests/hardware/readme.md b/tests/hardware/readme.md index c60807f6..161c66fa 100644 --- a/tests/hardware/readme.md +++ b/tests/hardware/readme.md @@ -10,7 +10,9 @@ pytest tests/hardware --hardware ``` The undo/redo test makes a disposable copy of the loaded preset, edits that -copy, then independently restores the original and deletes the copy. +copy, then independently restores the original and deletes the copy. Saving the +copy clears its instrument tag and makes the scene active at save time its +default scene; those metadata changes affect only the disposable copy. `pytest --hardware` from the repo root also works, and runs both suites, the offline one and this one. Name the directory unless you want that. @@ -79,9 +81,10 @@ offline modules do `from waiting import ...`, which works only while pytest puts callables put the grid right and leave the flag set. A session teardown clears it with a recall, and only when the preset was clean before the first test: unsaved edits that were already there are the owner's. -- **It edits a scratch copy.** `scratch_preset` hands a test a disposable copy of - the loaded preset. Nothing here saves a preset, so if a run dies badly, - recalling any preset discards whatever it left on the grid. +- **It edits a scratch copy.** `scratch_preset` saves a disposable copy of the + loaded preset and hands that copy to the test. It never saves over one of the + owner's presets; if a run dies badly, the fixed scratch name identifies the + copy that may need removing. ## Before you run it diff --git a/tests/hardware/test_identity_and_history.py b/tests/hardware/test_identity_and_history.py index 3b02ee1d..3a899731 100644 --- a/tests/hardware/test_identity_and_history.py +++ b/tests/hardware/test_identity_and_history.py @@ -5,9 +5,6 @@ import pytest from pyquadcortex import protocol -from pyquadcortex.protocol.enums import Setlist - - SETTLE = 1.0 @@ -21,60 +18,29 @@ def test_device_name_round_trips_and_is_restored(qc): if before == probe: probe = "pyquadcortex probe 2" + def read_name(): + reply = qc.version() + assert reply.HasField("custom_name"), ( + "the Version reply omitted custom_name, so the name cannot be " + "confirmed or restored") + return reply.custom_name + try: qc.set_device_name(probe) time.sleep(SETTLE) - assert qc.version().custom_name == probe + assert read_name() == probe finally: qc.set_device_name(before) time.sleep(SETTLE) - assert qc.version().custom_name == before + assert read_name() == before @pytest.mark.verifies("undo", "redo") -def test_undo_and_redo_reverse_and_reapply_a_scratch_edit(qc, restores): +def test_undo_and_redo_reverse_and_reapply_a_scratch_edit(qc, scratch_preset): """Create, edit, and remove a test-owned copy of the loaded preset.""" - original = qc.loaded_position() - for field in ("folder_key", "position", "is_factory"): - assert original.HasField(field), f"loaded position omitted {field}" - original_scene = int(qc.active_scene()) - - scratch_name = "pyquadcortex undo probe" - slots = qc.list_presets(Setlist.USER, include_empty=True) - assert not any(e.HasField("name") and e.name == scratch_name for e in slots), ( - f"delete the existing {scratch_name!r} preset before running this test" - ) - empty = next((e for e in slots - if e.HasField("index") - and (not e.HasField("name") or not e.name)), None) - if empty is None: - pytest.skip("My Presets has no empty slot for the disposable copy") - - def delete_scratch(): - qc.delete_preset(Setlist.USER, scratch_name) - qc.wait_for_listing( - Setlist.USER, - until=lambda entries: not any( - e.HasField("name") and e.name == scratch_name for e in entries - ), - timeout=30.0, - ) - - restores("delete the undo-test scratch preset", delete_scratch) - restores("restore the original active scene", - lambda: qc.switch_scene(original_scene)) - restores("recall the originally loaded preset", lambda: qc.read_preset( - original.folder_key, original.position, - is_factory=original.is_factory, timeout=30.0, - )) - - stored = qc.save_current_preset( - Setlist.USER, empty.index, scratch_name, - confirm=True, confirm_timeout=30.0, - ) - assert stored == scratch_name, "the disposable copy was not confirmed" - before_preset = qc.read_preset(Setlist.USER, empty.index, timeout=30.0) + setlist, position, _name = scratch_preset + before_preset = qc.read_preset(setlist, position, timeout=30.0) occupied = protocol.blocks(before_preset) if not occupied: pytest.skip("the loaded preset has no block whose bypass can be edited") diff --git a/tests/hardware/test_model_state.py b/tests/hardware/test_model_state.py index 152dc96d..11cd3194 100644 --- a/tests/hardware/test_model_state.py +++ b/tests/hardware/test_model_state.py @@ -189,8 +189,9 @@ def test_nothing_the_burst_delivered_is_read_again_on_first_access( "again, which is the round trip the cache exists to avoid") -def test_connects_version_read_warms_identity_with_profile_specific_announce( - qc, burst_warmed, handshake_burst, record_property): +def test_the_burst_warms_identity_from_connects_own_version_read(burst_warmed, + handshake_burst, + record_property): """Identity reaches the cache through the ONE Version READ connect() makes. The unit never volunteers its identity, so the model reads it (section 9's @@ -201,9 +202,7 @@ def test_connects_version_read_warms_identity_with_profile_specific_announce( its burst - the full reply to connect's READ (15 fields, +0.71 s), the unit's own ``Version{READ}`` about 1 ms behind it (the question it asks Cortex Control, section 4.4), and the ``UPDATE`` carrying - ``cortex_control_version_valid`` that answers our announce (+0.73 s). Four - fresh CorOS 4.1.0 connections on 2026-09-04 carried the full reply and unit - READ but no announce answer, while the subscribed state burst still arrived. + ``cortex_control_version_valid`` that answers our announce (+0.73 s). ``_hello`` itself still sends no READ; the 2026-08-27 measurement of one inbound ``Version`` stands for ``_hello`` alone. @@ -225,15 +224,8 @@ def test_connects_version_read_warms_identity_with_profile_specific_announce( if s[0] == pa.MessageAction.READ and s[1] == {"action"}] announce = [s for s in shapes if "cortex_control_version_valid" in s[1]] record_property("identity_reads", len(full)) - factory_count = len(qc.catalog.factory_models()) - record_property("connect_burst_factory_model_count", factory_count) - expected_announces = {412: 1, 420: 0} - assert factory_count in expected_announces, ( - f"the connected unit exposes {factory_count} factory models, so its " - f"connect-burst Version behavior has not been measured") - assert len(announce) == expected_announces[factory_count], ( - f"the {factory_count}-factory-model profile sent {len(announce)} " - f"announce answers, not the measured {expected_announces[factory_count]}. " + assert len(announce) == 1, ( + f"{len(announce)} answers to our version announce; one is measured. " f"Shapes seen: {shapes}") assert full, ( f"no full Version reply reached the listener: connect() stopped reading " @@ -242,7 +234,7 @@ def test_connects_version_read_warms_identity_with_profile_specific_announce( assert len(own_reads) == len(full), ( f"{len(full)} full replies but {len(own_reads)} unit READs; the unit asks " f"its own question once per answer (protocol.md 4.4). Shapes: {shapes}") - assert len(shapes) == len(full) + len(own_reads) + len(announce), ( + assert len(shapes) == len(full) + len(own_reads) + 1, ( f"a Version of a shape this test does not know arrived - the handshake " f"changed under us. Shapes: {shapes}") assert set(burst_warmed["identity"]) == {"device_serial_number", "app_fw_version"}, ( diff --git a/tests/test_hardware_markers.py b/tests/test_hardware_markers.py index cfbc5a6f..2792fbbd 100644 --- a/tests/test_hardware_markers.py +++ b/tests/test_hardware_markers.py @@ -22,19 +22,19 @@ "io_settings": "the input gain tests read it back as their instrument; nothing asserts the port listing against what the unit shows", "preset_dirty": "test_model_state.py calls it only to decide which branch to expect; nothing asserts the flag across a known-clean and known-dirty preset", "settings": "the global-settings echo test reads it only to find the value to flip; nothing asserts a settings() field against the unit's screen", - "list_presets": "read by the scratch_preset fixture, which no test uses yet; no test asserts on the listing itself", + "list_presets": "the undo/redo test's scratch_preset fixture uses it to find a free slot; no test asserts the listing itself against the unit's Directory", # -- the preset library: writes that would touch the owner's own presets --- # The scratch_preset fixture is what these would be built on - it saves a # copy into a free User slot and deletes it again - but no test uses it yet. - "save_current_preset": "no hardware test yet; scratch_preset is the fixture for one, and it must save into a free User slot rather than over the owner's work", + "save_current_preset": "the undo/redo test's scratch_preset fixture confirms a save into a free User slot, but the test verifies undo/redo rather than the save wire shape", "recall_preset": "no hardware test yet; a recall discards the loaded preset's unsaved edits, so it needs scratch_preset around it", - "delete_preset": "no hardware test yet; only scratch_preset's teardown deletes anything, and a teardown asserts nothing", + "delete_preset": "the undo/redo test's scratch_preset teardown deletes its copy and confirms absence; no test isolates the delete wire shape itself", "copy_preset": "no hardware test yet; it writes into a second setlist, so a failed run leaves a stray preset in the owner's Directory", "move_preset": "no hardware test yet; it rearranges the slots a player has laid out for a gig, which a restore cannot make invisible mid-run", - "read_preset": "no hardware test yet; it RECALLS the preset it reads, so it is a write in disguise and needs scratch_preset", + "read_preset": "the undo/redo test reads its scratch copy to choose an edit, but verifies the history result rather than the read operation itself", "find_preset": "no hardware test yet; it needs a name that exists on the unit, which the loaded preset supplies - just not written", - "wait_for_listing": "no hardware test yet; it is the polling wrapper round list_presets and says nothing until a write changes a listing", + "wait_for_listing": "scratch_preset teardown uses it to confirm deletion; no test independently verifies its polling and stability contract", "create_setlist": "no hardware test yet; it adds a folder to the owner's Directory that a failed run would leave behind", "delete_setlist": "no hardware test yet; it deletes a folder and everything in it, which is the one preset-library mistake nothing can undo", "duplicate_setlist": "no hardware test yet; it copies a whole setlist preset by preset, so a failed run leaves a partial folder behind", @@ -48,7 +48,7 @@ "favorites": "no hardware test yet; the FAVORITES list is the owner's and may be empty, so a test can only assert the shape", "recents": "no hardware test yet; RECENTS changes with every recall, so a test can only assert the shape", "pinned_models": "no hardware test yet; which models are pinned is the owner's choice, so a test can only assert the shape", - "loaded_position": "no hardware test yet; scratch_preset reads it, and asserting it needs a recall to a slot the test chose", + "loaded_position": "scratch_preset records it so teardown can return to the starting slot; no test independently verifies all fields against the unit", "read_current_preset_push": "no hardware test yet; it returns the RecallPreset wrapper round the same payload read_current_preset returns", "mode": "no hardware test yet; which footswitch mode slots exist is the owner's configuration", "mode_cycle": "no hardware test yet; the cycle order is the owner's configuration, so a test can only assert the shape", diff --git a/tests/test_profiles.py b/tests/test_profiles.py index f5895c90..98ef98d5 100644 --- a/tests/test_profiles.py +++ b/tests/test_profiles.py @@ -253,13 +253,13 @@ def test_the_4_1_profile_exposes_only_operations_with_contributed_evidence(): assert issubclass(cls, client.QuadCortex) assert cls.MEASURED_ON == ("4.1.0",) assert cls.EVIDENCE is support.Evidence.CONTRIBUTED - assert cls.VERIFIED == frozenset({"create_local_backup"}) + assert cls.VERIFIED == frozenset({"create_local_backup", "set_device_name"}) assert cls.CC_VERSION == "4.0.1", "inherited: the contributor's runs announced 4.0.1" assert isinstance(cls.models, support.NoSnapshot) with pytest.raises(AttributeError, match="coros_4_1_0"): cls.models.Delay assert cls(FakeTransport()).unverified_operations == ( - client.QuadCortex.operations() - {"create_local_backup"} + client.QuadCortex.operations() - {"create_local_backup", "set_device_name"} ) diff --git a/tests/test_session.py b/tests/test_session.py index 9c4bee4a..7f947652 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -506,7 +506,7 @@ def test_connect_hands_back_the_4_1_class_for_a_4_1_unit(fake_stack): qc = session.connect() assert type(qc) is profiles.QuadCortex41 assert qc.unverified_operations == ( - client.QuadCortex.operations() - {"create_local_backup"} + client.QuadCortex.operations() - profiles.QuadCortex41.VERIFIED ) with pytest.raises(errors.ControlNotDrivable): qc.switch_scene(1) diff --git a/tests/test_transport.py b/tests/test_transport.py index 797ca0f4..fd6b3668 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -135,41 +135,6 @@ def test_request_response_round_trip(): assert resp.request_id == 1 # first id from itertools.count(1) -def test_request_match_ignores_a_same_type_echo_and_waits_for_full_reply(): - class EchoThenFull(FakeHid): - def write(self, report): - report = bytes(report) - self.writes.append(report) - frame = framing.decode_reports([report]) - request = pa.VersionMessage() - request.ParseFromString(frame.payload) - echo = pa.VersionMessage(action=pa.MessageAction.READ) - full = pa.VersionMessage( - action=pa.MessageAction.UPDATE, - device_serial_number="QCS0000001", - ) - for response in (echo, full): - self.inject(*framing.encode_message( - registry.type_for(pa.VersionMessage), - response.SerializeToString(), - )) - return len(report) - - fake = EchoThenFull() - t = transport.Transport(fake, keepalive_interval=QUIET_KEEPALIVE) - t.start() - try: - reply = t.request( - pa.VersionMessage(action=pa.MessageAction.READ), - timeout=REQUEST_TIMEOUT, - match=lambda message: message.HasField("device_serial_number"), - ) - finally: - t.stop() - - assert reply.device_serial_number == "QCS0000001" - - def test_multi_report_reassembly(): # A 300-char kernel-version string makes the response payload > 128 bytes so # it spans multiple input reports; the transport must reassemble them. diff --git a/tests/test_writing.py b/tests/test_writing.py index ace0a876..87a3563f 100644 --- a/tests/test_writing.py +++ b/tests/test_writing.py @@ -41,7 +41,7 @@ def governed_documents(): def _ids(path): - return str(path.relative_to(ROOT)) + return path.relative_to(ROOT).as_posix() def _governed_text(path):