- Generated on for Trident IoT Zigbee SDK by
1.15.0
The Zigbee SDK build system is based on CMake.
It's not important to know much about CMake to compile a Zigbee application, but the more knowledge, the more flexibility.
This page explains what you can expect to find inside a Zigbee project, what the build output contains, some details of how the secure bootloader is tied into all of this, and some common troubleshooting steps.
The following shows the directory structure for the On/Off Switch project template (output from tree -L 2). The below sections will explain what all these files/directories are used for in a project.
| File Name | Description | Notes |
|---|---|---|
| app_gcc_cm3_mcu_2mb.ld | Linker file for T32CM11C | Can be modified to change flash partition sizes (must update OTA logic to align with correct addesses) |
| arm-gcc-toolchain-T32CM11.cmake | Toolchain file for T32CM11C | Used to set compiler/linker flags for the build |
| CMakeLists.txt | Primary build system file, contains all files being built | Common file to modify to add/remove functionality from a project |
| CMakePresets.json | Build presets used by elcap to build a project | Changing the presets may break the elcap build capabilities |
| config.cmake | Configuration file for high level build system settings | Can be modified to adjust things like signing keys location or Zigbee device type |
| tr_plugin_config.cmake | Configuration file for adding/modifying plugins | Can be modified to change which plugins exist in the project and modify and plugin settings |
bootloader sub-directory structure within the project (output from tree -L 3)
| File Name | Description | Notes |
|---|---|---|
| bootloader_gcc_cm3_mcu.ld | Linker file for T32CM11C bootloader | Should not be modified |
| arm-gcc-toolchain-BTL-T32CM11.cmake | Toolchain file for T32CM11C bootloader | Used to set compiler/linker flags for the build |
| CMakeLists.txt | Primary build system file | Should not be modified |
| config.cmake | Used to set relevant paths | Should not be modified |
| hal_config_custom_T32CM11/ | Contains hardware configs for CM11 based custom PCB target | Users should modify these for custom PCB targets as needed |
| hal_config_dkncm11_T32CM11/ | Contains hardware configs for DKNCM11 PCB target | Users can modify these as needed |
| src/ | Contains source files for bootloader project | Can modify as needed, any files added here will be added to the build |
Hardware files for the application exist in 2 directories by default:
| Directory Name | Description | Notes |
|---|---|---|
| hal_config_custom_T32CM11/ | Contains hardware configs for CM11 based custom PCB target | Users should modify these for custom PCB targets as needed |
| hal_config_dkncm11_T32CM11/ | Contains hardware configs for DKNCM11 PCB target | Users can modify these as needed |
This mechanism provides a powerful way to support multiple PCB targets within a single build. It enables Trident engineers to deliver higher-quality support, since we can run your application on hardware we already have available.
Each hal_config directory contains the configuration files that adapt the Trident HAL to a specific PCB. These files define how the HAL interfaces with the chip peripherals for each supported PCB target.
The generated directory contains all application-layer configuration files. All of these files are automatically produced by the ZAP tool and should never be edited by hand. Instead, update configurations through ZAP and re-generate the files to ensure consistency.
| ZAP Generated File Name | Description | Notes |
|---|---|---|
| tr_zcl_endpoint_config.c | Configures device endpoint(s) and ZCL profile | Do not edit manually |
| tr_zcl_endpoint_config.h | Configures device endpoint(s) and ZCL profile | Do not edit manually |
| tr_zcl_id.h | List of all ZAP supported ZCL IDs | Do not edit manually |
| tr_zcl_plugin_include.h | Includes all enabled ZCL plugin header files | Allows app to utilize enabled Trident ZCL plugins. Do not edit manually |
| tr_zcl_plugin_stubs.c | ZCL plugin initialization stubs file | Allows app to build with or without Trident ZCL plugins. Do not edit manually |
| tr_zcl_type.h | ZCL definitions for types, enums, and data structures | Do not edit manually |
The private_key.pem and public_key.der keys are required to satisfy the secure bootloader. These keys will be generated by the build system if they do not exist. If the files to exist as described in the config.cmake file, then those keys will be used instead.
Key Generation Logic
Manual Key Generation
If you wish to create the signing keys manually, you can do so with the following commands:
The src directory is where all application-specific logic should be implemented. This is the place to add your project’s custom source and header files.
The build system automatically includes files in src recursively, so you can freely organize your code into subdirectories and layers of modules without additional configuration. Any .c or .h files placed anywhere under src will be picked up during the build.
The tridentiot-sdk directory contains all of the SDK components relevant to Zigbee projects. This means the SDK already includes the full set of source files, libraries, and headers needed for development.
When you want to add functionality to your project, you do not need to create or copy new files. Instead, you simply update your project’s tr_plugin_config.cmake file to enable the desired plugin. The build system will include the needed files automatically based on the configurations selected.
If you want to add file of your own, just put them inside of the project's src directory and they will be added on the next full build.
A project also includes several supporting files that are primarily used by development tools and for reference:
The output of the build contains a mixture of files that can be used to:
The build output for the On/Off Switch project template example can be found below:
During the build process, several .bin, .elf, and .hex files are generated. Most of these are intermediate artifacts that you typically won’t need, but they are preserved in case you want to use them to create other outputs.
For example, a .bin file is required when generating custom OTA files with Trident tools.
File Naming Convention
Build outputs follow the naming pattern:
For instance, the On/Off Switch project produces files for both a custom PCB target and the Trident development board (DKNCM11).
Commonly Used Files (Example using DKNCM11 PCB target)
| File Name | Description | Notes |
|---|---|---|
| switch-dkncm11-signed-combined.hex | Signed application combined with bootloader and TR_MFG_TOKEN_SIGNED_BOOTLOADER_KEY tokens | This file allows a device to boot and run out of the box |
| switch-dkncm11-signed.hex | Signed application without bootloader or token data | Useful for reprogramming a running device without the bootloader |
| switch-dkncm11-signed.bin | Signed binary file without flash address information | Useful for creating custom OTA files using elcap |
An over-the-air upgrade (OTA) file will be generated at build time if the following requirements are met:
If all above requirements are satisfied, the build system will pull the default values for these attributes from the ZAP generated files to construct the following OTA files (Example using DKNCM11 PCB target):
| File Name | Description | Notes |
|---|---|---|
| switch-dkncm11-v0x01020304.ota | OTA upgrade file for switch application | Uses default attribute values generated from ZAP to populate version, MFG ID, and Image Type ID |
| null-file-v0x00000001.ota | NULL downgrade file for certification testing | Uses default attribute values generated from ZAP to populate MFG ID, and Image Type ID |
| null-file-v0xffffffff.ota | NULL upgrade file for certification testing | Uses default attribute values generated from ZAP to populate MFG ID, and Image Type ID |
Build System Generated OTA File Helpful Information
Debugger project files compatible with Segger Ozone are generated as part of the build process (Eg. switch-dkncm11.jdebug). To use this file to debug a project please see: Debugging a Project using SEGGER Ozone
There are 2 areas that generate token related files when a project is built:
First, the signing key MFG token data file (Eg. tr_public_signing_key.json) contains the data needed by the bootloader to verify the image signature at boot. This file can be used along with elcap to write those tokens manually. For example:
Second, in order to use the APP specific tokens defined in src/project_app_tokens.h, the flash address information needs to be defined in a format that elcap can use to locate them. This token definition file (Eg. T32CM11C_app_token_def.json) provides that address data to elcap. Please see the elcap Tokens documentation for details on how to use this.
The build directory contains two types of subdirectories:
Example:
Build artifact directories (e.g., T32CM11C.Debug) contain the compiled outputs as described in the previous sections.
Generated directory serves two purposes:
Once flash protection is enabled on the T32CM11C, the SWD interface is disabled. This means that after the device is locked, it cannot be unlocked through SWD alone.
An unlock application is included in every project build to provide a method for recovering SWD access while preserving security. This unlock app is signed using the project’s signing keys, ensuring that its signature is verified before the device is unlocked.
Using the Unlock Application
Unlocking a locked device requires transferring the signed unlock binary to the target using XMODEM.
1.15.0