Application description

The Serial LTE Modem (SLM) application demonstrates how to use an nRF91 Series device as a stand-alone LTE modem that can be controlled by AT commands.

Overview

The nRF91 Series SiP integrates both a full LTE modem and an application MCU, enabling you to run your LTE application directly on the device.

However, if you want to run your application on a different chip and use the nRF91 Series device only as a modem, the serial LTE modem application provides you with an interface for controlling the LTE modem through AT commands.

The application accepts both the modem-specific AT commands and proprietary AT commands. The AT commands are documented in the following guides:

Requirements

The application supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160_ns

nRF9161 DK

PCA10153

nrf9161dk_nrf9161

nrf9161dk_nrf9161_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Configuration

See Configuring and building an application for information about how to permanently or temporarily change the configuration.

Configuration options

Check and configure the following configuration options for the sample:

CONFIG_SLM_CUSTOMER_VERSION - Customer version string

Version string defined by the customer after customizing the application. When defined, this version is reported with the baseline versions by the #XSLMVER AT command.

CONFIG_SLM_AT_MAX_PARAM - AT command parameter count limit

This defines the maximum number of parameters allowed in an AT command, including the command name.

CONFIG_SLM_NATIVE_TLS - Use Zephyr’s Mbed TLS for TLS connections

This option is enabled by the native TLS overlay. See Native TLS for more information.

CONFIG_SLM_NATIVE_TLS_CREDENTIAL_BUFFER_SIZE - Buffer space reserved for loading credentials

Specifies the credential buffer size available for a single sec_tag when loading credentials for Mbed TLS. The default value is 4096.

CONFIG_SLM_NATIVE_TLS_CREDENTIAL_BUFFER_COUNT - Number of buffers for loading credentials

The number of buffers available for loading sec_tag credentials for Mbed TLS. TLS client only needs the buffer when connecting, while TLS server needs the buffer as long as it running. Increase the value if you need both TLS client and server running simultaneously with different sec_tags. The default value is 1.

CONFIG_SLM_EXTERNAL_XTAL - Use external XTAL for UARTE

This option configures the application to use an external XTAL for UARTE. For the nRF9160 DK, see the nRF9160 Product Specification (section 6.19 UARTE) for more information. For the nRF9161 DK, see the nRF9161 Product Specification (section 6.19 UARTE) for more information.

CONFIG_SLM_START_SLEEP - Enter sleep on startup

This option makes an nRF91 Series device enter deep sleep after startup. It is not selected by default.

CONFIG_SLM_WAKEUP_PIN - Interface GPIO to exit from sleep or idle

This option specifies which interface GPIO to use for exiting sleep or idle mode. It is set by default as follows:

  • On the nRF9161 DK:

    • P0.8 (Button 1 on the nRF9161 DK) is used when UART_0 is used.

    • P0.31 is used when UART_1 is used.

  • On the nRF9160 DK:

    • P0.6 (Button 1 on the nRF9160 DK) is used when UART_0 is used.

    • P0.31 is used when UART_1 is used.

  • On Thingy:91, P0.26 (Multi-function button on Thingy:91) is used.

Note

This pin is used as input GPIO and configured as Active Low. By default, the application pulls up this GPIO.

CONFIG_SLM_INDICATE_PIN - Interface GPIO to indicate data available or unsolicited event notifications

This option specifies which interface GPIO to use for indicating data available or unsolicited event notifications from the modem. It is set by default as follows:

  • On the nRF9161 DK:

    • P0.00 (LED 1 on the nRF9161 DK) is used when UART_0 is selected.

    • P0.30 is used when UART_2 is selected.

  • On the nRF9160 DK:

    • P0.2 (LED 1 on the nRF9160 DK) is used when UART_0 is selected.

    • P0.30 is used when UART_2 is selected.

  • It is not defined when the target is Thingy:91.

Note

This pin is used as output GPIO and configured as Active Low. By default, the application sets this GPIO as Inactive High.

CONFIG_SLM_INDICATE_TIME - Indicate GPIO active time

This option specifies the length, in milliseconds, of the time interval during which the indicate GPIO must stay active. The default value is 100 milliseconds.

CONFIG_SLM_AUTO_CONNECT - Connect to LTE network at start-up or reset

This option enables connecting to the LTE network at start-up or reset using a defined PDN configuration. This option is enabled by the LwM2M Carrier overlay, but is otherwise disabled by default.

Note

This option requires network-specific configuration in the slm_auto_connect.h file.

Here is a sample configuration for NIDD connection in the slm_auto_connect.h file:

/* Network-specific default system mode configured by %XSYSTEMMODE (refer to AT command manual) */
0,        /* LTE support */
1,        /* NB-IoT support */
0,        /* GNSS support, also define CONFIG_MODEM_ANTENNA if not Nordic DK */
0,        /* LTE preference */
/* Network-specific default PDN configured by +CGDCONT and +CGAUTH (refer to AT command manual) */
true,     /* PDP context definition required or not */
"Non-IP", /* PDP type: "IP", "IPV6", "IPV4V6", "Non-IP" */
"",       /* Access point name */
0,        /* PDP authentication protocol: 0(None), 1(PAP), 2(CHAP) */
"",       /* PDN connection authentication username */
""        /* PDN connection authentication password */
CONFIG_SLM_CR_TERMINATION - CR termination

This option configures the application to accept AT commands ending with a carriage return.

Select this option if you want to connect to the development kit using PuTTY. See Testing and optimization for instructions.

CONFIG_SLM_LF_TERMINATION - LF termination

This option configures the application to accept AT commands ending with a line feed.

CONFIG_SLM_CR_LF_TERMINATION - CR+LF termination

This option configures the application to accept AT commands ending with a carriage return followed by a line feed.

CONFIG_SLM_TCP_POLL_TIME - Poll timeout in seconds for TCP connection

This option specifies the poll timeout for the TCP connection, in seconds.

CONFIG_SLM_SMS - SMS support in SLM

This option enables additional AT commands for using the SMS service.

CONFIG_SLM_GNSS - GNSS support in SLM

This option enables additional AT commands for using the GNSS service.

CONFIG_SLM_NRF_CLOUD - nRF Cloud support in SLM

This option enables additional AT commands for using the nRF Cloud service.

CONFIG_SLM_FTPC - FTP client support in SLM

This option enables additional AT commands for using the FTP client service.

CONFIG_SLM_TFTPC - TFTP client support in SLM

This option enables additional AT commands for using the TFTP client service.

CONFIG_SLM_MQTTC - MQTT client support in SLM

This option enables additional AT commands for using the MQTT client service.

CONFIG_SLM_MQTTC_MESSAGE_BUFFER_LEN - Size of the buffer for the MQTT library

This option specifies the maximum message size which can be transmitted or received through MQTT (excluding PUBLISH payload). The default value is 512, meaning 512 bytes for TX and RX, respectively.

CONFIG_SLM_HTTPC - HTTP client support in SLM

This option enables additional AT commands for using the HTTP client service.

CONFIG_SLM_TWI - TWI support in SLM

This option enables additional AT commands for using the TWI service.

CONFIG_SLM_UART_RX_BUF_COUNT - Receive buffers for UART.

This option defines the amount of buffers for receiving (RX) UART traffic. The default value is 3.

CONFIG_SLM_UART_RX_BUF_SIZE - Receive buffer size for UART.

This option defines the size of a single buffer for receiving (RX) UART traffic. The default value is 256.

CONFIG_SLM_UART_TX_BUF_SIZE - Send buffer size for UART.

This option defines the size of the buffer for sending (TX) UART traffic. The default value is 256.

Additional configuration

To save power, both the console and the output logs over UART_0 are disabled in this application. This information is logged using RTT instead. See Testing and optimization for instructions on how to view this information.

To switch to UART output, change the following options in the prj.conf file:

# Segger RTT
CONFIG_USE_SEGGER_RTT=n
CONFIG_RTT_CONSOLE=n
CONFIG_UART_CONSOLE=y
CONFIG_LOG_BACKEND_RTT=n
CONFIG_LOG_BACKEND_UART=y

Configuration files

The sample provides predefined configuration files for both the parent image and the child image. You can find the configuration files in the applications/serial_lte_modem directory.

The following configuration files are provided:

  • prj.conf - This configuration file contains the standard configuration for the serial LTE modem application.

  • overlay-native_tls.conf - This configuration file contains additional configuration options that are required to use Native TLS. You can include it by adding -DEXTRA_CONF_FILE=overlay-native_tls.conf to your build command. See Providing CMake options.

  • overlay-carrier.conf - Configuration file that adds nRF Connect SDK LwM2M carrier support. See Using the LwM2M carrier library for more information on how to connect to an operator’s device management platform.

  • overlay-full_fota.conf - Configuration file that adds full modem FOTA support. See FOTA AT commands for more information on how to use full modem FOTA functionality.

  • boards/nrf9160dk_nrf9160_ns.conf - Configuration file specific for the nRF9160 DK. This file is automatically merged with the prj.conf file when you build for the nrf9160dk_nrf9160_ns build target.

  • boards/nrf9161dk_nrf9161_ns.conf - Configuration file specific for the nRF9161 DK. This file is automatically merged with the prj.conf file when you build for the nrf9161dk_nrf9161_ns build target.

  • boards/thingy91_nrf9160_ns.conf - Configuration file specific for Thingy:91. This file is automatically merged with the prj.conf file when you build for the thingy91_nrf9160_ns build target.

