Trident IoT Z-Wave SDK
Loading...
Searching...
No Matches
Radio CLI

User Interface on the DKNCZ20 board

The UART is by default set up to 230400,8,N,1

The supported commands can be seen by writing help on the terminal

Radio CLI basics

The Radio CLI tool can be used to test the radio functionality of a Z-Wave board

UART configuration

Default UART configuration uses UART0 (pin 16,17) set to 230400,N,8,1 The UART configuration can be changed but requires a recompilation of the project.

Using the Radio CLI test tool

  1. Program the binary to a Z-Wave chip
  2. Connect to the chip with a terminal program set to the correct UART and configuration
  3. Type help for a list of commands

Examples of using the Radio CLI

Here are some examples of setting up Z-Wave in the radio CLI

Transmitting a frame on us region at 100kbps

Setting up the radio for the US region and transmit a default frame at the 100kbps channel with Tx power 0dBm

> zw-region-set 1
Region 1, Tx channel 0
> zw-homeid-set 0x11111111
Setting homeID to 11111111
> zw-init
Z-Wave Radio initialized to Region US (1), Tx channel 0
> zw-nodeid-set 2
Setting nodeID to 2
> zw-tx-channel-set 0
Tx channel 0
Using default payload
> zw-tx-power-set 0
Tx Power on channel 0, set to 0dBm
> tx 1
TX int_region=1(1,0),ch=0(0),pwr=0(0),cnt=1,lbt=1,delay=100ms-OK
Transmit complete, 1 success, 0 failed, 0 lbt_failed

This should transmit one frame on the US region 100kbps frequency

Transmitting a constant carrier on us region at the 100kbps frequency

The Radio Test Tool can be setup to enable a continuous unmodulated carrier signal on a specific channel in a specific Z-Wave region. This example makes a continuous unmodulated carrier signal on Z-Wave region US_LR, channel 0 (100kbit GFSK channel).

> zw-region-set 9
Region 9, Tx channel 0
> zw-init
Z-Wave Radio initialized to Region US_LR_912MHz (9), Tx channel 0
> zw-tx-channel-set 0
Tx channel 0
Using default payload
> zw-tx-power-set 0
Tx Power on channel 0, set to 0dBm
> tx 1
TX int_region=9(9,1),ch=0(0),pwr=0(0),cnt=1,lbt=1,delay=100ms-OK
Transmit complete, 1 success, 0 failed, 0 lbt_failed
> rx off
Rx off - Received 0 frames
> zw-radio-tx-continues-set on 0
Continuous unmodulated signal transmit mode enabled

This should enable a measurable unmodulated carrier signal at 916 MHz

To stop carrier signal do a power off/reset of device

Using GPIO's to show radio state

Using Radio Test Tool for determining which state the RF radio is in by routing radio state to GPIO pins

> zw-radio-rf-debug-set on
Reset module to put the new rf state gpio settings into effect
> reset
Radio firmware version=0000036B
RF Rx and Tx state on GPIO 21 and 28 enabled - 1 = active
RF MCU state on GPIO 0 enabled - 1 = active, 0 = sleep
Trident Radio Test CLI version 0.5.2 git hash 57e6ae1a
Radio firmware version=0000036B
Current Z-Wave Region 9
Current Tx max power setting 14dBm
section windowsensor Window Sensor The Z Wave Window Sensor application reports when a and S2_AUTHENTICATED The Window Sensor transmits the following CC Notification types their version
Definition app_windowsensor.dox:26

To turn the radio debug feature off again use the command

> zw-radio-rf-debug-set off
zw-radio-rf-debug-set off
Reset module to put the new rf state gpio settings into effect
> reset
Trident Radio Test CLI version 0.5.2 git hash 57e6ae1a
Current Z-Wave Region 9
Current Tx max power setting 14dBm

Using the script feature to test CZ20 devices

When the CLI tool is flashed into the CZ20, it allows the CZ20 to be controlled from a serial connection to a terminal program such as PuTTY. The serial settings are 230400 baud, 8 data bits, no parity, 1 stop bit, and implicit CR after a LF should be enabled.

The help command will list all of the available commands in the CLI tool. In addition to using commands to control the CZ20 in real time, up to five scrips can be stored in the CZ20 (script 1 thru script 5). Any of these scripts can be executed from the command line interface without the need to retype each command in the script. In addition to executing a script from the command line, the CZ20 can also be configured to execute one of the scripts following a reset or at power up. This is very helpful if you need to have the device go into a specific mode of operation for testing when a battery is installed, without the need for a physical connection to a terminal.

