Best Practices for Z-Wave Door Locks

Introduction

Door Locks are critical to the security of the home and thus communication must be reliable and fast. This document brings together the many issues unique to door locks and guides the developer toward the most robust and interoperable implementation. These are mostly recommendations, not requirements and do not guarantee Z-Wave certification. Z-Wave allows for plenty of product differentiation, but it is important that common lock functions operate in the most interoperable fashion.

Z-Wave door locks entered the market in 2008. The problem was that at the time the Z-Wave Command Classes were missing standardized reporting of status of the lock and user codes. Initially Alarm CC was used by the locks to send various notifications to the hub to deliver status updates. The problem with this method is that each manufacturer used a unique set of commands to deliver the different status updates. Shortly after these initial locks hit the market and with the arrival of the Z-Wave Alliance, the Z-Wave specifications were updated and now locks can send standardized messages to deliver status changes. The standardized messages make Hub software much easier as basic operations can be received without the need for specialized code for each lock manufacturer.

Z-Wave Command Classes for Door Locks

SDS14224 Z-Wave Plus v2 Device Type Specification section 4.5.1 (in Version 10) specifies the Mandatory and Recommended Command Classes (CC) for Lock Device Types. Some command classes have a minimum version required for certification. However, the developer is free to choose the command class version that meets the product needs. As command classes have matured, commands have been added which in turn adds complexity and more code space. Every command in a command class must be implemented by the lock based on the version supported. If you don’t want to support some commands in a later version, then only declare the earlier versions in the Version CC.

Mandatory Command Classes

  • Door Lock CC (V4 or later)
  • Battery (V1) – unless the lock is mains powered
  • Basic CC – 00=UNLOCK, FF=LOCK (does not appear in NIF)
  • Security S0 CC – for backwards compatibility to older gateways that don’t support S2
    • S0 may change to recommended in the future but is mandatory in 2020

Common Mandatory CC for All Z-Wave Plus v2 Devices

  • Association, version 2
  • Association Group Information
  • Device Reset Locally
  • Firmware Update Meta Data, version 5
  • Indicator, version 3
  • Manufacturer Specific
  • Multi-Channel Association, version 3
  • Powerlevel
  • Security 2
  • Supervision – See discussion below – you SHOULD be using Supervision!
  • Transport Service, version 2
  • Version, version 2
  • Z-Wave Plus Info, version 2

Most of these command classes are handled by the SDK and/or the Z-Wave Application Framework (ZAF). There are some customizations to many of these command classes, but the effort is minimal.

Recommended Command Classes

  • User Code CC – If the lock has a keypad this CC is used to program/enable the codes
  • Notification CC – Send various lock status messages to the Lifeline NodeID (Gateway/Hub)
  • Time CC – See the section below on the time/clock command classes
    • Clock CC
    • Time Parameters CC
  • Generic Schedule CC – Defines time/date ranges to enable/disable User Codes
  • Schedule CC – Simpler but less flexible schedules using any Z-Wave command
  • Authentication CC – use with RFID, NFC, Mag cards etc. and link ScheduleIDs with User Codes

Other Command Classes

  • Door Lock Logging CC
    • Door lock logging CC provides a means to retrieve an audit trail of operations
    • Typical use: If the hub is offline, a log of all operations is recorded and can then be sent when the hub comes back online
  • Barrier Operator CC – Typically used with motorized entry gates which are like locks
  • Entry Control CC -Used with RFID or other means that have ASCII strings
    • Relies on the Hub to authenticate the string and then send an unlock command
    • Typically used for Keypads which do not control a lock
    • Use Authentication CC for locks
  • Configuration CC (V3) – configure specific features that are not supported by other CCs
    • See the Door Lock Configuration SET command which should provide most of the needed configuration
    • Configuration CC should only be used if really necessary as it is less interoperable
  • Application Status – Can be used to reply back to the Hub that the lock is currently busy and cannot execute the command just received
    • Use Supervision instead
  • Protection CC – enables a Child Protection mode
  • AntiTheft CC (v3) – Locks the device so if stolen it is a brick
  • Multi-channel – Multichannel should not be necessary
  • Multi-command – Can be used to return several commands in a single frame to reduce battery consumption however with the smaller payload size in S2 it is not recommended
  • Obsolete Command Classes – do not use these
    • Schedule Entry Lock CC – use Generic Schedule CC instead
    • Alarm CC – Use Notification CC (V3 or later)

Security Levels

Security S2 has three security levels and S0 has one for a total of four different security levels:

  1. Security S2 Access Control – Strongest Security level only used with devices that provide access to secure areas – door locks
  2. Security S2 Authenticated – SmartStart requires a QR code/DSK – lights/thermostats/sensors
  3. Security S2 UnAuthenticated – used by a small number of early S2 devices – generally not recommended – Does not require QR Code/DSK
  4. Security S0 – Legacy security mode – slower, uses more battery power, less secure than S2

The Security S2 Unauthenticated and S2 Authenticated keys are NOT recommended due to potential security holes. S2 is rapidly becoming commonplace so it is expected that S0 will no longer be mandatory but will change to recommended. S0 is slower, uses more battery power and is less secure than S2 due to the network key being exchanged using a known encryption key. Security S2 uses Diffie-Hellman elliptic curves to exchange the keys, an out-of-band DSK is required to join the network and Nonces are pre-computed enabling a single frame compared to three for S0 (Nonce Get, Nonce Report, Encrypted frame). Locks are required to use the Security S2 Access Control level.

Recommended Security Levels:

  • S2 Access Control
  • S0 if supported or if legacy support is desired (mandatory in 2020)

Reporting State Changes

All Z-Wave Plus devices are required to send to the Lifeline NodeID (typically the Hub) when their state changes. The Z-Wave Application Framework True-State Engine (TSE) can be used to send state changes. The primary state changes in a lock are:

  • Secured vs. Non-secured (locked vs. unlocked)
  • Keypad entry of a code
  • Battery level

Schedules

Currently most locks rely on the Hub to install/remove User Codes and to manage the times and dates when the codes are valid. Thus, the lock need not know the current date/time and does not need to store schedules and apply them to User Codes. This makes the lock firmware simple and keeps the complexity of schedules with the Hub and its significantly greater processing, storage and user interface capabilities. However, many rental property agencies prefer the battery powered lock to have the schedules built-in so that even if there is an extended power or internet failure, the proper User Codes are enabled/disabled at the proper times. Thus, there is a desire to have these schedules managed within the lock itself. Fortunately, Z-Wave already has the command classes in place to support them, but schedules are complicated.

Generic Schedule CC – Recommended

Generic Schedule CC can set Time Ranges and then Schedules which are comprised of one or more Time Ranges. A Time Range has Start and Stop Date/Time fields and each field can be enabled or ignored. For example, a Time Range can be every Monday from 1pm to 3pm (date and minute fields are ignored) or can include specific dates like 2022 May 24th from 11:23am to 4:57pm. This makes the Time Range very flexible and able to specify virtually any type of date/time combination.

A Schedule is a list of Time Ranges that are either Included or Excluded to build the schedule. Thus, a Time Range of M-F 8am-5pm could be included but then 1 Jan 2022 from 4pm to 5pm could be excluded. In this example, the Schedule includes the first Time Range and Excludes the second. Generic Schedule only creates the ScheduleIDs. It does not hold any commands or perform actions. Authentication CC is then used to link a Schedule to a User Code or other authentication method. There are up to 64K Schedule and Time Ranges though each device reports the number supported in the Generic Schedule Capabilities Report. Due to the memory required for schedules and time ranges most devices will typically only have perhaps a dozen or so of each.

Schedule CC

Schedule CC is different than Generic Schedule in that Z-Wave commands are used instead of ScheduleIDs/AuthenticationIDs/UserCodes. Schedule CC is usable for any Z-Wave command and not just those that use the Schedule IDs. Schedule CC is most often used with thermostats or other devices that change state automatically based on the time/date. While Schedule CC can be used to execute User Code Set commands to enable/disable User Codes on a schedule, it is less flexible than Generic Schedule CC. For simple weekly schedules this CC will work OK but trying to build more complex schedules quickly becomes cumbersome.

Schedule Entry Lock CC

The Schedule Entry Lock CC has been deprecated and thus should not be used in new locks. Use the Generic Schedule CC instead. There are less than a dozen certified locks with Schedule Entry Lock CC. Hubs may want to control this CC to support specific locks but it is not required.

Authentication CC

Authentication CC is used to connect a User Code to a Generic Schedule. Authentication CC can also be used in conjunction with RFID, NFC, mag stripes, BLE or other forms of user authentication. It is then used to enable/disable various access methods based on a schedule. Thus, Authentication is flexible but with that flexibility comes complexity.

Time CC vs. Clock CC vs. Time Parameters CC

If a lock supports schedules to enable/disable user codes, then it needs some way to determine the date and time. For example, the cleaners code only works on Tuesdays from 2 to 4pm. How is a lock supposed to get the current local time and date so it knows when to enable the cleaners code?

There are three different command classes for getting various parts of the time/date. Time Command Class is mandatory for all Gateways and is the most full featured method. Unfortunately, not all gateways support it yet, so most devices need to support one of the others for use with older hubs. Clock CC is defined in SDS13781 – Z-Wave Application CC but the other two are defined in SDS13782.

Time CCClock CCTime Parameters CC
SecondV1(Local)V1 (UTC)
MinuteV1(Local)V1V1 (UTC)
HourV1(Local)V1V1 (UTC)
Day of Week V1 
Day of MonthV1(Local)V1 (UTC)
MonthV1(Local)V1 (UTC)
YearV1(Local)V1 (UTC)
Time Zone Offset
Hour, Minute
V2
DST OffsetV2
DST Start
Month, Day Hour
V2
DST End
Month, Day Hour
V2
Command Classes for setting the Date and Time

Time CC – Recommended

Time command class is described in SDS13782 (Z-Wave Management Command Class Specification). Time CC is mandatory for all Z-Wave Plus Gateways and thus is the recommended method for a lock to set its clock to the current local date and time. Time CC Version 2 adds time zones and daylight savings time support if desired however V1 provides the necessary functionality in most cases.

The Z-Wave specification recommends having an association group to identify the time server node however the Gateway is expected to have an accurate time reference so using the Lifeline is acceptable.

