Luup Requests

From MiOS
(Difference between revisions)
Jump to: navigation, search
(relay)
Line 1: Line 1:
 
[[Category:Development]]
 
[[Category:Development]]
 
In addition to sending requests using standard UPnP, you can also do most things using a simple HTTP requests.  Use the built-in URL <tt>data_request</tt>, and pass the following on the URL:
 
In addition to sending requests using standard UPnP, you can also do most things using a simple HTTP requests.  Use the built-in URL <tt>data_request</tt>, and pass the following on the URL:
*<tt>id</tt> the id of the request (prior to 15 Oct 2010 all requests had an lu_ in front, which is now optional),  
+
*<tt>id</tt> the id of the request (prior to 15 Oct 2010 all requests had an lu_ in front, which is now optional),
 
*<tt>output_format</tt> the format in which you want a response as <tt>json</tt>, <tt>xml</tt> or <tt>text</tt>.
 
*<tt>output_format</tt> the format in which you want a response as <tt>json</tt>, <tt>xml</tt> or <tt>text</tt>.
  
Line 8: Line 8:
 
==user_data==
 
==user_data==
  
Example: http://ipaddress:3480/data_request?id=user_data&output_format=xml
+
Example: http://ip_address:3480/data_request?id=user_data&output_format=xml
  
 
This returns the configuration data for Vera, which is a list of all devices and the UPnP variables which are persisted between resets as well as rooms, names, and other data the user sets as part of the configuration.
 
This returns the configuration data for Vera, which is a list of all devices and the UPnP variables which are persisted between resets as well as rooms, names, and other data the user sets as part of the configuration.
Line 17: Line 17:
  
 
Examples:
 
Examples:
* http://ipaddress:3480/data_request?id=status&output_format=xml
+
* http://ip_address:3480/data_request?id=status&output_format=xml
 
Or for a specific device:
 
Or for a specific device:
* http://ipaddress:3480/data_request?id=status&output_format=xml&UDN=uuid:4d494342-5342-5645-0002-000000000002  
+
* http://ip_address:3480/data_request?id=status&output_format=xml&UDN=uuid:4d494342-5342-5645-0002-000000000002
* http://ipaddress:3480/data_request?id=status&output_format=xml&DeviceNum=6
+
* http://ip_address:3480/data_request?id=status&output_format=xml&DeviceNum=6
  
 
==sdata==
 
==sdata==
Line 28: Line 28:
  
 
Examples:
 
Examples:
* http://ip:3480/data_request?id=sdata
+
* http://ip_address:3480/data_request?id=sdata
* http://ip:3480/data_request?id=sdata&output_format=xml
+
* http://ip_address:3480/data_request?id=sdata&output_format=xml
  
 
==actions==
 
==actions==
Line 35: Line 35:
 
==device==
 
==device==
  
Example: http://ipaddress:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=3
+
Example: http://ip_address:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=3
  
Example: http://ipaddress:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=Garage
+
Example: http://ip_address:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=Garage
  
Example: http://ipaddress:3480/data_request?id=device&action=delete&device=5
+
Example: http://ip_address:3480/data_request?id=device&action=delete&device=5
  
 
This renames or deletes a device.  Use action=rename or action=delete.  For rename, you can optionally assign a room by either passing either the ID or the name.
 
This renames or deletes a device.  Use action=rename or action=delete.  For rename, you can optionally assign a room by either passing either the ID or the name.
Line 46: Line 46:
  
 
---old---
 
---old---
This returns all the XML with all the UPNP device description documents.  Use: http://ipaddress:3480/data_request?id=device&output_format=xml&DeviceNum=x or &UDN=y to narrow it down.  Then when you see the service URL's, like <SCPDURL>/luvd/S_HVAC_UserOperatingMode1.xml</SCPDURL>, you can view them with: http://ipaddress:3480/luvd/S_HVAC_UserOperatingMode1.xml
+
This returns all the XML with all the UPNP device description documents.  Use: http://ip_address:3480/data_request?id=device&output_format=xml&DeviceNum=x or &UDN=y to narrow it down.  Then when you see the service URL's, like <SCPDURL>/luvd/S_HVAC_UserOperatingMode1.xml</SCPDURL>, you can view them with: http://ip_address:3480/luvd/S_HVAC_UserOperatingMode1.xml
 