In general, Kconfig overlays have an overlay- prefix and a .conf extension. Board-specific configuration files are named <BOARD>.conf and are located in the boards folder. DTS overlay files are named as the build target they are meant to be used with, and use the file extension .overlay. They are also placed in the boards folder. When the DTS overlay filename matches the build target, the overlay is automatically chosen and applied by the build system.

See Build and configuration system: for more information on the nRF Connect SDK configuration system.

Native TLS

By default, the secure socket (TLS) is offloaded to the modem. If you need customized TLS features that are not supported by the modem firmware, you can use native TLS instead. Native TLS uses the Mbed TLS library in Zephyr to establish secure connectivity. Currently, the SLM application can be built to use native TLS for the following services:

  • Secure socket

  • TLS Proxy client

  • TLS Proxy server

  • HTTPS client

With native TLS, the credentials are stored in the Zephyr settings storage with the AT#XCMNG command.

The configuration options that are required to enable native TLS are defined in the overlay-native_tls.conf file.

Note

Native TLS services have the following limitations:

  • TLS session resumption is currently not supported.

Sending traces over UART on an nRF91 Series DK

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Building and running

This sample can be found under applications/serial_lte_modem in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing for general information about testing and debugging in the nRF Connect SDK.

Communicating with the modem on an nRF91 Series DK

In this scenario, an nRF91 Series DK running the Serial LTE Modem application serves as the host. You can use either a PC or an external MCU as a client.

Connecting with a PC

To connect to an nRF91 Series DK with a PC:

  1. Verify that UART_0 is selected in the application. It is defined in the default configuration.

  2. Use nRF Connect Serial Terminal to connect to the development kit. See Testing and optimization for instructions. You can also use the Open Serial Terminal option of the Cellular Monitor app to open the Serial Terminal. Using the Cellular Monitor app in combination with the nRF Connect Serial Terminal shows how the modem responds to the different modem commands. You can then use this connection to send or receive AT commands over UART, and to see the log output of the development kit.

    Alternatively, you can use a terminal emulator like Termite, Teraterm, or PuTTY to establish a terminal connection to the development kit, using the default serial port connection settings.

    Note

    The default AT command terminator is a carriage return followed by a line feed (\r\n). nRF Connect Serial Terminal supports this format. If you want to use another terminal emulator, make sure that the configured AT command terminator corresponds to the line terminator of your terminal.

    When using Termite and Teraterm, configure the AT command terminator as follows:

    Termite configuration for sending AT commands through UART
    Teraterm configuration for sending AT commands through UART

    When using PuTTY, you must set the CONFIG_SLM_CR_TERMINATION SLM configuration option instead. See application configuration for more details.

Connecting with an external MCU

Note

This section does not apply to Thingy:91 as it does not have UART2.

If you run your user application on an external MCU (for example, an nRF52 Series development kit), you can control the modem on an nRF91 Series device directly from the application. See the Cellular: SLM Shell for a sample implementation of such an application.

To connect with an external MCU using UART_2, change the configuration files for the default board as follows:

  • In the nrf9161dk_nrf9161_ns.conf file:

    # Use UART_0 (when working with PC terminal)
    # unmask the following config
    #CONFIG_UART_0_NRF_HW_ASYNC_TIMER=2
    #CONFIG_UART_0_NRF_HW_ASYNC=y
    #CONFIG_SLM_WAKEUP_PIN=8
    #CONFIG_SLM_INDICATE_PIN=0
    
    # Use UART_2 (when working with external MCU)
    # unmask the following config
    CONFIG_UART_2_NRF_HW_ASYNC_TIMER=2
    CONFIG_UART_2_NRF_HW_ASYNC=y
    CONFIG_SLM_WAKEUP_PIN=31
    CONFIG_SLM_INDICATE_PIN=30
    
  • In the nrf9161dk_nrf9161_ns.overlay file:

    / {
        chosen {
                 ncs,slm-uart = &uart2;
               }
      };
    
    &uart0 {
       status = "disabled";
    };
    
    &uart2 {
       compatible = "nordic,nrf-uarte";
       current-speed = <115200>;
       status = "okay";
       hw-flow-control;
    
       pinctrl-0 = <&uart2_default_alt>;
       pinctrl-1 = <&uart2_sleep_alt>;
       pinctrl-names = "default", "sleep";
    };
    

