OpenZWave 1.6 Release Notes
This is a WIP document in preparation for 1.6 Release
This document aims to assist Developers with updating their application to the latest version of OZW (1.6 at the time of writing).
This is a long overdue release, with several major new enhancements, lots of work on core OZW code and of course bug fixes. Basic functionality is retained with 1.4 meaning that application does not necessary have to update code to use 1.6, but several features would not be available to the end user.
With the release of 1.6, a significant set of new features has resulted in the Device Config Files changing slightly. Due to developer resource constraints, we will no longer be accepting updates to the 1.4 version config files. From a application perspective this means that you will not be able to offer support for the latest devices unless you choose to maintain 1.4 database yourself. We encourage you to update to 1.6 as quickly as possible to take advantage.
We also plan to add approx. 1300 new devices (with full config file support) to the OZW Device Database very soon after the release of 1.6.
Finally, the accompanied utility, OpenZWave Control Panel has had some minor updates to support 1.6, but is essentially unmaintained. A new maintainer for this project would be helpful as I know its in use as a embedded control panel in many home automation applications. Alternatively, you may wish to explore the Control Panel in the zwave2mtqq wrapper once its updated to 1.6
This quick summary of the new features include:
- A New ValueID Class - BitSet
- A Internal Timer Class - #1315
- UserCode CommandClass - Conversion to ASCII and Deleting Usercode's - #997
- SoundSwitch CC - #1664
- CentralScene CC - #367
- Config File Revision Numbers and Updates - #734
- Updated Notification CC (Previously Alarm CC) - #1395
- Internationalization/Localization - #184, #327
- SimpleAV CC - #1558
- Updated Multilevel Sensor CC to Version 11 - #1566
- Updated ThermostatMode CC to Version 3 - #1386
- Updated ThermostatSetPoint CC to Version 3 - #1385
- Updated BinarySwitch CC to Version 2 - #1314
- Updated Device Config Format to incorporate Revision and MetaData Information
- Refresh Values in specific CommandClasses when a device wakes up. Useful for refreshing the Battery Level on devices that don't periodically report.
- Depreciated the old dotNet wrapper that was included in the OZW source. The new dotNet wrapper is maintained by @dotMorten at https://github.com/OpenZWave/openzwave-dotnet-uwp
- Manager::WriteConfig is depreciated. OZW will automatically save the cache as each node reaches a QueryStage_Complete phase.
- It is now possible to assign labels to Instances, to easily identify what a instances function is. The Instance Label is preprended to all ValueLabels by default as well. If not Instance Labels are defined in a config file for a device, it defaults to "Instance X"
- Exceptions are enabled in OZW now. This is to allow us to bubble errors upto the application from deep inside OZW.
The ValueID Index parameter has been increased from 255 to 65535 (uint8_t to uint16_t). This is due to many command classes exporting a large amount of information. Applications should ensure they can handle larger indexes as several command classes are already making use of indexes > 255
BitSet ValueID is a new ValueID to represent (mainly) configuration variables where individual bits have a meaning. Often these Values are represented as a Integer and its up to the user to calculate what the final value would be for the configuration they want to set.
For Example, a configuration option from a vendor lists the following:
In the above example, with BitSet, each bit is accessible individually and includes labels and help text associated with it.
The Following new methods are implemented, as well as the new ValueID Type BitSet
- Manager::GetValueAsBitSet
- Manager::SetValue(ValueID, pos, bool)
- Manager::SetBitMask
- Manager::GetBitMask
- Manager::GetBitSetSize
The Set/GetBitMask allow a application to test which bits are valid.
The GetBitSetSize allows the applications to know what the BitSet is stored as (1, 2 or 4 bytes)
For Manager::GetValueLabel, Manager::GetValueLabel, Manager::GetValueHelp, Manager::GetValueHelp a optional parameter, pos is provided. If pos is > 0 and the ValueID type is a BitSet, then these methods will return the Label and Help text for the individual bits. If pos is not provided, then the Label and Help text for the entire ValueID will be provided
The BitSet ValueID is backwards compatible with the Methods to set/get values via Integer, String. eg Manager::GetValueAsInt or Manager::GetValueAsString
Existing Device Configurations are being ported to this new BitSet ValueID from their old Byte/Short/Integer Representations.
OZW now supports localization of all user visible strings, such as Labels, Help, and List Entries. This allows the application to display this information, if available, in a language native to the user or application context.
In Addition, Help information has been added to all "internal" ValueID's (eg, built in values from command classes)
The Localization is now stored in the config/Localization.xml file. A Wiki page will be created detailing how to add new languages.
Localization is also supported in the Device Config Files as well.
NOTE: Some Applications used the ValueID Label to identify what a ValueID represented. This approach was always discouraged (due to many reasons including the authors terrible spelling mistakes!). The Correct Approach is to use the ValueID Index to identify different ValueID's from a CommandClass.
The Index are guaranteed to remain static throughout the life of a Major Release of OZW (so in this case, for all 1.6 releases of OZW). To Assist Developers, a set of Enum's for each command class with all the available ValueID's is planned shortly.
The Alarm CommandClass (now known as the Notification CommandClass in the Z-Wave Specifications) has been rewritten to take advantage of numerous new features and functionality.
This CommandClass is one of the most updated CommandClasses in the Z-Wave Specifications and often the updates are adding new Notification Types. (eg, Gas, Irrigation etc). OZW now allows the Notification Types to be dynamically specified in a new config file, NotificationTypes.xml. This should mean as new notification types are released, a updated XML file should be all that is necessary to support them.
The Notification CommandClass will now also export any "parameters" that accompany the notification as a ValueID of the appropriate time. A example would be the UserCode that was entered to unlock a door. (assuming the lock supports sending this information). These parameters start at index 256, and will reuse the index for the same type of parameters. (so UserCode Parameters will always be at index 260)
The Notification Command Class will now export the different types of Notifications on different indexes depending upon what the Node Supports. So for example, the Smoke Alarm Notification Type will always be index 1, Carbon Monoxide will be index 2 etc etc.
The Notification Types are exported as a ValueList, and where the node supports it, the Items in the list will be what the Device Supports. (for devices that don't specify what events they support, all items will be exported in the ValueList)
Newer Devices support "clearing" notifications back to their idle state after a pre-determined timeframe. For devices that don't support this clearing, OZW will reset the Notification back to the idle state after 5 seconds by default. This can be changed via the "Automatically Clear Events" ValueID exposed on devices that don't clear events.
Upon Start-up - OZW will retrieve a list of previous notifications on the device and export these in quick succession. This is useful to determine if a alarm has been triggered while the application was not running. Care should be taken with any automations triggering on this feature, as the Notification was historic and may not be valid anymore. A Application May wish to check the QueryStage, anything that comes before QueryStage_Complete is considered historic.
When the initial UserCode CommandClass was written, it was reverse engineered, and Codes were exported as ValueRaw types. This was due to different manufactures implementing the Codes as either ASCII or Decimal representations. Since then, the Z-Wave Specifications have clarified that all UserCodes need to be represented as ASCII.
The UserCode CommandClass now exports all UserCodes as ValueString. For backwards compatibility with devices that still send the UserCode as a decimal representation, then the option exposeRawUserCodes can be specified in the device config file, and a ValueRaw ValueID will be created for that device. Applications should detect the presence of a ValueRaw ValueID and display that instead of the ValueString (as the string may not be able to display correctly).
In addition, due to the above issue of representation, the method of clearing a UserCode was inconsistent among devices. It was often up to the user to determine if they should be using 0000 or "0000" (or any other representation). Now, the UserCode CommandClass exposes a ValueInt "Remove User Code". Setting that ValueID to the position of the UserCode the application wishes to delete will delete that associated UserCode. This is implemented in OZW by a configuration option to specify how to clear the UserCode on a particular device.
This last feature has not been fully tested with all devices. Please encourage users who cannot reset their UserCodes to raise a issue at the OZW Github pages so we can add all the variations to the UserCode Command Class.
The CentralScene CommandClass in the Master branch was created to assist the developers reverse engineer the class (before the Specifications were released). In 1.6, the CentralScene as been fully rewritten to support all the features of this CommandClass.
The major changes is it is no longer necessary to manually create ValueID classes via the config file, as full auto discover is supported. In Addition, we support the 7 different type of scene activations (1 press, down, up, 2 press .... ) and each "scene" is exported via a unique ValueID. (max of 255 scenes are supported)
Scene's will also be cleared after a period of 1 second by default, but can be modified via the "Scene Reset Timeout" ValueID.
Several Devices such as dimmers often suffered from a issue where after setting a new value on the dimmer, OZW would return a often "indeterminate" value. This could be the value of the dimmer prior to the Set command being issue, or a random value between the current value and the new value being set.
This was due to the fact that OZW issues a "GET" immediately after a "SET", and some devices would respond with a "instant" value.
The Z-Wave Specifications now includes a new value exported for devices implementing the version 4 of this CommandClass that is the "Target Level". This is the Value that the device is ramping up/down to over time.
Application may wish to display this Target Level (when present) rather than the "Level" value to avoid confusion, or maybe implement a refresh of the Level Value if it != Target Level Value.
A large number of CommandClasses have seen updates, and several new CommandClasses have been introduced. A quick overview includes
* SoundSwitch CommandClass - Allows a device to play a set of different sounds. Currently implemented for the Aeotec Doorbell Gen 5
* SimpleAV CommandClass - a CommandClass for controlling Audio-visual Equipment.
* BarrierOperator CommandClass - Controlling Barriers.
* ManufacturerProprietary CommandClass - Currently implemented only for Fibaro Venetian Blind Controller.
* The Security (S0) CommandClass has seen several bug fixes and improvements over the 1.4 branch.
For Battery powered (sleeping) devices, its often needed to refresh certain values when the device wakes up. OZW can now query for updated dynamic values for each CommandClass when a device wakes up, ensuring that ValueID's are the most recent. This is useful for example with the Battery CommandClass. Not all devices will send a period Battery Level to the Controller, so this can refresh that Value when the device wakes up.
Requires adding "refreshonwakeup=true" to each commandclass of the device you wish to refresh in the device config database.
Device Config Files can now specify Labels to be assigned to Instances. This can assist users to identify the function of each instance (or say, distinguish between each switch in a 4-way Switch). Instance Labels are now prepended to the strings returned by Manager::GetValueLabel by default. (can be disabled by setting "IncludeInstanceLabel" in the Options Class (or options.xml)
Some New methods have also been introduced to the Manager Class to assist applications: Manager::GetInstanceLabel( ValueID const &_id); Manager::GetInstanceLabel(uint32 const _homeId, uint8 const _node, uint8 const _cc, uint8 const _instance);
A New Method, Manager::IsMultiInstance has been exported to allow applications to determine if a Device supports MultiInstance Associations.
The Manager::BeginControllerCommand method has been marked as depreciated. Applications should be using the dedicated ControllerCommand Methods now. Please see the Developer Documentation for a list of supported controller command methods implemented.
The Device Database now can contain a large amount of MetaData about a device. Metadata includes things like:
* Product Manual Link
* Product Image
* Instructions for Including/Excluding and Resetting a Device
* Changelog Entries detailing changes between versions of config file.
as well a several other fields. Much of this information for existing devices has been sourced for the the Z-Wave Alliance Product Database.
Applications can use the Manager::GetMetaData method and Manager::GetChangeLog method with the associated Node::MetaDataFields enum to retrieve specific metadata about a device as a string
The OZW Device Database now contains a new Revision parameter for each file (manufacturer_specific.xml, device config files, NotificationTypes.xml etc). With each change of the associated file, the revision is incremented.
When OZW starts up, it checks the revisions of each device against the latest release available, and can download the latest updated files. Optionally, the Application can check and trigger updates manually as well.
In addition, if a user adds a application that is not in the OZW device database, OZW will check the latest releases to see if a config file is available for it.
These checks require both DNS (for the version check) and HTTP access from the application.
The Following Methods are available:
- Manager::checkLatestConfigFileRevision
- Manager::checkLatestMFSRevision
- Manager::downloadLatestConfigFileRevision
- Manager::downloadLatestMFSRevision
The details of revisions of device config files is also available as a ValueInt's from the Manufacturer Specific CC as the following ValueID's:
"Loaded Config Revision" - The revision of the config file that's in use currently
"Config File Revision" - The revision of the config file on disk
"Latest Available Config File Revision" - Latest Version of the config file available via the OZW website.
Additionally the following options have been added (via the Options.xml or Options Class)
* AutoUpdateConfigFile - Bool - If we should automatically download latest version of config files if we detect they are out of date.
* ReloadAfterUpdate - "NEVER/IMMEDIATE/AWAKE" - If the node should be reloaded after updating the config file. Recommended is AWAKE.
* AWAKE - Only reload nodes that are not sleeping devices (eg mains powered)
* IMMEDIATE - Reload all nodes. Note, Sleeping Devices will then not fully reinitialize till their wakeup time comes
* NEVER - Do not reload. The Application needs to call Manager::RefreshNodeInfo to apply the new configuration to the device
Note - We do plan to switch this to HTTPS in a future version of OZW. The decision to not do that now was due to the fact that a dependency on a SSL Library would become required.
OZW now makes use of Exceptions in 1.6. What this means that wrappers and applications need to wrap all calls to OZW in Try...Catch Blocks (eg, any Manager.h method). Uncaught exceptions usually terminate the application.
OZW now includes a function to send raw packets to the device. This is purely for debugging and not intended as a "user feature" that should be exposed to the average user.
Additionally, there is no way to check the success, nor receive a reply. The following Methods are available:
- Manager::SendRawData
-
New Notification Types - Type_NodeReset, Type_UserAlerts, Type_ManufacturerSpecificDBReady have been added.
-
For UserAlerts - these are typically alerts that should be displayed to the user - Refer to OpenZWave::Notification::UserAlertNofification for a list of possible alerts.
-
Added the ControllerCommand that triggered the Notification (#1138) See Notification::GetCommand
-
Added the Path the the Serial Port in Notifications as well.
We have removed the old dotNet wrapper that was included with the OZW source. A new, better wrapper is maintained by @dotMorton at https://github.com/OpenZWave/openzwave-dotnet-uwp
You should migrate your applications to that wrapper instead as that is actively maintained.
This function has been depreciated. This name was confusing, as it was actually just saving a cache of the Z-Wave Network to a file. OZW now automatically saves the cache as each node reaches QueryStage_Complete, and the file name has been updated to ozwcache_*.xml to indicate it a cache file, and not a configuration file.
The following methods on the Manager Class have been depreciated and will be removed in a future version. They never fully functioned as intended, and were never recommended for use:
-
Manager::SetNodeOn
-
Manager::SetNodeOff
-
Manager::SetNodeLevel
-
Manager::SwitchAllOn
-
Manager::SwitchAllOff
OpenZWave included a Class that allowed the application to create very basic scenes controlled by the application. Its not evident that these were ever fully utilized by applications and have not received much attention from developers. All the methods relating to this implementation have been marked as depreciated and will be removed in a future version.
- Manager::GetNumOfScenes
- Manager::GetAllScenes
- Manager::RemoveAllScenes
- Manager::CreateScene
- Manager::RemoveScene
- Manager::AddSceneValue
- Manager::AddSceneValueListSelection
- Manager::RemoveSceneValue
- Manager::SceneGetValues
- Manager::SceneGetValueAsBool
- Manager::SceneGetValueAsByte
- Manager::SceneGetValueAsFloat
- Manager::SceneGetValueAsInt
- Manager::SceneGetValueAsShort
- Manager::SceneGetValueAsString
- Manager::SceneGetValueListSelection
- Manager::SetSceneValue
- Manager::SetSceneValueListSelection
- Manager::GetSceneLabel
- Manager::SetSceneLabel
- Manager::SceneExists
- Manager::ActivateScene
The Developers also plan to depreciate several features that have not seen much adoption or attention. This includes the following:
* Virtual Nodes/Button Support
* A Replacement for the Schedule ValueID as in its current form its limited in what it can represent and requires a redesign to take advantage of all the features that Z-Wave offers.
* HID Controller Support - These are very old controllers that have not been seen on the market in years.