Developing with Thingy:91

Nordic Thingy:91 is a battery-operated prototyping platform for cellular IoT systems, designed especially for asset tracking applications and environmental monitoring. Thingy:91 integrates an nRF9160 SiP that supports LTE-M, NB-IoT, and Global Navigation Satellite System (GNSS) and an nRF52840 SoC that supports Bluetooth® Low Energy, Near Field Communication (NFC) and USB.

You can find more information on the product in the Thingy:91 product page and in the Nordic Thingy:91 User Guide. The nRF Connect SDK provides support for developing applications on the Thingy:91. If you are not familiar with the nRF Connect SDK, see Installation and Configuration and building documentation to install the nRF Connect SDK and learn more about its development environment.

This guide gives you more information on the various aspects of Thingy:91.

Connecting to Thingy:91

You can connect to Thingy:91 wirelessly (using the nRF Toolbox app) or over a serial connection (using nRF Connect Serial Terminal, Cellular Monitor, or a serial terminal).

Using nRF Toolbox

To connect to your Thingy:91 wirelessly, you need to meet the following prerequisites:

  • The Connectivity bridge installed on your Thingy:91.

  • The Nordic UART Service (NUS) enabled.

    Note

    By default, the Bluetooth LE interface is off, as the connection is not encrypted or authenticated. To turn it on at runtime, set the appropriate option in the Config.txt file located on the USB Mass storage Device.

Using a serial terminal

If you prefer to use a standard serial terminal, the baud rate has to be specified manually.

Thingy:91 uses the following UART baud rate configuration:

UART Interface

Baud Rate

UART_0

115200

UART_1

1000000

Using nRF Connect Serial Terminal

You can use the nRF Connect Serial Terminal application to get debug output and send AT commands to the Thingy:91. In the case of nRF Connect Serial Terminal or Cellular Monitor, the baud rate for the communication is set automatically.

To connect to the Thingy:91 using the nRF Connect Serial Terminal app, complete the following steps:

  1. Open nRF Connect for Desktop.

  2. Find Serial Terminal in the list of applications and click Install.

  3. Connect the Thingy:91 to a computer with a micro-Universal Serial Bus (USB) cable.

  4. Make sure that the Thingy:91 is powered on.

  5. Launch the Serial Terminal application.

  6. In the navigation bar, click SELECT DEVICE. A drop-down menu appears.

  7. In the menu, select Thingy:91.

  8. In the terminal window, send an AT command to the modem. If the connection is working, the modem responds with OK.

The terminal view shows all of the Asset Tracker v2 debug output as well as the AT commands and their results. For information on the available AT commands, see the nRF9160 AT Commands Reference Guide.

Operating modes

Thingy:91 contains RGB indicator LEDs, which indicate the operating state of the device as described in the LED indication section of the User Interface module.

GNSS

Thingy:91 has a GNSS receiver, which, if activated, allows the device to be located globally using GNSS signals. In Asset Tracker v2, GNSS is activated by default.

LTE Band Lock

The modem within Thingy:91 can be configured to use specific LTE bands by using the band lock AT command. See Band lock and the band lock section in the AT Commands reference document for additional information. The preprogrammed firmware configures the modem to use the bands currently certified on the Thingy:91 hardware. When building the firmware, you can configure which bands must be enabled.

LTE-M / NB-IoT switching

Thingy:91 has a multimode modem, which enables it to support automatic switching between LTE-M and NB-IoT. A built-in parameter in the Thingy:91 firmware determines whether the modem first attempts to connect in LTE-M or NB-IoT mode. If the modem fails to connect using this preferred mode within the default timeout period (10 minutes), the modem switches to the other mode.

Updating the Thingy:91 firmware using Programmer

You can use the Programmer app from nRF Connect for Desktop to:

These operations can be done through USB using MCUboot, or through an external debug probe. When developing with your Thingy:91, it is recommended to use an external debug probe.

Note

