Developing with Thingy:53

Connecting to Thingy:53
Building and programming from the source code
Thingy:53 application guide

The Nordic Thingy:53 is a battery-operated prototyping platform for IoT Systems.

The Nordic Thingy:53 integrates the nRF5340 SoC that supports Bluetooth® Low Energy, IEEE 802.15.4 based protocols and Near Field Communication (NFC). The nRF5340 is augmented with the nRF21540 RF FEM (Front-end Module) Range extender that has an integrated power amplifier (PA)/low-noise amplifier (LNA) and nPM1100 Power Management IC (PMIC) that has an integrated dual-mode buck regulator and battery charger.

You can find more information on the Nordic Thingy:53 product page and in the Nordic Thingy:53 Hardware documentation. The nRF Connect SDK provides support for developing applications on the Nordic Thingy:53.

Connecting to Thingy:53 

Applications and samples for the Nordic Thingy:53 use a serial terminal to provide logs. By default, the serial terminal is accessible through the USB CDC ACM class handled by application firmware. The serial port is visible right after the Thingy:53 is connected to the host using a USB cable. The CDC ACM baudrate is ignored, and transfer goes with USB speed.

Note

Some of the samples and applications compatible with Thingy:53 may provide multiple instances of USB CDC ACM class. In that case, the first instance is used to provide logs, and the others are used for application-specific usages.

Building and programming from the source code 

You can program the Nordic Thingy:53 by using the images obtained by building the code in the nRF Connect SDK environment.

To set up your system to be able to build a compatible firmware image, follow the Getting started guide for the nRF Connect SDK.

Build targets 

The build targets of interest for Thingy:53 in the nRF Connect SDK are listed in the following table:

Component

Build target

nRF5340 SoC - Application core

thingy53_nrf5340_cpuapp for the secure domain

thingy53_nrf5340_cpuapp_ns for the non-secure domain

nRF5340 SoC - Network core

thingy53_nrf5340_cpunet

Note

The nRF Connect SDK samples and applications that are compatible with the Nordic Thingy:53 follow the Thingy:53 application guide. The application guide defines a consistent partition map and bootloader configuration to allow serial and OTA firmware updates.

The nRF Connect SDK by default uses Multi-image builds for Thingy:53. Because of this, when you choose thingy53_nrf5340_cpuapp or thingy53_nrf5340_cpuapp_ns as the build target when building a sample or application that is compatible with Thingy:53, you will generate firmware for both the application core and network core:

The application core firmware consists of MCUboot bootloader and an application image.
The network core firmware consists of network core bootloader (B0n) and application firmware of the network core.

The build process generates firmware in two formats:

Intel Hex file (merged_domains.hex) - Used with an external debug probe. The file contains bootloaders and applications for both cores.
Binary files (app_update.bin, net_core_app_update.bin), containing signed application firmwares for the application and network core, respectively. For convenience, the binary files are bundled in dfu_application.zip, together with a manifest that describes them. You can use the binary files or the combined zip archive to update application firmware for both cores, with either MCUboot serial recovery or OTA DFU using Bluetooth LE.

For more information about files generated as output of the build process, see Output build files.

See the following sections for details regarding building and programming the firmware for Thingy:53 in various environments. If your Thingy:53 is already programmed with a Thingy:53-compatible sample or application, you can also use the MCUboot bootloader to update the firmware after you finish building. See Updating firmware image for more detailed information about updating firmware on Thingy:53.

Building and programming using Visual Studio Code 

The nRF Connect for VS Code extension is a complete IDE for developing applications for nRF91, nRF53 and nRF52 Series devices. This includes an interface to the compiler and linker, an RTOS-aware debugger, a seamless interface to the nRF Connect SDK, and a serial terminal. For detailed instructions, see the nRF Connect for Visual Studio Code documentation site.

Complete the following steps after installing the nRF Connect for VS Code extension:

Open Visual Studio Code.

