Nordic UART Service (NUS)

The Bluetooth® Low Energy (LE) GATT Nordic UART Service is a custom service that receives and writes data and serves as a bridge to the UART interface.

The NUS Service is used in the Bluetooth: Peripheral UART sample. It is also included with the Thingy:91 Connectivity bridge, but is disabled by default, and with the Matter door lock sample, as an optional feature that extends the Bluetooth LE connectivity.

Service UUID

The 128-bit vendor-specific service UUID is 6E400001-B5A3-F393-E0A9-E50E24DCCA9E (16-bit offset: 0x0001).

Characteristics

This service has two characteristics.

RX Characteristic (6E400002-B5A3-F393-E0A9-E50E24DCCA9E)

Write or Write Without Response

Write data to the RX Characteristic to send it to the UART interface.

TX Characteristic (6E400003-B5A3-F393-E0A9-E50E24DCCA9E)

Notify

Enable notifications for the TX Characteristic to receive data from the application. The application transmits all data that is received over UART as notifications.

API documentation

Header file: include/bluetooth/services/nus.h
Source file: subsys/bluetooth/services/nus.c
group bt_nus

Nordic UART (NUS) GATT Service API.

Defines

BT_UUID_NUS_VAL

UUID of the NUS Service.

BT_UUID_NUS_TX_VAL

UUID of the TX Characteristic.

BT_UUID_NUS_RX_VAL

UUID of the RX Characteristic.

BT_UUID_NUS_SERVICE
BT_UUID_NUS_RX
BT_UUID_NUS_TX

Enums

enum bt_nus_send_status

NUS send status.

Values:

enumerator BT_NUS_SEND_STATUS_ENABLED

Send notification enabled.

enumerator BT_NUS_SEND_STATUS_DISABLED

Send notification disabled.

Functions

int bt_nus_init(struct bt_nus_cb *callbacks)

Initialize the service.

This function registers a GATT service with two characteristics, TX and RX. A remote device that is connected to this service can send data to the RX Characteristic. When the remote enables notifications, it is notified when data is sent to the TX Characteristic.

Parameters:

  • callbacks – [in] Struct with function pointers to callbacks for service events. If no callbacks are needed, this parameter can be NULL.

Return values:

0 – If initialization is successful. Otherwise, a negative value is returned.

int bt_nus_send(struct bt_conn *conn, const uint8_t *data, uint16_t len)

Send data.

This function sends data to a connected peer, or all connected peers.

Parameters:

  • conn – [in] Pointer to connection object, or NULL to send to all connected peers.

  • data – [in] Pointer to a data buffer.

  • len – [in] Length of the data in the buffer.

Return values:

0 – If the data is sent. Otherwise, a negative value is returned.

static inline uint32_t bt_nus_get_mtu(struct bt_conn *conn)

Get maximum data length that can be used for bt_nus_send.

Parameters:

  • conn – [in] Pointer to connection Object.

Returns:

Maximum data length.

struct bt_nus_cb
#include <nus.h>

Pointers to the callback functions for service events.

Public Members

void (*received)(struct bt_conn *conn, const uint8_t *const data, uint16_t len)

Data received callback.

The data has been received as a write request on the NUS RX Characteristic.

Param conn:

[in] Pointer to connection object that has received data.

Param data:

[in] Received data.

Param len:

[in] Length of received data.

void (*sent)(struct bt_conn *conn)

Data sent callback.

The data has been sent as a notification and written on the NUS TX Characteristic.

Param conn:

[in] Pointer to connection object, or NULL if sent to all connected peers.

void (*send_enabled)(enum bt_nus_send_status status)

Send state callback.

Indicate the CCCD descriptor status of the NUS TX characteristic.

Param status:

[in] Send notification status.