The Time CC does NOT have a date/time SET command. Thus, the hub cannot set the date/time and instead should wait for the lock to GET it. The hub can send a Time/Date REPORT to the lock when a lock is included in a network. However, the lock must send a Time GET command within the first few minutes to accurately set its internal clock. The lock should then periodically send a Time GET to ensure the internal clock remains accurate to the local time. Only the lock knows the accuracy of its real-time clock. Thus, the lock will determine how often it needs to update its internal clock and send a Time GET when needed. The hub should not send Time Reports unless responding to a Time GET other than immediately after inclusion. Note that for certification purposes a door lock CONTROLs Time CC, it does not SUPPORT it. The Hub is required to SUPPORT Time CC.

Time Parameters CC – Optional

The Time Parameters command can SET/GET/REPORT the year, month, day, hour, minute & second of the UTC time. However, it does not set the time zone which must be done via the Time CC V2. Thus, Time Parameters CC relies on the hub to send the current UTC time but the lock can also send a GET and adjust its internal clock to match the one from the hub. However, this requires support on the hub software which is not mandatory so not all hubs will be able to provide the current date/time.

Clock CC – NOT Recommended

Clock command class is sent by a Hub and can set the local weekday and time. Thus, it only supports a 7-day schedule since it cannot set the date, just the day of the week. Typically, the Hub would send a Clock Set as part of inclusion in the network. Since the clock on the lock will drift, the lock must periodically send a Clock Get to the Hub and to maintain time accurately. This method is NOT recommended. However, on some old hubs this is the only method available.

Recommended Time Setting Algorithm

The algorithm below provides a basic guide for setting the time. The first step is to wait for the inclusion and the security negotiation to complete. Then send a Time GET and start a 30 second timer. If a Time REPORT arrives before the end of the 30 second timer, then the Hub supports Time CC so use that. If the Hub instead sends either a Clock REPORT or a Time Parameters SET then that will set the initial time for the lock. The lock will have to continue to send periodic Clock GET commands to the Hub to maintain clock accuracy. If there is no response from the Hub, then the lock has no choice but to disable the schedule features as they require accurate local time.

Depending on the accuracy of the local clock circuitry, the functioning time setting command class should be used to update the local clock at a sufficient rate to match the desired settings. Typically, this would be once per day assuming a 100ppm or better 32Khz crystal is used for the clock (see section Real Time Clock (RTC) 32KHz Crystal below).

Notification CC

Notification CC was originally called Alarm CC which was deprecated at V2 and replaced with Notification CC. When the first Z-Wave locks were developed there was no standardized method for informing the Hub when a lock state changed. Each lock manufacturer was free to choose an Alarm Type and Alarm Level to communicate various status changes. Unfortunately, this resulted in non-standard and non-interoperable Z-Wave commands. Notification CC V3 defined a set of Access Control notification types and events which are described in SDS13713 which is a spreadsheet listing all standard notification types/events. For new lock developments it is recommended to use the standardized commands described here instead of the old Alarm CC ones (V8 or later is recommended). The Alarm CC can still be sent if the lock is joined using Security S0 for backwards compatibility, but their use is not recommended if the lock is joined using Security S2. Alternatively, a Configuration Parameter could be used to enable/disable the Alarm CC commands. Sending these old commands wastes battery power and clogs up the Z-Wave network.

Notification CC is typically used to communicate specific state changes beyond Door Lock or User Code CCs. There is overlap between some notifications and some Door Lock commands. The recommendation is to use Door Lock CC and only use Notification for cases that don’t have overlap.  A few examples are shown in the Sample Communication section below.

Supervision CC

Supervision CC is mandatory for all S2 devices. Since locks provide property security and users have very high expectations for reliability and robustness of lock operation, it is strongly recommended that all communication to/from a lock be wrapped in Supervision CC. Supervision eliminates the need to send a Notification that a user code has been SET as the Supervision Report confirms that the command was received, decrypted and executed. See Appendix A for a sample implementation of Supervision CC for the door lock firmware.

The example below shows a lock being unlocked manually by the user. The lock needs to be 100% certain it informs the Hub that the door is now unlocked. To do that, the DoorLock_Operation Report is encapsulated with a Supervision GET command. The first attempt is blocked by RF noise but the protocol will automatically retry sending the frame up to five different routes using the mesh network because the ACK was not received. The second try delivers a frame to the Hub but due to more RF noise, the Hub is unable to decrypt the message. The Hub has already ACKed the frame so the protocol has retired the frame from the transmit queue and will not try again. However, the SDK has started a 500ms timer expecting a Supervision Report within that time. Since the Hub could not decrypt the message, it has discarded the frame. Once the 500ms timeout has expired, the lock will resend the frame. This time it gets thru and the Hub is able to decrypt the message and replies with a Supervision REPORT with a status of Success. At that point, the lock is 100% certain the frame has been delivered, decrypted and executed. The use of Supervision command class ensures delivery and execution of any Z-Wave command and should be used with any critical function of any device.

Door Lock Command Class

Most of Door Lock CC is straightforward and documented in SDS13781. The Lock Timeout vs. Auto-Relock function however needs a little extra explanation. The Door Lock Operation Set (V1) command includes the Mode which assigns either Timeout mode or Constant mode. The Door Lock Configuration Set (V1) command sets the timeout in Minutes + Seconds and whether the lock is by default in Constant or Timeout mode. Later versions of Door Lock CC enable sending a Timeout or an Auto-Relock time in the Operation Set command. Auto-Relock is in force ONLY if the lock is in Constant mode. If the lock is in Timeout mode then the normal Timeout Minutes/Seconds is used and the Auto-Relock values are ignored. Given the more common support of the Timeout Mode, it is recommended to use this mode for improved interoperability. Note that some locks have the timeout or mode as a configuration parameter. While it is acceptable to have these modes read/writeable via Configuration CC, the same values must also be reflected in the Door Lock Configuration commands.

Sample Communication

This section describes the communication between a lock and a hub in various scenarios. All communication is Security S2 encrypted which is shown in most of the examples. The recommendation is to encapsulate all frames in Supervision to ensure the frames was delivered and decrypted.

User Manually Locks/Unlocks

When the user manually locks or unlocks the lock by turning the bolt/lever, the lock must send to the Lifeline NodeID(s) (the Hub) the following:

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
3 Properties1Supervision SessionID incremented with each new GET
40x09LenSupervision Length
50x62CmdClassDoor Lock Operation CC V4
60x03CmdDoor Lock Operation Report
7 LockMode00=unsecured, FF=secured – See SDS13781 table 44
8 Properties1In/out Handles Mode – table 45
9 DoorConditionDoor/bolt/latch state – table 46
100xFETimeoutMinLock returns to secured after these many minutes
110xFETimeoutSecLock returns to secured after these many seconds
12 TargetModeTarget Mode if in transition or LockMode
130x00DurationSeconds to reach target mode – 0=already at target

Note that Supervision CC is used to ensure the Hub has received and decrypted the frame.

A Notification CC can be sent if the lock was included using Security S0 for backwards compatibility. It is not recommended if the lock is using Security S2 which relies on the Supervision CC to ensure delivery.

Byte #ValueNameDescription
10x71CmdClassNotification CC
20x05CmdNotification REPORT
30x00V1AlarmTypeV1Alarm can be non-zero IF documented in the user manual
40x00V1AlarmLevelThese are used for backwards compatibility
50x00Reserved 
60xFFStatus00=notifications are disabled, FF=enabled
70x06Type06=Access Control
8 Event01=Manual Lock, 02=Manual Unlock
90x00Properties1Parameters Length

User Enters a Good User Code

A User Code of “1234” has been set in a deadbolt lock with a keypad at UserID=03. The lock is locked and then the user enters 1234 to unlock the lock.

A Notification CC is sent informing the Hub which User Code was used.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x13Properties1Supervision SessionID incremented since this is a new frame
40x09LenSupervision Length
50x71CmdClassNotification CC
60x05CmdNotification REPORT
70x00V1AlarmTypeV1Alarm can be non-zero IF documented in the user manual
80x00V1AlarmLevelThese are used for backwards compatibility
90x00Reserved 
100xFFStatus00=notifications are disabled, FF=enabled
110x06Type06=Access Control
120x06Event05=keypad Lock, 06=keypad Unlock
130x63ParamUser Code CC
140x03ParamUser Code CC cmd = REPORT
150x03ParamUserID=0x03
160x01ParamUserID Status = occupied & enabled
170x31ParamUser Code = ASCII “1”
180x32ParamUser Code = ASCII “2”
190x33ParamUser Code = ASCII “3”
200x34ParamUser Code = ASCII “4”

Optionally a Door Lock Operation could be sent to inform the Hub that the door is now unlocked.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x12Properties1Supervision SessionID=0x12
40x09LenSupervision Length
50x62CmdClassDoor Lock Operation CC V4
60x03CmdDoor Lock Operation Report
70x00LockMode00=unsecured, FF=secured – See SDS13781 table 44
80x00Properties1In/out Handles Mode – table 45
90x00DoorConditionDoor/bolt/latch state – table 46
100xFETimeoutMinLock returns to secured after these many minutes
110xFETimeoutSecLock returns to secured after these many seconds
120x00TargetModeTarget Mode if in transition or LockMode
130x00DurationSeconds to reach target mode

User Enters a Bad User Code

Currently nothing is sent when the user enters a bad code. There have been discussions that the lock should send the bad code so that the Hub could collect statistics on how many times a user has tried to enter a code and what the code was. This would require a new Notification Access Control Event. Let us know what you think of this idea or get involved with the Z-Wave Alliance Standards Development Organization and make a proposal.

Hub Sends Lock/Unlock Command

A hub sends a Lock or Unlock command. Most locks take a few seconds to slide a bolt and this sequence shows the use of a Supervision Report with a WORKING status followed by a SUCCESS.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x95Properties1Supervision SessionID=0x15 with Status Updates
40x03LenSupervision Length
50x62CmdClassDoor Lock Operation CC V4
60x01CmdDoor Lock Operation SET
70xFFLockMode00=unsecured, FF=secured

The lock immediately responds with a Supervision WORKING report with the More Status Updates bit set indicating another report will come within the next 7 seconds. The WORKING status means the lock is busy moving the bolt and it will take a few seconds to know for sure if it is properly engaged. If the Status Updates bit was 0, then only this supervision report would be sent. If the lock (or more typically a gate) takes more than 10 seconds to reach the final state it is suggested to send a WORKING report every 5-10s. Each time the Duration field should be updated with the estimated time to completion.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x02CmdSupervision REPORT
30x95Properties1Supervision SessionID=0x15 – More Status Updates set
40x01StatusWORKING – Once the bolt has finished moving another report will be sent
50x07DurationNext report will be in 7 seconds or less. The duration should be a worst-case number to handle the case when the lock is jammed.

