From c9df5375672ec9b7a999a6ae570400359a2f6654 Mon Sep 17 00:00:00 2001 From: Jimmy Date: Wed, 21 Oct 2026 15:53:22 +1300 Subject: [PATCH] Set SMC-PAD colours over the pad's existing Bluetooth link. Co-authored-by: Cursor --- scripts/smc_pad.py | 422 ++++++++++++++++++++++++++++++++++++++++++ tests/test_smc_pad.py | 53 ++++++ 2 files changed, 475 insertions(+) create mode 100644 scripts/smc_pad.py create mode 100644 tests/test_smc_pad.py diff --git a/scripts/smc_pad.py b/scripts/smc_pad.py new file mode 100644 index 0000000..c911900 --- /dev/null +++ b/scripts/smc_pad.py @@ -0,0 +1,422 @@ +#!/usr/bin/env python3 +"""Set the colours of the SMC-PAD pads. + +MidiSuite is not required. This talks to the pad over the Bluetooth +connection it already has. + + python3 scripts/smc_pad.py + python3 scripts/smc_pad.py 1 blue 2 green 5 red + python3 scripts/smc_pad.py 1-4 blue 5-8 red --all off + python3 scripts/smc_pad.py --bank 8 1 ff8800 + +Pad 1 is the bottom-left pad. Numbers then go right, and the next row +starts at the left. A colour is a name (red, green, blue, yellow, cyan, +magenta, orange, white, off) or six hex digits, such as ff8800. + +The colour shows straight away. It stays until the pad is switched off. +""" + +from __future__ import annotations + +import argparse +import queue +import sys +import threading +import time +from dataclasses import dataclass + +PRESET_SIZE = 3539 +PAD_BANKS = 8 +PAD_COUNT = 16 +PAD_RECORD_SIZE = 26 +PAD_TABLE_OFFSET = 211 +PAD_RGB_OFFSET = 5 +PAD_LED_OFFSET = 8 +LED_FOLLOWS_HOST = 0xFF + +READ = 0x23 +WRITE = 0x22 +PRESET_REGION = 0x05 +STATE_REGION = 0x04 +ACK = bytes.fromhex("00590001000000ff") + +STATE_BASE_BANK = 6 +STATE_SLOT = 10 +STATE_BANK_TOGGLE = 11 +TOGGLE_BANK = 8 + +COLOURS = { + "off": (0x00, 0x00, 0x00), + "black": (0x00, 0x00, 0x00), + "red": (0xF0, 0x00, 0x00), + "green": (0x00, 0xF0, 0x00), + "blue": (0x00, 0x00, 0xF0), + "yellow": (0xF0, 0xF0, 0x00), + "cyan": (0x00, 0xF0, 0xF0), + "magenta": (0xF0, 0x00, 0xF0), + "orange": (0xF0, 0x60, 0x00), + "white": (0xF0, 0xF0, 0xF0), +} + +# Top row first, so a printed grid matches the pad under your hands. +READING_ROWS = ((13, 14, 15, 16), (9, 10, 11, 12), (5, 6, 7, 8), (1, 2, 3, 4)) + + +class PadError(Exception): + pass + + +def vendor_packet(command: int, region: int, address: int, data_or_count: bytes | int) -> bytes: + """One read or write for the pad's configuration channel.""" + if isinstance(data_or_count, int): + count, data = data_or_count, b"" + else: + count, data = len(data_or_count), data_or_count + payload = bytes((region, *address.to_bytes(4, "little"), *count.to_bytes(3, "little"))) + data + checksum = (~sum(payload)) & 0xFF + return bytes((0x00, 0x59, command, *len(payload).to_bytes(3, "little"))) + payload + bytes((checksum,)) + + +@dataclass(frozen=True) +class Reply: + command: int + region: int + address: int + data: bytes + checksum_ok: bool + + +def parse_reply(packet: bytes) -> Reply: + if len(packet) < 7 or packet[0] != 0x00 or packet[1] != 0x59: + raise PadError(f"unexpected reply {packet.hex()}") + command = packet[2] + length = int.from_bytes(packet[3:6], "little") + payload = packet[6 : 6 + length] + checksum_ok = len(packet) > 6 + length and (sum(payload) + packet[6 + length]) & 0xFF == 0xFF + if command in (READ, WRITE) and len(payload) >= 8: + count = int.from_bytes(payload[5:8], "little") + return Reply( + command, + payload[0], + int.from_bytes(payload[1:5], "little"), + payload[8 : 8 + count], + checksum_ok, + ) + return Reply(command, 0, 0, payload, checksum_ok) + + +def bank_address(slot: int, bank: int) -> int: + if not 0 <= slot <= 7: + raise PadError(f"preset slot must be 0 to 7, got {slot}") + if not 1 <= bank <= PAD_BANKS: + raise PadError(f"bank must be 1 to {PAD_BANKS}, got {bank}") + return slot * PRESET_SIZE + PAD_TABLE_OFFSET + (bank - 1) * PAD_COUNT * PAD_RECORD_SIZE + + +def parse_state(block: bytes) -> tuple[int, int]: + """Return the preset slot and the pad bank on display.""" + if len(block) < 16: + raise PadError("state block is too short") + slot = block[STATE_SLOT] + base = block[STATE_BASE_BANK] + toggle = block[STATE_BANK_TOGGLE] + if not 0 <= slot <= 7 or not 0 <= base <= 7 or toggle not in (0, 1): + raise PadError(f"state block is not a preset display: {block.hex()}") + bank = TOGGLE_BANK if toggle else base + 1 + return slot, bank + + +def colour_of(text: str) -> tuple[int, int, int]: + name = text.strip().lower() + if name in COLOURS: + return COLOURS[name] + hex_digits = name[1:] if name.startswith("#") else name + if len(hex_digits) == 6 and all(c in "0123456789abcdef" for c in hex_digits): + return tuple(int(hex_digits[i : i + 2], 16) for i in (0, 2, 4)) # type: ignore[return-value] + known = ", ".join(name for name in COLOURS if name != "black") + raise PadError(f"unknown colour {text!r}. Use {known}, or six hex digits.") + + +def pad_numbers(text: str) -> list[int]: + """'1', '1-4', and '1,3,5' all name pads.""" + pads: list[int] = [] + for part in text.split(","): + part = part.strip() + if not part: + continue + ends = part.split("-") + if len(ends) == 1: + pads.append(_one_pad(ends[0])) + elif len(ends) == 2: + first, last = _one_pad(ends[0]), _one_pad(ends[1]) + step = 1 if last >= first else -1 + pads.extend(range(first, last + step, step)) + else: + raise PadError(f"bad pad range {text!r}") + if not pads: + raise PadError(f"bad pad {text!r}") + return pads + + +def _one_pad(text: str) -> int: + if not text.isdigit(): + raise PadError(f"bad pad {text!r}") + number = int(text) + if not 1 <= number <= PAD_COUNT: + raise PadError(f"pad must be 1 to {PAD_COUNT}, got {number}") + return number + + +def colour_map(items: list[str], fill: str | None) -> dict[int, tuple[int, int, int]]: + """Pairs of pad and colour. Later pairs win. ``fill`` paints every pad first.""" + chosen: dict[int, tuple[int, int, int]] = {} + if fill is not None: + rgb = colour_of(fill) + chosen = {pad: rgb for pad in range(1, PAD_COUNT + 1)} + if len(items) % 2: + raise PadError("each pad needs a colour, for example: 1 blue 5 red") + for pad_text, colour_text in zip(items[0::2], items[1::2]): + rgb = colour_of(colour_text) + for pad in pad_numbers(pad_text): + chosen[pad] = rgb + return chosen + + +def rgb_at(bank: bytes, pad: int) -> tuple[int, int, int]: + start = (pad - 1) * PAD_RECORD_SIZE + PAD_RGB_OFFSET + return bank[start], bank[start + 1], bank[start + 2] + + +def led_at(bank: bytes, pad: int) -> int: + return bank[(pad - 1) * PAD_RECORD_SIZE + PAD_LED_OFFSET] + + +def paint(bank: bytes, colours: dict[int, tuple[int, int, int]]) -> bytearray: + painted = bytearray(bank) + for pad, rgb in colours.items(): + start = (pad - 1) * PAD_RECORD_SIZE + PAD_RGB_OFFSET + painted[start : start + 3] = rgb + return painted + + +def format_colour(rgb: tuple[int, int, int]) -> str: + return "#{:02x}{:02x}{:02x}".format(*rgb) + + +def format_grid(bank: bytes) -> str: + lines = [] + for row in READING_ROWS: + cells = [] + for pad in row: + cells.append(f"{pad:2d} {format_colour(rgb_at(bank, pad))}") + lines.append(" ".join(cells)) + return "\n".join(lines) + + +class PadLink: + """BlueZ client for the pad's configuration characteristics.""" + + def __init__(self) -> None: + self._queue: queue.Queue[bytes | BaseException] = queue.Queue() + self._loop = None + self._notify = None + self._write = None + self._notify_path = "" + + def __enter__(self) -> PadLink: + self.open() + return self + + def __exit__(self, *_args: object) -> None: + self.close() + + def open(self) -> None: + import dbus + from dbus.mainloop.glib import DBusGMainLoop + from gi.repository import GLib + + # Look up the pad before the GLib bus exists. On this machine a + # GLib connection does not list the configuration characteristics. + probe = dbus.SystemBus() + device = _find_device(probe, dbus) + write_path, notify_path = _find_channels(probe, dbus, device) + + DBusGMainLoop(set_as_default=True) + bus = dbus.SystemBus(private=True) + self._notify_path = notify_path + self._notify = dbus.Interface(bus.get_object("org.bluez", notify_path), "org.bluez.GattCharacteristic1") + self._write = dbus.Interface(bus.get_object("org.bluez", write_path), "org.bluez.GattCharacteristic1") + bus.add_signal_receiver( + self._on_value, + signal_name="PropertiesChanged", + dbus_interface="org.freedesktop.DBus.Properties", + path=notify_path, + ) + self._loop = GLib.MainLoop() + threading.Thread(target=self._loop.run, daemon=True).start() + self._notify.StartNotify() + + def close(self) -> None: + if self._notify is not None: + try: + self._notify.StopNotify() + except Exception: + pass + if self._loop is not None: + self._loop.quit() + + def _on_value(self, _iface: str, changed: dict, _invalidated: list) -> None: + if "Value" in changed: + self._queue.put(bytes(changed["Value"])) + + def request(self, packet: bytes) -> bytes: + from gi.repository import GLib + + while not self._queue.empty(): + self._queue.get_nowait() + + def send() -> bool: + try: + import dbus + + self._write.WriteValue( + dbus.Array(packet, signature="y"), + dbus.Dictionary({"type": "command"}, signature="sv"), + ) + except Exception as exc: + self._queue.put(exc) + return False + + GLib.idle_add(send) + try: + reply = self._queue.get(timeout=3) + except queue.Empty: + raise PadError("the pad did not answer") from None + if isinstance(reply, BaseException): + raise PadError(str(reply)) from reply + return reply + + def read(self, address: int, count: int, region: int = PRESET_REGION) -> bytes: + raw = self.request(vendor_packet(READ, region, address, count)) + reply = parse_reply(raw) + if reply.command != READ or not reply.checksum_ok: + raise PadError(f"bad read reply {raw.hex()}") + if reply.region != region or reply.address != address or len(reply.data) != count: + raise PadError( + f"read {region:#x}:{address:#x} returned {len(reply.data)} bytes " + f"from {reply.region:#x}:{reply.address:#x}" + ) + return reply.data + + def write(self, address: int, data: bytes, region: int = PRESET_REGION) -> None: + raw = self.request(vendor_packet(WRITE, region, address, data)) + if raw != ACK: + reply = parse_reply(raw) + if not reply.checksum_ok: + raise PadError(f"the pad rejected the write: {raw.hex()}") + + +def _find_device(bus: object, dbus: object) -> str: + manager = dbus.Interface(bus.get_object("org.bluez", "/"), "org.freedesktop.DBus.ObjectManager") + objects = manager.GetManagedObjects() + found: list[tuple[bool, str]] = [] + for path, ifaces in objects.items(): + device = ifaces.get("org.bluez.Device1") + if not device: + continue + name = str(device.get("Name", "") or device.get("Alias", "")) + if "smc-pad" not in name.lower(): + continue + found.append((bool(device.get("Connected", False)), str(path))) + if not found: + raise PadError("SMC-PAD not found. Turn it on, and pair it in Bluetooth settings.") + found.sort(reverse=True) + path = found[0][1] + device = dbus.Interface(bus.get_object("org.bluez", path), "org.bluez.Device1") + props = dbus.Interface(bus.get_object("org.bluez", path), "org.freedesktop.DBus.Properties") + if not bool(props.Get("org.bluez.Device1", "Connected")): + device.Connect() + deadline = time.time() + 8 + while time.time() < deadline: + if bool(props.Get("org.bluez.Device1", "Connected")): + break + time.sleep(0.2) + else: + raise PadError("could not connect to the SMC-PAD") + return path + + +def _find_channels(bus: object, dbus: object, device: str) -> tuple[str, str]: + deadline = time.time() + 5 + while True: + manager = dbus.Interface(bus.get_object("org.bluez", "/"), "org.freedesktop.DBus.ObjectManager") + objects = manager.GetManagedObjects() + write_path = notify_path = "" + for path, ifaces in objects.items(): + if not str(path).startswith(device): + continue + char = ifaces.get("org.bluez.GattCharacteristic1") + if not char: + continue + uuid = str(char.get("UUID", "")).lower() + if uuid.startswith("0000ae41-"): + write_path = str(path) + elif uuid.startswith("0000ae42-"): + notify_path = str(path) + if write_path and notify_path: + return write_path, notify_path + if time.time() > deadline: + raise PadError("the pad is connected, but its configuration channel is missing") + time.sleep(0.2) + + +def showing(link: PadLink, preset: int | None, bank: int | None) -> tuple[int, int, bytes]: + slot, visible = parse_state(link.read(0, 16, STATE_REGION)) + if preset is not None: + if not 1 <= preset <= 8: + raise PadError("preset must be 1 to 8") + slot = preset - 1 + if bank is not None: + if not 1 <= bank <= PAD_BANKS: + raise PadError("bank must be 1 to 8") + visible = bank + image = link.read(bank_address(slot, visible), PAD_COUNT * PAD_RECORD_SIZE) + return slot, visible, image + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("items", nargs="*", help="pad colour pairs, such as 1 blue 5-8 red") + parser.add_argument("--all", metavar="COLOUR", help="paint every pad this colour first") + parser.add_argument("--bank", type=int, help="pad bank 1 to 8; the bank on display is the default") + parser.add_argument("--preset", type=int, help="preset 1 to 8; the preset on display is the default") + args = parser.parse_args(argv) + + try: + colours = colour_map(args.items, args.all) + with PadLink() as link: + slot, bank, image = showing(link, args.preset, args.bank) + print(f"Preset {slot + 1}, bank {bank}. Pad 1 is the bottom-left pad.") + if not colours: + print(format_grid(image)) + hidden = [pad for pad in range(1, PAD_COUNT + 1) if led_at(image, pad) != LED_FOLLOWS_HOST] + if hidden: + listed = ", ".join(str(pad) for pad in hidden) + print(f"Pads {listed} show incoming MIDI, so their stored colour stays hidden.") + return 0 + updated = paint(image, colours) + if updated == image: + print(format_grid(image)) + print("Those pads are already that colour.") + return 0 + link.write(bank_address(slot, bank), bytes(updated)) + print(format_grid(updated)) + print("Saved on the pad until it is switched off.") + except PadError as exc: + print(exc, file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_smc_pad.py b/tests/test_smc_pad.py new file mode 100644 index 0000000..2f61939 --- /dev/null +++ b/tests/test_smc_pad.py @@ -0,0 +1,53 @@ +"""Packet layout and colour parsing for scripts/smc_pad.py.""" + +from __future__ import annotations + +import importlib.util +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +spec = importlib.util.spec_from_file_location("smc_pad", ROOT / "scripts" / "smc_pad.py") +pad = importlib.util.module_from_spec(spec) +assert spec.loader is not None +sys.modules["smc_pad"] = pad +spec.loader.exec_module(pad) + + +def test_write_packet_matches_a_live_encoder_write() -> None: + # Encoder 0 of preset slot 4, rewritten with its own six bytes. + packet = pad.vendor_packet(pad.WRITE, 5, 4 * 3539 + 115, bytes.fromhex("0002001e007f")) + assert packet.hex() == "0059220e000005bf3700000600000002001e007f5f" + + +def test_state_block_from_this_pad() -> None: + block = bytes.fromhex("77003204000002000101040000000000") + slot, bank = pad.parse_state(block) + assert (slot, bank) == (4, 3) + + +def test_colour_names_and_hex() -> None: + assert pad.colour_of("Blue") == (0x00, 0x00, 0xF0) + assert pad.colour_of("#f000f0") == (0xF0, 0x00, 0xF0) + assert pad.colour_of("ff8800") == (0xFF, 0x88, 0x00) + + +def test_ranges_and_later_pairs_win() -> None: + chosen = pad.colour_map(["1-4", "blue", "3", "red", "1,2", "white"], "off") + assert chosen[1] == pad.COLOURS["white"] + assert chosen[3] == pad.COLOURS["red"] + assert chosen[4] == pad.COLOURS["blue"] + assert chosen[16] == pad.COLOURS["off"] + + +def test_paint_changes_only_the_named_pad() -> None: + bank = bytes(pad.PAD_COUNT * pad.PAD_RECORD_SIZE) + painted = pad.paint(bank, {1: (1, 2, 3), 16: (4, 5, 6)}) + assert pad.rgb_at(painted, 1) == (1, 2, 3) + assert pad.rgb_at(painted, 16) == (4, 5, 6) + assert pad.rgb_at(painted, 2) == (0, 0, 0) + assert painted[3:5] == bank[3:5] + + +def test_bank_address_of_the_visible_bank() -> None: + assert pad.bank_address(4, 3) == 4 * 3539 + 211 + 2 * 16 * 26