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
10 changes: 10 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,16 @@ sustained stretch without a correction.

## Unreleased

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

`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
its explicit `is_downloads: false` field. Unmeasured rename and occupied-slot
swap behavior are deliberately not exposed.

### The screen shortens one control's words, and not because of the words

A Mono Synth's oscillator tab draws `SIN` where the catalog says `Sine`. Whether
Expand Down
2 changes: 1 addition & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ already read and need no connection; calling them as methods raises
| **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 |
| **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, name)`, `move_preset(setlist, name, to_slot)` |
| **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 |

**Rows and columns are zero-based, and the unit displays rows 1 to 4.** `row=0`
Expand Down
4 changes: 2 additions & 2 deletions docs/manual-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,8 @@ settled is in [capture.md](capture.md).
| Preset descriptive tags | n/a | not preserved by any save path, including the unit's own Save As, so they are build-chain metadata no library can write. The instrument category is separate and fully mapped (`Instrument`: Guitar 1, Bass 2, Synth 3, Vocal 4, Other 5) |
| Preset description, author, cloud id | no | ignored by a `Grid` update. The unit stamps `author_name` from the signed-in cloud account on every save |
| Preset volume and pan | n/a | ignored by every route tried, and the unit has no control for them; they read 1.0 and 0.5 on every preset |
| Delete a preset | yes | `delete_preset()`, eventually consistent. `delete_setlist()` removes a whole setlist |
| Move a preset | yes | `move_preset()`, same-setlist only observed |
| Delete a preset | yes | `delete_preset()`, eventually consistent. Pass a listing's `ProductData` to preserve the device-provided key, or the exact display name for the measured 4.0.1 path shape. `delete_setlist()` removes a whole setlist |
| Move a preset | yes | `move_preset()`, same-setlist only observed; accepts the same device-provided `ProductData` or exact-name forms as delete |
| Factory and My Presets setlists | yes | `Setlist.FACTORY`, `Setlist.USER` |
| User folders / additional setlists | yes | `create_setlist()` makes them and `list_folders()` finds them; `list_presets()` accepts any key. MIDI CC#32's "User folders" 2 to 12 are created, not built in |
| Create a folder, nested navigation | yes | `create_setlist(name)`. Setlists are siblings under `/media/p4/Presets`, not children of My Presets |
Expand Down
4 changes: 2 additions & 2 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -2103,8 +2103,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"}}}` | read-back | asynchronous: a listing within about 2 s is stale, about 5 s is reliable |
| `move_preset` | `File{MOVE, folder{files{key}}, to_folder{files{index}}}` | read-back | source by file path, destination by index; asynchronous like delete |
| `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 |

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 row says the explicit false flag is present on the captured MOVE shape, and section 10.2 above still prints that shape without it:

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

One document, two shapes. A correction replaces the wrong sentence rather than sitting beside it, so section 10.2's block wants is_downloads: false added to folder (it is outside this diff, so I cannot suggest it inline).

Also, the "Verified by" column has a controlled vocabulary defined in the paragraph above the table - read-back, on-unit, captured only - and these two rows introduce "three Cortex Control 4.0.1 captures + read-back" and "Cortex Control 4.0.1 capture + read-back".

| `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
61 changes: 42 additions & 19 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -4187,37 +4187,60 @@ def save_current_preset(
return e.name
return None

def delete_preset(self, setlist_path: str, name: str):
"""Delete the preset named ``name`` from the setlist at ``setlist_path``.

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.
def _stored_preset_key(self, setlist_path: str, preset) -> str:
"""Resolve a display name or validate a listed ProductData key."""
if not isinstance(preset, pa.ProductData):
# Backward-compatible and deliberately listing-free: hardware
# teardown depends on a best-effort delete even when listing reads
# are silent. On measured 4.0.1 listings this reconstructed path is
# byte-for-byte the same value as the device-supplied key.
return f"{setlist_path.rstrip('/')}/{preset}.pb"
if not (field_present(preset, "key") and preset.key):
raise ControlNotDrivable(
"stored preset product key",
"the supplied ProductData carries no key, so the device did "
"not provide an address",
"pass a populated ProductData from list_presets(), or pass "
"the exact display name to use the measured 4.0.1 path shape",
)
prefix = setlist_path.rstrip("/") + "/"
if not preset.key.startswith(prefix):
raise ValueError(
f"preset key {preset.key!r} does not belong to "
f"setlist {setlist_path!r}")
return preset.key

def delete_preset(self, setlist_path: str, preset):

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 I would most like changed. Dropping name: str for an unannotated preset removes a guard the package ships to its users: pyquadcortex carries py.typed, so before this change qc.delete_preset(Setlist.USER, 42) was a mypy error for every downstream caller. Now it type-checks, sends key="/media/p4/Presets/My Presets/42.pb", and _file_operation returns None exactly as a success does.

Repo mypy is deliberately not strict, so CI stays green either way - this is about what downstream gets. The union is one line:

Suggested change
def delete_preset(self, setlist_path: str, preset):
def delete_preset(self, setlist_path: str, preset: str | pa.ProductData):

_stored_preset_key on line 4190 and move_preset on 4229 want the same annotation.

"""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.
Comment on lines +4216 to +4220

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.

The captured record that was here is gone rather than kept. Thread 3992216374 asked for the 4.0.1 captured shape to stay, with any 4.1.0 reading recorded beside it and labelled as read from the binary; the thread is resolved but the shape is not back. CLAUDE.md's rule is that a docstring states its evidence, and "on three CorOS 4.0.1 captures" names a firmware but no capture and no date.

I re-decoded the three sessions to check your claim, and it holds: one DELETE exists across all three (windows-session-02, frame 19033, t=54.6s) and it sent exactly this shape. So the old record and your new sentence are both true and can sit together.

Suggested change
``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.
``preset`` is either its exact display name or the ``ProductData``
returned by :meth:`list_presets`. Passing a listing entry sends the
device's own key; the name form stays listing-free for best-effort
cleanup.
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. In all three recorded 4.0.1 sessions
every occupied preset-setlist entry carried that same key.

"""
msg = pa.FileMessage(action=pa.MessageAction.DELETE, type=0)
msg.folder.key = setlist_path
msg.folder.is_factory = False
msg.folder.files.add().key = f"{setlist_path}/{name}.pb"
msg.folder.files.add().key = self._stored_preset_key(
setlist_path, preset)
return self._file_operation(msg)

def move_preset(self, setlist_path: str, name: str, to_position):
"""Move the preset named ``name`` to slot ``to_position`` (same setlist).
def move_preset(self, setlist_path: str, preset, to_position):

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.

Suggested change
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"``).

Confirmed by capture: dragging "Darkglass AO900
2_1" onto slot 28D sent ``File{action: MOVE, type: 0, folder{key:
<setlist path>, files{key: "<setlist path>/<name>.pb"}},
to_folder{key: <setlist path>, files{index: 219}}}`` - source by FILE
PATH, destination by LINEAR slot index.
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.
Comment on lines +4233 to +4236

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.

