OpenMotics Python SDK

From OpenMotics
Revision as of 11:38, 5 April 2014 by Fryckbos (talk | contribs)
Jump to navigation Jump to search

The code for the Python SDK can be found at ....

Hello world

As a 'Hello world' example we will put output 1 in the ON state.

api = OpenMoticsCloudApi("user", "pass")
api.set_output(1, True)

We can do the same for a local gateway, without using the OpenMotics cloud:

api = OpenMoticsApi("OpenMotics.local", "user", "pass")
api.set_output(1, True)

All Gateway API functions can be called on an instance of OpenMoticsCloudApi and OpenMoticsApi. The cloud api also exposes a convenient messaging system that uses long polling https requests to receive events such as output or thermostat state changes and realtime power statistics.

A more useful example

Get the output configuration, select an output by name and turn the output on.

Messaging system on the cloud api

The messaging system works as follows: 1) register a subscriber with an randomly generated subscriber_id (api/update_message_subscription) 2) get the id of the last message (api/get_last_message_id) 3) wait for new messages (api/get_messages_wait). This step will return when a new message was available for the subscriber or when the connection times out.

The OpenMoticsCloudApi has a msg_loop method that takes care of registering a subscriber and keeping track of the last message. The user starts a msg_loop with a list of messages types on which he wants to subscribe and a callback for each received message.

api = OpenMoticsCloudApi("user", "pass")

def callback(msg):
    print "Output changed: %s" % msg['data']
    return True

api.msg_loop([ OpenMoticsCloudApi.MSG_OUTPUT_CHANGE ], callback)

Message types + data format

TODO Overview of message types

Cloud api with multiple installations

If an OpenMotics cloud user has access to 1 installation, this installation will be selected by default. When the user access to multiple installations, the user will have to select the currently used installation. The following example selects the first installation.

api = OpenMoticsCloudApi("user", "pass")
installations = api.get_installations()

get_installations() returns a list of dicts with the following keys: id (integer), name (String), version (String).