Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
tests/fixtures/surface/pre_flip_init.py.txt text eol=lf
7 changes: 7 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,13 @@ sustained stretch without a correction.

## Unreleased

### Rename the unit, drive undo/redo, and read inhibited modules

`set_device_name()` sends a sparse Version update. `undo()` and `redo()` drive
the unit's native editable-preset history, and `inhibited_modules()` reads the
explicit Global EQ/Input Gate load-inhibition flags. All three wire shapes are
pinned offline and were exercised on CorOS 4.0.1 and 4.1.0 hardware.

### Preserve device-provided preset keys without adding a listing dependency

`delete_preset()` and `move_preset()` now also accept the `ProductData` returned
Expand Down
4 changes: 3 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ already read and need no connection; calling them as methods raises
| | |
|---|---|
| **Connect** | `protocol.connect(profile=, support=)` resolves the unit's device profile before the handshake (ADR-0020) and returns a connected client. An unknown `(device_type, zenos_git_hash)` raises `UnsupportedDevice`. `Support.VERIFIED` (default) refuses an operation the profile has not verified; `Support.EXPERIMENTAL` runs it with one warning. `qc.models`, `qc.params` and `qc.options` are that connection's own constants |
| **Inspect** | `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` |
Expand All @@ -68,6 +68,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. It runs on the transport's read thread, so it must not block and may not read from the unit. To catch the connect handshake's own burst, 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()` |
| **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`) |
Expand All @@ -76,6 +77,7 @@ already read and need no connection; calling them as methods raises
| **Copying** | `copy_preset(from_setlist, position, to_setlist)`: recall plus save, so it loads each source |
| **Device list** | `pin_model()`, `unpin_model()`, `pinned_models()`, `master_volume()` |
| **Neural Captures** | `captures()` and `list_irs()` to browse the library, `set_capture(cell, entry)` to place one. Creating a capture is the unit's own wizard; disconnect first, since a connected client suppresses it |
| **Edit history** | `undo()`, `redo()` |
| **Discovery** | `list_folders()`: every folder the unit knows, including the factory Captures Library and plugin artist presets; `recents()`, `favorites()`, `add_favorite()`, `remove_favorite()` |
| **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, preset)`, `move_preset(setlist, preset, to_slot)`; `preset` may be the exact name or a `ProductData` returned by `list_presets()` |
| **Local backups** | `create_local_backup()` returns the unit's validated portable backup document; serialize it to JSON wherever you keep backups |
Expand Down
4 changes: 2 additions & 2 deletions docs/domain-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -1095,7 +1095,7 @@ hardware, host concerns or reference text with nothing for a host API to model.
| 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. The MIDI CC follows the action, not the switch |
| Undo / redo | **omitted** | no | `UndoRedo` arrives as an acceptance signal; drivable, and not modelled |
| Undo / redo | **omitted from the model** | yes | protocol `undo()` / `redo()` reversed and reapplied a bypass edit on CorOS 4.0.1 and 4.1.0 |

## Chapter 5 - The Directory

Expand Down Expand Up @@ -1170,7 +1170,7 @@ hardware, host concerns or reference text with nothing for a host API to model.
| 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 |
| 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 |
Expand Down
12 changes: 6 additions & 6 deletions docs/manual-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -70,7 +70,7 @@ settled is in [capture.md](capture.md).
| Remove a block | yes | `remove_block()` (the `DELETE` action; an `UPDATE` with `hash: 0` is ignored) |
| Move a block | yes | `move_block(source, destination)`; a cross-row move makes the unit 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. 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 |
| Input blocks: assign a physical input | yes | `set_chain_input()` |
| Output blocks: assign a destination | yes | `set_chain_output()`. 16 to 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 |
Expand All @@ -93,7 +93,7 @@ settled is in [capture.md](capture.md).
| Set Parameters as Defaults | no | `DefaultParameters` is decoded and subscribed; never written |
| Looper X: place the block | yes | an ordinary catalog model |
| Looper X: transport actions and parameters | partly | `looper()` reads the full status and `LooperState` names five states. The transport is not driven from here; MIDI CC#48 to 61 is the documented route |
| Undo / redo | no | `UndoRedo` is decoded and subscribed. It arrives after accepted grid edits, so it is useful as an acceptance signal |
| Undo / redo | yes | `undo()` and `redo()` send sparse `UndoRedo{UPDATE}` commands; a bypass edit was reversed and reapplied on disposable preset copies |

## 05 The Directory

Expand Down Expand Up @@ -159,7 +159,7 @@ the menu; fifteen of its fields are confirmed writable one at a time.
| STOMP MODE BYPASS (auto-assign on load) | yes | `update_settings(stomp_mode_auto_assign=...)` |
| HOLD TIMING, SWAP TEMPO AND TUNER, GIG VIEW ACCESS | yes | all three via `update_settings()`. `set_hold_timing()` takes `Milliseconds` and writes the index the unit stores (500 to 1000 ms in 100 ms steps); `hold_timing_ms()` reads it back |
| LATENCY COMPENSATION | yes | `update_settings(enable_dynamic_delay_compensation=...)` |
| Device name | no | candidates `Serialization`, `GeneralSettings` |
| 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 |
| Firmware and serial | yes | `version()` |
| Diagnostics (DSP, footswitches, USB) | no | `ModuleStats` is decoded and subscribed; `Diagnostics` and `DSPCommsDiagnostics` are not |
| CorOS updates | no | `Updater` is decoded and subscribed; never driven, and out of scope for good |
Expand Down
3 changes: 3 additions & 0 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -2103,6 +2103,9 @@ wire, with no independent read-back.
|---|---|---|---|
| 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 | two messages come back; `version()` accepts only one carrying `device_serial_number` or `app_fw_version` (section 4.4) |
| `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 |
| `undo` / `redo` | `UndoRedo{UPDATE, undo}` / `{UPDATE, redo}` | read-back + on-unit | a bypass edit was reversed and reapplied on disposable preset copies; empty-history behaviour is unknown |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table already has an undo/redo row at line 2159, which I wrote: host undo / redo (undo() / redo() land in PR #42). Two rows for one operation, and they disagree on the verification column. The fix is to update 2159 and drop this one, rather than add beside it. Line 1786 needs the same treatment: its (PR #42, where undo() and redo() land) becomes false on merge.

| `inhibited_modules` | `CompilerInhibitedModules{READ}` | read-back | explicit false/false reply on CorOS 4.0.1 and 4.1.0; true semantics are schema-derived, not yet observed |
| `create_local_backup` | `LocalBackup{CREATE}` then `LocalBackup{UPDATE, backup_json}` pushes, the last with `is_last_chunk` | captured only | section 10.5. `can_apply_backup` never appeared, so the refusal path is unverified |
| `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 with `reason` |
Expand Down
54 changes: 54 additions & 0 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -660,6 +660,41 @@ def version(self, timeout: float = 10.0):
or m.HasField("app_fw_version")),
)

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.
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=name
))
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved

def undo(self):
"""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.

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
))
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved

def create_local_backup(self, timeout: float = 60.0) -> dict[str, typing.Any]:
"""Create and return the device's portable local-backup document.

Expand Down Expand Up @@ -2923,6 +2958,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. 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 ``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(
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
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.

Expand Down
5 changes: 3 additions & 2 deletions pyquadcortex/protocol/profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Splitting the semicolon left this sentence starting lowercase.

Suggested change
other inherited operations refuse under ``Support.VERIFIED`` and run with
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
Expand All @@ -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"})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the one thing I would most like settled, and it is yours to settle. What I wrote about set_device_name is now true of three more: on a 4.1.0 unit with the default Support.VERIFIED, qc.undo(), qc.redo() and qc.inhibited_modules() raise ControlNotDrivable, while their docstrings say they are confirmed on 4.1.0. Your evidence for those three looks the same as for set_device_name. If it is, promote them. If you are holding them back on purpose, say why here and I will take that.

models = NoSnapshot("coros_4_1_0")
params = NoSnapshot("coros_4_1_0")
options = NoSnapshot("coros_4_1_0")
Expand Down
2 changes: 1 addition & 1 deletion tests/hardware/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ def pytest_collection_modifyitems(session, config, items):
lambda dropped: config.hook.pytest_deselected(items=dropped)))
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)
})
Expand Down
12 changes: 9 additions & 3 deletions tests/hardware/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@ successful run leaves the unit exactly as it found it.
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. 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.

Expand Down Expand Up @@ -76,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

Expand Down
67 changes: 67 additions & 0 deletions tests/hardware/test_identity_and_history.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
"""Reversible device-name and edit-history checks against a real unit."""

import time

import pytest

from pyquadcortex import protocol
SETTLE = 1.0


@pytest.mark.verifies("set_device_name")
def test_device_name_round_trips_and_is_restored(qc):
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"

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 read_name() == probe
finally:
qc.set_device_name(before)
time.sleep(SETTLE)

assert read_name() == before


@pytest.mark.verifies("undo", "redo")
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."""
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")
target = occupied[0]
before_scene = int(qc.active_scene())
before = protocol.bypass_state(before_preset, target).scenes[before_scene]

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
17 changes: 17 additions & 0 deletions tests/hardware/test_settings_values.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,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

Expand All @@ -38,6 +39,22 @@
PORT = Input.INPUT_1


@pytest.mark.verifies("inhibited_modules")
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.
"""
# Read twice because a first state READ can be dropped; both successful

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

inhibited_modules() goes through _read_state to await_broadcast, which raises TimeoutError when no matching broadcast arrives. There is no retry. So on the unit this comment describes, a dropped first READ fails the test after the timeout rather than being covered by the second pass. The loop repeats the assertion, which is still worth doing; it just is not what the comment claims.

Suggested change
# Read twice because a first state READ can be dropped; both successful
# Read twice so a second reply must also carry explicit fields rather
# than protobuf defaults. A dropped first READ raises; there is no retry.

# 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")


def _input_level(qc, port_id):
for port in qc.io_settings().settings.in_port:
if port.input_port_id == int(port_id):
Expand Down
Loading
Loading