If you installed the nRF Connect SDK using the Toolchain Manager, you can click the Open VS Code button next to the version you installed.
Open the nRF Connect for VS Code extension by clicking its icon or pressing Ctrl + Alt + N.
Click the Add an existing application from the Welcome View.
In the prompt, navigate to the folder containing the sample or application you want to build, such as nrf/samples/bluetooth/peripheral_lbs.

Samples are located under nrf/samples/, and applications are located under nrf/applications/.
Click Select folder to select the sample’s or the application’s folder.

A new application is automatically added in the Applications View.
If needed, click Yes when prompted if you trust the authors of the files.
Click the Add Build Configuration button in the Application View, or click the text stating No build configurations. Click to create one.

This opens the Add Build Configuration screen.
Select the board onto which you want to program the sample. In this case, select thingy53_nrf5340_cpuapp as the target board.
Select the Build after generating configuration checkbox and click the Build Configuration button.

This generates the configuration file and triggers the build process. When the process is complete, the Actions View appears. In this View, you can trigger the build process again, flash the built sample, or start a debug session.
Program the sample or application:
1. Connect the Nordic Thingy:53 to the debug out port on a 10-pin external debug probe, for example nRF5340 DK, using a 10-pin JTAG cable.
2. Connect the external debug probe to the PC using a USB cable.
3. Make sure that the Thingy:53 and the external debug probe are powered on.
4. Click Flash in the Actions View.

Building and programming on the command line 

You must Set up the command-line build environment before you start building an nRF Connect SDK project on the command line.

To build and program the source code from the command line, complete the following steps:

Open a command line or terminal window.
Go to the specific directory for the sample or application.

For example, the directory path is ncs/nrf/applications/machine_learning when building the source code for the nRF Machine Learning application.
Make sure that you have the required version of the nRF Connect SDK repository by pulling the sdk-nrf repository on GitHub as described in Obtaining a copy of the nRF Connect SDK and Updating a copy of the nRF Connect SDK sections.
Get the rest of the dependencies using west:
```
west update
```
Build the sample or application code as follows:
```
west build -b build_target -d destination_directory_name
```
The build target should be thingy53_nrf5340_cpuapp or thingy53_nrf5340_cpuapp_ns when building samples for the application core and thingy53_nrf5340_cpunet when building for the network core.
Program the sample or application:
1. Connect the Nordic Thingy:53 to the debug out port on a 10-pin external debug probe, for example nRF5340 DK, using a 10-pin JTAG cable.
2. Connect the external debug probe to the PC using a USB cable.
3. Make sure that the Nordic Thingy:53 and the external debug probe are powered on.
4. Use the following command to program the sample or application to the device:
```
west flash
```
The device resets and runs the programmed sample or application.

Updating firmware image 

You can program the firmware on the Nordic Thingy:53 using an external debug probe and 10-pin JTAG cable, as described in Building and programming from the source code, using either Visual Studio Code or command line. You can also update applications running on both the network and application core using the built-in MCUboot bootloader and nRF Connect Programmer or the nRF Programmer app for Android and iOS. You can also update the prebuilt application images that way.

See Getting started with precompiled firmware samples for details about updating firmware image.

Firmware update using external debug probe

If you are using an external debug probe, such as the nRF5340 DK, or any J-Link device supporting ARM Cortex-M33, you do not have to use applications that follow the Thingy:53 application guide. In that case, you can program the Thingy:53 in a similar way as nRF5340 DK. See Working with nRF5340 DK for details.

Note

You need to program a sample or application compatible with the Nordic Thingy:53 application guide to bring back serial recovery and DFU OTA.

Firmware update using MCUboot bootloader

The Thingy:53-compatible samples and applications include the MCUboot bootloader that you can use to update firmware. This method uses signed binary files app_update.bin and net_core_app_update.bin (or dfu_application.zip). You can program the precompiled firmware image using one of the following ways:

Use the Introduction to MCUboot feature and the built-in serial recovery mode of Thingy:53. In this scenario Thingy is connected directly to your PC through USB.
Update the firmware over-the-air (OTA) using Bluetooth LE and the nRF Programmer mobile application for Android or iOS. To use this method, the application that is currently programmed on Thingy:53 must support it. All precompiled images support OTA using Bluetooth.

See Getting started with precompiled firmware samples for the detailed procedures on how to program a Thingy:53 using nRF Connect Programmer or the nRF Programmer for Android or iOS.

Thingy:53 application guide 

The Nordic Thingy:53 does not have a built-in J-Link debug IC. Because of that, the samples and applications that are compatible with the Nordic Thingy:53 by default include the MCUboot bootloader with serial recovery support. You can update applications compatible with the Nordic Thingy:53 using the DFU functionality with either nRF Connect Programmer or the nRF Programmer mobile application.

Enabling DFU and MCUboot requires consistency in configuration of the samples and applications. For a sample or application to be compatible with Thingy:53, the application must comply with the configurations described in the following sections.

Note

To use your application with the Nordic Thingy:53 preprogrammed bootloader, you must only set the proper configuration for the Partition Manager and MCUboot. Configurations that enable the other features are not mandatory, but you can enable them if needed.

All applications compatible with the Nordic Thingy:53 in the nRF Connect SDK also support the additional features. Refer to the source code of the samples and applications for examples of implementation.

Partition manager configuration 

The samples compatible with the Nordic Thingy:53 use Partition Manager to define memory partitions. To ensure that partition layout does not change between builds, the sample must use a static partition layout that is consistent between all compatible samples in the nRF Connect SDK. See pm_static_thingy53_nrf5340_cpuapp.yml in a compatible sample for the configuration used. The memory layout must stay consistent, so that MCUboot can perform proper image updates and clean up the settings storage partition.

The PCD SRAM partition is locked by the MCUboot bootloader to prevent the application from modifying the network core firmware. Trying to access data on this partition results in an ARM fault.

The MCUboot bootloader needs a flash controller overlay for the network core image update. The overlay is applied automatically.

MCUboot bootloader 

Each sample must enable the MCUboot bootloader and use the same configuration of the bootloader as all of the Nordic Thingy:53-compatible samples in the nRF Connect SDK. This ensures that the sample includes the MCUboot bootloader and that an MCUboot-compatible image is generated when the sample is built. When using nRF Connect SDK to build the MCUboot bootloader for the Thingy:53, the configuration is applied automatically from the MCUboot repository.

The MCUboot bootloader supports serial recovery and a custom command to erase the settings storage partition. Erasing the settings partition is needed to ensure that an application is not booted with incompatible content loaded from the settings partition.

Use the following Kconfig options to enable the MCUboot bootloader:

In addition, set the CONFIG_UPDATEABLE_IMAGE_NUMBER option to 2 and set an image version, such as "1.0.0+0", using the CONFIG_MCUBOOT_IMAGE_VERSION Kconfig option.

See thingy53_nrf5430_cpuapp.conf in a compatible sample for how this is done.

USB 

An application compatible with the Nordic Thingy:53 is expected to enable USB CDC ACM as backend for logging. The logs are provided using USB CDC ACM to allow accessing them without additional hardware.

Most of the applications and samples compatible with the Nordic Thingy:53 use only a single instance of USB CDC ACM that works as the logger’s backend. No other USB classes are used. These samples can share a common USB product name, vendor ID, and product ID. If a sample supports additional USB classes or more than one instance of USB CDC ACM, it must use a dedicated product name, vendor ID, and product ID.

To enable the USB device stack and the CDC ACM class:

Use the options CONFIG_USB_DEVICE_STACK and CONFIG_USB_CDC_ACM.
Set the default log level with the CONFIG_USB_CDC_ACM_LOG_LEVEL_ERR and CONFIG_USB_DEVICE_LOG_LEVEL_ERR Kconfig options.
Enable the UART log backend with the CONFIG_LOG_BACKEND_UART Kconfig option and disable SEGGER RTT with both the CONFIG_LOG_BACKEND_RTT and CONFIG_USE_SEGGER_RTT Kconfig options.

See thingy53_nrf5340_cpuapp.conf in a compatible sample for how this is done.

In addition, you have to call the usb_enable() function from your application to initialize the USB stack.

See the thingy53.c source file in a compatible sample for how this is done.

Antenna selection 

The Nordic Thingy:53 has an RF front-end with two 2.4 GHz antennas:

ANT1 is connected to the nRF5340 through the nRF21540 RF FEM and supports TX gain of up to +20 dBm.
ANT2 is connected to the nRF5340 through the RF switch and supports TX output power of up to +3 dBm.

The samples in the nRF Connect SDK that are compatible with the Nordic Thingy:53 use ANT1 by default, with the nRF21540 gain set to +10 dBm. You can configure the TX gain with the CONFIG_MPSL_FEM_NRF21540_TX_GAIN_DB Kconfig option to select between +10 dBm or +20 dBm gain. To use the ANT2 antenna, disable the CONFIG_MPSL_FEM Kconfig option in the network core’s child image configuration.

Note

Transmitting with TX output power above +10 dBM is not permitted in some regions. See the Nordic Thingy:53 Regulatory notices in the Nordic Thingy:53 Hardware documentation for the applicable regulations in your region before changing the configuration.

FOTA and SMP 

FOTA updates on the Nordic Thingy:53 are supported using MCUmanager’s Simple Management Protocol (SMP) over Bluetooth. The application acts as a GATT server and allows the connected Bluetooth Central to perform the firmware update for both the application and network core. The Bluetooth configuration is updated to allow quick DFU data transfer.

The application supports SMP handlers related to:

Image management.
Operating System (OS) management – used to reboot the device after the firmware upload is complete.
Erasing settings partition – used to ensure that a new application is not booted with incompatible content in the settings partition written by the previous application.

To enable the MCUmanager library and handling of SMP commands over Bluetooth, use the options CONFIG_MCUMGR and CONFIG_MCUMGR_SMP_BT. Also, disable encryption and authentication requirement for the Bluetooth SMP transport using CONFIG_MCUMGR_SMP_BT_AUTHEN.

You need to enable the MCUmanager handlers for image and OS management. Use the options CONFIG_MCUMGR_CMD_IMG_MGMT and CONFIG_MCUMGR_CMD_OS_MGMT.

You also have to enable the MCUmanager processing of basic Zephyr group commands and storage erase commands. Use the options CONFIG_MCUMGR_GRP_ZEPHYR_BASIC and CONFIG_MCUMGR_GRP_BASIC_CMD_STORAGE_ERASE.

See thing53_nrf5340_cpuapp.conf in a compatible sample for how this is done.

In addition, the application must call the functions os_mgmt_register_group() and img_mgmt_register_group() to register the image and OS management command handlers. The application must also call smp_bt_register() to register the SMP Bluetooth Service.

See the thingy53.c source file in a compatible sample for how this is done.

External flash 

During a FOTA update, there might not be enough space available in internal flash storage to store the existing application and network core images as well as the incoming images, so the incoming images must be stored in external flash storage. This means that a sample compatible with the Nordic Thingy:53 must enable the external flash using the QSPI driver. Enable the option CONFIG_NORDIC_QSPI_NOR, and set CONFIG_NORDIC_QSPI_NOR_FLASH_LAYOUT_PAGE_SIZE to 4096 and CONFIG_NORDIC_QSPI_NOR_STACK_WRITE_BUFFER_SIZE to 16. See thingy53_nrf5340_cpuapp.conf in a compatible sample for how this is done.

Samples and applications compatible with Thingy:53 

The following samples and applications in the nRF Connect SDK are already compatible with Thingy:53: