Nordic UART Service (NUS) Client

You can use the Nordic UART Service Client library to interact with a connected peer that is running the GATT server with the Nordic UART Service (NUS). The client uses the GATT Discovery Manager library to acquire the attribute handles that are necessary to interact with the RX and TX Characteristics.

The NUS Service Client is used in the Bluetooth: Central UART sample.

RX Characteristic

To send data to the RX Characteristic, use the bt_nus_client_send() function of this library. The sending procedure is asynchronous, so the data to be sent must remain valid until a dedicated callback notifies you that the write request has been completed.

TX Characteristic

To receive data coming from the TX Characteristic, enable notifications after the service discovery. After that, you can request to disable notifications again by returning the STOP value in the callback that is used to handle incoming data. Another dedicated callback is triggered when your request has been completed, to inform that you have unsubscribed successfully.

API documentation

Header file: include/bluetooth/services/nus_client.h
Source file: subsys/bluetooth/services/nus_client.c
group bt_nus_client

API for the Bluetooth LE GATT Nordic UART Service (NUS) Client.

Functions

int bt_nus_client_init(struct bt_nus_client *nus, const struct bt_nus_client_init_param *init_param)

Initialize the NUS Client module.

This function initializes the NUS Client module with callbacks provided by the user.

Parameters:

  • nus – [inout] NUS Client instance.

  • init_param – [in] NUS Client initialization parameters.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

int bt_nus_client_send(struct bt_nus_client *nus, const uint8_t *data, uint16_t len)

Send data to the server.

This function writes to the RX Characteristic of the server.

Note

This procedure is asynchronous. Therefore, the data to be sent must remain valid while the function is active.

Parameters:

  • nus – [inout] NUS Client instance.

  • data – [in] Data to be transmitted.

  • len – [in] Length of data.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

int bt_nus_handles_assign(struct bt_gatt_dm *dm, struct bt_nus_client *nus)

Assign handles to the NUS Client instance.

This function should be called when a link with a peer has been established to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module. The GATT attribute handles are provided by the GATT DB discovery module.

Parameters:

  • dm – [in] Discovery object.

  • nus – [inout] NUS Client instance.

Return values:

  • 0 – If the operation was successful.

  • (-ENOTSUP) – Special error code used when UUID of the service does not match the expected UUID.

  • Otherwise, a – negative error code is returned.

int bt_nus_subscribe_receive(struct bt_nus_client *nus)

Request the peer to start sending notifications for the TX Characteristic.

This function enables notifications for the NUS TX Characteristic at the peer by writing to the CCC descriptor of the NUS TX Characteristic.

Parameters:

  • nus – [inout] NUS Client instance.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

struct bt_nus_client_handles
#include <nus_client.h>

Handles on the connected peer device that are needed to interact with the device.

Public Members

uint16_t rx

Handle of the NUS RX characteristic, as provided by a discovery.

uint16_t tx

Handle of the NUS TX characteristic, as provided by a discovery.

uint16_t tx_ccc

Handle of the CCC descriptor of the NUS TX characteristic, as provided by a discovery.

struct bt_nus_client_cb
#include <nus_client.h>

NUS Client callback structure.

Public Members

uint8_t (*received)(struct bt_nus_client *nus, const uint8_t *data, uint16_t len)

Data received callback.

The data has been received as a notification of the NUS TX Characteristic.

Param nus:

[in] NUS Client instance.

Param data:

[in] Received data.

Param len:

[in] Length of received data.

Retval BT_GATT_ITER_CONTINUE:

To keep notifications enabled.

Retval BT_GATT_ITER_STOP:

To disable notifications.

void (*sent)(struct bt_nus_client *nus, uint8_t err, const uint8_t *data, uint16_t len)

Data sent callback.

The data has been sent and written to the NUS RX Characteristic.

Param nus:

[in] NUS Client instance.

Param err:

[in] ATT error code.

Param data:

[in] Transmitted data.

Param len:

[in] Length of transmitted data.

void (*unsubscribed)(struct bt_nus_client *nus)

TX notifications disabled callback.

TX notifications have been disabled.

Param nus:

[in] NUS Client instance.

struct bt_nus_client
#include <nus_client.h>

NUS Client structure.

Public Members

struct bt_conn *conn

Connection object.

atomic_t state

Internal state.

struct bt_nus_client_handles handles

Handles on the connected peer device that are needed to interact with the device.

struct bt_gatt_subscribe_params tx_notif_params

GATT subscribe parameters for NUS TX Characteristic.

struct bt_gatt_write_params rx_write_params

GATT write parameters for NUS RX Characteristic.

struct bt_nus_client_cb cb

Application callbacks.

struct bt_nus_client_init_param
#include <nus_client.h>

NUS Client initialization structure.

Public Members

struct bt_nus_client_cb cb

Callbacks provided by the user.