UI Notes - Revision history

Andreimios: /* lu_status */

2015-07-03T12:27:33Z

‎lu_status

Andreimios: /* user_data */

2015-07-03T12:26:33Z

‎user_data

Andreimios at 12:07, 4 June 2015

2015-06-04T12:07:37Z

Andreimios: /* lu_status */

2015-06-04T12:06:17Z

‎lu_status

Andreimios: /* Tracking status changes */

2015-06-04T12:04:24Z

‎Tracking status changes

Mcvflorin at 08:28, 23 August 2013

2013-08-23T08:28:12Z

A-lurker at 23:20, 16 June 2013

2013-06-16T23:20:49Z

A-lurker at 23:10, 16 June 2013

2013-06-16T23:10:51Z

Show changes

Mcvflorin: /* Accessing Vera remotely through the mios server */

2012-06-08T12:34:10Z

‎Accessing Vera remotely through the mios server

Micasaverde: /* Categories and device types */

2011-07-04T18:55:54Z

‎Categories and device types

@@ Line 121: / Line 121: @@
 ==lu_status==
-The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using lu_status request.
+The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using status request.
 Call lu_status request like so:
-:http://[ip address]:3480/data_request?id=lu_status
+:http://[ip address]:3480/data_request?id=status
-:http://[ip address]:3480/data_request?id=lu_status&output_format=xml
+:http://[ip address]:3480/data_request?id=status&output_format=xml
-:http://[ip address]:3480/data_request?id=lu_status&DataVersion=315587159
+:http://[ip address]:3480/data_request?id=status&DataVersion=315587159

@@ Line 83: / Line 83: @@
 ==user_data==
-The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system.  You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.).  You'll also want the list of scenes to present the user.  To fetch the current user_data from Vera use the user_data2 request, like this:
+The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system.  You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.).  You'll also want the list of scenes to present the user.  To fetch the current user_data from Vera use the user_data request, like this:
 Returns JSON (preferred native format):
-http://[ip address]:3480/data_request?id=user_data2
+http://[ip address]:3480/data_request?id=user_data
 Returns XML:
-http://[ip address]:3480/data_request?id=user_data2&output_format=xml
+http://[ip address]:3480/data_request?id=user_data&output_format=xml
 You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':
-http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159
+http://[ip address]:3480/data_request?id=user_data&DataVersion=315587159
 The user_data contains the state for all the devices.  For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)
@@ Line 118: / Line 117: @@
+      ]
+}
 ==lu_status==

@@ Line 78: / Line 78: @@
 '''6)''' Periodically poll the system with '''lu_status''' (explained below), like this:
-http://ipaddress:3480/data_request?id=lu_status2&amp;output_format=json
+http://ipaddress:3480/data_request?id=lu_status&amp;output_format=json
 That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.
 ==user_data==
-NOTE: On UI3 builds, user_data2 and user_data are the same, and so is lu_status2 and lu_status. However, on UI2 builds, user_data and lu_status have been deprecated, and you should user_data2 and lu_status2. Therefore, it's best to simply always use user_data2 instead of user_data, and lu_status2 instead of lu_status.
+NOTE: On UI3 builds, user_data2 and user_data are the same, and so is lu_status and lu_status. However, on UI2 builds, user_data and lu_status have been deprecated, and you should user_data2 and lu_status. Therefore, it's best to simply always use user_data2 instead of user_data, and lu_status instead of lu_status.
 The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system.  You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.).  You'll also want the list of scenes to present the user.  To fetch the current user_data from Vera use the user_data2 request, like this:
@@ Line 214: / Line 214: @@
       while(true)
+      {
-          newdata = FetchAndParse("lu_status2&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);
+          newdata = FetchAndParse("lu_status&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);
           if( newdata.IsEmpty()==false && newdata.isError()==false )
              break;  // If we got data, continue on and process it

@@ Line 124: / Line 124: @@
 Call lu_status request like so:
-:http://[ip address]:3480/data_request?id=lu_status2
+:http://[ip address]:3480/data_request?id=lu_status
-:http://[ip address]:3480/data_request?id=lu_status2&output_format=xml
+:http://[ip address]:3480/data_request?id=lu_status&output_format=xml
-:http://[ip address]:3480/data_request?id=lu_status2&DataVersion=315587159
+:http://[ip address]:3480/data_request?id=lu_status&DataVersion=315587159
@@ Line 143: / Line 143: @@
 ===Controlling the poll timing===
-You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does.  This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately.  You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds.  This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status2 calls returning non-stop consuming all the resources on both the Vera and the UI.
+You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does.  This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately.  You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds.  This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status calls returning non-stop consuming all the resources on both the Vera and the UI.
 ===Startup status===
@@ Line 161: / Line 161: @@
 Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.
-Note that lu_status2 also returns UserData_DataVersion, which is the dataversion from user_data.  That way you don't need to poll user_data in parallel.  Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.
+Note that lu_status also returns UserData_DataVersion, which is the dataversion from user_data.  That way you don't need to poll user_data in parallel.  Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.
 Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.

@@ Line 140: / Line 140: @@
 If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device.  Note that most of the UPnP variables do not ever change.  For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on.  There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified.  If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started.  So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1.  Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion.  Regardless, you will also get the current state of jobs and system initialization.
-On subsequent calls to lu_status2, you should also pass back in the LoadTime which you received on the prior call.
+On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.
 ===Controlling the poll timing===

@@ Line 22: / Line 22: @@
 == Finding Vera on the local network  ==
-You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''http://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.
+You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.
-Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''http://sta1.mios.com/locator_json.php?username=xxx'''.
+Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.
 == The HTTP interface  ==

@@ Line 89: / Line 89: @@
 Returns JSON (preferred native format):
-:http://[ip address]:3480/data_request?id=user_data2
+http://[ip address]:3480/data_request?id=user_data2
 Returns XML:
-:http://[ip address]:3480/data_request?id=user_data2&output_format=xml
+http://[ip address]:3480/data_request?id=user_data2&output_format=xml
 You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':
-:http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159
+http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159
 The user_data contains the state for all the devices.  For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)
@@ Line 184: / Line 184: @@
 The id is the job id number.  When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number.  All pending jobs for a device are shown by their id number.  The name is just an internal name for the job.  Icon is an optional keyword to indicate what sort of icon should be shown to the user.  For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user.  If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light.  Comments is notes about the job, if any.  This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know.  The status indicates the current state of the job, as shown:
-			job_None=-1,  // no icon
+*job_None=-1,  // no icon
-			job_WaitingToStart=0,  // gray icon
+*job_WaitingToStart=0,  // gray icon
-			job_InProgress=1,  // blue icon
+*job_InProgress=1,  // blue icon
-			job_Error=2,  // red icon
+*job_Error=2,  // red icon
-			job_Aborted=3,  // red icon
+*job_Aborted=3,  // red icon
-			job_Done=4,  // green icon
+*job_Done=4,  // green icon
-			job_WaitingForCallback=5  // blue icon - Special case used in certain derived classes
+*job_WaitingForCallback=5  // blue icon - Special case used in certain derived classes
 If the status is 0, this means the job is queued but hasn't started.  If it's 1 or 5 the job is being executed right now.  Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device.  Status codes 2, 3 and 4 mean the job has finished.  4 means the job went ok, and both 2 and 3 mean it failed.  Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device.  In both cases this is usually presented the user the same way, as a failure.
@@ Line 203: / Line 203: @@
   variable int DataVersion_lustatus=0
-  variable int LoadTime=0
+ variable int LoadTime=0
-  variable int DataVersion_userdata=0
+ variable int DataVersion_userdata=0
 :START

@@ Line 48: / Line 48: @@
 == Accessing Vera remotely through the mios server ==
-Native UPnP only works on a local area home network, and cannot be used over the Internet.  The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI.  Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax.  You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 10266).  For example, the above user_data is the syntax for local access on a home network.  To retrieve the same URL over the internet with mios use:
+Native UPnP only works on a local area home network, and cannot be used over the Internet.  The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI.  Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax.  You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345).  For example, the above user_data is the syntax for local access on a home network.  To retrieve the same URL over the internet with mios use:
-https://fwd2.mios.com/demovera/myvera123/10266/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)
+https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)
 assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account.  Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.

@@ Line 179: / Line 179: @@
 == Categories and device types ==
