Difference between revisions of "OpenMotics Python SDK"

From OpenMotics
Jump to navigation Jump to search
m
Line 43: Line 43:
  
 
=== Message types + data format ===
 
=== Message types + data format ===
TODO Overview of message types
 
  
 +
* 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
 +
* 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 ==
 
== Cloud api with multiple installations ==

Revision as of 12:21, 5 April 2014

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. 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
  • 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).