The external debug probe must support Arm Cortex-M33, such as the nRF9160 DK. You need a 10-pin 2x5 socket-socket 1.27 mm IDC (Serial Wire Debug (SWD)) JTAG cable to connect to the external debug probe.

Download and extract the latest application and modem firmware from the Thingy:91 Downloads page.

The downloaded ZIP archive contains the following firmware:

Application firmware

The img_app_bl folder contains full firmware images for different applications. The guides in this section use the images for the Connectivity bridge and Asset Tracker v2 applications. Connectivity bridge provides bridge functionality for the hardware, and Asset Tracker v2 simulates sensor data and transmits it to Nordic Semiconductor’s cloud solution, nRF Cloud.

The data is transmitted using either LTE-M or NB-IoT. Asset Tracker v2 first attempts to use LTE-M, then NB-IoT. Check with your SIM card provider for the mode they support at your location. For the iBasis SIM card provided with the nRF9160 DK, see iBasis IoT network coverage.

Application firmware for Device Firmware Update (DFU)

The images in the img_fota_dfu_bin and img_fota_dfu_hex folders contain firmware images for DFU. These images are not used in the guides in this section.

Modem firmware

The modem firmware is in a ZIP archive instead of a folder. The archive is named mfw_nrf9160_ followed by the firmware version number. Do not unzip this file.

Tip

For a more compact nRF Cloud firmware application, you can build and install the Cellular: nRF Cloud multi-service sample. See the Building and programming from the source code section for more information.

The CONTENTS.txt file in the extracted folder contains the location and names of the different firmware images.

Note

To update the Thingy:91 through USB, the nRF9160 SiP and nRF52840 SoC bootloaders must be factory-compatible. The bootloaders might not be factory-compatible if the nRF9160 SiP or nRF52840 SoC has been updated with an external debug probe. To restore the bootloaders, program the nRF9160 SiP or nRF52840 SoC with factory-compatible Thingy:91 firmware files through an external debug probe.

Note

You can also use these precompiled firmware image files for restoring the firmware to its initial image.

Updating the firmware in the nRF52840 SoC

To update the firmware, complete the following steps:

  1. Open nRF Connect for Desktop and launch the Programmer app.

  2. Scroll down in the menu on the left and make sure Enable MCUboot is selected.

    Programmer - Enable MCUboot

    Programmer - Enable MCUboot

  3. Switch off the Thingy:91.

  4. Press SW4 while switching SW1 to the ON position.

    thingy91_sw1_sw4

    Thingy:91 - SW1 SW4 switch

  5. In the Programmer navigation bar, click SELECT DEVICE. A drop-down menu appears.

    Programmer - Select device

    Programmer - Select device

  6. In the menu, select the entry corresponding to your device (MCUBOOT).

    Note

    The device entry might not be the same in all cases and can vary depending on the application version and the operating system.

  7. In the menu on the left, click Add file in the FILE section, and select Browse. A file explorer window appears.

    Programmer - Add file

    Programmer - Add file

  8. Navigate to where you extracted the firmware.

  9. Open the folder img_fota_dfu_hex that contains the HEX files for updating over USB. See the CONTENTS.txt file for information on which file you need.

  10. Select the Connectivity bridge firmware file.

  11. Click Open.

  12. Scroll down in the menu on the left to the DEVICE section and click Write.

    Programmer - Writing of HEX files

    Programmer - Writing of HEX files

    The MCUboot DFU window appears.

    Programmer - MCUboot DFU

    Programmer - MCUboot DFU

  13. In the MCUboot DFU window, click Write. When the update is complete, a “Completed successfully” message appears.

  14. Scroll up in the menu on the left to the FILE section and click Clear files.

Update the modem firmware on the nRF9160 SiP

To update the modem firmware using USB, complete the following steps:

  1. Open nRF Connect for Desktop and launch the Programmer app if you do not have it open already.

  2. Make sure that Enable MCUboot is selected.

  3. Switch off the Thingy:91.

  4. Press SW3 while switching SW1 to the ON position.

    Thingy:91 - SW1 SW3 switch

    Thingy:91 - SW1 SW3 switch

  5. In the menu, select Thingy:91.

  6. In the menu on the left, click Add file in the FILE section, and select Browse. A file explorer window appears.

    Programmer - Add file

    Programmer - Add file

  7. Navigate to where you extracted the firmware.

  8. Find the modem firmware zip file with the name similar to mfw_nrf9160_*.zip and the number of the latest version.

    Note

    Do not extract the modem firmware zip file.

  9. Select the zip file and click Open.

  10. In the Programmer app, scroll down in the menu on the left to the DEVICE section and click Write.

    Programmer - Update modem

    Programmer - Update modem

    The Modem DFU via MCUboot window appears.

    Programmer - Modem DFU via MCUboot

    Programmer - Modem DFU via MCUboot

  11. In the Modem DFU via MCUboot window, click Write. When the update is complete, a Completed successfully message appears.

Program the nRF9160 SiP application

To program the application firmware using USB, complete the following steps:

  1. Open nRF Connect for Desktop and launch the Programmer app if you have not done already.

  2. Make sure that Enable MCUboot is selected.

  3. Switch off the Thingy:91.

  4. Press SW3 while switching SW1 to the ON position.

    Thingy:91 - SW1 SW3 switch

    Thingy:91 - SW1 SW3 switch

  5. In the Programmer navigation bar, click SELECT DEVICE. A drop-down menu appears.

    Programmer - Select device

    Programmer - Select device

  6. In the menu, select Thingy:91.

  7. In the menu on the left, click Add file in the FILE section, and select Browse. A file explorer window appears.

    Programmer - Add file

    Programmer - Add file

  8. Navigate to where you extracted the firmware.

  9. Open the folder img_fota_dfu_hex that contains the HEX files for updating over USB. See the CONTENTS.txt file for information on which file you need.

  10. Select the appropriate Asset Tracker v2 firmware file.

    Note

    If you are connecting over NB-IoT and your operator does not support extended Protocol Configuration Options (ePCO), select the file that has legacy Protocol Configuration Options (PCO) mode enabled.

  11. Click Open.

  12. Scroll down in the menu on the left to the DEVICE section and click Write.

    Programmer - Writing of HEX files

    Programmer - Writing of HEX files

    The MCUboot DFU window appears.

    Programmer - MCUboot DFU

    Programmer - MCUboot DFU

  13. In the MCUboot DFU window, click Write. When the update is complete, a Completed successfully message appears.

  14. Scroll up in the menu on the left to the FILE section and click Clear files.

Building and programming from the source code

You can also program the Thingy:91 by using the images obtained by building the code in an nRF Connect SDK environment.

To set up your system to be able to build a compatible firmware image, follow the Installation guide for the nRF Connect SDK and read the Configuration and building documentation. The build targets of interest for Thingy:91 in nRF Connect SDK are as follows:

Component

Build target

nRF9160 SiP

thingy91_nrf9160_ns

nRF52840 SoC

thingy91_nrf52840

You must use the build target thingy91_nrf9160_ns when building the application code for the nRF9160 SiP and the build target thingy91_nrf52840 when building the application code for the onboard nRF52840 SoC.

Note

  • In nRF Connect SDK releases before v1.3.0, these build targets were named nrf9160_pca20035, nrf9160_pca20035ns, and nrf52840_pca20035.

  • In nRF Connect SDK releases ranging from v1.3.0 to v1.6.1, the build target thingy91_nrf9160_ns was named thingy91_nrf9160ns.

Note

LTE/GNSS features can only be used with Cortex-M Security Extensions enabled (_ns build target).

The table below shows the different types of build files that are generated and the different scenarios in which they are used:

File

File format

Programming scenario

merged.hex

Full image, HEX format

Using an external debug probe and nRF Connect Programmer.

app_signed.hex

MCUboot compatible image, HEX format

Using the built-in bootloader and nRF Connect Programmer.

