| Name | pyavcontrol JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | |
| Summary | Python Control of Audio/Visual Equipment (RS232/IP) |
| upload_time | 2024-02-25 07:52:22 |
| maintainer | |
| docs_url | None |
| author | Ryan Snodgrass |
| requires_python | >=3.10,<4.0 |
| license | LICENSE |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python Control of A/V Equipment (RS232 / IP)
[](https://pypi.python.org/pypi/pyavcontrol)
[](http://opensource.org/licenses/MIT)
[](https://github.com/rsnodgrass/pyavcontrol/actions/workflows/ci.yml)
[](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=WREP29UDAMB6G)
[](https://buymeacoffee.com/DYks67r)
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](https://github.com/rsnodgrass/pyxantech) and pyanthem-serial, which
were used to expose integrations for [Home Assistant](https://home-assistant.io).
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](https://community.home-assistant.io/t/mcintosh/) for issues with this library.
## Supported Equipment
See [SUPPORTED.md](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](https://github.com/miracle2k/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:
```python
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](https://pyserial.readthedocs.io/en/latest/url_handlers.html), 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](https://github.com/rsnodgrass/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](https://github.com/rsnodgrass/avemu) (very useful for testing client libraries)
- [Earlier McIntosh control in Home Assistant](https://community.home-assistant.io/t/need-help-using-rs232-to-control-a-receiver/95210/8)
- https://drivers.control4.com/solr/drivers/browse?q=mcintosh
- [RS232 to USB cable](https://www.amazon.com/RS232-to-USB/dp/B0759HSLP1?tag=carreramfi-20)
Raw data
{
"_id": null,
"home_page": "",
"name": "pyavcontrol",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Ryan Snodgrass",
"author_email": "rsnodgrass@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/30/c95d4d99057204877da35747ed887e16afa23c59c38245e3dda85c8d7297/pyavcontrol-0.1.3.tar.gz",
"platform": null,
"description": "# Python Control of A/V Equipment (RS232 / IP)\n\n\n[](https://pypi.python.org/pypi/pyavcontrol)\n[](http://opensource.org/licenses/MIT)\n[](https://github.com/rsnodgrass/pyavcontrol/actions/workflows/ci.yml)\n\n[](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=WREP29UDAMB6G)\n[](https://buymeacoffee.com/DYks67r)\n\nLibrary created to control a wide variety of A/V equipment which expose text-based control\nprotocols over RS232, USB serial connections, and/or remote IP sockets.\n\n### Background\n\nThis `pyavcontrol` library evolved from learnings during implementation a half dozen\ncustom client libraries for controlling specific equipment such as [pyxantech](https://github.com/rsnodgrass/pyxantech) and pyanthem-serial, which\nwere used to expose integrations for [Home Assistant](https://home-assistant.io).\n\nFrom those learnings, it was observed that the control protocols were often fairly similar and typically\nsimple pattern matching could be used for converting the interfaces into more modern dictionary based APIs.\nThis couples with dynamic Python class creation based on YAML protocol definition files for the protocols enables\nquickly spinning up new interfaces for specific devices even by anyone who has the ability to read technical\ndocumentation on the protocols (and not just those who are software developers).\n\nTwo additional goals:\n\n1. 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.\n2. Create a basic IP-based RS232 emulator which allows spinning up a basic emulator for each supported\ndevice 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.\n\n\n## Support\n\nVisit the [community support discussion thread](https://community.home-assistant.io/t/mcintosh/) for issues with this library.\n\n## Supported Equipment\n\nSee [SUPPORTED.md](SUPPORTED.md) for the complete list of supported equipment.\n\n## Background\n\nOne annoying thing when developing `pyxantech` was that none of the devices\never had a protocol definition in a machine-readable format. Manufacturers\nwould provide a PDF or XLS document (if anything at all) that listed\nthe various commands that could be sent via RS232. However, there was no\nconsistency for what were generally very similar callable actions when\ncontrolling preamps/receivers/etc.\n\nDuring the development of `pyxantech` it became clear that other manufacturers\nhad copied the protocol developed by Xantech, with each\nmanufacturer just making a very small change in the prefixes or suffixes.\nFrom this, a very primitive mechanism was built. YAML was chosen\nto be a machine-readable format that was also easily read/updated by humans\nwho may have limited programming skills.\n\nThis makes it easier and quicker to\nadd support for new devices without having to build an entirely new library each\ntime (with varying semantics and degrees of testing/clarity/documentation).\nAdditionally, these definitions make it possible to create similar libraries in\na variety of languages, all sharing the same protocol definitions.\n\nThe evolution found in this `pyavcontrol` library takes these ideas further by\nhaving a much more cohesive definition of protocols. Additional ideas were\ndiscovered in [onkyo-eiscp](https://github.com/miracle2k/onkyo-eiscp) around\nproviding a simple CLI to use the library and grouping commands together\nlogically. These ideas combined with the argument definitions and pattern\nmatching from `pyxantech` moved these ideas closer to reality.\n\nIf you are trying to implement your own interface to McIntosh in other\nlanguages besides Python, you should consider using the YAML series and\nprotocol files from this repository as a basis for the interface you provide.\nThe protocol and series definitions will likely be split out into separate\ndefinition-only package(s) in the future.\n\n## Using pyavcontrol\n\n### Asynchronous & Synchronous APIs\n\nThis library provides both an `asyncio` based and synchronous implementations.\nBy default, the synchronous implementation is returned when instantiating\nnew objects unless an `event_loop` is passed in when creating\nDeviceModelLibrary or DeviceClient objects.\n\nAsync example:\n\n```python\nloop = asyncio.get_event_loop()\n\nlibrary = DeviceModelLibrary.create(event_loop=loop)\nmodel_definition = library.load_model('mcintosh_mx160')\n\nclient = DeviceClient.create(\n model_definition,\n url,\n connection_config_overrides=config,\n event_loop=loop\n)\n\nawait client.power.on()\nawait client.volume.set(50)\n```\n\n### Connection URL\n\nThis interface uses URLs for specifying the communication transport\nto use, as defined in [pyserial](https://pyserial.readthedocs.io/en/latest/url_handlers.html), to allow a wide variety of underlying communication mechanisms.\n\nExample URL formats supported by pyserial:\n\n| URL | Notes |\n| ------------------------ | --------------------------------------------------------------------------------------------------- |\n| `/dev/ttyUSB0` | directly attached serial device (Linux) |\n| `COM3` | directly attached serial device (Windows) |\n| `socket://<host>:<port>` | remote service exposing RS232 over TCP (natively or using something like [Virtual IP2SL](https://github.com/rsnodgrass/virtual-ip2sl)) |\n| `socket://mx160.local:84` | direct connection to MX160's port 84 interface |\n\n## Future Ideas\n\n- Add programmatic override/enhancements to the base protocol where pure\n YAML configuration would not work fully. Of course, these overrides would have\n to be implemented in each language, but that surface area should be much smaller.\n\n## See Also\n\n- [avemu - A/V Equipment Emulator](https://github.com/rsnodgrass/avemu) (very useful for testing client libraries)\n- [Earlier McIntosh control in Home Assistant](https://community.home-assistant.io/t/need-help-using-rs232-to-control-a-receiver/95210/8)\n- https://drivers.control4.com/solr/drivers/browse?q=mcintosh\n- [RS232 to USB cable](https://www.amazon.com/RS232-to-USB/dp/B0759HSLP1?tag=carreramfi-20)\n\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Python Control of Audio/Visual Equipment (RS232/IP)",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7805cfb3e94c779159c060872905592e42de24df5d031d6251f7d0cbcd5d5646",
"md5": "35e29c3652bccdd19154db4cafbcd441",
"sha256": "ac3faf3931337df2127af274455e0ed0176541777d93935fddc21fd29c5f8a2b"
},
"downloads": -1,
"filename": "pyavcontrol-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35e29c3652bccdd19154db4cafbcd441",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 51702,
"upload_time": "2024-02-25T07:52:20",
"upload_time_iso_8601": "2024-02-25T07:52:20.566467Z",
"url": "https://files.pythonhosted.org/packages/78/05/cfb3e94c779159c060872905592e42de24df5d031d6251f7d0cbcd5d5646/pyavcontrol-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1230c95d4d99057204877da35747ed887e16afa23c59c38245e3dda85c8d7297",
"md5": "549eaae6b10df1b8de9760f713210e80",
"sha256": "38f5e16c0cf58e06659d19168d08925f41127dbc1dd438bc6dfbc158a3e33c81"
},
"downloads": -1,
"filename": "pyavcontrol-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "549eaae6b10df1b8de9760f713210e80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 37868,
"upload_time": "2024-02-25T07:52:22",
"upload_time_iso_8601": "2024-02-25T07:52:22.426903Z",
"url": "https://files.pythonhosted.org/packages/12/30/c95d4d99057204877da35747ed887e16afa23c59c38245e3dda85c8d7297/pyavcontrol-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-25 07:52:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyavcontrol"
}