When the lock has completed the operation, it sends another Supervision Report this time with the Status Updates bit cleared and a status of SUCCESS (if the Status Updates bit was set in the Supervision GET). This frame should be sent as soon as the lock has completed the operation.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x15Properties1Supervision SessionID=0x15
40xFFStatusSUCCESS
50DurationTarget mode completed

At this point the Hub is assured the lock has completed the operation because Supervision CC confirms the command was executed. However, most Hubs want to receive a status update so either a Notification CC, Access Control and Event of 0x03 (lock) or 0x04 (unlock) could be sent. It is recommended to send a Door Lock Operation Report wrapped in a Supervision Get as shown here.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x0AProperties1Supervision SessionID=0x0A
40x09LenSupervision Length
50x62CmdClassDoor Lock Operation CC V4
60x03CmdDoor Lock Operation REPORT
70xFFLockMode00=unsecured, FF=secured
80x00HandlesModeIn/out Handles Mode
90x00DoorConditionDoor/bolt/latch state
100xFETimeoutMinLock returns to secured after these many minutes
110xFETimeoutSecLock returns to secured after these many seconds
120xFFTargetModeTarget Mode if in transition or LockMode
130x00DurationSeconds to reach target mode

Hub Sends User Code Set

Supervision encapsulated User Code SET enabling the User Code of “1234” for User ID 5.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x01Properties1Supervision SessionID=0x01
40x08LenSupervision Length
50x63CmdClassUser Code CC
60x01CmdUser Code SET
70x05UserIDUser Identifier = 0x0005
80x01UserIDStatus0x00=available, 0x01=Access Enabled, 0x02=Disabled, 0x03=Messaging, 0x04=Passage Mode
90x31UserCode1ASCII ‘1’
100x32UserCode2ASCII ‘2’
110x33UserCode3ASCII ‘3’
120x34UserCode4ASCII ‘4’ – total length of the code is 4 to 10 digits

The lock would then send the Supervision CC REPORT with a value of SUCCESS if the User Code was properly executed otherwise it would return FAIL. If the UserID is more than 255, the Extended User Code Set command would be used. This command can also set multiple codes in a single frame.

When a Hub sends a User Code SET, the Hub typically wants confirmation that the code was in fact properly set. While this isn’t necessary if Supervision is used, it is good practice as that is the only method that a pre-S2 lock can confirm that the User Code was set. Since the Supervision Report already confirmed the User Code has been set, it is not necessary to wrap this frame in Supervision as it is merely informational. If the lock is using Security S0, the notification report confirming the User Code is recommended.

Byte #ValueNameDescription
10x71CmdClassNotification CC
20x05CmdNotification REPORT
30x00V1AlarmTypeV1Alarm can be non-zero IF documented in the user manual
40x00V1AlarmLevelThese are used for backwards compatibility
50x00Reserved 
60xFFStatus00=notifications are disabled, FF=enabled
70x06Type06=Access Control
80x0EEvent0E=New User Code added
90x00Properties1Parameters Length = none

Hub Sends a Duplicate User Code

If a Hub sends another User Code SET with a different UserID but with the same UserCode, the lock must return a Notification CC Type=Access Control (0x06) with an Event=New User Code Not Added (0x0F). This Notification should be sent encapsulated in Supervision CC if the lock is using S2.

Lock Sends Low Battery Warning

Most locks use simple alkaline batteries so version 1 of the battery command class is sufficient. Use the later versions for rechargeable or complex battery situations.

Battery powered locks should automatically send the Hub the battery level whenever the battery level changes by a significant amount. The lock should send an update if the battery level has changed by more than about 5% from the last report. The amount of change required to trigger an update is up to you, but it should be large enough to only send a battery update every several days or even weeks. Note that changes in temperature can cause the battery level to rise so the trigger should require the level to be lower. Be aware that most Hubs will occasionally poll the battery level which is why sending an update is not needed unless the level has changed significantly from the last report. Zero percent battery level should still allow the lock to operate reliably, but just barely. One Hundred percent battery level should be achievable with a wide range of batteries.

When the Critical Battery Level has been reached the lock must send a Low Battery warning (0xFF). Each lock will have a different Critical Level but it is typically in the 5% to 20% range. When the Critical level is reached for the first time, a low battery warning must be sent to the Lifeline. This warning must ONLY be sent once. Typically, a RAM variable holds a flag that is set when the low battery warning is sent and is only cleared upon power-on reset when the batteries are replaced. The Low Battery warning should be sent wrapped in Supervision command class to ensure the Hub received it. Normal battery reports do not need to be wrapped in Supervision.

Battery Report – Low Battery Warning

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x01Properties1Supervision SessionID=0x01
40x03LenSupervision Length
50x63CmdClassBattery CC
60x03CmdBattery Report
70xFFLevel0xFF=Low Battery Warning, 0-100 otherwise

Lock Updates Local Time

If a lock has schedules that enable User Codes at certain days/times, it needs to know the current local time. See the discussion above about the different command classes that can be used and the hardware considerations later in this document for the necessary hardware to support time keeping. Typically, a lock will send this frame once per day to sync to the local time. Note that in this case Supervision is not used as the clock update is not important enough to warrant the extra overhead and battery power. The frame below should be sent within the first five minutes after inclusion if the Hub does not automatically set the time. Note that the time can be off by a few seconds due to system wide delays.

Lock sends the Hub a Time GET

Byte #ValueNameDescription
10x8ACmdClassTime CC
20x01CmdTime GET

The Hub responds with Time REPORT that sets the local time to be 5:6:7 (6 minutes and 7 seconds after 5am)

Byte #ValueNameDescription
10x8ACmdClassTime CC
20x02CmdTime Report
30x05HourLocal Hour
40x06MinuteLocal Minute
50x07SecondLocal Second

Lock sends the Hub a Date GET

Byte #ValueNameDescription
10x8ACmdClassTime CC
20x03CmdDate GET

The Hub responds with Date REPORT that sets the local date to be 10 September 2019

Byte #ValueNameDescription
10x8ACmdClassTime CC
20x04CmdDate Report
30x07Year1Local year MSB
40xE3Year2Local year LSB – 0x7E3=2019
50x09MonthLocal Month – 0x09=September
60x0ADayLocal Day – 0x0A=10th day

The lock must calculate the day of the week based on the current date. The Time Offset Get command in V2 could also be used to get the daylight savings date/time if desired. Checking the local time/date at around 3:10am each day should keep the lock accurate to the current local daylight savings time.

Generic Schedule to Enable a User Code

The following sequence assigns User Code 0x05 to be enabled M-F 8am-5pm except on 5 June 2019 from 1:23pm to 6:45pm. First step is to SET two Time Ranges (01 and 02). The Hub should first send a Generic Schedule Capabilities Get to determine how many Time Ranges and Schedules the lock supports.

Time Range Monday thru Friday 8am to 5pm

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x09Properties1Supervision SessionID=0x09
40x15LenSupervision Length
50xA3CmdClassGeneric Schedule
60x03CmdGeneric Schedule Time Range Set
70x00TRngID1 
80x01TRngID2Time Range ID=0x0001
90xBEWeekdayWeekday Mask = M-F
100x00StartYear1Note the InUse bit (MSB) is zero for all fields that are not used
110x00StartYear2Start Year not used
120x00StopYear1 
130x00StopYear2Stop Year not used
140x00StartMonStart Month
150x00StopMonStop Month
160x00StartDayStart Day
170x00StopDayStop Day
180x00StartHourStart Hour
190x00StopHourStop Hour
180x00StartMinStart Minute
190x00StopMinStop Minute
200x88DayStartHrDaily Start Hour = 8am
210x91DayStopHrDaily Stop Hour = 17:00=5pm
220x00DayStartMinDaily Start Minute
230x00DayStopMinDaily Stop Minute

Time Range 5 June 2019 from 1:23pm to 6:45pm:

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x0AProperties1Supervision SessionID=0x0A
40x15LenSupervision Length
50xA3CmdClassGeneric Schedule
60x03CmdGeneric Schedule Time Range Set
70x00TRngID1 
80x02TRngID2Time Range ID=0x0002
90x00WeekdayWeekday Mask not used
100x87StartYear1 
110xE3StartYear2Start Year = 2019
120x87StopYear1 
130xE3StopYear2Stop Year = 2019
140x86StartMonStart Month = June
150x86StopMonStop Month = June
160x85StartDayStart Day = 5th
170x85StopDayStop Day = 5th
180x8EStartHourStart Hour = 1pm
190x92StopHourStop Hour = 6pm
200x97StartMinStart Minute = 23 minutes after the hour
210xADStopMinStop Minute = 45 min after the hour
220x00DayStartHrDaily Start Hour
230x00DayStopHrDaily Stop Hour
240x00DayStartMinDaily Start Minute
250x00DayStopMinDaily Stop Minute

Now that the two Time Ranges have been defined, the next step is to link them to each other to create a ScheduleID. In this case Time Range 0001 is being INCLUDED and Time Range 0002 is being EXCLUDED to make the desired schedule.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x0BProperties1Supervision SessionID=0x0B
40x09LenSupervision Length
50xA3CmdClassGeneric Schedule
60x06CmdGeneric Schedule Schedule Set
70x00SchedID1 
80x01SchedID2Schedule ID = 0001
90x02NumIDsNumber of Time Range IDs = 2
100x80TimeRngID1 
110x01TimeRngID2Include Time Range 0001
120x00TimeRngID1 
130x02TimeRngID2Exclude Time Range 0002

Finally, the Authentication CC is used to link the Schedule ID to the User Code CC UserID

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x0CProperties1Supervision SessionID=0x0C
40x0ALenSupervision Length
50xA1CmdClassAuthentication CC
60x06CmdAuthentication Technologies Combination Set
70x00AuthID1 
80x05AuthID2Schedule ID = 0005 – can be any value but matching with the UserID is easier to match them up
90x01FallBackFallback Status = 01 = enable access based on the schedule
100x00UserID1 
110x05UserID2User Code CC UserID=0005
120x00SchedID1 
130x01SchedID2Generic Schedule CC ScheduleID=0001
140x00NumAuthIDOnly the User Code is enabled

In all cases Supervision should be used to confirm the schedule and time ranges are set properly. Alternatively, a GET should be used if the lock is only using security S0. If NFC, BLE or some other authentication technology is used then the NumAuthID would be more than zero to include these other forms of authentication.