app_update.bin

MCUboot compatible image, binary format

  • Using the built-in bootloader and mcumgr command line tool.

  • For FOTA updates.

For an overview of different types of build files in the nRF Connect SDK, see Output build files.

There are multiple methods of programming a sample or application onto a Thingy:91. It is recommended to use an external debug probe to program the Thingy:91.

Note

If you do not have an external debug probe available to program the Thingy:91, you can directly program by using the USB (MCUboot) method and nRF Connect Programmer. In this scenario, use the app_signed.hex firmware image file.

Note

While building applications for Thingy:91, the build system changes the signing algorithm of MCUboot so that it uses the default RSA Keys. This is to ensure backward compatibility with the MCUboot versions that precede the nRF Connect SDK v1.4.0. The default RSA keys must only be used for development. In a final product, you must use your own, secret keys. See Using development keys for more information.

Building and programming using Visual Studio Code

Complete the following steps to build and program using the nRF Connect for VS Code extension:

  1. Open Visual Studio Code.

    If you installed the nRF Connect SDK using the Installing automatically steps, 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 application:

  1. Set the Thingy:91 SWD selection switch (SW2) to nRF91 or nRF52 depending on whether you want to program the nRF9160 SiP or the nRF52840 SoC component.

  2. Connect the Thingy:91 to the debug out port on a 10-pin external debug probe, for example, nRF9160 DK (Development Kit), using a 10-pin JTAG cable.

    Note

    If you are using nRF9160 DK as the debug probe, make sure that VDD_IO (SW11) is set to 1.8 V on the nRF9160 DK.

  3. Connect the external debug probe to the PC using a USB cable.

  4. Make sure that the Thingy:91 and the external debug probe are powered on.

  1. In nRF Connect for VS Code extension, click the Flash option in the Actions View.

    If you have multiple boards connected, you are prompted to pick a device at the top of the screen.

    A small notification banner appears in the bottom-right corner of Visual Studio Code to display the progress and confirm when the flash is complete.

Building and programming on the command line

Complete the command-line build setup before you start building nRF Connect SDK projects on the command line.

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

  1. Open a terminal window.

  2. Go to the specific sample or application directory. For example, the folder path is ncs/nrf/applications/asset_tracker_v2 when building the source code for the Asset Tracker v2 application on the nRF9160 SiP component and ncs/nrf/applications/connectivity_bridge when building the source code for the Connectivity bridge application on the nRF52840 SoC component.

  3. Make sure that you have the required version of the nRF Connect SDK repository by pulling the nRF Connect SDK repository, sdk-nrf on GitHub using the procedures described in Obtaining a copy of the nRF Connect SDK and Updating a copy of the nRF Connect SDK.

  4. To get the rest of the dependencies, run the west update command as follows:

    west update
    
  5. To build the sample or application code, run the west build command as follows:

    west build -b build_target

    The parameter build_target must be thingy91_nrf9160_ns if building for the nRF9160 SiP component and thingy91_nrf52840 if building for the nRF52840 SoC component.

    Note

    The parameter destination_directory_name can be used to optionally specify the destination directory in the west command. Unless a destination_directory_name is specified, the build files are automatically generated in build/zephyr/.

  1. Program the application:

  1. Set the Thingy:91 SWD selection switch (SW2) to nRF91 or nRF52 depending on whether you want to program the nRF9160 SiP or the nRF52840 SoC component.

  2. Connect the Thingy:91 to the debug out port on a 10-pin external debug probe, for example, nRF9160 DK (Development Kit), using a 10-pin JTAG cable.

    Note

    If you are using nRF9160 DK as the debug probe, make sure that VDD_IO (SW11) is set to 1.8 V on the nRF9160 DK.

  3. Connect the external debug probe to the PC using a USB cable.

  4. Make sure that the Thingy:91 and the external debug probe are powered on.

  1. Program the sample or application to the device using the following command:

    west flash
    

    The device resets and runs the programmed sample or application.