UI Notes
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.
Current state of devices
The current state of a device is presented as token in the 'state' field. These are set by Vera, do not modify them. Examples for a thermostat are: <HEAT_SET_POINT=21> <COOL_SET_POINT=21> <FAN=AUTO> <POWER=OFF>
POWER="ON" or "OFF"
LEVEL=For dimmable devices, a value from 0-100
HEAT_SET_POINT/COOL_SET_POINT=The current set point for heat/cool for a thermostat, always in celsius
MODE=For thermostats: "HEAT" or "COOL" or "AUTO"
MODE=For security sensors: "ARMED" or "UNARMED"
FAN=For thermostats: "ON" or "AUTO"
TEMP=Current temperature in celsius
TRIPPED=For sensors, "YES" or "NO" if the sensor is tripped
BRIGHTNESS=For light sensors, a value from 0-100
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/DEVICEDATA_Energy_Log_CONST 286: 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/DEVICEDATA_EK_AlertType_CONST 45: These are for sensors indicating if they are input/output, normally open/close, and what type of alert they fire. You should not need to modify these because the default values pulled from template_data.json, which are set when the device is created, should be correct.
DEVICEDATA_Wattage_CONST 285: This is how many watts the device uses at full power. The user should be allowed to edit this so the estimated energy usage is accurate.
Device specific notes:
Light switches/lamp & appliance modules/Sensors: There are no special settings. Just follow the general settings above.
Thermostats: Note the syntax of Wattage here: Watts Otherwise no special settings.
IP Cameras: There are special json tags for the IP address and MAC address. Store the username/password for http authentication in: DEVICEDATA_AuthUser_CONST 114/DEVICEDATA_AuthPassword_CONST 115 and the URL to retrieve a JPEG image in DEVICEDATA_Path_CONST 2. Store information about archiving images and association with lights/motion sensors in DEVICEDATA_sPK_Device_Relations_For_Creat_CONST 184,DEVICEDATA_Video_settings_CONST 89.
DEVICEDATA_sPK_Device_Relations_For_Creat_CONST 184 = comma separated list of associated lights, dash, comma separated list of associated sensors.
DEVICEDATA_Video_settings_CONST 89 = comma separated values: # of seconds to archive, # of minutes/seconds to take automatic picture as a # followed by m or s, # of days to keep archives, [1|0] for 'turn on lights when viewing camera', [1|0] for 'turn on lights when the sensors are tripped and armed', [1|0] for 'turn on lights when the sensors are tripped and not armed', [1|0] for 'turn on lights for automatic picture'. So, the following is data is stored for the following configuration:
"FK_DeviceData_184": "13,14,17-20"
"FK_DeviceData_89": "98,97m,96,1,1,0,0"
Archive a photo whenever the following sensors are tripped:
(20)
And after the sensor(s) are tripped archive the video for 98 seconds.
Which lights should be turned on when viewing this camera:
(13,14,17)
For archival purposes, take a picture from the camera every 97 minutes, and keep the pictures 96 days.
Turn on the lights:
[x] When I view the camera from the web or phone.
[x] When the sensor(s) above are tripped and they are armed
[ ] When the sensors above are tripped and they are *not* armed
[ ] When you take an automatic picture for the archive
Configuration parameters for the Z-Wave device
The Z-Wave device, the parent of all Z-Wave nodes, has configuration parameters as well:
DEVICEDATA_COM_Port_on_PC_CONST 37: The com port/linux device for the Z-Wave dongle.
DEVICEDATA_Polling_Settings_CONST 283: The default poll settings, comma separated: [0|1] polling enabled, seconds to wait after startup before polling, seconds of idle time on the network before doing a poll, how many seconds to wait between polling nodes, seconds to wait between polling each node.
So, "FK_DeviceData_283": "1,20,10,10,60" is displayed as:
[x] Poll nodes
Wait 20 seconds to start polling.
Only poll a node if the Z-Wave network is idle at least 10 seconds.
Poll a node every 10 seconds.
Unless specified otherwise, poll each node at most once every 60 seconds.
DEVICEDATA_Configuration_CONST 59: Firmware version of the dongle. Read only
DEVICEDATA_PortChannel_Number_CONST 12: House code and node id of the dongle. Read only.
DEVICEDATA_Capabilities_CONST 207: Read only status if the device is SUC/SIS and primary or not, such as: "Suc SIS:YES PRI:YES"
Creating scenes in the user_data.json
A scene is just a list of commands to send to various devices. The Scenes section of user_data contains the pre-defined scenes. For example: {
"scenes": {
"scene_10": {
"Description": "leave home",
"FK_Room": "5",
"commands_ids": [
1,
2,
3,
4,
5
],
"commands": {
"command_1": {
"Device_To": 5,
"FK_Command": "972",
"params": {
"FK_CommandParameter_2": 24,
"FK_CommandParameter_5": "ARMED"
}
},
"command_2": {
"Device_To": 14,
"FK_Command": "184",
"params": {
"FK_CommandParameter_76": 75
}
},
"command_3": {
"Device_To": 14,
"FK_Command": "193",
"Delay": 60
},
"command_4": {
"Device_To": 21,
"FK_Command": "280",
"params": {
"FK_CommandParameter_8": "C"
}
},
"command_5": {
"Device_To": 21,
"FK_Command": "278",
"params": {
"FK_CommandParameter_5": 20
}
}
}
}
}
}
This defines a scene called "leave home" which is in room. It sets a thermostat (device #21) to 'cool' mode (command #280) and to 20 degrees celsius (command #278). It also arms a motion detector (command #972). As explained below, ZWave motion detectors themselves don't have an arm/disarm command. It's just a flag which the security plugin keeps so that when a sensor is tripped, it knows if it's an "armed sensor tripped event" or a normal "sensor tripped event". So the command goes to device #5 (the security plugin), and the device id of the motion sensor (24) is a parameter to it. It also sets device #14 (a light) to 75% (command #184) and after 60 seconds turns it off (command #193). The list of device #'s is found in user_data Devices section. The command and parameters and how to use them are explained below.
To add this scene, you would submit the following JSON in the POST data for the user_data request. Note that if you do a POST with an existing scene ID, the entire scene is replaced. Changes are not merged. For example, if you want to add a timer to an existing scene, send the entire scene again, with command, and include the timer. We did this because it was difficult in the java script UI to keep track of all the changes and was easier to have the UI just re-send the whole scene each time. See: Data_Provider_Catalog_Plugin_Requests
{
"scenes": {
"scene_1000010": {
"Description": "leave home",
"FK_Room": "5",
"commands_ids": [
1,
2,
3,
4,
5
],
"commands": {
"command_1": {
"Device_To": 5,
"FK_Command": "972",
"params": {
"FK_CommandParameter_2": 24,
"FK_CommandParameter_5": "ARMED"
}
},
"command_2": {
"Device_To": 14,
"FK_Command": "184",
"params": {
"FK_CommandParameter_76": 75
}
},
"command_3": {
"Device_To": 14,
"FK_Command": "193",
"Delay": 60
},
"command_4": {
"Device_To": 21,
"FK_Command": "280",
"params": {
"FK_CommandParameter_8": "C"
}
},
"command_5": {
"Device_To": 21,
"FK_Command": "278",
"params": {
"FK_CommandParameter_5": 80
}
}
},
"json_action": "add"
}
}
}
Note the tag "json_action": "add" within the scene. This tells the data provider handler to add this scene. Also note that the scene id number is 1000010. The convention is that when adding new devices, scenes, rooms, sections or users you should use an id number > 1,000,000. When the data provider handler sees an id number >1m, it automatically changes it to be the next available id #. This is because all devices, scenes, rooms, sections and users need a unique id #. Since there could be multiple web ui's submitting user changes at once, you don't want the web ui to assign the id # as there may be a collision. If there were, the plugin would merge the data from the 2 post's. By using an id# > 1m, you are ensured there will be no conflicts as the id # will be changed when it's processed. Note that the same user_data you POST to with the new data, will also return the resulting user_data after the POST. So after POST'ing the data, you should parse and use the user_data that is returned, and discard any copy of the user_data you posted, as the id #'s may be different.
POST'ing the commands_ids is purely optional. The Vera back-end doesn't ever use any of the _ids parameters in the json file. They are there purely for the convenience of the web engine if it makes it easier to parse the json files.
List of commands and parameters to send to devices
The complete list of all commands and parameters is in the template_data json file explained here. There are over 1,000 commands in the full LinuxMCE command set. But the common ones used in Vera are:
#184 Set Level: Sets a device to a certain level. For dimmable lights this sets the level
Parameters: #76 Level: a number between 0 and 100
#192 On/#193 Off: Turns a device on or off. This is also used for unlock/lock door locks
Parameters: #76 Level: a number between 0 and 100
#278 Set Temperature: Sets a thermostat's set point to a given temperature
Parameters: #5 Value_To_Assign: The temperature in degrees celsius. The number may be preceded with a - or a + to decrease/increase the temperature relative to its current setting, and may be followed by an H or C to set only heat or cool set point. If H or C is not specified, both heat/cool set points will be set for those thermostats that support dual set points
#279 Set Fan: Sets the fan of a thermostat to always on or to automatic
Parameters: #8 On/Off: Set this value to 1 to put the thermostat is 'on' mode, and 0 to put it in auto mode.
#280 Set Heat/Cool: Sets the thermostat to heat/cool
Parameters: #8 On/Off: Set this value to H for heat mode, C for cool. To turn the thermostat off, send command #193 (off), and to put it in full auto mode, send command #192 (on)
#370 Execute Command Group: In the user_data, find the device with the template "FK_DeviceTemplate": "27" (General_Info_Plugin) and send it this command to execute a scene. By including this command within a scene, you can have one scene execute or embed another scene.
Parameters: #28 PK_CommandGroup: This is the id of the scene (ie the number following scene_).
Parameters: #9 Text: If you want to test a scene that you have not yet created, instead of passing the command group parameter above, you put send the raw string of commands in this format:
PK_Device,PK_DeviceGroup,PK_Command,Delay,CancelIfOther,IsTemporary,"PK_CommandParameter","Description"
where each command is separated with a new line (\n). In Vera's UI, when you execute a scene from the dashboard (ie a scene that's already saved), it passes the scene # in parameter #28. When the user clicks 'test' next to a scene in the scene editor, and you want to test a scene that you have not yet saved, it is sent as parameter #9. You can grep DCERouter.log for '^08' (ie lines starting with 08 are commands) after clicking 'test' to see the syntax.
#684 Zoom In/#685 Zoom Out/#200 Move Up/#201 Move Down/#202 Move Left/#203 Move Right: Send these commands to a camera for pan/tilt/zoom.
Parameters: None
#84 Get_Video_Frame: Send this command to a camera to retrieve the current image as a JPEG file:
Parameters: #19 Data: This is an output parameter that is returned, not an input parameter. It contains the actual image. The parameter type is 'Data', so it contains a block of binary data.
Parameters: #20 Format: This is the format of the data. Presently all the cameras return 'JPEG'.
#776 Reset (when sent to a ZWave node): When sent to a ZWave node (ie a child of the device ZWave interface), it resets that node and causes it to be reconfigured. This is what's sent with Vera's "configure node right now" button. A configuration job is immediately added to the queue.
Parameters: none
#776 Reset (when sent to the ZWave interface): When sent to the parent ZWave device, the interface which is often device #9, it resets the ZWave pairing in dongle. This is the only way to restore the black dongle to a clean state. If you do a hardware reset of Vera, without sending this command, the pairing's will remain because they're stored in the dongle itself. This command is sent from Vera's Devices, ZWave options, 'reset zwave network' button explained here: ZWave_Options.
Parameters: #51 Arguments: This parameter can be: SUC or SIS (ie send either of those 3 character strings, or leave the parameter blank). The default is to send it with SIS. This is a ZWave term, meaning the dongle will report new nodes to slave controllers.
#967 Add Node: When sent to the parent ZWave device, the interface which is often device #9, it causes the to go into 'pairing' mode to add new devices. See ZWave_Options
Parameters: #39 Options: This parameter can be the single character H to use high power inclusion. Or it can be the word CANCEL to stop any current add/remove going on.
Parameters: #48 Value: If empty or set to 1, any type of node can be added. You can also send on the of the Zensys define's to restrict what type of node is added: 2=node controller, 3=node slave, 4=node existing, 5=node stop, 6=node stop failed
Parameters: #182 Timeout: Number of seconds to timeout. If not specified default is 60 seconds. This is how long to wait for the new node.
Parameters: #259 Multiple: If true (ie 1) then multiple devices can be added and the dongle will stay in include mode until the timeout is reached. Otherwise, the dongle will only add 1 device and exist add mode.
#968 Remove Node: When sent to the parent ZWave device, the interface which is often device #9, it causes the to go into 'reset' mode to remove devices. See ZWave_Options
Parameters: #39 Options: This parameter can be the single character H to use high power inclusion.
Parameters: #48 Value: If empty or set to 1, any type of node can be removed. You can also send on the of the Zensys define's to restrict what type of node is added: 2=node controller, 3=node slave, 4=node existing, 5=node stop, 6=node stop failed
Parameters: #182 Timeout: Number of seconds to timeout. If not specified default is 60 seconds. This is how long to wait for the new node.
Parameters: #259 Multiple: If true (ie 1) then multiple devices can be added and the dongle will stay in remove mode until the timeout is reached. Otherwise, the dongle will only remove 1 device and exist remove mode.
#972 Set Sensor State: In the user_data, find the device with the template "FK_DeviceTemplate": "33" (Security_Plugin) and send it this command to change the arm/unarmed state of a sensor. Z-Wave doesn't have the concept of armed/unarmed sensors. But the security plugin keeps a flag for all sensors so when a sensor is tripped, it can fire the normal 'sensor tripped' only, or also a 'armed sensor is tripped' event.
Parameters: #2 PK_Device: This is the device id of the sensors
Parameters: #5 Value To Assign: Can be either: ARMED or UNARMED
#974 Set PIN: For door locks, this sets a user code or pin.
Parameters: #17 PK_Users: This is user code to set
Parameters: #99 Password: This is the pin code. Leave it blank to clear the pin code for the given user.
Timer
If you want to have a scene executed automatically at a certain time, add a Timer. As explained above, you must re-send the whole scene with the timer. Add a JSON block like this to a scene to make it a timer:
"Timer": {
"PK_Timer_1": {
"Description": "T_on30m",
"Type": "1",
"Enabled": "1",
"Criteria": {
"param_1": {
"PK_CriteriaParmList": 11,
"Operator": 1,
"Parm": "",
"Value": "30m"
}
}
}
}
The Timer ID # (1 in this case) can be whatever you want, as well as the description. If Enabled is set to "0", the timer will not execute. Type can be: INTERVAL_EVENT=1 (ie does something every x minutes/seconds), DAY_OF_WEEK=2, DAY_OF_MONTH=3, ABSOLUTE_TIME=4. In all cases, the parameters for the type are specified in the Criteria section. The operator is OPERATOR_EQUALS=1, OPERATOR_NOTEQUALS=2, OPERATOR_GREATERTHAN=3, OPERATOR_LESSTHAN=4, OPERATOR_CONTAINS=5.
For interval timers, leave parm blank, use "PK_CriteriaParmList": 11 (per LinuxMCE this is: #define CRITERIAPARMLIST_Time_of_day_CONST 11), and set the value to a number followed by m or h (minutes/hours). The above is a timer that will go off every 30 minutes.
For Day of Week timers, set CRITERIAPARMLIST_Day_Of_Week_CONST 17 with a comma separated list of days of week (ie 1=Sunday), and CRITERIAPARMLIST_Time_of_day_CONST 11 is the time of day. Multiple times are comma separated. Times can be in 12 hour (with an optional am/pm) or 24 hour. All the following are acceptable ways of saying 3:15pm: 3:15pm 3:15 p.m., 3:15p, 15:15. Generally we use 24 hour time since it's simpler. Here is a day of week timer that goes off every day at 6pm and 8pm:
"Criteria": {
"param_1": {
"PK_CriteriaParmList": 17,
"Operator": 1,
"Parm": "",
"Value": "1,2,3,4,5,6,7"
},
"param_2": {
"PK_CriteriaParmList": 11,
"Operator": 1,
"Parm": "",
"Value": "6:00pm ,20:00"
}
}
For absolute timers, set "PK_CriteriaParmList": 19 (CRITERIAPARMLIST_Specific_Date_CONST 19) and set the Value to the actual date/time.
switch( PK_CriteriaParmList ) { case CRITERIAPARMLIST_Day_Of_Week_CONST: m_sDaysOfWeek=sValue; case CRITERIAPARMLIST_Time_of_day_CONST: m_sTimes=StringUtils::ToUpper(sValue); case CRITERIAPARMLIST_Day_Of_Month_CONST: m_sDaysOfMonth=sValue; case CRITERIAPARMLIST_Specific_Date_CONST: m_tTime=StringUtils::SQLDateTime(sValue); };
"Criteria": {
"param_1": {
"PK_CriteriaParmList": 17,
"Operator": 1,
"Parm": "",
"Value": "1,2,3,4,5,6,7"
},
"param_2": {
"PK_CriteriaParmList": 11,
"Operator": 1,
"Parm": "",
"Value": "6:00pm ,20:00"
}
}