Lock Has a Hardware Failure

If a lock has some sort of a hardware failure, there are several Notification Events that can be sent. The most common is the lock is jammed where the bolt is neither in the locked or unlocked position but somewhere in between. Other options are to send a Home Security – Tamper event when the battery cover is removed. The Impact Detected event could be used if an accelerometer detects the lock being smashed. If someone is jamming the RF in an attempt to bypass the lock, then an RF Jamming message could be sent. In this case the lock should store the RF jamming message if the message is not acknowledged by the Hub due to the jamming. The lock should continue to attempt delivery at ever larger timeouts between retries.

Byte #ValueNameDescription
10x6CCmdClassSupervision CC
20x01CmdSupervision GET
30x01Properties1Supervision SessionID=0x01
40x08LenSupervision Length
50x71CmdClassNotification CC
60x05CmdNotification Report
70x00V1AlarmTypeV1Alarm can be non-zero IF documented in the user manual
80x00V1AlarmLevelThese are used for backwards compatibility
90x00Reserved 
100xFFStatus00=notifications are disabled, FF=enabled
110x06Type06=Access Control
120x0BEvent0B=Lock Jammed

The lock should also send a Door Lock Operation Report with a value of 0xFE (Door Mode Unknown) if the bolt is not in either the Locked or Unlocked mode.

Z-Wave Long Range

Z-Wave Long Range (ZWLR) support is recommended for locks. Z-Wave Long Range is a star topology with very long range. ZWLR is ideal for a battery backed up hub to talk directly to a distant lock even if the power is out and the Z-Wave mesh repeaters are offline. ZWLR will be available at the end of 2020 and is a software upgrade that can be OTAed to existing units. RF regulatory testing (FCC) may need to be redone to ensure ZWLR meets the applicable regulatory limits.

Hardware Considerations

The 700 series Z-Wave hardware is typically a FLiRS (Frequently Listening Routing Slave) device. Typical power consumption in this mode is on the order of 10uA average with brief peaks of 12mA during a transmit. Once every second the chip briefly wakes up and listens for a Wakeup Beam from the hub or an adjacent node. If the hub wants to talk to the lock it sends the Beam which wakes up the lock and then the two can communicate. Once the communication is complete the lock will again enter a low-power state. The 250ms FLiRS mode can be used to reduce the latency of waking the lock with a tradeoff of additional power draw.

Real Time Clock (RTC) 32KHz Crystal

Most locks need to accurately measure time and keep schedules of when to enable User Codes. The 700 series has an internal low power Low Frequency RC Oscillator (LFRCO=32KHz). However, the oscillator is not accurate enough to keep the schedule accurate without frequent updates from the Time Server (LFRCO can drift by more than 1min/hour). Thus, it is recommended to use a 32KHz crystal connected to the LFXO of the EFR32. A low cost 100ppm 32KHz crystal can provide accuracy of 9s per day. Note that if your lock does not support Time CC then an external crystal is not needed.

  • Use a 32KHz crystal for the LFXO if schedules are supported

One MCU or Multiple?

The Z-Wave 700 series is an ARM processor with built-in cryptography accelerators and plenty of low power peripherals. The ZGM130S has plenty of GPIOs and can be easily extended using simple GPIO expanders via I2C or SPI. In most cases the ZGM130S is more than powerful enough to run the entire lock using the single processor. This avoids the complexity and security issues involved with using multiple microcontrollers within the lock. If a multi-MCU solution is chosen, the communication method between the ZGM130 and the lock MCU should be a UART, SPI or I2C and should be encrypted. Do NOT use the SerialAPI on the ZGM130! The SerialAPI is intended for use with Internet Gateway processors with large amounts of FLASH/RAM/CPU. The SerialAPI does NOT provide support for security encryption/decryption which is built-in to the embedded SDK. The recommendation is to develop your own encrypted serial protocol between processors.

Appendix A: Supervision Encapsulation End Device Example

Z-Wave SDK 7.14 does not have direct support for encapsulating frames with Supervision CC. However, it is easy to add manually. The example below simply wraps the DoorLockOperationReport with the SuperVisionGet IF the device was added as S2 which means the Hub support Supervision CC. The frame is not encapsulated if responding to a GET from the Hub.

In CC_DoorLock.c - Add the following code to this function:
  
 static uint8_t prepare_operation_report(ZW_APPLICATION_TX_BUFFER *pTxBuffer, uint8_t enableSuper)
 {
   ZW_APPLICATION_TX_BUFFER * ptr = pTxBuffer;
   memset((uint8_t*)pTxBuffer, 0, sizeof(ZW_APPLICATION_TX_BUFFER) );
   uint8_t len=sizeof(ZW_DOOR_LOCK_OPERATION_REPORT_V4_FRAME);
  
   if (SECURITY_KEY_S2_ACCESS == GetHighestSecureLevel(ZAF_GetSecurityKeys()) && enableSuper) { // add supervision if S2 enabled
     ptr->ZW_SupervisionGetFrame.cmdClass = COMMAND_CLASS_SUPERVISION;
     ptr->ZW_SupervisionGetFrame.cmd = SUPERVISION_GET;
     DL_SessionID = CC_SUPERVISION_ADD_SESSION_ID((DL_SessionID+1));
     ptr->ZW_SupervisionGetFrame.properties1 = DL_SessionID;
     ptr->ZW_SupervisionGetFrame.encapsulatedCommandLength = sizeof(ZW_DOOR_LOCK_OPERATION_REPORT_V4_FRAME);
     ptr=(ZW_APPLICATION_TX_BUFFER*)((uint8_t*)ptr+sizeof(ZW_SUPERVISION_GET_FRAME)); // skip 4 bytes
     len+=sizeof(ZW_SUPERVISION_GET_FRAME);
   }
   ptr->ZW_DoorLockOperationReportV4Frame.cmdClass = COMMAND_CLASS_DOOR_LOCK_V4;
   ptr->ZW_DoorLockOperationReportV4Frame.cmd = DOOR_LOCK_OPERATION_REPORT_V4;
   cc_door_lock_operation_report_t operation_report;
   CC_DoorLock_OperationGet_handler(&operation_report);
   ptr->ZW_DoorLockOperationReportV4Frame.currentDoorLockMode = (uint8_t)operation_report.mode;
   ptr->ZW_DoorLockOperationReportV4Frame.properties1 =
       (operation_report.outsideDoorHandleMode << 4) | operation_report.insideDoorHandleMode;
   ptr->ZW_DoorLockOperationReportV4Frame.doorCondition = operation_report.condition;
   ptr->ZW_DoorLockOperationReportV4Frame.lockTimeoutMinutes = operation_report.lockTimeoutMin;
   ptr->ZW_DoorLockOperationReportV4Frame.lockTimeoutSeconds = operation_report.lockTimeoutSec;
   ptr->ZW_DoorLockOperationReportV4Frame.targetDoorLockMode = operation_report.targetMode;
   ptr->ZW_DoorLockOperationReportV4Frame.duration = operation_report.duration;
   return(len);
 } 

Time vs. Clock vs. Time Parameters Command Classes Explained

Introduction

Door locks, thermostats and other Z-Wave devices often need to know at least the time and day of the week. In many cases they need to know the full date and time to enable a lock User Code when a renters code is valid or set the thermostat into energy save mode. These devices need a way to determine the current date and time to within a few seconds of accuracy.

Z-Wave provides three different command classes (CC) for getting various parts of the date/time. Time Command Class is mandatory for all Gateways. Unfortunately, not all gateways support it yet, so most devices need to support one of the other command classes for use with older hubs. The question then is how is a device supposed to get the current date/time so the schedule can operate properly?

Time CC – Recommended

Time command class is described in SDS13782 (Z-Wave Management Command Class Specification). Time CC is mandatory for all Z-Wave Plus Gateways and thus is the recommended method for a device to set its clock to the current local date and time. Time CC Version 2 adds time zones and daylight savings time support if desired however V1 provides the necessary data in most cases.

The Z-Wave specification recommends having an association group to identify the time server node however the Gateway is expected to have an accurate time reference so using the Lifeline is acceptable.

The Time CC does NOT have a date/time SET command. Thus, the hub cannot set the date/time and instead must wait for the device to GET it. When a device is included in a network, it must send a Time GET command within the first few minutes to accurately set its internal clock. The device should then periodically send a Time GET to ensure the internal clock remains accurate to the local time. Note that for certification purposes a device CONTROLs Time CC, it does not SUPPORT it. The Hub is required to SUPPORT Time CC.

Time Parameters CC – Optional

The Time Parameters command can SET/GET/REPORT the year, month, day, hour, minute & second of the UTC time. However, it does not set the time zone which must be done via the Time CC V2. Thus, Time Parameters CC relies on the hub to send the current UTC time but the device can also send a GET and adjust its internal clock to match the one from the hub. However, this requires support on the hub software which is not mandatory so not all hubs will be able to provide the current date/time.

Clock CC – NOT Recommended

Clock command class is sent by a Hub and can set the local weekday and time. Thus, it only supports a 7-day schedule since it cannot set the date, just the day of the week. Typically, the Hub would send a Clock Set as part of inclusion in the network. Since the clock on the device will drift, the device must periodically send a Clock Get to the Hub and to maintain time accurately. This method is NOT recommended. However, on some old hubs this is the only method available.

Recommended Time Setting Algorithm

  1. Wait for Inclusion into a Z-Wave Network
  2. Wait for Security negotiation to complete
  3. Send a Time CC DATE GET
  4. Wait for a Time CC DATE REPORT for ~30s
  5. If DATE REPORT arrives, Send a Time CC TIME GET and wait for ~30s
    1. if the Time REPORT arrives then the date/time is now set and use Time CC for future clock adjustments
    1. Exit the search for the local time
  6. If Time CC DATE REPORT times out:
    1. Retry 2 more times with random delay of a few minutes between each retry
  7. During steps 3-6, If a Time Parameters CC SET or a Clock CC REPORT is received, use those to update the date/time but if a Time CC report arrives use Time CC
  8. Send a Clock CC GET
    1. If a REPORT arrives within ~30s then use Clock CC GET to update the date/time
  9. If CLOCK fails
  10. Send Time Parameters CC GET to get the current date/time
  11. If those fail, there is no source for the current date/time, disable all scheduling features

Depending on the accuracy of the local clock circuitry, the functioning time setting command class should be used to update the local clock at a sufficient rate to match the desired settings. Typically, this would be once per day assuming a 100ppm or better 32Khz crystal is used for the 700 series low frequency external crystal oscillator (LFXCO).