---end old---
 
---end old---
  
 
==scene==
 
==scene==
  
Example: http://ipaddress:3480/data_request?id=scene&action=record
+
Example: http://ip_address:3480/data_request?id=scene&action=record
  
Example: http://ipaddress:3480/data_request?id=scene&action=pause&seconds=y
+
Example: http://ip_address:3480/data_request?id=scene&action=pause&seconds=y
  
Example: http://ipaddress:3480/data_request?id=scene&action=stoprecord
+
Example: http://ip_address:3480/data_request?id=scene&action=stoprecord
  
Example: http://ipaddress:3480/data_request?id=scene&action=listrecord
+
Example: http://ip_address:3480/data_request?id=scene&action=listrecord
  
Example: http://ipaddress:3480/data_request?id=scene&action=deleterecord&number=x
+
Example: http://ip_address:3480/data_request?id=scene&action=deleterecord&number=x
  
Example: http://ipaddress:3480/data_request?id=scene&action=saverecord&name=whatever&room=X
+
Example: http://ip_address:3480/data_request?id=scene&action=saverecord&name=whatever&room=X
  
Example: http://ipaddress:3480/data_request?id=scene&action=rename&scene=5&name=Chandalier&room=Garage
+
Example: http://ip_address:3480/data_request?id=scene&action=rename&scene=5&name=Chandalier&room=Garage
  
Example: http://ipaddress:3480/data_request?id=scene&action=delete&scene=5
+
Example: http://ip_address:3480/data_request?id=scene&action=delete&scene=5
  
Example: http://ipaddress:3480/data_request?id=scene&action=create&json=[valid json data]
+
Example: http://ip_address:3480/data_request?id=scene&action=create&json=[valid json data]
  
Example: http://ipaddress:3480/data_request?id=scene&action=list&scene=5
+
Example: http://ip_address:3480/data_request?id=scene&action=list&scene=5
  
 
This creates, renames, or deletes a scene depending on the action.
 
This creates, renames, or deletes a scene depending on the action.
Line 81: Line 81:
 
==room==
 
==room==
  
Example: http://ipaddress:3480/data_request?id=room&action=create&name=Kitchen
+
Example: http://ip_address:3480/data_request?id=room&action=create&name=Kitchen
  
Example: http://ipaddress:3480/data_request?id=room&action=rename&room=5&name=Garage
+
Example: http://ip_address:3480/data_request?id=room&action=rename&room=5&name=Garage
  
Example: http://ipaddress:3480/data_request?id=room&action=delete&room=5
+
Example: http://ip_address:3480/data_request?id=room&action=delete&room=5
  
 
This creates, renames, or deletes a room depending on the action.  To rename or delete a room you must pass the room id for the room=.
 
This creates, renames, or deletes a room depending on the action.  To rename or delete a room you must pass the room id for the room=.
Line 92: Line 92:
 
Returns the contents of a file in '''/etc/cmh''' or '''/etc/cmh-ludl'''. Has one parameter, <tt>parameters</tt>, which is the name of the file.
 
Returns the contents of a file in '''/etc/cmh''' or '''/etc/cmh-ludl'''. Has one parameter, <tt>parameters</tt>, which is the name of the file.
  
Example: http://192.168.81.1:3480/data_request?id=file&parameters=D_BinaryLight1.xml
+
Example: http://ip_address:3480/data_request?id=file&parameters=D_BinaryLight1.xml
  
 
==lua==
 
==lua==
Line 98: Line 98:
 
==action==
 
==action==
  
Example: http://ipaddress:3480/data_request?id=action&amp;output_format=xml&amp;DeviceNum=6&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1  
+
Example: http://ip_address:3480/data_request?id=action&amp;output_format=xml&amp;DeviceNum=6&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1
  
Sends a UPnP action.  
+
Sends a UPnP action.
  
To run a scene, you send the action 'RunScene' like this::  
+
To run a scene, you send the action 'RunScene' like this::
  
