Hyperion Ambient Lighting Python Package
Project description
Hyperion Library
Python library for Hyperion-NG. See JSON API for more details about the inputs and outputs of this library.
Usage
Client API calls
All API calls can be found in
client.py.
All async calls start with async_
.
Data model philosophy
Whilst not universally true, this library attempts to precisely represent the data model, API and parameters as defined in the Hyperion JSON documentation. Thus no attempt is made (intentionally) to present convenient accessors/calls at a finer level of granularity than the model already supports. This is to ensure the client has a decent chance at staying functional regardless of underlying data model changes from the server, and the responsibility to match the changes to the server's data model (e.g. new Hyperion server features) belong to the caller.
Connection & Disconnection
- async_connect()
- async_disconnect()
Native API Calls
Send request and await response | Send request only | Documentation |
---|---|---|
async_clear | async_send_clear | Docs |
async_image_stream_start | async_send_image_stream_start | Docs |
async_image_stream_stop | async_send_image_stream_stop | Docs |
async_is_auth_required | async_send_is_auth_required | Docs |
async_led_stream_start | async_send_led_stream_start | Docs |
async_led_stream_stop | async_send_led_stream_stop | Docs |
async_login | async_send_login | Docs |
async_logout | async_send_logout | Docs |
async_request_token | async_send_request_token | Docs |
async_request_token_abort | async_send_request_token_abort | Docs |
async_set_adjustment | async_send_set_adjustment | Docs |
async_set_color | async_send_set_color | Docs |
async_set_component | async_send_set_component | Docs |
async_set_effect | async_send_set_effect | Docs |
async_set_image | async_send_set_image | Docs |
async_set_led_mapping_type | async_send_set_led_mapping_type | Docs |
async_set_sourceselect | async_send_set_sourceselect | Docs |
async_set_videomode | async_send_set_videomode | Docs |
async_start_instance | async_send_start_instance | Docs |
async_stop_instance | async_send_stop_instance | Docs |
async_switch_instance | async_send_switch_instance | Docs |
Note that the command
and subcommand
keys shown in the above linked
documentation will automatically be included in the calls the client sends, and
do not need to be specified.
Client inputs / outputs
The API parameters and output are all as defined in the JSON API documentation.
Example usage:
#!/usr/bin/python
import asyncio
from hyperion import client, const
HOST = "hyperion"
async def print_brightness():
hyperion_client = client.HyperionClient(HOST)
if not await hyperion_client.async_connect():
return
print("Brightness: %i%%" % hyperion_client.adjustment[0][const.KEY_BRIGHTNESS])
if __name__ == "__main__":
asyncio.get_event_loop().run_until_complete(print_brightness())
Running in the background
A background asyncio task
runs to process all post-connection inbound data
(e.g. request responses, or subscription updates from state changes on the
server side). This background task must either be started post-connection, or
start (and it will itself establish connection).
Optionally, this background task can call callbacks back to the user.
Waiting for responses
If the user makes a call that does not have _send_
in the name (see table
above), the function call will wait for the response and return it to the
caller. This matching of request & response is done via the tan
parameter. If
not specified, the client will automatically attach a tan
integer, and this
will be visible in the returned output data. This matching is necessary to
differentiate between responses due to requests, and "spontaneous data" from
subscription updates.
Example: Waiting for a response
#!/usr/bin/python
from hyperion import client
async def go():
hc = client.HyperionClient('hyperion')
await hc.async_connect()
hc.start_background_task()
result = await hc.async_is_auth_required()
print("Result: %s" % result)
import asyncio
asyncio.get_event_loop().run_until_complete(go())
Output:
Result: {'command': 'authorize-tokenRequired', 'info': {'required': False}, 'success': True, 'tan': 1}
Callbacks
The client can be configured to callback as the Hyperion server reports new values. There are two classes of callbacks supported:
- default_callback: This callback will be called when a more specific callback is not specified.
- callbacks: A dict of callbacks keyed on the Hyperion subscription 'command' (see JSON API documentation)
Callbacks can be specified in the HyperionClient
constructor
(default_callback=
or callbacks=
arguments) or after construction via the
set_callbacks()
and set_default_callback()
methods.
As above, the callbacks
dict is keyed on the relevant Hyperion subscription
command
(e.g. components-update
, priorities-update
). The client also
provides a custom callback with command connection-update
of the following
form:
{"command": "connection-update",
"connected": True}
This can be used to take special action as the client connects or disconnects from the server.
Example: Callbacks
from hyperion import client, const
HOST = "hyperion"
def callback(json):
print("Received Hyperion command: %s" % json)
if __name__ == "__main__":
hyperion_client = client.HyperionClient(HOST, default_callback=callback)
asyncio.get_event_loop().run_until_complete(hyperion_client.async_connect())
# Start client in "background".
hyperion_client.start_background_task()
asyncio.get_event_loop().run_forever()
Output:
Received Hyperion command: {'command': 'connection-update', 'connected': True}
ThreadedHyperionClient
A ThreadedHyperionClient
is also provided as a convenience wrapper to for
non-async code. The ThreadedHyperionClient
wraps the async calls with
non-async versions (without the async_
on the method names shown above).
Example use of Threaded client
#!/usr/bin/python
from hyperion import client, const
HOST = "hyperion"
if __name__ == "__main__":
hyperion_client = client.ThreadedHyperionClient(HOST)
# Start the asyncio loop in a new thread.
hyperion_client.start()
# Connect the client.
hyperion_client.connect()
print("Brightness: %i%%" % hyperion_client.adjustment[0][const.KEY_BRIGHTNESS])
# Stop the loop (will stop the thread).
hyperion_client.stop()
# Join the created thread.
hyperion_client.join()
Output:
Brightness: 59%
Exceptions
Philosophy
HyperionClient strives not to throw an exception regardless of network circumstances, reconnection will automatically happen in the background. Exceptions are only raised (intentionally) for instances of likely programmer error.
HyperionError
Not directly raised, but other exceptions inherit from this.
HyperionClientConnectAfterStartError
Exception raised if connect()
or async_connect()
is called after
start_background_task()
. Either only start_background_task()
should be
called (it will automatically connect), or async_connect()
/connect()
should
be called first, followed by start_background_task()
once the connect call
has returned.
HyperionClientTanNotAvailable
Exception raised if a tan
parameter is provided to an API call, but that
tan
parameter is already being used by another in-progress call. Users
should either not specify tan
at all (and the client library will
automatically manage it in an incremental fashion), or if specified manually,
it is the caller's responsibility to ensure no two simultaneous calls share a
tan
(as otherwise the client would not be able to match the call to the
response, and this exception will be raised automatically prior to the call).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for hyperion_py-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 80efa117df34f2bd1cade3037ce52a40529d83b67903d4a65144590aa0e9437e |
|
MD5 | 7094cfe7fa6275f3b3880044ed5fdc26 |
|
BLAKE2b-256 | 789c74f9e821d629721a88545601a1b2b815dc9ea7b7071e3c2e70b9b22f633e |