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 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:

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.

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.

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

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.

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.

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.

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.

Hub Sends User Code Set

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

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.

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

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

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

Lock sends the Hub a Date GET

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

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

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

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.

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

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.

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);

}

Problem: How to OTA a co-processor via Z-Wave?

You have a second MCU or other data files you want to OTA via Z-Wave. How can you reuse the Bootloader firmware to verify the signature and decrypt the data?

The code to verify and decrypt the file already exists in the bootloader and is known good. Reusing the existing bootloader code is smaller and safer than re-inventing the wheel - or in this case encryption.

The attached project is a modified Z-Wave Door Lock Key Pad sample application that demonstrates how to OTA code/data other than the Z-Wave firmware. OTA of the Z-Wave firmware works in the sample application already - but first the encryption keys MUST be generated. See https://www.silabs.com/community/wireless/z-wave/knowledge-base.entry.html/2019/04/09/z-wave_700_ota_ofe-i00M on how to generate the keys. See the two .BAT files in the comments section which will run all the necessary commands for you. They are also included in this .sls file in the KEYS directory. You MUST create your own project keys to OTA either the Z-Wave Firmware or any other data.

To OTA other types of files you need to start with a binary file. Most microprocessor development environments will output a binary file so use that instead of a HEX file. If you have an Intel hex or Mototola S record file, use a utility like SREC_CAT to convert it to a binary file. SREC_CAT can convert just about any file type into any other file type. If the file is more than 200K bytes, you will need to break the file into 200K or smaller files and OTA each, one at a time. Doing that is beyond the scope of this project. Note there is no need to encrypt the file. We will be using Commander to sign and encrypt it using the keys generated here.

Theory of Operation:

Changes to the SSv4 DoorlockKeyPad sample project are indicated with the comment "AKER" - search for these to find what changed. You can also diff the files with a fresh copy of the DoorLockKeyPad sample app from SSv4. Most of the code to support OTA of an external processor is in this file. A few changes have been made to ota_util.c in ZAF_CommandClasses_FirmwareUpdate but these are expected to be included in a future release of the SDK (currently tested on 7.13). 

Commander is used to generate a pair of public and private keys. The private key is then programmed into every device to be OTAed. Commander then encrypts and signs the binary file and wraps it with bootloader tokens. The gbl file is downloaded, the signature checked and the encrypted data is then passed to a callback function 64 bytes at a time. You then have to store the data or pass it to the external MCU. This example simply prints the data out a UART.

Procedure:

Step 1: Generate the keys

There two .BAT files in the KEYS directory for this project. These are windows script files. For other platforms you can easily convert them to the platform specific commands. See the comments in the files for more details. In a windows shell type:
   GenGblToken.bat
This will use Commander to generate a project set of keys in the files vendor_*.*. Only execute this command ONCE. The same keys are used for the duration of the project. If you change the keys then you cannot OTA the devices as the keys no longer match.

Step 2: Program the key into a devkit and every DUT

Each device manufactured must have the private key programmed into FLASH. Use the PgmToken.bat to program the key into a target device connected via USB. Note that EVERY unit manufactured must have these keys programmed into it.

Step 3: Generate the .gbl file

Create the .gbl file from the binary file using the following command:
   commander gbl create <OTA_FileName>.gbl --metadata <BinaryFile> --sign vendor_sign.key --encrypt vendor_encrypt.key
The --metadata option will wrap the binary data with the necessary tokens for the bootloader to parse the data. Do not use the --compress option. If the data needs to be compressed, use your own algorithm for that. There are 3 sample binary files in the KEYS directory - a small .WAV audio file, a large .M4A audio file and a PNG image file. Use the command above to wrap the file with the necessary tokens for OTA.

 Step 4: OTA the .gbl file

Use the PC Controller or other application to send the gbl file over Z-Wave. Once the entire file has been sent and the CRC checked to be good, the FinishFwUpdate function is called to begin processing the image. Note that in the PCC you have to first GET the Current Firmware, then select the Target: 1 to download the metadata. Then click on UPDATE and the OTA will begin. Connect a terminal to the VCOM port of the WSTK to view the data streaming down during the OTA. Once all the data is sent down, the signature is checked and the decrypted data is sent out the UART. This is where you would need to change the code to store the data instead of printing it out the UART.

Step 5: Verify the Signature and pass in the callback function