Conclusion

End Devices should send a Time CC Date/Time GET shortly after inclusion in a Z-Wave network and then periodically send Date/Time GETs based on the accuracy of the real-time clock circuitry. Updating at 3:10am ensures the clock will be accurate to daylight savings time should be sufficient for a low-cost 32kHz crystal. The algorithm above works for just about any hub that has at least minimal support for time keeping.

Z-Wave Alliance is Now an SDO

What does an SDO mean you might ask? An SDO is a Standards Development Organization and the Z-Wave Alliance has now legally become a non-profit SDO. What this means to you is that Silicon Labs no longer control the progress of Z-Wave, the members of the SDO now control it. Read more details about the SDO in the Z-Wave Alliance Press Release.

There are seven founding members: Alarm.com, Assa Abloy, Leedarson, Ring, Silicon Labs, StratIS, and Qolsys. If you’re employed by one of these companies, join a working group and make your ideas known! There are six different membership levels with varying “voting rights” and costs so your organization can choose a level based on interest and budget.

How will this impact you and your IoT device development? In the short term probably not much, early next year however, expect to see the first Z-Wave product pass thru the new certification requirements based on the specifications produced by the SDO. Longer term this is all part of Z-Wave becoming an open standard with more silicon providers and software stack provides implementing new features all to make Z-Wave last for years to come.

The goal is to make Z-Wave THE sub-GigaHertz radio standard for IoT devices. Z-Wave is simple, low power, doesn’t require a lot of FLASH/RAM (IE: it runs on cheap MCUs) and most of all interoperable all the way back to devices released over two decades ago. Sub-GigaHertz means the radio passes thru walls and travels longer distances with less interference than the 2.4GHz protocols.

I want to remind everyone to register for the Works With Virtual Conference coming up in just a few weeks! Click below to check it out – HEY it’s FREE!

Register for the Works With Conference by clicking here. Learn how to integrate into Amazon, Google, Apple an other IoT ecosystems.

Works With is much more than just Z-Wave. All the key eco-system players are there explaining in detail how to be a part of their world. This is a technical conference so don’t miss it. I’ll be giving a demo of the latest version of Simplicity Studio V5 and how to quickly build, debug and certify Z-Wave applications.

Whats the difference between Z-Wave and Z-Wave Plus?

There is a lot of confusion between Z-Wave Plus and older non-Plus devices.

Z-Wave_Plus_Badge_RGB_v3.1A product that is Z-Wave Plus means it has passed a rigorous certification process and thus is likely to be more reliable and have fewer issues than non-Plus devices. All Z-Wave devices are 100% interoperable and backwards compatible so a Z-Wave Plus device can communicate with any non-Plus device without issue. If you have a choice between a Z-Wave Plus device and a non-Plus device, I recommend you choose the Z-Wave Plus device because the Plus device will work better.

Z-Wave History Lesson

The timeline shows the technology trajectory that Z-Wave has traveled since its inception in 2002.ZWaveTimeLineThe timeline shows the constant improvement and evolution of Z-Wave. Initially the data rate was only 9600 bits per second. This was fast enough to turn a light or two on or off but as things progressed and you want to slowly change the color of a dozen or more bulbs, then you need a faster data rate. Thus, the increase to 40K with the 300 series and 100K with the 500 series. There are many other enhancements along the way including longer range, better RF sensitivity, lower power, more peripherals and in particular the AES encryption engine. The amazing thing though all of these improvements is that they have all remained 100% backward compatible. Even the latest chips can talk to the early 100 series chips. Granted it is only at the slower 9600 bps but it still works! So the lamp dimmer you bought in 2004 is still able to talk to the latest SmartThings hub.

The Curse of the Even Series

Z-Wave has had some mistakes along the way, after all no one is perfect. Much like the Star Trek Movies, all of the even series chips were flawed and quickly obsoleted. The developers became so fearful of the curse of the even series they skipped the 600 series and jumped straight to 700. The 200 series chips were simply buggy. Period. They had some significant power issues making them difficult to use as a battery powered device among other problems. The flaws were quickly fixed and the series replaced with the largely firmware compatible 300 series which had a long and plentiful life. Many 300 series devices are still in the market though the chips have reached end-of-life so there are limited inventories left. A small number of 300 series chip based devices are Z-Wave Plus – but that number is quite small and there are probably none left on the shelves though you could have one installed in your home. Fortunately, as we’ve seen they are all completely interoperable so no problem there.

The 400 series suffered from a marketing mistake early on – the memory that holds the firmware is One-Time-Programmable (OTP). This means the firmware cannot be updated – EVER. You burn it once, and pray it is good. This is a nightmare for developers as they have to replace the chip every time they make a new firmware build, which they typically do hundreds of times per day. While the OTP saves a fraction of cent in the cost of the chip, the drawbacks far outweigh that tiny cost.  Fortunately we developers didn’t have long to wait and the 400 series was replaced with the 500 series. The 500 series had plenty of FLASH and added the ability to update the firmware in the device even after it is installed in the field using a technique called Over-The-Air (OTA) firmware update.

Z-Wave Security – AES Encryption

One of the most important IoT devices is a door lock. Naturally, a door lock needs to be secure. Up until 2008, Z-Wave was “in the clear” meaning it wasn’t secure at all. The Security Command Class was added to encrypt all communication with banking quality AES-128 encryption which makes Z-Wave secure – or so the Z-Wave developers thought.

In 2013 it was widely published that the Z-Wave security has a weakness when a device is first joined to a network. During that process, the encryption “key” is sent to the device over the radio and it is encrypted, but the encryption key is 128 bits of 0. Since the encryption key is all zero, it is possible for someone with very sophisticated equipment to “sniff” the radio data and thus obtain the key to every secure device in the network. While this is a security hole, it requires a lot of equipment on-site at the short time when the user is adding a secure device to the network. Much easier for a burglar to throw a brick thru a window to gain access vs. hacking a Z-Wave door lock. But Z-Wave had to counter with an improvement and they did just that in 2015 – with the updated Security S2 command class.

Security S2 adds full diffe-hellman symmetric encryption to the key exchange. A number of performance improvements were also made which enables battery powered devices to be secure without spending extra time exchanging secrets back and forth. All devices certified after April 2017 are required to support Security S2.

The question of Z-Wave Plus vs. Non-Plus however is independent of Security. Since new devices have to implement Security and they are Z-Wave Plus certified, it seems like the two go together but in reality they are independent. But all new devices will have both which is good. Fortunately support for Security S2 isn’t required to be supported by Hub vendors like SmartThings, Vera, HomeSeer, etc. They will need to add support but all your older non-secure devices will remain 100% backward compatible.

The Future

Z-Wave continues to evolve and improve but continues to remain 100% backward compatible all the way back to 2002 and the initial release of the 100 series transceivers. The Z-Wave Certification program continues to be strengthened with new features and new tests that make every Z-Wave certified product better and completely interoperable with every other Z-Wave device on the market. Interoperability is the advantage Z-Wave has over the many other competing wireless protocols for IoT.

Newer devices have been tested more rigorously and use the latest chip sets for better RF range and mesh network routing algorithms. So given the choice it’s generally better to buy newer devices using the latest technology.

Conclusion

Choose a Z-Wave Plus device over a non-Plus device even if you have to pay a little more. A Z-Wave Plus device uses the 500 series chips with the latest RF technology and firmware and has been tested under the Z-Wave Alliance Certification program which is quite difficult to pass. Rest assured that the Z-Wave device you purchase today will continue to be interoperable with future versions of Z-Wave technology for the foreseeable future.

 

EU Z-Wave Summit 2018 – Amsterdam

2018EUSummit1IoT Device Testing Best Practices by Eric Ryherd

Click  HERE to see the entire presentation including my notes. If you are a Z-Wave Alliance member a video of the presentation is usually posted on the members only section of their web site. The main takeaways from my presentation are:

  • Have a written test plan
  • Use the Compliance Test Tool (CTT) as the START of your test plan
  • Vary the environmental conditions during testing
  • Test using real world applications
  • Test using complex Z-Wave networks with routing and marginal RF links
  • Test with other hubs and devices
  • Automate testing using tools like the ZWP500
  • Code firmware with failure in mind
  • Utilize the WatchDog timer built into the Z-Wave chip

The presentation goes into detail on each of these topics so I won’t duplicate the information here. I also go thru several failures of devices I’ve been working with. You learn more from failures than you do when everything just works. This is the same presentation that gave last fall in the US summit.

Z-Wave Summit Notes

2018EUSummit4There were nearly 200 attendees at the Summit – a significant increase over last year. One of the main purposes of the summit is to learn what’s new in Z-Wave and what Silicon Labs is planning for the future. The most important news at this year’s summit is the 700 series which was announced at CES in January. Unfortunately we will have to wait a bit longer to get our hands on the chips due to the purchase of Sigma Designs by Silicon Labs. The 700 series chip has been updated to match the other SiLabs microcontrollers so the silicon has been delayed a bit but they expect to ship parts before the end of 2018. Z-Wave will benefit tremendously from a real CPU instead of the very resource constrained 8051 in the 500 series. The feature I can’t wait for is the hardware debugger. We’ll finally be able to single step our C code and inspect variables and set breakpoints. No more PRINTF! Yeah!

Time for hubs to switch to Z/IP and ZWare

The very clear message of the summit is that Z/IP and ZWare are now mature and is THE gateway interface going forward. My initial brief trials with Z/IP were frustrating with poor documentation and the software really wasn’t quite ready. But with the recent release of 2.81 it would appear it is ready for prime time and I’ll have to give it another look. I was surprised by the number of gateway developers that were at the summit and most were already using at least Z/IP and many also using the ZWare abstraction layer. The SerialAPI is the interface most gateway developers have used in the past but this is a very low-level interface. There are many nuances of handling sleeping devices and the complexities of the encrypted security encapsulation when using such a low-level interface. This is where Z/IP comes in which handles nearly all of these lower level details for you. Z/IP is planned to be the only supported interface in the near future and certification costs will be significantly higher if it is not used. ZWare adds another layer on top of the Z/IP which provides much easier C++ objects relieving the developer from having to learn the details of each Z-Wave command class. See the Z-Wave Public web site for more details.

The internal Z-Wave Technical Site (ZTS) is now also available to everyone but you still have to click on “accept terms” to gain access. However the access is granted immediately so you don’t have to wait for “approval”. So anyone wanting to learn about the inner guts of Z-Wave can now do so without buying a DevKit.

