Package: onkyo-eiscp
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.InstallationMost recent released version:$ easy_install onkyo-eiscpUsageThe package installs a script calledonkyo, that can be used from the
command line:$ onkyo system-power=offThis 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 --discoverIf 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 0009B0D34163
TX-NR609 192.168.178.169:60128 0009B0D24B75

$ onkyo -n 709 system-power=onThis will only turn on the TX-NR709 device.Or using the unique identifier:$ onkyo -i 0009B0D24B75 system-power=onThis will turn on the TX-NR609 device.There is also an--allflag, 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=55To find out which commands are available, use the--help-commandsoption.CommandsA command consists of three parts: The zone, the command, and the arguments.
Here are some examples:system-power=on
zone2.power=on
main.balance=3As you can see, the basic format is:zone.command=argumentIf you do not specify a zone, thenmainis 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 onIn 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.Notes on Power OnFor thepower oncommand to work while the device is in standby, make
sure you turn on the obtusely namedSetup->Hardware->Network->Network Controloption.Without it, you can only connect to your receiver while it is already
turned on.Python moduleIn a simple case, this might look like this:importeiscp# Create a receiver object, connecting to the hostreceiver=eiscp.eISCP('192.168.1.125')# Turn the receiver on, select PC inputreceiver.command('power on')receiver.command('source pc')receiver.disconnect()Don’t forget to calldisconnect()to close the socket. You can also use
awithstatement:witheiscp.eISCP('192.168.1.125')asreceiver: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 therawmethod:receiver.raw('MVLUP')The functioncommand_to_iscpwill allow you to convert a high-level
command to a low-level ISCP message for use witheISCP.raw.Receiving messagesThe 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, theeISCP.rawandeISCP.commandreturn the
response received from the Onkyo device. They are blocking.To receive other messages, there iseISCP.get, which will
either return a message orNone. You may specify a custom timeout
value.WarningAt least for now, there is no queue. If you calleISCP.raworeISCP.command, any messages not picked
up viaeISCP.getare 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 sendingSLI05may be aSLI06update from another controller.It is thus preferable to approach the protocol in a different way. Instead
of usingeISCP.raworeISCP.command, which try to serialize
the exchange into a request-response scheme, you may also useeISCP.send, which dispatches a message without waiting for a response.
You would then usegetto 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.Async APIThere is also an experimentaleiscp.Receiver, which has the
same api aseiscp.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_receivedNote that theon_messagehandler is executed on the background
thread, so you may want to use a queue.For consistancy,eISCP.rawandeISCP.commandare still
designed to artificially block, whileeISCP.sendis non-blocking.Device discoveryYou can have it find the receivers on your local network:forreceiverineiscp.eISCP.discover(timeout=5):receiver.command('power off')This will turn off all the Onkyo receivers on your network.A discovered device has aninfoattribute that gives you some data:{'iscp_port':'60128','identifier':'0009B04448E0','area_code':'XX','model_name':'TX-NR709','device_category':'1'}LimitationsSome 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).The YAML fileThis 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.Related LinksDocuments from Onkyo describing the protocol, including lists of supported commands:http://michael.elsdoerfer.name/onkyo/ISCP_AVR_134.xlsxhttp://michael.elsdoerfer.name/onkyo/ISCP_AVR_2014.Models.xlsxhttp://michael.elsdoerfer.name/onkyo/ISCP-V1.26_2013.xlsxhttp://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xlsThe repository on which this was originally based on:https://github.com/compbrain/Onkyo-TX-NR708-ControlAn implementation in Perl:https://github.com/beanz/device-onkyo-perlAn implementation in C#:http://code.google.com/p/onkyo-eiscp-remote-windows/An implementation in Object-C:https://github.com/janten/onkyo-eiscp-remote-macMQTT connectivity for onkyo-eiscp, adhering to the mqtt-smarthome specification:https://github.com/owagner/onkyo2mqttSome Java code that deserves credit for providing the original Onkyo protocol documentation linked above:https://sites.google.com/a/webarts.ca/toms-blog/Blog/new-blog-items/javaeiscp-integraserialcontrolprotocol