Shell interface
The application provides a Unix-like shell through the serial interface. Main features are described in the Zephyr documentation reference : Bluetooth Mesh Shell.
Note
This documentation refers to LinkIO firmwares based on Zephyr v3.3.0, including the embedded shell in Controller firmwares greater than v2.2.1.0
Hardware Interface
data rate 115200 bits/s
8-N-1 byte format.
no flow control
Terminal interface
If the module is connected to a Linux host interface, you can simply interact with a (shell) terminal.
sudo apt-get install gtkterm
gtkterm -p /dev/ttyACM0 -s 115200
By default echo is disabled, to enable it type :
==> shell echo on
<== uart:~$ # Indicates that you can send commands
Helps to begin :
# You can send command when prompt is show
<== uart:~$
In the rest of the documentation these 2 keywords will not be specified again.
Useful commands :
==> <tab> # Show all available commands
<== clear device devmem flash
<== help history kernel log
<== mcuboot mesh nrf_clock_control resize
<== shell stats vnd
==> help
<== Please press the <Tab> button to see all available commands.
<== You can also use the <Tab> button to prompt or auto-complete all commands or its subcommands.
<== You can try to call commands with <-h> or <--help> parameter for more information.
<==
<== Shell supports following meta-keys:
<== Ctrl + (a key from: abcdefklnpuw)
<== Alt + (a key from: bf)
<== Please refer to shell documentation for more details.
<==
<== Available commands:
<== clear :Clear screen.
<== device :Device commands
<== devmem :Read/write physical memory
<== Usage:
<== Read memory at address with optional width:
<== devmem address [width]
<== Write memory at address with mandatory width and value:
<== devmem address <width> <value>
<== flash :Flash shell commands
<== help :Prints the help message.
<== history :Command history.
<== kernel :Kernel commands
<== log :Commands for controlling logger
<== mcuboot :MCUboot commands
<== mesh :Bluetooth mesh shell commands
<== nrf_clock_control :Clock control commands
<== resize :Console gets terminal screen size or assumes default in
<== case the readout fails. It must be executed after each
<== terminal width change to ensure correct text display.
<== shell :Useful, not Unix-like shell commands.
<== stats :Stats commands
<== vnd :vnd
Built-in commands
Mesh commands
The Bluetooth Mesh Shell subsystem provides a set of Bluetooth Mesh commands for the Shell module. It allows for testing and exploring the Bluetooth Mesh API through an interactive interface, without having to write an application.
The Bluetooth Mesh Shell interface provides access to most Bluetooth Mesh features, including provisioning, configuration, and message sending.
# In most bt-mesh cmd, get exit code and know when shell is finished
<== cmd_end (err %d)
In the rest of the documentation this keywords will not be specified again.
LinkIO add-ons
LinkIO adds its own specific commands to enhance the current set and answer project needs, described below.
vnd info all
The following command displays firmware version information (and more):
.. code-block:: bash
==> vnd info all <== build time: Mar 6 2024 12:49:04 <== MODULE_MANUFACTURER_NAME=EUROHM <== MODULE_MANUFACTURER_ID=10 <== MODULE_MODEL_NAME=CONTROLLER <== MODULE_MODEL_ID=0 <== MODULE_PLATFORM=NRF52840 <== BOARD=nrf52840dk_nrf52840 <== PROJECT_NAME=Zephyr-Kernel <== MODULE_SW_VERSION_MAJOR=2 <== MODULE_SW_VERSION_MINOR=2 <== MODULE_SW_VERSION_REVISION=1 <== MODULE_SW_VERSION_BUILD=0 <== MODULE_VERSION_STR=2.2.1.0 <== OUTPUT_FILENAME=NRF52840_EUROHM_CONTROLLER_v2.2.1.0 <== ADDRESS_MAC=D6:03:1D:47:0C:CB (random) <== ame=CONTROLLER_0CCB
vnd isprov
Return if the product is provisionned or not
==> vnd isprov
<== prov=false
vnd reset
Reset the product
==> vnd reset
model mesh message parameters
For commands :
elem id: the element index of the model instance (source)
model id: the model id sender (source)
company id: the Company ID of the vendor model
addr: the destination address
opcode: the opcode message to send
opcode_rsp: the opcode waited for response
payload: Hexadecimal BCD value
msg_id: ID of message, if not given, it’s 0
- For answers :
src addr: the element address of the model instance (source)dest addr: the element address of the model instance (destination)rssi: Received Signal Strength Indicatorelem id: the element index of the model instance (source)mid cid: the client model id + compagny id(for vendor) which received messageopcode cid: the opcode + compagny id(for vendor) which received messagestatus: Linkio statuslength: payload length
models msg send
Send a command from a generic model client to destination
==> mesh models msg send <elem id> <model id> <addr> <opcode> [payload] [msg_id]
models msg send-vnd
Send a command from a vendor model client to destination
==> mesh models msg send-vnd <elem id> <model id> <company id> <addr> <opcode> [payload] [msg_id]
models msg send-rsp
Send a command from a generic model client with an expected response from destination
==> mesh models msg send-rsp <elem id> <model id> <addr> <opcode> <opcode_rsp> [payload] [msg_id]
models msg send-vnd-rsp
Send a command from a vendor model client with expected response from destination
==> mesh models msg send-vnd-rsp <elem id> <model id> <company id> <addr> <opcode> <opcode_rsp> [payload] [msg_id]
models msg publish
Publish a status message on a generic model client.
==> mesh models msg publish <elem id> <model id> <opcode> [payload] [msg_id]
models msg publish-vnd
Publish a status message on a vendor model client.
==> mesh models msg publish-vnd <elem id> <model id> <company id> <opcode> [payload] [msg_id]
Spontaneous message received
These messages can be sent at any time
# product ready for command after (re)boot
<== Application is ready
<== Node provisioned
<== Provisioning link opened on PB-GATT
<== Provisioning link closed on PB-ADV
# For all client model status are return with same format ...
<== Mesh status from <src addr> dst <dst addr> rssi <rssi> element <elem id>, model <model id cid> op <opcode cid> len <length>: <payload>
<== Mesh ack status from <src addr> dst <dst addr> rssi <rssi> element <elem id>, model <model id cid> op <opcode cid> msg_id <msg_id> status <status> len <length>: <payload>
<== Mesh timeout from <src addr> op_expected <op_expected> msg_id <msg_id> len <length>: <payload>
# ... but for Health it a bit different
<== Health from <src addr> opcode <opcode> test_id <test_id> cid <cid> cnt <cnt>: <payload>
<== Health timeout from <src addr> since <since> opcode <opcode> test_id <test_id> cid <cid> cnt <cnt>: <payload>
# Product can receive some command BLE Mesh on its freature property server
<== Featprop from <src addr> dst <dst addr> rssi <rssi> element <elem id>, model <model id cid> op <opcode cid> len <length>: <payload>
Commands workflow sample
Mesh shell init
==> mesh init
Initial configuration
#if need clear previous config
==> mesh reset-local
==> mesh cdb clear
==> kernel reboot cold
==> mesh init
#create new db
==> mesh cdb create
#Create Appkey
==> mesh cdb app-key-add 0 0
#Show config database
==> mesh cdb show
Local provisioning
#Local provision
==> mesh prov local 0 1
#Show config database
==> mesh cdb show
Local commissioning
#Select local
==> mesh dst 0x1
#Get composition
==> mesh models cfg get-comp
#Add app keys
==> mesh cdb app-key-add 0 0
#Subscribe to status msg in group 0xC000
#mesh models cfg model sub-add :<elem addr> <sub addr> <Model ID> [Company ID]
==> mesh mesh models cfg model sub-add 0x1 0xC000 0x1001
#check
==> mesh mod-sub-get 0x1 0x1001
#Bind model with appkey
==> mesh mesh models cfg model app-bind 0x1 0 0x1001
Node provisioning
#Start scan
==> mesh prov beacon-listen on
#Get scanned UUID
#Stop Scan
==> mesh prov beacon-listen off
#Set static oob if need
#static-oob :[val: 1-16 hex values]
#mesh static-oob a12d
#Start provision
#provision-adv :<UUID> <NetKeyIndex> <addr> <AttentionDuration>
==> mesh prov remote-adv 78f86a8c8f91493eae99eef34ac9be13 0 0x2 5
#Check node is added to cdb
==> mesh cdb show
Node commissioning
#Select Node 0x2
==> mesh dst 0x2
#Get composition
==> mesh models cfg get-comp
#Add keys
==> mesh cdb app-key-add 0 0
#Add subscription to group
==> mesh mesh models cfg model sub-add 0x3 0xC010 0x1000
#Bind a AppKey for each element addr to BT_MESH_MODEL_ID_GEN_ONOFF_SRV=0x1000
==> mesh mesh models cfg model app-bind 0x3 0 0x1000
#Pub status in 0xC000
==> mesh models cfg model pub 0x3 0x1000 0xC000 0 off 0x00 0 0 0
Commands examples
See various control commands :
Backup cdb
Store information given by :
==> mesh cdb show
Restore cdb
Use this cmd :
==> cdb-node-add :<UUID> <addr> <num-elem> <NetKeyIdx> [DevKey]
==> cdb-subnet-add :<NeyKeyIdx> [<NetKey>]
==> cdb-app-key-add :<NetKeyIdx> <AppKeyIdx> [<AppKey>]
Reset gateway and re-import existing nodes
# Clear
==> mesh reset-local
==> mesh cdb clear
==> kernel reboot cold
# Start Init
==> mesh init
#Create db with existing netkey and appkey
==> mesh cdb create a832eae389e86c73753b340b40d1eb9c
==> mesh cdb app-key-add 0 0 0123456789abcdef0123456789abcdef
# Import already provisionned node from old db
# Mesh Network Information␍␊
# ========================␍␊
# Address Elements Flags UUID DevKey␍␊
# 0x0007 2 - 78f86a8c8f91493eae99eef34ac9be13 adeb672f597aa7e4d96f0c5d4461f888␍␊
# 0x0003 4 - 2e814e9c76f300000000000000000000 782c113ca9c35131c491ecfcc8c8f9c3␍␊
#cdb node-add :<UUID> <addr> <num-elem> <NetKeyIdx> [DevKey]
==> mesh cdb node-add 78f86a8c8f91493eae99eef34ac9be13 0x0007 2 0 adeb672f597aa7e4d96f0c5d4461f888
==> mesh cdb node-add 2e814e9c76f300000000000000000000 0x0003 4 0 782c113ca9c35131c491ecfcc8c8f9c3