esp-idf/examples/ieee802154/ieee802154_cli

Supported Targets	ESP32-C6	ESP32-H2

IEEE802.15.4 Command Line Example

This example demonstrates an IEEE802.15.4 Command Line. The IEEE802.15.4 CLI exposes configuration and management APIs via a command line interface.

How to use example

Hardware Required

To run this example, a board with IEEE 802.15.4 module (for example ESP32-H2) is required.

Configure the project

idf.py menuconfig

The example can run with the default configuration. IEEE802.15.4 Command Line is enabled with UART as the default interface. Additionally, USB JTAG is also supported and can be activated through the menuconfig:

Component config → ESP System Settings → Channel for console output → USB Serial/JTAG Controller

Build, Flash, and Run

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT build flash monitor

Now you'll get an IEEE802.15.4 command line shell.

IEEE802.15.4 Command List

• cca
• channel
• coordinator
• ed
• esp154
• extaddr
• free
• heap
• panid
• pending
• promisc
• reg
• restart
• rx
• shortaddr
• tx
• txpower
• version
• help

IEEE802.15.4 Command Details

Most of the commands are available in both full and abbreviated form. For example, to enable the receive mode, both rx -r 1 and rx --receive=1 are valid

> rx -r 1
I (4227508) i154cmd: RX Start
> rx --receive=1
I (4249898) i154cmd: RX Start

Only abbreviated formats are described below.

cca

cca -g

Get the cca cfg.

> cca -g
I (2676818) i154cmd: threshold:-60 dB, mode: 1

cca -m <mode>

Set the cca mode.

• 0: carrier
• 1: ED
• 2: carrier or ED
• 3: carrier and ED

> cca -m 1
I (5047618) i154cmd: set cca mode as: 1

cca -v <value>

Set the cca threshold.

> cca -v 60
I (4731648) i154cmd: set cca threshold as: 60

channel

channel -g

Get the channel number.

> channel -g
I (67238) i154cmd: current channel: 11

channel -s <n>

Set the channel number.

> channel -s 21
I (220268) i154cmd: set channel: 21

coordinator

coordinator -d

Enable the coordinator.

> coordinator -d
I (438228) i154cmd: hardware coordinator is disabled

coordinator -e

Disable the coordinator.

> coordinator -e
I (453288) i154cmd: hardware coordinator is enabled

coordinator -g

Get the coordinator.

> coordinator -g
I (472398) i154cmd: hardware coordinator was enabled

ed

ed -d <duration>

Configure the duration of energy detection.

> ed -d 2
I (668548) i154cmd: ed start
I (668548) i154cmd: ed_scan_rss_value: -98 dB
I (472398) i154cmd: hardware coordinator was enabled

esp154

esp154 -e

Enable initialize the IEEE 802.15.4 subsystem.

> esp154 -e
I (87127) i154cmd: initialize the IEEE 802.15.4 subsystem

esp154 -d

Disable initialize the IEEE 802.15.4 subsystem.

> esp154 -d
I (97107) i154cmd: deinitialize the IEEE 802.15.4 subsystem

extaddr

extaddr <extaddr>

Set the device extended address.

> extaddr 0xaa 0xbb 0xcc 0xdd 0x00 0x11 0x22 0x33
I (704937) i154cmd: set extaddr: 33221100ddccbbaa

extaddr -g

Get the device extended address.

> extaddr -g
I (615587) i154cmd: get extaddr: 0807060504030201

free

Get the current size of free heap memory.

> free
235024

heap

Get minimum size of free heap memory that was available during program execution.

> heap
min heap size: 231076

panid

panid <panid>

Set the device Pan ID.

> panid 0x1234
I (1112117) i154cmd: set panid: 0x1234

panid -g

Get the device Pan ID.

> panid -g
I (1128457) i154cmd: current panid: 0x1234

pending

pending <addr>

Add the address to pending table (2 bytes for short address, 8 bytes for extended address).

> pending 0x34 0x12
I (1806327) i154cmd: add pending shortaddr: 0x1234

pending -m <mode>

Set the autopending mode.

• 0: disable
• 1: enable
• 2: enhanced

> pending -m 1
I (1828817) i154cmd: set auto pending mode as: 1

pending -g

Get the autopending mode.

> pending -g
I (2007797) i154cmd: get auto pending mode as: 1

pending -r

Reset the pending address table.

> pending -r
I (2113377) i154cmd: clear the pending address table

pending -d

Delete the address from pending table (2 bytes for short address, 8 bytes for extended address).

> pending -d 0x34 -d 0x12
I (2322787) i154cmd: delete pending shortaddr: 0x1234

promisc

promisc [-edg]

• e: Enable the promiscuous mode.
• d: Disable the promiscuous mode.
• g: Get the promiscuous mode.

> promisc -e
I (2599357) i154cmd: promiscuous mode is enabled
> promisc -d
I (2600977) i154cmd: promiscuous mode is disabled
> promisc -g
I (2602927) i154cmd: hardware promiscuous mode was disabled

reg

reg -w <address> -v <value>

Write the register <address> with <value>.

> reg -w 0x0184 -v 0x00
I (103917) i154cmd: write reg 0x184: 0x1234

reg -r <address>

Read the register <address>.

> reg -r 0x0184
I (220967) i154cmd: reg 0x184 value: 0x1234

restart

Restart the program.

rx

rx -r <mode>

Configure the radio receive mode.

• 0: disable
• 1: enable

> rx -r 1
I (121977) i154cmd: RX Start
> rx -r 0
I (127267) i154cmd: radio exit receive mode

shortaddr

shortaddr <shortaddr>

set the device short address.

> shortaddr 0x1234
I (543167) i154cmd: set shortaddr: 0x1234

shortaddr -g

