Library created to control a wide variety of A/V equipment which expose text-based control protocols over RS232, USB serial connections, and/or remote IP sockets.
This pyavcontrol library evolved from learnings during implementation a half dozen
custom client libraries for controlling specific equipment such as pyxantech and pyanthem-serial, which
were used to expose integrations for Home Assistant.
From those learnings, it was observed that the control protocols were often fairly similar and typically simple pattern matching could be used for converting the interfaces into more modern dictionary based APIs. This couples with dynamic Python class creation based on YAML protocol definition files for the protocols enables quickly spinning up new interfaces for specific devices even by anyone who has the ability to read technical documentation on the protocols (and not just those who are software developers).
Two additional goals:
- allow clients in other programming languages to share the same YAML protocol definitions to provide similar dynamic APIs that support a wide variety of devices quickly.
- Create a basic IP-based RS232 emulator which allows spinning up a basic emulator for each supported device model based purely on the YAML definition and unit tests against those definitions. This emulator can be used by client libraries in any language for testing. See avemu for more details.
One of the goals for creating this library is to reduce the amount of otherwise great equipment being thrown away (especially esoteric equipment that isn't well supported). Typically these can be modernized easily via wrapping their existing protocols with modern integrations.
Visit the community support discussion thread for issues with this library.
See SUPPORTED.md for the complete list of supported equipment.
One annoying thing when developing pyxantech was that none of the devices
ever had a protocol definition in a machine-readable format. Manufacturers
would provide a PDF or XLS document (if anything at all) that listed
the various commands that could be sent via RS232. However, there was no
consistency for what were generally very similar callable actions when
controlling preamps/receivers/etc.
During the development of pyxantech it became clear that other manufacturers
had copied the protocol developed by Xantech, with each
manufacturer just making a very small change in the prefixes or suffixes.
From this, a very primitive mechanism was built. YAML was chosen
to be a machine-readable format that was also easily read/updated by humans
who may have limited programming skills.
This makes it easier and quicker to add support for new devices without having to build an entirely new library each time (with varying semantics and degrees of testing/clarity/documentation). Additionally, these definitions make it possible to create similar libraries in a variety of languages, all sharing the same protocol definitions.
The evolution found in this pyavcontrol library takes these ideas further by
having a much more cohesive definition of protocols. Additional ideas were
discovered in onkyo-eiscp around
providing a simple CLI to use the library and grouping commands together
logically. These ideas combined with the argument definitions and pattern
matching from pyxantech moved these ideas closer to reality.
If you are trying to implement your own interface to McIntosh in other languages besides Python, you should consider using the YAML series and protocol files from this repository as a basis for the interface you provide. The protocol and series definitions will likely be split out into separate definition-only package(s) in the future.
See API documentation.
This library provides both an asyncio based and synchronous implementations.
By default, the synchronous implementation is returned when instantiating
new objects unless an event_loop is passed in when creating
DeviceModelLibrary or DeviceClient objects.
Async example:
loop = asyncio.get_event_loop()
library = DeviceModelLibrary.create(event_loop=loop)
model_definition = library.load_model('mcintosh_mx160')
client = DeviceClient.create(
model_definition,
url,
connection_config_overrides=config,
event_loop=loop
)
await client.power.on()
await client.volume.set(50)This interface uses URLs for specifying the communication transport to use, as defined in pyserial, to allow a wide variety of underlying communication mechanisms.
Example URL formats supported by pyserial:
| URL | Notes |
|---|---|
/dev/ttyUSB0 |
directly attached serial device (Linux) |
COM3 |
directly attached serial device (Windows) |
socket://<host>:<port> |
remote service exposing RS232 over TCP (natively or using something like Virtual IP2SL) |
socket://mx160.local:84 |
direct connection to MX160's port 84 interface |
- Add programmatic override/enhancements to the base protocol where pure YAML configuration would not work fully. Of course, these overrides would have to be implemented in each language, but that surface area should be much smaller.
- Move to a modern schema/config language for the library (Nickel, PKL, etc)
- Split out the library definitions from the library itself (eventually) so other language clients can share
- avemu - A/V Equipment Emulator (very useful for testing client libraries)
- Earlier McIntosh control in Home Assistant
- https://drivers.control4.com/solr/drivers/browse?q=mcintosh
- RS232 to USB cable