Summit isn’t all work, work, work

Maker:L,Date:2017-8-26,Ver:5,Lens:Kan03,Act:Kan02,E-YThe Summit isn’t all work all day even though the days are long and filled with lots of technical information. This summit had an evening at the Rosarium park. The park has room for team building games like a maze run, archery, volleyball among other games and of course lots of food and drink. It was a nice ice breaker and a good way to get to know your fellow Z-Wave developers. The networking opportunities are a very large part of the value of attending the summit in person. The evening highlight was a performance by the “Interoperables” Z-Wave Rock and Roll band lead by Alliance chairman Mitch Klein.

Z-Wave Saved My Fathers Life

My father is a cantankerous curmudgeon but at 89 years old he deserves to be a little crusty. In his infinite wisdom at the age of 79 he decided to move away from his family here in New England and purchased a home in warm sunny Florida. He was happy he no longer had to freeze in the cold of winter but I was unhappy because now he was 2,000 miles away and I worried something might happen to him. If someone broke in or if he fell no one would know potentially for weeks. To ease my worries I applied my technical expertise and deployed an inexpensive Z-Wave based system to keep an eye on him.

HomeSeer to the Rescue

HomeseerZeeS2

HomeSeer sells a Raspberry Pi based Home Automation system with a built-in Z-Wave interface called the Zee S2. This small box needs only 6 Watts of power but contains a complete Linux computer that can serve web pages and runs the HomeSeer HS3 application. My initial system was just the HomesSeer Zee S2 ($199) and two Express Controls EZMultiPli Multi-sensors ($99) for a total cost of $300 for my peace of mind.  No monthly charges, no “monitoring fees” or any other costs so this is indeed a low-cost solution. All of the Z-Wave devices just plug in with no wiring, no batteries and everything pretty much plug-and-play. In less than an hour the system went from the box to fully installed and the web interface up and running via my phone or computer.

The HomeSeer system is accessible 24x7x365 via their portal at myhs.homeseer.com. No complex router tunneling or anything like that – just plug the Zee S2 Ethernet cord into HS3the router and then login to it from anywhere in the world. The system is secure and password protected. The HS3 application serves web pages with a status of every Z-Wave device. The HS3 application runs on the Raspberry Pi so all processing is local which means temporary Internet connectivity outages are no problem.

The HS3 user interface shown here is utilitarian which is fine for this application. HomeSeer has an easy to use IF-THEN “events” page which is quite powerful. The HS3 system constantly monitors the motion sensors and depending on the time of day sends me a text anytime there hasn’t been motion detected in the house for more than 5 hours. I placed a motion sensor next to his bed and another in the kitchen. Since he typically would get up several times each night, my 5 hour time limit rarely false-triggered. The trigger was extended longer during the day since he would be up and around the house and not in the bedroom for more than 8 hours at a time.

Nothing is Perfect

When I first put the system together, it seemed to work reliably. However the Zee S2 unit was installed at the far end of the house near the cable box. The kitchen motion

ezmultipli200
Express Controls EZmultiPli Motion Sensor

sensor was about 25′ away and the bedroom one was another 20′ away and had to pass thru several walls, the HVAC system and a bathroom. With only 3 nodes in the Z-Wave network I violated one of the key rules of a mesh network – always have more than two routes to every device. In this case I had exactly one route to each device so I didn’t have a mesh and the result was a number of false triggers because the bedroom motion sensor occasionally couldn’t reach all the way back to the Zee S2.

I was frustrated because I left what I thought was a working system but soon turned out to be unreliable. Now I was 2000 miles away and had to suffer with this system for nearly a year before my next visit to Florida. The solution was to add a few lamp modules and another multi-sensor so now I had 7 nodes with several routes to all nodes. Now the system was reliable and did not false trigger. I added an event that automatically turned on a lamp in the family room whenever motion was detected. My father really liked this feature as he always had light as soon as he entered and it would automatically turn off when he had left the room.

I thought things were pretty robust at this point but my next Achilles heel turned up rather quickly. Something caused the Raspberry Pi to crash. I couldn’t log into it and it was no longer sending me the daily emails telling me what time my father had gotten up in the morning. After nearly 2 months the system just suddenly started sending me the daily emails again. Apparently a power outage had in effect rebooted the HomeSeer system. On my next visit I put the entire system on a power strip that my father could reach so he could reset the system. I still want a power strip that has a watchdog timer function and if it doesn’t get some sort of “ping” every hour or so, it reboots everything downstream.

He Takes a Fall

At 2:39am one morning in mid-November 2017, my father fell in his bedroom. He was unable to get up. He was unable to call for help. My HomeSeer system sent me a text at 7:39am stating he had not gotten up. That seemed like an odd time for him to not get up so I tried to call him. After several calls with no answer and checking the HomeSeer system to see that there has been no changes since 2:39am I became concerned. I had the Sheriff stop by and check on him and it turns out he was on the floor, awake but unable to move. The EMTs were called and he was taken to the hospital. In just 5 hours he was already dehydrated and would have slowly died a painful death in a day or so if my system had not been in place. The Z-Wave system saved my fathers life.

Looking back on it now, I had noticed that his morning schedule had started to vary significantly from day to day. For years he had been getting up at a pretty predictable time of around 10am. But in the months prior to his fall, his schedule had started to vary from 8am to as late as 1pm in the afternoon. When we talked on the phone he said he was fine but clearly he was struggling. He enjoyed being warm in Florida and he was happy and I was confident that my Z-Wave system would alert me to any major problems which it did.

Z-Wave Multi-sensor Version 2.0 with SmartStart – Batteries not Required

Merrimack, NH March 19, 2018 – Express Controls LLC announces the release of Version 2.0 of the EZMultiPli three-in-one multi-sensor and Z-Wave repeater. The Z-Wave Plus certified device is one of the first available SmartStart devices on the market and is available for purchase now on Amazon.

EZMFrontAnimFeatures

  • Motion Sensor
  • Temperature Sensor
  • Light Sensor
  • Color Indicator Night Light
  • Z-Wave® Range extender
  • Wall Powered – No Batteries, No wires
  • Screw tab for secure installation
  • SmartStart enabled

The new features for the 2.0 version are the addition of a screw tab for secure mounting and SmartStart. The tab on the enclosure enables secure mounting in either a standard outlet or a decorator outlet common with GFCI circuits used in kitchens and baths. The tab ensures children, elders, cleaners or maintenance personnel can’t easily remove the sensor. Secure mounting means the Z-Wave network is robust and reliable since EZMultiPli typically is a key repeater in the Z-Wave mesh network. Never worry about the batteries dying since EZMultiPli is wall powered. Installed by anyone with just a screwdriver – no wires, no batteries, no damage to the walls drilling holes.

SmartStart

qrPackSigma Designs SmartStart technology makes installation easy and secure. If your home automation system supports SmartStart, the first step is to scan the QR code on the back of EZMultiPli. If EZMultiPli was purchased as part of a kit containing several SmartStart devices, the QR code may have already been scanned at the factory. The next step is to simply plug EZMultiPli into a wall outlet and it will automatically join the Z-Wave network. Inclusion should begin within a couple of minutes but may take longer if several SmartStart devices are added at the same time. SmartStart uses the latest Security S2 encryption technology for all radio communication ensuring your system is secure.

Express Controls

Express Controls provides expert consulting services for the design and manufacture of wireless Internet of Things (IoT) products for Z-Wave product development teams. Express Controls has been been developing IoT products using Z-Wave protocol since 2003 and the 100 series Z-Wave RF transceivers.  Currently we are developing Z-Wave products using the latest Sigma Designs fifth generation 500 series RF modules which enable us to quickly prototype any IoT device you can imagine.  We have resources available for PCB design and layout as well as industrial design and 3D printing to help visualize the entire IoT product quickly.   Leverage our knowledge of the nuances of the Z-Wave protocol to bring your Z-Wave product to market quickly.  

Contact

Eric Ryherd – CEO and Z-Wave Expert Consultant

info@expresscontrols.com – +1 (603) 889-4841 – ExpressControls.com

EZMultipli How-To for SmartThings

SmartThings, now part of electronics giant Samsung, is a popular home automation platform and with the recently published Device Type fully supports the EZMultipli multi-sensor. Samsung_SmartThings_LogoSmartThings (a.k.a. ST) relies on the Cloud for processing which makes it flexible but is a little slower executing commands compared to a system with local processing. The ST user interface is exclusively thru a smartphone or tablet, there is no web interface for desktop computer access.  The system is easy to use with good support and an active user community.  SmartThings requires a $99 hub to interface to Wifi, Zigbee and Z-Wave devices. This post will show you how to get the most out of Express Controls EZMultipli Z-Wave MultiSensor. Refer to the EZMultipli User Manual for more details.

EZMultipli Multisensor

ezmultipli200The EZMultipli performs five functions:

  1. Motion Sensor
  2. Temperature Sensor
  3. Light Level Sensor
  4. Color LED indicator
  5. Z-Wave Range Extender

What sets the EZMultipli apart from the typical battery-powered motion sensors is that it is wall powered so you never need to change the batteries! Because EZMultipli is wall powered it functions as a Z-Wave range extender which adds another routing node in the Z-Wave mesh network. If your Z-Wave network is a little flakey and you have some nodes that are having trouble communicating reliably, adding an EZMultipli or two will provide additional routes for every Z-Wave node to talk to every other node. Then the sensors are a bonus!

Because EZMultipli is firmly plugged into an outlet, there is no mounting required. No screws, no tape, no mending of the wall when you move. This makes EZMultipli ideal for apartments, offices or other short-term uses where you’ll want to take it with you when you leave. But what if you don’t have an outlet in the right spot for detecting motion? Ah… that is a problem and not every device can solve every problem. EZMultipli was specifically designed with a wide-angle lens to capture motion in any direction out to about 12 feet. So it doesn’t have to be placed in the perfect location to be able to detect motion where you need it. It is ideal for kitchens, bathrooms and garages which often have unused outlets in handy locations. You can also put it in unused outlets under a table or chair. Obviously it isn’t much good behind a couch or other solid furniture. Some locations like hallways will have to use a battery-powered motion sensor because the sensor has to be in just the right place and there are no outlets nearby.

