Plugin Configuration Guide

Back to Trident IoT SDK

Overview

---

Plugins are source code modules that provide functionality for common device behavior. These are designed to build in helpful functionality into user applications by adding things like ZCL cluster functionality, best practices for common needs such as network rejoins backoff delay algorithms, or providing useful tools like the Trident command line interface and debug print utility. All plugins are completely optional and are up to the user to decide if they want to use them or not. Also, plugin source code is copied into projects during project generation so feel free to modify any plugins that you wish.

Plugin configuration is what gives users the ability to add, remove, or modify the built in Trident plugins to an application. The concept of adding plugins to a project involves turning on the plugin define that enables the plugin and adding any plugin-specific definitions inside of project_dir/tr_plugin_config.cmake, then doing a clean build of the project.

Once a plugin has been added, there are optional Application Callbacks (See Application Callbacks Guide) that can be implemented to provide application level insight and control of plugin behavior without needing to modify the plugin itself.

See below for some examples on how to enable this.

Note

tr_plugin_config.cmake is a manually edited file right now but a configuration tool is in the works...stay tuned.

How to Add a Trident Plugin

---

Overview

Adding a Trident plugin consists of 2 simple steps for non-ZCL plugins and 3 steps for ZCL plugins. If adding a non-ZCL plugin, start from step 2.

1. If adding a ZCL plugin, the cluster must be added to the project using ZAP before the plugin will do anything.
2. Turn on the required plugin-enable in the project and add any additional optional configurations specific to that plugin.
3. Perform a clean build to allow the plugin configuration to take effect.

Example: Adding Groups Server Plugin with Optional Features

The following is an example of how to add the Groups Server plugin with some additional details about what goes into each step. This example adds the required components as well as the optional feature that allows for group bindings to be created automatically when an add groups command is received.

Note

This assumes that Command Line Interface (CLI) and Debug Print already exist in the project

Step 1: Add Groups Server cluster via ZAP

The Trident ZCL plugins provide cluster functionality and give access to optional ZCL Plugins Application Callbacks. However, adding a ZCL plugin does not add the cluster to the ZCL profile of the device without also adding the cluster to a project via the ZAP tool. Please see ZAP User Guide for how to add clusters to a project via ZAP.

Step 2: Enable Groups Server plugin and configuration options in tr_plugin_config.cmake

Navigate to the Groups Server under the Plugins - ZCL section. Note that TR_GROUPS_SERVER_PLUGIN_ENABLE is a required definition to enable this plugin, and there are several optional configurations you can enable: TR_GROUPS_SERVER_PLUGIN_CLI_ENABLE to expose Groups-related commands through the CLI for development and testing, TR_GROUPS_SERVER_PLUGIN_PRINT_ENABLE=1 to enable printing at the plugin level, and TR_GROUPS_SERVER_AUTO_BIND_ENABLE to automatically manage group bindings.

Locate tr_plugin_config.cmake in the root directory of your project, and open it in a text editor. Within set(ZIGBEE_PROJECT_CONFIGURATIONS ...), find these configuration options and values, uncomment the mandatory (if currently commented out) and add any optional ones that you wish to use. This populates the list variable ZIGBEE_PROJECT_CONFIGURATIONS with a set of project configuration options and key-value pairs that will be consumed in the build step. Next time you build the project, the source and include files associated with this plugin according to the ZIGBEE_PROJECT_CONFIGURATIONS list variable will be pulled into the project build. See a snippet below from tr_plugin_config.cmake for an application that enables the Groups Server plugin and auto binding:

set(ZIGBEE_PROJECT_CONFIGURATIONS
    # [START TRIDENT CONFIGS]

    # ... most configs omitted for brevity ...

    # --- ZCL CONFIGS ---
    TR_GROUPS_SERVER_PLUGIN_ENABLE
    # ... most plugin enable configs omitted for brevity ...

    # --- ZCL PLUGIN PRINT CONFIGS ---
    TR_GROUPS_SERVER_PLUGIN_PRINT_ENABLE=1
    # ... most plugin print enable configs omitted for brevity ...

    # --- ZCL PLUGIN CLI CONFIGS ---
    TR_GROUPS_SERVER_PLUGIN_CLI_ENABLE
    # ... most plugin cli enable configs omitted for brevity ...

    # --- GROUPS SERVER CONFIGS ---
    TR_GROUPS_SERVER_AUTO_BIND_ENABLE

    # ... more configs omitted for brevity ...

    # [END TRIDENT CONFIGS]
)

Note

In the case where the definitions have values that can be set, default values from the plugin tables can be used but it is up to the user to modify those values as needed.

Step 3: Perform a clean build to do a full rebuild of the project

Now the plugin has been added and all is left is to build it! Doing a full clean build is a best practice though not always necessary.

1. Use elcap to clean the project using command: elcap clean
2. Use elcap to build the project using command: elcap build

Once you understand how this works, you may want to use the combined command for both steps: elcap build --clean

See elcap page for more information.

Note

See Application Callbacks Guide for more ways to take advantage of Trident plugins.

How to Remove a Trident Plugin

---

