Data Provider Catalog Plugin Requests

Revision as of 03:31, 14 April 2010

Here are the possible requests you can make on port 3451 to the Data Provider Catalog Plugin. For a general overview, see Data_Provider_Catalog_Plugin

Built-in requests

user_data
Optional URL Parameters: output_format=json
Post Variables: parm=[json data to update] as multipart/form-data, not application/x-www-form-urlencoded

This is the main request to retrieve the configuration and to make changes to it. This returns the current configuration, which is stored in JSON format: http://192.168.81.1:3451/user_data?output_format=json
Go to http://www.jsonlint.com/ to format it nicely for easy reading.

To update information, such as adding rooms, renaming devices, and so on, put the new JSON in the post variable 'parm'. When you are including a JSON object your new objects are by default merged into the current ones unless you can attach the special tag json_action with "add" or "del" to explicitly add or remove something. For example, assume that the data is currently like this:

 "Room": {
       "PK_Room_1": {
           "Description": "Living Room",
           "FK_Section": "1" 
       },
       "PK_Room_2": {
           "Description": "Bedroom",
           "FK_Section": "1" 
       } 

You want to remove the bedroom and add a new room called "Den" and change the Living Room to be called Kitchen. You put the following in the parm post:

{

   "Room": {
       "PK_Room_2": {
           "json_action": "del" 
       },
       "PK_Room_1": {
           "Description": "Kitchen",
       },
       "PK_Room_1000002": {
           "Description": "Den",
           "FK_Section": "1",
           "json_action": "add" 
       } 
   }

}

Note that Sections, Rooms, Devices, and Scenes are all numbered: PK_Room_1, scene_2, etc. When are adding new Sections, Rooms, Devices, and Scenes, use a number that is very high (> 1,000,000) to prevent conflicts. Note that Room uses a really large ID. You don't want to use the next available ID, like 3, because that might already have been created by another user, and, since the ID # is the key to merging, your new room would be preserved and there would be 2 room 3's if json_action=add, or your changes would be merged and overwrite room 3 otherwise. When you use large id's > 1m, then on save, the system automatically re-numbers them and re-outputs the renumbered result. This includes relationships as well. So if you are submitting a new scene, device, room, etc., the device may be id 1m, and reference room 2, so it goes into room 2, and a new device id 1m + 1 may reference room 1m. In this case both device id's would be renumbered, and the room 1m would be renumbered, and the reference in the device id 1m + 1 would be changed to reflect this.

Thus when you submit new json data you should always output_format=json to the URL which causes the new json result to be output. Then replace the existing json tree with the new one. If there was a problem with your submission, you'll get back FAIL + a message instead of json. If you leave off output_format you will just get back an "OK" or a failure message.

messagesend
URL Parameters:
from=the originating device ID
to=the destination device id
type=the type of message
id=the message id
response=[r|o|c] for Return String, Output Parameters, and Confirmation of delivery. (Default=don't wait for response)
target=[c|t] meaning the 'to' id is not a device ID but rather a Category or Template of device. (Default='to' is a device id)
[device data]=some other message parameter, where 'device data' is the parameter number
output_format=[json_callback_xxx|html] is how you want the response to come back, where xxx is a function that you want called in java script

For example, to request a video frame from a camera with the device id #20 you send the message type 1 (command), id 84 (get video frame) and optionally the parameter 60 and 61 (width and height of desired image). The command returns output parameters 19 and 20 where 19 contains the video image and 20 the format. So you would send a message with response=o, causing the request to block until the message is processed by device 20, and to get back the output parameters. Here is the URL:

http://192.168.80.1:3451/messagesend?from=1&to=20&response=o&type=1&id=84&60=640&61=480

messagesend_cmdline
message=The message in the same format as the command line utility /usr/bin/MessageSend URL encoded
output_format=same as messagesend

simple_html
A simple text-only html control interface for use on WAP phones

iphone
A basic web-based iphone interface

data_request

These are passed on to the plugins and other devices that register to handle them. The URL contains:

id=id of the data request
parameters=parameters to send on the data request
input_format=format of the parameters being sent
output_format= the desired output format of the data (xml, json, or nothing for plain text)

Every device in the system can register to handle a particular 'id'. The parameters are defined by the device. The input_format is what format you will send the parameters in, in case the device can handle multiple formats, and output_format is how to get the data out. Here are the current id's:

simple_device_list
A simple list of the devices

scene_detail
A simple list of the scenes

zwave_status
The status of all ZWave devices. See ZWave_Status

job_status
The status of a job. You must pass on the parameter the id of the device that is handling the job, or the id of one of the device's children. You can optionally add a , followed by the particular job id. So: http://127.0.0.1:3451/data_request?id=job_status&parameters=16,17 that will return information on job #17 that is being handled by device #16. If you leave off the ,17, then you'll get all jobs currently active by device 16, but, without specifying the job id, the list only includes currently active devices. If you specify the job id you can get the status up to 3 minutes after the job has finished.

live_energy_usage
Live Energy usage

camera_control/xxx
Control for camera xxx

lu_device
Return the LuaUPNP device description document in XML format. The only output format is xml. This is the same description document that is retrieved by UPNP control points when they interrogate Vera. Vera provides one master device (called Vera) which has embedded devices for lights, sensors, a/v gear, and so on. Get the master document like this: http://ipaddress:3451/data_request?id=lu_device or if you want to see only the device description for a particular embedded device add &parameters=[devicenumber] to the URL.

lu_file
Return the contents of the file 'lu_file' from the UPNP root file directory. Example: http://ipaddress:3451/data_request?id=lu_file&parameters=HVAC_ZoneThermostat1.xml

lu_lua
Returns the Lua code for the device specified in the parameter. The only output format is text. Example: http://192.168.1.102:3451/data_request?id=lu_lua&parameters=15

lu_action
Executes a UPNP action. Pass on the URL either DeviceNum=[number of device] or udn=[UDN of device] and serviceId=[serviceid], or, if you don't specify it, the first service with the given action is assumed. Pass the name of the action as 'action'. Any extra arguments will be passed as arguments to the action. The response to the UPNP action is returned in the output_format, or, if there's an error, an error string is returned instead. So this turns on light #13: http://ipadress:49451/data_request?id=lu_action&output_format=xml&DeviceNum=10&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=1