Important Changes#

The changes described in this file will possibly break the build and/or functionality of an existing application. The description serves the purpose of helping to fix the failing build.

7.21.2#

Fix migration process from 7.17 to 7.18+#

The migration process of the controller is broken since 7.18.1. Restore this migration process. This process is used when a controller is updated from a version older than 7.18 to 7.18 or newer.

7.21.1#

Support#

Footprint (heap, stack, ROM) has been optimized to support low-end devices (ZG14).

Fix saving host data in controller#

Fixed an issue on 700 series controllers, where the host was no longer able to save data in the controller's NVM. Increased largest NVM object size to match host's limitation (from 204 to 512 bytes currently used by ZPC or ZGW) This is to satisfy the design of the 700 series and allow the host to store data on the controller's NVM.

ZPAL Power Manager#

Relocated zpal_pm_set_device_type to apps (e.g. sensor is non-listening). Reworked notifications (deep sleep, power down) related to EM4, EM3, EM2 states.

7.21.0#

SPAN synchronization#

Unsollicited request from end devices will now have S2_TXOPTION_VERIFY_DELIVERY enabled by default to allow SPAN synchronization.

Portable Controller Application#

The portable controller application has been removed in this version. Last version supporting this application is 7.20.

ZPAL Power Manager#

The maximum number of power manager handlers has been reduced from 20 to 17. This number includes both stack-side and application-side handlers.

Application user-specified versioning#

A new boolean parameter is introduced into Simplicity Studio. When the user creates a new application, the user can choose whether their application uses the Z-Wave SDK Version, or a specific version he is free to define.

OTW Update of Serial API controller#

In version 7.20 of the Z-Wave SDK, The Serial API Controller application's Product ID, used for validation during OTW updates had been changed to include a Generic and Specific Device Type.\ This prevented updating devices running version 7.19 or lower of the Serial API Controller to more recent versions.

To address this incompatibility, the Specific and Generic Device Type bytes of the Product ID, defined in application_properties_config.h (used by the struct sl_app_properties of the bootloader) have been reverted to their previous values of 0.\ This only affects the Product ID; the application still reports the new Device Type values in its Node Information Frame.\ Note that these values can be changed on the fly using the Serial API command SERIAL_API_APPL_NODE_INFORMATION.

The following update paths for this application are not possible using the pre-built binaries:

  • 7.19 or lower to 7.20

  • 7.20 to 7.21 or higher

However, firmwares that are not affected by this incompatibility can be created manually, as described in the README of the application.

Z-Wave NVM instance configurable from Simplicity Studio#

A configurable component (ZPAL Z-Wave NVM instance) has been created to help user to configure the Z-Wave NVM stack instance from Simplicity Studio. This NVM instance is used on series 700 to store ZAF and user application's data. GSDK and Z-Wave stack data are stored in the default NVM instance (which is configurable from the NVM3 Default Config component).\ On other series, all data are stored in the NVM default instance. So this component is available only in projects using series 700.

Improve NVM management on series 700#

Add periodic repacks for Z-Wave NVM instance on series 700 in zpal. Avoid to repack this NVM instance on NVM write (which could create latency in wireless communication).\ NVM default instance already has a periodic repack.

Controller's NVM data update#

Controller's data in NVM have been updated in order to save the nodeId length (Classic Z-Wave or Long Range Z-Wave). A migration script is required to update data in NVM. This script is enable by installing slc component "Migration from V7.20 (to V7.21)" in the controller project.

7.20.2#

zwave_soc_led_bulb Moved to NonCertifiableApps#

The zwave_soc_led_bulb (LED Bulb) application is no longer certified, so this application is moved from Apps to NonCertifiableApps folder.

7.20.1#

ZAF Retention Register#

Added module for retention registers. Application can now use ZAF_retention_register_read and ZAF_retention_register_write to read and write retention registers not used by ZAF, protocol and PAL. ZAF_retention_register_count can be used to get the number of registers available for application use. Register index starts from 0.

7.20.0#

ZAF Application Name#

Storing the name of applications is now handled by the zaf_appname component.\ The name is stored as a string by default. By installing an additional component, zaf_appname_nvm, the name can be saved to the non-volatile memory as well.\ When multiple Z-Wave devices are connected, this feature can speed up the process of identifying which application is flashed on each device.

ZAF Job Helper#

This module is no longer recommended for use in new applications. The main use case for this module was to transmit different frames for the same event. The new applications should leverage the ZAF Transport Queue instead. For applications that still wants to use this module it has been moved to its own component: zaf_job_helper.slcc

ZAF Transport Module#

ZW_TransportEndpoint was refactored and much local data has been removed. Functions Transport_SendRequestEP() and Transport_SendResponseEP() were replaced with a common function ZAF_Transmit() The type of callback_function in ZAF_Transmit(buffer, len, txOptions, callback_function) is now ZAF_TX_Callback_t. Note that ZAF_Transmit() does not set S2_TXOPTION_VERIFY_DELIVERY by default, as it was with Transport_SendRequestEP(). This flag can be set in ZAF_Transmit(), by enabling it in TransmitSecurityOptions. It is not recommended to use this API directly, applications should use the ZAF Transport Queue to ensure that only one frame is sent from the application to the protocol at one time.

ZAF_Transmit migrated to zaf_transport_tx#

In order to ensure a single entry point for frames from the application to the protocol, ZAF_Transmit is not being called directly by Command Classes.

ZAF Transport Queue#

This module implements a transport queue in the application level. This queue ensures that there is only a single entry point for a frame from the application. This adds a new feature to applications, the ability to "send and forget", which means the user only has to send to the queue, and the rest of the process is taken care of. i.e. Send Central Scene Notification and Send Basic Set in sequence. The queue size is configurable and it can bet set by ZAF_TRANSPORT_CONFIG_QUEUE_SIZE, the default is 2.

ZAF TX Mutex Removed#

This module was used to ensure that a shared buffer frame was only used by one module at the same time. It was very relevant for 500 series to reduce the RAM usage as no stack was available for the tasks, however it became irrelevant for 700 series and forward. This module was only being used by the ZW Transport Multicast module at this point. The buffer was moved to the module itself and the TX Mutex module was removed, therefore the ZAF_tx_mutex.h no longer exists.

Merge agi.c/h into CC_AssociationGroupInfo.c/h#

The agi.c/h module does not exist anymore as the contents of the files have been merged into CC_AssociationGroupInfo. This should reduce some complexity since data does not have to be passed between the different modules, and should reduce flash and ram consumption.

ZAF Event Helper module removed#

This module was only used by the event distributor soc to enqueue events into the application event queue therefore this functionality was moved into the event distributor soc.

The interface changes are listed below:

Old name

New name

ZAF_EventHelperInit

->

Not needed anymore

ZAF_EventHelperIsInitialized

->

Not needed anymore

ZAF_EventHelperEventEnqueue

->

zaf_event_distributor_enqueue_app_event

ZAF_EventHelperEventEnqueueFromISR

->

zaf_event_distributor_enqueue_app_event_from_isr

The functions that still exist takes the same arguments as before. They are defined in zaf_event_distributor_soc.h

Application Name Configurable#

Each application's name is configurable. It can be changed by specifying the configuration entry named ZAF_APP_NAME in the SLC project description. Printing the application's name, reset reason, and SDK version was moved to ZAF_PrintAppInfo().

Eliminating the config_app.h files#

config_app.h files were eliminated from sample applications, and the content of the headers were moved to the project source files. Exceptions to this are version numbers, previously stored in these files. Version numbers have been moved to a configurable SLC component. The APP_VERSION_MAJOR, APP_VERSION_MINOR, and APP_VERSION_PATCH numbers are now configurable via the zw_version component in the studio GUI. Users still get the original Silicon Labs version numbers by default, but it is also possible to change them as described above.

Common hardware functions#

Each application would implement each own <App>_hw_init function and have their own <App>_hw.h header. The applications that go to deep sleep also had their own <APP>_hw_deep_sleep_wakeup_handler function. These two common functions have been consolidate in a app_hw.h as app_hw_init and app_hw_deep_sleep_wakeup_handler. app_hw_init MUST be implemented by the application while app_hw_deep_sleep_wakeup_handler should only be implemented by applications that can go into deep sleep.

Application's Source Code#

Application's source codes were moved from <application_name>.c to app.c file. The app.h headers were also removed with the function app_init(). Because of this the function calls were removed from the main.c file.

Board Indicator Moved into ZAF#

Board indicator LED is initialized in ZAF_Init() and the default idle status is set also in it. Board_IndicateStatus() is available so it can be used freely in the code.

Command Classes#

New Version of Command Classes Handlers#

New macro REGISTER_CC_V5() has been created and can be used to initialize Command Classes. This macro requires a CC handler that takes only input and output structure as arguments. See CC_BinarySwitch_handler(cc_handler_input_t * input, cc_handler_output_t * output) as an example. This makes it possible for CC to exit with status WORKING, without a need to pass duration parameter to Supervision CC, or to call Supervision Report directly, as was the case so far.

REGISTER_CC_V5() is supported in all Command Classes that support timed change, and their handlers were updated accordingly. List of handlers compatible with REGISTER_CC_V5():

  • CC_BinarySwitch_handler()

  • CC_ColorSwitch_handler()

  • CC_DoorLock_handler()

  • CC_MultilevelSwitch_handler()

  • CC_MultiChannel_handler()

Folder structure and private/public headers#

Some command classes have more than two source files and header files. This is because the command class contains a lot of logic therefore splitting into more than one source and one header file makes sense for readability. In order to allow interaction between two source files, private header were introduced and to avoid confusion a new folder structure is used. The source files and private header are placed in src while the public headers are placed in inc.

All Command Classes have been structured to have inc, src and in some cases, config folder. Header files located in config folder contain values configurable in Simplicity Studio.

CC Basic#

CC_Basic_Set_handler() was removed. This function is no longer required by applications as ZAF handles Basic Command Class mapping (assuming all relevant Command Classes implement a Basic Set mapper function).

CC Central Scene#

Configuration of Command Class Central Scene was migrated to Z-Wave Command Class Configurator and must be configured in <app>.cc_config. More details can be found here.

The configuration of cc_central_scene_get_supported_key_attributes was removed from zw_cc_central_scene component. Values can either be set using Z-Wave Command Class Configurator, or they are automatically calculated by Command Class.

  • Function cc_central_scene_set_configuration was removed since this operation is only done internally in the Command Class.

  • cc_central_scene_get_supported_key_attributes were made static as they are only used internally.

  • cc_central_scene_get_configuration was removed as obsoleted. Slow refresh value is now used only internally in CC_CentralScene.c and can be accessed directly.

  • Refactored function CommandClassCentralSceneNotificationTransmit():

    • Renamed to cc_central_scene_notification_tx()

    • Removed sourceEndpoint argument. The function will always use ROOT as source endpoint.

CC Door Lock#

It is now the responsibility of the Command Class to ensure that the TSE actions are managed. All TSE-related functionalities have been moved from the applications to the Door Lock CC. This includes functions cc_door_lock_handle_working_state() and CC_DoorLock_operation_report_notifyWorking()

Hardware handling has been moved out of CC Door Lock, leaving the command class with the software logic only.

Supervision Handling Moved to CC#

Handling of Supervision Get for Door Lock Operation Set has been moved from application to Command Class.

Function cc_supervision_get_received_handler no longer needs to be implemented in the app.

New REGISTER_CC_V5 made it possible to remove CmdClassSupervisionReportSend() with status Working and leave it to CC Supervision to handle the working case.

CC Multi Channel#

Configuration of Command Class Multi Channel (endpoints) was migrated to Z-Wave Command Class Configurator and must be configured in <app>.cc_config. More details can be found here.

Configuring whether endpoints are identical or not must be done in Studio.

As a result of the migration, Transport_AddEndpointSupport() was removed.

To comply with the naming scheme, the following two SLC components were renamed:

  • zw_cc_multichannelcontrol -> zw_cc_multi_channel_control

  • zw_cc_multichannelsupport -> zw_cc_multi_channel_support

CC Notification#

The source code in notification.c has been moved to CC_Notification.c and notification.c has been removed.

Notification types have been moved into cc_notification_types.h and states/events have been moved into cc_notification_events.h. This is done to prepare for automatic generation of these two files based on the types and states/events defined in the Z-Wave specification.

CC_NOTIFICATION_MAX_EVENTS_PER_NOTIFICATION was removed as the number of configured events/states can be derived from the CC configuration.

The CC configuration syntax was simplified to no longer require state_event: for each state/event listed under state_events:. This is a breaking change and existing cc_config files must be updated. More details can be found here.

Existing syntax:

state_events:
  - state_event: NOTIFICATION_EVENT_POWER_MANAGEMENT_OVERLOADED_DETECTED
  - state_event: NOTIFICATION_EVENT_POWER_MANAGEMENT_LOAD_ERROR

New syntax:

state_events:
  - NOTIFICATION_EVENT_POWER_MANAGEMENT_OVERLOADED_DETECTED
  - NOTIFICATION_EVENT_POWER_MANAGEMENT_LOAD_ERROR

CC Wake Up#

Applications that included the Command Class Wake Up had to call three functions in response to the EVENT_SYSTEM_LEARNMODE_FINISHED event. These functions were CC_WakeUp_stayAwake10s, CC_WakeUp_AutoStayAwakeAfterInclusion and CC_WakeUp_startWakeUpNotificationTimer if the inclusion state is not excluded. Now this is handled by ZAF. This is done by implementing the weak function zaf_learn_mode_finished.

Application Events Abstracted#

Some sample applications contained events that contained hardware-specific names. Those names were based on how the Silicon Labs port would generate those events.

Many events had the BUTTON keyword and it was removed from event names so EVENT_APP_BUTTON_<event> becomes EVENT_APP_<event>. Below is the list of renamed events for each application that did NOT follow this pattern.

zwave_soc_switch_on_off#

Old name

New name

EVENT_APP_BUTTON_TOGGLE_SHORT_PRESS

->

EVENT_APP_TOGGLE_LED

EVENT_APP_BUTTON_TOGGLE_HOLD

->