OpenMotics Python SDK

From OpenMotics
Jump to: navigation, search

The code for the Python SDK can be found at https://github.com/openmotics/sdk

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

Show all outputs that are on and turn them off.

api = OpenMoticsCloudApi("user", "pass")
 
configs = api.get_output_configurations()['config']
output_names = dict()
for config in configs:
    output_names[config["id"]] = config["name"]
 
for status in api.get_output_status()['status']:
    oid = status['id']
    if status['status'] == 1:
        print "Turning off output %s: %s" % (oid, output_names[oid])
        api.set_output(oid, False)

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. The msg_loop keeps running until the callback returns False.

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

  • MSG_OUTPUT_CHANGE
    • Is sent whenever the state of an output changes
    • The message does not contain the actual state of the output, this has to be fetched in an extra call
    • Data format: Integer - input id of the changed input
  • MSG_THERMOSTAT_CHANGE
    • Is sent whenever the state of a thermostat changes
    • The message does not contain the actual state of the thermostat, this has to be fetched in an extra call
    • Data format: Integer - thermostat id of the changed thermostat
  • MSG_RT_POWER_RAW
    • Is sent when the cloud receives power data from the gateway (typically every x seconds)
    • The message contains all realtime information about the power usage
    • Data format: dictionary with the power module id (as String) as key and a list as value. This list contains
  • MSG_RT_POWER_TAGS
  • MSG_RT_PULSE_COUNTERS
  • MSG_RT_ENERGY_SUPPLIERS
  • MSG_RT_ENERGY_MODULES
  • MSG_RT_ENERGY_TAGS

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()
api.set_installation_id(installations[0]['id'])

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