This feature can especially be usefull when doing RF regulatory compliance testing (like FCC) where a console connection to the device under test is not possible during testing.

As an example, suppose you wanted the device to go into receive mode on the 916 MHz classic Z-Wave channel on power up by storing a configuration in Script 3.

First enter following line followed by a 'return'

script start 3

The CLI tool will return

Clearing Script 3
Enter script commands (use tab completion). Type .done when finished

Next enter the commands/lines followed by a 'return' needed for the script

zw-init
zw-region-set 1
zw-rx-channel-set 0
rx on
.done

The .done command saves the script. The CLI will on the terminal return

Script entry done

To check the contents of Script 3, enter following on the terminal

script list 3

This will print out Script 3 contents on the terminal.

To execute Script 3 while the terminal is connected enter

run 3

If you wish to have Script 3 execute on powerup, type

script autoon 3

The CLI tool will return on the terminal

Script 3 autorun on upstart enabled

At this point, the device can be disconnected from the terminal and Script 3 will be executed whenever the device powers up or resets.

Script commands including start, stop, autoon, autooff, list and clear can be found by using the 'help' commmand when the device is connected.

Advanced Script Editing

Editing Existing Scripts

The radio CLI supports editing existing scripts without retyping everything from scratch. Use the script edit command to load and modify an existing script:

> script edit 3
Editing Script 3 (4 existing lines)
Existing script commands:
[1]: zw-init
[2]: zw-region-set 1
[3]: zw-rx-channel-set on 0
[4]: rx on
You can add/edit lines (use tab completion). Type .done when finished
Edit commands: .replace .delete .insert .clear - Type .help for details
Script-3[5]:>

This will:

  • Load script 3 from flash memory
  • Display all existing lines with line numbers
  • Enter edit mode where you can modify the script

Load Mode (Bulk Entry Without Parser)

For loading multiple lines from your clipboard, use script load which completely bypasses the CLI parser and writes raw input directly to the script:

> script load 1
Starting Script 1 load mode (bypassing CLI parser)
Load multiple lines from clipboard. Each line stored as-is.
Type .done when finished, .cancel to abort
Available: .list .help .done .cancel
Script-1[1]:> zw-region-set 9
Script-1[2]:> zw-init
Script-1[3]:> zw-tx-delay-set 30
Script-1[4]:> zw-tx-power-set 14
Script-1[5]:> rx on
Script-1[6]:> .done
Script 1 entry complete - 5 lines saved

This mode is ideal when you have a list of commands in a text file and want to load them all at once. The CLI will:

  • Bypass embedded-cli parser completely
  • Capture raw UART input character-by-character
  • Store each line exactly as loaded, preserving all formatting

Load Mode Commands:

  • .done - Save script and exit load mode
  • .cancel - Discard changes and exit load mode
  • .list - Display current script lines
  • .help - Show load mode help

Note: Load mode bypasses all embedded-cli parsing. Each line is stored as raw text. Advanced editing commands (.replace, .delete, .insert) are not available in load mode. Use script edit after saving if you need to modify specific lines.

Line Editing Commands

While in script entry or edit mode, special dot commands are available to manipulate script lines:

.replace N command - Replace a line

Replace an existing line with a new command:

Script-3[5]:> .replace 2 zw-region-set 9
Line 2 replaced: zw-region-set 9

.delete N - Delete a line

Remove a line from the script (shorthand .del also works):

Script-3[5]:> .delete 3
Line 3 deleted: zw-rx-channel-set on 0

.insert N command - Insert a line

Insert a new line before the specified position (shorthand .ins also works):

Script-3[4]:> .insert 1 zw-homeid-set 0x11111111
Line 1 inserted: zw-homeid-set 0x11111111

.clear - Clear all lines

Delete all lines in the current script:

Script-3[5]:> .clear
All lines cleared

.list - Show current script

Display all lines with line numbers and capacity:

Script-3[5]:> .list
Current script lines (4/200):
1: zw-homeid-set 0x11111111
2: zw-init
3: zw-region-set 9
4: rx on

.done - Save and exit

Complete script entry and save to flash memory:

Script-3[5]:> .done
Script 3 entry complete - 4 lines saved

.cancel - Exit without saving

Cancel script entry and discard changes:

Script-3[5]:> .cancel
Script 3 entry cancelled

.help - Show command help

Display all available commands in script entry mode.

Example: Creating and Editing a Script

Complete example of creating and then modifying a script:

Step 1: Create initial script

> script start 1
Starting Script 1 entry mode
Script-1[1]:> zw-init
Script-1[2]:> zw-region-set 1
Script-1[3]:> tx 100
Script-1[4]:> .done
Script 1 entry complete - 3 lines saved

Step 2: Edit the script to change region and add commands

> script edit 1
Editing Script 1 (3 existing lines)
Existing script commands:
[1]: zw-init
[2]: zw-region-set 1
[3]: tx 100
Script-1[4]:> .replace 2 zw-region-set 9
Line 2 replaced: zw-region-set 9
Script-1[4]:> .insert 3 zw-tx-power-set 0
Line 3 inserted: zw-tx-power-set 0
Script-1[5]:> .list
Current script lines (4/200):
1: zw-init
2: zw-region-set 9
3: zw-tx-power-set 0
4: tx 100
Script-1[5]:> .done
Script 1 entry complete - 4 lines saved

Step 3: Verify the changes

> script list 1
Script 1 ***
zw-init
zw-region-set 9
zw-tx-power-set 0
tx 100

Script Command Summary

CommandDescription
script start N Create a new script (clears existing)
script edit N Edit an existing script
script load N Load mode (no tab-complete) for bulk entry
run N Execute a script
script list [N]List script(s) - omit N to list all
script autoon N Enable autorun for script N on boot
script autooff Disable autorun
script clear N Delete script N
script stop Stop currently running script

Below are scripts that may be helpful for making the device transmit or receive on various North American channels on power up.

CZ20 CLI Transmit scripts

Script 1 ***916MHz 100 kbps GFSK

zw-init
zw-region-set 9
zw-tx-channel-set 0
zw-tx-payload-set 11 11 11 11 02 41 06 17 01 01 01 D3 9C 01 10 00 5E 98 9F 55 6C
zw-tx-power-set 0
zw-tx-delay-set 20
tx 100000

Script 2 ***908.40MHz 40 kbps FSK

zw-init
zw-region-set 9
zw-tx-channel-set 1
zw-tx-payload-set 11 11 11 11 02 41 06 17 01 01 01 D3 9C 01 10 00 5E 98 9F 55 6C
zw-tx-power-set 0
zw-tx-delay-set 20
tx 100000

Script 3 ***908.42MHz 9.6 kbps FSK

zw-init
zw-region-set 9
zw-tx-channel-set 2
zw-tx-payload-set 11 11 11 11 02 41 06 17 01 01 01 D3 9C 01 10 00 5E 98 9F 55 6C
zw-tx-power-set 0
zw-tx-delay-set 20
tx 100000

Script 4 ***912MHz 100 kbps DSSS

zw-init
zw-region-set 9
zw-tx-channel-set 3
zw-tx-payload-set 11 11 11 11 02 41 06 17 01 01 01 D3 9C 01 10 00 5E 98 9F 55 6C
zw-tx-power-set 20
zw-tx-delay-set 20
tx 100000

Script 5 ***920MHz 100 kbps DSSS

zw-init
zw-region-set 100
zw-tx-channel-set 3
zw-tx-payload-set 11 11 11 11 02 41 06 17 01 01 01 D3 9C 01 10 00 5E 98 9F 55 6C
zw-tx-power-set 20
zw-tx-delay-set 20
tx 100000

CZ20 CLI fixed channel Receive mode scripts

Script 1 ***916MHz 100 kbps GFSK receive

zw-init
zw-region-set 1
zw-rx-channel-set on 0
rx on

Script 2 ***908.40MHz 40 kbps FSK receive

zw-init
zw-region-set 1
zw-rx-channel-set on 1
rx on

Script 3 ***908.42MHz 9.6 kbps FSK receive

zw-init
zw-region-set 1
zw-rx-channel-set on 2
rx on

Script 4 ***912MHz 100 kbps DSSS receive

zw-init
zw-region-set 9
zw-rx-channel-set on 3
rx on

Script 5 ***920MHz 100 kbps DSSS receive

