biamp-ntp 0.1.0__tar.gz

biamp_ntp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

biamp_ntp-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: biamp-ntp
+Version: 0.1.0
+Summary: Dependency-free Python client + CLI for the Biamp Nexia/Audia Text Protocol (telnet control)
+Author: Matt
+License: MIT
+Project-URL: Homepage, https://github.com/biamp-ntp/biamp-ntp
+Project-URL: Issues, https://github.com/biamp-ntp/biamp-ntp/issues
+Keywords: biamp,nexia,audia,dsp,telnet,audio,home-automation,av
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Home Automation
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# biamp-ntp
+
+A tiny, **dependency-free** Python client and CLI for the **Biamp Nexia / Audia Text Protocol** — the line-based control protocol those DSPs expose over telnet (TCP port 23, no authentication).
+
+Works with the Nexia family (CS / PM / SP / VC / TC) and Audia (FLOW, …). Pure standard library, so it runs anywhere Python does — macOS, Linux, a Raspberry Pi, inside Home Assistant, wherever. No vendor software or Windows box needed for day-to-day control.
+
+> Extracted and generalized from a working Nexia PM sub-controller. The fiddly parts — telnet IAC stripping, reply framing, and the instance-ID drift problem — are already solved here.
+
+## Install
+
+```bash
+# from GitHub (works today):
+pip install git+https://github.com/biamp-ntp/biamp-ntp
+
+# or from a local checkout:
+pip install -e .
+```
+
+> The short form `pip install biamp-ntp` will work once it's published to PyPI.
+
+## CLI
+
+```bash
+# read the device number (needed as <dev> in every command; usually 1)
+biamp-ntp --host 192.168.1.199 devid
+
+# discover instance IDs — the #1 thing you need (see "Instance IDs" below)
+biamp-ntp --host 192.168.1.199 scan OUTLVLPM          # sweep output-level blocks
+biamp-ntp --host 192.168.1.199 scan MMLVLOUT          # sweep matrix outputs
+
+# read / write an attribute:  <attr> <instance> <idx...> [value]
+biamp-ntp --host 192.168.1.199 get OUTLVLPM 8 5        # output block inst 8, ch 5
+biamp-ntp --host 192.168.1.199 set OUTLVLPM 8 5 -6.0   # set ch 5 to -6 dB
+biamp-ntp --host 192.168.1.199 set OUTMUTEPM 8 5 1     # mute ch 5
+
+# escape hatch: send any raw command line
+biamp-ntp --host 192.168.1.199 raw GET 0 DEVID
+```
+
+## Library
+
+```python
+from biamp_ntp import BiampNTP, scan, protocol as p
+
+with BiampNTP("192.168.1.199") as dsp:
+    print(dsp.device_id())                       # -> 1
+
+    # find the output block's instance ID (don't hardcode it)
+    for inst, val in scan(dsp, p.OUTPUT_LEVEL_PM):
+        print("output block at instance", inst)
+
+    level = dsp.get_float(p.OUTPUT_LEVEL_PM, 8, 5)   # ch 5 level, dB
+    dsp.set(p.OUTPUT_LEVEL_PM, 8, 5, -6.0)           # set ch 5 to -6 dB
+    dsp.set(p.OUTPUT_MUTE_PM, 8, 5, True)            # mute (bool -> 1)
+```
+
+`command()` is thread-safe and reconnects automatically if the socket drops.
+
+## Instance IDs — read this
+
+Every block in a Biamp design has an **instance ID**, used in every GET/SET. The catch: **instance IDs are assigned at compile time and renumber whenever the design is recompiled and re-pushed** from the Windows software. So the numbers in your `.nex` file go stale, and hardcoding them will silently break after an edit.
+
+Always discover them live:
+
+```bash
+biamp-ntp --host <ip> scan <ATTR>
+```
+
+Only a real block of that type answers; everything else returns `-ERR:XACTION ERROR`. Use `--range 1-400` for large designs.
+
+## Common attributes
+
+| Block | Level | Mute | Other | Index |
+|---|---|---|---|---|
+| PM input | `INPLVLPML` | `INPMUTEPML` | `INPGAINPML` | input |
+| PM output | `OUTLVLPM` | `OUTMUTEPM` | `OUTINVRTPM` (polarity) | output ch |
+| Generic output | `OUTLVL` | `OUTMUTE` | | output ch |
+| Matrix mixer | `MMLVLOUT` / `MMLVLIN` | `MMMUTEOUT` | `MMLVLXP` (crosspoint) | out / in |
+| Level (fader) | `FDRLVL` | `FDRMUTE` | | channel |
+| Device | | | `DEVID` (GET 0 DEVID) | — |
+
+Levels are dB; mute/invert are `0`/`1`. Crosspoints (`MMLVLXP`/`MMMUTEXP`) take two indices: input row, output column. Any attribute string works with `get`/`set` — the table is just the common ones. See `biamp_ntp/protocol.py`.
+
+## Protocol notes (the gotchas)
+
+- **Grammar:** `GET <dev> <ATTR> <inst> <idx...>` → value; `SET <dev> <ATTR> <inst> <idx...> <value>` → `+OK`. Errors: `-ERR:SYNTAX`, `-ERR:XACTION ERROR`.
+- **Telnet IAC:** the server sends IAC negotiation bytes on connect and can interleave them with replies — this library strips them.
+- **Reply timing:** replies dribble out just after the command echo; a single immediate `recv()` catches a partial frame. The client settles briefly then drains fully (tunable via `settle=`).
+- **One client at a time:** the telnet server is happiest single-threaded; `command()` serializes on a lock.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+The unit tests need no hardware (they cover parsing / IAC / formatting).
+
+## License
+
+MIT.