STEZMAddThingAnother placement problem involves pets. If you put the sensor down low in a typical wall outlet, virtually any pet from a cat to a small dog will trigger the motion sensor. You have to either put the sensor up on a higher outlet or in a room that pets are not allowed in when you need to detect if a burglar is in your home. In my case we always close off our home office from the pets during the day when we are not home. Only the EZMultipli in the office and the one in the garage will send us a text when the home is in Away mode.

Setup and Configuration

STEZMfullInclude EZMultipli into the ST hub in the normal way: Just click on the +Add A Thing button on the ST app. Next then press the button on the side of EZMultipli. You should get a device called “EZMultipli” which is the default name.
Rename the device if you want then click on Save and then OK.
You should now have the screen shown here. The main Tile at the top will turn the LED behind the lens on and off or if you click on the color circle you can change it to be any of 8 different colors. The motion sensor, temperature sensor and luminance sensor are on the next row of tiles. The REFRESH button will force the ST hub to poll EZMultipli to be certain it has the latest sensor readings. We’ll get to the CONFIGURE tile in the next section.

STEZMConfigAt this point, the best thing to do is to click on the Gear icon in the upper right corner. This brings you to the configuration screen where you can adjust various parameters to suite your needs. Generally the defaults will work fine for most applications. The next section will get into more details.

The temperature and luminance sensors are set to send a report every 6 minutes which is fine for an average sized Z-Wave network. However, if you have a lot of nodes (more than 50) in your network and specifically more than a few EZMultiplis, it would be better to reduce the frequency of sensor updates just to keep the traffic from getting clogged up. If you set the report frequency to 0 then that sensor will never send an update so if you’re not interested in a sensor then make its value 0. Click on DONE and then CONFIGURE to push the configurations down to the EZMultipli.

Initially the temperature and light level sensors may not have a value but in a few minutes the sensors will send readings the values will update.

For the first several minutes after joining the sensor to the ST hub the LED will blink white anytime is detects motion. You can use this to make sure it will detect motion where you want it too. If it is not detecting motion, try flipping it around in the outlet as this will change the orientation of the lens elements. Remember that EZMultipli detects MOTION, not people. So the people have to be moving within range of the sensor otherwise the lights will turn off while they are still in the room!

Configuration Parameters

Screenshot_20170410-125808EZMultipli has five configuration parameters that change how the device responds to various events.

  1. OnTime – Number of minutes the light will stay on when motion is not detected
  2. OnLevel – Dim level sent to Association Group 2 nodes
  3. LiteMin – Number of minutes between luminance reports
  4. TempMin – Number of minutes between temperature reports
  5. TempAdj – Temperature adjustment and 1/10ths of a degree F

Generally ST works best with a fairly short OnTime parameter of 2 minutes. This allows a SmartApp to control the amount of time a light stays on after motion is no longer detected. The current Device Type doesn’t provide access to the Z-Wave Association command class so that feature of the EZMultipli is not available. Thus, it is best to leave the OnTime at 2 minutes and configure your SmartApps to do all the other work. Refer to the EZMultipli User Manual for details on the other parameters.

After changing any configuration settings, be sure to click on the CONFIGURE button to push the configuration settings to EZMultipli.

SmartApps

STEZMSmartAppNow that you have a motion sensor, the most common thing is to turn a light on or off when there is motion or not. In ST that is done using a SmartApp. Go back to the home screen and click on Automation at the bottom. Then click on + Add a SmartApp and select Lights and Switches and then Smart Lights. You can then easily pick the light(s) you want to control and which sensor will trigger which lights as shown here. Turn on the Turn Off After Motion Stops and then pick a reasonable amount of time for the lights to turn off then no-motion is detected. In a hallway, this number can be quite short like 2 or 3 minutes. In a kitchen it needs to be more like 15 minutes and if sitting in a living room reading you might want it to be more than an hour. You can also set different timeouts using multiple SmartApps that are only active at certain times of the day. For example, I significantly extend the OFF time during meal times because while sitting at our kitchen table I don’t want the lights to turn off while we’re eating but no one has moved enough for the kitchen sensor to detect motion (which is next to the sink, not the table).

Color LED

The color LED of the EZMultipli is easily controlled using the phone app. But the more interesting use is to display things like when your garage doors are open or what the weather will be today (Blue for nice blue sky, Yellow for sunny and warm, Red for blistering HOT, White for snow, Green for rain, etc.). I’ll follow up later with more posts on how to do fun things like this with SmartThings and EZMultipli.

EZMultipli How-To for Vera

vera_logo_tmVera is one of the more popular home automation platforms and with the UI7 release it fully supports the EZMultipli muli-sensor. The main selling points of Vera are “no monthly subscription fee, no contracts and no hassles” which pretty much sums Vera up. Vera is an easy to use system with good support and an active user community who are often quicker to respond to questions than the Vera technical support team.  Vera has several platforms to choose from. I’m using the VeraEdge in this How-To which for only $69 is a good deal. This post will show you how to get the most out of Express Controls EZMultipli Z-Wave MultiSensor and specifically how to use it with Vera UI7. Refer to the EZMultipli User Manual for more details.

EZMultipli Multisensor

ezmultipli200The EZMultipli performs five functions:

  1. Motion Sensor
  2. Temperature Sensor
  3. Light Level Sensor
  4. Color LED indicator
  5. Z-Wave Range Extender

What sets the EZMultipli apart from the typical battery-powered motion sensors is that it is wall powered so you never need to change the batteries! Because EZMultipli is wall powered it is a Z-Wave range extender and adds another routing node in the Z-Wave mesh network. If your Z-Wave network is a little flakey and you have some nodes that are having trouble reporting in reliably, adding an EZMultipli or two will provide additional routes for every Z-Wave node to talk to every other node. The sensors are just a bonus!

Because EZMultipli is simply plugged into an outlet, there is no mounting required. No screws, no tape, no mending of the wall when you move. This makes EZMultipli ideal for apartments, offices or other short-term uses where you’ll want to take it with you when you leave. But what if you don’t have an outlet in the right spot for detecting motion? Ah… that is a problem and not every device can solve every problem. EZMultipli was specifically designed with a wide-angle lens to capture motion in any direction out to about 12 feet. So it doesn’t have to be placed in the perfect location to be able to detect motion where you need it. It is ideal for kitchens, bathrooms and garages which often have unused outlets in handy locations. You can also put it in unused outlets under a table or chair. Obviously it isn’t much good behind a couch or other solid furniture. Some locations like hallways will have to use a battery-powered motion sensor because the sensor has to be in just the right place and there are no outlets in that place.

Another placement problem involves pets. If you put the sensor down low in a typical wall outlet, virtually any pet from a cat to a small dog will trigger the motion sensor. You have to either put the sensor up on a higher outlet or in a room that pets are not allowed in when you need to detect if a burglar is in your home. In my case we always close off our home office from the pets during the day when we are not home. Only the EZMultipli in the office and the one in the garage will send us a text when the home is in Away mode.

Setup and Configuration

The first and most important step is to make sure you are running Vera Firmware Version 1.7.2406 or later. Check the firmware via Settings->Firmware and the screen will show you which version you currently have and if there is an upgrade available. You can include the EZMultipli into Vera but previous firmware versions didn’t understand the Z-Wave Notification command class used by EZMultipli so it isn’t very usable without at least this version.

Include EZMultipli into Vera in the normal way: Devices->Add Device->Generic Z-Wave Device->Next->Next then press the button on the side of EZMultipli. You should get a device called “EZM” which is the default name. Pick a room. Then click on FINISH.

You’ll then have three new devices:

  1. vera3sensorsEZM which is the motion sensor
  2. _Temperature Sensor which is obviously the temperature sensor
  3. _Light Sensor which is the light level in the room

Initially the temperature and light level sensors don’t have a value but in a few minutes the sensors will send readings the values will update. Rename the devices to more meaningful names  by clicking on the > and entering a new name. These three sensors are the main sensors – but where is the color LED? Currently you have to load a Plug-in to use the color LED. Hopefully in a future release Vera will add support for the Z-Wave Color Command Class and we won’t need the plugin anymore. To add the plugin click on Apps->Install Apps and then enter “EZM” into the search bar and the EZMultipli Color Utility will come up. Click on DETAILS and then install the app. While you’re at it, search for DataMine2 graphing plug in and install that too.

vera4sensorsWith the plugin installed there are three more devices but the only one that is interesting is the EZM Light 2 which has the 8 LED color buttons as shown here. Assign that device to the same room as the other EZMultipli sensors. I create a virtual room called ZZZVirtual to put all the extra stuff I don’t normally want to see so it’s at the bottom of the screen.

If you wave your hand in front of the motion sensor, the EZM device will go red indicating the sensor has detected motion. If there is no motion for 10 minutes it will go back to being grey which means no-motion. NOTE! The motion sensor sends a MOTION command when motion is initially detected. Then, only after the OnTime number of minutes of there being a complete lack of motion will the No-MOTION command be sent. The sensor does NOT send a motion command every time it detects motion (though you can enable it to do that).

Vera Scenes

The most common thing you want to do with a motion sensor is to turn on a light when motion is detected and turn it back off again when no one is in the room. With Vera, we do this with Scenes. Click on Scenes->Add Scene. This will open up a wizard that will guide you thru the process. Step 1 picks the device which in this case is EZM and we’ll choose “Whenever EZM detects motion whether is armed or disarmed”. Step 2 is to pick a light to control. In this case we’ll chose the EZM Color and chose the green color. Click on Next step, scroll down and name the scene then click Finish. Next click on the RUN button just to be sure the scene works. There are tons of other options you can choose as part of the scene so try them out and experiment. You can set the scene to only run at certain times of the day or certain days of the week. This is handy for example to set the brightness of a dimmer to be only 20% late at night when all you really want is a night lite to get down a hallway without stepping on the toys your kids left in the hallway.

Configuration Parameters

EZMultipli has five configuration parameters that change how the device responds to various events.

  1. OnTime – Number of minutes the light will stay on when motion is not detected
  2. OnLevel – Dim level sent to Association Group 2 nodes
  3. LiteMin – Number of minutes between luminance reports
  4. TempMin – Number of minutes between temperature reports
  5. TempAdj – Temperature adjustment