The bootloader_verifyImage() function is called and the metadataCallback function is passed in. bootloader_verifyImage first returns a zero if the signature matches. If the signature fails an error value is returned giving some details on why it failed. The time to verify the signature can be fairly long depending on the size of the image so the watchdog timer is disabled during the processing.

Step 6: MetadataCallback passes blocks of 64 bytes of the decrypted data

The function passed in to bootloader_verifyImage is called with a pointer to the data and the number of bytes in each block. The size of the block can vary up to 64 bytes. In this example the data is simply printed out the UART. In your application you would replace this function with code to store the data as needed on the other MCU or external NVM.

Step 7: Reboot

It is recommended to reboot after the image data has been stored to ensure the FLASH is cleaned up properly. The current demo however does not reboot.

Note: This is an SSv4 SDK 7.13 sample but the same concepts should work in SSv5. The changes to ota_util.c will be folded into the SDK in a future release but for now those changes are necessary.

@peter milligan - if you're getting the error "0x03 not upgradeable" that's usually because there is no bootloader in flash. The easy way to tell is to enable DEBUGPRINT and you'll see a message that there is no bootloader. Anytime you Unlock Debug which does a complete erase of the entire FLASH the bootloader is also erased and has to be reprogrammed.

@yong - as Richard mentioned, the same file can OTA all devices that are identical. The keys described here should be different for each PROJECT but are the same for each unit in production. So a light switch and a dimmer switch would each have different keys as they are different products. But if you manufacture 100K dimmer switches all with the same firmware then they can all be updated with the same OTA file. Even if you manufacture 50K with one firmware version and then make a few minor changes (but it is still the same product) and make another 50K with that version, then release a new firmware with more minor changes than that 3rd OTA file can update all 100K units.

@Tony Zhao - This AES key is used to encrypt and sign the OTA image files. This way you can be secure in publishing the OTA file on the internet and a bad actor cannot (easily) use the file to make counterfeit copies of your product. By SIgning the OTA image then only the proper image can be OTAed to you device and thus prevent malicious code from being downloaded.

The Silicon Labs EFR32 family of IoT microcontrollers are very flexible and can do a ton of cool stuff. However, along with all that flexibility comes a lot of complexity. With that complexity are default settings that work fine for many applications but in some cases you want to dig into the details to come up with an optimal solution. In this post I’ll show how to speed up the wake up time for the Z-Wave ZGM130S chip from a GPIO.

But first – a caveat: This post applies to Z-Wave SDK 7.13.x. Future releases of the SDK may have different methods for sleep/wake and thus may require a different solution.

The Problem

Frequently Listening Routing Slaves (FLiRS) devices like door locks and many thermostats spend most of their time in Energy Mode 2 (EM2) to conserve battery power. Once per second they wake up briefly and listen for a Beam from an always-on device. If there is a beam, the FLiRS device will wakeup and receive the Z-Wave command. This allows battery powered devices to use very little power but still be able to respond to a Z-Wave command within one second. FLiRS devices use more battery power than fully sleeping devices like most sensors which use Hibernate Sleep mode (EM4). To wake every second the ZGM130 has to wake quickly and go right back to sleep to minimize power. The problem with EM4 is that it takes a few tens of milliseconds to wake up as the entire CPU and RAM have to be initialized as they were powered down to save power. For a FLiRS device, it’s more efficient to keep RAM powered but in a low-power state and resume quickly to go right back to sleep if there is no beam. Typically the ZGM130 can wake up in about 500 microseconds from EM2. But in many cases this is still too long of a time to stay awake if there are other interrupts such as UARTs or other sensors.

The scope shot above shows the processing that takes place by default on the ZGM130S. In this case I am using a WSTK to drive the SPI pins of another WSTK running the DoorLockKeyPad sample application. The chip is in EM2 at the start of the trace. When SPISEL signal goes low, the chip wakes up. But it is running on the HFRCO oscillator which is not accurate enough to run the radio but it is stable and usable in just a few microseconds. Thus, the SPI clock and data is captured in the USART using this clock. However, by default the Interrupt Service Routine is blocked waiting for the HFXO to stabilize. The 39MHz HFXO crystal oscillator has the accuracy required for the radio.

The question is what’s going on during this 500usec? The answer is the CPU is just waiting for the HFXO to stabilize. Can we use this time to do some other work? Fortunately, the answer is YES! The challenge is that it takes some understanding and some code which I’ll describe below.

The Solution

There are three functions that do the majority of the sleep processing. These are provided in source code so you can read the code but you should not change it. Instead you’ll provide a callback function to do your processing while the chip is waking up.

