通过以太网控制Onkyo接收器。
项目描述
这是一个用于通过网络控制和交互Onkyo接收器的Python库。它也是一个无需了解编程即可使用的现成命令行脚本。
最后，此存储库包含一个包含Onkyo协议定义的所有命令的YAML文件，该文件通过解析官方文档自动生成。即使您不使用Python，在实现自己的接口时，您也可能发现此文件很有用。更多信息请参见下面的说明。
安装
最新发布版本
$ easy_install onkyo-eiscp
使用方法
该包安装了一个名为 onkyo 的脚本，可以从命令行使用
$ onkyo system-power=off
这将关闭您的接收器。您可能会注意到，您没有提供任何有关接收器在网络中的位置的信息。实际上，该脚本应该能够自行找到您的Onkyo设备。
要查看脚本能够找到哪些接收器，您可以使用
$ onkyo --discover
如果您网络中有多个接收器，则默认情况下，它将简单地连接到找到的第一个设备（每次可能不同）。
您可以通过名称筛选来选择特定的一个
$ onkyo --discover TX-NR709 192.168.178.200:60128 0009B0D34163 TX-NR609 192.168.178.169:60128 0009B0D24B75 $ onkyo -n 709 system-power=on
这将仅打开TX-NR709设备。
或使用唯一标识符
$ onkyo -i 0009B0D24B75 system-power=on
这将打开TX-NR609设备。
此外，还有一个 --all 标志，可以一次向所有设备发送命令。
当然，您也可以手动指定要连接的设备。
$ onkyo --host 172.20.0.144 volume=55 $ onkyo --host 172.20.0.144 --port 42424 volume=55
要了解哪些命令可用，请使用 --help-commands 选项。
命令
一个命令由三个部分组成：区域、命令和参数。以下是一些示例
system-power=on zone2.power=on main.balance=3
如您所见，基本格式为
zone.command=argument
如果您没有指定区域，则默认为主区域。
该语法有一些变体，例如以下都是等价的
power on power:on main.power on main power on
换句话说，可以使用空格代替 . 和 = 分隔符，冒号 : 可以作为 = 的替代。然而，最好使用上述建议的语法。
这些命令的名称由本项目定义，并重写为Onkyo使用的实际低级eISCP命令。如果您知道它们，也可以直接发送此类低级命令。
$ onkyo SLI26 # Selects the "Tuner" source.
关于电源开启的说明
为了使设备处于待机状态时也能正常使用电源开启命令，请确保您已经开启了名为 Setup -> Hardware -> Network -> Network Control 的选项。
如果没有这个选项，您只能在设备已经开启的情况下连接到接收器。
Python模块
在简单情况下，这可能看起来像这样
import eiscp
# Create a receiver object, connecting to the host
receiver = eiscp.eISCP('192.168.1.125')
# Turn the receiver on, select PC input
receiver.command('power on')
receiver.command('source pc')
receiver.disconnect()不要忘记调用 disconnect() 来关闭套接字。您还可以使用 with 语句
with eiscp.eISCP('192.168.1.125') as receiver:
receiver.command('source all-ch-stereo')命令语言在上文已解释。您也可以更明确地使用结构
receiver.command('power', 'on', zone='main')
如果您更喜欢直接发送低级ISCP命令，可以使用 raw 方法
receiver.raw('MVLUP')
函数 command_to_iscp 将允许您将高级命令转换为低级ISCP消息，以便与 eISCP.raw 一起使用。
接收消息
Onkyo接收器也会向您发送消息。具体来说，它会针对您发送的每个命令返回响应，要么是将您发送的命令重复发送回您，要么是在您发送查询消息的情况下，向您报告查询的答案。当接收器状态改变时，它还会向您发送未经请求的状态更新。
从API的角度看，eISCP.raw 和 eISCP.command 返回从Onkyo设备接收到的响应。它们是阻塞的。
要接收其他消息，有 eISCP.get，它将返回一条消息或 None。您可以指定自定义的超时值。
Onkyo协议的一个问题是，没有万无一失的方法来区分响应和未经请求的状态更新。通常情况下，这不会成为问题，尽管在理论上，在发送 SLI05 后返回的响应可能是来自另一个控制器的 SLI06 更新。
因此，最好以不同的方式处理协议。与其使用尝试将交换序列化为请求-响应方案的 eISCP.raw 或 eISCP.command，不如使用不等待响应就发送消息的 eISCP.send。然后您可以使用 get 以相同的方式处理所有传入的消息，无论它们为什么被发送。这很有效，因为命令或查询的响应与状态更新没有区别。
异步API
还有一个实验性的 eiscp.Receiver，它具有与 eiscp.eISCP 相同的API，但使用后台线程进行网络通信。这允许您通过回调处理传入的消息。
def message_received(message):
print message
receiver = Receiver('...')
receiver.on_message = message_received
请注意，on_message 处理器在后台线程中执行，因此您可能需要使用队列。
为了保持一致性，eISCP.raw 和 eISCP.command 仍然被设计为人工阻塞，而 eISCP.send 是非阻塞的。
设备发现
它可以找到您本地网络上的接收器
for receiver in eiscp.eISCP.discover(timeout=5):
receiver.command('power off')这将关闭您网络上的所有Onkyo接收器。
发现设备有一个 info 属性，可以提供一些数据
{'iscp_port': '60128', 'identifier': '0009B04448E0',
'area_code': 'XX', 'model_name': 'TX-NR709', 'device_category': '1'}局限性
一些命令需要更复杂的参数结构，如可变长度的字符串，这些目前还不受支持（当然，您当然可以在原始模式下发送它们）。
YAML 文件
此存储库包含一个YAML文件，其中包含由Onkyo协议定义的所有命令，该文件通过解析官方Excel文档自动生成，然后进一步手动调整。
想法是拥有一个计算机可读的Onkyo协议定义，其中Onkyo的内部低级命令被映射为人类可理解的标识符，并包括描述。
解析Onkyo Excel文档可以使您取得惊人的进展，但也有局限性。YAML文件需要手动编辑和修正解析器失败的地方，包括大量的外观修正。其中一些已经完成，但仍有很大的空间来改进协议的YAML描述。
选择此过程和具体的YAML格式是为了允许将来将Onkyo主文档的更改与手动调整无缝合并。
总之，如果您正在实现自己的Onkyo接口，即使它不是用Python编写的，我也鼓励您考虑将此YAML文件作为您提供给用户的命令接口的基础。您将获得可用的命令、值甚至支持的设备的完整列表。
