Developing with Thingy:53

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.

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 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 Cortex-M Security Extensions (CMSE) disabled

thingy53_nrf5340_cpuapp_ns for CMSE enabled

nRF5340 SoC - Network core

thingy53_nrf5340_cpunet

The nRF Connect SDK uses Multi-image builds for Thingy:53 by default. When you choose thingy53_nrf5340_cpuapp or thingy53_nrf5340_cpuapp_ns as the build target when building a sample or application, 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. 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 installation instructions, see Installing using Visual Studio Code. For other instructions related to nRF Connect for VS Code extension, see the nRF Connect for Visual Studio Code documentation site.

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

  1. Open Visual Studio Code.

    If you installed the nRF Connect SDK using the Installing automatically, you can click the Open VS Code button next to the version you installed.

  2. Complete the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation.

  1. 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:

  1. Open a command line or terminal window.

  2. 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.

  3. 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.

  4. Get the rest of the dependencies using west:

    west update

  5. 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. The proper child image for thingy53_nrf5340_cpunet will be built automatically. See Build targets for details.

  6. 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 can program the Thingy:53 the same way as nRF5340 DK. See Developing with nRF5340 DK for details.

Firmware update using MCUboot bootloader

Samples and applications built for Thingy:53 include the MCUboot bootloader that you can use to update the firmware out of the box. 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. For details, refer to FOTA over Bluetooth Low Energy section. 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 Thingy:53 board enables MCUboot bootloader with serial recovery support and predefined static Partition Manager memory map by default. You can also enable FOTA updates manually. See the following sections for details of what is configured by default and what you can configure by yourself.

Partition manager configuration

The samples and applications for Nordic Thingy:53 use the Partition Manager by default to define memory partitions. The memory layout must stay consistent, so that MCUboot can perform proper image updates and clean up the settings storage partition. To ensure that the partition layout does not change between builds, the sample must use a static partition layout that is consistent between all samples in the nRF Connect SDK. The memory partitions are defined in the pm_static_thingy53_nrf5340_cpuapp.yml and pm_static_thingy53_nrf5340_cpuapp_ns.yml files in the zephyr/boards/arm/thingy53_nrf5340 directory.

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

MCUboot bootloader is enabled by default for Thingy:53 in the Kconfig.defconfig file of the board. 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.

In addition, you can set an image version, such as "2.3.0+0", using the CONFIG_MCUBOOT_IMAGE_VERSION Kconfig option.

USB

The logs on the Thingy:53 board are provided by default using USB CDC ACM to allow access to them without additional hardware.

Most of the applications and samples for 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. This sample must also enable USB composite device configuration (CONFIG_USB_COMPOSITE_DEVICE).

The CONFIG_BOARD_SERIAL_BACKEND_CDC_ACM Kconfig option (defined in the zephyr/boards/arm/thingy53_nrf5340/Kconfig.defconfig file) automatically sets the default values of USB product name, vendor ID and product ID of Thingy:53. It also enables the USB device stack and initializes the USB device at boot. The remote wakeup feature of a USB device is disabled by default as it requires extra action from the application side. A single USB CDC ACM instance is automatically included in the default board’s DTS configuration file (zephyr/boards/arm/thingy53_nrf5340/thingy53_nrf5340_common.dts). The USB CDC instance is used to forward application logs.

If you do not want to use the USB CDC ACM as a backend for logging out of the box, you can disable it as follows:

  • Disable the CONFIG_BOARD_SERIAL_BACKEND_CDC_ACM Kconfig option.

  • If USB CDC ACM is not used for anything else, you can disable it in the application’s DTS overlay file:

    &cdc_acm_uart {
    status = "disabled";
};

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.

Nordic Thingy:53 - Antenna connections

Nordic Thingy:53 - Antenna connections

The samples in the nRF Connect SDK 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 over Bluetooth Low Energy

FOTA updates are supported using MCUmgr’s Simple Management Protocol (SMP) over Bluetooth. The application acts as a GATT server and allows the connected Bluetooth Central device to perform a firmware update. To use FOTA over Bluetooth LE, samples must support Bluetooth peripheral role (CONFIG_BT_PERIPHERAL).

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 support for FOTA updates, do the following:

  • Enable the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option, which implies configuration of the following:

    • All of the SMP command handlers mentioned in the previous paragraph.

    • SMP BT reassembly feature.

    • The CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP Kconfig option automatically extends the Bluetooth buffers, which allows to speed up the FOTA transfer over Bluetooth, but also increases RAM usage.

Bluetooth buffers configuration introduced by the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP Kconfig option is also automatically applied to the network core child image by the dedicated overlay file. Thingy:53 supports network core upgrade out of the box.

If necessary, you can modify any of the implied options or defaulted values introduced by the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option.

You can either add these Kconfig options to the configuration files of your application or have them inline in a project build command. Here is an example of how you can build for the Bluetooth: Peripheral LBS sample:

 west build -b build_target -- -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y

When you connect to the device after the build has completed and the firmware has been programmed to it, the SMP Service is enabled with the UUID 8D53DC1D-1DB7-4CD3-868B-8A527460AA84. If you want to add SMP Service to advertising data, refer to the SMP Server Sample.

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. The Thingy:53 board automatically configures external flash storage and QSPI driver when FOTA updates are implied with the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option.

Samples and applications for Thingy:53 with FOTA out of the box

The following samples and applications in the nRF Connect SDK enable FOTA for Thingy:53 by default: