Skip to main content

ADA RS-232

An asyncio library for the Audio Design Associates PTM-1645 PAC amplifier controller. The protocol implementation is independent of Home Assistant and uses serialx for local serial ports, ESPHome serial proxies, and network serial connections.

The PTM-1645 protocol and hardware connection were tested by the maintainer using an ESPHome RS-232 proxy. Version 0.1.0 is the dependency for the prepared Home Assistant Core change. Version 0.2.0 adds the remaining documented commands; those additions require hardware verification.

Usage

import asyncio

from ada_rs232 import AdaClient


async def main() -> None:
    client = AdaClient("/dev/serial/by-id/your-adapter", address=1)
    try:
        print(await client.async_get_state())
        print(await client.async_set_zone(1, True))
    finally:
        await client.async_close()


asyncio.run(main())

Addresses are 1–9; zone numbers are 1–8. The returned tuple contains eight booleans in zone order. Serial settings are fixed at 19200 baud, 8N1, with no flow control. Use the amplifier's default one-to-one trigger mapping.

subscribe(callback) registers a synchronous listener and returns an unsubscribe function. The listener receives the actual zone tuple, or None when the connection fails. A failed transaction raises AdaConnectionError; the next request reconnects. Single-zone updates read current state before writing. Explicit mask and broadcast actions write the mask the caller requested. Invalid arguments raise ValueError. Connection URLs are never included in library error messages.

All read/modify/write/readback operations share one lock. A set command can be silent, so it is followed by an explicit query. A voltage trigger or bypass can override data control; returned hardware state is authoritative. The protocol does not report the origin of a trigger and has no transaction IDs. External changes between read and write cannot be made atomic. Use one AdaBus per serial connection and an addressed AdaClient for each amplifier. Never create independent buses or standalone clients for the same port.

Shared bus and additional commands

from ada_rs232 import AdaBus, AdaClient

bus = AdaBus("/dev/serial/by-id/your-adapter")
first = AdaClient(bus.port, address=1, bus=bus)
ninth = AdaClient(bus.port, address=9, bus=bus)
try:
    print(await bus.async_get_states())  # GA; wait for staggered replies.
    print(await ninth.async_set_zones((True,) * 8))
    print(await bus.async_all_off())  # SA=00000000, then GA readback.
finally:
    await bus.async_close()

Bus transactions serialize across every addressed client. Closing a client view never closes a supplied bus. Its owner must close the bus after releasing all views and unsubscribing their listeners. Bus subscribers receive (address, state) callbacks; missing addresses in a successful GA cycle are invalidated. The GA collection window is at least 1.1 seconds because replies are staggered by address in 0.1 second increments. states returns a copy of the cache. A timeout closes the shared transport, invalidating its cached states.

Physical setup mode

Connect only one amplifier with no loop-throughs, hold its rear Setup button for more than five seconds, then release. await bus.async_read_setup() sends Enter and parses all eight trigger rows, the firmware version, current address, and Quick Turn On. Settings are returned as an immutable SetupState.

After a complete setup screen has been read, these methods change and verify settings: async_set_trigger_mapping(trigger, eight_booleans), async_set_quick_turn_on(enabled), async_set_address(address), and async_restore_trigger_defaults(). Q is a toggle: the library first reads the current setting, sends Q only if it differs, and verifies the result. No setup write is retried automatically after losing confirmation.

Power commands raise AdaSetupError while a confirmed setup session remains active. Press the physical Setup button once to exit, then call async_resume(address) to verify normal operation. The device also exits setup after 60 seconds without commands. A failed or partial setup response never permits a settings write. The host cannot verify disconnected loop-throughs; callers must enforce the single-amplifier prerequisite.

The screen parser follows the manufacturer's printed ASCII table. It has tests for fragmented screens and incomplete data, but needs comparison with a real terminal capture. Custom trigger mappings prevent independent zone control: feedback reports outputs, while mask writes operate configured triggers.

Development

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov=ada_rs232 --cov-report=term-missing
uv build

Source and wheel distributions are built from the release tag in GitHub Actions. Publishing uses PyPI Trusted Publishing, without a stored API token.

Metadata

Release files for ada-rs232 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ada-rs232 0.2.0
File Size Uploaded Provenance Actions
ada_rs232-0.2.0.tar.gz 52.5 kB With provenance Details for ada_rs232-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ada-rs232 0.2.0
File Interpreter ABI Platform Actions
ada_rs232-0.2.0-py3-none-any.whl Python 3 none any Details for ada_rs232-0.2.0-py3-none-any.whl

Total release size: 63.1 kB

Release files / ada_rs232-0.2.0.tar.gz

Download URL ada_rs232-0.2.0.tar.gz
Size 52.5 kB
Tags Source
SHA-256 checksum
How to use checksums
20df31365b9745dc1424acbcf82ad7ace67210e343968e89a09aeda458511e79
BLAKE2b-256 checksum
How to use checksums
8715319042d05646bf498e9cff1da063f0c95e6aa1837edc891c099fed72c93d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ada_rs232-0.2.0-py3-none-any.whl

Download URL ada_rs232-0.2.0-py3-none-any.whl
Size 10.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62150e9aa4dda4cdce824f59b83da0eb0086f91baa44850bd9aa8c7c33a77203
BLAKE2b-256 checksum
How to use checksums
593aaa658dfea0450159f0b5c9c4db1ae6d840bfe27104c159861b2e2e9cbef1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for ada-rs232 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ada_rs232-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page