Nordic UART Service (NUS) shell transport
The Bluetooth® LE GATT Nordic UART Service shell transport allows you to receive shell commands remotely over Bluetooth. It uses the Nordic UART Service (NUS).
The NUS Service shell transport is used in the Bluetooth: NUS shell transport sample.
Setup
Enable NUS shell transport in your application to be able to receive shell commands remotely.
Sending shell commands
The nRF Connect SDK provides two alternatives for sending shell commands from a host, like a PC, to the application that uses this module:
bt_nus_shell.py. It is a Python script that requires a console application, like PuTTY, and a second development kit.
Bluetooth LE Console. It is a stand-alone application for Linux.
bt_nus_shell.py
The script file scripts/shell/bt_nus_shell.py
contains a cross-platform example host application, written in Python 3.
The script uses an additional Nordic development kit, like the PCA10040, as a Bluetooth central device.
It connects to the specified device and forwards all NUS traffic to the network port.
You can then use a console application, like PuTTY, to connect to that port and use the shell.
The default port is set to 8889
.
To install the script dependencies, open your preferred command-line interface, and enter the following command in the nRF Connect SDK root directory:
pip install --user -r scripts/shell/requirements.txt
The script requires the following parameters:
com
- the COM port of the development kit used by the script
Additionally, following parameters are option:
snr
- the SEGGER board IDfamily
- the chip family of the development kit, for example, nRF52name
- the advertising name of the device with the NUS shellport
- the local network port
Note
The script does not support reconnections. Therefore, you must restart both the script and the console application after each reconnection.
Perform the following steps to use the bt_nus_shell.py
script:
Connect a Nordic Development Kit, like the PCA10040, to your PC.
Start the
bt_nus_shell.py
script with the correct parameters, for example:bt_nus_shell.py --name BT_NUS_shell --com COM237 --family NRF52 --snr 682560213
Open a console application, for example, PuTTY. Open a new session, setting up the Connection Type to Raw and the Destination Address to
127.0.0.1:8889
.Press Enter in the terminal window. A console prompt is displayed.
Enter the commands that you want to execute in the remote shell.
Bluetooth LE Console
The Bluetooth LE Console is a stand-alone Linux application that uses a standard Bluetooth device, like an HCI dongle or a built-in Bluetooth device, and the BlueZ stack to communicate over Bluetooth with the device that runs the NUS shell transport.
See Bluetooth LE Console for more information.
API documentation
include/shell/shell_bt_nus.h
subsys/shell/shell_bt_nus.c
- group shell_bt_nus
Nordic UART Service (NUS) shell transport API.
Defines
-
SHELL_BT_NUS_DEFINE(_name, _tx_ringbuf_size, _rx_ringbuf_size)
Macro for creating an instance of the module.
Functions
-
int shell_bt_nus_init(void)
Initialize the NUS shell transport instance.
This function initializes a shell thread and the Nordic UART Service.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
void shell_bt_nus_enable(struct bt_conn *conn)
Enable the NUS shell transport instance.
This function should be called when the connection is established.
- Parameters
conn – Connection handle.
-
void shell_bt_nus_disable(void)
Disable the NUS shell transport instance.
Variables
-
const struct shell_transport_api shell_bt_nus_transport_api
-
struct shell_bt_nus_ctrl_blk
- #include <shell_bt_nus.h>
Instance control block (RW data).
-
struct shell_bt_nus
- #include <shell_bt_nus.h>
Instance structure.
-
SHELL_BT_NUS_DEFINE(_name, _tx_ringbuf_size, _rx_ringbuf_size)