dx5ii-cli 0.0.1__py3-none-any.whl

dx5ii/__init__.py

@@ -0,0 +1,114 @@
+"""Control a Topping DX5 II over its HID interface.
+
+Public API::
+
+    from dx5ii import Dx5ii, Dx5iiError, apply_changes
+
+    with Dx5ii() as dev:
+        state = dev.snapshot()                 # full read
+        dev.set_output("hp_balanced")          # switch output port
+        dev.set_config_index(2)                # switch EQ preset
+
+Everything the CLI does is available here; the CLI is a thin wrapper around
+:class:`Dx5ii`, :func:`dx5ii.fields.encode_field` and
+:func:`dx5ii.actions.apply_changes`.
+"""
+
+from __future__ import annotations
+
+from .actions import apply_changes, state_summary
+from .bands import (
+    Band,
+    decode_block,
+    encode_block,
+    encode_name_words,
+    parse_apo_filters,
+)
+from .constants import (
+    PID,
+    PROTOCOL_INTERFACE,
+    PT_READ,
+    PT_WRITE,
+    VID,
+)
+from .device import Dx5ii, list_interfaces
+from .errors import Dx5iiError
+from .fields import (
+    FIELD_ACTIONS,
+    FIELD_SPECS,
+    encode_field,
+    field_raw,
+    field_state,
+    resolve_config,
+    resolve_output,
+)
+from .interpreter import (
+    collect_words,
+    interpret_config_blocks,
+    interpret_config_upload,
+    interpret_peq_preview,
+    interpret_sampling,
+    interpret_settings,
+)
+from .peq import (
+    create_preset,
+    delete_preset,
+    find_preset,
+    read_presets,
+    rename_preset,
+)
+from .protocol import Frame, build_frame, db_to_volume, decode_name, format_firmware, mask_to_items, parse_frame, volume_to_db
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    # identity
+    "VID",
+    "PID",
+    "PROTOCOL_INTERFACE",
+    "PT_READ",
+    "PT_WRITE",
+    # device
+    "Dx5ii",
+    "Dx5iiError",
+    "list_interfaces",
+    # actions
+    "apply_changes",
+    "state_summary",
+    # fields
+    "FIELD_SPECS",
+    "FIELD_ACTIONS",
+    "encode_field",
+    "field_state",
+    "field_raw",
+    "resolve_output",
+    "resolve_config",
+    # EQ presets
+    "Band",
+    "decode_block",
+    "encode_block",
+    "encode_name_words",
+    "parse_apo_filters",
+    "read_presets",
+    "find_preset",
+    "create_preset",
+    "delete_preset",
+    "rename_preset",
+    # protocol
+    "Frame",
+    "build_frame",
+    "parse_frame",
+    "decode_name",
+    "volume_to_db",
+    "format_firmware",
+    "db_to_volume",
+    "mask_to_items",
+    # interpreters
+    "collect_words",
+    "interpret_settings",
+    "interpret_sampling",
+    "interpret_peq_preview",
+    "interpret_config_upload",
+    "interpret_config_blocks",
+]

dx5ii/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m dx5ii`` entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dx5ii/actions.py

