Getting started

Serial Modem Host Applications
tags
Serial Modem Host Applications

  1. Wire up the development boards:

    1. Connect the host DK (nRF54L15 or nRF54LM20B) to the nRF9151 DK (Serial Modem).
    2. Configure both DKs in the Board Configurator and flash Serial Modem firmware with PPP and CMUX enabled on the nRF9151.
    3. Use the serial_modem_*_nrf9151dk_nrf91m1.zip from your SMHA release bundle, or download the newest matching archive from ncs-serial-modem releases.

    See Hardware setup for wiring, pin assignments, and how to flash the Serial Modem image.

  2. Build and flash nRF91M1 PPP Host Application on the host DK:

    All west commands must run inside the nRF Connect SDK toolchain environment. Launch it first (see Initialize the workspace):

    nrfutil sdk-manager toolchain launch --ncs-version v3.4.0 --shell

    nRF54L15 DK:

    cd applications/91m1_ppp
west build -b nrf54l15dk/nrf54l15/cpuapp/ns -p
west flash --recover

    nRF54LM20B DK:

    cd applications/91m1_ppp
west build -b nrf54lm20dk/nrf54lm20b/cpuapp/ns -p
west flash --recover

    For Wi-Fi® location with the nRF7002-EB II shield, see Hardware setup - Wi-Fi location.

  3. Verify the host application boots:

    1. Open a serial terminal on the host console port (see Hardware setup for which VCOM to use on your board).

    2. Confirm the application starts and note the Device ID from the boot log:

      <inf> nrf_cloud_info: Device ID: E4361AD8FD3E4554

      This 16-character hex ID comes from the host SoC HW ID (CONFIG_NRF_CLOUD_CLIENT_ID_SRC_HW_ID). Use it for credential generation and portal onboarding. It is not the nRF91 modem UUID. The cloud module logs it again when connecting:

      <inf> cloud: nRF Cloud client ID: E4361AD8FD3E4554

  4. Install nRF Cloud Utils: (one-time setup on your host machine)

    pip3 install nrfcloud-utils

    See the nRF Cloud Utils repository for details.

  5. Create a self-signed CA certificate: (one-time, reuse the same CA for all devices)

    create_ca_cert -c US -f self_

    Replace US with your two-letter country code. This produces three files (serial number varies):

    • self_<serial>_ca.pem - CA certificate
    • self_<serial>_prv.pem - CA private key
    • self_<serial>_pub.pem - CA public key

    Keep the CA private key secure.

  6. Install device credentials on the host - Run device_credentials_installer from the directory containing your CA files, pointing at the host console serial port and the device ID from step 3:

    device_credentials_installer \
  --ca self_<serial>_ca.pem \
  --ca-key self_<serial>_prv.pem \
  --id-str <device_id> \
  -s -d --verify --coap --local-cert --cmd-type tls_cred_shell \
  --port /dev/cu.usbmodem*

    Where:

    • <device_id> is the 16-character hex ID from the boot log (for example, E4361AD8FD3E4554).
    • --coap installs the CoAP server root CA in addition to the AWS root CA chain.
    • --local-cert generates the device certificate and private key on the host (required because the TLS credentials shell does not support CSR generation).
    • --cmd-type tls_cred_shell sends cred shell commands over the host UART.
    • -s saves generated PEM files (<device_id>_crt.pem, <device_id>_prv.pem, etc.) in the current directory.
    • -d deletes any existing credentials in sec tag 16842753 before installing new ones.
    • --verify confirms credentials were written correctly.
    • --port selects the host console serial port (adjust for your OS; omit if auto-detection works). On nRF54LM20B, use VCOM0 (primary port) for both plain and nRF7002-EB2 builds.

    On success you see the following message:

    Saving nRF Cloud device onboarding CSV file onboard.csv...
Onboarding CSV file saved, row count: 1

    Delete the device private key PEM from your host after installation if you used --local-cert. The default nRF Cloud security tag is 16842753 (CONFIG_NRF_CLOUD_SEC_TAG).

  7. Onboard the device to your nRF Cloud account - Register the device public key using the CSV generated in the previous step:

    nrf_cloud_onboard --api-key <your_api_key> --csv onboard.csv

    Use an API key from your nRF Cloud user account.

  8. Verify the nRF Cloud connection - After onboarding:

    1. Ensure the cellular link is up. Wait for Network connected in the log (PPP over the Serial Modem).
    2. The cloud module retries automatically every 10 seconds if credentials or valid time are missing.

    3. On success, logs show the following message:

      <inf> cloud: nRF Cloud client ID: E4361AD8FD3E4554
<inf> main: Cloud connected
<inf> main: Cloud message sent

    4. On first connect, the application sends a demo JSON message and polls for FOTA updates. While the cloud stays connected, this cloud synchronization repeats every 30 seconds (see Application behavior).

    Credentials persist across reboots when CONFIG_TLS_CREDENTIALS_BACKEND_PROTECTED_STORAGE is enabled.