Basic Usage

This section covers the most basic usage of the build system for creating a Z-Wave application.

See Advanced Usage for more advanced usage.

Directory Structure

The following shows the directory structure for the Switch On/Off sample application (output from tree -L 2).

.
├── CMakeLists.txt
├── CMakePresets.json
├── app
│   ├── CMakeLists.txt
│   ├── SwitchOnOff.yaml
│   ├── app.c
│   └── events.h
├── hardware
│   ├── CMakeLists.txt
│   └── src_hw_neptune_usb_T32CZ20
├── trident.toml
└── tridentiot-sdk
    ├── framework
    ├── platform
    └── z-wave

CMakePresets.json

Enables easy compilation of a CMake project by offering presets.

CMakePresets.json inherits from the CMakePresets.json in tridentiot-sdk/z-wave making at least two presets available: T32CZ20.Debug and T32CZ20.Release.

Using these presets replaces the need for passing several options to CMake on the command line.

CMakeLists.txt

To put it briefly, this file basically tells CMake what to do.

Example:

cmake_minimum_required(VERSION 3.23.5)
 
project(my_application
        VERSION 24.10.0
        LANGUAGES C ASM)
 
add_subdirectory(tridentiot-sdk/z-wave)
 
zw_create_app(
  "${CMAKE_PROJECT_NAME}" # Name
  "src/app.c"             # Source files
  ""                      # Sources region
  ""                      # Include directories
  ""                      # CMake libraries
  ""                      # Definitions
  "REGION_EU"             # Region(s)
)

cmake_minimum_required() sets a minimum version of CMake required to build this project.

project() sets the name of the project and some additional information that CMake uses for configuration.

add_subdirectory() enables CMake to find the Z-Wave SDK and makes zw_create_app() among other CMake functions available to the application project.

The build system will create an application target (*.elf) when zw_create_app() is invoked, but the actual binary file won't be available until make is run.

More information about CMakeLists.txt can be found here.

tridentiot-sdk/

Contains the Z-Wave SDK and other resources to enable application development.

app/SwitchOnOff.yaml

This file contains configuration for the Z-Wave command classes. The content of the file depends on the required and desired command classes. Furthermore, some command classes require configuration while others don't.

The build system will process this file and generate C source and header files files with configuration.

app/

This folder contains the source files of the application.

Advanced Usage

Automatic discovery of source files

zw_create_app() supports a more advanced use case in combination with tr_zw_generate_hardware_libraries().

tr_zw_generate_hardware_libraries() automatically discovers source files in directories matching the pattern src_hw_*_T32CZ20. If found, an object library is created for each directory matching the pattern.

For each library, zw_create_app() creates an application target (*.elf).

Note: cmake --preset <preset> must be run when adding or removing files in a src_hw_*_T32CZ20 directory.

We use this functionality internally in Trident IoT because it's convenient for supporting more than one hardware target, i.e. PCB revision A and B, during development where tests might continue to run on revision 1 while adding support for revision 2 without the need for creating a new application project.

Example of folder structure:

app/
-> CMakePresets.json
-> CMakeLists.txt
-> tridentiot-sdk/z-wave/
-> app/
   -> app.c
   -> app.yaml
-> hardware/
   -> src_hw_boardone_T32CZ20
      -> gpio_constants.h
      -> temperature_sensor_one.c
   -> src_hw_boardtwo_T32CZ20
      -> gpio_constants.h
      -> temperature_sensor_two.c
   -> src_hw_common
      -> temperature_sensor.h

In the above example two different targets will be generated. One for board one and another for board two.

Board one has a certain combination of GPIOs and a specific temperature sensor using I2C. Board two has a another combination of GPIOs and a different temperature sensor using SPI.

src_hw_boardone_T32CZ20 contains GPIO constants for buttons, LEDs, etc. and a driver for the temperature sensor on board one. src_hw_boardtwo_T32CZ20 contains GPIO constants for buttons, LEDs, etc. and a driver for the temperature sensor on board two. src_hw_common contains a header file that declares the temperature sensor API.

Customizing filenames

The build system supports customizing the names of the generated binaries.

This can be done by setting a specific variable partly based on the project name: <project_name>_TARGET_NAME_TEMPLATE.

Example:

Setting the project name to "my_application" makes the build system look for a variable named MY_APPLICATION_TARGET_NAME_TEMPLATE.

set(MY_APPLICATION_TARGET_NAME_TEMPLATE "{{name}}_{{version}}.elf")
 
zw_create_app(
  "my_application"        # Name
  .
  .
  .
)

Template variables

Supports the following variables:

name (CMAKE_PROJECT_NAME)
version (<project_name>_CUSTOM_VERSION or built-in CMake version variables)
commit (git commit, only available if the application folder is a git repository)
hardware (if using tr_zw_generate_hardware_libraries())
region (us, eu, ...)
build_type (debug / release)