Embedded firmware command reference#
This chapter provides details about CLI commands supported by the firmware.
Firmware shell commands#
The firmware can be controlled with a shell accessible using the serial terminal. This chapter describes the command-line interface to secure proximity devices along with common command syntax and response format.
Note: The shell does not show any prompt.
Parent topic:Embedded firmware command reference
Command syntax#
The command line interface (CLI) is text-based, that is, only printable characters are used. The user can interact with the board using some commands such as a regular command prompt. This process requires a serial terminal application such as Tera Term/Putty. Line processes commands, that is, all information needed to process a command is contained in one line. Lines are terminated with the “line-feed” character. A command consists of one or more space separated words where each word, except the first, can be a command, submenu, or value (of any type; integer/hex/character/string). The first word cannot be a value. All commands are constructed with menus, which consist of commands and/or submenus. Commands can have zero or more value arguments.
Implicit commands#
The command-line processor has two implicit commands:
“help” or if no <name> is specified – this command shows all available commands/sub-menus in the selected menu.
“show” – this command shows the current values of all readable items in the selected menu.
Parent topic:Command syntax
Command response#
The device does not echo back the commands given to it. However, the device can respond to each command received immediately and with a single line, except the “range”, “help”, and “show” commands. The “range” commands also have a delayed response.
The response for single-line commands is “<last-subcommand>: <value>”. All responses are terminated with one “line-feed” character.
Parent topic:Command syntax
Boot message#
When the device boots, it displays the following information:
Software version number of the application
Git hash and build date
The reset reason of the device, for example, PIN, SW, WATCHOG
Parent topic:Command syntax
Parent topic:Embedded firmware command reference
Main menu#
By sending the “help” command, a help menu gets listed (see below). Commands are provided to initiate a ranging measurement, display, and modify parameters.
-----------commands-------------
range [<ble-address>] | Run HADM procedure measurement with given peer
test [<tx,rx>] | Run HADM test mode measurement
setup [<ble-address>] | Run HADM setup (from Central only)
communication [options] | Communication commands
parameter [options] | Parameter commands
system [options] | System commands
misc [options] | Miscellaneous commands
-------------end----------------
The options displayed are explained in the table below:
Table: Wireless ranging top level commands
Command |
Description |
|---|---|
range |
Execute a CS measurement using the Bluetooth Low Energy connection (implicitly set service role of the board as “client”). Limitation: should be issued from the same board after first invocation |
test |
Execute a CS measurement using CS test either as initiator (TX) or reflector (RX) |
parameter |
Submenu to set/display CS parameters |
communication |
Set Bluetooth Low Energy role (central/peripheral) |
system |
Submenu to set/display system-related parameters |
misc |
Submenu to set/display miscellaneous parameters |
“parameter” - CS parameters#
The CS parameters menu lists and allows modification of CS configuration. The options displayed here are explained in the table below.
-----------commands-------------
ch_list | Channel list commands (test mode only)
ch_map [<bitmask> [<repeat>]] | Set/show channel map as 10 hexa octets (79 bits used)
cs_algo [<0|1> [<0|1>] [<2...8>]] | Set/show channel selection algo type (0=3b, 1=3c), and for #3c: shape (0=hat, 1=X) and jump
main_mode_nb [<1...160> <1...160> <0...3>] | Set/show numbers of HADM main mode steps (min, max, repetition)
mode0_nb [<1...3>] | Set/show number of HADM mode0 steps
mode_type [<1...3> [<1...3>]] | Set/show main mode and sub-mode types
role [<initiator,reflector>] | Set/show HADM role
rtt_phy [<0|1>] | Set/show RTT phy rate (0=1Mbps, 1=2Mbps)
tx_pwr [<-12...MAX>] | Set/show TX power in dBm of CS measurement. Range is -12dBm to max chip capability
debug [<0-255>] | Set/show debug options (REPORT_DBG_INFO<2>, IQ_AVERAGE_DISABLE<1>, IQ_DETAILS<0>)
ant_cfg [<0|7> [<0...23|255>]] | Set/show antenna config index and (test mode only) permutation index
ant_type [<0-5> ] | Set/show antenna board type: 0:none, 1:X-FR-ANTDIV SMA, 2:X-FR-ANTDIV printed, 3:LOC SMA, 4:LOC printed, 5:LOC printed SMA1 dummy
pn_seq [<AA initiator> [<AA reflector>]] | Set/show PN sequences (must be a hex number, test mode only)
tone_ext [<0...4>] | Set/show TP tone extension (test mode only)
timings | Timings commands
-------------end----------------
Table: Wireless ranging CS parameters commands
Command |
Default |
Description |
|---|---|---|
ch_list |
- |
Used to define the CS channel list in test mode |
ch_map |
All ones |
Used to define the CS channel map in connected mode |
cs_algo |
0 |
Used to define channel selection algorithm type (0=3b, 1=3c), and for #3c: shape (0=hat, 1=X) and jump |
main_mode_nb |
4, 4, 0 |
Numbers of CS main mode steps (min, max, repetition) |
mode0_nb |
2 |
Set/show numbers of CS mode 0 steps |
mode_type |
2,1 |
Set/show main mode and submode types as defined by CS |
role |
Initiator |
Set/show CS role |
rtt_phy |
0 |
Set/show RTT PHY rate (0=1 Mbit/s, 1=2 Mbit/s) |
tx_pwr |
0 |
TX power in dBm used during the CS measurement; |
pn_seq |
- |
Set/show the PN sequences to be used in test mode |
tone_ext |
- |
Set/show the tone extension behavior in test mode |
timings |
- |
Timings submenu (see below); Only for test mode |
debug |
0 |
For internal debug purpose |
ant_cfg |
0, 0 |
Antenna configuration index as defined in CS specs |
ant_type |
0 |
Antenna diversity board to be used |
“ch_list” parameter#
The “ch_list” command parameter defines the CS channel list. It only applies in test mode. See for example, the code below:
set [<0...78>,..,<0...78> [<repeat>]] | Set/show channel list
generate <0...78> <0...78> [rand] | Generate channel list from first and last CS channels
Two modes can be used:
The “set” mode to input a CS channel list that is input to the firmware.
parameter ch_list set 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
This mode defines a CS sequence of 17 steps on CS channels in the given order.
The “generate” mode makes the firmware generate the channel list based on a start and stop frequency.
parameter ch_list generate 0 78
This mode defines a CS sequence of 79 steps on CS channels 0 to 78 (linear sweep). This is the default behavior of the firmware.
There is also a possibility to randomize the generated frequency list.
parameter ch_list generate 0 78 rand
It defines a CS sequence of 79 steps on CS channels 0 to 78 in a pseudo-randomized order.
Parent topic:”parameter” - CS parameters
“timings” – CS timings configuration#
-----------commands-------------
intervals <150|80|50> <145|80|40> [<145|80|40> ] | Set/show HADM interval timings T_FCS, T_IP1, T_IP2 (us)
t_pm <20|40> | Set/show HADM T_PM timing (us)
t_sw <2|4|10> | Set/show HADM T_SW timing (us)
-------------end----------------
Table: Wireless ranging CS timings commands
Command |
Default |
Description |
|---|---|---|
intervals |
150, 145, 145 (test mode) |
Set T_FCS, T_IP1 and T_IP2 interval in µs, as defined by CS. Allowed values are: 150 µs, 80 µs, and 50 µs for T_FCS and 145 µs, 80 µs, and 40 µs for T_IP1 and T_IP2. |
t_pm |
20 |
Set T_PM, duration in µs, as defined by CS Allowed values are: 20 µs and 40 µs |
t_sw |
0 |
When antenna diversity is used, this command controls the antenna switch time which can be set to 2 µs, 4 µs, or 10 µs. Otherwise 0 is used. |
Note: The ‘Timings’ input is relevant for test mode only. In connected mode, the BLE controller chooses timings based on CS capability exchanged between the two devices. NXP controller implementation chooses the fastest timings supported by the two devices.
Parent topic:”parameter” - CS parameters
Parent topic:Main menu
“system” – system commands#
-----------commands-------------
build_info | Show SW build information
debug [0|1] | Enable debug features (DTEST...)
verbosity [<0...255>] | Set/show verbosity flags (1=Info, 2=Debug, 4=MeasurementInfo, 8=MeasurementData, 16=MeasurementDebug, 32=BoardInfo, 64=Profiling)
unique_id | Show Unique Id
version | Show SW version number
reset | Reset MCU
store | Store all parameters
factory | Reload and store factory defaults
events | Show events
timing | Show BLE timing
baudrate <value> | Set/show baudrate of serial interface (default: 115200, volatile)
output_format | Show output format
calibrate [<MCIQ dist> <ToF dist> [store]] | Set/Show zero-distance calibration, distances are in meters, Q10
-------------end----------------
Table. Wireless ranging system commands
Command |
Default |
Comment |
|---|---|---|
verbosity |
13 |
Level of details of the range response in the form of bits field. Add verbosity flag values to combine them (for instance 12 for Measurement Info and Measurement Data). |
unique_id |
NA |
6 bytes unique identifier. Reserved for future use; all zeros for now |
version |
NA |
Application version. For example: v2.0.0 |
build_info |
NA |
Build version information (Git hash, and so on) |
reset |
NA |
Reset the CPU |
store |
NA |
Save settings to flash |
factory |
NA |
Revert to default settings |
events |
NA |
Reserved for future use |
timing |
NA |
Reserved for future use |
baudrate |
115200 |
Change the baud rate of the UART interface. This setting is volatile, that is, it is restored to the default value after a power cycle or reset. |
output_format |
4 |
Internal usage |
Parent topic:Main menu
“misc” – miscellaneous commands#
-----------commands-------------
xtal_trim [<0...63>] | Set/show XTAL trim value
cw_trim [0|1] | Start/Stop 2440MHz constant wave Tx (used for XTAL trimming)
rtp_algo [<0...7>] | Set/show RTP embedded algorithm bitmap to be run (bit0:CDE, bit2:RADE)
rtp_algo_config [<1(CDE)> [<param1> <param2>]] | Set/show RTP embedded algorithm configuration
Table: Wireless ranging miscellaneous commands
Command |
Default |
Comment |
|---|---|---|
xtal_trim |
0 |
Set/show 32 MHz crystal oscillator trimming value. Combined with cw_trim command, it allows you to adjust Xtal precisely. |
cw_trim |
- |
Turn on/off a 2440 MHz constant wave transmission to tune the Xtal (using xtal_trim) |
rtp_algo |
1 |
Set RTP embedded algorithm to be run in bitmap format: 0: No embedded algorithm is run |
rtp_algo_config |
- |
This command can be used to customize some parameters of CDE algorithm. It is for internal usage only. |
Parent topic:Main menu
Firmware response interpretation#
Each CS measurement produces results represented as a JSON-like structure terminated with “[DONE]”.
The “system verbosity” command controls the verbosity of the output.
An example response of a “range” command with default (minimal) verbosity, showing mainly the distance computation results (‘cde’ and ‘ad’ fields in meters), without any additional data is shown below:
items:[{mciq:{cfg:{n_ap:4,n_stp:79},result:{vf:79,cde:0.64,cqi:0.842},},tof:{cfg:{n_stp:13},result:{ad:0.3,sr:100},},},]
CRC32:1cebcbcb
marker:[DONE]
An example response of a “range” command is shown below:
items:[{hadm:{cfg:{rtyp:0,rphy:0,txpwr:0,fcs:150,ip1:145,ip2:145,tpm:20,ant:0},
sts:0,stp:{nb:101,md:'0002222122221222212222122221222212222122221222212222122221222212
2221222212222122221222212222122221222',
ch:'0001020001020303040506070708090A0B0B0C0D0E0F0F1011121313141516171718191A1B1B1C1D1E1
F1F2021222323242526272728292A2B2B2C2D2E2F2F3031323333343536373738393A3B3B3C3D3E3F3F40414243
43444546474748494A4B4B4C4D4E'}},
md0:{cfg:{n_stp:3},init:{r:'626262',c:'fjHQfkSQfh4g'},refl:{r:'808080',c:'gAAAgAAAgAAA'}},
mciq:{cfg:{n_ap:1,n_stp:79},init:{i:['n6i4YIY6oGncnylGm6agmQiSYKiYagmacGYedckSh+Y8nAmKmKdkhwaMae
meZelimKleaAaEbYkmacaihOkKa0lSk+lEjYiGcejgd0fqkEg8kmbWgodSiAfAcGcSjkj+dsdKjibkgMb8jcjOigdojadShkhof4',],
q:['iYYUiakMeujYdumSkCaKbGnqfcYolgbwmme6nGmGnGeceijac2Zkmqcej6ecfOjYeedEfOfkjocihYhalecehcgMeah
Ij4kqjkjkbmk4dcbWe8gYkicYkCbuiAiQdoeacYc0imgMbeiQc8jUj8cEjIcSbubwki',],},},tof:{cfg:{n_stp:19},init:
{d:'AyUOAyUVAyUbAyUdAyUkAyUlAyUsAyUwAyU2AyU+AyVBAyVGAyVKAyVOAyVQAyVWAyVcAyVnAyVn',r:'62626161616160605F5F5E5E5D5D5C5C5C5D5D'},},
info:{init:{syn:0,syg:0,syr:0,syc:0,f:0x0000,x:0,ta:0,te:0,},
refl:{syn:0,syg:0,syr:0,syc:0,f:0x0000,x:0,ta:0,te:0,},},},]
marker:[DONE]
These responses have an albeit slightly modified YAML syntax. The modifications are: “: “ is replaced with “:” and indentation/end-of-lines are removed by using the YAML data stream syntax. This reduces the output size to a minimum.
Online YAML beautifier tools can be used (after adding a space after double-colons) to convert them into a more readable format.
The above example is shown below:
At the top level, we have the items, profiling, and marker elements. The marker element is there to signal the end of the message.
The profiling element contains timing related information about the CS procedure.
The items element is a list of range-result blocks. The parameters in range-result block are shown in the table below.
Table. Wireless ranging response structure
Hierarchy |
Parameter |
Unit |
Description |
|---|---|---|---|
Init/refl |
u |
- |
Unique ID of board (required) |
Init/refl |
v |
- |
SW Version (required) |
CS configuration |
|||
hadm |
sts |
- |
CS event status (0 = OK) |
hadm.cfg |
rtyp |
- |
CS rtt_type configured |
hadm.cfg |
rphy |
- |
CS rtt_phy configured |
hadm.cfg |
fcs |
µs |
CS T_FCS configured |
hadm.cfg |
ip1/ip2 |
µs |
CS T_IP1/T_IP2 configured |
hadm.cfg |
tpm |
µs |
CS T_PM configured |
CS steps configuration |
|||
hadm.stp |
nb |
# |
Number of steps of CS event |
hadm.stp |
md |
# |
Step mode array of the CS event (0-3) |
hadm.stp |
ch |
# |
Channel number mode array of the CS event (0-79) |
CS mode 0 config and results |
|||
hadm.stp |
evt |
# |
CS subevent event index (2 hex digits per CS subevent) |
hadm.stp |
se |
# |
Last CS step index of each CS subevent (2 hex digits per CS subevent) |
hadm.md0.cfg |
n_stp |
# |
Number of mode 0 steps |
hadm.md0.init/refl |
r |
dBm |
Mode 0 RSSI array of n_stp steps |
hadm.md0.init/refl |
c |
Hz |
Mode 0 CFO array of n_stp steps |
MCIQ (RTP) results |
|||
mciq.cfg |
n_ap |
# |
Number of antenna paths for RTP (<=4) |
mciq.cfg |
n_stp |
# |
Number of steps containing PCTs (step modes 2 and 3) |
mciq.init/refl |
i |
- |
List of base64 encoded 12 bit PCT I values, that is, for each tone there are 2 characters, each representing 6-bits of data (required, length=n_stp); Repeated per antenna path |
mciq.init/refl |
q |
- |
List of base64 encoded 12-bit PCT Q values, that is, for each tone there are 2 characters, each representing 6-bits of data (required, length=n_stp); Repeated per antenna path |
mciq.init/refl |
tqi |
- |
List of TQI values for each tone; Repeated per antenna path |
mciq.result |
cde, cqi |
m, # |
CDE distance estimation and quality indicator computed by embedded algorithm |
mciq.result |
vf |
# |
Number of valid frequencies retained by distance estimation algorithms |
mciq.result |
rade, rade_dqi |
m, # |
RADE distance estimation and quality indicator computed by embedded algorithm |
ToF (RTT) results |
|||
tof.cfg |
n_stp |
# |
Number of steps containing RTT packets (step modes 1 and 3) |
tof.init/refl |
d |
ns |
List of base64 encoded 18 bits + 4 error bits ToA-ToD or ToD-ToA values, resulting in 4 characters each (required, length=n_stp) |
tof.init/refl |
r |
dBm |
Mode 1 or 3 packet RSSI array (required, length=n_stp) |
tof.result |
ad, sr |
m, % |
Average distance estimation and success rate as computed by embedded algorithm |
tof.init/refl |
| nadm |
| - | |
Estimated chance of an attack on the received packet based on the normalized attack detector metric (NADM) |
CS measurement info |
|||
info.init/refl |
syn |
# |
Mode 0 index in sequence that was used to synchronize gain and frequency |
info.init/refl |
syg |
# |
AGC index used during whole CS event (<= 11) |
info.init/refl |
syr |
dBm |
RSSI of mode 0 used for gain lock |
info.init/refl |
syc |
Hz |
CFO of mode 0 used for CFO compensation |
info.init/refl |
f |
- |
Error/warning flag (see description below) |
info.init/refl |
te |
- |
Reserved for future use |
The table below shows the “info” error flags bit field description.
Table: Info error flags interpretation
Bit Mask |
Comment |
|---|---|
0x0001 |
PLL lock error |
0x0002 |
CS sequence was aborted |
0x0004 |
Error during AGC lock |
0x0008 |
Error during IQ capture |
0x0010 |
RSSI measured became too low |
0x0020 |
Error happened during Mode 0 synchronization phase |
0x0040 |
Timestamp reading on one or more RTT packets failed |
0x0080 |
SW scheduler detected a desynchronization with RSM HW scheduler |
0x0100 |
XCVR API reported an error |
Use the script record_range_measurement.py to decode this data and obtain numerical values. We do not provide the encoding method of the compressed fields here.
Table: CSV fields description
Field |
Description |
|---|---|
meta.error_msg |
Application error message. |
meta.testcase.meas_nr |
Ranging measurement number. |
mciq.cfg.n_ap |
Number of antenna paths used during CS mode 2 or mode 3 steps. Typically 1 for the single antenna mode, 4 for 2x2 antenna mode. |
mciq.cfg.n_stp |
Number of CS RTP steps (mode2 or mode3) included in the CS procedure. |
mciq.result.CDE_distance |
CDE distance estimate in meters. |
mciq.result.CDE_dqi |
CDE distance quality indicator between 0 and 1. |
mciq.result.RADE |
RADE distance estimate in meters. |
mciq.result.RADE_dqi |
RADE distance quality indicator between 0 and 1. |
mciq.result.RADE_error |
RADE error status. |
mciq.result.distance |
Distance estimate in meters. |
mciq.result.slope_rmse |
IQ samples quality metric in degree. 2-way phase slope root mean square error. |
tof.cfg.n_stp |
Number of CS RTT steps (mode1 or mode3) included in the CS procedure. |
tof.result.distance |
RTT distance estimate in meters. |
tof.result.successrate |
How many CS RTT packets were sucessfully exchanged during the CS procedure, in %. |
tof.result.init_nadm |
Initiator Normalized Attack Detector Metric. |
tof.result.refl_nadm |
Reflector Normalized Attack Detector Metric. |
tof.result.std |
Standard deviation of the distance computed over all CS mode 1 steps. |
md0.cfg.n_stp |
Number of CS mode 0 steps (Synchronization) included in the CS procedure. |
hadm.cfg.rtyp |
Channel sounding RTT Type. |
hadm.cfg.rphy |
Channel sounding RTT PHY (0 = 1Mbps, 1 = 2Mbps). |
hadm.cfg.txpwr |
TX power used during the CS procedure, in dBm. |
hadm.cfg.fcs |
Channel sounding T_FCS, in µs. Frequency change period. |
hadm.cfg.ip1 |
Channel sounding T_IP1, in µs. Defined for the CS mode 0 and CS mode 1 : idle time between the transmission from the initiator and the transmission from the reflector. |
hadm.cfg.ip2 |
Channel sounding T_IP2, in µs. Defined for the CS mode 2 : idle time between the transmission from the initiator and the transmission from the reflector. |
hadm.cfg.tpm |
Channel sounding T_PM, in µs. Phase measurement period (CS mode 2). |
hadm.sts |
Channel sounding measurement status. |
hadm.stp.nb |
Channel sounding number of executed steps. |
hadm.stp.modes |
The list of Channel Sounding modes used for each step. |
hadm.stp.channels |
The list of Channel Sounding channel numbers used for each step. |
hadm.stp.event |
Index of last event number. |
hadm.stp.subevt |
Index of last subevent number. |
hadm.stp.m0_idx |
The list of indexes for the steps that use mode 0 procedures. |
hadm.stp.tof_idx |
The list of indexes for the steps that use ToF procedures. |
hadm.stp.mciq_idx |
The list of indexes for the steps that use phase based procedures. |
info.init.sync_step_id |
Initiator side. Which step index has been used during the synchronization (CS mode 0) to capture the receiver gain index, the RSSI and the CFO. |
info.init.sync_agc |
Initiator receiver gain index selected for the CS procedure. |
info.init.sync_rssi |
Initiator RSSI in dBm. |
info.init.sync_cfo |
Initiator measured Carrier Frequency Offset before compensation, in Hz. |
info.init.flags |
Initiator error flags (refer to SDK documentation ‘CS wireless ranging demo application.pdf’) |
info.init.temperature |
Temperature of initiator device during measurement. |
info.refl.sync_step_id |
Reflector side. Which step index has been used during the synchronization (CS mode 0) to capture the receiver gain index, the RSSI and the CFO. |
info.refl.sync_agc |
Reflector receiver gain index selected for the CS procedure. |
info.refl.sync_rssi |
Reflector RSSI in dBm. |
info.refl.sync_cfo |
Reflector measured Carrier Frequency Offset before compensation, in Hz. |
info.refl.flags |
Reflector error flags (refer to SDK documentation ‘CS wireless ranging demo application.pdf’) |
info.refl.temperature |
Temperature of reflector device during measurement. |
Parent topic:Main menu
Parent topic:Embedded firmware command reference