.. _ug_nrf9160: Developing with nRF9160 DK ########################## .. contents:: :local: :depth: 2 The nRF9160 DK is a hardware development platform used to design and develop application firmware on the nRF9160 LTE Cat-M1 and Cat-NB1 :term:`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 :ref:`ug_nrf9160_gs` section. If you are not familiar with the |NCS|, see :ref:`installation` and :ref:`configuration_and_build` documentation to install the |NCS| and learn more about its development environment. .. _nrf9160_ug_intro: 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`_. Make sure to select the correct controller before you program the application to your development kit. 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 :ref:`zephyr: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 :ref:`zephyr:nrf9160dk_board_controller_firmware` for detailed information. .. _nrf9160_ug_updating_cloud_certificate: Updating the nRF Cloud certificate ********************************** .. |DK| replace:: nRF9160 DK .. dk_update_cloud_cer_start 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. .. dk_update_cloud_cer_end .. _downloading_cloud_certificate_nRF9160: Downloading the nRF Cloud certificate for the |DK| ================================================== .. dk_cloud_cer_download_start To download the nRF Cloud certificate for your |DK|, complete the following steps. Make sure you are logged in to the `nRF Cloud`_ portal. 1. Click :guilabel:`Devices` under :guilabel:`Device Management` in the navigation pane on the left. .. figure:: /gsg_guides/images/nrfcloud_devices.png :alt: nRF Cloud - Devices nRF Cloud - Devices #. Click :guilabel:`Add Devices`. .. figure:: /gsg_guides/images/nrfcloud_add_devices.png :alt: nRF Cloud - Add Devices nRF Cloud - Add Devices The **Select Device Type** pop-up opens. #. Click :guilabel:`LTE Device` in the **Select Device Type** pop-up. .. figure:: /gsg_guides/images/nrfcloud_selectdevicetype.png :alt: nRF Cloud - Select Device Type nRF Cloud - Select Device Type #. Click **Create JITP Certificates** at the bottom of the page. The **Create JITP Certificates** dialog box opens. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/nrfcloud_jitpcertificates.png :alt: nRF Cloud - Create JITP Certificates dialog box nRF Cloud - Create JITP Certificates dialog box #. Enter the following information: * **Device ID:** the device ID is composed of *nrf-* and the 15-digit :term:`International Mobile (Station) Equipment Identity (IMEI)` number that is printed on the label of your |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 |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 |DK|. Therefore, do not share it with anyone. #. Click :guilabel:`Download Certificate` and save the :file:`.cert.json` file to a folder of your choice. .. note:: The certificate contains all the information that is needed to connect your |DK| to nRF Cloud. Therefore, do not share it with anyone. #. Close the **Create JITP Certificates** dialog box. .. dk_cloud_cer_download_end .. _provisioning_cloud_certificate: 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 :ref:`nrf9160_gs_updating_fw` documentation or the :ref:`nrf9160_ug_updating_fw_programmer` or :ref:`build_pgm_nrf9160` sections, this requirement is fulfilled. Complete the following steps to provision the certificate: 1. Start nRF Connect for Desktop and install the `Cellular Monitor`_ app. #. Open the Cellular Monitor app. #. Connect the DK to the computer with a micro-USB cable, and turn it on. #. Click :guilabel:`Select device` and select the DK from the drop-down list. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/cellularmonitor_selectdevice1_nrf9160.png :alt: 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. #. Click the :guilabel:`Open Serial Terminal` option of the `Cellular Monitor`_ app to open the Serial Terminal. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/cellularmonitor_open_serial_terminal.png :alt: Cellular Monitor - Open Serial Terminal Cellular Monitor - Open Serial Terminal #. Enter ``AT+CFUN=4`` in the text field for AT commands and click :guilabel:`Send`. This AT command puts the modem to offline state. #. Enter ``AT+CFUN?`` in the text field for AT commands and click :guilabel:`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. #. Open the Cellular Monitor app. #. Click :guilabel:`CERTIFICATE MANAGER` in the navigation bar to switch to the certificate manager view. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/cellularmonitor_navigationcertificatemanager.png :alt: Cellular Monitor - Certificate Manager Cellular Monitor - Certificate Manager #. Click :guilabel:`Load from JSON` and select the :file:`*.cert.json` file that you downloaded from nRF Cloud. Alternatively, you can drag and drop the file onto the GUI. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/cellularmonitor_loadjson.png :alt: Cellular Monitor - Load from JSON Cellular Monitor - Load from JSON #. Ensure that the **Security tag** is set to ``16842753``, which is the security tag for nRF Cloud credentials. #. Click :guilabel:`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 :guilabel:`Delete Device`. Then, add the nRF9160 DK again as described in :ref:`nrf9160_gs_connecting_dk_to_cloud` Build targets ************* Make sure to select a suitable build target when building your application. In Zephyr, the firmware for the application core of :ref:`zephyr:nrf9160dk_nrf9160` 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 :ref:`app_boards_spe_nspe`. .. _nrf9160_ug_updating_fw_programmer: Updating the DK firmware using Programmer ***************************************** .. |sim_card| replace:: For the iBasis SIM card provided with the nRF9160 DK, see `iBasis IoT network coverage`_. .. |firmware_filename| replace:: :file:`mfw_nrf9160_` Download and extract the latest application and modem firmware from the `nRF9160 DK Downloads`_ page. .. dk_update_firware_start The downloaded ZIP archive contains the following firmware: Application firmware The :file:`img_app_bl` folder contains full firmware images for different applications. The guides in this section use the image for the :ref:`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. |sim_card| Application firmware for Device Firmware Update (DFU) The images in the :file:`img_fota_dfu_bin` and :file:`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 |firmware_filename| 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 :ref:`nrf_cloud_multi_service` sample. See :ref:`building` for details on building a firmware sample application. The :file:`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`_. .. dk_update_firware_end .. _nrf9160_updating_fw_modem: .. _nrf9160_gs_updating_fw_modem: 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. #. 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. #. Connect the nRF9160 DK to the computer with a micro-USB cable, and then turn the DK on. #. Click :guilabel:`SELECT DEVICE` and select the DK from the drop-down list. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_selectdevice_nrf9160.png :alt: 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 :guilabel:`Auto read memory` option is selected in the **JLINK SETTINGS** section of the side panel, the memory layout will update. If it is not selected and you wish to see the memory layout, click :guilabel:`Read` in the **DEVICE** section of the side panel. #. Click :guilabel:`Add file` in the **FILE** section, and select :guilabel:`Browse`. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_addfile_nrf9160dk.png :alt: Programmer - Add file Programmer - Add file #. Navigate to where you extracted the firmware, and select the :file:`mfw_nrf9160_.zip` file. #. Click :guilabel:`Write` in the **DEVICE** section of the side panel. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_write_nrf9160dk.png :alt: Programmer - Write Programmer - Write The **Modem DFU** window appears. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmerapp_modemdfu.png :alt: Modem DFU window The Modem DFU window #. Click the :guilabel:`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 :ref:`nrf9160_updating_fw_application`. .. note:: If you experience problems updating the modem firmware, click :guilabel:`Erase all` in the **DEVICE** section of the side panel and try updating again. .. _nrf9160_updating_fw_application: .. _nrf9160_gs_updating_fw_application: 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. #. 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 :ref:`asset_tracker_v2` application, the switch must be set to **nRF91**. #. Connect the nRF9160 DK to the computer with a micro-USB cable, and then turn the DK on. #. Click :guilabel:`SELECT DEVICE` and select the DK from the drop-down list. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_selectdevice_nrf9160.png :alt: 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 :guilabel:`Auto read memory` option is selected in the **JLINK SETTINGS** section, the memory layout will update. If it is not selected and you wish to see the memory layout, click :guilabel:`Read` in the **DEVICE** section. #. Click :guilabel:`Add file` in the **FILE** section, and select :guilabel:`Browse`. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_addfile_nrf9160dk.png :alt: Programmer - Add file Programmer - Add file #. Navigate to where you extracted the firmware, and then to the :file:`img_app_bl` folder there. #. Select the :file:`.hex` file for the application you are programming. For Asset Tracker v2, select the :file:`nrf9160dk_asset_tracker_v2_.hex` HEX file. For NB-IoT, there is a second variant of the Asset Tracker v2 firmware in the :file:`nrf9160dk_asset_tracker_v2_nbiot_legacy_pco_.hex` file. Only use this legacy variant if your network does not support ePCO. #. Click the :guilabel:`Erase & write` button in the **DEVICE** section to program the DK. Do not unplug or turn off the DK during this process. .. figure:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/images/programmer_erasewrite_nrf9160dk.png :alt: Programmer - Erase & write Programmer - Erase & write .. _build_pgm_nrf9160: 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 that 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 :ref:`nrf9160_updating_fw_application`. .. _build_pgm_nrf9160_vsc: Building and programming using |VSC| ==================================== Complete the following steps to build and program using the |nRFVSC|: .. |sample_path_vsc| replace:: :file:`ncs/nrf/applications/asset_tracker_v2` .. |vsc_sample_board_target_line| replace:: you must use the build target ``nrf9160dk/nrf9160/ns`` when building the application code for the nRF9160 DK .. include:: ../../../../../../nrf/includes/vsc_build_and_run.txt 3. Program the application: .. prog_nrf9160_start .. a. 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**. #. Connect the nRF9160 DK to your PC using a USB cable. #. Power on the nRF9160 DK. .. prog_nrf9160_end .. d. In |nRFVSC|, click the :guilabel:`Flash` option in the :guilabel:`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 |VSC| to display the progress and confirm when the flashing is complete. .. _build_pgm_nrf9160_cmdline: Building and programming on the command line ============================================ .. |cmd_folder_path| replace:: on the nRF9160 DK .. |cmd_build_target| replace:: ``nrf9160dk/nrf9160/ns`` when building the application code for the nRF9160 DK .. include:: ../../../../../../nrf/includes/cmd_build_and_run.txt 6. Program the application: .. include:: ../../../../../../nrf/device_guides/working_with_nrf/nrf91/nrf9160.rst :start-after: prog_nrf9160_start :end-before: prog_nrf9160_end .. d. Program the sample or application to the device using the following command: .. code-block:: console west flash .. note:: When programming with the :ref:`asset_tracker_v2` application, use the ``west flash --erase`` command. The application has secure boot enabled by default that includes data in the :ref:`One-Time Programmable region (OTP)`. This means that everything must be erased before flashing. The device resets and runs the programmed sample or application. .. _nrf9160_gs_testing_cellular: Testing the cellular connection with the AT Client sample ********************************************************* .. |firmware_update| replace:: :ref:`nrf9160_gs_updating_fw_application` .. |firmware_file| replace:: :file:`nrf9160dk_at_client_.hex` .. at_client_test_start The :ref:`at_client_sample` sample enables you to send AT commands to the modem of your |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 |firmware_update| to program the sample to the DK. When selecting the HEX file, select |firmware_file| instead of the one for Asset Tracker v2. #. Test the AT Client sample as described in the Testing section of the :ref:`at_client_sample` documentation. .. at_client_test_end .. _nrf9160_board_revisions: 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@0.9.0/nrf9160/ns`` as build target. See :ref:`zephyr:application_board_version` and :ref:`zephyr:nrf9160dk_additional_hardware` for more information. .. _nrf9160_external_flash: 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: #. Download the nRF9160 DK board controller firmware from the `nRF9160 DK downloads`_ page. #. Make sure the **PROG/DEBUG SW10** switch on the nRF9160 DK is set to **nRF52**. #. Program the board controller firmware (:file:`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: * :kconfig:option:`CONFIG_FLASH` * :kconfig:option:`CONFIG_FLASH_MAP` * :kconfig:option:`CONFIG_SPI` * :kconfig:option:`CONFIG_SPI_NOR` * :kconfig:option:`CONFIG_SPI_NOR_SFDP_DEVICETREE` * :kconfig:option:`CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK` To automatically include the devicetree overlay with the external flash, specify the board revision parameter when :ref:`building`. 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: .. code-block:: devicetree /* 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 :ref:`zephyr:use-dt-overlays`. Using Partition Manager ======================= If your application was built using the |NCS|, you must define partitions using :ref:`partition_manager`. The built-in partition definitions can be found in the :file:`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 :file:`pm.yml.pgps` file has an option (:kconfig:option:`CONFIG_PM_PARTITION_REGION_PGPS_EXTERNAL`) to place the P-GPS partition in external flash: .. code-block:: c #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 :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_PARTITION_SIZE`. Available drivers, libraries, and samples ***************************************** See the :ref:`drivers`, :ref:`libraries`, and :ref:`samples ` sections and the respective repository folders for up-to-date information.