To remove a plugin the process is essentially the same as How to Add a Trident Plugin but in reverse.

1. Find and comment the plugin-enable and any additional configurations in the tr_plugin_config.cmake file.
2. If this is a ZCL plugin, and you wish to remove the cluster completely, remove it using ZAP.
3. Perform a clean build to rebuild the project using your updated plugin configuration.

How to Read Plugin Tables

---

The plugin tables show what required and optional functionality exists as well as the information needed to add each plugin into a project. All non-optional configurations must be added to (or uncommented in) tr_plugin_config.cmake. Any required value can be the default value or modified according to your project needs, so long as it remains in its valid range.

Define	Value	Optional	Depends On
PLUGIN_CONFIG_NAME to add to tr_plugin_config.cmake	–	NO if settings in this row are required for this plugin, YES if it is an optional feature of this plugin	plugins and/or config options that this one depends on
PLUGIN_CONFIG_VALUE_NAME=default_value to add to tr_plugin_config.cmake	[min - max] value to set PLUGIN_CONFIG_VALUE_NAME to	NO if settings in this row are required for this plugin, YES if it is an optional feature of this plugin	plugins and/or config options that this one depends on

Plugins - Services

---

Services plugins are used for adding "services" to a device that are not explicitly ZCL cluster related. These are intended to improve the quality of life for a product developer by providing configurable functionality that is commonly added to devices during product development. If there is anything you would like to see added to this list please let us know!

Bind

This is an extension to the default binding capabilities that are found in the stack. This is primarily intended to be used along with the Groups Server plugin to interact with groups bindings.

Define	Value	Optional	Depends On
TR_BIND_PLUGIN_ENABLE	–	NO	–

Command Line Interface (CLI)

This plugin includes the cli engine with up/down arrow command history, left/right arrow command editing, command parsing, command option and argument parsing, and numerous built-in CLI commands. Built-in commands include general commands like "info", "version", and "reset", mac control commands, network commands, print commands, plugin commands, debug commands, global cluster specific ZCL commands, and ZDO commands.

See Zigbee Command Line Interface for information on configuring the HAL for CLI use.

Note

Currently the CLI prompt is truncated to 10 characters, even if TR_CLI_MAX_PROMPT_LEN is set to a larger value

Define	Value	Optional	Depends On
TR_CLI_PLUGIN_ENABLE	–	NO	Debug Print
TR_CLI_PROMPT="Trident> "	prompt string to show up in the CLI terminal	YES	–
TR_CLI_MAX_PROMPT_LEN=9	[1 - 100] max length of custom prompt	YES	–
TR_CUSTOM_CLI_COMMANDS_ENABLE	–	YES	–
TR_CUSTOM_CLI_TOPLEVEL="custom"	custom CLI top level command	YES	TR_CUSTOM_CLI_COMMANDS_ENABLE
TR_VERBOSE_ZDO_CLI_ENABLE	–	YES	–

ZCL Command Line Interface (ZCL-CLI)

When a Zigbee cluster is added via ZAP (see ZAP User Guide), if Command Line Interface is enabled and if this cluster has CLI commands implemented (typically to facilitate constructing a ZCL command), this CLI feature (which we call ZCL-CLI to distinguish it from the rest of the CLI) is enabled by default. You can optionally disable individual clusters from this ZCL-CLI support using these configuration options in your project tr_plugin_config.cmake.

Define	Value	Optional	Depends On
TR_ALARMS_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_BASIC_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_GROUPS_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_IDENTIFY_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_LEVEL_CONTROL_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_ON_OFF_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_SCENES_CLIENT_ZCL_CLI_DISABLE	–	YES	–
TR_POLL_CONTROL_CLIENT_ZCL_CLI_DISABLE	–	YES	–

Note

ZCL-CLI is a component of CLI to facilitate constructing a ZCL over-the-air command packet. Furthermore,

• If a cluster has a ZCL-CLI feature in the Trident IoT Zigbee SDK, it is enabled by default when a cluster is added via ZAP, while configurations exist to disable ZCL-CLI for individual clusters.
• A cluster can have both a plugin CLI and a ZCL-CLI while they serve distinctly different purposes. A plugin CLI is often (but not always) on the server side to control local behavior. For example, a Door Lock server plugin exposes convenient commands for a user to lock and unlock locally. A ZCL-CLI is often (but not always) on the client side; for example, a Groups client ZCL-CLI command lets you construct a Groups over-the-air command and puts it in the TX buffer without requiring you to know all details of the command structure. This is then ready to transmit using a subsequent send command on the CLI.

Debug Print

The debug print plugin provides a build-time and run-time configurable print feature for use in product debug. It also works hand-in-hand with the Command Line Interface (CLI) plugin by providing the character output. Debug prints are classified into groups and each group can be configured to a specific color or color can be turned off, and there are APIs available for enabling and disabling print groups at run time.

Print output is associated with a print group by using the appropriate printf function. Using the proper print function is necessary to maintain group identity. In other words, application code should NOT use tr_app_printf() and tr_app_println() directly! The print groups, functions, and usage are:

