Building and running

The Serial Modem application can be found under app in the Serial Modem folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Communicating with the modem on an nRF91 Series DK 

In this scenario, an nRF91 Series DK running the Serial 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:

Verify that UART_0 is selected in the application. It is defined in the default configuration.
Use the Serial Terminal app 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 app. Using the Cellular Monitor app in combination with the Serial Terminal app 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.

Instead of using the Serial Terminal app, you can use 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 (\r). The Serial Terminal app, PuTTY and many terminal emulators support this format by default. However, make sure that the configured AT command terminator corresponds to the line terminator of your terminal. See Configuration options for more details on AT command terminator choices.

Connecting with an external MCU 

Note

This section does not apply to Thingy:91 X.

If you run your user application on an external MCU (for example, an nRF54 Series development kit), you can control the Serial Modem application on an nRF91 Series device directly from the application. See the AT Client Shell sample for a sample implementation of such an application.

To connect with an external MCU using UART_2, include the overlay-external-mcu.overlay devicetree overlay in your build. This overlay configures the UART_2 pins, DTR pin, and RI pin for the nRF9151 DK.

If you use a different setup, you can customize the overlay-external-mcu.overlay file to match your hardware configuration in (for example) the following ways:

Change the highlighted UART baud rate or DTR and RI pins:

&uart2 {
   compatible = "nordic,nrf-uarte";
   current-speed = <**115200**>;
   hw-flow-control;
   status = "okay";

   dtr_uart2: dtr-uart {
      compatible = "nordic,dtr-uart";
      dtr-gpios = <**&gpio0 31** (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
      ri-gpios = <**&gpio0 30** GPIO_ACTIVE_LOW>;
      status = "okay";
   };
   pinctrl-0 = <&uart2_default_alt>;
   pinctrl-1 = <&uart2_sleep_alt>;
   pinctrl-names = "default", "sleep";
};

Change the highlighted UART pins:

&pinctrl {
   uart2_default_alt: uart2_default_alt {
      group1 {
         psels = <NRF_PSEL(UART_RX, **0, 3**)>,
                 <NRF_PSEL(UART_CTS, **0, 7**)>;
         bias-pull-up;
      };
      group2 {
         psels = <NRF_PSEL(UART_TX, **0, 2**)>,
                 <NRF_PSEL(UART_RTS, **0, 6**)>;
      };
   };

   uart2_sleep_alt: uart2_sleep_alt {
      group1 {
         psels = <NRF_PSEL(UART_TX, **0, 2**)>,
                 <NRF_PSEL(UART_RX, **0, 3**)>,
                 <NRF_PSEL(UART_RTS, **0, 6**)>,
                 <NRF_PSEL(UART_CTS, **0, 7**)>;
         low-power-enable;
      };
   };
};

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

nRF54L15 DK	nRF91 Series DK
UART TX P0.00	UART RX P0.03
UART RX P0.01	UART TX P0.02
UART CTS P0.03	UART RTS P0.06
UART RTS P0.02	UART CTS P0.07
DTR OUT P1.11	DTR IN P0.31
RI IN P1.12	RI OUT P0.30
GPIO GND	GPIO GND

Note

You must disable the VCOM0 on the nRF54L15 DK to release the UART GPIO pins to use it with the AT Client Shell sample.

For nRF54L15 DK, you can use the Board Configurator app to disable the Connect port VCOM0 setting.

Note

The GPIO output levels on the nRF91 Series device and nRF54L15 DK must be the same.

You can set the VDD voltages for both devices with the Board Configurator app.

Use the following UART devices:

nRF54 Series DK - UART30
nRF91 Series DK - UART2

The UART configuration must match on both sides. By default the Serial Modem application and AT Client Shell sample use the following settings:

Hardware flow control: enabled
Baud rate: 115200
Parity bit: no

Communicating with the modem on Thingy:91 X 

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

Connecting with a PC 

The nRF5340 SoC of Thingy:91 X is pre-programmed with the Connectivity bridge application. To update the Connectivity bridge application, see the Updating the Thingy:91 X firmware using nRF Util documentation. The Connectivity bridge application routes UART_0 to USB_CDC0 on Thingy:91 X. By enabling the CONFIG_BRIDGE_BLE_ENABLE Kconfig option in the Connectivity bridge application, you can also use Serial Modem over Nordic UART Service (NUS).

To connect to a Thingy:91 X with a PC:

Verify that UART_0 is selected in the application. It is defined in the default configuration.
Use the Serial Terminal app 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 app. Using the Cellular Monitor app in combination with the Serial Terminal app 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.

Instead of using the Serial Terminal app, you can use 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 (\r). The Serial Terminal app, PuTTY and many terminal emulators support this format by default. However, make sure that the configured AT command terminator corresponds to the line terminator of your terminal. See Configuration options for more details on AT command terminator choices.

Testing 

The following testing instructions focus on testing the application with a PC client.

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

Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.
Connect to the kit with the Serial Terminal app. You can also use the Open Serial Terminal option of the Cellular Monitor app to open the Serial Terminal app. If you want to use a different terminal emulator, see Connecting with a PC.
Reset the kit.
Observe that the development kit sends a Ready\r\n message on UART.
Send AT commands and observe the responses from the development kit.

See Testing scenarios for typical test cases.

Note

If the initialization of Serial Modem fails, the application sends an INIT ERROR\r\n message on UART if it has managed to enable UART. See the logs for more information about the error. The logs are written to RTT by default.

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 following parameters to your build command:

-DEXTRA_CONF_FILE=overlay-carrier.conf
-DEXTRA_DTC_OVERLAY_FILE=overlay-carrier.overlay

The CA root certificates that are needed for modem FOTA are not provisioned in the Serial Modem application. You can flash the Cellular: LwM2M carrier sample to write the certificates to modem before flashing the Serial 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 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 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_SM_AUTO_CONNECT option.

Building without the immutable B0 bootloader 

By default, the Serial Modem application uses an immutable bootloader B0 (NSIB) and an upgradeable MCUboot bootloader.

Version 1.x.x of the Serial Modem application uses only an upgradeable MCUboot bootloader. Building without the B0 bootloader is offered as backwards compatibility option if you want to maintain the same partition layout as in Serial Modem version 1.x.x.

To build without B0 and with a single, non-updatable MCUboot slot, include overlay-disable-b0.overlay in both the application and MCUboot images and disable the secure boot appcore in the sysbuild configuration:

west build -p -b nrf9151dk/nrf9151/ns -- -DEXTRA_DTC_OVERLAY_FILE=overlay-disable-b0.overlay -Dmcuboot_EXTRA_DTC_OVERLAY_FILE=<path-to-app>/overlay-disable-b0.overlay -DSB_CONFIG_SECURE_BOOT_APPCORE=n

Where <path-to-app> is the absolute path to the app directory.

This configuration removes the b0 and s1 partitions, giving MCUboot a single 64 kB slot.