Bluetooth: Peripheral UART

The Peripheral UART sample demonstrates how to use the Nordic UART Service (NUS). It uses the NUS service to send data back and forth between a UART connection and a Bluetooth® LE connection, emulating a serial port over Bluetooth LE.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:53

PCA20053

thingy53_nrf5340

thingy53_nrf5340_cpuapp_ns thingy53_nrf5340_cpuapp

nRF54L15 PDK

nrf54l15pdk_nrf54l15_cpuapp

nrf54l15pdk_nrf54l15_cpuapp

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns nrf5340dk_nrf5340_cpuapp

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52 DK (emulating nRF52810)

PCA10040

nrf52dk_nrf52810

nrf52dk_nrf52810

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52840 DK (emulating nRF52811)

PCA10056

nrf52840dk_nrf52811

nrf52840dk_nrf52811

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

nRF52833 DK (emulating nRF52820)

PCA10100

nrf52833dk_nrf52820

nrf52833dk_nrf52820

nRF21540 DK

PCA10112

nrf21540dk_nrf52840

nrf21540dk_nrf52840

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Note

  • The boards nrf52dk_nrf52810, nrf52840dk_nrf52811, and nrf52833dk_nrf52820 only support the Minimal sample variant.

  • When used with Thingy:53, the sample supports the MCUboot bootloader with serial recovery and SMP DFU over Bluetooth. Thingy:53 has no built-in SEGGER chip, so the UART 0 peripheral is not gated to a USB CDC virtual serial port.

  • When used with nRF5340 DK, the sample might support the MCUboot bootloader with serial recovery of the networking core image.

The sample also requires a smartphone or tablet running a compatible application. The Testing instructions refer to nRF Connect for Mobile, but you can also use other similar applications (for example, nRF Blinky or nRF Toolbox).

You can also test the application with the Bluetooth: Central UART sample. See the documentation for that sample for detailed instructions.

Note

If you build this application for Thingy:53, it enables additional features. See Thingy:53 application guide for details.

The sample also enables an additional USB CDC ACM port that is used instead of UART 0. Because of that, it uses a separate USB Vendor and Product ID.

Overview

When connected, the sample forwards any data received on the RX pin of the UART 0 peripheral to the Bluetooth LE unit. On Nordic Semiconductor’s development kits, the UART 0 peripheral is typically gated through the SEGGER chip to a USB CDC virtual serial port.

Any data sent from the Bluetooth LE unit is sent out of the UART 0 peripheral’s TX pin.

Note

Thingy:53 uses the second instance of USB CDC ACM class instead of UART 0, because it has no built-in SEGGER chip that could be used to gate UART 0.

Debugging

In this sample, the UART console is used to send and read data over the NUS service. Debug messages are not displayed in this UART console. Instead, they are printed by the RTT logger.

If you want to view the debug messages, follow the procedure in Testing and optimization.

Note

On the Thingy:53, debug logs are provided over the USB CDC ACM class serial port, instead of using RTT.

For more information about debugging in the nRF Connect SDK, see Debugging an application.

FEM support

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

  • Build the sample for one board that contains the nRF21540 FEM, such as nrf21540dk_nrf52840.

  • Manually create a devicetree overlay file that describes how FEM is connected to the nRF5 SoC in your device. See Set devicetree overlays for different ways of adding the overlay file.

  • Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command, for example SHIELD=nrf21540ek. This variable instructs the build system to append the appropriate devicetree overlay file.

    To build the sample in the nRF Connect for VS Code IDE for an nRF52840 DK with the nRF21540 EK attached, add the shield variable in the build configuration’s Extra CMake arguments and rebuild the build configuration. For example: -DSHIELD=nrf21540ek.

    See nRF Connect for VS Code extension pack documentation for more information.

    See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Working with RF front-end modules for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Minimal sample variant

You can build the sample with a minimum configuration as a demonstration of how to reduce code size and RAM usage. This variant is available for resource-constrained boards.

See Activating sample extensions for details.

USB CDC ACM extension

For the boards with the USB device peripheral, you can build the sample with support for the USB CDC ACM class serial port instead of the physical UART. This build uses the sample-specific UART async adapter module that acts as a bridge between USB CDC ACM and Zephyr’s UART asynchronous API used by the sample. See Activating sample extensions for details about how to build the sample with this extension using the prj_cdc.conf file.

Async adapter experimental module

The default sample configuration uses the UART async API. The sample uses the UART async adapter library to communicate with the USB CDC ACM driver. This is needed because the USB CDC ACM implementation provides only the interrupt interface.

To use the library, set the CONFIG_UART_ASYNC_ADAPTER Kconfig option to y.

MCUboot with serial recovery of the networking core image

For the nrf5340dk_nrf5340_cpuapp, it is possible to enable serial recovery of the network core while multi-image update is not enabled in the MCUboot. See Activating sample extensions for details on how to build the sample with this feature using the nrf5340dk_app_sr_net.conf and nrf5340dk_mcuboot_sr_net.conf files.

User interface

The user interface of the sample depends on the hardware platform you are using.

Development kits

LED 1:

Blinks, toggling on/off every second, when the main loop is running and the device is advertising.

LED 2:

Lit when connected.

Button 1:

Confirm the passkey value that is printed in the debug logs to pair/bond with the other device.

Button 2:

Reject the passkey value that is printed in the debug logs to prevent pairing/bonding with the other device.

Thingy:53

RGB LED:

The RGB LED channels are used independently to display the following information:

  • Red channel blinks with a period of two seconds, duty cycle 50%, when the main loop is running (device is advertising).

  • Green channel displays if device is connected.

Button:

Confirm the passkey value that is printed in the debug logs to pair/bond with the other device. Thingy:53 has only one button, therefore the passkey value cannot be rejected by pressing a button.

Configuration

See Configuring and building an application for information about how to permanently or temporarily change the configuration.

Configuration options

Check and configure the following configuration options for the sample:

CONFIG_UART_ASYNC_ADAPTER - Enable UART async adapter

Enables asynchronous adapter for UART drives that supports only IRQ interface.

Building and running

This sample can be found under samples/bluetooth/peripheral_uart in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Activating sample extensions

To activate the optional extensions supported by this sample, modify OVERLAY_CONFIG in the following manner:

  • For the minimal build variant, set prj_minimal.conf.

  • For the USB CDC ACM extension, set prj_cdc.conf. Additionally, you need to set DTC_OVERLAY_FILE to the usb.overlay file.

  • For the MCUboot with serial recovery of the networking core image feature, set the nrf5340dk_app_sr_net.conf file. You also need to set the mcuboot_OVERLAY_CONFIG variant to the nrf5340dk_mcuboot_sr_net.conf file.

See Providing CMake options for instructions on how to add this option. For more information about using configuration overlay files, see Important Build System Variables in the Zephyr documentation.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the device to the computer to access UART 0. If you use a development kit, UART 0 is forwarded as a COM port (Windows) or ttyACM device (Linux) after you connect the development kit over USB. If you use Thingy:53, you must attach the debug board and connect an external USB to UART converter to it.

  2. Connect to the kit with a terminal emulator (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

  3. Optionally, you can display debug messages. See Debugging for details.

  4. Reset the kit.

  5. Observe that LED 1 is blinking and that the device is advertising with the device name that is configured in CONFIG_BT_DEVICE_NAME.

  6. Observe that the text “Starting Nordic UART service example” is printed on the COM listener running on the computer.

  7. Connect to the device using nRF Connect for Mobile. Observe that LED 2 is lit.

  8. Optionally, pair or bond with the device with MITM protection. This requires using the passkey value displayed in debug messages. See Debugging for details on how to access debug messages. To confirm pairing or bonding, press Button 1 on the device and accept the passkey value on the smartphone.

  9. In the application, observe that the services are shown in the connected device.

  10. Select the UART RX characteristic value in nRF Connect for Mobile. You can write to the UART RX and get the text displayed on the COM listener.

  11. Type “0123456789” and tap SEND. Verify that the text “0123456789” is displayed on the COM listener.

  12. To send data from the device to your phone or tablet, enter any text, for example, “Hello”, and press Enter to see it on the COM listener. Observe that a notification is sent to the peer.

  13. Disconnect the device in nRF Connect for Mobile. Observe that LED 2 turns off.

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following Zephyr libraries:

  • include/zephyr/types.h

  • boards/arm/nrf*/board.h

  • Kernel Services:

    • include/kernel.h

  • Peripherals:

    • include/gpio.h

    • include/uart.h

  • Bluetooth APIs:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/gatt.h

    • include/bluetooth/hci.h

    • include/bluetooth/uuid.h

The sample also uses the following secure firmware component: