UI Notes

Revision as of 21:59, 4 February 2009

Here is some general information about getting information to display in a user interface:

zwave_status is the status of all the zwave devices. It's explained here: ZWave_Status. This is what you poll regularly to find the state of the device (on, off, cool, heat, 73 degrees, etc.), as well as if it's been configured, and if it's got pending jobs (ie it's being turned on/off/etc.).

The unassigned devices and automation devices in the user_data json request are just counters. You can probably ignore them. Automation devices is just the count of all the devices that are children of 'zwave' (ie the count of your light switches, thermostats, etc.). Unassigned devices is the count of devices that haven't yet been assigned a room (ie FK_Room=0). It's your responsibility, in the UI, to be sure that every device which does *NOT* have FK_DeviceData_284": "1" is assigned to a room. You don't have to, actually; the devices work fine if they're not in a room. It's just a convention in our user paradigm that all devices have to be put in rooms as a way of cataloging. And our web developer said that since javascript is slow, rather than him parsing the whole device tree in order to figure out if there are any devices he needs to ask the user what room it's in, he asked us to put a counter in the json (UnassignedDevices). If it's 0, he doesn't need to display the popup "Tell me what rooms these new devices are in". If it's >0, then he goes ahead and parses the device tree to figure out what devices are already assigned to a room and displays the popup for those that are not yet in a room.

He also wanted a 'automation devices' counter, again, so he doesn't need to parse the json tree unnecessarily. If the counter is 0, then the user has no zwave devices and he doesn't bother rendering the devices tab.

The counters and data in the user_data are the 'master database' of all the devices in the home and their parameters. The database is updated whenever the list of devices changes, or the user makes changes to the configuration.

The zwave_status shows the current, real-time status of all the devices (the same devices as the database, of course). zwave_status is contains data that is not stored in the master device database, like what jobs are running at any given moment, what the temperature is on teh thermostat at this moment in time, etc.

The way our UI works is there's a background thread that polls user_data every 60 seconds or so. Each time it polls user_data, it passes in the DataVersion from the last user_data it got. This way if there no changes, rather than returning an identical json tree for you to parse all over again, you just get back an empty tree meaning "that DataVersion is still current". When the user_data changes, the ui needs to update all the devices/trees/etc. because that means stuff has changed.

Separately, there's another background poll of 'zwave_status' to get the realtime info on the device. This is used to determine which action button to highlight (on/off/etc.), what color code to use for the config cog wheel, what job icons to display, and so on. The way we implemented it is that when the user does something in the UI, we start polling zwave_status every 2 seconds. This is because things are changing quickly (ie the job may be succeeding/failing/etc.). Then after 15 seconds, the polling is reduced to once every 15 seconds. Then after 1 minute, the polling is reduced to 1 minute intervals. This way, when the UI is idle, and the user turns off a light, you won't see the change immediately in the UI because it can be 1 minute before the next zwave_status poll. But, you're not generating constant network traffic to keep polling the devices over and over again when there's nothing going on.

If you use the binary socket layer, you don't need to poll since you can register to receive events when things change. But for web based ui's and engines like javascript, implementing raw socket transfers isn't as easy as simple http get's, so it just uses polling of the http gets.