The most important parameter is the OnTime parameter. As the name implies, OnTime is the number of minutes the lights will be ON after motion stops being detected. When you walk within range of the motion sensor, Vera receives a Motion event immediately. Vera can then turn lights on or if you configure association group 2 EZMultipli can control the lights directly. Let’s say you then walk around the room for 5 minutes and then walk out of the room. Then 10 minutes later, Vera will be sent a No-Motion event. Why 10 minutes and not 5? Because OnTime is set to 10 minutes which starts counting down when you left the room, not when you entered. Here are some recommended values for the OnTime parameter:

  • OnTime=0 disables sending OFF commands. Only ON commands are sent. This setting is not recommended.
  • OnTime=1 is the minimum setting. For example, late at night you could set the timeout to be only the 1 minute since you’re probably just passing thru. But at dinner time you want a much longer timeout of 30 minutes to prevent Vera from turning the lights off at the dinner table while you are eating dinner. Having to wave your arms in the air in the middle of dinner to turn the lights back on will lower your Wife-Acceptance-Factor (WAF).
  • OnTime=5 minutes is generally a good setting for hallways or other places that you are actively moving thru and only need the lights on while moving thru the space
  • OnTime=10 default setting which is OK for most use cases.
  • OnTime=30 minutes is recommended for rooms where people might be sitting for some time such as in an office or watching TV.
  • OnTime=60 minutes or more might be necessary for a room where someone might be sitting for a long time perhaps reading.

Remember that EZMultipli detects MOTION, not people. So the people have to be moving within range of the sensor otherwise the lights will turn off while they are still in the room!

veraconfigTo change parameters, click on the > on the EZM device and then the Device Options to get the screen shown here. If there are no configuration settings shown, click on the Add Configuration Settings button and one will be created. Select “1 byte dec” in the Data Size field then enter the desired value for the OnTime parameter in the Desired Value field. Then click on Save Changes.

Refer to the EZMultipli User Manual for details on the other parameters. The challenge with the Vera parameter user interface is that it only uses unsigned integers whereas many parameters are signed values. For example, parameter 5 is the TempAdj parameter which is in 1/10ths of a degree Fahrenheit and is a signed number. So if you want to adjust the temperature readings of EZMultipli up by 1.2 degrees you enter 12. But if you want to lower the readings by 1.2 degrees you have to enter the number of 256-12=244. The other parameters are unsigned 1 byte integers so they don’t require this crazy math.

Z-Wave Association Direct Control of Lights

EZMultipli also supports the Z-Wave Association Command class. Associations are used to tell EZMultipli to send ON/OFF commands directly to other Z-Wave devices with out requiring a scene or even talking to Vera. The advantage of Associations is that it results in very fast response times and even if Vera isn’t running the lights will come on and off automatically. Note that if EZMultipli controls a device via Associations, the Vera UI won’t show the new state of the controlled device until it gets around to polling it which can be several minutes later.

Setting associations in Vera involves first clicking on the EZM device and then Device Options. Associations are just below the configuration parameters. Enter a 2 in the Group ID field and then Click on Add Group. Refresh the screen and there should now be Group ID 2. Click on SET and choose the device you want to directly control using EZMultipli. Finally click on Apply Changes. Once this is set, the device that is now associated will automatically turn on when motion is detected and turn off after OnTime minutes when motion is no longer detected.

 

Well that should get you started using EZMultipli with Vera. Future posts will include more advanced usage of the color LED and how to use the other sensors. If you have an interesting use case for the EZmultipli please add a comment or send an email to DrZwave at ExpressControls.com.

EZMultipli How-To for HomeSeer HSM200

HomeSeer HS3 is my favorite smart home software. I use the HomeSeer HomeTroller Zee S2 to run my home. The Zee S2 is a Raspberry Pi (RPi) with a built-in Z-Wave interface that runs the HomeSeer HS3 software. The part I like the most about HomeSeer is that the processing runs locally on the RPi which makes the response time very snappy compared to the cloud based systems. The RPi has plenty of horsepower to serve the web pages and run the events that control my home automatically and it does it all with a mere 6 Watts of power. Compared to having running on a PC 24/7/365 at typically 60+ watts, the RPi is a green and low-cost alternative. HomeSeer has a very active user community on their forums and if you have a question on how to do something, just ask and someone will respond quickly. HomeSeer sells the EZMultipli under their own brand name as the HSM200. For this post I’m going to show you how to get the most out of Express Controls EZMultipli Z-Wave MultiSensor and specifically how to use it with HomeSeer. Refer to the User Manual for more details on EZMultipli/HSM200.

ezmultipli200EZMultipli Multisensor

The EZMultipli performs five functions:

  1. Motion Sensor
  2. Temperature Sensor
  3. Light Level Sensor
  4. Color LED indicator
  5. Z-Wave Range Extender

What sets the EZMultipli apart from the typical battery-powered motion sensors is that it is wall powered so you never need to change the batteries! Because EZMultipli is wall powered it is a Z-Wave range extender and adds another routing node in the Z-Wave mesh network. If your Z-Wave network is a little flakey and you have some nodes that are having trouble reporting in reliably, adding an EZMultipli or two will provide additional routes for every Z-Wave node to talk to every other node. The sensors are just a bonus in that case!

Because EZMultipli is simply plugged into an outlet, there is no mounting required. No screws, no tape, no mending of the wall when you move. This makes EZMultipli ideal for apartments, offices or other short-term uses where you’ll want to take it with you when you leave. But what if you don’t have an outlet in the right spot for detecting motion? Ah… that is a problem and not every device can solve every problem. EZMultipli was specifically designed with a wide-angle lens to capture motion in any direction out to about 12 feet. So it doesn’t have to be placed in the perfect location to be able to detect motion where you need it. It is ideal for kitchens, bathrooms and garages which often have unused outlets in handy locations. You can also put it in unused outlets under a table or chair. Obviously it isn’t much good behind a couch or other solid furniture. Some locations like hallways will have to use a battery-powered motion sensor because the sensor has to be in just the right place and there are no outlets in that place.

Another placement problem involve pets. If you put the sensor down low in a typical wall outlet, virtually any pet from a cat to a small dog will trigger the motion sensor. You have to either put the sensor up on a higher outlet or in a room that pets are not allowed in when you need to detect if a burglar is in your home. In my case we always close off our home office from the pets during the day when we are not home. Only the EZMultipli in the office and the one in the garage will send us a text when the home is in Away mode.

HomeSeer Motion Events

Now that we have a sensor in an outlet that will detect motion, what do we do with that information? Naturally the most common thing is to turn lights on and off and to send a text when motion is detected and the house is in Away mode (security is enabled).ezmeventonoff

These two events are the most basic ways to control a light with motion. The light will come on when motion is detected but only if it is after sunset and before sunrise. When the sensor has not detected motion for several minutes it will change state to No Motion and the light will be turned off. Note that I also turn the light off at sunrise just to be sure its off during the daytime. The light I’m controlling with these events is the color LED of the EZMultipli itself and you can set the color to any of eight different colors.

Z-Wave Association Direct Control of Lights

EZMultipli also supports the Z-Wave Association Command class. Associations are used to tell EZMultipli to send ON/OFF commands directly to other Z-Wave devices without requiring events or even talking to HomeSeer. The advantage of Associations is that it results in very fast response times and even if HomeSeer isn’t running the lights will come on and off automatically.

Setting associations in HomeSeer involves first clicking on the root device of the EZMultipli or HSM200. Then click on the Z-Wave tab as shown here.

ezmhs3assoc

Click on the little yellow triangle to open the Associations menu. Next click on Update which will cause HomeSeer to double-check the associations set in the device. HomeSeer automatically assigns itself to Group 1 so that it will get the Motion/NoMotion Notifications. To turn lights on and off directly from EZMultipli, Click on the Association Group drop down menu and select Group 2. Then pick the device to be controlled and then Add Association. I recommend then clicking on Update again just to be sure. It is also a good idea to click on Full Optimize which will improve the Z-Wave routing thru the mesh network. Once this is done, the light in Group 2 will turn on when motion is detected and off after motion is no longer detected for 10 minutes.

Configuration Parameters

EZMultipli has five configuration parameters that change how the device responds to various events.

  1. OnTime – Number of minutes the light will stay on when motion is not detected
  2. OnLevel – Dim level sent to Association Group 2 nodes
  3. LiteMin – Number of minutes between luminance reports
  4. TempMin – Number of minutes between temperature reports
  5. TempAdj – Temperature adjustment

The most important parameter is the OnTime parameter. As the name implies, OnTime is the number of minutes the lights will be ON after motion stops being detected. When you walk within range of the motion sensor, HomeSeer is sent a Motion event immediately. HomeSeer (or via Group 2) can then turn lights on. Let’s say you then walk around the room for 5 minutes and then walk out of the room. Then 10 minutes later, HomeSeer will be sent a No-Motion event. Why 10 minutes and not 5? Because OnTime defaults to 10 minutes which starts counting down when you left the room, not when you entered. Here are some recommended values for the OnTime parameter:

  • OnTime=0 disables sending OFF commands. Only ON commands are sent. This setting is not recommended with HomeSeer.
  • OnTime=1 is the minimum setting. Use this value in collaboration with HomeSeer Timers to vary the off time based on the time of day. For example, late at night you could set the timeout to be only the 1 minute since you’re probably just passing thru. But at dinner time you want a much longer timeout of 30 minutes to prevent HomeSeer from turning the lights off at the dinner table while you are eating dinner. Having to wave your arms in the air in the middle of dinner to turn the lights back on will lower your Wife-Acceptance-Factor (WAF).
  • OnTime=5 minutes is generally a good setting for hallways or other places that you are actively moving thru and only need the lights on while moving thru the space
  • OnTime=10 default setting which is OK for many use cases.
  • OnTime=30 minutes is recommended for rooms where people might be sitting for some time like an office or watching TV.
  • OnTime=60 minutes or more might be necessary for a room where someone might be sitting for a long time perhaps reading.

Remember that EZMultipli detects MOTION, not people. So the people have to be moving within range of the sensor otherwise the lights will turn off while they are still in the room!

Refer to the EZMultipli User Manual for details on the other parameters.

To change parameters, click on the root device from the Home screen and then the Z-Wave tab and then the Settings yellow triangle to get the screen shown here.

ezmhs3config

 

 

HomeSeer knows about parameters 1, 3 and 4 but you can adjust any parameter via the Set Configuration Parameters box at the bottom of the screen. You have to “Use at your OWN risk” but the parameters are straightforward enough – I think you can handle it. The biggest challenge with parameters is setting values greater than 127. Officially all parameters are supposed to be twos-complement but you can enter values greater than 127 by using the twos-complement equivalent.

Well that should get you started using EZMultipli with HomeSeer. Future posts will include more advanced usage of the color LED and how to implement a variable timeout. If you have an interesting use case for the HSM200 please add a comment or send an email to DrZwave at ExpressControls.com.