Developing with nRF9160 DK

The nRF9160 DK is a hardware development platform used to design and develop application firmware on the nRF9160 LTE Cat-M1 and Cat-NB1 System in Package (SiP).

See the nRF9160 DK Hardware guide for detailed information about the nRF9160 DK hardware. To get started with the nRF9160 DK, follow the steps in the Getting started with nRF9160 DK section. 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.

Board controller

The nRF9160 DK contains an nRF52840 SoC that is used to route some of the nRF9160 SiP pins to different components on the DK, such as LEDs and buttons, and to specific pins of the nRF52840 SoC itself. For a complete list of all the routing options available, see the nRF9160 DK board control section in the nRF9160 DK User Guide.

The nRF52840 SoC on the DK comes preprogrammed with a firmware. If you need to restore the original firmware at some point, download the nRF9160 DK board controller firmware from the nRF9160 DK downloads page. To program the HEX file, use nrfjprog (which is part of the nRF Command Line Tools).

If you want to route some pins differently from what is done in the preprogrammed firmware, program the Hello World sample instead of the preprogrammed firmware. Build the sample (located under ncs/zephyr/samples/hello_world) for the nrf9160dk_nrf52840 board. To change the routing options, enable or disable the corresponding devicetree nodes for that board as needed. See Board controller firmware for detailed information.

Updating the nRF Cloud certificate

When you wish to use nRF Cloud’s REST Application Programming Interface (API), the DK requires a valid security certificate. This means that you need to update the certificate stored on the DK. To do so, you need to download a new certificate and then provision it to your DK.

Downloading the nRF Cloud certificate

Complete the following steps to download the nRF Cloud certificate for your nRF9160 DK:

  1. Go to nRF Cloud and sign in.

  2. Click Device Management in the left pane and select Provision Devices.

    nRF Cloud - Provision Devices

    nRF Cloud - Provision Devices

  3. In the page that opens up, click the gear icon near the upper right corner and select Create JITP Certificates.

    nRF Cloud - Gear icon in Provision Devices

    nRF Cloud - Gear icon in Provision Devices

    The Create JITP Certificates dialog box opens.

    nRF Cloud - Create JITP Certificates dialog box

    nRF Cloud - Create JITP Certificates dialog box

  4. Enter the following information:

    • Device ID: the device ID is composed of nrf- and the 15-digit International Mobile (Station) Equipment Identity (IMEI) number that is printed on the label of your nRF9160 DK. For example, nrf-123456789012345.

    • Ownership code: the ownership code is the PIN or the hardware ID of your DK, and it is found on the label of your nRF9160 DK.

      If the label contains a PIN in addition to the IMEI number, enter this pin. If it does not contain a PIN, enter the Hardware ID (HWID) HEX code, with or without colons. For example, AA:BB:CC:DD:EE:FF or AABBCCDDEEFF.

      Note

      The ownership code serves as a password and proves that you own the specific nRF9160 DK. Therefore, do not share it with anyone.

  5. Click Download Certificate and save the .cert.json file to a folder of your choice.

    Note

    The certificate contains all the information that is needed to connect your nRF9160 DK to nRF Cloud. Therefore, do not share it with anyone.

Provisioning the nRF Cloud certificate

After downloading the certificate, you must provision it to your nRF9160 DK.

Note

The application firmware on the nRF9160 DK must support long AT commands up to 3 kB to provision the certificate. If you have updated the application firmware using the instructions in either the Getting started documentation or the Building and programming section, this requirement is fulfilled.

Complete the following steps to provision the certificate:

  1. Start nRF Connect for Desktop and install the Cellular Monitor app.

  2. Open the Cellular Monitor app.

  3. Make sure that the DK is programmed as mentioned in the Getting started using Quick Start section.

  4. Connect the DK to the computer with a micro-USB cable, and turn it on.

  5. Click Select device and select the DK from the drop-down list.

    Cellular Monitor - Select device

    Cellular Monitor - Select device

    The drop-down text changes to the type of the selected device, with the SEGGER ID below the name.

  6. Click the Open Serial Terminal option of the Cellular Monitor app to open the Serial Terminal.

    Cellular Monitor - Open Serial Terminal

    Cellular Monitor - Open Serial Terminal

  7. Enter AT+CFUN=4 in the text field for AT commands and click Send. This AT command puts the modem to offline state.

  8. Enter AT+CFUN? in the text field for AT commands and click Send. This AT command returns the state of the modem.

    The command must return +CFUN: 4, which indicates that the modem is in offline state. If it returns a different value, repeat the previous step.

  9. Open the Cellular Monitor app.

  10. Click CERTIFICATE MANAGER in the navigation bar to switch to the certificate manager view.

    Cellular Monitor - Certificate Manager

    Cellular Monitor - Certificate Manager

  11. Click Load from JSON and select the *.cert.json file that you downloaded from nRF Cloud. Alternatively, you can drag and drop the file onto the GUI.

    Cellular Monitor - Load from JSON

    Cellular Monitor - Load from JSON

  12. Ensure that the Security tag is set to 16842753, which is the security tag for nRF Cloud credentials.

  13. Click Update certificate.

    The log message “Certificate update completed” indicates that the certificate was provisioned successfully. If you encounter any errors, switch to the terminal view and check the output of the AT commands that were sent to the nRF9160 DK modem.

    Note

    If you have connected your nRF9160 DK to nRF Cloud before, you must delete the device there after provisioning the certificate. Open the entry for your device from the Devices view, then click the gear icon to the right of the device’s name, and select Delete Device. Then, add the nRF9160 DK again as described in Connecting the nRF9160 DK to nRF Cloud

Build targets

Make sure to select a suitable build target when building your application.

In Zephyr, the firmware for the application core of nRF9160 DK is divided into two different build targets:

  • nrf9160dk_nrf9160 for build targets that have Cortex-M Security Extensions (CMSE) disabled.

  • nrf9160dk_nrf9160_ns for build targets that have CMSE enabled and have the Secure Processing Environment (SPE) firmware alongside the Non-Secure Processing Environment (NSPE) firmware.

For information about CMSE and the difference between the two environments, see Processing environments.

Updating the DK firmware using Programmer

Download and extract the latest application and modem firmware from the nRF9160 DK 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 image for the Asset Tracker v2 application as an example. 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 Building and programming an application for details on building a firmware sample application.

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

Complete the following steps to program applications using the Programmer app from nRF Connect for Desktop.

Updating the modem firmware

To update the modem firmware, complete the following steps. If you experience any problems during the process, press Ctrl+R (command+R on macOS) to restart the Programmer app and try again.

  1. Open the Programmer app.

  2. Make sure the PROG/DEBUG SW10 switch on the nRF9160 DK is set to nRF91. On DK v0.9.0 and earlier, this is the SW5 switch.

  3. Connect the nRF9160 DK to the computer with a micro-USB cable, and then turn the DK on.

  4. Click SELECT DEVICE and select the DK from the drop-down list.

    Programmer - Select device

    Programmer - Select device

    If the DK is not visible, press Ctrl+R in Windows or command+R in macOS to restart the Programmer application.

    The drop-down text changes to the type of the selected device, with its SEGGER ID below the name. The Device memory layout section also changes its name to the device name, and indicates that the device is connected. If the Auto read memory option is selected in the DEVICE section of the side panel, the memory layout will update. If it is not selected and you wish to see the memory layout, click Read in the DEVICE section of the side panel.

  5. Click Add file in the FILE section, and select Browse.

    Programmer - Add file

    Programmer - Add file

  6. Navigate to where you extracted the firmware, and select the mfw_nrf9160_<version-number>.zip file.

  7. Click Write in the DEVICE section of the side panel.

    Programmer - Write

    Programmer - Write

    The Modem DFU window appears.

    Modem DFU window

    The Modem DFU window

  8. Click the Write button in the Modem DFU window to update the firmware. Do not unplug or turn off the device during this process.

When the update is complete, you see a success message. If you update the application firmware now, you can go directly to Step 5 of Updating the application firmware.

Note

If you experience problems updating the modem firmware, click Erase all in the DEVICE section of the side panel and try updating again.

Updating the application firmware