Simplified Sleep Processing Code:

1. SLEEP_Sleep in sleep.c: The main function called to enter sleep
   1. CORE_ENTER_CRITICAL – PRIMASK=1 mask interrupts
   2. DO-WHILE loop
      1. Call enterEMx() – this is where the chip sleeps
      2. Call restoreCallback (return 0 to wake, 1 to sleep)
   1. Call EMU_Restore – waits for HFXO to be ready ~500us
   2. CORE_EXIT_CRITICAL – ISRs will now run
2. enterEMx() in sleep.c:
   1. sleepCallback called
   2. Call EMU_EnterEM[1-4]
   3. wakeupCallback after returning from EMU_EnterEMx
3. EMU_EnterEM2 in em_emu.c:
   1. Scales voltage down
   2. Call EMU_EM23PresleepHook()
   3. __WFI – Wait-For-Interrupt instruction – ZGM130 sleeps here
   4. Call EMU_EM23PostsleepHook() ~ 17usec after wakeup
   5. Voltage Scale restored which takes ~20us

The code is in sleep.c in the SDK which has a lot more detail but at a high level this is what you need to know. The important part to understand here is where the “hooks” are and how to use them.

• Use Sleep_initEx() to assign:
  • sleepCallback – called just before sleeping
  • restoreCallback – Return 0 to wake, 1 to sleep
  • wakeupCallback – called after waking
  • Sleep_initEx() input is a pointer to a structure with the three callbacks or NULL if not used
• Define the function:
  • EMU_EM23PresleepHook()
  • EMU_EM23PostsleepHook()
  • These are both WEAK functions with nothing in them so if you define them then the compiler will install them

The two EMU_EM23* weak functions are run immediately before/after the Wait-For-Interrupt (WFI) instruction which is where the CPU sleeps. These are very low level functions and while you can use them I recommend using the callbacks from Sleep_initEx().

The SLEEP_initEx() function is the one we want to use and in particular the restoreCallback. The comments around the restoreCallback function talk about restoring the clocks but if the function returns a 0 the chip will wake up and if it returns a 1 then it will immediately go back to sleep which is what we want! You can use the other two hooks if you want but the restoreCallback is the key one since it will immediately put the chip back to sleep if everything is idle.

The key to using ANY of these function is that you CANNOT call ANY FreeRTOS functions! You cannot send any Z-Wave frames or call any Z-Wave function as they all require the RTOS. At this point in the wakeup processing the RTOS is not running! All you can do in these routines is to capture data and quickly decide if everything is idle and to go back to sleep. If there is more processing needed, then return 0 and wait for the event in the RTOS and process the data there. You also don’t want to spend too much time in these routines as it may interfere with the timing of the RTOS. A hundred microseconds is probably fine but longer you should wait for the HFXO.

In ApplicationInit() you will call Sleep_initEx() like this:

const SLEEP_Init_t sleepinit = {NULL, NULL, CheckSPI};
...
ZW_APPLICATION_STATUS ApplicationInit(EResetReason_t eResetReason) {
...
SLEEP_InitEx(&sleepinit); // call checkSPI() upon wakeup from EM2.
...
}
...
uint32_t CheckSPI(SLEEP_EnergyMode_t emode) { 
	uint32_t retval=0; // wake up by default
	if (GPIO_IntGetEnabled() & 0x0000AAAA) { // Check SPI
		GPIO_ODD_IRQHandler(); // service the GPIO interrupt
		// wait for all the bytes to come in and compute checksum 
		NVIC->ICPR[0] = NVIC->ICPR[0]; //clear NVIC pending interrupts
		if (!SPIDataError && !IsWakeupCausedByRtccTimeout())	{
			 retval=1; // go back to sleep!
		}
	}
	return(retval); // 0=wakeup, 1=sleep
}

Recall that every second the FLiRS device has to check for a Z-Wave beam which is triggered by the RTCC timer. Thus the check for IsWakeupCausedByRtccTimer ensures that the beaming still works.

This scope shot shows the wake up processing of the ZGM130S:

1. SPISEL_N SPI chip select signal goes low triggering a GPIO_ODD interrupt
   1. The chip wakes up, the HFRCO begins oscillating
2. HFRCO begins oscillating in a few microseconds
   1. Once HFRCO is running, the peripherals are functional
   2. SPI data can begin shifting once the HFRCO is running
   3. The default HFRCO frequency is 19MHz but can be increased
   4. Higher frequencies for HFRCO also may need more wait states for the CPU and will use more power
