pynadtcp 1.0.0__tar.gz

pynadtcp-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+# Publishes to PyPI whenever main has a version in pyproject.toml that isn't on PyPI yet.
+# To release: bump the version in pyproject.toml and pynadtcp/__init__.py, then merge to main.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      publish: ${{ steps.pypi.outputs.publish }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Read version
+        id: version
+        run: |
+          version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          module=$(python -c 'import re; print(re.search(r"__version__ = \"(.+)\"", open("pynadtcp/__init__.py").read())[1])')
+          if [ "$version" != "$module" ]; then
+            echo "::error::pyproject.toml has $version but pynadtcp/__init__.py has $module"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Check PyPI
+        id: pypi
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/pynadtcp/${{ steps.version.outputs.version }}/json")
+          if [ "$status" = "404" ]; then
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          elif [ "$status" = "200" ]; then
+            echo "Version ${{ steps.version.outputs.version }} is already on PyPI, nothing to release."
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "::error::Unexpected response $status from PyPI"
+            exit 1
+          fi
+
+  test:
+    needs: check
+    if: needs.check.outputs.publish == 'true'
+    uses: ./.github/workflows/test.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pynadtcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: [check, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Tag and create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          gh release create "v$VERSION" dist/* \
+            --repo "$GITHUB_REPOSITORY" \
+            --target "$GITHUB_SHA" \
+            --title "v$VERSION" \
+            --generate-notes

pynadtcp-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest

pynadtcp-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

pynadtcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niels Bik
+
+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.

pynadtcp-1.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: pynadtcp
+Version: 1.0.0
+Summary: Async client library for NAD amplifiers controllable over TCP (e.g. the C338).
+Project-URL: Homepage, https://github.com/nielsrowinbik/pynadtcp
+Project-URL: Source, https://github.com/nielsrowinbik/pynadtcp
+Project-URL: Issues, https://github.com/nielsrowinbik/pynadtcp/issues
+Author: Niels Bik
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amplifier,asyncio,c338,home-assistant,nad
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pynadtcp
+
+Async Python client for NAD amplifiers that expose a TCP/IP control protocol on
+port 30001 — most notably the **NAD C338**. It is a modern, typed rewrite of the
+abandoned [`nadtcp`](https://gitlab.com/mindig.marton/nadtcp) library and is
+designed to back the Home Assistant `nad_tcp` integration, but has no Home
+Assistant dependency and can be used standalone.
+
+## Install
+
+```bash
+pip install pynadtcp
+```
+
+## Usage
+
+```python
+import asyncio
+from pynadtcp import NadClient
+
+
+async def main() -> None:
+    async with NadClient("192.168.1.50") as client:
+        print(client.state.model, client.state.version)
+
+        await client.power_on()
+        await client.set_volume(-40)        # dB, clamped to [-80, 0]
+        await client.select_source("Stream")
+
+        def on_update(c: NadClient) -> None:
+            print("state:", c.state)
+
+        unsubscribe = client.register_state_update_callback(on_update)
+        await asyncio.sleep(30)
+        unsubscribe()
+
+
+asyncio.run(main())
+```
+
+## API
+
+- `NadClient(host, *, port=30001, connect_timeout=5.0, reconnect_interval=15.0)`
+- `await client.connect()` / `await client.disconnect()` (or use as an async context manager)
+- `client.is_connected()` → `bool`
+- `client.state` → `NadState(power, volume_db, muted, source, model, version)`
+- `client.sources` → list of selectable input source names
+- `await client.power_on()` / `power_off()`
+- `await client.set_volume(db)` / `volume_up()` / `volume_down()`
+- `await client.set_mute(bool)`
+- `await client.select_source(name)`
+- `client.register_state_update_callback(cb)` → unsubscribe callable
+
+After a successful `connect()`, the client keeps the connection alive and
+transparently reconnects if it drops. Callbacks fire on every state change and
+whenever the connection is established or lost.
+
+## Supported devices
+
+Developed and tested against the **NAD C338**. Other NAD models that speak the
+same port-30001 text protocol (potentially the C368 / C388 / M10) are likely to
+work, but are currently untested — reports welcome.
+
+## License
+
+MIT

pynadtcp-1.0.0/README.md

@@ -0,0 +1,66 @@
+# pynadtcp
+
+Async Python client for NAD amplifiers that expose a TCP/IP control protocol on
+port 30001 — most notably the **NAD C338**. It is a modern, typed rewrite of the
+abandoned [`nadtcp`](https://gitlab.com/mindig.marton/nadtcp) library and is
+designed to back the Home Assistant `nad_tcp` integration, but has no Home
+Assistant dependency and can be used standalone.
+
+## Install
+
+```bash
+pip install pynadtcp
+```
+
+## Usage
+
+```python
+import asyncio
+from pynadtcp import NadClient
+
+
+async def main() -> None:
+    async with NadClient("192.168.1.50") as client:
+        print(client.state.model, client.state.version)
+
+        await client.power_on()
+        await client.set_volume(-40)        # dB, clamped to [-80, 0]
+        await client.select_source("Stream")
+
+        def on_update(c: NadClient) -> None:
+            print("state:", c.state)
+
+        unsubscribe = client.register_state_update_callback(on_update)
+        await asyncio.sleep(30)
+        unsubscribe()
+
+
+asyncio.run(main())
+```
+
+## API
+
+- `NadClient(host, *, port=30001, connect_timeout=5.0, reconnect_interval=15.0)`
+- `await client.connect()` / `await client.disconnect()` (or use as an async context manager)
+- `client.is_connected()` → `bool`
+- `client.state` → `NadState(power, volume_db, muted, source, model, version)`
+- `client.sources` → list of selectable input source names
+- `await client.power_on()` / `power_off()`
+- `await client.set_volume(db)` / `volume_up()` / `volume_down()`
+- `await client.set_mute(bool)`
+- `await client.select_source(name)`
+- `client.register_state_update_callback(cb)` → unsubscribe callable
+
+After a successful `connect()`, the client keeps the connection alive and
+transparently reconnects if it drops. Callbacks fire on every state change and
+whenever the connection is established or lost.
+
+## Supported devices
+
+Developed and tested against the **NAD C338**. Other NAD models that speak the
+same port-30001 text protocol (potentially the C368 / C388 / M10) are likely to
+work, but are currently untested — reports welcome.
+
+## License
+
+MIT

pynadtcp-1.0.0/RELEASING.md

@@ -0,0 +1,10 @@
+# Releasing
+
+Releases are automatic. To publish a new version:
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `pynadtcp/__init__.py` to the same value.
+2. Merge to `main`.
+
+The Release workflow sees that this version isn't on PyPI yet, runs the tests, builds the package, publishes it to PyPI through Trusted Publishing, and creates a `v<version>` tag and GitHub Release. Pushes that don't change the version publish nothing.
+
+The PyPI trusted publisher is configured for workflow `release.yml` and environment `pypi`. Renaming either breaks publishing until the PyPI settings are updated to match.

pynadtcp-1.0.0/pynadtcp/__init__.py

@@ -0,0 +1,21 @@
+"""Async client library for NAD amplifiers controllable over TCP (e.g. C338)."""
+
+from __future__ import annotations
+
+from .client import NadClient
+from .const import DEFAULT_PORT, VOLUME_MAX_DB, VOLUME_MIN_DB
+from .exceptions import NadConnectionError, NadException, NadTimeoutError
+from .models import NadState
+
+__all__ = [
+    "DEFAULT_PORT",
+    "VOLUME_MAX_DB",
+    "VOLUME_MIN_DB",
+    "NadClient",
+    "NadConnectionError",
+    "NadException",
+    "NadState",
+    "NadTimeoutError",
+]
+
+__version__ = "1.0.0"

pynadtcp-1.0.0/pynadtcp/client.py

@@ -0,0 +1,278 @@
+"""Asyncio client for NAD amplifiers controllable over TCP (e.g. the C338)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+import inspect
+import logging
+from types import TracebackType
+from typing import Any
+
+from .const import (
+    CMD_MAIN,
+    CMD_MODEL,
+    CMD_MUTE,
+    CMD_POWER,
+    CMD_SOURCE,
+    CMD_VERSION,
+    CMD_VOLUME,
+    C338_CMDS,
+    CMD_MIN_INTERVAL,
+    DEFAULT_PORT,
+    VOLUME_MAX_DB,
+    VOLUME_MIN_DB,
+)
+from .exceptions import NadConnectionError, NadException, NadTimeoutError
+from .models import NadState
+from .protocol import NadProtocol, make_command
+
+_LOGGER = logging.getLogger(__name__)
+
+StateCallback = Callable[["NadClient"], Awaitable[None] | None]
+
+
+class NadClient:
+    """Manage a persistent control connection to a NAD amplifier."""
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        port: int = DEFAULT_PORT,
+        connect_timeout: float = 5.0,
+        reconnect_interval: float = 15.0,
+    ) -> None:
+        """Initialize the client. No connection is opened until ``connect``."""
+        self._host = host
+        self._port = port
+        self._connect_timeout = connect_timeout
+        self._reconnect_interval = reconnect_interval
+
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._transport: asyncio.Transport | None = None
+        self._raw: dict[str, Any] = {}
+        self._state = NadState()
+        self._callbacks: set[StateCallback] = set()
+
+        self._closing = False
+        self._auto_reconnect = False
+        self._ready = asyncio.Event()
+        self._reconnect_task: asyncio.Task[None] | None = None
+        self._cmd_lock = asyncio.Lock()
+        self._last_cmd = 0.0
+
+    @property
+    def host(self) -> str:
+        """Return the configured host."""
+        return self._host
+
+    @property
+    def state(self) -> NadState:
+        """Return the latest known device state."""
+        return self._state
+
+    @property
+    def sources(self) -> list[str]:
+        """Return the list of selectable input sources."""
+        return list(C338_CMDS[CMD_SOURCE]["values"])
+
+    def is_connected(self) -> bool:
+        """Return whether a live connection to the device exists."""
+        return self._transport is not None and not self._closing
+
+    async def connect(self) -> None:
+        """Open the connection and wait until the device identifies itself.
+
+        Raises:
+            NadConnectionError: if the socket cannot be opened.
+            NadTimeoutError: if the device does not respond in time.
+        """
+        self._closing = False
+        self._loop = asyncio.get_running_loop()
+        await self._open()
+        self._auto_reconnect = True
+
+    async def disconnect(self) -> None:
+        """Close the connection and stop reconnecting."""
+        self._closing = True
+        self._auto_reconnect = False
+        if self._reconnect_task is not None:
+            self._reconnect_task.cancel()
+            self._reconnect_task = None
+        if self._transport is not None:
+            self._transport.close()
+            self._transport = None
+
+    async def __aenter__(self) -> NadClient:
+        """Connect on entering an async context."""
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Disconnect on leaving an async context."""
+        await self.disconnect()
+
+    def register_state_update_callback(
+        self, callback: StateCallback
+    ) -> Callable[[], None]:
+        """Register a callback invoked on every state or connection change.
+
+        Returns a function that unregisters the callback.
+        """
+        self._callbacks.add(callback)
+
+        def _unsubscribe() -> None:
+            self._callbacks.discard(callback)
+
+        return _unsubscribe
+
+    def unregister_state_update_callback(self, callback: StateCallback) -> None:
+        """Unregister a previously registered callback."""
+        self._callbacks.discard(callback)
+
+    async def power_on(self) -> None:
+        """Turn the amplifier on."""
+        await self._send(make_command(CMD_POWER, "=", True))
+
+    async def power_off(self) -> None:
+        """Turn the amplifier off."""
+        await self._send(make_command(CMD_POWER, "=", False))
+
+    async def set_mute(self, mute: bool) -> None:
+        """Mute or unmute the amplifier."""
+        await self._send(make_command(CMD_MUTE, "=", mute))
+
+    async def set_volume(self, volume_db: float) -> None:
+        """Set the volume in dB, clamped to the device's supported range."""
+        clamped = round(max(VOLUME_MIN_DB, min(VOLUME_MAX_DB, volume_db)))
+        await self._send(make_command(CMD_VOLUME, "=", clamped))
+
+    async def volume_up(self) -> None:
+        """Increase the volume by one device step."""
+        await self._send(make_command(CMD_VOLUME, "+"))
+
+    async def volume_down(self) -> None:
+        """Decrease the volume by one device step."""
+        await self._send(make_command(CMD_VOLUME, "-"))
+
+    async def select_source(self, source: str) -> None:
+        """Select an input source."""
+        await self._send(make_command(CMD_SOURCE, "=", source))
+
+    async def _open(self) -> None:
+        """Open a single connection and wait for the device to identify."""
+        assert self._loop is not None
+        self._ready.clear()
+
+        def _factory() -> NadProtocol:
+            return NadProtocol(self._handle_lines, self._handle_connection_lost)
+
+        try:
+            transport, _ = await asyncio.wait_for(
+                self._loop.create_connection(_factory, self._host, self._port),
+                timeout=self._connect_timeout,
+            )
+        except TimeoutError as err:
+            raise NadTimeoutError(
+                f"Timed out connecting to {self._host}:{self._port}"
+            ) from err
+        except OSError as err:
+            raise NadConnectionError(
+                f"Could not connect to {self._host}:{self._port}: {err}"
+            ) from err
+
+        self._transport = transport
+        await self._send(make_command(CMD_MAIN, "?"))
+        try:
+            async with asyncio.timeout(self._connect_timeout):
+                await self._ready.wait()
+        except TimeoutError as err:
+            transport.close()
+            raise NadTimeoutError(
+                f"No response from NAD device at {self._host}:{self._port}"
+            ) from err
+
+    async def _reconnect(self) -> None:
+        """Retry opening the connection until it succeeds or we close."""
+        while not self._closing:
+            await asyncio.sleep(self._reconnect_interval)
+            if self._closing:
+                return
+            try:
+                await self._open()
+            except NadException as err:
+                _LOGGER.debug("Reconnect to %s failed: %s", self._host, err)
+                continue
+            _LOGGER.debug("Reconnected to %s", self._host)
+            return
+
+    def _handle_lines(self, lines: list[tuple[str, Any]]) -> None:
+        """Apply a batch of parsed response lines to the local state."""
+        for key, value in lines:
+            self._raw[key] = value
+            # A volume change implicitly clears mute on the device.
+            if key == CMD_VOLUME and self._raw.get(CMD_MUTE) is True:
+                self._raw[CMD_MUTE] = False
+        self._rebuild_state()
+        if CMD_MODEL in self._raw:
+            self._ready.set()
+        self._schedule_notify()
+
+    def _handle_connection_lost(self, exc: Exception | None) -> None:
+        """React to the transport closing, reconnecting if appropriate."""
+        self._transport = None
+        self._raw.clear()
+        self._rebuild_state()
+        self._ready.clear()
+        self._schedule_notify()
+        if (
+            self._auto_reconnect
+            and not self._closing
+            and self._loop is not None
+            and (self._reconnect_task is None or self._reconnect_task.done())
+        ):
+            _LOGGER.debug("Connection to %s lost (%s); reconnecting", self._host, exc)
+            self._reconnect_task = self._loop.create_task(self._reconnect())
+
+    def _rebuild_state(self) -> None:
+        """Recompute the public ``NadState`` from raw device values."""
+        version = self._raw.get(CMD_VERSION)
+        self._state = NadState(
+            power=self._raw.get(CMD_POWER),
+            volume_db=self._raw.get(CMD_VOLUME),
+            muted=self._raw.get(CMD_MUTE),
+            source=self._raw.get(CMD_SOURCE),
+            model=self._raw.get(CMD_MODEL),
+            version=None if version is None else str(version),
+        )
+
+    def _schedule_notify(self) -> None:
+        """Schedule callback notification on the event loop."""
+        if self._loop is not None:
+            self._loop.create_task(self._notify())
+
+    async def _notify(self) -> None:
+        """Invoke every registered callback, awaiting async ones."""
+        for callback in list(self._callbacks):
+            result = callback(self)
+            if inspect.isawaitable(result):
+                await result
+
+    async def _send(self, command: str) -> None:
+        """Write a command to the device, throttled to the minimum interval."""
+        transport = self._transport
+        if transport is None:
+            raise NadConnectionError("Not connected to the device")
+        assert self._loop is not None
+        async with self._cmd_lock:
+            wait = (self._last_cmd + CMD_MIN_INTERVAL) - self._loop.time()
+            if wait > 0:
+                await asyncio.sleep(wait)
+            transport.write(command.encode("utf-8"))
+            self._last_cmd = self._loop.time()

pynadtcp-1.0.0/pynadtcp/const.py

@@ -0,0 +1,102 @@
+"""Constants and the command table for the NAD TCP protocol."""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: TCP port the NAD amplifier listens on for the control protocol.
+DEFAULT_PORT = 30001
+
+#: Minimum interval (seconds) between commands sent to the device.
+CMD_MIN_INTERVAL = 0.15
+
+#: Line terminator used by the protocol.
+EOL = "\r\n"
+
+# Command keys used by the protocol.
+CMD_MAIN = "Main"
+CMD_BRIGHTNESS = "Main.Brightness"
+CMD_BASS_EQ = "Main.Bass"
+CMD_CONTROL_STANDBY = "Main.ControlStandby"
+CMD_AUTO_STANDBY = "Main.AutoStandby"
+CMD_VERSION = "Main.Version"
+CMD_MODEL = "Main.Model"
+CMD_MUTE = "Main.Mute"
+CMD_POWER = "Main.Power"
+CMD_AUTO_SENSE = "Main.AutoSense"
+CMD_SOURCE = "Main.Source"
+CMD_VOLUME = "Main.Volume"
+
+MSG_ON = "On"
+MSG_OFF = "Off"
+
+#: Description of every command the C338 supports: which operators are valid,
+#: the accepted values, and the Python type each value maps to. This table
+#: drives both command formatting and response parsing.
+C338_CMDS: dict[str, dict[str, Any]] = {
+    "Main": {"supported_operators": ["?"]},
+    "Main.AnalogGain": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "type": int,
+    },
+    "Main.Brightness": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": range(0, 4),
+        "type": int,
+    },
+    "Main.Mute": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.Power": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.Volume": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": range(-80, 1),
+        "type": float,
+    },
+    "Main.Bass": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.ControlStandby": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.AutoStandby": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.AutoSense": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [MSG_OFF, MSG_ON],
+        "type": bool,
+    },
+    "Main.Source": {
+        "supported_operators": ["+", "-", "=", "?"],
+        "values": [
+            "Stream",
+            "Wireless",
+            "TV",
+            "Phono",
+            "Coax1",
+            "Coax2",
+            "Opt1",
+            "Opt2",
+        ],
+    },
+    "Main.Version": {"supported_operators": ["?"]},
+    "Main.Model": {"supported_operators": ["?"]},
+}
+
+#: Lowest volume the device accepts, in dB.
+VOLUME_MIN_DB = -80.0
+#: Highest volume the device accepts, in dB.
+VOLUME_MAX_DB = 0.0

pynadtcp-1.0.0/pynadtcp/exceptions.py

@@ -0,0 +1,15 @@
+"""Exceptions raised by pynadtcp."""
+
+from __future__ import annotations
+
+
+class NadException(Exception):
+    """Base class for all pynadtcp errors."""
+
+
+class NadConnectionError(NadException):
+    """Raised when the connection to the device fails or is lost."""
+
+
+class NadTimeoutError(NadException):
+    """Raised when the device does not respond in time."""

pynadtcp-1.0.0/pynadtcp/models.py

@@ -0,0 +1,20 @@
+"""Data models for pynadtcp."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class NadState:
+    """Snapshot of the amplifier's state.
+
+    Every field is ``None`` until the device has reported a value for it.
+    """
+
+    power: bool | None = None
+    volume_db: float | None = None
+    muted: bool | None = None
+    source: str | None = None
+    model: str | None = None
+    version: str | None = None

pynadtcp-1.0.0/pynadtcp/protocol.py

@@ -0,0 +1,119 @@
+"""Low-level command grammar and asyncio transport for the NAD TCP protocol."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+import logging
+import socket
+from typing import Any
+
+from .const import C338_CMDS, EOL
+from .exceptions import NadException
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def make_command(key: str, operator: str, value: Any = None) -> str:
+    """Build a raw protocol command string such as ``Main.Volume=-40``.
+
+    Raises:
+        NadException: if the key/operator combination is invalid.
+    """
+    try:
+        cmd_desc = C338_CMDS[key]
+    except KeyError:
+        raise NadException(f"Unknown command: {key}") from None
+    if operator not in cmd_desc["supported_operators"]:
+        raise NadException(f"Operator {operator!r} is not valid for {key}")
+    if operator == "=" and value is None:
+        raise NadException(f"Operator '=' for {key} requires a value")
+    if operator in ("?", "+", "-") and value is not None:
+        raise NadException(f"Operator {operator!r} cannot take a value")
+    if value is None:
+        return f"{key}{operator}"
+    if cmd_desc.get("type") is bool:
+        value = cmd_desc["values"][int(bool(value))]
+    return f"{key}{operator}{value}"
+
+
+def parse_line(line: str) -> tuple[str, Any] | None:
+    """Parse a single ``key=value`` response line.
+
+    Returns ``None`` for lines without a value or keys we do not understand,
+    so unexpected output never crashes the parser.
+    """
+    key, sep, raw = line.partition("=")
+    if not sep:
+        return None
+    cmd_desc = C338_CMDS.get(key)
+    if cmd_desc is None:
+        return None
+    value_type = cmd_desc.get("type")
+    try:
+        if value_type is bool:
+            return key, bool(cmd_desc["values"].index(raw))
+        if value_type is not None:
+            return key, value_type(raw)
+    except (ValueError, KeyError):
+        return None
+    return key, raw
+
+
+class NadProtocol(asyncio.Protocol):
+    """asyncio protocol that frames the device's line-based output."""
+
+    def __init__(
+        self,
+        on_lines: Callable[[list[tuple[str, Any]]], None],
+        on_connection_lost: Callable[[Exception | None], None],
+    ) -> None:
+        """Initialize the protocol with line and disconnect callbacks."""
+        self._on_lines = on_lines
+        self._on_connection_lost = on_connection_lost
+        self._buffer = ""
+        self.transport: asyncio.Transport | None = None
+
+    def connection_made(self, transport: asyncio.BaseTransport) -> None:
+        """Store the transport and enable TCP keepalive (best effort)."""
+        assert isinstance(transport, asyncio.Transport)
+        self.transport = transport
+        sock: socket.socket | None = transport.get_extra_info("socket")
+        if sock is not None:
+            _enable_keepalive(sock)
+
+    def data_received(self, data: bytes) -> None:
+        """Split incoming bytes into complete lines and hand them off."""
+        self._buffer += data.decode("utf-8", "ignore").replace("\x00", "")
+        parsed: list[tuple[str, Any]] = []
+        while EOL in self._buffer:
+            line, self._buffer = self._buffer.split(EOL, 1)
+            if not line:
+                continue
+            result = parse_line(line)
+            if result is not None:
+                parsed.append(result)
+        if parsed:
+            self._on_lines(parsed)
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        """Notify the client that the transport was closed."""
+        self.transport = None
+        self._on_connection_lost(exc)
+
+
+def _enable_keepalive(sock: socket.socket) -> None:
+    """Turn on TCP keepalive, tuning the timers where the platform allows."""
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+    for name, value in (
+        ("TCP_KEEPIDLE", 60),
+        ("TCP_KEEPINTVL", 10),
+        ("TCP_KEEPCNT", 3),
+    ):
+        option = getattr(socket, name, None)
+        if option is None:
+            continue
+        try:
+            sock.setsockopt(socket.IPPROTO_TCP, option, value)
+        except OSError:  # noqa: PERF203 - best effort per option
+            _LOGGER.debug("Could not set socket option %s", name)

pynadtcp-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pynadtcp"
+version = "1.0.0"
+description = "Async client library for NAD amplifiers controllable over TCP (e.g. the C338)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Niels Bik" }]
+keywords = ["nad", "amplifier", "c338", "home-assistant", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/nielsrowinbik/pynadtcp"
+Source = "https://github.com/nielsrowinbik/pynadtcp"
+Issues = "https://github.com/nielsrowinbik/pynadtcp/issues"
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["pynadtcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

pynadtcp-1.0.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for pynadtcp."""

pynadtcp-1.0.0/tests/test_client.py

@@ -0,0 +1,240 @@
+"""Tests for the pynadtcp client and protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+
+import pytest
+
+from pynadtcp import NadClient, NadConnectionError, NadTimeoutError
+from pynadtcp.exceptions import NadException
+from pynadtcp.protocol import make_command, parse_line
+
+STATE_DUMP = (
+    "Main.Model=NADC338\r\n"
+    "Main.Version=1.53\r\n"
+    "Main.Power=On\r\n"
+    "Main.Volume=-40\r\n"
+    "Main.Mute=Off\r\n"
+    "Main.Source=Stream\r\n"
+)
+
+
+class FakeNad:
+    """A minimal fake NAD device speaking the port-30001 protocol."""
+
+    def __init__(self) -> None:
+        """Initialize the fake device."""
+        self.received: list[str] = []
+        self._server: asyncio.AbstractServer | None = None
+        self._writers: list[asyncio.StreamWriter] = []
+        self.port = 0
+
+    async def start(self) -> None:
+        """Start listening on an ephemeral local port."""
+        self._server = await asyncio.start_server(self._handle, "127.0.0.1", 0)
+        self.port = self._server.sockets[0].getsockname()[1]
+
+    async def _handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        self._writers.append(writer)
+        while not reader.at_eof():
+            data = await reader.read(1024)
+            if not data:
+                break
+            text = data.decode()
+            self.received.append(text)
+            if "Main?" in text:
+                writer.write(STATE_DUMP.encode())
+                await writer.drain()
+        writer.close()
+
+    async def push(self, text: str) -> None:
+        """Send unsolicited output to every connected client."""
+        for writer in self._writers:
+            writer.write(text.encode())
+            await writer.drain()
+
+    async def stop(self) -> None:
+        """Stop the server if it is still running."""
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+
+@pytest.fixture
+async def fake_nad() -> FakeNad:
+    """Provide a running fake NAD device."""
+    device = FakeNad()
+    await device.start()
+    yield device
+    await device.stop()
+
+
+async def test_connect_populates_state(fake_nad: FakeNad) -> None:
+    """Connecting queries the device and fills in the state."""
+    client = NadClient("127.0.0.1", port=fake_nad.port)
+    await client.connect()
+
+    assert client.is_connected()
+    assert client.state.model == "NADC338"
+    assert client.state.version == "1.53"
+    assert client.state.power is True
+    assert client.state.volume_db == -40.0
+    assert client.state.muted is False
+    assert client.state.source == "Stream"
+    assert client.sources[0] == "Stream"
+
+    await client.disconnect()
+    assert not client.is_connected()
+
+
+async def test_context_manager(fake_nad: FakeNad) -> None:
+    """The client works as an async context manager."""
+    async with NadClient("127.0.0.1", port=fake_nad.port) as client:
+        assert client.is_connected()
+    assert not client.is_connected()
+
+
+async def test_callbacks_fire(fake_nad: FakeNad) -> None:
+    """Registered callbacks receive state updates."""
+    client = NadClient("127.0.0.1", port=fake_nad.port)
+    powers: list[bool | None] = []
+
+    async def _cb(c: NadClient) -> None:
+        powers.append(c.state.power)
+
+    unsubscribe = client.register_state_update_callback(_cb)
+    await client.connect()
+    await asyncio.sleep(0.05)
+
+    assert True in powers
+    unsubscribe()
+    await client.disconnect()
+
+
+async def test_unparseable_lines_keep_connection(fake_nad: FakeNad) -> None:
+    """Bad lines are skipped; later valid lines still apply on the same connection."""
+    client = NadClient("127.0.0.1", port=fake_nad.port)
+    await client.connect()
+
+    await fake_nad.push("garbage\r\nMain.Unknown=1\r\nMain.Volume=-20\r\n")
+    await asyncio.sleep(0.05)
+
+    assert client.state.volume_db == -20.0
+    assert client.is_connected()
+    await client.disconnect()
+
+
+@pytest.mark.parametrize(
+    ("requested", "expected"),
+    [(-30, "Main.Volume=-30"), (-200, "Main.Volume=-80"), (10, "Main.Volume=0")],
+)
+async def test_set_volume_clamped(
+    fake_nad: FakeNad, requested: float, expected: str
+) -> None:
+    """Volume is clamped to the device range before sending."""
+    client = NadClient("127.0.0.1", port=fake_nad.port)
+    await client.connect()
+    fake_nad.received.clear()
+
+    await client.set_volume(requested)
+    await asyncio.sleep(0.05)
+
+    assert expected in "".join(fake_nad.received)
+    await client.disconnect()
+
+
+async def test_power_and_source_commands(fake_nad: FakeNad) -> None:
+    """Power and source commands are encoded correctly on the wire."""
+    client = NadClient("127.0.0.1", port=fake_nad.port)
+    await client.connect()
+    fake_nad.received.clear()
+
+    await client.power_on()
+    await client.select_source("Phono")
+    await client.set_mute(True)
+    await asyncio.sleep(0.05)
+
+    sent = "".join(fake_nad.received)
+    assert "Main.Power=On" in sent
+    assert "Main.Source=Phono" in sent
+    assert "Main.Mute=On" in sent
+    await client.disconnect()
+
+
+async def test_connect_refused() -> None:
+    """Connecting to a closed port raises NadConnectionError."""
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+
+    client = NadClient("127.0.0.1", port=port, connect_timeout=1)
+    with pytest.raises((NadConnectionError, NadTimeoutError)):
+        await client.connect()
+    assert not client.is_connected()
+
+
+async def test_no_response_times_out() -> None:
+    """A device that accepts but never answers raises NadTimeoutError."""
+
+    async def _silent(
+        reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        await reader.read(1024)
+        await asyncio.sleep(5)
+        # Without this, wait_closed() below hangs on Python 3.12.
+        writer.close()
+
+    server = await asyncio.start_server(_silent, "127.0.0.1", 0)
+    port = server.sockets[0].getsockname()[1]
+
+    client = NadClient("127.0.0.1", port=port, connect_timeout=0.3)
+    with pytest.raises(NadTimeoutError):
+        await client.connect()
+
+    server.close()
+    await server.wait_closed()
+
+
+def test_make_command() -> None:
+    """Commands are formatted per the protocol grammar."""
+    assert make_command("Main", "?") == "Main?"
+    assert make_command("Main.Power", "=", True) == "Main.Power=On"
+    assert make_command("Main.Power", "=", False) == "Main.Power=Off"
+    assert make_command("Main.Volume", "=", -40) == "Main.Volume=-40"
+    assert make_command("Main.Volume", "+") == "Main.Volume+"
+
+
+def test_make_command_invalid() -> None:
+    """Invalid keys and operator/value combinations raise."""
+    with pytest.raises(NadException):
+        make_command("Unknown.Key", "?")
+    with pytest.raises(NadException):
+        make_command("Main.Power", "!")
+    with pytest.raises(NadException):
+        make_command("Main.Volume", "?", -40)
+    with pytest.raises(NadException):
+        make_command("Main.Power", "=")
+
+
+@pytest.mark.parametrize(
+    ("line", "expected"),
+    [
+        ("Main.Power=On", ("Main.Power", True)),
+        ("Main.Power=Off", ("Main.Power", False)),
+        ("Main.Volume=-40", ("Main.Volume", -40.0)),
+        ("Main.Source=Stream", ("Main.Source", "Stream")),
+        ("Main.Model=NADC338", ("Main.Model", "NADC338")),
+        ("Unknown.Key=1", None),
+        ("garbage", None),
+        ("Main.Mute=Weird", None),
+    ],
+)
+def test_parse_line(line: str, expected: tuple[str, object] | None) -> None:
+    """Response lines parse to typed values, bad input to None."""
+    assert parse_line(line) == expected