http://ipadress:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=&lt;SceneNum&gt;
+
http://ip_address:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=&lt;SceneNum&gt;
  
 
==variableset==
 
==variableset==
  
http://ip:3480/data_request?id=variableset&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status&Value=1
+
http://ip_address:3480/data_request?id=variableset&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status&Value=1
  
 
If you leave off the DeviceNum and serviceID, then this sets a top-level json tag called "Variable" with the value.
 
If you leave off the DeviceNum and serviceID, then this sets a top-level json tag called "Variable" with the value.
Line 114: Line 114:
 
==variableget==
 
==variableget==
  
http://ip:3480/data_request?id=variableget&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status
+
http://ip_address:3480/data_request?id=variableget&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status
  
 
If you leave off the DeviceNum and serviceID, then this gets a top-level json tag called "Variable".
 
If you leave off the DeviceNum and serviceID, then this gets a top-level json tag called "Variable".
Line 122: Line 122:
 
Resets the Luup engine with any new configuration settings.
 
Resets the Luup engine with any new configuration settings.
  
Example: http://192.168.81.1:3480/data_request?id=reload
+
Example: http://ip_address:3480/data_request?id=reload
  
 
==alive==
 
==alive==
Line 132: Line 132:
 
Returns the '''device number''', '''UDN''' and '''device type''' of the first device that matches any or all the parameters passed on the URL: <tt>devtype</tt>, <tt>ip</tt>, <tt>devid</tt>, where <tt>devid</tt> is the ''altid'' of the device.  Or instead of <tt>devid</tt>, pass '''<tt>devnum</tt>''' and it will find the device with that number.
 
Returns the '''device number''', '''UDN''' and '''device type''' of the first device that matches any or all the parameters passed on the URL: <tt>devtype</tt>, <tt>ip</tt>, <tt>devid</tt>, where <tt>devid</tt> is the ''altid'' of the device.  Or instead of <tt>devid</tt>, pass '''<tt>devnum</tt>''' and it will find the device with that number.
  
Example: http://192.168.81.1:3480/data_request?id=finddevice&devid=6
+
Example: http://ip_address:3480/data_request?id=finddevice&devid=6
  
 
==resync==
 
==resync==
Line 156: Line 156:
 
For backward compatibility, it reports the current energy usage in a tab delimited format.
 
For backward compatibility, it reports the current energy usage in a tab delimited format.
  
Example: http://192.168.81.1:3480/data_request?id=live_energy_usage
+
Example: http://ip_address:3480/data_request?id=live_energy_usage
  
 
  '''Device #'''    '''Name'''              '''Room'''        '''Category'''    '''Watts'''
 
  '''Device #'''    '''Name'''              '''Room'''        '''Category'''    '''Watts'''
Line 163: Line 163:
 
  61          Porch Light      Outside      3          30
 
  61          Porch Light      Outside      3          30
  
To display only the watts variable : http://192.168.81.1:3480/data_request?id=variableget&DeviceNum=34&serviceId=urn:micasaverde-com:serviceId:EnergyMetering1&Variable=Watts
+
To display only the watts variable : http://ip_address:3480/data_request?id=variableget&DeviceNum=34&serviceId=urn:micasaverde-com:serviceId:EnergyMetering1&Variable=Watts
 
and you must specify the device id for the variable and the service id.
 
and you must specify the device id for the variable and the service id.
  
== request_image ==
+
==request_image==
  
'''<span style="color: rgb(255, 0, 0);">NOTE:</span>'''<span style="color: rgb(255, 0, 0);"> request_video is not implemented yet.
+
Returns an image from a camera. This fetches the image from the camera using the URL variable for the device. Pass arguments:
</span>
+
 
+
Returns an image from a camera. This fetches the image from the camera using the URL variable for the device. Pass arguments:  
+
  
 
  cam = the device id of the camera.  This is the only mandatory argument.
 
  cam = the device id of the camera.  This is the only mandatory argument.
  res = optional: a resolution, which gets appended to the variable.  So passing "low" means the image from the URL_low variable will be returned.  If it doesn't exist it reverts to the standard URL or DirectStreamingURL  
