pyavcontrol 0.1.3

Python Control of Audio/Visual Equipment (RS232/IP)

Python Control of A/V Equipment (RS232 / IP)

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.

Background

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:

1. 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.
2. 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.

Support

Visit the community support discussion thread for issues with this library.

Supported Equipment

See SUPPORTED.md for the complete list of supported equipment.

Background

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.

Using pyavcontrol

Asynchronous & Synchronous APIs

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)

Connection URL

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

Future Ideas

• 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.

See Also

• 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