Version 21 (modified by gengen, 7 years ago) (diff)

--

GenGeneric? Scene Controller

EvolveLCD1_big.png

This is a Vera plug-in that supports several different Z-Wave scene controllers.

The Plug-in is designed to eak out as much functionality from these devices as possible but it alwo does this with as much common code as practical.

The Evolve LCD1 and Nexia One-Touch, especially, are similar in appearance as they both have the same programmable LCD screen and 5 button arrangement. They also respond to some of the same Z-Wave command-classes. However the implementation details are quite different. The plug-in exploits these similarities and separates device-specific code into three separate objects - one deditcated to each device.

The Vera plug-in API is not very friendly to new Z-Wave devices which are not fully supported by Vera Controls. That said, this plug-in has overcome these hurdles using several novel techniques

Peer Devices

Vera Z-Wave devices are child devices of the Z-Wave network scene controller. Unfortunately, they do not receive action events from the Vera GUI as do non-Z-Wave devices. For this reason, the Plug-In makes the Z-Wave device invisible but creates a new peer device which has no device parent. The device that you actually see in the Vera Web GUI is the peer device, but some of the advanced control panel pages link directly to the Z-Wave device. The Z-Wave device is linke to its peer using the "PeerID" variable. The Peer device is linked to the Z-Wave device using the AltID variable. If you exclude the Z-Wave devine from your network, the peer device will aso be automatically removed. If you add a new recognized device to your network, the plug-in will automatically "adopt" the device by making it invisible and creating a peer.

The Z-Wave Interceptor (Zwint)

Although Vera includes a "SendData?" action which is crucial for sending arbitrary Z-Wave commands to various devices, there is no easy way to receive responses from external devices. The Z-Wave interceptior (Zwint for short) solves this problem by intercepting all data going over the Z-Wave serial protocol between Vera's main controller chip and its Z-Wave module. Zwint is a Lua plug-in written in C. Once installed, it normally passes through all data going in either direction but it can monitor (Z-Wave to main SOC) or intercept (main SOC to Z-Wave) any Z-Wave commands. Monitored/interceted commands can be sent as Vera luup requests over the internal HTTP: interface. A monitored command can either be forwarded to the LuaUPnP engine either modifified or unmodified or it can be immediately replied to and thus LuaUPnP will not see that command. However the event can still be received by the plug-in as a Luup request. Similarly, commands from LuaUPnP can be intercepted and forwarded (modified or unmodified) or responded to immedediately. As such, it is possible to fix inappropriate LuaUPnP behavior for specific devices.

Interception is used to prevent the battery-operated Nexia One-Touch from going to sleep when it wakes up but LuaUPnP tries to send a No_More_Information command. If the plug-in has information to send to the Nexia One-Touch (for example, to change the screen display), it will wait until it wakes up, intercept LuaUPnP's No_More_Information command, send its own commands and then send the No_More_Information command allowing the device to go back to sleep.

Zwint accepts Monitor and Intercept objects from the Lua code. Each object has a "trigger" regular expression which is applied to the hexified Z-Wave command. You can use all of the Linux C Library's extended regular expression features to parse the Z-Wave command and extract inportant information. Any (captures) are passed as a luup action with parameter names C1 through C9. These captures can also be used in a replacement hex string using \1 through \9. The replacement string is converted back into binary with XX replaced by the Z-Wave checksum and sent in the appropriate direction. The XX also marks the end of a Z-Wave command before a response is expected. The actual response string may contain several such commands (typically 2 or 3) concatenated with the internal responses (typically ACK) ignored.

Z-Wave messages may be duplicated in a mesh network. The same message may be received several times. Deciding which message is original and which is a duplicate is actually fairly tricky and specific to each message. A Lua function, CheckDups? centralizes the common parts of duplicate detection but also includes parameters which can be used to customize this behavior.

There are many examples in the code of monitors and intercepts which are well commented. You need a deep understanding of the Z-Wave protocol in order to effectively use Zwint, but it has proven to be extremely powerful not only for supporting device-specific features but also for fixing bugs or misbehaviors in LuaUPnP.

The GenGeneric? Scene Controller installer and Uninstaller

UI5 and UI7 use completely different methods to detect specific Z-Wave devices and assign them differenct device types, etc. UI5 using an XML file whereas UI7 uses several JSON files. The one device which is created when you install the Vera plug-in is the installer. It adds information as appropriate to UI5 and UI7 so that newly added Z-Wave devices which the plug-in recoginizes will get the correct behavior and icons. The installer also creates an uninstaller device. If you remove the plug-in, the uninstaller detects that the installer has been deleted and it cleans up all files created by the installer and "un-adopts" all devices which were adopted by the installer by deleting the peer devices and making the original Z-Wave devices visible again. The Uninstaller also removes the Z-Wave interceptor. Vera should once again behave exactly as it did before the plug-in was installed.

The Z-Wave queue