Debug Print Group	Functions	Used For
TR_DEBUG_PRINT_STACK	tr_stack_printf(...) tr_stack_println(...)	Prints from the Zigbee stack will be in this group
TR_DEBUG_PRINT_CORE	tr_core_printf(...) tr_core_println(...)	Core prints are used in the CLI
TR_DEBUG_PRINT_APP	tr_app_printf(...) tr_app_println(...)	Prints from the application should be in this group
TR_DEBUG_PRINT_ZCL	tr_zcl_printf(...) tr_zcl_println(...)	ZCL prints from the ZCL plugins will be in this group
TR_DEBUG_PRINT_RX_MSGS	tr_rxmsgs_printf(...) tr_rxmsgs_println(...)	All Zigbee messages received will print from this group

Print group build-time configuration is accomplished in the project tr_plugin_config.cmake file by modifying the options shown below.

Note

Using xxx_println(...) function is less efficient than using xxx_printf(...) with a \n at the end of the format string

Disabling a print group removes it from the build and it cannot be enabled at run-time! Enabling a print group sets the runtime enable to true by default.

Debug Print Color Options
DEBUG_BLACK
DEBUG_RED
DEBUG_GREEN
DEBUG_YELLOW
DEBUG_BLUE
DEBUG_MAGENTA
DEBUG_CYAN
DEBUG_WHITE
DEBUG_DEFAULT
DEBUG_RESET

Define	Value	Optional	Depends On
TR_DEBUG_PRINT_PLUGIN_ENABLE	–	NO	–
TR_DEBUG_PRINT_STACK_ENABLED	none, define to enable stack print group	YES	–
TR_DEBUG_PRINT_CORE_ENABLED	none, define to enable core print group	YES	–
TR_DEBUG_PRINT_APP_ENABLED	none, define to enable app print group	YES	–
TR_DEBUG_PRINT_ZCL_ENABLED	none, define to enable ZCL print group	YES	–
TR_DEBUG_PRINT_RX_MSGS_ENABLED	none, define to enable printing of received messages	YES	–
TR_DEBUG_PRINT_COLOR_ENABLED	none, define to enable color prints	YES	–
TR_DEBUG_PRINT_STACK_COLOR=DEBUG_BLUE	color to use, select option from color table above.	YES	TR_DEBUG_PRINT_COLOR_ENABLED TR_DEBUG_PRINT_STACK_ENABLED
TR_DEBUG_PRINT_CORE_COLOR=DEBUG_DEFAULT	color to use, select option from color table above.	YES	TR_DEBUG_PRINT_COLOR_ENABLED TR_DEBUG_PRINT_CORE_ENABLED
TR_DEBUG_PRINT_APP_COLOR=DEBUG_MAGENTA	color to use, select option from color table above.	YES	TR_DEBUG_PRINT_COLOR_ENABLED TR_DEBUG_PRINT_APP_ENABLED
TR_DEBUG_PRINT_ZCL_COLOR=DEBUG_GREEN	color to use, select option from color table above.	YES	TR_DEBUG_PRINT_COLOR_ENABLED TR_DEBUG_PRINT_ZCL_ENABLED
TR_DEBUG_PRINT_RX_MSGS_COLOR=DEBUG_YELLOW	color to use, select option from color table above.	YES	TR_DEBUG_PRINT_COLOR_ENABLED TR_DEBUG_PRINT_RX_MSGS_ENABLED

Manufacturing Library

The MFG library plugin provides CLI commands to put the radio into different modes for testing and to calibrate things such as the external crystal (XTAL) tuning values.

Define	Value	Optional	Depends On
TR_MFG_LIB_PLUGIN_ENABLE	–	NO	Command Line Interface (CLI)

Network Rejoin

As its name indicates, the network rejoin plugin provides control over Zigbee network rejoins with configurable backoff times between rejoin attempts. Rejoin backoffs reduce battery drain when the network is not immediately available, and also reduces chatter on the Zigbee channels.

Rejoins are done in blocks with the backoff applying between each block of rejoins. The rejoin order within each block is:

Rejoin Attempt	Description
1	Secure rejoin on the current channel
2	Trust center rejoin on the current channel
3	Secure rejoin attempt across the primary channel set
4	Trust center rejoin across the primary channel set
5	Secure rejoin across the secondary channel set
6	Trust center rejoin across the secondary channel set

The rejoin backoff is configured using several macros to set the initial backoff time, the maximum backoff time, and the backoff multiplier. At boot or on successful rejoin, the backoff time is set to TR_NWK_REJOIN_INITIAL_DELAY_SEC. If the execution of a rejoin block fails to get the device back on the network, the rejoin backoff time is multiplied by TR_NWK_REJOIN_DELAY_MULTIPLIER, but the rejoin backoff time is never allowed to be longer than TR_NWK_REJOIN_MAX_DELAY_SEC. The network rejoin plugin then waits rejoin time before executing the next rejoin block.

The network rejoin plugin configuration can be set in tr_plugin_config.cmake, but the default values shown below will apply if the configuration is not set.