biamp_ntp-0.1.0/README.md

@@ -0,0 +1,102 @@
+# biamp-ntp
+
+A tiny, **dependency-free** Python client and CLI for the **Biamp Nexia / Audia Text Protocol** — the line-based control protocol those DSPs expose over telnet (TCP port 23, no authentication).
+
+Works with the Nexia family (CS / PM / SP / VC / TC) and Audia (FLOW, …). Pure standard library, so it runs anywhere Python does — macOS, Linux, a Raspberry Pi, inside Home Assistant, wherever. No vendor software or Windows box needed for day-to-day control.
+
+> Extracted and generalized from a working Nexia PM sub-controller. The fiddly parts — telnet IAC stripping, reply framing, and the instance-ID drift problem — are already solved here.
+
+## Install
+
+```bash
+# from GitHub (works today):
+pip install git+https://github.com/biamp-ntp/biamp-ntp
+
+# or from a local checkout:
+pip install -e .
+```
+
+> The short form `pip install biamp-ntp` will work once it's published to PyPI.
+
+## CLI
+
+```bash
+# read the device number (needed as <dev> in every command; usually 1)
+biamp-ntp --host 192.168.1.199 devid
+
+# discover instance IDs — the #1 thing you need (see "Instance IDs" below)
+biamp-ntp --host 192.168.1.199 scan OUTLVLPM          # sweep output-level blocks
+biamp-ntp --host 192.168.1.199 scan MMLVLOUT          # sweep matrix outputs
+
+# read / write an attribute:  <attr> <instance> <idx...> [value]
+biamp-ntp --host 192.168.1.199 get OUTLVLPM 8 5        # output block inst 8, ch 5
+biamp-ntp --host 192.168.1.199 set OUTLVLPM 8 5 -6.0   # set ch 5 to -6 dB
+biamp-ntp --host 192.168.1.199 set OUTMUTEPM 8 5 1     # mute ch 5
+
+# escape hatch: send any raw command line
+biamp-ntp --host 192.168.1.199 raw GET 0 DEVID
+```
+
+## Library
+
+```python
+from biamp_ntp import BiampNTP, scan, protocol as p
+
+with BiampNTP("192.168.1.199") as dsp:
+    print(dsp.device_id())                       # -> 1
+
+    # find the output block's instance ID (don't hardcode it)
+    for inst, val in scan(dsp, p.OUTPUT_LEVEL_PM):
+        print("output block at instance", inst)
+
+    level = dsp.get_float(p.OUTPUT_LEVEL_PM, 8, 5)   # ch 5 level, dB
+    dsp.set(p.OUTPUT_LEVEL_PM, 8, 5, -6.0)           # set ch 5 to -6 dB
+    dsp.set(p.OUTPUT_MUTE_PM, 8, 5, True)            # mute (bool -> 1)
+```
+
+`command()` is thread-safe and reconnects automatically if the socket drops.
+
+## Instance IDs — read this
+
+Every block in a Biamp design has an **instance ID**, used in every GET/SET. The catch: **instance IDs are assigned at compile time and renumber whenever the design is recompiled and re-pushed** from the Windows software. So the numbers in your `.nex` file go stale, and hardcoding them will silently break after an edit.
+
+Always discover them live:
+
+```bash
+biamp-ntp --host <ip> scan <ATTR>
+```
+
+Only a real block of that type answers; everything else returns `-ERR:XACTION ERROR`. Use `--range 1-400` for large designs.
+
+## Common attributes
+
+| Block | Level | Mute | Other | Index |
+|---|---|---|---|---|
+| PM input | `INPLVLPML` | `INPMUTEPML` | `INPGAINPML` | input |
+| PM output | `OUTLVLPM` | `OUTMUTEPM` | `OUTINVRTPM` (polarity) | output ch |
+| Generic output | `OUTLVL` | `OUTMUTE` | | output ch |
+| Matrix mixer | `MMLVLOUT` / `MMLVLIN` | `MMMUTEOUT` | `MMLVLXP` (crosspoint) | out / in |
+| Level (fader) | `FDRLVL` | `FDRMUTE` | | channel |
+| Device | | | `DEVID` (GET 0 DEVID) | — |
+
+Levels are dB; mute/invert are `0`/`1`. Crosspoints (`MMLVLXP`/`MMMUTEXP`) take two indices: input row, output column. Any attribute string works with `get`/`set` — the table is just the common ones. See `biamp_ntp/protocol.py`.
+
+## Protocol notes (the gotchas)
+
+- **Grammar:** `GET <dev> <ATTR> <inst> <idx...>` → value; `SET <dev> <ATTR> <inst> <idx...> <value>` → `+OK`. Errors: `-ERR:SYNTAX`, `-ERR:XACTION ERROR`.
+- **Telnet IAC:** the server sends IAC negotiation bytes on connect and can interleave them with replies — this library strips them.
+- **Reply timing:** replies dribble out just after the command echo; a single immediate `recv()` catches a partial frame. The client settles briefly then drains fully (tunable via `settle=`).
+- **One client at a time:** the telnet server is happiest single-threaded; `command()` serializes on a lock.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+The unit tests need no hardware (they cover parsing / IAC / formatting).
+
+## License
+
+MIT.

