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 inform you that you have unsubscribed successfully.
API documentation¶
include/nus_client.h
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.
- Returns 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.
- Returns 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.
- Returns 0
If the operation was successful.
- Returns (-ENOTSUP)
Special error code used when UUID of the service does not match the expected UUID.
- Returns 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.
- Returns 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.
-
struct
bt_nus_client_cb
¶ - #include <nus_client.h>
NUS Client callback structure.
Public Members
-
uint8_t (*
received
)(const uint8_t *data, uint16_t len)¶ Data received callback.
The data has been received as a notification of the NUS TX Characteristic.
- Parameters
data – [in] Received data.
len – [in] Length of received data.
- Returns BT_GATT_ITER_CONTINUE
To keep notifications enabled.
- Returns BT_GATT_ITER_STOP
To disable notifications.
-
void (*
sent
)(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.
- Parameters
err – [in] ATT error code.
data – [in] Transmitted data.
len – [in] Length of transmitted data.
-
void (*
unsubscribed
)(void)¶ TX notifications disabled callback.
TX notifications have been disabled.
-
uint8_t (*
-
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_conn *
-
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.
-
struct bt_nus_client_cb
-
int