Define	Value	Optional	Depends On
TR_NETWORK_REJOIN_PLUGIN_ENABLE	–	NO	–
TR_NETWORK_REJOIN_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_NWK_REJOIN_INITIAL_DELAY_SEC=1	[1 - 4294967295] initial rejoin delay in seconds	YES	–
TR_NWK_REJOIN_MAX_DELAY_SEC=900	[1 - 4294967295] maximum rejoin delay in seconds	YES	–
TR_NWK_REJOIN_DELAY_MULTIPLIER=2	[1 - 255] rejoin backoff multiplier	YES	–
TR_NWK_REJOIN_ALLOW_TC_REJOINS	–	YES	–

Sleep

The sleep plugin provides APIs and callbacks for application management of sleep for a sleepy end device. The APIs allow sleep to be blocked or enabled, and the pre-sleep callback allows the application to block sleep on a per-event basis as needed. A post-wake callback allows the application to perform processing upon a wake from sleep if needed.

Define	Value	Optional	Depends On
TR_SLEEP_PLUGIN_ENABLE	–	NO	–
TR_STAY_AWAKE_WHEN_NOT_JOINED	none, define to prevent device from sleeping when not joined to a network	YES	–

The wake source for the project is defined in tr_hal_config.h. The macro TR_WAKE_SOURCES is configured as a list of wake reasons such as GPIO pins, timers, UARTs, etc. An example from the Door Lock SZED sample app is shown below. Also refer to the On/Off Switch SZED sample application.

#define TR_WAKE_SOURCES             \
        LOW_POWER_WAKEUP_GPIO4,     \
        LOW_POWER_WAKEUP_GPIO5,     \
        LOW_POWER_WAKEUP_GPIO6,     \
        LOW_POWER_WAKEUP_GPIO9,     \
        LOW_POWER_WAKEUP_GPIO20,    \
        LOW_POWER_WAKEUP_GPIO21,    \
        LOW_POWER_WAKEUP_32K_TIMER, \
        LOW_POWER_WAKEUP_UART0_RX
 
#define TR_LOW_POWER_LEVEL LOW_POWER_LEVEL_SLEEP1

The possible wake sources are:

Wake Sources
LOW_POWER_WAKEUP_RTC_TIMER
LOW_POWER_WAKEUP_COMPARATOR
LOW_POWER_WAKEUP_32K_TIMER
LOW_POWER_WAKEUP_GPIO0
LOW_POWER_WAKEUP_GPIO1
LOW_POWER_WAKEUP_GPIO2
LOW_POWER_WAKEUP_GPIO3
LOW_POWER_WAKEUP_GPIO4
LOW_POWER_WAKEUP_GPIO5
LOW_POWER_WAKEUP_GPIO6
LOW_POWER_WAKEUP_GPIO7
LOW_POWER_WAKEUP_GPIO8
LOW_POWER_WAKEUP_GPIO9
LOW_POWER_WAKEUP_GPIO10
LOW_POWER_WAKEUP_GPIO11
LOW_POWER_WAKEUP_GPIO12
LOW_POWER_WAKEUP_GPIO13
LOW_POWER_WAKEUP_GPIO14
LOW_POWER_WAKEUP_GPIO15
LOW_POWER_WAKEUP_GPIO16
LOW_POWER_WAKEUP_GPIO17
LOW_POWER_WAKEUP_GPIO18
LOW_POWER_WAKEUP_GPIO19
LOW_POWER_WAKEUP_GPIO20
LOW_POWER_WAKEUP_GPIO21
LOW_POWER_WAKEUP_GPIO22
LOW_POWER_WAKEUP_GPIO23
LOW_POWER_WAKEUP_GPIO24
LOW_POWER_WAKEUP_GPIO25
LOW_POWER_WAKEUP_GPIO26
LOW_POWER_WAKEUP_GPIO27
LOW_POWER_WAKEUP_GPIO28
LOW_POWER_WAKEUP_GPIO29
LOW_POWER_WAKEUP_GPIO30
LOW_POWER_WAKEUP_GPIO31
LOW_POWER_WAKEUP_UART0_RX
LOW_POWER_WAKEUP_UART1_RX
LOW_POWER_WAKEUP_UART2_RX

Note

The only supported value for TR_LOW_POWER_LEVEL at this time is LOW_POWER_LEVEL_SLEEP1

Plugins - Zigbee Stack

---

The stack configuration options in this section are not really plugins but things that can be defined in tr_plugin_config.cmake to modify stack behavior. These are all optional as sane default values already exist.

Zigbee R23 and Dynamic Link Key

Stack configuration defaults to r23 behavior but defining TR_ZIGBEE_R22 will force the stack to use r22 behavior. When using r23 behavior, 2 ECDH options are in play. Either or both can be disabled by defining TR_DONT_USE_ECDHE_CURVE_25519_HASH_SHA256 and/or TR_DONT_USE_ECDHE_CURVE_25519_HASH_AESMMO128.

Define	Value	Optional	Depends On
TR_ZIGBEE_R22	–	YES	–
TR_DONT_USE_ECDHE_CURVE_25519_HASH_SHA256	–	YES	!TR_ZIGBEE_R22
TR_DONT_USE_ECDHE_CURVE_25519_HASH_AESMMO128	–	YES	!TR_ZIGBEE_R22

Distributed Network Join Enable

Joining a distributed network is optional in the Zigbee Base Device Behavior (BDB) specification. This configuration macro allows this optional behavior to be enabled. If distributed network joining is enabled, the value of the manufacturing token TR_MFG_TOKEN_DISTRIBUTED_KEY is used as the distributed link key if is programmed. The global distributed key is also accepted when joining a distributed network.

Define	Value	Optional	Depends On
TR_ENABLE_JOINING_DISTRIBUTED_NETWORKS	–	YES	–

Well-known Key Network Join Enable

By default, joining using the Zigbee well-known key is disabled. Devices join networks using either a dynamic link key (DLK) or an install-code derived preshared link key (PSK). Often though devices must join older networks that do not support either DLK or PSK. In those cases, the only way to join the network is to allow the network key to be encrypted with the well-known link key. While this is not desirable from a security standpoint, it is sometimes necessary. The following macro can be defined to allow joins via the well-known link key. The joining process will be to first attempt to join across all channels, primary and secondary, with the install-code derived link key, then if that fails, try again across primary and secondary channels with both the install-code derived link key and the well-known link key.

Define	Value	Optional	Depends On
TR_ENABLE_JOINING_WITH_WELL_KNOWN_KEY	–	YES	–

Primary/Secondary Channel Masks

The Zigbee Base Device Behavior (BDB) specification calls for prioritizing the 16 Zigbee channels for initial joins and for rejoins. In most deployments this reduces the time that a device is off the network by scanning the more commonly used channels first. Those channels are typically 11, 15, 20, and 25. The primary and secondary channel masks for a project is defined in tr_plugin_config.cmake. All 16 channels should be accounted for between the 2 masks. The masks simply contain a 1 in the bit position corresponding to the desired channel. The default settings are shown below, but can be changed as desired.

Define	Value	Optional	Depends On
TR_PRIMARY_CHANNEL_MASK=0x02108800	primary channel bitmask	YES	–
TR_SECONDARY_CHANNEL_MASK=0x05EF7000	secondary channel bitmask	YES	–

End Device Keepalive

Zigbee End Devices (ZEDs and SZEDs) establish a "parent/child" relationship with a Zigbee Router (ZR) or Zigbee Coordinator (ZC) when they join or rejoin a network. That relationship can become disfunctional if the end device child and its parent don't agree. As in all relationships, communication is key. The Zigbee stack specification defines methods that end device children may use to keep their relationship with their parent in good standing.

Timeout Request

One method of maintaining the parent/child relationship is via the end device timeout request. The end device timeout request allows an end device to tell its parent what the child timeout should be, and sending that request periodically will maintain the parent/child relationship. This is a very efficient method of maintaining network connectivity, especially for battery powered devices because it reduces the number of transmits that a ZED must make.

Data Poll

MAC Data Polls can be used as a keepalive when an end device's parent is on an older Zigbee stack or does not support the end device timeout requests. Sleepy ZEDs normally implement some method for sending MAC Data Polls such as the Poll Control Server or a hardcoded Data Poll rate as a way of receiving messages. That by itself is often enough to maintain the parent/child relationship. Non-sleepy ZEDs however do not need to send MAC Data Polls in order to receive messages, but they do need to communicate with their parent on a periodic basis to maintain a functional relationship. Enabling the MAC Data Poll Keeplive will fulfill this need for a healthy relationship.

Configuration

The End Device Keepalive plugin can be configured to use data polls as a keepalive, end device timeouts, both, or neither. If both methods are selected and the parent does not support end device timeout, then the ZED will fall back to data polls. The configuration is set in tr_plugin_config.cmake and the options are shown below:

End Device Timeout Configurations
ED_AGING_TIMEOUT_10SEC
ED_AGING_TIMEOUT_2MIN
ED_AGING_TIMEOUT_4MIN
ED_AGING_TIMEOUT_8MIN
ED_AGING_TIMEOUT_16MIN
ED_AGING_TIMEOUT_32MIN
ED_AGING_TIMEOUT_64MIN
ED_AGING_TIMEOUT_128MIN
ED_AGING_TIMEOUT_256MIN
ED_AGING_TIMEOUT_512MIN
ED_AGING_TIMEOUT_1024MIN
ED_AGING_TIMEOUT_2048MIN
ED_AGING_TIMEOUT_4096MIN
ED_AGING_TIMEOUT_8192MIN
ED_AGING_TIMEOUT_16384MIN

End Device Keepalive Method
ED_KEEPALIVE_DISABLED
MAC_DATA_POLL_KEEPALIVE
ED_TIMEOUT_REQUEST_KEEPALIVE
BOTH_KEEPALIVE_METHODS

Define	Value	Optional	Depends On
TR_ED_AGING_TIMEOUT ED_AGING_TIMEOUT_64MIN	timeout duration macro	YES	–
TR_ED_KEEPALIVE_INTERVAL_MS=300000	[1000 - 327680000] keepalive interval in milliseconds	YES	–
TR_ED_KEEPALIVE_METHOD=BOTH_KEEPALIVE_METHODS	keepalive method macro	YES	–

Plugins - ZCL

---

ZCL plugins are used to add cluster functionality to a device once the cluster has been added to the project via ZAP (see ZAP User Guide). Some of these add only what the ZCL specification requires while others add some extra options on top to help bridge the gap from what the specification requires to what a real world device requires. There are often optional CLI commands that can be included in a project to give a useful interface for testing cluster functionality via the command line interface. There are also configurable debug prints for each cluster implementation that can be turned on or off to add or remove additional debug print information.

Alarms Client

Implementation of the ZCL Alarms Client cluster.

Define	Value	Optional	Depends On
TR_ALARMS_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_ALARMS_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Alarms Server

Implementation of the ZCL Alarms Server cluster.

Define	Value	Optional	Depends On
TR_ALARMS_SERVER_PLUGIN_ENABLE	–	NO	–
TR_ALARMS_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Basic Client

Implementation of the ZCL Basic Client cluster.

Define	Value	Optional	Depends On
TR_BASIC_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_BASIC_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Basic Server

Implementation of the ZCL Basic Server cluster.

Define	Value	Optional	Depends On
TR_BASIC_SERVER_PLUGIN_ENABLE	–	NO	–
TR_BASIC_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Color Control Server

Implementation of the ZCL Color Control Server cluster.

Define	Value	Optional	Depends On
TR_COLOR_CONTROL_SERVER_PLUGIN_ENABLE	–	NO	–
TR_COLOR_CONTROL_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_COLOR_CONTROL_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Door Lock Server

Implementation of the ZCL Door Lock server cluster. This implementation is NOT complete. It provides manadory functionality and management of a user table including PIN code verification.
This implementation does not include the following:

• storing user table in NVRAM
• user schedules
• logging

Define	Value	Optional	Depends On
TR_DOOR_LOCK_SERVER_PLUGIN_ENABLE	–	NO	–
TR_DOOR_LOCK_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_DOOR_LOCK_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_DOOR_LOCK_SERVER_MAX_PIN_LEN=4	[1 - 255] max pin code length	YES	–
TR_DOOR_LOCK_SERVER_MAX_NUM_USERS=8	[1 - 255] max number of PIN users	YES	–

Door Lock Server Plugin Received Commands Implemented
The following received commands are implemented in the door lock server plugin. Application callbacks are available for each command, allowing door lock server plugin functionality to be overridden on a per-command basis.

Command	Description
TR_ZCL_CMD_LOCK_DOOR_ID	Lock the door, with optional PIN/RFID code
TR_ZCL_CMD_UNLOCK_DOOR_ID	Unlock the door, with optional PIN/RFID code
TR_ZCL_CMD_SET_PIN_ID	Set the PIN code for the specified user ID in the user table
TR_ZCL_CMD_GET_PIN_ID	Retrieve the PIN code for the specified user ID from the user table
TR_ZCL_CMD_CLEAR_PIN_ID	Delete the PIN code for the specified user ID from the user table
TR_ZCL_CMD_CLEAR_ALL_PINS_ID	Clear the PIN codes for all user IDs from the user table
TR_ZCL_CMD_SET_USER_STATUS_ID	Set the status of a user ID in the user table
TR_ZCL_CMD_GET_USER_STATUS_ID	Retrieve the status of a user ID from the user table
TR_ZCL_CMD_SET_USER_TYPE_ID	Set the user type of a user ID in the user table
TR_ZCL_CMD_GET_USER_TYPE_ID	Retrieve the user type of a user ID from the user table

Groups Client

Implementation of the ZCL Groups Client cluster.

Define	Value	Optional	Depends On
TR_GROUPS_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_GROUPS_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Groups Server

Implementation of the ZCL Groups Server cluster. This plugin contains an optional feature that allows bindings to be created automatically when an add to group command is received. This is done by defining TR_GROUPS_SERVER_AUTO_BIND_ENABLE in tr_plugin_config.cmake and including the required dependency outlined in the table below.

Define	Value	Optional	Depends On
TR_GROUPS_SERVER_PLUGIN_ENABLE	–	NO	–
TR_GROUPS_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_GROUPS_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_GROUPS_SERVER_AUTO_BIND_ENABLE	–	YES	Bind

Identify Client

Implementation of the ZCL Identify Client cluster.

Define	Value	Optional	Depends On
TR_IDENTIFY_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_IDENTIFY_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Identify Server

Implementation of the ZCL Identify Server cluster.

Define	Value	Optional	Depends On
TR_IDENTIFY_SERVER_PLUGIN_ENABLE	–	NO	–
TR_IDENTIFY_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_IDENTIFY_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Level Control Client

Implementation of the ZCL Level Control Client cluster. If enabled, this has CLI commands for sending commands to a device implementing Level Control Server.

Define	Value	Optional	Depends On
TR_LEVEL_CONTROL_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_LEVEL_CONTROL_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Level Control Server

Implementation of the ZCL Level Control Server cluster. This keeps track of the level based on received commands and also changes level over time as necessary. If On/Off Server plugin is enabled then this plugin can adjust it based on the commands received.

