| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Nordic UART Service Client
This example requires one of the following SoftDevices: S130, S132

Important: Before you run this example, make sure to program the SoftDevice.

The Nordic UART Service (NUS) Client Application is an example that implements the Nordic UART Service Client over BLE. In the example, the development board serves as a GAP central and a GATT client.

The application scans peripheral devices and connects to a device that advertises with the NUS UUID in its advertisement report. After connecting, the application enables notifications on the device that delivers the Nordic UART Service.

Note
  This application will connect to only one device that delivers the NUS. If the application cannot find the NUS in the device discovery, it will not disconnect. This makes it possible to use more GATT clients at the same time.

# Setup

You can find the source code and the project file of the example in the following folder: `<InstallFolder>\examples\ble_central\ble_app_uart_c`

Button assignments: BSP BLE Button Assignments

The application uses the following UART settings:

- Baud rate: 115.200
- 8 data bits
- 1 stop bit
- No parity
- HW flow control: RTS/CTS

# Design overview

The responsibility of connecting to the NUS server is shared between the main program and the ble_nus_c module. The main program scans and reads the advertisement packets and connects to a device that delivers the NUS. After connecting, it starts service discovery. In this way, it is possible to scan for different services without needing to start unnecessary service discoveries.

The ble_nus_c module is responsible for parsing the service scan response and passing notifications back to the main program.

## Scanning and reading advertisement packets

The scanning parameters are set in the m_scan_params structure. Active scanning must be enabled, because the advertised service list is sent as scan response data.

The advertisement packet is parsed using the function is_uuid_present. If this function returns true, the application will connect to the device.

## Handling events from ble_nus_c

The following code example shows how to handle events from the ble_nus_c module:

static void ble_nus_c_evt_handler(ble_nus_c_t * p_ble_nus_c, const ble_nus_c_evt_t * p_ble_nus_evt)
{
uint32_t err_code;
switch (p_ble_nus_evt->evt_type)
{
case BLE_NUS_C_EVT_DISCOVERY_COMPLETE:
err_code = ble_nus_c_handles_assign(p_ble_nus_c, p_ble_nus_evt->conn_handle, &p_ble_nus_evt->handles);
APP_ERROR_CHECK(err_code);
err_code = ble_nus_c_rx_notif_enable(p_ble_nus_c);
APP_ERROR_CHECK(err_code);
printf("The device has the Nordic UART Service\r\n");
break;
case BLE_NUS_C_EVT_NUS_RX_EVT:
for (uint32_t i = 0; i < p_ble_nus_evt->data_len; i++)
{
while (app_uart_put( p_ble_nus_evt->p_data[i]) != NRF_SUCCESS);
}
break;
case BLE_NUS_C_EVT_DISCONNECTED:
printf("Disconnected\r\n");
scan_start();
break;
}
}

If the RX characteristic is found, notifications are enabled. When an RX notification is received, the data is printed out to UART.

## Handling data received from UART

When data is received from UART, the data is split up in packets and sent using NUS. The following code example shows how to handle UART data:

case APP_UART_DATA_READY:
UNUSED_VARIABLE(app_uart_get(&data_array[index]));
index++;
if ((data_array[index - 1] == '\n') || (index >= (BLE_NUS_MAX_DATA_LEN)))
{
while (ble_nus_c_string_send(&m_ble_nus_c, data_array, index) != NRF_SUCCESS)
{
// repeat until sent.
}
index = 0;
}
break;

# Testing

Two boards are needed to perform this test:

- Central Board: nRF5 development board containing an S13x SoftDevice.
- Peripheral Board: nRF5 development board containing an S13x SoftDevice and the UART peripheral application provided with the nRF5 SDK.

The application running on the Peripheral Board is intended to serve as a peer (for example, in the Nordic UART Service (NUS) Application role) to this NUS Client application.

Test the BLE NUS Client Example application by performing the following steps:

1. Compile the BLE NUS Client Example application and program both the SoftDevice and the application on the Central Board.
2. On the Central board, observe that the BSP_INDICATE_SCANNING state is indicated. This shows that the application is scanning for a NUS service Peripheral.
3. Compile the NUS application and program both the SoftDevice and the application on the Peripheral Board.
4. Observe that the NUS Peripheral is advertising.
5. Once the connection is established, the BSP_INDICATE_CONNECTED state is indicated on both boards.
6. Now it is possible to send data between the two boards. To do so, send data to one of the boards using the serial port. Observe that the data is displayed on the UART on the other board.