Utilities#
The Z-Wave Application Framework (ZAF) provides reusable utilities for Z-Wave applications. Configure applications with the software components supplied by the installed Simplicity SDK, and use that installation's API reference and generated project configuration as the source of truth for component options and signatures.
Scope: Z-Wave SDK 8.1.x in the Simplicity SDK release stream supports Series 800 product development. Series 500 and Series 700 devices are not supported by this SDK release stream. The board, pin, and peripheral details below must be selected for the specific Series 800 board or module in use.
Command-class utilities#
Some utilities are part of command-class implementations rather than general application services:
The Association Group Information (AGI) functionality is part of the Association Group Information Command Class. See Association Group Information CC.
Association functionality is shared by the Association and Multi Channel Association Command Classes. Refer to the installed SDK API reference for the available interfaces.
ota_utilis used by Firmware Update Meta Data Command Class functionality. Refer to the installed SDK API reference and the command-class documentation for the supported workflow.
Peripheral access#
Simplicity SDK projects use software components and board support appropriate to the selected Series 800 target. Add the required components in Simplicity Studio's Project Configurator, then use the board and peripheral APIs documented for that target. Do not assume that a driver, pin assignment, board source file, or peripheral shown for another radio board is present or wired the same way on your hardware.
For peripheral behavior and examples, use the Simplicity SDK documentation and example projects installed with the SDK. Older EMLIB/EMDRV links and examples may describe APIs or boards that differ from the selected Series 800 target.
GPIO, buttons, and LEDs
GPIO pins are board-specific. Consult the schematic and board documentation for the Series 800 development kit or product hardware, and configure the GPIO or button/LED components for that board. The historical Board_Init(), Board_EnableButton(), and Board_SetLed() examples for BRD4001A, BRD4202A, and BRD8029A do not define a portable Series 800 interface.
UART and serial data#
Use the UART or IO Stream components configured for the selected Series 800 board. Configure baud rate, parity, data bits, stop bits, flow control, and pin routing to match the connected device. The values and GPIO mappings from the legacy Serial API board examples are not universal defaults for Series 800 hardware.
When an interrupt-driven peripheral needs to notify application code, keep interrupt work short and defer processing to the application task through the event mechanism configured by the application. Use the relevant FromISR API when enqueueing from an interrupt, and check whether the enqueue succeeded. Do not call task-context APIs from an ISR.
Event distribution#
For on-chip applications, use the ZAF SOC Event Distributor component and the application structure provided by the selected SDK example. The component owns the event queues and dispatch path; applications should not copy the legacy queue creation, notification-bit assignment, or event-distributor setup shown in older examples unless the installed SDK's example explicitly requires it.
Application events can be placed on the SOC event distributor's application queue with the interfaces in zaf_event_distributor_soc.h:
bool zaf_event_distributor_enqueue_app_event(const uint8_t event);
bool zaf_event_distributor_enqueue_app_event_from_isr(const uint8_t event);Use the second function from an ISR. Check the return value so a full or unavailable queue is handled appropriately by the application.
The former ZAF_EventHelper module was removed. Replace ZAF_EventHelperEventEnqueue() with zaf_event_distributor_enqueue_app_event() and ZAF_EventHelperEventEnqueueFromISR() with zaf_event_distributor_enqueue_app_event_from_isr(). ZAF_EventHelperInit() is no longer needed. The NCP Event Distributor is intended for Serial API applications whose host runs on a separate chip; use the SOC variant for an application running on the Series 800 device itself.
For the complete API and any event-dispatch customization, see the Event Distributor documentation shipped with the installed SDK. The older EventDistributorConfig() / EventDistributorDistribute() example in this chapter is retained only in older SDK documentation and should not be used as the starting point for an SDK 8.1.x SOC application.
Job sequencing and transport#
ZAF_JobHelper is a legacy utility and is no longer recommended for new applications. For sending multiple frames in sequence, use the ZAF Transport Queue configured by the project components. This queue provides a single application-level entry point for transmissions and supports queuing follow-up frames.
Existing applications that still use ZAF_JobHelper may need to add its separate software component. Check the SDK migration guide and installed component documentation before carrying that design forward. Do not assume that the helper is included by default.
Power management#
The Z-Wave power-management components coordinate low-power operation with protocol activity. Use the components and application hooks supplied by the selected SDK project; avoid adding direct power-mode transitions that bypass protocol and platform power management.
ZAF_PM_Wrapper.h and its Power Module Wrapper API are deprecated/not supported as the application pattern for new SDK 8.x projects. For application work that must run immediately before deep-sleep shutdown, use the weakly defined ZW_AppPowerDownCallBack hook described in the installed SDK API reference. For Series 800 in SDK 8.1.x, configure the platform sleeptimer as SL_SLEEPTIMER_PERIPHERAL_DEFAULT (typically SYSRTC). BURTC is reserved for Z-Wave EM4 wake-up and compare programming; the platform sleeptimer and Z-Wave deep-sleep manager must not use the same peripheral.
Application timers#
Use the AppTimer and software-timer interfaces provided by the installed ZAF components. Register timers and connect their notifications to the application event flow as shown in the SDK's current sample applications. Timer callback context and available timer count are component/version details; confirm them in the installed API reference rather than relying on the older signatures and limits in legacy examples.
A software timer is not persistent across a full shutdown or reset. If the device enters EM4 and restarts, application initialization runs again; a timer callback that would have expired during shutdown is not delivered after reboot. Store a deadline or remaining duration in persistent state if the application needs to resume timed work after a restart.
Supply-voltage measurement#
Supply-voltage measurement is target- and component-dependent. The legacy ZAF_ADC_* API described for ZGM130S is not a portable Series 800 API. Check the selected Series 800 device, board design, and installed SDK components for a supported voltage-measurement path before using ADC code. Battery-powered applications should use the Battery Command Class and reporting behavior configured for the product; see Battery Support Basics.
Migration notes#
When moving an older application to Simplicity SDK and Z-Wave SDK 8.1.x:
Select a supported Series 800 target and migrate or create the project using Simplicity Studio.
Review generated software components and project configuration, especially the SOC Event Distributor, transport queue, power management, and sleeptimer components.
Replace removed Event Helper calls with the SOC event-distributor enqueue APIs.
Replace new uses of
ZAF_JobHelperwith the Transport Queue, and useZW_AppPowerDownCallBackinstead of the Power Module Wrapper for the pre-shutdown hook.Verify board-specific GPIO/UART routing and supply-voltage measurement against the actual Series 800 hardware.
See the Z-Wave SDK 8.1.x release notes and the migration/API documentation included with the installed SDK for release-specific changes.