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 ID

  • family - the chip family of the development kit, for example, nRF52

  • name - the advertising name of the device with the NUS shell

  • port - 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:

  1. Connect a Nordic Development Kit, like the PCA10040, to your PC.

  2. 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

  3. Open a console application, for example, PuTTY. Open a new session, setting the Connection Type to Raw and the Destination Address to 127.0.0.1:8889.

  4. Press Enter in the terminal window. A console prompt is displayed.

  5. 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

Header file: include/shell/shell_bt_nus.h
Source file: 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.