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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,10 @@ sustained stretch without a correction.

`delete_preset()` and `move_preset()` now also accept the `ProductData` returned
by `list_presets()`, validate that its key belongs to the requested setlist, and
send that key unchanged. The exact-name form remains listing-free and preserves
the measured CorOS 4.0.1 `<setlist>/<name>.pb` wire shape, including hardware
cleanup when listing reads are silent. The captured move shape now also carries
send that key unchanged. Both take `str | ProductData`, so a caller that passes
anything else is a type error. The exact-name form remains listing-free and
preserves the measured CorOS 4.0.1 `<setlist>/<name>.pb` wire shape, including
hardware cleanup when listing reads are silent. The captured move shape carries
its explicit `is_downloads: false` field. Unmeasured rename and occupied-slot
swap behavior are deliberately not exposed.

Expand Down
18 changes: 15 additions & 3 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -1363,13 +1363,25 @@ File{action: DELETE, type: 0,

```
File{action: MOVE, type: 0,
folder{key: <setlist path>, files{key: "<setlist path>/<name>.pb"}},
folder{key: <setlist path>, is_factory: false, is_downloads: false,
files{key: "<setlist path>/<name>.pb"}},
to_folder{key: <setlist path>, files{index: 219}}}
```

Source by file path, destination by linear index. Only same-setlist moves have
been observed. `delete_from_library` exists in the schema and was never sent.

Both explicit false flags are measured. The three recorded CorOS 4.0.1
sessions hold one `MOVE` (session 02, frame 25825) and one `DELETE` (session
02, frame 19033); this is what each carries, decoded 2026-09-21.

| field | `DELETE` | `MOVE` |
|---|---|---|
| `folder.is_factory` | present, false | present, false |
| `folder.is_downloads` | absent | present, false |
| `to_folder.is_factory` | n/a | absent |
| `to_folder.is_downloads` | n/a | absent |

### 10.3 Setlists

**Creating a setlist** is captured from the unit's own "New Setlist" and
Expand Down Expand Up @@ -2103,8 +2115,8 @@ wire, with no independent read-back.
| `set_scene_label` / `set_scene_color` | `SceneLabel` / `SceneColor{UPDATE, index, label/color}` | read-back | colour is ARGB uint32; exact round-trip |
| `copy_scene` | `SceneCopy{UPDATE, from_index, to_index, is_swap}` | read-back + on-unit | `from_index` and `is_swap` confirmed; label and colour travel with the state |
| `save_current_preset` | `File{CREATE, folder{key, files{index, name, instrument}}}` | read-back | snapshots the grid; `preset_payload` is ignored |
| `delete_preset` | `File{DELETE, folder{files{key: "<setlist>/<name>.pb"}}}` | three Cortex Control 4.0.1 captures + read-back | Every occupied entry in those captures exposed that exact key. The API also accepts the listing's `ProductData`, validates that its device-provided key belongs to the named setlist, and sends the key unchanged. Works, but asynchronously: a listing within about 2 s is stale, about 5 s is reliable |
| `move_preset` | `File{MOVE, folder{is_downloads: false, files{key}}, to_folder{files{index}}}` | Cortex Control 4.0.1 capture + read-back | Source by file path, destination by index; asynchronous like delete. The explicit false flag is present on the captured wire shape. The API accepts either the exact name or a listing `ProductData` and never waits for a listing before sending |
| `delete_preset` | `File{DELETE, folder{files{key: "<setlist>/<name>.pb"}}}` | one captured `DELETE` + three-session key evidence + read-back | Every occupied entry in those captures exposed that exact key. The API also accepts the listing's `ProductData`, validates that its device-provided key belongs to the named setlist, and sends the key unchanged. Works, but asynchronously: a listing within about 2 s is stale, about 5 s is reliable |
| `move_preset` | `File{MOVE, folder{is_factory: false, is_downloads: false, files{key}}, to_folder{files{index}}}` | one captured `MOVE` + read-back | Source by file path, destination by index; asynchronous like delete. The explicit false flag is present on the captured wire shape. The API accepts either the exact name or a listing `ProductData` and never waits for a listing before sending |
| `set_param_scene_mode` | `Grid{UPDATE, ..., params{index, scene_mode}}` (flag alone) | read-back | a value in the same message voids it |
| `set_chain_output` | `Grid{UPDATE, preset{chains{row, out_portid}}}` | read-back | required for a new chain: the unit never assigns an output on its own |
| `set_param(Mixer(row), ...)` | `Grid{UPDATE, preset{chains{row, mixer{params{index, param_values}}}}}` | read-back | supports per-scene; how factory presets build scenes |
Expand Down
38 changes: 29 additions & 9 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -4187,7 +4187,8 @@ def save_current_preset(
return e.name
return None

def _stored_preset_key(self, setlist_path: str, preset) -> str:
def _stored_preset_key(self, setlist_path: str,
preset: str | pa.ProductData) -> str:
"""Resolve a display name or validate a listed ProductData key."""
if not isinstance(preset, pa.ProductData):
# Backward-compatible and deliberately listing-free: hardware
Expand All @@ -4210,14 +4211,23 @@ def _stored_preset_key(self, setlist_path: str, preset) -> str:
f"setlist {setlist_path!r}")
return preset.key

def delete_preset(self, setlist_path: str, preset):
def delete_preset(self, setlist_path: str, preset: str | pa.ProductData):
"""Delete a stored preset from ``setlist_path``.

``preset`` is either its exact display name or the ``ProductData``
returned by :meth:`list_presets`. On three CorOS 4.0.1 captures every
occupied entry's key was exactly ``<setlist>/<name>.pb``; passing a
listing entry avoids reconstructing it, while the name form remains a
listing-free compatibility path for best-effort cleanup.
returned by :meth:`list_presets`. Passing a listing entry sends the
device's own key. The name form stays listing-free, for cleanup that
cannot wait for a listing read.

Confirmed by capture: deleting "Test save to user sl" from slot 28E
sent ``File{action: DELETE, type: 0, folder{key: <setlist path>,
is_factory: false, files{key: "<setlist path>/<name>.pb"}}}`` - the
preset is addressed by its device FILE PATH (name-based, ``.pb``
extension), NOT by slot index. ``folder.is_factory`` is present and
false; ``folder.is_downloads`` is absent. One captured ``DELETE``,
session 02 frame 19033, decoded 2026-09-21. Separately, every occupied
preset-setlist entry in all three recorded sessions carried that same
key shape.
"""
msg = pa.FileMessage(action=pa.MessageAction.DELETE, type=0)
msg.folder.key = setlist_path
Expand All @@ -4226,14 +4236,24 @@ def delete_preset(self, setlist_path: str, preset):
setlist_path, preset)
return self._file_operation(msg)

