Package: hyperion-py
Hyperion LibraryPython library forHyperion-NG. SeeJSON
APIfor more details about the
inputs and outputs of this library.Installation$pip3installhyperion-pyUsageData model philosophyWhilst not universally true, this library attempts to precisely represent the
data model, API and parameters as defined in theHyperion 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.Constructor ArgumentsThe following arguments may be passed to theHyperionClientconstructor:ArgumentTypeDefaultDescriptionhoststrHost or IP to connect toportint19444Port to connect todefault_callbackcallableNoneA callable for Hyperion callbacks. SeecallbackscallbacksdictNoneA dictionary of callables keyed by the update name. SeecallbackstokenstrNoneAn authentication tokeninstanceint0An instance id to switch to upon connectionoriginstr"hyperion-py"An arbitrary string describing the calling applicationtimeout_secsfloat5.0The number of seconds to wait for a server response or connection attempt before giving up. Seetimeoutsretry_secsfloat30.0The number of seconds between connection attemptsraw_connectionboolFalseIf True, the connect call will establish the network connection but not attempt to authenticate, switch to the required instance or load state. The client must callasync_client_loginto login,async_client_switch_instanceto switch to the configured instance andasync_get_serverinfoto load the state manually. This may be useful if the caller wishes to communicate with the server prior to authentication.Connection, disconnection and client control callsasync_client_connect(): Connect the client.async_client_disconnect(): Disconnect the client.async_client_login(): Login a connected client. Automatically called byasync_client_connect()unless theraw_connectionconstructor argument is True.async_client_switch_instance(): Switch to the configured instance on the Hyperion
server. Automatically called byasync_client_connect()unless theraw_connectionconstructor argument is True.Native API CallsAll API calls can be found inclient.py.
All async calls start withasync_.Send request and await responseSend request onlyDocumentationasync_clearasync_send_clearDocsasync_image_stream_startasync_send_image_stream_startDocsasync_image_stream_stopasync_send_image_stream_stopDocsasync_is_auth_requiredasync_send_is_auth_requiredDocsasync_led_stream_startasync_send_led_stream_startDocsasync_led_stream_stopasync_send_led_stream_stopDocsasync_loginasync_send_loginDocsasync_logoutasync_send_logoutDocsasync_request_tokenasync_send_request_tokenDocsasync_request_token_abortasync_send_request_token_abortDocsasync_get_serverinfoasync_send_get_serverinfoDocsasync_set_adjustmentasync_send_set_adjustmentDocsasync_set_colorasync_send_set_colorDocsasync_set_componentasync_send_set_componentDocsasync_set_effectasync_send_set_effectDocsasync_set_imageasync_send_set_imageDocsasync_set_led_mapping_typeasync_send_set_led_mapping_typeDocsasync_set_sourceselectasync_send_set_sourceselectDocsasync_set_videomodeasync_send_set_videomodeDocsasync_start_instanceasync_send_start_instanceDocsasync_stop_instanceasync_send_stop_instanceDocsasync_switch_instanceasync_send_switch_instanceDocsasync_sysinfoasync_send_sysinfoDocsNote that thecommandandsubcommandkeys 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 / outputsThe API parameters and output are all as defined in theJSON API
documentation.Example usage:#!/usr/bin/env python"""Simple Hyperion client read demonstration."""importasynciofromhyperionimportclient,constHOST="hyperion"asyncdefprint_brightness()->None:"""Print Hyperion brightness."""asyncwithclient.HyperionClient(HOST)ashyperion_client:asserthyperion_clientadjustment=hyperion_client.adjustmentassertadjustmentprint("Brightness:%i%%"%adjustment[0][const.KEY_BRIGHTNESS])if__name__=="__main__":asyncio.get_event_loop().run_until_complete(print_brightness())Running in the backgroundA backgroundasyncio taskruns 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 responsesIf 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 thetanparameter. If
not specified, the client will automatically attach ataninteger, 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/env python"""Simple Hyperion client request demonstration."""importasynciofromhyperionimportclientHOST="hyperion"asyncdefprint_if_auth_required()->None:"""Print whether auth is required."""hc=client.HyperionClient(HOST)awaithc.async_client_connect()result=awaithc.async_is_auth_required()print("Result:%s"%result)awaithc.async_client_disconnect()asyncio.get_event_loop().run_until_complete(print_if_auth_required())Output:Result: {'command': 'authorize-tokenRequired', 'info': {'required': False}, 'success': True, 'tan': 1}Example: Sending commandsA slightly more complex example that sends commands (clears the Hyperion source
select at a given priority, then sets color at that same priority).#!/usr/bin/env python"""Simple Hyperion client request demonstration."""importasyncioimportloggingimportsysfromhyperionimportclientHOST="hyperion"PRIORITY=20asyncdefset_color()->None:"""Set red color on Hyperion."""asyncwithclient.HyperionClient(HOST)ashc:asserthcifnotawaithc.async_client_connect():logging.error("Could not connect to:%s",HOST)returnifnotclient.ResponseOK(awaithc.async_clear(priority=PRIORITY))ornotclient.ResponseOK(awaithc.async_set_color(color=[255,0,0],priority=PRIORITY,origin=sys.argv[0])):logging.error("Could not clear/set_color on:%s",HOST)returnlogging.basicConfig(stream=sys.stdout,level=logging.DEBUG)asyncio.get_event_loop().run_until_complete(set_color())Example: Starting and switching instancesThe following example will start a stopped instance, wait for it to be ready,
then switch to it. Usescallbacks, discussed below.#!/usr/bin/env python"""Simple Hyperion client request demonstration."""from__future__importannotationsimportasyncioimportloggingimportsysfromtypingimportAnyfromhyperionimportclientHOST="hyperion"PRIORITY=20asyncdefinstance_start_and_switch()->None:"""Wait for an instance to start."""instance_ready=asyncio.Event()definstance_update(json:dict[str,Any])->None:fordatainjson["data"]:ifdata["instance"]==1anddata["running"]:instance_ready.set()asyncwithclient.HyperionClient(HOST,callbacks={"instance-update":instance_update})ashc:asserthcifnotclient.ResponseOK(awaithc.async_start_instance(instance=1)):logging.error("Could not start instance on:%s",HOST)return# Blocks waiting for the instance to start.awaitinstance_ready.wait()ifnotclient.ResponseOK(awaithc.async_switch_instance(instance=1)):logging.error("Could not switch instance on:%s",HOST)returnlogging.basicConfig(stream=sys.stdout,level=logging.DEBUG)asyncio.get_event_loop().run_until_complete(instance_start_and_switch())CallbacksThe 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' (seeJSON API documentation)Callbacks can be specified in theHyperionClientconstructor
(default_callback=orcallbacks=arguments) or after construction via theset_callbacks()andset_default_callback()methods.As above, thecallbacksdict is keyed on the relevant Hyperion subscriptioncommand(e.g.components-update,priorities-update). The client also
provides a custom callback with commandclient-updateof the following
form:{"command":"client-update","connected":True,"logged-in":True,"instance":0,"loaded-state":True}This can be used to take special action as the client connects or disconnects from the server.Example: Callbacks#!/usr/bin/env python"""Simple Hyperion client callback demonstration."""from__future__importannotationsimportasynciofromtypingimportAnyfromhyperionimportclientHOST="hyperion"defcallback(json:dict[str,Any])->None:"""Sample callback function."""print("Received Hyperion callback:%s"%json)asyncdefshow_callback()->None:"""Show a default callback is called."""asyncwithclient.HyperionClient(HOST,default_callback=callback):passif__name__=="__main__":asyncio.get_event_loop().run_until_complete(show_callback())Output, showing the progression of connection stages:Received Hyperion callback: {'connected': True, 'logged-in': False, 'instance': None, 'loaded-state': False, 'command': 'client-update'}
Received Hyperion callback: {'connected': True, 'logged-in': True, 'instance': None, 'loaded-state': False, 'command': 'client-update'}
Received Hyperion callback: {'connected': True, 'logged-in': True, 'instance': 0, 'loaded-state': False, 'command': 'client-update'}
Received Hyperion callback: {'command': 'serverinfo', ... }
Received Hyperion callback: {'connected': True, 'logged-in': True, 'instance': 0, 'loaded-state': True, 'command': 'client-update'}ThreadedHyperionClientAThreadedHyperionClientis also provided as a convenience wrapper to for
non-async code. TheThreadedHyperionClientwraps the async calls with
non-async versions (methods are named as shown above, except do not start withasync_).Waiting for the thread to initialize the clientThe thread must be given a chance to initialize the client prior to interaction
with it. This method call will block the caller until the client has been initialized.wait_for_client_init()Example use of Threaded client#!/usr/bin/env python"""Simple Threaded Hyperion client demonstration."""fromhyperionimportclient,constHOST="hyperion"if__name__=="__main__":hyperion_client=client.ThreadedHyperionClient(HOST)# Start the asyncio loop in a new thread.hyperion_client.start()# Wait for the client to initialize in the new thread.hyperion_client.wait_for_client_init()# Connect the client.hyperion_client.client_connect()print("Brightness:%i%%"%hyperion_client.adjustment[0][const.KEY_BRIGHTNESS])# Disconnect the client.hyperion_client.client_disconnect()# Stop the loop (will stop the thread).hyperion_client.stop()# Join the created thread.hyperion_client.join()Output:Brightness: 59%Exceptions / ErrorsPhilosophyHyperionClient 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.HyperionErrorNot directly raised, but other exceptions inherit from this.HyperionClientTanNotAvailableException raised if atanparameter is provided to an API call, but thattanparameter is already being used by another in-progress call. Users
should either not specifytanat 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 atan(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)."Task was destroyed but it is pending!"If aHyperionClientobject is connected but destroyed prior to disconnection, a warning message may be printed ("Task was destroyed but it is pending!"). To avoid this, ensure to always callasync_client_disconnectprior to destruction of a connected client. Alternatively use the async context manager:asyncwithclient.HyperionClient(TEST_HOST,TEST_PORT)ashc:ifnothc:return...TimeoutsThe client makes liberal use of timeouts, which may be specified at multiple levels:In the client constructor argumenttimeout_secs, used for connection and requests.In each request using atimeout_secsargument to the individual callsTimeout values:None: IfNoneis used as a timeout, the client will wait forever.0: If0is used as a timeout, the client default (specified in the constructor) will be used.>0.0: This number of seconds (or partial seconds) will be used.By default, all requests will honour thetimeout_secsspecified in the client constructor unless explicitly overridden and defaults to 5 seconds (seeconst.py). The one exception to this is theasync_send_request_tokenwhich has a much larger default (180 seconds, seeconst.py) as this request involves the user needing the interact with the Hyperion UI prior to the call being able to return.HelpersResponseOKA handful of convenience callable classes are provided to determine whether
server responses were successful.ResponseOK: Whether any Hyperion command response was successful (general).ServerInfoResponseOK: Whether aasync_get_serverinfowas successful.LoginResponseOK: Whether anasync_loginwas successful.SwitchInstanceResponseOK: Whether anasync_switch_instancecommand was successful.Example usageif not client.ResponseOK(await hc.async_clear(priority=PRIORITY))Auth IDWhen requesting an auth token, a 5-character ID can be specified to ensure the
admin user is authorizing the right request from the right origin. By default
theasync_request_tokenwill randomly generate an ID, but if one is required
to allow the user to confirm a match, it can be explicitly provided. In this case,
this helper method is made available.generate_random_auth_id: Generate a random 5-character auth ID for external display and inclusion in a call toasync_request_token.Example usageauth_id  = hc.generate_random_auth_id()
hc.async_send_login(comment="Trustworthy actor", id=auth_id)
# Show auth_id to the user to allow them to verify the origin of the request,
# then have them visit the Hyperion UI.