> shortaddr -g
I (568387) i154cmd: current shortaddr: 0x1234

tx

tx <n>

Transmit IEEE 802154 MAC frame.

• -C: Set cca trigging tx mode true.

> tx 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77
I (6399947) i154cmd: tx sfd done, Radio state: 4
I (6399957) i154cmd: Tx Done 8 bytes
I (6399957) i154cmd: 00 11 22 33 44 55 66 77
> tx 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77 -C
I (6580547) i154cmd: tx sfd done, Radio state: 4
I (6580547) i154cmd: Tx Done 8 bytes
I (6580547) i154cmd: 00 11 22 33 44 55 66 77

tx -l <len>

Transmit IEEE 802154 MAC frame wich has a length=<len>.

• -C: Set cca trigging tx mode true.

> tx -l 10
I (6721867) i154cmd: tx sfd done, Radio state: 4
I (6721867) i154cmd: Tx Done 10 bytes
I (6721867) i154cmd: 00 01 02 03 04 05 06 07
I (6721867) i154cmd: 08 09 00 00 00 00 00 00
> tx -l 10 -C
I (6726067) i154cmd: tx sfd done, Radio state: 4
I (6726067) i154cmd: Tx Done 10 bytes
I (6726067) i154cmd: 00 01 02 03 04 05 06 07
I (6726067) i154cmd: 08 09 00 00 00 00 00 00

txpower

txpower -g

Get the txpower.

> txpower -g
I (7100077) i154cmd: current txpower: 20

txpower -s <n>

Set the txpower.

> txpower -s 40
I (7116217) i154cmd: set txpower: 40

version

Get version of chip and SDK.

> version
IDF Version:v5.3-dev-699-gb94f6ef680-dirty
Chip info:
	      model:ESP32-H2
	      cores:1
	      feature:/BLE/External-Flash:2 MB
	      revision number:1

help

Get the summary of all registered commands.

> help
cca  [-g] [-v <threshold>] [-m <mode>]
  cca config
  -v, --value=<threshold>  cca threshold setting
  -m, --mode=<mode>  cca mode, 0: carrier; 1: ED; 2: carrier or ED; 3: carrier and ED
     -g, --get  get the cca cfg

channel  [-g] [-s <n>]
  get/set the channel number
     -g, --get  get channel number
  -s, --set=<n>  set channel number

coordinator  [-edg]
  enable/disable/get the coordinator
  -e, --enable  enable the coordinator
  -d, --disable  disable the coordinator
     -g, --get  get the coordinator

ed  [-d <duration>]
  configure the duration
  -d, --duration=<duration>  configure the duration of energy detection

esp154  [-ed]
  enable/disable initialize the IEEE 802.15.4 subsystem
  -e, --enable  initialize the IEEE 802.15.4 subsystem
  -d, --disable  deinitialize the IEEE 802.15.4 subsystem

extaddr  [-g] [<extaddr>]...
  set/get the device extended address
     -g, --get  get the device extended address
     <extaddr>  set the device extended address

free 
  Get the current size of free heap memory

heap 
  Get minimum size of free heap memory that was available during program
  execution

help  [<string>]
  Print the summary of all registered commands if no arguments are given,
  otherwise print summary of given command.
      <string>  Name of command

log_level  <tag|*> <none|error|warn|debug|verbose>
  Set log level for all tags or a specific tag.
       <tag|*>  Log tag to set the level for, or * to set for all tags
  <none|error|warn|debug|verbose>  Log level to set. Abbreviated words are accepted.

panid  [-g] [<panid>]
  get/set the device Pan ID
       <panid>  set the device Pan ID
     -g, --get  get the device Pan ID

pending  [-gr] [-m <mode>] [<addr>]... [-d <addr>]...
  configure the pending address table
  -m, --mode=<mode>  set the autopending mode (0: disable; 1: enable; 2: enhanced)
     -g, --get  get the autopending mode (0: disable; 1: enable; 2: enhanced)
   -r, --reset  reset the pending address table
        <addr>  add the address to pending table (2 bytes for short address, 8 bytes for extended address)
  -d, --delete=<addr>  delete the address from pending table (2 bytes for short address, 8 bytes for extended address)

promisc  [-edg]
  enable/disable/get the promiscuous mode
  -e, --enable  enable the promiscuous mode
  -d, --disable  disable the promiscuous mode
     -g, --get  get the promiscuous mode

reg  [-r <address>] [-w <address>] [-v <value>]
  read/write the register
  -r, --read=<address>  read the register value
  -w, --write=<address>  register address to be written
  -v, --value=<value>  register value to be written

restart 
  Software reset of the chip

rx  [-r <mode>]
  enable/disable the receive mode
  -r, --receive=<mode>  configure the radio receive mode, 0: disable; 1: enable

shortaddr  [-g] [<shortaddr>]
  get/set the device short address
   <shortaddr>  set the device short address
     -g, --get  get the device short address

tx  [-C] [-l <len>] [<n>]... [-o <offset>]
  transmit IEEE 802154 MAC frame
  -l, --length=<len>  frame length
  -C, --cca_enable  set cca trigging tx mode true
           <n>  transmit raw frame
  -o, --offset=<offset>  tx buffer offset

txpower  [-g] [-s <n>]
  get/set the txpower
     -g, --get  get txpower
  -s, --set=<n>  set txpower,value range -80dBm~-10dBm

version 
  Get version of chip and SDK

help <command>

Get the summary of given command.

> help tx
tx  [-C] [-l <len>] [<n>]... [-o <offset>]
  transmit IEEE 802154 MAC frame
  -l, --length=<len>  frame length
  -C, --cca_enable  set cca trigging tx mode true
           <n>  transmit raw frame
  -o, --offset=<offset>  tx buffer offset