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

## Unreleased

### CorOS 4.1 can duplicate a setlist with one firmware-side copy

`QuadCortex41.duplicate_setlist()` sends the sparse folder `COPY` extracted from
Cortex Control 4.1 exactly once, then confirms the firmware-created destination
with stable folder generations and two identical complete 256-slot inventories.
A contributed CorOS 4.1.0 hardware run on 2026-09-11 confirmed a two-preset copy
in 49.878 seconds. The CorOS 4.0.1 base refuses this unmeasured command and points
callers to the older, measured `copy_preset()` recall-and-save composition.
### Rename the unit, drive undo/redo, and read inhibited modules

`set_device_name()` sends a sparse Version update. `undo()` and `redo()` drive
Expand Down
2 changes: 1 addition & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ already read and need no connection; calling them as methods raises
| **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, ...)`, including a block's side-chain `SOURCE` |
| **Setlists** | `create_setlist(name)`, `delete_setlist(name)`, `duplicate_setlist(src, dest)`, `list_folders()` |
| **Setlists** | `create_setlist(name)`, `delete_setlist(name)`, `duplicate_setlist(source)`, `list_folders()`; on CorOS 4.1 duplication is one firmware-side COPY and the device chooses the destination name. The CorOS 4.0.1 profile refuses that unmeasured command and points to `copy_preset()` |
| **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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/manual-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ settled is in [capture.md](capture.md).
| 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 |
| Favorites and Recents | yes | `recents()` and `favorites()` read the two lists. The request's `is_favorites` flag selects which; the reply never sets it, so correlate on `request_id`. `add_favorite()` and `remove_favorite()` write one entry at a time. Only presets can be favourited |
| Bulk actions | partly | no host-drivable bulk copy; `BulkOperation` only narrates progress. `copy_preset()` and `duplicate_setlist()` do it by recall plus save, a few seconds per preset |
| Bulk actions | partly | On the measured CorOS 4.1 profile, `duplicate_setlist()` sends Cortex Control's single firmware-side folder COPY, then verifies the asynchronously created destination without replaying the write; the CorOS 4.0.1 profile refuses and points to `copy_preset()`. `BulkOperation` only narrates progress |
| Search | no | candidate `RecentSearches` |
| Sort | n/a | client-side once a listing is in hand |
| Neural Captures: list | yes | `captures()` browses the library, over 2000 entries. Not the catalog, which does not grow when a capture is saved |
Expand Down
20 changes: 12 additions & 8 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -1409,14 +1409,17 @@ does. So the MIDI documentation's "User folders" at bank-select LSB 2 to 12 are
folders a player creates. **Deleting a setlist** is `File{DELETE, folder{key,
name}}` against the setlist's own key.

**There is no host-drivable copy.** The unit's duplicate action sends a `File`
`CREATE` for the destination and then narrates itself through `BulkOperation`
(`"Duplicating, please wait."`, a progress fraction, `finished`); doing the same
from the host creates an empty destination. The unit's per-preset paste
announces the same shape as a Save As pointed at another folder. So copying a
preset is recall then save, and duplicating a setlist is that per preset, which is
what `copy_preset()` and `duplicate_setlist()` do. Each one recalls the source on
the unit.
On CorOS 4.0.1, the unit's duplicate action sends a `File` `CREATE` and narrates
progress through `BulkOperation`; replaying that `CREATE` from the host produced
an empty destination. `copy_preset()` retains the measured recall-and-save
fallback on that profile.

On CorOS 4.1, Cortex Control sends one host-drivable sparse
`File{COPY, type: 0, folder{key: <source>, is_factory: false}}`. Firmware chooses
the collision-safe destination and performs the copy asynchronously.
`duplicate_setlist()` sends `COPY` exactly once and uses read-only polling until
two complete, identical 256-slot destination generations match the source.
A contributed 4.1.0 hardware run verified a two-preset copy in 49.878 seconds.

### 10.4 Recents and Favorites

Expand Down Expand Up @@ -2163,6 +2166,7 @@ wire, with no independent read-back.
| `delete_setlist` | `File{DELETE, folder{key, name}}` | read-back | removes the setlist and its contents |
| `create_setlist` | `File{CREATE, folder{key: "/media/p4/Presets/<name>", name}}` | read-back + on-unit | setlists are siblings under the presets root |
| `copy_preset` / `duplicate_setlist` | recall then `File{CREATE}` per preset | read-back | compositions; each recalls the source on the unit |
| `duplicate_setlist` (CorOS 4.1) | `File{COPY, folder{key: <source>, is_factory: false}}` | Cortex Control 4.1 binary + contributed hardware read-back | sends once, then stabilizes folder and complete 256-slot preset listings; CorOS 4.0.1 refuses because this shape has not been measured there |
| `set_split_mute` | `Grid{UPDATE, preset{chains{row, splitBypass{bypass}}}}` | read-back | reported back in `mixBypass`; one write sets all eight scenes |
| `set_stomp_assignment` / `clear_stomp_assignment` | `Grid{DELETE, stomp_mode_assignments{row, column}}` then `Grid{UPDATE, ...{stomp_index}}` | read-back + on-unit | the unit's own two-message sequence |
| `set_stomp_momentary` | `Grid{UPDATE, preset{stomp_is_momentary{key, value}}}` | read-back + on-unit | keyed by footswitch; lands only on a switch driving exactly one block |
Expand Down
233 changes: 203 additions & 30 deletions pyquadcortex/protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -920,12 +920,15 @@ def list_presets(self, setlist: str = Setlist.USER, timeout: float = 25.0,
device push a folder listing per setlist, so this sends that READ and
waits for the listing whose key matches ``setlist``.

A listing that arrives is COMPLETE - five READs against an 18-preset setlist
each produced a full listing, and no short one has been observed. But a READ
does not reliably produce one promptly: two of those five saw nothing for
that setlist within 8 s, delivery being lazy. So treat a timeout as "ask
again", which is what :meth:`wait_for_listing` does, rather than as an
answer about the setlist's contents.
On CorOS 4.0.1, five READs against an 18-preset setlist each produced a
complete listing, although two produced nothing within 8 s. A contributed
CorOS 4.1.0 run on 2026-09-11 also observed transient one-slot and blank
generations before the eventual 256-slot user-setlist listing. This returns the first
matching non-empty broadcast, so a workflow that needs an authoritative
user-setlist inventory must require and stabilize all 256 slot indices, as
:meth:`duplicate_setlist` does. Treat a timeout as "ask again", which is
what :meth:`wait_for_listing` does, rather than as an answer about the
setlist's contents.

Note the trailing-slash asymmetry the match has to absorb: recalls need
the factory path WITH its trailing slash (Cortex Control sends it that
Expand Down Expand Up @@ -3704,36 +3707,174 @@ def copy_preset(self, from_setlist: str, position, to_setlist: str,
name or source_name or "copy",
instrument=instrument, confirm=True)

def duplicate_setlist(self, source_name: str, dest_name: str,
limit: int | None = None):
"""Copy a whole setlist into a new one, preset by preset.
def duplicate_setlist(self, source_name: str, *, confirm: bool = True,
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
timeout: float | None = None,
interval: float = 2.0):
"""Refuse firmware-native duplication on the CorOS 4.0.1 profile."""
raise ControlNotDrivable(
"duplicate_setlist",
"firmware-native File COPY was measured on CorOS 4.1.0, not on "
"the CorOS 4.0.1 base profile",
"copy presets individually with copy_preset(), or use a measured "
"CorOS 4.1 profile",
)

Also a composition rather than a device operation. The unit's own
duplicate action broadcasts a ``BulkOperation`` narrating its progress -
``"Duplicating, please wait."``, then a progress fraction, then
``finished`` - but that is the device REPORTING: replaying it copies
nothing, and no host-drivable duplicate exists. So this creates the
destination and copies each preset with :meth:`copy_preset`.
def _duplicate_setlist_41(self, source_name: str, *, confirm: bool = True,
timeout: float | None = None,
interval: float = 2.0):
"""Ask firmware to duplicate a complete user setlist exactly once.

Which means it is SLOW - a recall and a save per preset, several seconds
each - and it recalls every one of them on the unit as it goes. ``limit``
caps how many are copied, for trying it out on a large setlist.
Cortex Control sends one sparse ``File{COPY}`` containing only the
source folder key and explicit ``is_factory: false``. Firmware chooses
the collision-safe destination name and key and copies the inventory
asynchronously; no destination identity or per-preset writes belong on
the wire.

Returns the list of names stored in the destination.
With ``confirm=True`` (the default), this takes a fresh folder and source
inventory baseline before the write, then performs read-only polling
until exactly one new folder has the source's complete
position/name/instrument inventory. The COPY is never replayed. Firmware
has taken more than 80 seconds for 74 presets, so the default deadline is
``90 + 2 * occupied_presets`` seconds, capped at ten minutes. A 2026-09-11
CorOS 4.1.0 run confirmed a disposable two-preset copy in 49.878 seconds.
That run also received partial ``File`` broadcasts before complete ones,
so both inventories require two identical generations containing every
user-setlist slot index before they are trusted.

Returns the device-created :class:`Folder` when confirmed. With
``confirm=False``, returns the immediate File reply if one arrives,
otherwise ``None``; that mode does not prove completion.
"""
dest_key = self.create_setlist(dest_name)
time.sleep(3.0)
source_key = (source_name if source_name.startswith("/")
else f"{USER_SETLIST_ROOT}/{source_name}")
entries = self.list_presets(source_key)
if limit is not None:
entries = entries[:limit]
stored = []
for i, entry in enumerate(entries):
stored.append(self.copy_preset(source_key, entry.index, dest_key,
to_position=i, name=entry.name,
instrument=entry.instrument))
return stored
if not _is_user_setlist_key(source_key):
raise ValueError(
f"source {source_key!r} is not a direct user setlist")
if confirm:
before = self._stable_folder_listing(timeout=120.0,
interval=interval)
before_keys = {folder.key for folder in before}
if source_key not in before_keys:
raise ValueError(f"source setlist {source_key!r} is not in the fresh catalog")
expected = self._stable_complete_user_setlist(
source_key, timeout=120.0, interval=interval
)
if timeout is None:
timeout = _setlist_copy_timeout(len(expected))

msg = pa.FileMessage(action=pa.MessageAction.COPY, type=0)
msg.folder.key = source_key
msg.folder.is_factory = False
reply = self._file_operation(msg)
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
if not confirm:
return reply

assert timeout is not None
deadline = time.monotonic() + timeout
previous_destination = None
previous_folders = None
while True:
remaining = max(0.1, deadline - time.monotonic())
folders = self.list_folders(seconds=min(20.0, remaining))
folder_generation = tuple(
(f.key, f.name, f.slots, f.occupied, f.is_factory)
for f in folders)
if folder_generation != previous_folders:
previous_folders = folder_generation
if time.monotonic() >= deadline:
raise TimeoutError(
f"setlist COPY was sent once but did not publish a complete "
f"matching destination within {timeout}s; it was not replayed")
time.sleep(interval)
continue
created = [
folder for folder in folders
if folder.key not in before_keys
and _is_user_setlist_key(folder.key)
]
if len(created) > 1:
raise RuntimeError(
"more than one folder appeared during duplicate verification; "
"the device-created destination is ambiguous"
)
if created:
destination = created[0]
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError(
f"setlist COPY was sent once but did not publish a complete "
f"matching destination within {timeout}s; it was not replayed")
try:
listing = self.list_presets(
destination.key,
timeout=min(25.0, remaining),
include_empty=True,
)
except TimeoutError:
listing = []
actual = _complete_user_setlist_inventory(listing)
if actual == expected:
if previous_destination == actual:
return destination
previous_destination = actual
else:
previous_destination = None
if time.monotonic() >= deadline:
raise TimeoutError(
f"setlist COPY was sent once but did not publish a complete "
f"matching destination within {timeout}s; it was not replayed"
)
time.sleep(interval)

def _stable_folder_listing(self, *, timeout: float,
interval: float) -> list:
"""Return two identical folder generations inside one deadline."""
deadline = time.monotonic() + timeout
previous_identity = None
while True:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError(
f"no stable folder listing arrived within {timeout}s")
folders = self.list_folders(seconds=min(20.0, remaining))
identity = tuple(
(f.key, f.name, f.slots, f.occupied, f.is_factory)
for f in folders)
if identity == previous_identity:
return folders
previous_identity = identity
time.sleep(interval)

def _stable_complete_user_setlist(self, key: str, *, timeout: float,
interval: float) -> tuple:
"""Return two identical complete 256-slot generations for ``key``."""
deadline = time.monotonic() + timeout
previous = None
listings_seen = 0
while True:
remaining = max(0.1, deadline - time.monotonic())
try:
listing = self.list_presets(
key,
timeout=min(25.0, remaining),
include_empty=True,
)
except TimeoutError:
listing = []
actual = _complete_user_setlist_inventory(listing)
if actual is not None:
listings_seen += 1
if previous == actual:
return actual
previous = actual
else:
previous = None
if time.monotonic() >= deadline:
raise TimeoutError(
f"no stable complete 256-slot listing arrived for {key!r} "
f"within {timeout}s ({listings_seen} complete generation(s) seen)"
)
time.sleep(interval)

#: How many parameters each Global EQ band occupies, and the offset of each
#: control within a band. See :meth:`set_global_eq`.
Expand Down Expand Up @@ -4344,6 +4485,38 @@ def field_present(message, field: str) -> bool:
return False


def _preset_inventory(entries) -> tuple:
"""Stable occupied-inventory identity used for setlist COPY verification."""
return tuple(sorted(
(
entry.index,
entry.name,
entry.instrument if field_present(entry, "instrument") else 0,
)
for entry in entries
if field_present(entry, "name") and entry.name
))


def _complete_user_setlist_inventory(entries) -> tuple | None:
"""Occupied identity only when a user-setlist generation has all 256 slots."""
positions = [entry.index for entry in entries if field_present(entry, "index")]
if len(entries) != 256 or set(positions) != set(range(256)):
return None
return _preset_inventory(entries)


def _is_user_setlist_key(key: str) -> bool:
"""Whether ``key`` is a direct setlist child of the user preset root."""
prefix = f"{USER_SETLIST_ROOT}/"
return key.startswith(prefix) and "/" not in key[len(prefix):]


def _setlist_copy_timeout(occupied_presets: int) -> float:
"""Measured 4.1 COPY allowance, capped at ten minutes."""
return min(600.0, 90.0 + 2.0 * occupied_presets)


def blocks(p: preset.BinaryPreset) -> list:
"""The OCCUPIED grid cells of ``p``, as :class:`Block` entries.

Expand Down
10 changes: 9 additions & 1 deletion pyquadcortex/protocol/profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,19 @@ class QuadCortex41(QuadCortex):

MEASURED_ON = ("4.1.0",)
EVIDENCE = Evidence.CONTRIBUTED
VERIFIED = frozenset({"create_local_backup", "set_device_name"})
VERIFIED = frozenset({
"create_local_backup", "duplicate_setlist", "set_device_name"})
models = NoSnapshot("coros_4_1_0")
params = NoSnapshot("coros_4_1_0")
options = NoSnapshot("coros_4_1_0")

def duplicate_setlist(self, source_name: str, *, confirm: bool = True,
timeout: float | None = None,
interval: float = 2.0):
"""Duplicate a setlist with the CorOS 4.1 firmware-side COPY."""
return self._duplicate_setlist_41(
source_name, confirm=confirm, timeout=timeout, interval=interval)


class QuadCortexMini(QuadCortex):
"""Quad Cortex Mini - recognised, not supported, and here to be finished.
Expand Down
Loading
Loading