UI Notes

Revision as of 18:32, 9 February 2009

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

Getting information from the json files and zwave_status

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.

Saving configuration settings

All the configuration data is stored in the user_data json file. The UI should allow the user to modify this data, set configuration parameters, and so on. Refer to the user_data request on Data_Provider_Catalog_Plugin_Requests for instructions on how to submit the user's changes to the json files. You can add your own tags to the JSON file to store your own information about devices. Vera will simply ignore json tags that it doesn't recognize. Vera looks for device configuration options in the "DeviceData" section for each device. Each configuration parameter has a number, such as: "FK_DeviceData_12": "6". Next is a list of configuration settings the UI should prompt the user for.

Configuration parameters for devices

Here are configuration settings the UI should prompt the user for and store in the "DeviceData" section. The ID numbers come from the LinuxMCE database:

Global

DEVICEDATA_Manage_Associations_CONST 300: Some Z-Wave devices report information about their state (ie fire events), such as motion sensors, remote controls which fire 'button pressed' events, and so on. Generally you tell the device where to send the events by assigning them 'associations'. For example, a motion sensor can be associated with a light switch and it will turn the light on/off automatically, or it can be associated with Vera so Vera gets 'sensor tripped' events. If this is the sort of device that Vera would normally want to set associations for, Vera adds this configuration parameter to the device, with an empty value. If the UI sees this parameter in "DeviceData", display a check box that says something like "Allow Vera to manage associations" and, if checked, store a 1, otherwise a 0.

DEVICEDATA_Scenes_As_Events_CONST 298: Normally ZWave handheld remote controls work with light switches only, and you can't receive events in Vera to allow them to execute Vera's scenes, which can do anything. If this is a handheld remote control that Vera can "trick" into sending scene commands to Vera, which Vera can in turn translate into events, Vera will add this configuration parameter to the device, with an empty value. If the UI sees this parameter in "DeviceData", display a check box that says something like "Treat Scenes as events" and, if checked, store a 1, otherwise a 0. See: ZWave_Add_Controller method #2

DEVICEDATA_Wakeup_Interval_CONST 299: If this is a battery operated device, that is not a FLiRS (see Zensys definition), it is normally 'sleeping' and cannot be communicated with except when it periodically wakes up and broadcasts a wakeup message. If Vera detects this type of device, Vera will add this configuration parameter to the device, with an empty value. If the UI sees this parameter in "DeviceData", prompt the user for the wakeup interval and store the value, as # of seconds, in this parameter.

DEVICEDATA_Manufacturer_Desc_CONST 294/DEVICEDATA_Model_Desc_CONST 295: This is a read-only setting with the name of the manufacturer/name of the model of the device, if known. Do not overwrite these values.

DEVICEDATA_Battery_Level_CONST 292: This is a read-only setting with the percentage of battery life left, from 0-100.

DEVICEDATA_Battery_Alarm_CONST 293: If DEVICEDATA_Battery_Level_CONST 292 is specified, you can display an input box asking the user for the minimum battery life before firing an event (0-99) and store it in this setting. When the battery level drops below this level an event will be fire, which can be attached to a scene to notify a user.

DEVICEDATA_Capabilities_CONST 207: This may be of interest to more advanced users. It has the device classes followed by a | and the supported command classes. An S at the end means its a 'secure' command class.

DEVICEDATA_PortChannel_Number_CONST 12: This is read-only, and it's the ZWave Node id.

DEVICEDATA_Multi_Channel_End_Point_CONST 296/DEVICEDATA_Multi_Channel_Capabilities_CONST 297/#define DEVICEDATA_Model_CONST 233/DEVICEDATA_Configuration_CONST 59/DEVICEDATA_Update_Name_CONST 41/DEVICEDATA_Only_One_Per_PC_CONST 162: Internal use only. Do not modify or present to the user.

DEVICEDATA_LastUpdate_CONST 234: This is the unix time stamp indicating when the device was successfully configured. Vera sets this when configuration is done. If this is not empty or 0, Vera will not attempt to configure the device. Whenever the user makes any change to a device, such as changing the settings in the UI, the UI must reset this to 0 when saving so Vera will re-configurate the device.

DEVICEDATA_Polling_Settings_CONST 283: This is the maximum frequency, in seconds, to poll the device. If set to empty, the default values will be used. 0 means the device will not be pulled. 60, for example, means poll the device at most once per 60 seconds.

DEVICEDATA_PK_FloorplanObjectType_CONST 11: Vera has no use for this value, but it is traditionally used to indicate which type of icon the user wants to see this device represented with on the floorplan. It is made available to any controllers.

DEVICEDATA_InputOrOutput_CONST 18:

DEVICEDATA_Default_State_CONST 19:

#define DEVICEDATA_EK_AlertType_CONST 45