Define	Value	Optional	Depends On
TR_LEVEL_CONTROL_SERVER_PLUGIN_ENABLE	–	NO	–
TR_LEVEL_CONTROL_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_LEVEL_CONTROL_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

On/Off Client

Implementation of the ZCL On/Off Client cluster.

Define	Value	Optional	Depends On
TR_ON_OFF_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_ON_OFF_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

On/Off Server

Implementation of the ZCL On/Off Server cluster. This is currently a wrapper of the existing ZBOSS ZCL implementation and will be updated to be a full Trident plugin soon.

Define	Value	Optional	Depends On
TR_ON_OFF_SERVER_PLUGIN_ENABLE	–	NO	–
TR_ON_OFF_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

On/Off Switch Configuration Client

Implementation of the ZCL On/Off Switch Configuration Client cluster.

Define	Value	Optional	Depends On
TR_ON_OFF_SWITCH_CONFIGURATION_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_ON_OFF_SWITCH_CONFIGURATION_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

On/Off Switch Configuration Server

Implementation of the ZCL On/Off Switch Configuration Server cluster.

Define	Value	Optional	Depends On
TR_ON_OFF_SWITCH_CONFIGURATION_SERVER_PLUGIN_ENABLE	–	NO	–
TR_ON_OFF_SWITCH_CONFIGURATION_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Over the Air Bootloading Client

The Over the Air (OTA) Bootloading Client plugin is an implementation of the OTA client cluster. It provides APIs and callbacks that can be used by the application for managing firmware upgrades and also provides an interface to the FLASH and the bootloader. The OTA client plugin will start when a device successfully joins or rejoins a network. The first Query Next Image Request (QNIR) will be sent at a random time between 1 and 5 minutes after the network achieves the joined state. After that, QNIRs will be sent based on the value of the TR_OVER_THE_AIR_BOOTLOADING_CLIENT_QUERY_DELAY_MINUTES macro. The TR_OVER_THE_AIR_BOOTLOADING_CLIENT_MAX_DATA_SIZE macro is used to limit the amount of data returned by the OTA Upgrade Server. The server will also limit the data based the available payload in the Zigbee packet. For greatest efficiency (i.e. fewest packets), keep this macro set to a large number like 64. Inclusion of the hardware version in the QNIR command is configured using TR_OVER_THE_AIR_BOOTLOADING_CLIENT_QUERY_INCLUDE_HW_VERSION. If that is defined to a 1, the hardware version will be included. Inclusion of the IEEE address is configured using TR_OVER_THE_AIR_BOOTLOADING_CLIENT_IMAGE_BLOCK_REQUEST_INCLUDE_IEEE_ADDRESS. If that is set to 1 then the device's IEEE address will be included in the image block requests. The plugin can also be configured to allow only firmware upgrades (new firmware version numerically greater than the current firmware version) or to also allow downgrades (new firmware version numerically less than the current firmware version). The default is to allow upgrades only, but defining TR_OVER_THE_AIR_BOOTLOADING_CLIENT_ALLOW_DOWNGRADE will allow the device to downgrade as well. This plugin also has features that are enabled by the configuration of certain attributes.

Rate Limiting

This plugin supports rate limiting IF the "Minimum Block Period" attribute is implemented. Rate limiting allows both the OTA Upgrade client and server to set the minimum block request period. Some devices may want to limit how often image block requests are sent to manage their battery, and OTA Upgrade servers may want to limit image block requests in order to manage network bandwidth.

Resume Upgrade on Reboot

This plugin supports "resume upgrade on reboot" IF the "File Offset" attribute is implemented and stored in NVRAM and if the "Image Upgrade Status" attribute is also configured to be stored in NVRAM. This feature allows a partial upgrade to be resumed upon device reboot rather than requiring a full restart.

Support for Multi-processor Upgrades

This plugin supports multi-processor upgrades by including manufacturer specific sub element tags in the .ota file. Manufacturer specific sub element tags have a tag id value between 0xF000 and 0xFFFF. Note that tag id 0xFFFF is reserved by this plugin for internal use. If a manufacturer specific sub element is found after the .ota file has been downloaded, a user callback will be invoked BEFORE the Zigbee firmware image (if any) is applied. The plugin also provides an API that the application can use to search for a specific sub element in the downloaded image.

More details of the application interface can be found in Over the Air Bootloading client Callbacks and the Over the Air Bootloading client APIs.

Configuration

Define	Value	Optional	Depends On
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_QUERY_DELAY_MINUTES=60	[1 - 10080] how often to send query next image requests in minutes	YES	–
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_MAX_DATA_SIZE=64	[1 - 255] maximum number of bytes to request in an image block request	YES	–
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_QUERY_INCLUDE_HW_VERSION=0	[0 - 1] 1 to include the device hardware version in the query next image request, 0 to not include it	YES	–
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_IMAGE_BLOCK_REQUEST_INCLUDE_IEEE_ADDRESS=0	[0 - 1] 1 to include the device IEEE address in the image block requests, 0 to not include it	YES	–
TR_OVER_THE_AIR_BOOTLOADING_CLIENT_ALLOW_DOWNGRADE	–	YES	–