@@ -0,0 +1,146 @@
+"""High-level switches: "make the device look like X", with before/after.
+
+``apply_changes`` is what the game watcher uses: it switches the output port
+first, then the EQ preset, and reports both the state it found and the state
+it left behind.  The ``before`` block is what a caller needs in order to roll
+back later.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .device import Dx5ii
+from .errors import Dx5iiError
+from .fields import resolve_config, resolve_output
+
+
+def state_summary(snap: dict[str, Any]) -> dict[str, Any]:
+    """Condense a snapshot to the four values a caller cares about."""
+    settings = snap.get("settings") or {}
+    configs = snap.get("configs") or {}
+    preview = snap.get("peq") or {}
+
+    index = configs.get("current_index")
+    if index is None and preview.get("preview_active") is False:
+        index = preview.get("local_index")
+    return {
+        "output": settings.get("output"),
+        "output_raw": settings.get("output_raw"),
+        "input": settings.get("input"),
+        "input_raw": settings.get("input_raw"),
+        "config_index": index,
+        "config_name": configs.get("current_name"),
+        "preview_active": preview.get("preview_active"),
+    }
+
+
+def apply_changes(
+    dev: Dx5ii,
+    snap: dict[str, Any],
+    want_output: Optional[str] = None,
+    want_config: Optional[Any] = None,
+) -> dict[str, Any]:
+    """Switch the output port and/or the EQ preset, then read the state back.
+
+    The output switch runs first because each port remembers its own EQ preset:
+    switching the port may change the active preset, so the preset check has to
+    happen afterwards.  Both switches are idempotent -- a value that already
+    matches is left alone.
+
+    Returns a report with ``ok``, ``changed``, ``before``, ``after``,
+    ``actions`` and ``errors``.
+    """
+    configs = snap.get("configs") or {}
+    known = {item["index"]: item["name"] for item in (configs.get("configs") or [])}
+    settings = snap.get("settings") or {}
+
+    report: dict[str, Any] = {
+        "ok": True,
+        "changed": False,
+        "before": state_summary(snap),
+        "after": None,
+        "actions": [],
+        "errors": [],
+    }
+    before = report["before"]
+
+    if want_output is not None:
+        try:
+            raw = resolve_output(want_output)
+        except Dx5iiError as exc:
+            report["ok"] = False
+            report["errors"].append(str(exc))
+        else:
+            start = settings.get("output_raw")
+            if start == raw:
+                report["actions"].append({
+                    "what": "output", "from": start, "to": raw, "changed": False})
+            else:
+                got = dev.set_output(raw)
+                ok = bool(got) and got.get("output_raw") == raw
+                report["changed"] = report["changed"] or ok
+                report["ok"] = report["ok"] and ok
+                report["actions"].append({
+                    "what": "output", "from": start, "to": raw, "changed": ok,
+                    "observed": (got or {}).get("output"),
+                })
+                if ok:
+                    # Each port remembers its own preset, so the value worth
+                    # restoring is the one *after* the switch.
+                    new_index = dev.current_config_index()
+                    before.update({
+                        "output": (got or {}).get("output"),
+                        "output_raw": raw,
+                        "config_index": new_index,
+                        "config_name": known.get(new_index),
+                    })
+                else:
+                    report["errors"].append(
+                        f"output did not change to {raw!r} "
+                        f"(observed {(got or {}).get('output_raw')!r})")
+
+    if want_config is not None:
+        try:
+            target = resolve_config(want_config, configs.get("configs") or [])
+        except Dx5iiError as exc:
+            report["ok"] = False
+            report["errors"].append(str(exc))
+        else:
+            start = before.get("config_index")
+            if start is None:
+                start = dev.current_config_index()
+            if start == target:
+                report["actions"].append({
+                    "what": "config", "from": start, "to": target, "changed": False})
+            else:
+                got = dev.set_config_index(target)
+                ok = got == target
+                report["changed"] = report["changed"] or ok
+                report["ok"] = report["ok"] and ok
+                report["actions"].append({
+                    "what": "config", "from": start, "to": target, "changed": ok,
+                    "observed": got,
+                })
+                if not ok:
+                    report["errors"].append(
+                        f"config did not change to {target!r} (observed {got!r})")
+
+    final = dev.snapshot(include_configs=False, keep_raw=False)
+    summary = state_summary(final)
+    if summary["config_index"] is None:
+        try:
+            summary["config_index"] = dev.current_config_index()
+        except Dx5iiError:
+            pass
+    if summary["config_index"] is not None:
+        summary["config_name"] = known.get(summary["config_index"])
+    report["after"] = summary
+
+    if summary["output"] is None:
+        report["ok"] = False
+        report["errors"].append("could not read state back after the switch")
+    return report
+
+
+__all__ = ["apply_changes", "state_summary"]

dx5ii/bands.py

@@ -0,0 +1,218 @@
+"""EQ preset blocks: the 78-word payload the device stores per preset.
+
+Layout (verified 2026-11-09 against the five factory presets; the
+``IER-M7.Harman`` block matches ``harman_10band.txt`` exactly):
+
+    word 0..3     preset name, UTF-8, little-endian, NUL padded
+    word 4        enabled flag (1)
+    word 5        content hash / revision
+    word 6        enabled flag (1)
+    word 7        content hash / revision (same as word 5)
+    word 8..40    left channel, 11 bands x 3 words
+    word 41..73   right channel, 11 bands x 3 words
+    word 74..77   zero
+
+Each band is three words::
+
+    packed = enabled | type << 8 | gain_tenth_db << 16   (gain is signed 8-bit)
+    freq_hz
+    q * 10000
+
+``type`` is 1 = PK, 4 = LS (low shelf), 5 = HS (high shelf); 3 also appears in
+the factory ``SPEAKER`` preset and is kept verbatim.  Band 11 is the device's
+spare slot: disabled, 632 Hz, Q 0.707.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Iterable, Sequence
+
+from .constants import (
+    BAND_TYPE_IDS,
+    BAND_TYPES,
+    BANDS_PER_CHANNEL,
+    BAND_WORDS,
+    CONFIG_BLOCK_WORDS,
+    CONFIG_HEAD_WORDS,
+)
+from .protocol import decode_name
+
+DEFAULT_Q = 0.707
+DEFAULT_FREQ = 632
+MIN_FREQ = 20
+MAX_FREQ = 20000
+MIN_Q = 0.1
+MAX_Q = 15.0
+MAX_GAIN_DB = 12.0
+
+
+@dataclass
+class Band:
+    """One parametric EQ band."""
+
+    enabled: bool = True
+    type: str = "PK"
+    gain_db: float = 0.0
+    freq_hz: float = DEFAULT_FREQ
+    q: float = DEFAULT_Q
+
+    def __post_init__(self) -> None:
+        self.gain_db = max(-MAX_GAIN_DB, min(MAX_GAIN_DB, round(self.gain_db, 1)))
+        self.freq_hz = float(max(MIN_FREQ, min(MAX_FREQ, round(self.freq_hz))))
+        self.q = max(MIN_Q, min(MAX_Q, round(self.q, 4)))
+
+    def as_dict(self) -> dict:
+        return {
+            "enabled": self.enabled,
+            "type": self.type,
+            "gain_db": self.gain_db,
+            "freq_hz": self.freq_hz,
+            "q": self.q,
+        }
+
+    def to_ap_filter(self, index: int) -> str:
+        """Render as an Equalizer APO line (``PK``/``LSC``/``HSC``)."""
+        kind = {"PK": "PK", "LS": "LSC", "HS": "HSC"}.get(self.type, "PK")
+        state = "ON" if self.enabled else "OFF"
+        return (
+            f"Filter {index}: {state} {kind} Fc {self.freq_hz:g} Hz "
+            f"Gain {self.gain_db:+g} dB Q {self.q:g}"
+        )
+
+
+SPARE_BAND = Band(enabled=False, type="PK", gain_db=0.0, freq_hz=DEFAULT_FREQ)
+SPARE_WORDS: list[int] = [0x00000100, DEFAULT_FREQ, round(DEFAULT_Q * 10000)]
+
+
+def _signed_byte(value: int) -> int:
+    return value - 256 if value & 0x80 else value
+
+
+def decode_band(packed: int, freq: int, q: int) -> Band:
+    type_id = (packed >> 8) & 0xFF
+    return Band(
+        enabled=bool(packed & 0xFF),
+        type=BAND_TYPES.get(type_id, f"type{type_id}"),
+        gain_db=_signed_byte((packed >> 16) & 0xFF) / 10.0,
+        freq_hz=float(freq),
+        q=q / 10000.0,
+    )
+
+
+def encode_band(band: Band) -> list[int]:
+    type_id = BAND_TYPE_IDS.get(band.type, 1)
+    gain = max(-128, min(127, int(round(band.gain_db * 10)))) & 0xFF
+    packed = (gain << 16) | (type_id << 8) | (1 if band.enabled else 0)
+    return [
+        packed & 0xFFFFFFFF,
+        int(round(band.freq_hz)),
+        int(round(band.q * 10000)),
+    ]
+
+
+_APO_FILTER = re.compile(
+    r"^Filter\s+\d+\s*:\s*(ON|OFF)\s+(PK|LSC|HSC|LS|HS)\s+"
+    r"Fc\s+([0-9.]+)\s*Hz\s+Gain\s+([+-]?[0-9.]+)\s*dB(?:\s+Q\s+([0-9.]+))?",
+    re.IGNORECASE,
+)
+_APO_KIND = {"PK": "PK", "LSC": "LS", "LS": "LS", "HSC": "HS", "HS": "HS"}
+
+
+def parse_apo_filters(text: str) -> list[Band]:
+    """Parse ``Filter N: ON PK Fc ... Hz Gain ... dB Q ...`` lines.
+
+    Shelf filters without an explicit ``Q`` fall back to the device default.
+    Unknown filter kinds are skipped rather than guessed.
+    """
+    bands: list[Band] = []
+    for line in text.splitlines():
+        match = _APO_FILTER.match(line.strip())
+        if not match:
+            continue
+        state, kind, freq, gain, q = match.groups()
+        if kind.upper() not in _APO_KIND:
+            continue
+        bands.append(Band(
+            enabled=state.upper() == "ON",
+            type=_APO_KIND[kind.upper()],
+            gain_db=float(gain),
+            freq_hz=float(freq),
+            q=float(q) if q else DEFAULT_Q,
+        ))
+    return bands
+
+
+def encode_name_words(name: str) -> list[int]:
+    """Encode a preset name as the eight UTF-8 words used by rename/upload."""
+    raw = name.encode("utf-8")[:32].ljust(32, b"\x00")
+    return [int.from_bytes(raw[i * 4:(i + 1) * 4], "little") for i in range(8)]
+
+
+def decode_bands(words: Sequence[int], channel: int) -> list[Band]:
+    base = CONFIG_HEAD_WORDS + channel * BANDS_PER_CHANNEL * BAND_WORDS
+    out: list[Band] = []
+    for i in range(BANDS_PER_CHANNEL):
+        offset = base + i * BAND_WORDS
+        out.append(decode_band(words[offset], words[offset + 1], words[offset + 2]))
+    return out
+
+
+def decode_block(words: Sequence[int]) -> dict:
+    """Decode one 78-word preset block."""
+    if len(words) < CONFIG_BLOCK_WORDS:
+        raise ValueError(f"need {CONFIG_BLOCK_WORDS} words, got {len(words)}")
+    return {
+        "name": decode_name(list(words[0:4])),
+        "enabled": bool(words[4]),
+        "hash": words[5],
+        "bands_left": decode_bands(words, 0),
+        "bands_right": decode_bands(words, 1),
+    }
+
+
+def _pad_bands(bands: Iterable[Band]) -> list[Band]:
+    items = list(bands)[:BANDS_PER_CHANNEL]
+    while len(items) < BANDS_PER_CHANNEL:
+        items.append(SPARE_BAND)
+    return items
+
+
+def encode_block(
+    name: str,
+    bands_left: Iterable[Band],
+    bands_right: Iterable[Band],
+    head: Sequence[int] | None = None,
+) -> list[int]:
+    """Build a 78-word preset block ready for ``CMD_DOWNLOAD_CONFIG``.
+
+    ``head`` supplies words 4..7 (enabled flag + hash, twice).  When omitted a
+    zero hash is sent; the device fills it in on save.
+    """
+    words = [0] * CONFIG_BLOCK_WORDS
+    raw = name.encode("utf-8")[:16].ljust(16, b"\x00")
+    for i in range(4):
+        words[i] = int.from_bytes(raw[i * 4:(i + 1) * 4], "little")
+
+    words[4:8] = list(head)[:4] if head else [1, 0, 1, 0]
+
+    for channel, bands in enumerate((bands_left, bands_right)):
+        base = CONFIG_HEAD_WORDS + channel * BANDS_PER_CHANNEL * BAND_WORDS
+        for i, band in enumerate(_pad_bands(bands)):
+            words[base + i * BAND_WORDS: base + (i + 1) * BAND_WORDS] = encode_band(band)
+    return words
+
+
+__all__ = [
+    "Band",
+    "SPARE_BAND",
+    "SPARE_WORDS",
+    "decode_band",
+    "decode_bands",
+    "decode_block",
+    "encode_band",
+    "encode_block",
+    "encode_name_words",
+    "parse_apo_filters",
+]