Onkyo Integra Serial Control Protocols

Latest version

Binding should be compatible with Onkyo AV receivers which support ISCP (Integra Serial Control Protocol) over Ethernet (eISCP) and Serial port (since version. Onkyo RZ Series is built for superior entertainment and seamless integration. DTS Play-Fi® is a wireless protocol that works with any audio app on mobiles and PC. Flick whatever’s playing to the receiver, even different sources to different components at the same time (requires a future firmware update). RS-232 Serial Input for.

Last released:

Control Onkyo receivers over ethernet.

Project description

This is a Python library to control and interact with Onkyo receiversover the network. It is also a ready-made command line script youcan use without knowing how to program.

Finally, this repository contains a YAML file containing all thecommands defined by the Onkyo protocol, automatically generated byparsing the official documentation. Even if you are not usingPython, you may find this file useful when implementing your owninterface. See further down below for more information.

Usage

The package installs a script called onkyo, that can be used from thecommand line:

This will turn your receiver off. You may notice that you haven’t given anyinformation as to where in the network your receiver is. The script shouldin fact be able to find your Onkyo device by itself.

To see which receivers the script is able to find, you can use:

If you have multiple receivers on your network, then by default, it willsimply connect to the first device found (which may be a different oneevery time).

You can select a specific one by filtering by name:

This will only turn on the TX-NR709 device.

Or using the unique identifier:

This will turn on the TX-NR609 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:

To find out which commands are available, use the --help-commands option.

Commands

A command consists of three parts: The zone, the command, and the arguments.Here are some examples:

As you can see, the basic format is:

If you do not specify a zone, then main is assumed.

There are some variations on this syntax that are possible, for example thefollowing are all equivalent:

In other words, instead of the . and = separators, whitespace maybe used, and the colon : is an alternative to =. However, it’s bestto use the suggested syntax above.

The names of these commands are defined by this project, and are rewrittento actual low-level eISCP commands Onkyo uses. If you know them, you canalso send such low-level commands directly:

Notes on Power On

For the power on command to work while the device is in standby, makesure you turn on the obtusely namedSetup -> Hardware -> Network -> Network Control option.

Without it, you can only connect to your receiver while it is alreadyturned on.

Python module

In a simple case, this might look like this:

Don’t forget to call disconnect() to close the socket. You can also usea with statement:

The command language is explained above. You can also be more explict withthe structure:

If you prefer to send low-level ISCP commands directly, you can use theraw method:

The function command_to_iscp will allow you to convert a high-levelcommand to a low-level ISCP message for use with eISCP.raw.

Receiving messages

The Onkyo receiver will send messages to you as well. Specifically, itreturns a response to every command you send, either by repeating thecommand you have sent back to you, or, in case you sent a querymessage, reporting the answer to you query. It will also send unsolicitedstatus updates to you whenver the state of the receiver changes.

API-wise, the eISCP.raw and eISCP.command return theresponse received from the Onkyo device. They are blocking.

To receive other messages, there is eISCP.get, which willeither return a message or None. You may specify a custom timeoutvalue.

Warning

At least for now, there is no queue. If you calleISCP.raw or eISCP.command, any messages not pickedup via eISCP.get are lost.

A problem with the Onkyo protocol is that there is no fool-proof way todifferentiate a response from unsolicited status updates. Generally, thiswon’t be an issue, though in theory the response that is given to youafter sending SLI05 may be a SLI06 update from another controller.

It is thus preferable to approach the protocol in a different way. Insteadof using eISCP.raw or eISCP.command, which try to serializethe exchange into a request-response scheme, you may also useeISCP.send, which dispatches a message without waiting for a response.You would then use get to process all incoming messages in the sameway, regardless of why they were sent. This works well, since a response toeither a command or a query is no different than a status update.

Async API

There is also an experimental eiscp.Receiver, which has thesame api as eiscp.eISCP, but uses a background thread fornetwork communication. This allows you to handle incoming messagesvia a callback:

Note that the on_messageConvert video to 3gp format online. handler is executed on the backgroundthread, so you may want to use a queue.

For consistancy, eISCP.raw and eISCP.command are stilldesigned to artificially block, while eISCP.send is non-blocking.

Device discovery

You can have it find the receivers on your local network:

This will turn off all the Onkyo receivers on your network.

A discovered device has an info attribute that gives you some data:

Limitations

Some commands require a more complex argument structure, likevariable-length strings, and those are not yet supported (you cansend them in raw mode of course).

The YAML file

This repository contains a YAML file containing all the commandsdefined by the Onkyo protocol, automatically generated byparsing the official Excel documentation, and then further adjustedmanually.

The idea is to have a computer-readable definition of the Onkyoprotocol, where Onkyo’s internal low-level commands are mapped toidentifiers that can be understood by humans, and which includedescriptions.

Parsing the Onkyo Excel document gets you astonishingly far, butthere’s a limit. The YAML file requires manual edits and fixes wherethe parser fails, including a lot of cosmetic corrections. Some ofthose have been made, but there’s significant room for improvingthe YAML description of the protocol.

The process and the specific YAML formatting have been chosen toallow future changes to the Onkyo master document to be merged withthe 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 toconsider using this YAML file as a basis for the command interfaceyou provide to users. You’ll have a complete list of availablecommands, values, and even supported devices.

Release historyRelease notifications

1.2.7

1.2.5

1.2.4

1.2.3

1.2.2

1.2.1

1.2

1.1

1.0

0.9.1

0.9

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for onkyo-eiscp, version 1.2.7
Filename, size	File type	Python version	Upload date	Hashes
Filename, size onkyo-eiscp-1.2.7.tar.gz (48.3 kB)	File type Source	Python version None	Upload date	Hashes

Hashes for onkyo-eiscp-1.2.7.tar.gz

Hashes for onkyo-eiscp-1.2.7.tar.gz
Algorithm	Hash digest
SHA256	`761abb16c654a1136763b927d094174d41f282809e44ea32cd47e199dd79d9c9`
MD5	`5b14b3cc7f88bb665652da98ea84b5ca`
BLAKE2-256	`057ba25440e34d015237d1f68b8e353f06eaa3a90c1fa77a6621e5e15e4388de`

Home‎ > ‎Tom's Ideas And Notes‎ > ‎

Java eISCP - Integra Serial Control Protocol

posted Nov 1, 2011, 9:45 PM by Tom Gutwin [ updated Dec 9, 2012, 11:19 AM]

I wanted to control my Onkyo AV receiver using a computer. Lucky for me, my Onkyo has a published serial control protocol that also works over Ethernet - eISCP. So off to the races!! I wrote a Java Implementation of the eISCP.
UPDATE:

I have added more to this Java App in a 2nd post - Part 2, where I have added full response processing.
read this post 1st then go on to Part 2

Onkyo's protocol doc is attached to this post below in the attachments section. This doc is version 1.21 dated 2011, I just got it from my dealer (Crutchfield.ca), great support! It appears to be newer than any other floating around the net and specifically references the 3008 and 5008 models.

There are a few implementations that are floating around the internet - the one I found most useful was a python implementation at https://github.com/compbrain/Onkyo-TX-NR708-Control. It worked but was minimal, plus I wanted to wrap eISCP in a Java class that was robust and extendable.
I wrote a simple java class that I plan to continue to expand its functionality:
My Eiscp.java file is attached to this post below in the attachments section

It has a full set of methods that can be used from other Java classes,
It can also be run from the command line to send commands and requests to a receiver.
> java ca.bc.webarts.tools.eiscp.Eiscp MUTE

Things I still want to update:

It does not (yet) validate if the receiver can accept the specific commands,
It has the IP and port hardcoded,
all the command strings are hard-coded (I want to put them in some config/properties file).
more stuff

While I was implementing the eISCP message packet I found some things that were unclear in the Onkyo protocol document. Specifically the data size part of the message - is actually the size of the entire message, not just the data part. See my comments in the code for details.

Here is my code for the method that forms the data message. (full class is attached below)

getEiscpMessage Method

/**
* Wraps a command in a eiscp data message (data characters).
*
* @param command must be one of the Strings from the eiscp.Eiscp.Command class.
**/
public StringBuilder getEiscpMessage(String command)
{
StringBuilder sb = new StringBuilder();
int eiscpDataSize = command.length() + 2 ; // this is the eISCP data size
int eiscpMsgSize = eiscpDataSize + 1 + 16 ; // this is the size of the entire eISCP msg
/* This is where I construct the entire message
character by character. Each char is represented by a 2 disgit hex value */
sb.append('ISCP');
// the following are all in HEX representing one char
// 4 char Big Endian Header
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('10', 16));
// 4 char Big Endian data size
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
// the official ISCP docs say this is supposed to be just the data size (eiscpDataSize)
// ** BUT **
// It only works if you send the size of the entire Message size (eiscpMsgSize)
sb.append((char)Integer.parseInt(Integer.toHexString(eiscpMsgSize), 16));
// eiscp_version = '01';
sb.append((char)Integer.parseInt('01', 16));
// 3 chars reserved = '00'+'00'+'00';
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
sb.append((char)Integer.parseInt('00', 16));
// eISCP data
// Start Character
sb.append('!');
// eISCP data - unittype char '1' is receiver
sb.append('1');
// eISCP data - 3 char command and param ie PWR01
sb.append( command);

 // msg end - this can be a few different cahrs depending on you receiver
 // my NR5008 works when I use 'EOF'

sb.append((char)Integer.parseInt('0D', 16));
System.out.println('eISCP data size: '+eiscpDataSize +'(0x'+Integer.toHexString(eiscpDataSize) +') chars');
System.out.println('eISCP msg size: '+sb.length() +'(0x'+Integer.toHexString(sb.length()) +') chars');
return sb;
}

You can take and use the code as per the GNU license.

Have fun! and check back, I will continue to extend this until I have a full remote app.

Stay tuned, I also want to test this through the Networking module of the Universal DevicesISY-99i home controller.