Poll Control Server

Implementation of the ZCL Poll Control Server cluster. See Poll Control server Callbacks for all the application callbacks that can be implemented for this plugin.

Define	Value	Optional	Depends On
TR_POLL_CONTROL_SERVER_PLUGIN_ENABLE	–	NO	–
TR_POLL_CONTROL_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Power Configuration Client

Implementation of the ZCL Power Configuration Client cluster.

Define	Value	Optional	Depends On
TR_POWER_CONFIGURATION_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_POWER_CONFIGURATION_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Power Configuration Server

Implementation of the ZCL Power Configuration Server cluster. This plugin contains an additional configuration option to latch the low battery status bits in the battery alarm state attribute when the TR_POWER_CONFIGURATION_SERVER_BATTERY_LATCHING option is defined in tr_plugin_config.cmake. This prevents the battery alarm state from being cleared when a voltage level drifts back above the respective trip points and requires a device reboot to show a good battery status again.

Define	Value	Optional	Depends On
TR_POWER_CONFIGURATION_SERVER_PLUGIN_ENABLE	–	NO	–
TR_POWER_CONFIGURATION_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_POWER_CONFIGURATION_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_POWER_CONFIGURATION_SERVER_BATTERY_LATCHING	–	YES	Bind

Remote CLI Client

This plugin enables the sending of Zigbee Command Line Interface command strings to other nodes on the Zigbee network. In order to receive the CLI commands and handle them appropriately, the receiving node must support the Remote CLI Server.

Define	Value	Optional	Depends On
TR_REMOTE_CLI_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_REMOTE_CLI_CLIENT_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_REMOTE_CLI_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Remote CLI Server

This plugin enables Trident CLI command strings to be received over the air via Zigbee packets. The command strings are passed to the Zigbee Command Line Interface for parsing just like UART command strings are. The output from the CLI command execution is then packaged up and sent back out over Zigbee.

Define	Value	Optional	Depends On
TR_REMOTE_CLI_SERVER_PLUGIN_ENABLE	–	NO	–
TR_REMOTE_CLI_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_REMOTE_CLI_SEND_BUFFER_SIZE=4096	[1 - 65535] size of remote cli transmit buffer	YES	–
TR_REMOTE_CLI_SEND_PACKET_PAYLOAD_SIZE=47	[1 - 255] max size of remote cli packet payload	YES	–

Scenes Client

Implementation of the ZCL Scenes Client cluster. If enabled, this plugin provided CLI commands that can be used to send Scenes commands to the Scenes Server.

Define	Value	Optional	Depends On
TR_SCENES_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_SCENES_CLIENT_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print

Scenes Server

Implementation of the ZCL Scenes Server cluster. This handles all Scenes Server Client messages and manages the scenes table. If enabled, this plugin provides CLI commands that allow viewing the existing scenes table.

Define	Value	Optional	Depends On
TR_SCENES_SERVER_PLUGIN_ENABLE	–	NO	Groups Server
TR_SCENES_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_SCENES_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_SCENES_SERVER_SCENE_TABLE_NUM_ENTRIES=12	[1 - 16] number of entries in the Scenes Table	YES	–

Thermostat Server

Implementation of the ZCL Thermostat Server cluster.

Define	Value	Optional	Depends On
TR_THERMOSTAT_SERVER_PLUGIN_ENABLE	–	NO	Groups Server
TR_THERMOSTAT_SERVER_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_THERMOSTAT_SERVER_PLUGIN_PRINT_ENABLE=1	1 to enable, 0 to disable	YES	Debug Print
TR_THERMOSTAT_SERVER_PLUGIN_SCHEDULE_ENABLE	–	YES	–
TR_THERMOSTAT_SERVER_PLUGIN_SCHEDULES_PER_DAY=4	[1 - 12] number of schedules per day	YES	TR_THERMOSTAT_SERVER_PLUGIN_SCHEDULE_ENABLE

Time Client

Implementation of the ZCL Time Client cluster. This plugin discovers a Time Server on the network and reads the time from this server by sending ZCL Read Attribute Request commands and parsing the ZCL Read Attribute Response commands. There are no cluster specific ZCL commands or attributes for this cluster.

The user of this plugin can set the rediscovery period of the Time Server and also the resynchronization period for re-reading the time attribute from the Time Server.

Define	Value	Optional	Depends On
TR_TIME_CLIENT_PLUGIN_ENABLE	–	NO	–
TR_TIME_CLIENT_PLUGIN_CLI_ENABLE	–	YES	Command Line Interface (CLI)
TR_TIME_CLIENT_PLUGIN_PRINT_ENABLE	1 to enable, 0 to disable	YES	Debug Print
TR_TIME_CLIENT_PLUGIN_SERVER_REDISCOVERY_PERIOD_MINS	[15 - 65535] server rediscovery period in minutes	YES	–
TR_TIME_CLIENT_PLUGIN_RESYNC_PERIOD_MINS	[15 - 65535] resync period in minutes	YES	–