+
  res = optional: a resolution, which gets appended to the variable.  So passing "low" means the image from the URL_low variable will be returned.  If it doesn't exist it reverts to the standard URL or DirectStreamingURL
 
  timeout = optional: how long to wait for the image to be retrieved, or how long to retrieve video.  defaults to 10 seconds.
 
  timeout = optional: how long to wait for the image to be retrieved, or how long to retrieve video.  defaults to 10 seconds.
 
  url = optional: override the camera's default URL
 
  url = optional: override the camera's default URL
 
  ip = optional: override the camera's default ip
 
  ip = optional: override the camera's default ip
 
  user or pass = optional: override the camera's default username/password
 
  user or pass = optional: override the camera's default username/password
 +
 +
==archive_video==
 +
''* UI5+ only''
 +
 +
Archives a MJPEG video or a JPEG snapshot.
 +
 +
Parameters:
 +
* <tt>cam</tt>: the device # of the camera.
 +
* <tt>duration</tt>: the duration, in seconds, of the video. The default value is 60 seconds.
 +
* <tt>format</tt>: set it to '''1''' for snapshots. If this is missing or has any other value, the archive will be a MJPEG video.
 +
 +
 +
Examples:
 +
 +
* Archive a snapshot:
 +
http://ip_address:3480/data_request?id=archive_video&cam=8&format=1
 +
* Archive a 40 seconds video:
 +
http://ip_address:3480/data_request?id=archive_video&cam=3&duration=40
  
 
==jobstatus==
 
==jobstatus==
Line 196: Line 211:
 
* '''5''': Job waiting for callback. Used in special cases.
 
* '''5''': Job waiting for callback. Used in special cases.
 
* '''6''': Job requeue. If the job was aborted and needs to be started, use this special value.
 
* '''6''': Job requeue. If the job was aborted and needs to be started, use this special value.
* '''7''': Job in progress with pending data. This means the job is waiting for data, but can't take it now.  
+
* '''7''': Job in progress with pending data. This means the job is waiting for data, but can't take it now.
  
 
Examples:
 
Examples:
  
http://192.168.81.1:3480/data_request?id=jobstatus&job=13
+
http://ip_address:3480/data_request?id=jobstatus&job=13
  
http://192.168.81.1:3480/data_request?id=jobstatus&job=6&plugin=zwave
+
http://ip_address:3480/data_request?id=jobstatus&job=6&plugin=zwave
  
 
==invoke==
 
==invoke==
Line 209: Line 224:
  
 
Examples:
 
Examples:
* http://192.168.81.1:3480/data_request?id=invoke
+
* http://ip_address:3480/data_request?id=invoke
* http://192.168.81.1:3480/data_request?id=invoke&DeviceNum=6
+
* http://ip_address:3480/data_request?id=invoke&DeviceNum=6
* http://192.168.81.1:3480/data_request?id=invoke&UDN=uuid:4d494342-5342-5645-0002-000000000002
+
* http://ip_address:3480/data_request?id=invoke&UDN=uuid:4d494342-5342-5645-0002-000000000002
  
 
==relay==
 
==relay==
 +
''* UI5+ only''
  
 
This tells the system to setup a relay so that you can access a device on the home network from outside the home.  This is most commonly used to fetch streaming video from a camera, although it can actually be used for any IP device.  This takes either an 'ip' or 'device' argument.  If you pass a device, this is assumed to be a device ID, and the system will find the ip associated with that device.  Optionally pass a port argument for the port you want to be relayed.  Port 80 is assumed if none is specified.
 
This tells the system to setup a relay so that you can access a device on the home network from outside the home.  This is most commonly used to fetch streaming video from a camera, although it can actually be used for any IP device.  This takes either an 'ip' or 'device' argument.  If you pass a device, this is assumed to be a device ID, and the system will find the ip associated with that device.  Optionally pass a port argument for the port you want to be relayed.  Port 80 is assumed if none is specified.
Line 221: Line 237:
 
So, assume you have a NAS device on the home network with the ip 192.168.1.55 and the NAS runs a configuration web page on port 80.  You could access it by doing this:
 
So, assume you have a NAS device on the home network with the ip 192.168.1.55 and the NAS runs a configuration web page on port 80.  You could access it by doing this:
  