def move_preset(self, setlist_path: str, preset, to_position):
def move_preset(self, setlist_path: str, preset: str | pa.ProductData,
to_position):
"""Move a stored preset into ``to_position`` in the same setlist.

``to_position`` is either the linear slot index or the slot name shown on
the unit (``"28D"``). ``preset`` may be its exact display name or the
``ProductData`` returned by :meth:`list_presets`; the latter supplies
the device's own key. Cortex Control 4.0.1 was captured adding
``is_downloads: false`` to this MOVE shape.
the device's own key.

Confirmed by capture: dragging "Darkglass AO900 2_1" onto slot 28D
sent ``File{action: MOVE, type: 0, folder{key: <setlist path>,
is_factory: false, is_downloads: false, files{key: "<setlist
path>/<name>.pb"}}, to_folder{key: <setlist path>, files{index:
219}}}`` - source by FILE PATH, destination by LINEAR slot index.
Both ``folder`` flags are present and false; ``to_folder`` carries
neither. ``is_downloads`` is absent from the DELETE in the same
session. One captured ``MOVE``, session 02 frame 25825, decoded
2026-09-21.
"""
msg = pa.FileMessage(action=pa.MessageAction.MOVE, type=0)
msg.folder.key = setlist_path
Expand Down
25 changes: 16 additions & 9 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -666,7 +666,12 @@ def test_move_preset_uses_an_authoritative_key_and_the_captured_flag():
assert not sent.to_folder.HasField("is_factory")


def test_move_preset_matches_the_captured_cortex_builder_bytes():
def test_move_preset_serializes_the_captured_field_order_and_flags():
# Pins field numbering, field ORDER and the explicit false flags against the
# shape measured in windows-session-02 frame 25825 (CorOS 4.0.1). The key
# below is this test's own string, not a device-supplied one, so this says
# nothing about which key the caller should send - see the tests above for
# that. It does catch is_downloads or is_factory going away.
setlist = "/media/p4/Presets/My Presets"
product_key = f"{setlist}/Numb.pb"
listing = _preset_listing(
Expand Down Expand Up @@ -1047,17 +1052,19 @@ def test_file_operations_do_not_raise_when_the_device_stays_silent():
# File ops are asynchronous and every host write is STALLed, so a missing reply
# says nothing about success. Raising made callers wrap each one in
# try/except and verify by re-reading anyway.
transport = TimingOutTransport()
transport.broadcast = _preset_listing(
# Both forms of ``preset``. The by-name form is the one hardware teardown
# uses (tests/hardware/conftest.py), and a silent device is exactly the case
# it has to survive, so testing only the ProductData form leaves that hole.
source = _preset_listing(
str(Setlist.USER),
{"index": 1, "name": "Some Preset",
"key": f"{Setlist.USER}/opaque-source"},
{"index": 219, "name": "Unsaved"},
)
qc = client.QuadCortex(transport)
source = transport.broadcast.folder.files[0]
assert qc.delete_preset(Setlist.USER, source) is None
assert qc.move_preset(Setlist.USER, source, "28D") is None
).folder.files[0]
for preset in ("Some Preset", source):
qc = client.QuadCortex(TimingOutTransport())
assert qc.delete_preset(Setlist.USER, preset) is None
assert qc.move_preset(Setlist.USER, preset, "28D") is None
qc = client.QuadCortex(TimingOutTransport())
assert qc.save_current_preset(Setlist.USER, "30A", "Some Preset") == "Some Preset"


Expand Down
Loading