This is a Python library to control and interact with Onkyo receivers over the network. It is also a ready-made command line script you can use without knowing how to program.
Finally, this repository contains a YAML file containing all the commands defined by the Onkyo protocol, automatically generated by parsing the official documentation. Even if you are not using Python, you may find this file useful when implementing your own interface. See further down below for more information.
Most recent released version:
$ easy_install onkyo-eiscp
Latest development version:
$ easy_install onkyo-eiscp==dev
The package installs a script called onkyo, that can be used from the
command line:
$ onkyo system-power=off
This will turn your receiver off. You may notice that you haven't given any information as to where in the network your receiver is. The script should in fact be able to find your Onkyo device by itself.
To see which receivers the script is able to find, you can use:
$ onkyo --discover
If you have multiple receivers on your network, then by default, it will simply connect to the first device found (which may be a different one every time).
You can select a specific one by filtering by name:
$ onkyo --discover TX-NR709 192.168.178.200:60128 TX-NR609 192.168.178.169:60128 $ onkyo -n 709 system-power=on
This will only turn on the TX-NR709 device.
There is also an --all flag, to send you commands to all devices at once.
Finally, you are of course able to manually specify the device to connect to:
$ onkyo --host 172.20.0.144 volume=55 $ onkyo --host 172.20.0.144 --port 42424 volume=55
To find out which commands are available, use the --help-commands option.
A command consists of three parts: The zone, the command, and the arguments. Here are some examples:
system-power=on zone2.power=on main.balance=3
As you can see, the basic format is:
zone.command=argument
If you do not specify a zone, then main is assumed.
There are some variations on this syntax that are possible, for example the following are all equivalent:
power on power:on main.power on main power on
In other words, instead of the . and = separators, whitespace may
be used, and the colon : is an alternative to =. However, it's best
to use the suggested syntax above.
The names of these commands are defined by this project, and are rewritten to actual low-level eISCP commands Onkyo uses. If you know them, you can also send such low-level commands directly:
$ onkyo SLI26 # Selects the "Tuner" source.
For the power on command to work while the device is in standby, make
sure you turn on the obtusely named
Setup -> Hardware -> Network -> Network Control option.
Without it, you can only connect to your receiver while it is already turned on.
In a simple case, this might look like this:
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()Don't forget to call disconnect() to close the socket. You can also use
a with statement:
with eiscp.eISCP('192.168.1.125') as receiver:
receiver.command('source all-ch-stereo')The command language is explained above. You can also be more explict with the structure:
receiver.command('power', 'on', zone='main')
If you prefer to send low-level ISCP commands directly, you can use the :meth:`raw` method:
receiver.raw('MVLUP')
The function :func:`command_to_iscp` will allow you to convert a high-level command to a low-level ISCP message for use with :meth:`eISCP.raw`.
The Onkyo receiver will send messages to you as well. Specifically, it returns a response to every command you send, either by repeating the command you have sent back to you, or, in case you sent a query message, reporting the answer to you query. It will also send unsolicited status updates to you whenver the state of the receiver changes.
API-wise, the :meth:`eISCP.raw` and :meth:`eISCP.command` return the response received from the Onkyo device. They are blocking.
To receive other messages, there is :meth:`eISCP.get`, which will
either return a message or None. You may specify a custom timeout
value.
Warning
At least for now, there is no queue. If you call :meth:`eISCP.raw` or :meth:`eISCP.command`, any messages not picked up via :meth:`eISCP.get` are lost.
A problem with the Onkyo protocol is that there is no fool-proof way to
differentiate a response from unsolicited status updates. Generally, this
won't be an issue, though in theory the response that is given to you
after sending SLI05 may be a SLI06 update from another controller.
It is thus preferable to approach the protocol in a different way. Instead of using :meth:`eISCP.raw` or :meth:`eISCP.command`, which try to serialize the exchange into a request-response scheme, you may also use :meth:`eISCP.send`, which dispatches a message without waiting for a response. You would then use :meth:`get` to process all incoming messages in the same way, regardless of why they were sent. This works well, since a response to either a command or a query is no different than a status update.
There is also an experimental :class:`eiscp.Receiver`, which has the same api as :class:`eiscp.eISCP`, but uses a background thread for network communication. This allows you to handle incoming messages via a callback:
def message_received(message):
print message
receiver = Receiver('...')
receiver.on_message = message_received
Note that the on_message handler is executed on the background
thread, so you may want to use a queue.
For consistancy, :meth:`eISCP.raw` and :meth:`eISCP.command` are still designed to artificially block, while :meth:`eISCP.send` is non-blocking.
You can have it find the receivers on your local network:
for receiver in eiscp.eISCP.discover(timeout=5):
receiver.command('power off')This will turn off all the Onkyo receivers on your network.
A discovered device has an info attribute that gives you some data:
{'iscp_port': '60128', 'identifier': '0009B04448E0',
'area_code': 'XX', 'model_name': 'TX-NR709', 'device_category': '1'}- Some commands require a more complex argument structure, like variable-length strings, and those are not yet supported (you can send them in raw mode of course).
This repository contains a YAML file containing all the commands defined by the Onkyo protocol, automatically generated by parsing the official Excel documentation, and then further adjusted manually.
The idea is to have a computer-readable definition of the Onkyo protocol, where Onkyo's internal low-level commands are mapped to identifiers that can be understood by humans, and which include descriptions.
Parsing the Onkyo Excel document gets you astonishingly far, but there's a limit. The YAML file requires manual edits and fixes where the parser fails, including a lot of cosmetic corrections. Some of those have been made, but there's significant room for improving the YAML description of the protocol.
The process and the specific YAML formatting have been chosen to allow future changes to the Onkyo master document to be merged with the manual adjustments made as painlessly as possible.
To summarize, if you are implementing your own interface to Onkyo, even if it's in a language other than Python, I encourage you to consider using this YAML file as a basis for the command interface you provide to users. You'll have a complete list of available commands, values, and even supported devices.
- http://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xls
- Document from Onkyo describing the protocol, including a full list of supported commands.
- https://github.com/compbrain/Onkyo-TX-NR708-Control
- Repository on which this was originally based.
- https://github.com/beanz/device-onkyo-perl
- Perl implementation.
- http://code.google.com/p/onkyo-eiscp-remote-windows/
- C# implementation.
- https://github.com/janten/onkyo-eiscp-remote-mac
- Object-C implementation.
- https://sites.google.com/a/webarts.ca/toms-blog/Blog/new-blog-items/javaeiscp-integraserialcontrolprotocol
- Some Java code. Also deserves credit for providing the official Onkyo protocol documentation linked above.