Same as on delete_preset: the dated capture record came out and prose went in.

Your is_downloads claim checks out, and it is worth stating more precisely than "was captured adding". I decoded the sessions: exactly one MOVE exists (windows-session-02, frame 25825, t=149.8s), its folder.is_downloads is explicitly present with value false, and the one DELETE in the same session does not carry the field at all. That asymmetry is the interesting fact and nothing in the tree records it.

Suggested change
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.
``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.
Confirmed by capture: dragging "Darkglass AO900 2_1" onto slot 28D
sent ``File{action: MOVE, type: 0, folder{key: <setlist path>,
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. The explicit ``is_downloads:
false`` is present on MOVE and absent from the DELETE in the same
session.

"""
msg = pa.FileMessage(action=pa.MessageAction.MOVE, type=0)
msg.folder.key = setlist_path
msg.folder.is_factory = False
msg.folder.files.add().key = f"{setlist_path}/{name}.pb"
msg.folder.is_downloads = False
msg.folder.files.add().key = self._stored_preset_key(
setlist_path, preset)
msg.to_folder.key = setlist_path
msg.to_folder.files.add().index = _as_position(to_position)
return self._file_operation(msg)
Expand Down
122 changes: 102 additions & 20 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -586,37 +586,105 @@ def test_save_current_preset_sends_file_create_by_reference():
)


def test_delete_preset_sends_file_delete_by_path():
# CONFIRMED wire shape (Windows capture 2): delete addresses the preset by
# its device file path "<setlist>/<name>.pb", not by slot index.
qc = client.QuadCortex(FakeTransport())
qc.delete_preset("/media/p4/Presets/My Presets", "Test save to user sl")
def _preset_listing(setlist, *entries):
listing = pa.FileMessage()
listing.folder.key = setlist
for values in entries:
entry = listing.folder.files.add()
for field, value in values.items():
setattr(entry, field, value)
return listing


def test_delete_preset_uses_the_authoritative_catalog_key():
setlist = "/media/p4/Presets/My Presets"
listing = _preset_listing(setlist, {
"index": 220,
"name": "Test save to user sl",
"key": f"{setlist}/opaque-device-key-220",
})
fake = FakeTransport()
qc = client.QuadCortex(fake)
qc.delete_preset(setlist, listing.folder.files[0])
sent = qc._t.sent[-1]
assert isinstance(sent, pa.FileMessage)
assert sent.action == pa.MessageAction.DELETE
assert sent.type == 0
assert sent.folder.key == "/media/p4/Presets/My Presets"
assert sent.folder.is_factory is False
assert (
sent.folder.files[0].key
== "/media/p4/Presets/My Presets/Test save to user sl.pb"
)
assert sent.folder.files[0].key == f"{setlist}/opaque-device-key-220"
assert not sent.folder.files[0].HasField("name")
assert not sent.folder.files[0].HasField("index")
assert not sent.HasField("to_folder")


def test_move_preset_sends_file_move():
# CONFIRMED wire shape (Windows capture 2): source by file path,
# destination by linear slot index in to_folder.
def test_delete_preset_by_name_stays_listing_free_for_hardware_cleanup():
setlist = "/media/p4/Presets/My Presets"
qc = client.QuadCortex(FakeTransport())
qc.move_preset("/media/p4/Presets/My Presets", "Darkglass AO900 2_1", 219)
qc.delete_preset(setlist, "Test save to user sl")
assert qc._t.sent[-1].folder.files[0].key == \
f"{setlist}/Test save to user sl.pb"


def test_a_product_key_must_belong_to_the_named_setlist():
qc = client.QuadCortex(FakeTransport())
wrong = pa.ProductData(
key="/media/p4/Presets/Factory Presets/Cali Basswalk.pb")
with pytest.raises(ValueError, match="does not belong"):
qc.delete_preset("/media/p4/Presets/My Presets", wrong)
assert qc._t.sent == []


def test_a_product_without_a_key_refuses_with_auditable_evidence():
qc = client.QuadCortex(FakeTransport())
with pytest.raises(ControlNotDrivable) as caught:
qc.delete_preset("/media/p4/Presets/My Presets",
pa.ProductData(name="Unnamed"))
assert caught.value.control == "stored preset product key"
assert "no key" in caught.value.evidence
assert "list_presets" in caught.value.workaround


def test_move_preset_uses_an_authoritative_key_and_the_captured_flag():
setlist = "/media/p4/Presets/My Presets"
listing = _preset_listing(
setlist,
{"index": 218, "name": "Darkglass AO900 2_1",
"key": f"{setlist}/opaque-source"},
{"index": 219, "name": "Unsaved"},
)
fake = FakeTransport()
qc = client.QuadCortex(fake)
qc.move_preset(setlist, listing.folder.files[0], 219)
sent = qc._t.sent[-1]
assert isinstance(sent, pa.FileMessage)
assert sent.action == pa.MessageAction.MOVE
assert (
sent.folder.files[0].key
== "/media/p4/Presets/My Presets/Darkglass AO900 2_1.pb"
)
assert sent.folder.is_downloads is False
assert sent.folder.files[0].key == f"{setlist}/opaque-source"
assert sent.to_folder.key == "/media/p4/Presets/My Presets"
assert sent.to_folder.files[0].index == 219
assert not sent.to_folder.HasField("is_factory")


def test_move_preset_matches_the_captured_cortex_builder_bytes():

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.

Threads 3992216440 and 3992216451 both land here and neither is closed. I decoded the hex independently: it is byte-for-byte what the four lines above it build, and the key it pins is f"{setlist}/Numb.pb", invented on line 671 - the reconstructed display-name path, which is the thing this PR argues we should stop rebuilding. No capture in the repo mentions "Numb" or index 54; the one recorded MOVE is "Darkglass AO900 2_1" at index 219.

The test is still worth keeping - it would catch is_downloads going away, and that is a real regression guard. The problem is only that its name claims a provenance the bytes do not have.

Suggested change
def test_move_preset_matches_the_captured_cortex_builder_bytes():
def test_move_preset_serializes_the_captured_field_order_and_flags():

If you want it to pin the device rather than the field order, build it from the recorded MOVE: "Darkglass AO900 2_1" onto index 219, which is windows-session-02 frame 25825.

setlist = "/media/p4/Presets/My Presets"
product_key = f"{setlist}/Numb.pb"
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
listing = _preset_listing(
setlist,
{"index": 55, "name": "Numb", "key": product_key},
{"index": 54, "name": "Unsaved"},
)
fake = FakeTransport()
qc = client.QuadCortex(fake)
qc.move_preset(setlist, listing.folder.files[0], 54)
assert fake.sent[-1].SerializeToString() == bytes.fromhex(
"08 04 18 00 22 4a 0a 1c 2f 6d 65 64 69 61 2f 70 34 2f 50 72 65 73 "
"65 74 73 2f 4d 79 20 50 72 65 73 65 74 73 20 00 28 00 3a 26 0a 24 "
"2f 6d 65 64 69 61 2f 70 34 2f 50 72 65 73 65 74 73 2f 4d 79 20 50 "
"72 65 73 65 74 73 2f 4e 75 6d 62 2e 70 62 2a 22 0a 1c 2f 6d 65 64 "
"69 61 2f 70 34 2f 50 72 65 73 65 74 73 2f 4d 79 20 50 72 65 73 65 "
"74 73 3a 02 10 36"
)


# -- session hello -------------------------------------------------------------
Expand Down Expand Up @@ -744,6 +812,12 @@ def test_find_preset_looks_a_preset_up_by_name():

def test_save_and_move_accept_slot_names():
fake = FakeTransport()
fake.broadcast = _preset_listing(
str(Setlist.USER),
{"index": 1, "name": "Some Preset",
"key": f"{Setlist.USER}/opaque-source"},
{"index": 219, "name": "Unsaved"},
)
qc = client.QuadCortex(fake)

qc.save_current_preset(Setlist.USER, "30A", "Some Preset")
Expand Down Expand Up @@ -973,9 +1047,17 @@ 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.
qc = client.QuadCortex(TimingOutTransport())
assert qc.delete_preset(Setlist.USER, "Some Preset") is None
assert qc.move_preset(Setlist.USER, "Some Preset", "28D") is None
transport = TimingOutTransport()
transport.broadcast = _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
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
assert qc.move_preset(Setlist.USER, source, "28D") is None

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 test exists for the case where the device never answers, and it no longer covers the form that case actually arises in. tests/hardware/conftest.py:682 calls delete_preset(setlist, name) by name during teardown, and that is now the only caller in the repo; after this change the silent-transport assertion runs on the ProductData form instead.

The new test_delete_preset_by_name_stays_listing_free_for_hardware_cleanup does not fill the gap, because it uses a plain FakeTransport, which answers.

Keeping both forms under TimingOutTransport is enough. The transport.broadcast seeding is also dead at this head - _stored_preset_key never reads a listing - so it can go, here and in test_save_and_move_accept_slot_names.

assert qc.save_current_preset(Setlist.USER, "30A", "Some Preset") == "Some Preset"


Expand Down
Loading