Nordic UART Service (NUS) Client

The Nordic UART Service Client module can be used 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 module 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 send API of this module. 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 notify you that you have unsubscribed successfully.

API documentation

Header file: include/nus_c.h
Source file: subsys/bluetooth/services/nus_c.c
group bt_gatt_nus_c

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

Functions

int bt_gatt_nus_c_init(struct bt_gatt_nus_c *nus_c, const struct bt_gatt_nus_c_init_param *nus_c_init)

Initialize the NUS Client module.

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

Parameters
  • nus_c: NUS Client instance.
  • nus_c_init: NUS Client initialization instance.
Return Value
  • 0: If the operation was successful. Otherwise, a negative error code is returned.

int bt_gatt_nus_c_send(struct bt_gatt_nus_c *nus_c, const u8_t *data, u16_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_c: NUS Client instance.
  • data: Data to be transmitted.
  • len: Length of data.
Return Value
  • 0: If the operation was successful. Otherwise, a negative error code is returned.

int bt_gatt_nus_c_handles_assign(struct bt_gatt_dm *dm, struct bt_gatt_nus_c *nus_c)

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: Discovery object.
  • nus_c: NUS Client instance.
Return Value
  • 0: If the operation was successful.
  • (-ENOTSUP): Special error code used when UUID of the service does not match the expected UUID.
  • Otherwisea: negative error code is returned.

int bt_gatt_nus_c_tx_notif_enable(struct bt_gatt_nus_c *nus_c)

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_c: NUS Client instance.
Return Value
  • 0: If the operation was successful. Otherwise, a negative error code is returned.

struct bt_gatt_nus_c_handles
#include <nus_c.h>

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

Public Members

u16_t rx

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

u16_t tx

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

u16_t tx_ccc

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

struct bt_gatt_nus_c_cbs
#include <nus_c.h>

NUS Client callback structure.

Public Members

u8_t (*data_received)(const u8_t *data, u16_t len)

Data received callback.

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

Parameters
  • data: Received data.
  • len: Length of received data.
Return Value
  • BT_GATT_ITER_CONTINUE: To keep notifications enabled.
  • BT_GATT_ITER_STOP: To disable notifications.

void (*data_sent)(u8_t err, const u8_t *data, u16_t len)

Data sent callback.

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

Parameters
  • err: ATT error code.
  • data: Transmitted data.
  • len: Length of transmitted data.

void (*tx_notif_disabled)(void)

TX notifications disabled callback.

TX notifications have been disabled.

struct bt_gatt_nus_c
#include <nus_c.h>

NUS Client structure.

Public Members

struct bt_conn *conn

Connection object.

atomic_t state

Internal state.

struct bt_gatt_nus_c_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_gatt_nus_c_cbs cbs

Application callbacks.

struct bt_gatt_nus_c_init_param
#include <nus_c.h>

NUS Client initialization structure.

Public Members

struct bt_gatt_nus_c_cbs cbs

Callbacks provided by the user.