biamp_ntp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "biamp-ntp"
+version = "0.1.0"
+description = "Dependency-free Python client + CLI for the Biamp Nexia/Audia Text Protocol (telnet control)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Matt" }]
+requires-python = ">=3.8"
+keywords = ["biamp", "nexia", "audia", "dsp", "telnet", "audio", "home-automation", "av"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Home Automation",
+    "Intended Audience :: Developers",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/biamp-ntp/biamp-ntp"
+Issues = "https://github.com/biamp-ntp/biamp-ntp/issues"
+
+[project.scripts]
+biamp-ntp = "biamp_ntp.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

biamp_ntp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

biamp_ntp-0.1.0/src/biamp_ntp/__init__.py

@@ -0,0 +1,7 @@
+"""biamp-ntp: a dependency-free client + CLI for the Biamp Nexia/Audia Text Protocol."""
+from . import protocol
+from .client import BiampError, BiampNTP
+from .scan import scan
+
+__all__ = ["BiampNTP", "BiampError", "scan", "protocol"]
+__version__ = "0.1.0"

biamp_ntp-0.1.0/src/biamp_ntp/cli.py

@@ -0,0 +1,94 @@
+"""Command-line interface: ``biamp-ntp``.
+
+Examples::
+
+    biamp-ntp --host 192.168.1.199 devid
+    biamp-ntp --host 192.168.1.199 scan OUTLVLPM
+    biamp-ntp --host 192.168.1.199 get OUTLVLPM 8 5
+    biamp-ntp --host 192.168.1.199 set OUTLVLPM 8 5 -6.0
+    biamp-ntp --host 192.168.1.199 raw GET 0 DEVID
+"""
+import argparse
+import sys
+
+from .client import BiampNTP, BiampError
+from .scan import scan
+
+__all__ = ["main", "build_parser"]
+
+
+def _parse_range(s):
+    lo, _, hi = s.partition("-")
+    return int(lo), int(hi or lo)
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="biamp-ntp",
+        description="Control a Biamp Nexia/Audia DSP over the Text Protocol "
+                    "(telnet, port 23, no auth).")
+    p.add_argument("--host", required=True, help="DSP IP address or hostname")
+    p.add_argument("--device", type=int, default=1,
+                   help="device number (default 1; read it with the 'devid' command)")
+    p.add_argument("--port", type=int, default=23)
+    p.add_argument("--timeout", type=float, default=3.0)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("devid", help="read the device number (GET 0 DEVID)")
+
+    sp = sub.add_parser("scan", help="find instance IDs that answer an attribute")
+    sp.add_argument("attr", help="attribute code, e.g. OUTLVLPM or MMLVLOUT")
+    sp.add_argument("idx", nargs="*", type=int, help="index/channel to probe (default 1)")
+    sp.add_argument("--range", default="1-200", help="instance range, e.g. 1-300")
+
+    sp = sub.add_parser("get", help="GET an attribute")
+    sp.add_argument("attr")
+    sp.add_argument("inst", type=int)
+    sp.add_argument("idx", nargs="*", type=int)
+
+    sp = sub.add_parser("set", help="SET an attribute (last arg is the value)")
+    sp.add_argument("attr")
+    sp.add_argument("inst", type=int)
+    sp.add_argument("args", nargs="+", metavar="idx...-value")
+
+    sp = sub.add_parser("raw", help="send a raw command line and print the reply")
+    sp.add_argument("line", nargs=argparse.REMAINDER)
+
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    dsp = BiampNTP(args.host, device=args.device, port=args.port, timeout=args.timeout)
+    try:
+        with dsp:
+            if args.cmd == "devid":
+                print(dsp.device_id())
+            elif args.cmd == "scan":
+                lo, hi = _parse_range(args.range)
+                idx = args.idx or [1]
+                n = 0
+                for inst, val in scan(dsp, args.attr, *idx, rng=range(lo, hi + 1)):
+                    print("instance %d -> %s" % (inst, val))
+                    n += 1
+                sys.stdout.flush()
+                print("(%d instance(s) answered %s)" % (n, args.attr), file=sys.stderr)
+            elif args.cmd == "get":
+                print(dsp.get(args.attr, args.inst, *args.idx))
+            elif args.cmd == "set":
+                idx, value = args.args[:-1], args.args[-1]
+                dsp.set(args.attr, args.inst, *[int(i) for i in idx], value)
+                print("+OK")
+            elif args.cmd == "raw":
+                print(dsp.command(" ".join(args.line)))
+    except BiampError as e:
+        print("error: %s" % e, file=sys.stderr)
+        return 2
+    except OSError as e:
+        print("connection error: %s" % e, file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

biamp_ntp-0.1.0/src/biamp_ntp/client.py

@@ -0,0 +1,200 @@
+"""A small, dependency-free client for the Biamp Nexia / Audia Text Protocol.
+
+The Nexia (CS/PM/SP/VC/TC) and Audia (FLOW, ...) families expose a line-based
+control protocol over TCP port 23 (telnet, no authentication). This module
+speaks it with nothing but the Python standard library.
+"""
+import socket
+import threading
+import time
+
+__all__ = ["BiampNTP", "BiampError"]
+
+
+class BiampError(Exception):
+    """A command returned a protocol error (-ERR:...) or an unparseable reply."""
+
+
+def _strip_iac(b):
+    """Remove telnet IAC negotiation triples (0xFF cmd opt) from a raw buffer.
+
+    The Nexia/Audia telnet server emits IAC negotiation on connect and can
+    interleave it with replies; left in, it corrupts parsing.
+    """
+    out = bytearray()
+    i, n = 0, len(b)
+    while i < n:
+        if b[i] == 0xFF:
+            i += 3            # skip IAC + command byte + option byte
+            continue
+        out.append(b[i])
+        i += 1
+    return bytes(out)
+
+
+def _fmt(v):
+    """Format a Python value for the wire (bool -> 0/1, tidy floats)."""
+    if isinstance(v, bool):
+        return "1" if v else "0"
+    if isinstance(v, float):
+        s = ("%.4f" % v).rstrip("0").rstrip(".")
+        return s or "0"
+    return str(v)
+
+
+class BiampNTP:
+    """Telnet client for one Biamp DSP.
+
+    Typical use::
+
+        from biamp_ntp import BiampNTP, protocol as p
+
+        with BiampNTP("192.168.1.199") as dsp:
+            print(dsp.device_id())                      # device number
+            db = dsp.get_float(p.OUTPUT_LEVEL_PM, 8, 5) # output block inst 8, ch 5
+            dsp.set(p.OUTPUT_LEVEL_PM, 8, 5, -6.0)      # set ch 5 to -6 dB
+
+    Command grammar::
+
+        GET <dev> <ATTR> <inst> <idx...>           -> value
+        SET <dev> <ATTR> <inst> <idx...> <value>   -> +OK
+        errors: -ERR:SYNTAX | -ERR:XACTION ERROR
+
+    Instance IDs are assigned at compile time and RENUMBER whenever the design
+    is recompiled and re-pushed, so numbers taken from a .nex file go stale.
+    Discover them live with :func:`biamp_ntp.scan.scan`.
+
+    ``command()`` is thread-safe (serialized on an internal lock); the telnet
+    server is happiest with one client at a time.
+    """
+
+    def __init__(self, host, device=1, port=23, timeout=3.0, settle=0.25):
+        self.host = host
+        self.device = device
+        self.port = port
+        self.timeout = timeout
+        self.settle = settle
+        self._sock = None
+        self._lock = threading.Lock()
+
+    # -- connection ------------------------------------------------------
+
+    def connect(self):
+        """Open the telnet session (idempotent). Returns self."""
+        if self._sock is None:
+            self._sock = socket.create_connection(
+                (self.host, self.port), timeout=self.timeout)
+            self._drain()     # swallow banner + IAC negotiation
+        return self
+
+    def close(self):
+        """Close the session if open."""
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            finally:
+                self._sock = None
+
+    def __enter__(self):
+        return self.connect()
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # -- framing ---------------------------------------------------------
+
+    def _drain(self):
+        """Read the whole reply frame: settle briefly, then mop up non-blocking.
+
+        The device dribbles its reply just after echoing the command, so a
+        single immediate recv() catches a partial frame (and splits IAC
+        triples). A short settle plus a brief non-blocking drain gets it whole.
+        """
+        time.sleep(self.settle)
+        chunks = bytearray()
+        self._sock.settimeout(0.15)
+        while True:
+            try:
+                b = self._sock.recv(4096)
+                if not b:
+                    break
+                chunks += b
+            except socket.timeout:
+                break
+        return bytes(chunks)
+
+    def _reply(self, raw):
+        """Extract the reply string: strip IAC, take the last non-empty line."""
+        lines = [l for l in _strip_iac(raw).replace(b"\r", b"").split(b"\n")
+                 if l.strip()]
+        return lines[-1].decode("latin-1", "replace").strip() if lines else ""
+
+    # -- I/O -------------------------------------------------------------
+
+    def command(self, text, retry=True):
+        """Send one command line; return its reply string. Thread-safe.
+
+        Reconnects and retries once if the socket has dropped (including a
+        silent drop that yields an empty reply).
+        """
+        with self._lock:
+            last = ""
+            for attempt in (1, 2):
+                try:
+                    self.connect()
+                    self._sock.settimeout(self.timeout)
+                    self._sock.sendall((text + "\n").encode())
+                    last = self._reply(self._drain())
+                    if last or not retry:
+                        return last
+                    self.close()          # empty reply -> likely dropped; retry
+                except OSError:
+                    self.close()
+                    if attempt == 2 or not retry:
+                        raise
+            return last
+
+    # -- typed helpers ---------------------------------------------------
+
+    def query(self, attr, inst, *idx):
+        """Raw GET: returns the reply string (a value, or -ERR:... on failure)."""
+        parts = ["GET", str(self.device), attr, str(inst)]
+        parts += [str(i) for i in idx]
+        return self.command(" ".join(parts))
+
+    def get(self, attr, inst, *idx):
+        """GET, raising BiampError on error/empty; returns the string value."""
+        r = self.query(attr, inst, *idx)
+        if not r or r.startswith("-ERR"):
+            raise BiampError("GET %s %s %s -> %r" % (attr, inst, list(idx), r))
+        return r
+
+    def get_float(self, attr, inst, *idx):
+        return float(self.get(attr, inst, *idx))
+
+    def get_bool(self, attr, inst, *idx):
+        return self.get(attr, inst, *idx).strip() == "1"
+
+    def set(self, attr, inst, *idx_and_value):
+        """SET: the last positional is the value, the rest are indices.
+
+        Returns True on +OK, else raises BiampError. Booleans map to 0/1.
+        """
+        if not idx_and_value:
+            raise TypeError("set() needs at least a value")
+        idx = idx_and_value[:-1]
+        value = idx_and_value[-1]
+        parts = ["SET", str(self.device), attr, str(inst)]
+        parts += [str(i) for i in idx] + [_fmt(value)]
+        r = self.command(" ".join(parts))
+        if r != "+OK":
+            raise BiampError("SET %s %s %s %s -> %r"
+                             % (attr, inst, list(idx), value, r))
+        return True
+
+    def device_id(self):
+        """Read the device number (GET 0 DEVID)."""
+        r = self.command("GET 0 DEVID")
+        if not r or r.startswith("-ERR"):
+            raise BiampError("GET 0 DEVID -> %r" % r)
+        return int(r)

biamp_ntp-0.1.0/src/biamp_ntp/protocol.py

@@ -0,0 +1,39 @@
+"""Biamp NTP attribute codes, grouped by block type.
+
+These are the attribute names used in GET/SET commands. Which set applies
+depends on the blocks in your running design; discover their instance IDs with
+:func:`biamp_ntp.scan.scan`. This is a convenience map of the common ones, not
+an exhaustive list -- any attribute string works with ``BiampNTP.get``/``set``.
+
+Levels are in dB unless noted; mute/invert are 0/1; index is the channel /
+crosspoint selector for that block.
+"""
+
+# --- Nexia PM input block ---------------------------------------------------
+INPUT_LEVEL_PM = "INPLVLPML"     # idx = input
+INPUT_MUTE_PM = "INPMUTEPML"     # idx = input
+INPUT_GAIN_PM = "INPGAINPML"     # idx = input (analog input gain)
+
+# --- Nexia PM output block --------------------------------------------------
+OUTPUT_LEVEL_PM = "OUTLVLPM"     # idx = output channel, -100..+12 dB
+OUTPUT_MUTE_PM = "OUTMUTEPM"     # idx = output channel, 0/1
+OUTPUT_INVERT_PM = "OUTINVRTPM"  # idx = output channel, 0/1 (polarity)
+OUTPUT_FS_PM = "OUTFSPM"         # idx = output channel (full-scale / range)
+
+# --- Generic (non-PM) output block ------------------------------------------
+OUTPUT_LEVEL = "OUTLVL"          # idx = output channel
+OUTPUT_MUTE = "OUTMUTE"          # idx = output channel
+
+# --- Standard matrix mixer --------------------------------------------------
+MATRIX_IN_LEVEL = "MMLVLIN"      # idx = input
+MATRIX_OUT_LEVEL = "MMLVLOUT"    # idx = output, -100..+12 dB
+MATRIX_OUT_MUTE = "MMMUTEOUT"    # idx = output, 0/1
+MATRIX_XP_LEVEL = "MMLVLXP"      # idx1 = input row, idx2 = output col, -100..0 dB
+MATRIX_XP_MUTE = "MMMUTEXP"      # idx1 = input row, idx2 = output col, 0/1
+
+# --- Standard level (fader) block -------------------------------------------
+FADER_LEVEL = "FDRLVL"           # idx = channel
+FADER_MUTE = "FDRMUTE"           # idx = channel
+
+# --- Device -----------------------------------------------------------------
+DEVICE_ID = "DEVID"              # GET 0 DEVID -> device number

biamp_ntp-0.1.0/src/biamp_ntp/scan.py

@@ -0,0 +1,29 @@
+"""Instance-ID discovery for a running Biamp design.
+
+Instance IDs change on every recompile+push, so numbers taken from a .nex file
+go stale. Sweep a GET across candidate instance IDs; only a real block of the
+matching type answers with a value instead of an -ERR:XACTION ERROR.
+"""
+
+__all__ = ["scan"]
+
+
+def scan(client, attr, *idx, rng=range(1, 200)):
+    """Yield ``(instance_id, value)`` for each instance that answers ``attr``.
+
+    ``idx`` defaults to ``(1,)`` (the first channel). Example::
+
+        from biamp_ntp import BiampNTP, scan, protocol as p
+        with BiampNTP("192.168.1.199") as dsp:
+            for inst, val in scan(dsp, p.OUTPUT_LEVEL_PM):
+                print(inst, val)
+
+    Widen ``rng`` if nothing turns up -- large designs can push instance IDs
+    well past the default upper bound.
+    """
+    if not idx:
+        idx = (1,)
+    for inst in rng:
+        r = client.query(attr, inst, *idx)
+        if r and not r.startswith("-ERR"):
+            yield inst, r

biamp_ntp-0.1.0/src/biamp_ntp.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: biamp-ntp
+Version: 0.1.0
+Summary: Dependency-free Python client + CLI for the Biamp Nexia/Audia Text Protocol (telnet control)
+Author: Matt
+License: MIT
+Project-URL: Homepage, https://github.com/biamp-ntp/biamp-ntp
+Project-URL: Issues, https://github.com/biamp-ntp/biamp-ntp/issues
+Keywords: biamp,nexia,audia,dsp,telnet,audio,home-automation,av
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Home Automation
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# biamp-ntp
+
+A tiny, **dependency-free** Python client and CLI for the **Biamp Nexia / Audia Text Protocol** — the line-based control protocol those DSPs expose over telnet (TCP port 23, no authentication).
+
+Works with the Nexia family (CS / PM / SP / VC / TC) and Audia (FLOW, …). Pure standard library, so it runs anywhere Python does — macOS, Linux, a Raspberry Pi, inside Home Assistant, wherever. No vendor software or Windows box needed for day-to-day control.
+
+> Extracted and generalized from a working Nexia PM sub-controller. The fiddly parts — telnet IAC stripping, reply framing, and the instance-ID drift problem — are already solved here.
+
+## Install
+
+```bash
+# from GitHub (works today):
+pip install git+https://github.com/biamp-ntp/biamp-ntp
+
+# or from a local checkout:
+pip install -e .
+```
+
+> The short form `pip install biamp-ntp` will work once it's published to PyPI.
+
+## CLI
+
+```bash
+# read the device number (needed as <dev> in every command; usually 1)
+biamp-ntp --host 192.168.1.199 devid
+
+# discover instance IDs — the #1 thing you need (see "Instance IDs" below)
+biamp-ntp --host 192.168.1.199 scan OUTLVLPM          # sweep output-level blocks
+biamp-ntp --host 192.168.1.199 scan MMLVLOUT          # sweep matrix outputs
+
+# read / write an attribute:  <attr> <instance> <idx...> [value]
+biamp-ntp --host 192.168.1.199 get OUTLVLPM 8 5        # output block inst 8, ch 5
+biamp-ntp --host 192.168.1.199 set OUTLVLPM 8 5 -6.0   # set ch 5 to -6 dB
+biamp-ntp --host 192.168.1.199 set OUTMUTEPM 8 5 1     # mute ch 5
+
+# escape hatch: send any raw command line
+biamp-ntp --host 192.168.1.199 raw GET 0 DEVID
+```
+
+## Library
+
+```python
+from biamp_ntp import BiampNTP, scan, protocol as p
+
+with BiampNTP("192.168.1.199") as dsp:
+    print(dsp.device_id())                       # -> 1
+
+    # find the output block's instance ID (don't hardcode it)
+    for inst, val in scan(dsp, p.OUTPUT_LEVEL_PM):
+        print("output block at instance", inst)
+
+    level = dsp.get_float(p.OUTPUT_LEVEL_PM, 8, 5)   # ch 5 level, dB
+    dsp.set(p.OUTPUT_LEVEL_PM, 8, 5, -6.0)           # set ch 5 to -6 dB
+    dsp.set(p.OUTPUT_MUTE_PM, 8, 5, True)            # mute (bool -> 1)
+```
+
+`command()` is thread-safe and reconnects automatically if the socket drops.
+
+## Instance IDs — read this
+
+Every block in a Biamp design has an **instance ID**, used in every GET/SET. The catch: **instance IDs are assigned at compile time and renumber whenever the design is recompiled and re-pushed** from the Windows software. So the numbers in your `.nex` file go stale, and hardcoding them will silently break after an edit.
+
+Always discover them live:
+
+```bash
+biamp-ntp --host <ip> scan <ATTR>
+```
+
+Only a real block of that type answers; everything else returns `-ERR:XACTION ERROR`. Use `--range 1-400` for large designs.
+
+## Common attributes
+
+| Block | Level | Mute | Other | Index |
+|---|---|---|---|---|
+| PM input | `INPLVLPML` | `INPMUTEPML` | `INPGAINPML` | input |
+| PM output | `OUTLVLPM` | `OUTMUTEPM` | `OUTINVRTPM` (polarity) | output ch |
+| Generic output | `OUTLVL` | `OUTMUTE` | | output ch |
+| Matrix mixer | `MMLVLOUT` / `MMLVLIN` | `MMMUTEOUT` | `MMLVLXP` (crosspoint) | out / in |
+| Level (fader) | `FDRLVL` | `FDRMUTE` | | channel |
+| Device | | | `DEVID` (GET 0 DEVID) | — |
+
+Levels are dB; mute/invert are `0`/`1`. Crosspoints (`MMLVLXP`/`MMMUTEXP`) take two indices: input row, output column. Any attribute string works with `get`/`set` — the table is just the common ones. See `biamp_ntp/protocol.py`.
+
+## Protocol notes (the gotchas)
+
+- **Grammar:** `GET <dev> <ATTR> <inst> <idx...>` → value; `SET <dev> <ATTR> <inst> <idx...> <value>` → `+OK`. Errors: `-ERR:SYNTAX`, `-ERR:XACTION ERROR`.
+- **Telnet IAC:** the server sends IAC negotiation bytes on connect and can interleave them with replies — this library strips them.
+- **Reply timing:** replies dribble out just after the command echo; a single immediate `recv()` catches a partial frame. The client settles briefly then drains fully (tunable via `settle=`).
+- **One client at a time:** the telnet server is happiest single-threaded; `command()` serializes on a lock.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+The unit tests need no hardware (they cover parsing / IAC / formatting).
+
+## License
+
+MIT.

biamp_ntp-0.1.0/src/biamp_ntp.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/biamp_ntp/__init__.py
+src/biamp_ntp/cli.py
+src/biamp_ntp/client.py
+src/biamp_ntp/protocol.py
+src/biamp_ntp/scan.py
+src/biamp_ntp.egg-info/PKG-INFO
+src/biamp_ntp.egg-info/SOURCES.txt
+src/biamp_ntp.egg-info/dependency_links.txt
+src/biamp_ntp.egg-info/entry_points.txt
+src/biamp_ntp.egg-info/top_level.txt
+tests/test_protocol.py

biamp_ntp-0.1.0/src/biamp_ntp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

biamp_ntp-0.1.0/src/biamp_ntp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+biamp-ntp = biamp_ntp.cli:main

biamp_ntp-0.1.0/src/biamp_ntp.egg-info/top_level.txt

@@ -0,0 +1 @@
+biamp_ntp

biamp_ntp-0.1.0/tests/test_protocol.py

@@ -0,0 +1,54 @@
+"""Unit tests that need no hardware -- parsing, IAC stripping, wire formatting."""
+import unittest
+
+from biamp_ntp.client import BiampNTP, _fmt, _strip_iac
+
+
+class StripIAC(unittest.TestCase):
+    def test_single_triple(self):
+        # IAC WILL ECHO (0xFF 0xFB 0x01) prefixing "+OK"
+        self.assertEqual(_strip_iac(b"\xff\xfb\x01+OK\r\n"), b"+OK\r\n")
+
+    def test_multiple_triples(self):
+        self.assertEqual(_strip_iac(b"\xff\xfd\x03\xff\xfb\x01-3.00\r\n"), b"-3.00\r\n")
+
+    def test_no_iac(self):
+        self.assertEqual(_strip_iac(b"-3.00\r\n"), b"-3.00\r\n")
+
+
+class Fmt(unittest.TestCase):
+    def test_bool(self):
+        self.assertEqual(_fmt(True), "1")
+        self.assertEqual(_fmt(False), "0")
+
+    def test_float(self):
+        self.assertEqual(_fmt(1.0), "1")
+        self.assertEqual(_fmt(-3.5), "-3.5")
+        self.assertEqual(_fmt(0.0), "0")
+        self.assertEqual(_fmt(-6.25), "-6.25")
+
+    def test_int_and_str(self):
+        self.assertEqual(_fmt(5), "5")
+        self.assertEqual(_fmt("on"), "on")
+
+
+class Reply(unittest.TestCase):
+    def setUp(self):
+        self.c = BiampNTP("test.invalid")  # no connection is opened
+
+    def test_strips_iac_and_takes_last_line(self):
+        self.assertEqual(self.c._reply(b"\xff\xfb\x01-3.00\r\n"), "-3.00")
+
+    def test_echo_then_value(self):
+        raw = b"GET 1 OUTLVLPM 8 5\r\n-3.00\r\n"
+        self.assertEqual(self.c._reply(raw), "-3.00")
+
+    def test_ok(self):
+        self.assertEqual(self.c._reply(b"SET 1 OUTLVLPM 8 5 -3.00\r\n+OK\r\n"), "+OK")
+
+    def test_empty(self):
+        self.assertEqual(self.c._reply(b"\xff\xfb\x01"), "")
+
+
+if __name__ == "__main__":
+    unittest.main()