The following table shows how to connect an nRF52 Series development kit to an nRF91 Series development kit to be able to communicate through UART:

nRF52 Series DK

nRF91 Series DK

UART TX P0.6

UART RX P0.11

UART RX P0.8

UART TX P0.10

UART CTS P0.7

UART RTS P0.12

UART RTS P0.5

UART CTS P0.13

GPIO OUT P0.27

GPIO IN P0.31

GPIO IN P0.26

GPIO OUT P0.30

Use the following UART devices:

  • nRF52840 or nRF52832 - UART0

  • nRF9160 or nRF9161 - UART2

Use the following UART configuration:

  • Hardware flow control: enabled

  • Baud rate: 115200

  • Parity bit: no

  • Operation mode: IRQ

Note

The GPIO output level on the nRF91 Series device side must be 3 V. You can set the VDD voltage with the VDD IO switch (SW9). See the VDD supply rail section in the nRF9160 DK User Guide for more information related to nRF9160 DK.

Communicating with the modem on Thingy:91

In this scenario, Thingy:91 running the Serial LTE Modem application serves as the host. You can use only a PC as a client.

Connecting with a PC

To connect to Thingy:91 with a PC, you must first program the Connectivity bridge on the nrf52840 of Thingy:91. It routes UART_0 to USB_CDC0 on Thingy:91. By enabling the option CONFIG_BRIDGE_BLE_ENABLE , you can also use SLM over Nordic UART Service (NUS).

Then follow the instructions below:

  1. Verify that UART_0 is selected in the application. It is defined in the default configuration.

  2. Use nRF Connect Serial Terminal to connect to the development kit. See Testing and optimization for instructions. You can also use the Open Serial Terminal option of the Cellular Monitor app to open the Serial Terminal. Using the Cellular Monitor app in combination with the nRF Connect Serial Terminal shows how the modem responds to the different modem commands. You can then use this connection to send or receive AT commands over UART, and to see the log output of the development kit.

    Alternatively, you can use a terminal emulator like Termite, Teraterm, or PuTTY to establish a terminal connection to the development kit, using the default serial port connection settings.

    Note

    The default AT command terminator is a carriage return followed by a line feed (\r\n). nRF Connect Serial Terminal supports this format. If you want to use another terminal emulator, make sure that the configured AT command terminator corresponds to the line terminator of your terminal.

    When using Termite and Teraterm, configure the AT command terminator as follows:

    Termite configuration for sending AT commands through UART
    Teraterm configuration for sending AT commands through UART

    When using PuTTY, you must set the CONFIG_SLM_CR_TERMINATION SLM configuration option instead. See application configuration for more details.

You can also test the i2c sensor on Thingy:91 using TWI AT commands. See TWI AT commands for more details.

Testing

The following testing instructions focus on testing the application with a PC client. If you have an nRF52 Series DK running a client application, you can also use this DK for testing the different scenarios.

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with nRF Connect Serial Terminal. You can also use the Open Serial Terminal option of the Cellular Monitor app to open the Serial Terminal. If you want to use a different terminal emulator, see Connecting with a PC.

  3. Reset the kit.

  4. Observe that the development kit sends a Ready\r\n message on UART.

  5. Send AT commands and observe the responses from the development kit.

    See Testing scenarios for typical test cases.

Using the LwM2M carrier library

The application supports the nRF Connect SDK LwM2M carrier library that you can use to connect to the operator’s device management platform. See the library’s documentation for more information and configuration options.

To enable the LwM2M carrier library, add the parameter -DOVERLAY_CONFIG=overlay-carrier.conf to your build command.

The CA root certificates that are needed for modem FOTA are not provisioned in the Serial LTE Modem application. You can flash the Cellular: LwM2M carrier sample to write the certificates to modem before flashing the Serial LTE Modem application, or use the Cellular: AT Client sample as explained in preparing the Cellular: LwM2M Client sample for production. It is also possible to modify the Serial LTE Modem application project itself to include the certificate provisioning, as demonstrated in the Cellular: LwM2M carrier sample.

int lwm2m_carrier_event_handler(const lwm2m_carrier_event_t *event)
{
        switch (event->type) {
        case LWM2M_CARRIER_EVENT_INIT:
                carrier_cert_provision();
        ...

The certificate provisioning can also be done directly in the Serial LTE Modem application by using the same AT commands as described for the Cellular: AT Client sample.

When the LwM2M carrier library is in use, by default the application will auto-connect to the network on startup. This behavior can be changed by disabling the CONFIG_SLM_AUTO_CONNECT option.

Dependencies

This application uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib libraries:

In addition, it uses the following secure firmware component: