Metadata-Version: 1.1
Name: onkyo-eiscp
Version: 1.2.7
Summary: Control Onkyo receivers over ethernet.
Home-page: https://github.com/miracle2k/onkyo-eiscp
Author: Michael Elsdörfer
Author-email: michael@elsdoerfer.com
License: MIT
Description: Onkyo eISCP Control
        ===================
        
        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.
        
        
        Installation
        ------------
        
        Most recent released version::
        
            $ easy_install onkyo-eiscp
        
        
        Usage
        -----
        
        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 0009B0D34163
            TX-NR609 192.168.178.169:60128 0009B0D24B75
           
            $ onkyo -n 709 system-power=on
        
        This will only turn on the TX-NR709 device.
        
        Or using the unique identifier::
        
            $ onkyo -i 0009B0D24B75 system-power=on
        
        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::
        
            $ 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.
        
        
        Commands
        --------
        
        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.
        
        
        Notes on Power On
        ~~~~~~~~~~~~~~~~~
        
        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.
        
        
        Python module
        -------------
        
        In a simple case, this might look like this:
        
        .. code:: 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()
        
        Don't forget to call ``disconnect()`` to close the socket. You can also use
        a ``with`` statement:
        
        .. code:: python
        
            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
        `raw` method::
        
            receiver.raw('MVLUP')
        
        The function `command_to_iscp` will allow you to convert a high-level
        command to a low-level ISCP message for use with `eISCP.raw`.
        
        
        Receiving messages
        ~~~~~~~~~~~~~~~~~~
        
        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 `eISCP.raw` and `eISCP.command` return the
        response received from the Onkyo device. They are blocking.
        
        To receive other messages, there is `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
            `eISCP.raw` or `eISCP.command`, any messages not picked
            up via `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 `eISCP.raw` or `eISCP.command`, which try to serialize
        the exchange into a request-response scheme, you may also use
        `eISCP.send`, which dispatches a message without waiting for a response.
        You would then use `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.
        
        
        Async API
        ~~~~~~~~~
        
        There is also an experimental `eiscp.Receiver`, which has the
        same api as `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, `eISCP.raw` and `eISCP.command` are still
        designed to artificially block, while `eISCP.send` is non-blocking.
        
        
        Device discovery
        ~~~~~~~~~~~~~~~~
        
        You can have it find the receivers on your local network:
        
        .. code:: python
        
            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:
        
        .. code:: python
        
            {'iscp_port': '60128', 'identifier': '0009B04448E0',
             'area_code': 'XX', 'model_name': 'TX-NR709', 'device_category': '1'}
        
        
        Limitations
        -----------
        
        - 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).
        
        
        The YAML file
        -------------
        
        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.
        
        
        Related Links
        -------------
        
        Documents from Onkyo describing the protocol, including lists of supported commands:
            - http://michael.elsdoerfer.name/onkyo/ISCP_AVR_134.xlsx
            - http://michael.elsdoerfer.name/onkyo/ISCP_AVR_2014.Models.xlsx
            - http://michael.elsdoerfer.name/onkyo/ISCP-V1.26_2013.xlsx
            - http://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xls
        
        The repository on which this was originally based on:
            https://github.com/compbrain/Onkyo-TX-NR708-Control
        
        An implementation in Perl:
            https://github.com/beanz/device-onkyo-perl
        
        An implementation in C#:
            http://code.google.com/p/onkyo-eiscp-remote-windows/
        
        An implementation in Object-C:
            https://github.com/janten/onkyo-eiscp-remote-mac
        
        MQTT connectivity for onkyo-eiscp, adhering to the mqtt-smarthome specification:
            https://github.com/owagner/onkyo2mqtt
        
        Some 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
Platform: any
Classifier: Topic :: System :: Networking
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