-The following values are used in user_data to determine the types of devices.  In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:
+The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]].  In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:
-−
-  // Device Types
-−
-  #define DEVICETYPE_HOME_AUTO_GATEWAY	"urn:schemas-micasaverde-com:device:HomeAutomationGateway:1"
-  #define DEVICETYPE_BINARY_LIGHT			"urn:schemas-upnp-org:device:BinaryLight:1"
-  #define DEVICETYPE_DIMMABLE_LIGHT		"urn:schemas-upnp-org:device:DimmableLight:1"
-  #define DEVICETYPE_THERMOSTAT			"urn:schemas-upnp-org:device:HVAC_ZoneThermostat:1"
-  #define DEVICETYPE_HUMIDITY_SENSOR		"urn:schemas-micasaverde-com:device:HumiditySensor:1"
-  #define DEVICETYPE_MULTI_IO				"urn:schemas-micasaverde-com:device:MultiIO:1"
-  #define DEVICETYPE_DOOR_LOCK			"urn:schemas-micasaverde-com:device:DoorLock:1"
-  #define DEVICETYPE_DOOR_SENSOR			"urn:schemas-micasaverde-com:device:DoorSensor:1"
-  #define DEVICETYPE_ZWAVE_NETWORK		"urn:schemas-micasaverde-com:device:ZWaveNetwork:1"
-  #define DEVICETYPE_INSTEON_NETWORK		"urn:schemas-micasaverde-com:device:InsteonNetwork:1"
-  #define DEVICETYPE_USB_UIRT				"urn:schemas-micasaverde-com:device:USBUIRT:1"
-  #define DEVICETYPE_TEMPERATURE_SENSOR	"urn:schemas-micasaverde-com:device:TemperatureSensor:1"
-  #define DEVICETYPE_POWER_METER			"urn:schemas-micasaverde-com:device:PowerMeter:1"
-  #define DEVICETYPE_MOTION_SENSOR		"urn:schemas-micasaverde-com:device:MotionSensor:1"
-  #define DEVICETYPE_LIGHT_SENSOR			"urn:schemas-micasaverde-com:device:LightSensor:1"
-  #define DEVICETYPE_IR_TRANSMITTER		"urn:schemas-micasaverde-com:device:IrTransmitter:1"
-  #define DEVICETYPE_WINDOW_COVERING		"urn:schemas-micasaverde-com:device:WindowCovering:1"
-  #define DEVICETYPE_GENERIC_IO			"urn:schemas-micasaverde-com:device:GenericIO:1"
-  #define DEVICETYPE_REMOTE_CONTROL		"urn:schemas-micasaverde-com:device:RemoteControl:1"
-  #define DEVICETYPE_COMBO_DEVICE			"urn:schemas-micasaverde-com:device:ComboDevice:1"
-  #define DEVICETYPE_CAMERA				"urn:schemas-upnp-org:device:DigitalSecurityCamera:1"
-  #define DEVICETYPE_SERIALPORT			"urn:micasaverde-org:device:SerialPort:1"
-  #define DEVICETYPE_SCENE_CONTROLLER		"urn:schemas-micasaverde-com:device:SceneController:1"
-  #define DEVICETYPE_ENERGY_CALCULATOR	"urn:schemas-micasaverde-com:device:EnergyCalculator:1"
-−
-  // IR Device Types
-−
-  #define DEVICETYPE_TV					"urn:schemas-micasaverde-com:device:tv:1"
-  #define DEVICETYPE_CABLE				"urn:schemas-micasaverde-com:device:cable:1"
-  #define DEVICETYPE_SATELLITE			"urn:schemas-micasaverde-com:device:satellite:1"
-  #define DEVICETYPE_VIDEO_ACCESSORY		"urn:schemas-micasaverde-com:device:videoaccessory:1"
-  #define DEVICETYPE_VCR_DVR				"urn:schemas-micasaverde-com:device:vcrdvd:1"
-  #define DEVICETYPE_DVD_BLURAY			"urn:schemas-micasaverde-com:device:dvdbluray:1"
-  #define DEVICETYPE_RECEIVER				"urn:schemas-micasaverde-com:device:receiver:1"
-  #define DEVICETYPE_AMP					"urn:schemas-micasaverde-com:device:amp:1"
-  #define DEVICETYPE_CD					"urn:schemas-micasaverde-com:device:cd:1"
-  #define DEVICETYPE_MISC_HOME_CONTROL	"urn:schemas-micasaverde-com:device:mischomecontrol:1"
-  #define DEVICETYPE_AV_MISC				"urn:schemas-micasaverde-com:device:avmisc:1"
-  #define DEVICETYPE_VIRTUAL_DEVICE		"urn:schemas-micasaverde-com:device:VirtualDevice:1"
-−
-  // Device Categories
-−
-  #define DEVICE_CATEGORY_INTERFACE		1
-  #define DEVICE_CATEGORY_DIMMABLE_LIGHT         2
-  #define DEVICE_CATEGORY_SWITCH                 3
-  #define DEVICE_CATEGORY_SECURITY_SENSOR	4
-  #define DEVICE_CATEGORY_HVAC			5
-  #define DEVICE_CATEGORY_CAMERA                 6
-  #define DEVICE_CATEGORY_DOOR_LOCK		7
-  #define DEVICE_CATEGORY_WINDOW_COV		8
-  #define DEVICE_CATEGORY_REMOTE_CONTROL         9
-  #define DEVICE_CATEGORY_IR_TX			10
-  #define DEVICE_CATEGORY_GENERIC_IO		11
-  #define DEVICE_CATEGORY_GENERIC_SENSOR         12
-  #define DEVICE_CATEGORY_SERIAL_PORT		13
-  #define DEVICE_CATEGORY_SCENE_CONTROLLER       14
-  #define DEVICE_CATEGORY_AV			15
-  #define DEVICE_CATEGORY_HUMIDITY		16
-  #define DEVICE_CATEGORY_TEMPERATURE		17
-  #define DEVICE_CATEGORY_LIGHT			18
-  #define DEVICE_CATEGORY_ZWAVE_INT		19
-  #define DEVICE_CATEGORY_INSTEON_INT		20
-  #define DEVICE_CATEGORY_POWER_METER		21
-−
 == pseudo-code for a UI ==