zw-init
zw-region-set 100
zw-rx-channel-set on 3
rx on

User Interface for the Radio CLI test tool

The following commands can be used in the Radio CLI tool

Supported commands

CommandParametersDescription
zw-region-setRegion (0-103) - Region numberSet the desired Z-Wave region. Supported region numbers can be shown by running the zw-region-list command
zw-region-listn/aLists current region and all supported regions
zw-initn/aInitialize the Z-Wave PHY layer to the region specified with the zw-region-set command
zw-homeid-setHomeID (hexadecimal) - HomeID for receive filtering Set the desired Z-Wave HomeID for use in receive filtering
zw-nodeid-setNodeID (decimal, 0-239 for classic, 256-1024 for LR) - NodeID for receive filteringSet the desired Z-Wave nodeID for use in receive filtering
zw-tx-payload-setpayload (hexadecimal)Set the frame payload in hexadecimal bytes, If fewer than 9 bytes are provided, the default payload will be used
zw-tx-data-sethex bytes (hexadecimal)Set the frame data in hexadecimal bytes. Wraps data in Z-Wave frame: HomeID+Src+FC+Len+Dst+data (radio adds CRC).
Src uses zw-nodeid-set value, Dst uses zw-tx-destid-set value.
Example: zw-tx-data-set 20 01 FF (Basic Set ON)
zw-tx-channel-setchannel (0-3), actual channel range follows region setup - channel numberSet the transmit channel number
zw-tx-destid-setdestination node ID (0-239 and 255 for classic, 256-4095 for LR)Set transmit destination node ID. Used by zw-tx-data-set and frame construction commands
zw-tx-srcid-setsource node ID (0-239 and 255 for classic, 256-4095 for LR)Set transmit source node ID. Used by zw-tx-data-set and frame construction commands
zw-tx-homeid-sethome ID (32-bit hexadecimal, 0x00000000 - 0xFFFFFFFF)Set transmit home ID. Used by zw-tx-data-set and frame construction commands (different from zw-homeid-set which sets receive filter)
zw-tx-power-setTx power (-20 to +20 dBm).
Optional: powerindex to map Tx power to radio power index until next reset
Set the transmit power
zw-tx-power-index-listn/aList current active Tx power to radio powerindex conversion table - for current selected region and channel
zw-classic-tx-power-enableClassic Z-Wave Tx power control on none lr channels (on/off) - if on then Tx power on none lr channels are set through classic Tx power settingsEnable/disable usage of classic Z-Wave Tx power settings on none lr channels
zw-classic-tx-power-setClassic Z-Wave Tx power in dBm (-20-+20) - used on none lr channels if classic Z-Wave Tx power feature is enabledSet classic Z-Wave Tx power 'normal' setting
zw-classic-tx-power-adjust-setClassic Z-Wave Tx power adjust in dBm (-5-+5) - used on none lr channels if classic Z-Wave Tx power feature is enabledSet classic Z-Wave channel power measured at a PA setting of 0dBm
zw-classic-tx-power-attenuation-setClassic Z-Wave Tx power attenuation in dBm (0-20) - used on none lr channels if classic Z-Wave Tx power feature is enabledSet classic Z-Wave Tx power setting attenuation
zw-tx-lbt-setchannel (0-3), actual channel range follows region setup - channel number.
LBT threshold (-127-0) - Set LBT threshold in dBm, 0 equals LBT is turned off
Set transmit Listen Before Talk threshold on specified channel
zw-stats-getn/aGet network statistics from the PHY layer
zw-stats-clearn/aClear the network statistics and set all counters to 0
zw-tx-delay-setdelay (2-65535) - Interframe delay in msSet delay between transmitted frames when sending multiple frames
zw-tx-config-setoption (fail-crc)
state (on/off)
Set transmit options. Currently supported: fail-crc (on/off) - intentionally send frames with bad CRC for testing
zw-rx-channel-setSingle channel (on/off) - Single channel mode
Channel number (0-3) - Fixed channel
Switch between single channel and channel scanning mode.
Single channel on → disables scanning, fixes receiver to specified channel
Single channel off → enables channel scanning
zw-tx-max-power-setmax Tx power (14/20) - Max Tx power in dBm supported by the radio boardSet the max Tx power supported by the radio board. This command will only take effect after a reset command
zw-radio-tx-continues-setstate (on/off) - Set the transmit of continuous signal wave on/off
Signal wave type (0/1/2)
- 0 = unmodulated
- 1 = modulated
- 2 = modulated with whitening
Transmit an unmodulated, modulated or modulated with whitening signal wave. It is recommended to reset the module with the reset command after having sent a continuous signal wave
zw-radio-rf-debug-setDebug mode (on/off) - Turn radio debug mode on or offSet the radio debug mode on or off
Pins used:
RF Rx state on GPIO 21
RF Tx state on GPIO 28
RF MCU state on GPIO 0
zw-radio-rf-debug-reg-setting-listList radio register settings [0/1] - List selected radio register settings and optionally an extended number of radio register settingsList radio register settings, if parameter equals 1 list extended number of radio register settings
zw-radio-rssi-getchannel (0-3), actual channel range follows region setup - Get measured RSSI on channel
count - optional count times
delay ms - optional delay ms inbetween
Get last measured RSSI on channel, optional count times with optional delay ms inbetween (default 1000ms)
zw-radio-rssi-get-allcount - optional count times
delay ms - optional delay ms inbetween
Get last RSSI measurement on all region channels, optional count times with optional delay ms inbetween (default 1000ms)
zw-radio-rssi-config-setsample_freq - sample frequency in ms
average_count - number of samples for doing RSSI average
Setup RSSI noise level to be sampled every sample_freq ms and generate an average out of average_count samples. Disable with 'zw-radio-rssi-config-set 0 0'
txrepeat - number of times the frame should be transmittedSend repeat frames
zw-tx-beam<repeat>Send Z-Wave beam followed by frame, repeat this <repeat> times with delay set by zw-tx-delay-set in between. Used for testing FLiRS/beam-wake devices.
zw-tx-beam-fragment<repeats> <destid>Transmit <repeats> Z-Wave beam fragments back-to-back to <destid>. Used for advanced FLiRS/beam timing tests.
rxRx mode (on/off) - Receive modeSet the receiver on or off
stopn/aStop any ongoing repeated or continuous operations.
Affects: tx (repeated frames), rx (continuous receive), zw-tx-beam, zw-rx-beam, run (script execution), zw-radio-rssi-get, zw-radio-rssi-get-all.
Does NOT affect one-time transmissions already in progress or configuration commands
zw-rx-beam<repeat> [wakeup_ms]Receive Z-Wave beam and frame, repeat <repeat> times with optional wakeup period [wakeup_ms] (default 1000ms). Used for testing beam reception and frame handling in power-managed or FLiRS devices.
timestampenable <on/off> - enable/disable timestamp in msEnable/Disable timestamp in ms on line output
resetn/aPerform a soft reset of the radio board
scriptcmd
- autoon [1-5] - enable active or specified script run on startup
- autooff [1-5] - disable active or specified script run on startup
- start [1-5] - start active or specified script entry
- edit [1-5] - edit existing script with line editing commands
- load [1-5] - bulk entry mode (bypassing CLI parser) for pasting multiple lines
- stop - stop running script at next scriptline
- list [1-5] - list all or specified script
- clear [1-5] - clear active or specified script
Script handling makes it possible for running several commands autonomously. Note: 'script stop' stops script execution, while standalone 'stop' command stops all ongoing operations including scripts
runnumber [1-5] - optional script number to runRun active script or specified script number
waittime - number of milliseconds before next scriptline should be executedWait some time before executing the next scriptline - only useful in a script
statusn/aGet current status
gpio-pulsePin number (required)
Pulse width in ms (required)
Create a pulse of the given milliseconds on the given pin.
Example for 150 ms on pin 4:
gpio-pulse 4 150
gpio-outputPin number (required)
Output level high/low (optional)
Set to output the pin at the given level, default level value is low.
Example to set pin 4 to high:
gpio-output 4 high
gpio-inputPin number (required)
Pull-up option <pull-up=on/off> (optional)
Set pin as input with the given pull-up option, default is pull-up on (10K).
Example to set pin 5 as input with pull-up on:
gpio-input 5 pull-up=on
gpio-setPin number (required)
Output level high/low (required)
Set an output pin at the given level.
Example to set pin 1 to low:
gpio-set 1 low
gpio-getPin number (required)Get the current level of the given pin.
Example to get level of pin 1:
gpio-get 1
versionn/aGet the version of the Radio CLI tool and the radio firmware