3. The WFI instruction that put the CPU to sleep is exited here
   1. EMU_EM23PostSleepHook function is called if defined
   2. After returning from PostSleepHook, the VSCALE is returned to full power which takes about 10usec
   3. It is best to wait for the voltage to be powered up to ensure all logic is running at optimal speeds
4. EMU_EnterEM2 is exited and restoreCallback is called if initialized
   1. This is the function where the ISR should be called to process data
   2. If the data says things are idle and want to go back to sleep, return 1
   3. If more analysis is needed, then return 0
   4. Carefully clear the interrupt bits
      1. First clear the peripheral Interrupt Flags
      2. Then clear the NVIC Interrupt pending register
         1. NVIC->ICPR[n]=NVIC->ICPR[n] where n is 0-1 depending on your interrupt
   5. Make sure there aren’t other reasons to wake up fully
      1. !IsWakeupCausedByRtccTimeout() is the 1s FLiRS interrupt
      2. There may be other reasons to wake up which is application dependent
5. In this example the SPI data is being fetched from the USART at each toggle of the GPIO
   1. The final toggle shows that the checksum was computed and the data is idle so go back to sleep
6. The chip returns back to sleep in a few more microseconds
   1. Total processing time of this interrupt is less than 200usec which is a fraction of the time just waiting for the HFXO to stabilize
   2. Much of that time is receiving and processing the SPI data
   3. It is possible to sleep in under 50usec if the check for idle is quicker

If your peripheral processing will take significantly less than 500usec, then it may be more efficient to process the data using the HFRCO and not wait for the HFXO to power up. But if your application needs more processing, then you are probably better off waiting. Each application must make their own calculations to determine the most efficient path.

What About Sleeping Devices?

Fully sleeping devices (EM4 also known as RSS – Routing Sleeping Slaves) have entirely different wake/sleep processing. For sleeping slaves the processor and RAM have to be re-initialized and the chip essentially boots out of reset. All that initialization takes quite a bit of time – a few tens of milliseconds. If your device needs to do a lot of frequent checking of a sensor, then it might make more sense to force it to stay in EM2 by setting a Power Lock to PM_TYPE_PERIPHERAL. For more details on power locks see INS14259 section 7.6. Deciding which way to go is application specific so you have to make the calculations or measurements to find the right balance for your project.

This is a complex posting but I hope I’ve made it clear enough to enable you to optimize your application firmware. Let me know what you think by leaving a comment below or on my blog at drzwave.blog.

This guide uses the DoorlockKeyPad built under 7.12.2 but the same basic concepts apply to any sample app and your project. A generic KBA on upgrading SDKs for Bluetooth projects provides general insights but this document is specific to this Z-Wave release.

1. Update Simplicity Studio (SS)
   1. From the Launcher perspective, click on the download icon and then click on Update All
   2. Close Simplicity and restart (just to be safe) - SS may ask to do this as well
   3. Click on the download button again, click on Package Manager, click on SDK tab, click on each Update button (keep scrolling down). I recommend restarting SS between each update.
2. Set the Preferred SDK to the latest release
   1. Plug in a WSTK devkit or select the ZGM130S in the MyProduct window
   2. From the Launcher perspective, click here:
   3. Select the Gecko SDK Suite 7.13.3.0
   4. Now when you want to create a new project it will start with the 7.13.3 release
3. At this point there are 3 options for upgrading:
   1. Open a new 7.13.3 project and then copy your changes into it
   2. Import/Export parts of your project into a new 7.13.3 project
   3. Manually edit the .cproject and .project files
4. Far and away the best option is the first one - option A
   1. The advantage of this is that you get all the latest and newest files of the Z-Wave Application Framework (ZAF), emlib, linker scripts, and lots of other stuff
   2. The challenge is that you have to plug all of your changes back into the sample application
   3. If you’ve made most of the changes in files other than the sample application, then the changes are probably easy to install
   4. However, if you’ve made a lot of changes to the sample application source code file it will take more time
   5. Option B or C might be the way to go but at some point it might still be better to go back to option A. Option A is fairly straightforward as the sample apps in the 7.13.3 release already work so just copy in your changes a few at a time and keep recompiling to make sure you haven’t broken something.
   6. If taking option A you’re done! No need to read any further! Create the new sample app and start plugging in your changes
   7. If you’re not taking option A, pick one of the 2 options below. The choice of B or C is up to you and primarily how confident you are in fixing XML files. If you think you can fix an XML file, then use option C otherwise use B.
