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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.