The Installer device also acts as a master Z-Wave queue. It coordinates the Z-Wave messages sent by the peer Vera devices to the physical controllers to which they are assigned, but also so other devices controlled by them. Some of these commands cannot be sent back-to-back and must be performed with an adequate delay. The Z-Wave queue coordinates and prioritizes such commands, and also handles waiting for commands to be sent to battery-operated devices such as the Nexia One-Touch.

The "Failed to get lock" bug

As of December, 2017, Vera Controls has yet to completely resolve a long-standing bug in LuaUPnP which is the root cause of many Vera crashes. The LuaUPnP engine will suddenly freeze for one minute and then restart with any pending operations lost. This seems to be a race condition in some of LuaUPnP's internal threads and happens at random times, especially when the engine is performing several tasks concurrently. Veral Controls has been made well aware of this bug and hopefully, they will fix it soon.

The Z-Wave queue con be considered as a huge work-around for this bug. It has been designed to coordinate all Z-Wave activity from the plug-in in one place even when several different devices are being handled simultaneously.

Github source code

​https://github.com/ElephantEight/GenGenSceneController

Older documentation

The product page for the Evolve LCD1 is ​here.

It also works with the LCD-1 Tabletop model (LCD-1TT) as well as the dual-gang LCD1/Switch (LCD-2) as well as the newer round button dual-scene 3-scene and 4-scene models but probably not with the LCD-3 or LCD-D.

Before this plug-in, you cold install an Evolve LCD1 into Vera just like any other Z-Wave device and it works as a generic 5-button scene controller. However, you could not modify the LCD screen or take advantage of other advanced features.

This plug-in not only allows you to set the LCD labels but also allows you to change screens. The scenes triggered when you press a button depends on the current screen.

The Evolve LCD-1 controller can also act as a remote thermostat controller and display for separate Z-Wave thermostats such as the Evolve T100R Thermostat. The temperature from other temperature sensors can also be displayed.

Version 0.8 is a major new release with many new features. This however, is still work-in-progress so expect new features and bug-fixes.

Current features

  • Switch between 9 different screens from the Vera dashboard
  • Select labels for 6 different custom screens. Each screen can have 5 labels and each label can have 1 or 2 lines of text.
  • Each custom label can either be in normal, condensed, or inverted font and can be left, center, or right-justified.
  • Each screen can trigger 5 different scenes. Each button can be programmed in several different modes: Momentary, Toggle, Exclusive, and Switch Screen.
  • Select from 6 temperature screens. The first two have fixed labels. The other four can be programmed with custom top and bottom labels. Each temperature screen can be associated with a different thermostat or temperature sensor
  • Screens have an optional timeout which will automatically switch to a designated screen if there is no user activity within a specified time.
  • Detailed configuration options predefined in the Device Option tab.
  • Easy scene creation. Just press the "Set" button and choose the devices to change with each button.
  • The controller can itself be controlled in other scenes to, for example, switch to a different screen at a particular time of the day.

Known bugs / unimplemented features

  • There may be some reliability issues where labels are sometimes not displayed correctly when you switch screens, or else the device reboots and briefly shows its splash screen momentarily.

Installation

If you have previously included your Evolve LCD1 controller into your Z-Wave network, exclude it first.

Now install the app from the Mios Marketplace as you would any other plug-in. However, once installed, it will not automatically generate an icon.

Now include the LCD1 controller like any other Z-Wave device. Note that the inclusion process may take a little longer than usual. You may first see a generic scene controller icon. Then it will disappear, and it will then be replaced with the Evolve LCD1 icon.

Note: that this plug-in installs a global file: zwave_products_user.xml in vera's /etc/cmh directory. This file did not exist until this plug-in. This file can be used to add important extra information to specific Z-Wave devices. The current version contains entries for the Evolve LCD1 controller as well as the Evolve T100-R thermostat. Future versions could add information, such as detailed configuration parameters, for more Z-Wave devices. Unfortunately, there can only be one of these files and any plug-in which updates this file would overwrite any previous version.

Clicking on the wrench icon, you will see various tabs. The most important one is named "Screens" and it controls the labels and other features of each screen. When the device is first created, these labels are filled in with numbers from One to Thirty spelled out, but you can change them to whatever you want.

Selecting an item from the upper pop-up selects which screen you want to edit. There are several types of screens

  • Preset screens - These are hard-coded into the Evolve LCD firmware and cannot be changed. In firmware versions prior to 00.00.39, you can select from several different languages. Firmware 00.00.39 only supports English but provides more reliable operation

Preset Screen example

  • Custom screens. These allow all 5 labels to be edited. Labels can be at most 16 characters long. Each label can either be in Normal, Condensed or Inverted font. The normal font can be split into two lines. This will happen automatically at spaces or hyphens as needed or you can force a line-break with \r. Lines can be displayed as left, center, or right justified. Note that center justified is only approximate.

Custom screen example

  • Temperature Screens. These show the current temperature in degrees Fahrenheit according to the associated thermostat. There are also up and down arrows for changing the temperature. Temperature screens 1 and 2 have fixed labels. You can edit the top and bottom labels in temperature screens 3 through 6. Note that the LCD1 does not have its own built-in temperature sensor.