http://vera_ip:3480/data_request?id=relay&ip=192.168.1.55&port=80
+
http://ip_address:3480/data_request?id=relay&ip=192.168.1.55&port=80
  
 
and if the response is: "someserver:20202", then for 15 minutes, "http://someserver:20202" will be the NAS's configuration page.
 
and if the response is: "someserver:20202", then for 15 minutes, "http://someserver:20202" will be the NAS's configuration page.
Line 227: Line 243:
 
If you want to access a camera, device #5, then do this:
 
If you want to access a camera, device #5, then do this:
  
http://vera_ip:3480/data_request?id=relay&device=5
+
http://ip_address:3480/data_request?id=relay&device=5
  
 
and if the response is "someserver:20211" and if the 'DirectStreamURL' variable (or 'streaming' in sdata) is "video.mpeg", then for 15 minutes you can access the camera's video at: http://someserver:20211/video.mpeg
 
and if the response is "someserver:20211" and if the 'DirectStreamURL' variable (or 'streaming' in sdata) is "video.mpeg", then for 15 minutes you can access the camera's video at: http://someserver:20211/video.mpeg
Line 236: Line 252:
  
 
==update_plugin==
 
==update_plugin==
 +
''* UI5+ only''
  
 
Updates a plugin to the latest version.
 
Updates a plugin to the latest version.
  
Example: http://192.168.81.1:3480/data_request?id=update_plugin&Plugin=Plugin_ID
+
Example: http://ip_address:3480/data_request?id=update_plugin&Plugin=Plugin_ID
  
 
==What to do when the HTTP request string is too long==
 
==What to do when the HTTP request string is too long==
  
 
http://forum.micasaverde.com/index.php/topic,10170.msg69530.html#msg69530
 
http://forum.micasaverde.com/index.php/topic,10170.msg69530.html#msg69530

Revision as of 15:13, 13 December 2012

In addition to sending requests using standard UPnP, you can also do most things using a simple HTTP requests. Use the built-in URL data_request, and pass the following on the URL:

  • id the id of the request (prior to 15 Oct 2010 all requests had an lu_ in front, which is now optional),
  • output_format the format in which you want a response as json, xml or text.

Not all requests support all output_format options. Here is a list of requests:

Contents

user_data

Example: http://ip_address:3480/data_request?id=user_data&output_format=xml

This returns the configuration data for Vera, which is a list of all devices and the UPnP variables which are persisted between resets as well as rooms, names, and other data the user sets as part of the configuration.

status

This returns the current status for all devices including all the current UPnP variables and the status of any active jobs.


Examples:

Or for a specific device:

sdata

This is an abbreviated form of user_data and status (sdata = summary data). It allows a user interface that is only worried about control, and not detailed configuration, to get a summary of the data that would normally be presented to the user and to monitor the changes. See UI_Simple for a walkthrough.


Examples:

actions

device

Example: http://ip_address:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=3

Example: http://ip_address:3480/data_request?id=device&action=rename&device=5&name=Chandalier&room=Garage

Example: http://ip_address:3480/data_request?id=device&action=delete&device=5

This renames or deletes a device. Use action=rename or action=delete. For rename, you can optionally assign a room by either passing either the ID or the name.


---old--- This returns all the XML with all the UPNP device description documents. Use: http://ip_address:3480/data_request?id=device&output_format=xml&DeviceNum=x or &UDN=y to narrow it down. Then when you see the service URL's, like <SCPDURL>/luvd/S_HVAC_UserOperatingMode1.xml</SCPDURL>, you can view them with: http://ip_address:3480/luvd/S_HVAC_UserOperatingMode1.xml ---end old---

scene

Example: http://ip_address:3480/data_request?id=scene&action=record

Example: http://ip_address:3480/data_request?id=scene&action=pause&seconds=y

Example: http://ip_address:3480/data_request?id=scene&action=stoprecord

Example: http://ip_address:3480/data_request?id=scene&action=listrecord

Example: http://ip_address:3480/data_request?id=scene&action=deleterecord&number=x

Example: http://ip_address:3480/data_request?id=scene&action=saverecord&name=whatever&room=X