5. Option B - Import/Export parts of your project into a new 7.13.3 project:
6. This option avoids manually editing the XML file but requires importing/exporting several files and using the GUI to fix paths. The advantage however is that you shouldn’t break the XML file which is easily done with manual editing.
7. Export the project created with Z-Wave 12.2 SDK using [File] > [Export...].
8. Window->Preferences->SimplicityStudio->SDKs
   1. Remove the 7.1x.xx SDKs from the Simplicity Studio SDK preferences
   2. This does not delete or uninstall the actual SDK, just removes it from the current workspace settings so it will not be used during the project import step
9. Import the .sls file created with the export. ([File] > [Import...]) above
10. Right click the project from the IDE perspective
11. Project Properties [C/C++ Build] > [Board / Part / SDK] and select the Gecko SDK Suite: 7.13.3.0, Flex 2.7.3 from the dropdown list
12. When it asks to Rebuild Now - click on YES!
13. The build will fail because the Linker script location has changed from:
    1. ${StudioSdkPath}/ZWave/linkerscripts/zgm13-zw700.ld
    2. to
    3. ${StudioSdkPath}/protocol/z-wave/ZWave/linkerscripts/zgm13-zw700.ld
    4. Right click on the project
    5. Properties->C/C++ Build->Settings->Memory Layout
    6. Change the linker script location as shown here
14. Try to Build again but now there are all sorts of problems with basic things like SizeOf.h cannot be found. This is caused by the change in the directory structure for the 7.13 SDK.
15. In the 7.13.3 project - right click on the project->properties->C/C++ General->Paths and Symbols and click on EXPORT Settings
16. Export them all to a temporary file - IE:Seven13Paths.xml
17. Return to the same screen in your project, <CTL-A> to select all the paths then Delete - be sure to delete ALL of them
18. Then click on Import Settings and select the Seven13Paths.xml file
19. Build again and you should get a “conflicting types for __Vectors” error
    1. This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
20.  Build again and you get an error “No rule to make target libZWaveSlave.a”.
21. Right click properties->C/C++Build/Settings->GNU ARM C Linker->Other objects
22. Change
    1. ${StudioSdkPath}/ZWave/lib/libZWaveSlave.a
    2. to
    3. ${StudioSdkPath}/protocol/z-wave/ZWave/lib/libZWaveSlave.a
    4. and
    5. ${StudioSdkPath}/SubTree/rail-import/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg13_gcc_releasa
    6. to
    7. ${StudioSdkPath}/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg13_gcc_release.a
23. If other errors turn up, try doing a Clean Project and exit SS and start it up again
24. Click Build
    1. OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
