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