To update the application firmware using the Programmer app, complete the following steps. If you experience any problems during the process, press Ctrl+R (command+R in macOS) to restart the Programmer app and try again.

  1. Open the Programmer app.

  2. Make sure the PROG/DEBUG SW10 switch (SW5 on DK v0.9.0 and earlier) on the nRF9160 DK is set to nRF91 or nRF52 as appropriate for the application or sample you are programming. See the Device programming section in the nRF9160 DK User Guide for more information.

    For the Asset Tracker v2 application, the switch must be set to nRF91.

  3. Connect the nRF9160 DK to the computer with a micro-USB cable, and then turn the DK on.

  4. Click SELECT DEVICE and select the DK from the drop-down list.

    Programmer - Select device

    Programmer - Select device

    If the DK is not visible, press Ctrl+R in Windows (command+R in macOS) to restart the Programmer application.

    The drop-down text changes to the type of the selected device, with its SEGGER ID below the name. The Device memory layout section also changes its name to the device name, and indicates that the device is connected. If the Auto read memory option is selected in the DEVICE section, the memory layout will update. If it is not selected and you wish to see the memory layout, click Read in the DEVICE section.

  5. Click Add file in the FILE section, and select Browse.

    Programmer - Add file

    Programmer - Add file

  6. Navigate to where you extracted the firmware, and then to the img_app_bl folder there.

  7. Select the .hex file for the application you are programming.

    For Asset Tracker v2, select the nrf9160dk_asset_tracker_v2_<version-number>.hex HEX file.

    For NB-IoT, there is a second variant of the Asset Tracker v2 firmware in the nrf9160dk_asset_tracker_v2_nbiot_legacy_pco_<version-number>.hex file. Only use this legacy variant if your network does not support ePCO.

  8. Click the Erase & write button in the DEVICE section to program the DK. Do not unplug or turn off the DK during this process.

    Programmer - Erase & write

    Programmer - Erase & write

Building and programming

You can program applications and samples on the nRF9160 DK after obtaining the corresponding firmware images.

Note

When you update the application firmware on an nRF9160 DK, make sure the modem firmware and application firmware are compatible versions.

To program applications using the Programmer app from nRF Connect for Desktop, follow the instructions in Updating the application firmware.

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 the nRF Connect SDK 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 SW10 switch (marked PROG/DEBUG) in the nRF91 position to program the nRF9160 application. In nRF9160 DK v0.9.0 and earlier, the switch is called SW5.

  2. Connect the nRF9160 DK to your PC using a USB cable.

  3. Power on the nRF9160 DK.

  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 flashing 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 DK.

  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 nrf9160dk_nrf9160_ns when building the application code for the nRF9160 DK.

    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 SW10 switch (marked PROG/DEBUG) in the nRF91 position to program the nRF9160 application. In nRF9160 DK v0.9.0 and earlier, the switch is called SW5.

  2. Connect the nRF9160 DK to your PC using a USB cable.

  3. Power on the nRF9160 DK.

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

    west flash
    

    Note

    When programming with the Asset Tracker v2 application, use the west flash --erase command. The application has secure boot enabled by default that includes data in the One-Time Programmable region (OTP). This means that everything must be erased before flashing.

    The device resets and runs the programmed sample or application.

nRF91 modem tracing with UART backend using snippets

Snippets are tailored for tracing on the nRF91 Series devices but can work with other boards as well. It enables the CONFIG_NRF_MODEM_LIB_TRACE Kconfig option and chooses the Zephyr UART driver for the backend, with the necessary Kconfig options. The snippet also enables the UART1 peripheral with a baud rate of 1 Mbd and hardware flow control enabled. If this configuration does not match your requirements, you can add a snippet or Kconfig and devicetree overlays to your application with the desired setup. To enable modem tracing with the UART trace backend on a nRF91 device, add the nrf91-modem-trace-uart snippet to the build configuration. This can be done in one of the following ways:

With west

To add the modem trace UART snippet when building an application with west, use the following command:

west build --board <your_board> -S nrf91-modem-trace-uart

With CMake

To add the modem trace UART snippet when building an application with CMake, add the following command to the CMake arguments:

-DSNIPPET="nrf91-modem-trace-uart" [...]

To build with the nRF Connect for VS Code extension, specify -DSNIPPET="nrf91-modem-trace-uart" [...] in the Extra CMake arguments field.

See Providing CMake options for more details.

Shared UART for application and TF-M logging

If you want to activate TF-M logging while having modem traces enabled, it can be useful to direct the TF-M logs to the UART (UART0) used by the application. To activate both modem traces and TF-M logs, use the following command:

west build --board build target -S nrf91-modem-trace-uart -S tfm-enable-share-uart

Testing the cellular connection with the AT Client sample

The Cellular: AT Client sample enables you to send AT commands to the modem of your nRF9160 DK to test and monitor the cellular connection. You can use it to troubleshoot and debug any connection problems.

Complete the following steps to test the cellular connection using the AT Client sample:

  1. Follow the steps in Updating the application firmware to program the sample to the DK. When selecting the HEX file, select nrf9160dk_at_client_<version-number>.hex instead of the one for Asset Tracker v2.

  2. Test the AT Client sample as described in the Testing section of the Cellular: AT Client documentation.

Board revisions

nRF9160 DK v0.13.0 and earlier has following hardware features missing that are available on later versions of the DK:

  • External flash memory

  • I/O expander

To build without these features, specify the board revision when building your application.

Note

If you do not specify a board revision, the firmware is built for the default revision (v0.14.0).

To specify the board revision, append it to the board argument when building. The board revision is printed on the label of your DK, just below the PCA number. For example, when building a non-secure application for nRF9160 DK v0.9.0, use nrf9160dk_nrf9106_ns@0.9.0 as build target.

See Building for a board revision and Additional hardware in v0.14.0+ for more information.

External flash memory

The nRF9160 DK version 0.14.0 and later versions contain an 8 MB external flash (MX25R6435F). The external flash can be used to store data that does not fit on the internal flash. To free up GPIO when the external flash is not needed, the nRF9160 DK board controller (nRF52840 SoC) controls a switch to enable or disable routing between the external flash and the nRF9160 SIP.

See nRF9160 DK board controller and External memory sections in the nRF9160 DK user guides for more details.

Programming the board controller firmware

To use the external flash memory on the nRF9160 DK v0.14.0 or later versions, the board controller firmware must be of version v2.0.1. This is the factory firmware version. If you need to program the board controller firmware again, complete the following steps:

  1. Download the nRF9160 DK board controller firmware from the nRF9160 DK downloads page.

  2. Make sure the PROG/DEBUG SW10 switch on the nRF9160 DK is set to nRF52.

  3. Program the board controller firmware (nrf9160_dk_board_controller_fw_2.0.1.hex) using the Programmer app in nRF Connect for Desktop. By default, this enables pin routing to external flash.

Adding the configuration and devicetree option

To use external flash, the application also needs to enable configuration and devicetree options.

Enable the following Kconfig options by setting it to y in your project configuration:

To automatically include the devicetree overlay with the external flash, specify the board revision parameter when Building and programming an application. The board revision is printed on the label of your DK, just below the PCA number.

Then add the following relevant devicetree blocks to the application`s devicetree overlay file, depending on your application`s needs:

/* Enable the external flash device (required) */
&mx25r64 {
         status = "okay";
};

/* Configure partition manager to use mx25r64 as the external flash device */
/ {
    chosen {
        nordic,pm-ext-flash = &mx25r64;
    };
};

/* Enable high performance mode to increase write/erase performance */
&mx25r64 {
    mxicy,mx25r-power-mode = "high-performance";
};

For more information about devicetree overlays, see Use devicetree overlays.

Using Partition Manager

If your application was built using the nRF Connect SDK, you must define partitions using Partition Manager. The built-in partition definitions can be found in the nrf/subsys/partition_manager folder, and the file names start with pm.yml. The files which have external_flash as their region will have support for storing partitions in the external flash. You can also find the configuration option required to place the partition in the external flash region in those files. For example, the pm.yml.pgps file has an option (CONFIG_PM_PARTITION_REGION_PGPS_EXTERNAL) to place the PGPS partition in external flash:

#ifdef CONFIG_PM_PARTITION_REGION_PGPS_EXTERNAL
  region: external_flash
#else
  inside: [nonsecure_storage]
#endif
  size: CONFIG_NRF_CLOUD_PGPS_PARTITION_SIZE

It is also possible to change the size of the partition with CONFIG_NRF_CLOUD_PGPS_PARTITION_SIZE.

Available drivers, libraries, and samples

See the Drivers, Libraries, and samples sections and the respective repository folders for up-to-date information.