2.7. Sensor Control Channel: Actuators

An actuator is a sensor that uses a control channel to actuate things. Rather than POSTing data to the WoTKit, an actuator script or gateway polls the control URL for messages to affect the actuator, to do things like move a servo motor, turn a light on or off, or display a message on a screen. Any name/value pair can be sent to an actuator in a message.

For example, provided with the WoTKit at , a control widget that can be added to a dashboard (http://wotkit.sensetecnic.com/wotkit//dashboards) sends three types of events to the sensor control channel:

button	‘on’ or ‘off’ to control a light, or switch.
message	text message for use by the actuator, for example to be shown on a message board or display.
slider	a numeric value to affect the position of something, such as a server motor.

2.7.1. Sending Actuator Messages

To send a control message to a sensor (actuator), you must POST name value pairs corresponding to the data fields to the /sensors/{sensorname}/message URL.

URL	http://wotkit.sensetecnic.com/api/v1/sensors/{sensorname}/message
Privacy	Public or Private
Format	x-www-form-urlencoded
Method	POST
Returns	OK 200 (no content) on success.

2.7.2. Receiving Actuator Messages

To receive actuator messages you must first subscribe to an Actuator Controller, then you can query for messages.

Note

In order to receive messages from an actuator, you must own that actuator.

2.7.2.1. Subscribing to an Actuator Controller

First, subscribe to the controller by POSTing to /api/control/sub/{sensor-name}. In return, we receive a json object containing a subscription id.

URL	http://wotkit.sensetecnic.com/api/v1/control/sub/{sensor-name}
Privacy	Private
Format	json
Method	POST
Returns	200 OK on success. A JSON object in the response body containing subscription id.

Example subscription id returned:

{
        "subscription":1234
}

2.7.2.2. Query an Actuator

Using the subscription id, then poll the following resource: /api/control/sub/{subscription-id}?wait=10. The wait parameter specifies the time to wait in seconds for a control message. If unspecified, a default wait time of 10 seconds is used. The maximum wait time is 20 seconds. The server will respond on timeout, or when a control messages is received.

URL	http://wotkit.sensetecnic.com/api/v1/control/sub/{subscription-id}?wait={wait-time}
Privacy	Private
Format	json
Method	GET
Returns	200 OK on success. A JSON object in the response body containing control messages.

Note

Each subscription will be open for as long as the client that created it keeps sending long pull requests. A subscription that does not receive any requests after 5 minutes (3000 seconds) will be garbage-collected and will not be accessible after that. A client must catch this error and create a new subscription if this occurs.

To illustrate, the following code snippet uses HTTP client libraries to subscribe and get actuator messages from the server, and then print the data. Normally, the script would change the state of an actuator like a servo or a switch based on the message received.

# sample actuator code
import urllib
import urllib2
import base64
import httplib

try:
        import json
except ImportError:
        import simplejson as json

#note trailing slash to ensure .testactuator is not dropped as a file extension
actuator="mike.testactuator/"

# authentication setup
conn = httplib.HTTPConnection("wotkit.sensetecnic.com")
base64string = base64.encodestring('%s:%s' % ('{id}', '{password}'))[:-1]
authheader =  "Basic %s" % base64string
# In some clients (<Python 2.6) params must be used to force sending Content-Length header
# so, we'll use dummy params.
params = urllib.urlencode({'@type': 'subscription'})
headers = {'Authorization': authheader}

#subscribe to the controller and get the subscriber ID
conn.request("POST", "/api/v1/control/sub/" + actuator, params, headers=headers)
response = conn.getresponse()
data = response.read()

json_object = json.loads(data)
subId = json_object['subscription']

#loop to long poll for actuator messages
while 1:
        print "request started for subId: " + str(subId)
        conn.request("GET", "/api/v1/control/sub/" + str(subId) + "?wait=10", headers=headers)
        response = conn.getresponse()
        data = response.read()

        json_object = json.loads(data)

                # change state of actuator based on json message received
        print json_object