Example: http://ip_address:3480/data_request?id=scene&action=rename&scene=5&name=Chandalier&room=Garage

Example: http://ip_address:3480/data_request?id=scene&action=delete&scene=5

Example: http://ip_address:3480/data_request?id=scene&action=create&json=[valid json data]

Example: http://ip_address:3480/data_request?id=scene&action=list&scene=5

This creates, renames, or deletes a scene depending on the action.

Recording a scene means whatever actions come in after sending the 'record' will be saved into an internal buffer. listrecord shows what's recorded so far. pause adds a pause. deleterecord deletes some action in the internal buffer. When deleting, for number=x, use the same 'id' in listrecord. saverecord takes the internal buffer, the recorded macro, and saves it as an actual scene.

To create a scene by hand, rather than recording it, use 'create'. When using the 'create' command json must be valid JSON for a scene as documented in Scene_Syntax. The name, room and optional id (if you're overwriting an existing scene) are passed in the json, so nothing is on the command line except the json. Because the json data can be long it is recommended to send it as an http POST instead of GET with the data passed with the name "json"

list returns the JSON data for an existing scene.

room

Example: http://ip_address:3480/data_request?id=room&action=create&name=Kitchen

Example: http://ip_address:3480/data_request?id=room&action=rename&room=5&name=Garage

Example: http://ip_address:3480/data_request?id=room&action=delete&room=5

This creates, renames, or deletes a room depending on the action. To rename or delete a room you must pass the room id for the room=.

file

Returns the contents of a file in /etc/cmh or /etc/cmh-ludl. Has one parameter, parameters, which is the name of the file.

Example: http://ip_address:3480/data_request?id=file&parameters=D_BinaryLight1.xml

lua

action

Example: http://ip_address:3480/data_request?id=action&output_format=xml&DeviceNum=6&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=1

Sends a UPnP action.

To run a scene, you send the action 'RunScene' like this::

http://ip_address:3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=RunScene&SceneNum=<SceneNum>

variableset

http://ip_address:3480/data_request?id=variableset&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status&Value=1

If you leave off the DeviceNum and serviceID, then this sets a top-level json tag called "Variable" with the value.

variableget

http://ip_address:3480/data_request?id=variableget&DeviceNum=6&serviceId=urn:micasaverde-com:serviceId:DoorLock1&Variable=Status

If you leave off the DeviceNum and serviceID, then this gets a top-level json tag called "Variable".

reload

Resets the Luup engine with any new configuration settings.

Example: http://ip_address:3480/data_request?id=reload

alive

Return OK if the engine is running.

finddevice

Returns the device number, UDN and device type of the first device that matches any or all the parameters passed on the URL: devtype, ip, devid, where devid is the altid of the device. Or instead of devid, pass devnum and it will find the device with that number.

Example: http://ip_address:3480/data_request?id=finddevice&devid=6

resync

ReSync's all the devices, rooms, users, sections with event servers and returns OK

wget

Returns the contents of the URL you pass in the "url" argument. Optionally append "user" and "pass" arguments for http authentication, and "timeout" to specify the maximum time to wait in seconds.

iprequests

Returns the recent IP requests in order by most recent first, including information about devices in use and if the IP is blacklisted (ignored by the plug and play mechanism). Optionally append "oldest" to specify the oldest IP request in seconds.

blacklistip

Append "ip" to the URL, and optionally "remove=1" to add (or remove) the IP to the blacklist so plug and play IP devices won't be added.

Not implemented yet!

live_energy_usage

For backward compatibility, it reports the current energy usage in a tab delimited format.

Example: http://ip_address:3480/data_request?id=live_energy_usage

Device #    Name              Room         Category    Watts
59          Basement Light    Basement     3           20
60          Bedroom Light     1st Floor    3           0
61          Porch Light       Outside      3           30

To display only the watts variable : http://ip_address:3480/data_request?id=variableget&DeviceNum=34&serviceId=urn:micasaverde-com:serviceId:EnergyMetering1&Variable=Watts and you must specify the device id for the variable and the service id.

request_image

Returns an image from a camera. This fetches the image from the camera using the URL variable for the device. Pass arguments:

cam = the device id of the camera.  This is the only mandatory argument.
res = optional: a resolution, which gets appended to the variable.  So passing "low" means the image from the URL_low variable will be returned.  If it doesn't exist it reverts to the standard URL or DirectStreamingURL
timeout = optional: how long to wait for the image to be retrieved, or how long to retrieve video.  defaults to 10 seconds.
url = optional: override the camera's default URL
ip = optional: override the camera's default ip
user or pass = optional: override the camera's default username/password

archive_video

* UI5+ only

Archives a MJPEG video or a JPEG snapshot.

Parameters:

  • cam: the device # of the camera.
  • duration: the duration, in seconds, of the video. The default value is 60 seconds.
  • format: set it to 1 for snapshots. If this is missing or has any other value, the archive will be a MJPEG video.


Examples:

  • Archive a snapshot:

http://ip_address:3480/data_request?id=archive_video&cam=8&format=1

  • Archive a 40 seconds video:

http://ip_address:3480/data_request?id=archive_video&cam=3&duration=40

jobstatus

Returns the status of a job. The parameters are job, which is the job ID and optionally plugin, which is the plugin name. For a Z-Wave job the plugin parameter must be zwave.

If job is invalid the status returned is -1.

This is the list with all job statuses and their meaning:

  • -1: No job, i.e. job doesn't exist.
  • 0: Job waiting to start.
  • 1: Job in progress.
  • 2: Job error.
  • 3: Job aborted.
  • 4: Job done.
  • 5: Job waiting for callback. Used in special cases.
  • 6: Job requeue. If the job was aborted and needs to be started, use this special value.
  • 7: Job in progress with pending data. This means the job is waiting for data, but can't take it now.

Examples:

http://ip_address:3480/data_request?id=jobstatus&job=13

http://ip_address:3480/data_request?id=jobstatus&job=6&plugin=zwave

invoke

This request shows the list of devices and the actions they support through the UPnP services specified in their UPnP device description file. Only the actions with a star (*) preceding their name are implemented.

Examples:

relay

* UI5+ only

This tells the system to setup a relay so that you can access a device on the home network from outside the home. This is most commonly used to fetch streaming video from a camera, although it can actually be used for any IP device. This takes either an 'ip' or 'device' argument. If you pass a device, this is assumed to be a device ID, and the system will find the ip associated with that device. Optionally pass a port argument for the port you want to be relayed. Port 80 is assumed if none is specified.

This request will return a 'server:port' which you can use externally to access the designated device. The relay stays open for 15 minutes before closing, at which point you will need to open it again.

So, assume you have a NAS device on the home network with the ip 192.168.1.55 and the NAS runs a configuration web page on port 80. You could access it by doing this:

http://ip_address:3480/data_request?id=relay&ip=192.168.1.55&port=80

and if the response is: "someserver:20202", then for 15 minutes, "http://someserver:20202" will be the NAS's configuration page.

If you want to access a camera, device #5, then do this:

http://ip_address:3480/data_request?id=relay&device=5

and if the response is "someserver:20211" and if the 'DirectStreamURL' variable (or 'streaming' in sdata) is "video.mpeg", then for 15 minutes you can access the camera's video at: http://someserver:20211/video.mpeg

Note that if the device, the camera in this case, has http authentication, you will need to pass this too. So, if the user_data or sdata for the camera shows the user name is 'johndoe' and the password is 'john123', then you can view the video at: http://john:john123@someserver:20211/video.mpeg

IMPORTANT: For the 15 minutes while this relay is open, it will be open to anyone on the internet and public. Therefore, for security, you may want to add to the data_request the argument externalip=x where x is the routable, external IP, such as 70.182.172.111, of the device that will be accessing the port. This means that when the relay is open, a firewall will be set on the relay server so that incoming connections are only accepted from that ip address.

update_plugin

* UI5+ only

Updates a plugin to the latest version.

Example: http://ip_address:3480/data_request?id=update_plugin&Plugin=Plugin_ID

What to do when the HTTP request string is too long

http://forum.micasaverde.com/index.php/topic,10170.msg69530.html#msg69530

Personal tools