Temperature screen example

Connecting scenes

The easiest way to connect a scene to a button is to press the "Set" button on the right side of the row. This will bring up the Vera scene editor and will automatically create a new scene if one does not already exist. You can add delayed actions to the scene if desired as you would with the regular scene editor. However, you don't need to create triggers for each scene that you create. The Evolve LCD1 GUI will do that automatically for you. Scenes created this way are standard Vera scenes and will show up in Vera's automation/scenes tab and can be edited there after they have been created.

(Note that the scene numbers used in versions prior to 0.8 have changed. Pressing the "Set" button in the screens tab automatically selects the correct scene number.)

The Evolve LCD1 can itself be part of a scene to change the screen. For example, you can have one set of controls in the morning and a different screen in the evening by using a pair of time-based scenes to switch the screen twice per day.

Button modes

The Evolve LCD1 currently supports four different modes for custom or preset lables:

  • Momentary - When a button is pressed, the line will highlight briefly. These buttons are associated with a single scene
  • Toggle - When a button is pressed, the line with toggle highlighting on and off. These buttons are associated with tow scenes - an on scene and an off scene. The "Set" button turns into a pair of "On" and "Off" buttons.
  • Exclusive - When a button is pressed, it highlights that line and all other lines are unhighlighted. This can be used, for example, to set up to five different brightnesses for a single light.
  • Switch Screen - When a button is pressed, it switches the screen to a different one. This allows you to create several different menu levels.

Screen timeouts

If you use several custom screens, it is best to set up a "home" screen (typically Custom 1) which can provide the most important feature as well as "jumps" to other screens. To get back to the home screen, you can either create a specific "home" button, or you can simply wait for a particular timeout to occur. Pressing any button on the LCD panel resets the timeout so that the screen changes only when there is no new activity for the given timeout.

How it works

This is a hybrid Vera device. Most devices in Vera are either Z-Wave or Lua devices. The Evolve LCD1 is both. In order to do this, two devices are created: The "Z-Wave device" and the "Peer device" but only the peer device is displayed in the main UI5 devices page or on the dashboard. (This is different from the typical parent-child relationship in other plug-in devices.) This dual-device strategy works around a limitation in the Vera architecture whereby Z-Wave devices cannot execute Lua commands. It also allows us to dispatch different scenes depending on what screen mode the device is in.

Sending screen updates to the LCD too quickly can cause lines of test to be lost, garbled, or placed in the wrong spot. Unfortunately, the delay required to avoid such errors is variable and choosing the maximum "safe" delay would cause screen redraws to be very slow. Furythermore, the device, does not give any feedback as to when it is safe to draw the next part of the screen. To solve this problem starting in version 0.7, the plug-in sends a dummy request to the controller. The controller will not respond if it is not yet ready and the plug-in will retry drawing that chunk with a bit more delay. Unfortunately, the only requests that pass through the Z-Wave chip on the device and onto the display microcontroller are not understood by Vera, and the current Vera firmware has no good method to pass such unknown messages to Lua code. Instead, the plug-in enables Z-Wave data received messages (log level 42) if they are not already enabled, and monitors the log for the expected response. This is an incredible hack but it is the only thing that works after many failed attempts at a more elegant solution.

Tuning Parameters

In the Advanced tab, you will find various tuning parameters which may be used to improve performance. The values of these parameters may depend on how far your LCD controller is away from Vera as well as the firmware version of the controller. When you first create the device one of two sets of parameters is chosen depending on whether the firmware version is greater than 0.31 or not. This plug-in was developed mostly with firmware version 0.39. All delay parameters are in milliseconds

Parameter Meaning 0.31 default 0.37 default 0.39 default
LCD_BaseDelay Delay after redrawing any chunk of the screen 2000 100 300
LCD_ClearDelay Delay after clearing the screen 0 500 500
LCD_LineDelay Delay after redrawing each line of the screen 0 100 35
LCD_CharDelay Delay after redrawing each character of the screen 0 10 8
LCD_ResponseDelay Time needed to wait for a response after displaying a chunk 30 30 30
LCD_BackoffDelay Delay to add after each failed attempt to draw a chunk 50 50 50
LCD_MaxParts Maximum secions to draw in one chunk. Can be 1 or 2 1 2 2
LCD_UseClearScreen 1 to clear the whole scree, 0 to clear individual lines 1 1 1
LCD_Retries maximum number of retries if redraw fails 10 10 0
LDD_SwitchScreenDelay Delaye befor swiching screens 50 50 50
ShowSingleDevice? Set to 0 to show both the Z-Wave and peer devices in UI5 1 1 1

If your LCD1 firmware is older than 00.00.39, we recommend contacting Evolve Guest Controls for an upgrade to the latest firmware (unless you absolutely need support for foreign languages in some of the fixed screens, which was rrmoved in 00.00.39) since the new firmware is more reliable.

Evolve Documnetation

Here is a PDF of the original Evolve LCD1 documentation: attachment:"EVLCDx Z-Wave Specification Rev H.pdf​​"

Enjoy!

Gengen

Attachments