25. Click Build
    1. The error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
    2. The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2. Basically, delete (or #if 0/#endif) several lines of code.
26. Click Build
    1. The error is: Undefined Reference to CC_FirmwareUpdate_InvalidateImage
    2. The confusing part of this error is that you can click on this function and it will open the correct file. The problem is that it is not included in the project.
    3. The problem is there are 2 new Linked files - btl_reset_cause_util.[c,h].
    4. Copy via a link into the ZAF_CommandClasses_FirmwareUpdate
27. The project builds correctly! You may have additional files/directories that need to be cleaned up or corrected. Usually compare what is in the 7.13.3 project with yours to find what’s changed.
28. Program your project in your device and verify it still works
29. It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
30. For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
31. Connect the debugger using an Attach To
32. Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
33. Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
34. Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
35. The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
    1. ASSERT(NULL != pData);
36. Looking back in the sample app we notice there is a new Init routine for this command class:
    1.   CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
    2. Which also needs a new definition:
    3. SCCZWavePlusInfo CCZWavePlusInfo = { …
    4. Adding these to the source code, recompiling and downloading and testing it now works
37. There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.
38.  
39. Option C - Manually edit the .cproject and .project XML files:
40. This option uses a text editor to edit the two XML files SS uses to build your project. XML files are very picky and if you mess up the structure of the document it simply won’t work. So be very careful or go back to option A.
41. Open a new sample project in the 7.13.3 release using the same sample app you started with originally
42. Compile it and make sure it builds without error - change APP_FREQ to REGION_US (or your region) if needed
43. Close Simplicity Studio
44. The .cproject and .project are XML files which you can edit in a text editor. If you mess up the hierarchy of the file, it can make the files unusable. Editing the files is tricky so be very careful and keep backups of your work.
45. Rename the .cproject and .project files in your application directory - add .orig or .old to the filename
46. Copy the .cproject and .project files from the top level of the 7.13.3 sample app into your application directory
47. Open the two .cproject files in a text editor and diff the two files
    1. Carefully copy the few things you need from your original .cproject file into the 7.13.3 one - typically this is just a few filenames you have added to the project and other customizations
    2. You’ll see that many files are now in different directories
    3. many files now have /protocol/z-wave added or /util removed - all of these changes are necessary now that Z-Wave has been integrated with the other wireless protocols
48. Open the two .project files in a text editor and diff the two files
    1. Follow the same procedure as with the .cproject file
    2. The project name is the 3rd line of the file - this will certainly need to change
49. Open SS and select the project
50. Click on Clean Project
51. Click on Build
52. There are likely several errors usually caused by include paths not being correct
    1. Click on the Problems tab and highlight the error
    2. Go to the corresponding line in the 7.13.3 project and find the correct include path
    3. Copy that into your project properties
    4. In my trial SS was not able to find ZAF_common_helper.h
       1. Adding "${StudioSdkPath}/protocol/z-wave/ZAF/ApplicationUtilities/_commonIF" to the C include paths got it past this error
    5. Click Build
    6. Next problem is that UReceiveCmdPayload did not have a corresponding member
    7. In this case the structure has added an extra level of hierarchy so the reference changes from:
    8. RxPackage.uReceiveParams.Rx.Payload.ZW_Common.cmdClass
    9. to
    10. RxPackage.uReceiveParams.Rx.Payload.rxBuffer.ZW_Common.cmdClass
    11. Next problem is that __Vectors has conflicting types
    12. This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
    13. Click Build again
    14. Now the error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
    15. The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2.
    16. Click Build
    17. OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
    18. Click Build
    19. The project should now build correctly
    20. There are other potential problems with missing include directories,  #defines or function names that have changed. The solution is to search the new 7.13.3 project for the same area of code and identify the new directory or function name.
53. Program your project in your device and verify it still works
54. It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
55. For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
56. Connect the debugger using an Attach To
57. Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
58. Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
59. Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
60. The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
    1. ASSERT(NULL != pData);
61. Looking back in the sample app we notice there is a new Init routine for this command class:
    1.   CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
    2. Which also needs a new definition:
    3. SCCZWavePlusInfo CCZWavePlusInfo = { …
    4. Adding these to the source code, recompiling and downloading and testing it now works
62. There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.

Another minor issue with the 7.13.3 release is that it is not properly creating the .GBL files for OTA. The fix is simple:

Modify line 46 in \SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.7\protocol\z-wave\ZAF\ApplicationUtilities\application_properties.c

from:

.type = 1<<6UL,

to:

.type = 1<<7UL,

My recommendation is to click on this file in the Project Explorer->ZAF_ApplicationUtilites and make the change. When you change the code, this popup comes up:

And you should click on Make A Copy.

When the next minor release comes out this will be fixed and you will then want to delete the copy and go back to the Linked version of the file. I do NOT recommend changing the files in the SDK.

This guide uses the DoorlockKeyPad build under 7.12.2 but the same basic concepts apply to any sample app and your project. A generic KBA on upgrading SDKs for Bluetooth projects provides some general insights but this document is specific to this Z-Wave release.

1. Update Simplicity Studio (SS)
   1. From the Launcher perspective, click on the download icon and then click on Update All
   2. Close Simplicity and restart (just to be safe) - SS may ask to do this as well
   3. Click on the download button again, click on Package Manager, click on SDK tab, click on each Update button (keep scrolling down). I recommend restarting SS between each update.
2. Set the Preferred SDK to the latest release
   1. Plug in a WSTK devkit or select the ZGM130S in the MyProduct window
   2. From the Launcher perspective, click here:
   3. Select the Gecko SDK Suite 7.13.3.0
   4. Now when you want to create a new project it will start with the 7.13.3 release
3. At this point there are 3 options for upgrading:
   1. Open a new 7.13.3 project and then copy your changes into it
   2. Import/Export parts of your project into a new 7.13.3 project
   3. Manually edit the .cproject and .project files
4. Far and away the best option is the first one - option A
   1. The advantage of this is that you get all the latest and newest files of the Z-Wave Application Framework (ZAF), emlib, linker scripts, and lots of other stuff
   2. The challenge is that you have to plug all of your changes back into the sample application
   3. If you’ve made most of the changes in files other than the sample application, then the changes are probably easy to install
   4. However, if you’ve made a lot of changes to the sample application source code file it will take more time
   5. Option B or C might be the way to go but at some point it might still be better to go back to option A. Option A is fairly straightforward as the sample apps in the 7.13.3 release already work so just copy in your changes a few at a time and keep recompiling to make sure you haven’t broken something.
   6. If taking option A you’re done! No need to read any further! Create the new sample app and start plugging in your changes
   7. If you’re not taking option A, pick one of the 2 options below. The choice of B or C is up to you and primarily how confident you are in fixing XML files. If you think you can fix an XML file, then use option C otherwise use B.
5. Option B - Import/Export parts of your project into a new 7.13.3 project:
6. This option avoids manually editing the XML file but requires importing/exporting several files and using the GUI to fix paths. The advantage however is that you shouldn’t break the XML file which is easily done with manual editing.
7. Export the project created with Z-Wave 12.2 SDK using [File] > [Export...].
8. Window->Preferences->SimplicityStudio->SDKs
   1. Remove the 7.1x.xx SDKs from the Simplicity Studio SDK preferences
   2. This does not delete or uninstall the actual SDK, just removes it from the current workspace settings so it will not be used during the project import step
9. Import the .sls file created with the export. ([File] > [Import...]) above
10. Right click the project from the IDE perspective
11. Project Properties [C/C++ Build] > [Board / Part / SDK] and select the Gecko SDK Suite: 7.13.3.0, Flex 2.7.3 from the dropdown list
12. When it asks to Rebuild Now - click on YES!
13. The build will fail because the Linker script location has changed from:
    1. ${StudioSdkPath}/ZWave/linkerscripts/zgm13-zw700.ld
    2. to
    3. ${StudioSdkPath}/protocol/z-wave/ZWave/linkerscripts/zgm13-zw700.ld
    4. Right click on the project
    5. Properties->C/C++ Build->Settings->Memory Layout
    6. Change the linker script location as shown here
14. Try to Build again but now there are all sorts of problems with basic things like SizeOf.h cannot be found. This is caused by the change in the directory structure for the SDK.
15. In the 7.13.3 project - right click on the project->properties->C/C++ General->Paths and Symbols and click on EXPORT Settings
16. Export them all to a temporary file - IE:Seven13Paths.xml
17. Return to the same screen in your project, <CTL-A> to select all the paths then Delete
18. Then click on Import Settings and select the Seven13Paths.xml file
19. Build again and you should get a “conflicting types for __Vectors” error
    1. This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
20.  Build again and you get an error “No rule to make target libZWaveSlave.a”.
21. Right click properties->C/C++Build/Settings->GNU ARM C Linker->Other objects
22. Change
    1. ${StudioSdkPath}/ZWave/lib/libZWaveSlave.a
    2. to
    3. ${StudioSdkPath}/protocol/z-wave/ZWave/lib/libZWaveSlave.a
    4. and
    5. ${StudioSdkPath}/SubTree/rail-import/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg13_gcc_releasa
    6. to
    7. ${StudioSdkPath}/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg13_gcc_release.a
23. If other errors turn up, try doing a Clean Project and exit SS and start it up again
24. Click Build
    1. OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
25. Click Build
    1. The error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
    2. The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2. Basically, delete (or #if 0/#endif) several lines of code.
26. Click Build
    1. The error is: Undefined Reference to CC_FirmwareUpdate_InvalidateImage
    2. The confusing part of this error is that you can click on this function and it will open the correct file. The problem is that it is not included in the project.
    3. The problem is there are 2 new Linked files - btl_reset_cause_util.[c,h].
    4. Copy via a link into the ZAF_CommandClasses_FirmwareUpdate
27. The project builds correctly! You may have additional files/directories that need to be cleaned up or corrected. Usually compare what is in the 7.13.3 project with yours to find what’s changed.
28. Program your project in your device and verify it still works
29. It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
30. For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
31. Connect the debugger using an Attach To
32. Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
33. Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
34. Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
35. The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
    1. ASSERT(NULL != pData);
36. Looking back in the sample app we notice there is a new Init routine for this command class:
    1.   CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
    2. Which also needs a new definition:
    3. SCCZWavePlusInfo CCZWavePlusInfo = { …
    4. Adding these to the source code, recompiling and downloading and testing it now works
37. There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.
38.  
39. Option C - Manually edit the .cproject and .project XML files:
40. This option uses a text editor to edit the two XML files SS uses to build your project. XML files are very picky and if you mess up the structure of the document it simply won’t work. So be very careful or go back to option A.
41. Open a new sample project in the 7.13.3 release using the same sample app you started with originally
42. Compile it and make sure it builds without error - change APP_FREQ to REGION_US (or your region) if needed
43. Close Simplicity Studio
44. The .cproject and .project are XML files which you can edit in a text editor. If you mess up the hierarchy of the file, it can make the files unusable. Editing the files is tricky so be very careful and keep backups of your work.
45. Rename the .cproject and .project files in your application directory - add .orig or .old to the filename
46. Copy the .cproject and .project files from the top level of the 7.13.3 sample app into your application directory
47. Open the two .cproject files in a text editor and diff the two files
    1. Carefully copy the few things you need from your original .cproject file into the 7.13.3 one - typically this is just a few filenames you have added to the project and other customizations
    2. You’ll see that many files are now in different directories
    3. many files now have /protocol/z-wave added or /util removed - all of these changes are necessary now that Z-Wave has been integrated with the other wireless protocols
48. Open the two .project files in a text editor and diff the two files
    1. Follow the same procedure as with the .cproject file
    2. The project name is the 3rd line of the file - this will certainly need to change
49. Open SS and select the project
50. Click on Clean Project
51. Click on Build
52. There are likely several errors usually caused by include paths not being correct
    1. Click on the Problems tab and highlight the error
    2. Go to the corresponding line in the 7.13.3 project and find the correct include path
    3. Copy that into your project properties
    4. In my trial SS was not able to find ZAF_common_helper.h
       1. Adding "${StudioSdkPath}/protocol/z-wave/ZAF/ApplicationUtilities/_commonIF" to the C include paths got it past this error
    5. Click Build
    6. Next problem is that UReceiveCmdPayload did not have a corresponding member
    7. In this case the structure has added an extra level of hierarchy so the reference changes from:
    8. RxPackage.uReceiveParams.Rx.Payload.ZW_Common.cmdClass
    9. to
    10. RxPackage.uReceiveParams.Rx.Payload.rxBuffer.ZW_Common.cmdClass
    11. Next problem is that __Vectors has conflicting types
    12. This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
    13. Click Build again
    14. Now the error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
    15. The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2.
    16. Click Build
    17. OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
    18. Click Build
    19. The project should now build correctly
    20. There are other potential problems with missing include directories,  #defines or function names that have changed. The solution is to search the new 7.13.3 project for the same area of code and identify the new directory or function name.
53. Program your project in your device and verify it still works
54. It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
55. For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
56. Connect the debugger using an Attach To
57. Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
58. Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
59. Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
60. The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
    1. ASSERT(NULL != pData);
61. Looking back in the sample app we notice there is a new Init routine for this command class:
    1.   CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
    2. Which also needs a new definition:
    3. SCCZWavePlusInfo CCZWavePlusInfo = { …
    4. Adding these to the source code, recompiling and downloading and testing it now works
62. There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.

Another minor issue with the 7.13.3 release is that it is not properly creating the .GBL files for OTA. The fix is simple:

Modify line 46 in \SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.7\protocol\z-wave\ZAF\ApplicationUtilities\application_properties.c

from:

.type = 1<<6UL,

to:

.type = 1<<7UL,

My recommendation is to click on this file in the Project Explorer->ZAF_ApplicationUtilites and make the change. When you change the code, this popup comes up:

And you should click on Make A Copy.

When the next minor release comes out this will be fixed and you will then want to delete the copy and go back to the Linked version of the file. I do NOT recommend changing the files in the SDK.

I ran into this same problem. The issue is that in SPI mode the TX pin is used as the data input when in slave mode.

So MOSI is in fact the pin you want.

In my case I used: 

        USART1->ROUTELOC0 = (USART_ROUTELOC0_CLKLOC_LOC9) | // US1_CLK       on location 9 = PC6 per datasheet section 6.2
                            (USART_ROUTELOC0_TXLOC_LOC12) | // US1_TX (MOSI) on location 14 = PC7 - in SPI slave mode (Master=0) this is the datain
                            (USART_ROUTELOC0_CSLOC_LOC0 );// | // US1_CS        on location 0 = PA3

        USART1->ROUTEPEN = USART_ROUTEPEN_CLKPEN | USART_ROUTEPEN_CSPEN | USART_ROUTEPEN_TXPEN;

Which seems backwards as you're using TXPEN to enable the data input. But it works.