Modem SLM

The Modem SLM library exposes the AT command interface of the Serial LTE Modem application for external devices over a serial interface. This library is for applications running on external MCU that is built with nRF Connect SDK and is connected to nRF9160 SiP through UART.

Overview

The Modem SLM library allows you to perform the following functions:

  • Manage the serial interface so that the application only decides which UART device to use and configures its DTS.

  • Manage the GPIO pins, with support for bidirectional indication and wakeup.

  • Send modem or SLM proprietary AT commands, receive responses and notifications, similar to the AT Host library. Received AT responses or notifications can be parsed by the AT command parser library.

  • Send raw data in SLM data mode. Refer to Running in data mode.

  • Monitor AT notifications with registered callbacks, similar to the AT monitor library.

  • Send AT commands via UART or RTT shell, similar to the AT shell library.

Configuration

The library is enabled and configured entirely using the Kconfig system.

Configure the following Kconfig options to enable this library:

Optionally configure the following Kconfig options based on need:

The application must use Zephyr chosen nodes in devicetree to select UART device. For example:

/ {
   chosen {
      ncs,slm-uart = &uart1;
   };
};

Use one of the following options to select the termination character:

You must configure the same termination character as that configured in SLM on nRF9160 SiP. The library sends the termination character automatically after an AT command.

Shell usage

To send AT commands in shell, use the following syntax:

uart:~$ slm AT%XPTW=4,\"0001\"

OK

uart:~$ slm at%ptw?

%XPTW: 4,"0001"
%XPTW: 5,"0011"

OK

SLM accepts AT command characters in upper, lower, or mixed case.

SLM Monitor usage

The SLM Monitor has similar functions to the AT monitor library, except “Direct dispatching”.

SLM_MONITOR(network, "\r\n+CEREG:", cereg_mon);

SLM_MONITOR(download, "\r\n#XDFUGET: 0,", download_mon, MON_PAUSED);

API documentation

Header file: include/modem/modem_slm.h
Source file: lib/modem/modem_slm.c
Source file: lib/modem/modem_slm_monitor.c
group modem_slm

Public APIs for the Modem SLM library.

Defines

SLM_AT_CMD_RESPONSE_MAX_LEN

Max size of AT command response is 2100 bytes.

MON_ANY

Wildcard. Match any notifications.

MON_PAUSED

Monitor is paused.

MON_ACTIVE

Monitor is active, default

SLM_MONITOR(name, _filter, _handler, ...)

Define an SLM monitor to receive notifications in the system workqueue thread.

Parameters:

  • name – The monitor’s name.

  • _filter – The filter for AT notification the monitor should receive, or MON_ANY to receive all notifications.

  • _handler – The monitor callback.

  • ... – Optional monitor initial state (MON_PAUSED or MON_ACTIVE). The default initial state of a monitor is MON_ACTIVE.

Typedefs

typedef void (*slm_data_handler_t)(const uint8_t *data, size_t datalen)

Handler to handle data received from SLM, which could be AT response, AT notification or simply raw data (for example DFU image).

Note

The handler runs from uart callback. It must not call modem_slm_send_cmd. The data should be copied out by the application as soon as called.

Param data:

Data received from SLM.

Param datalen:

Length of the data received.

typedef void (*slm_ind_handler_t)(void)

Handler to handle MODEM_SLM_INDICATE_PIN signal from SLM.

typedef void (*slm_monitor_handler_t)(const char *notif)

SLM monitor callback.

Param notif:

The AT notification callback.

Enums

enum at_cmd_state

AT command result codes.

Values:

enumerator AT_CMD_OK
enumerator AT_CMD_ERROR
enumerator AT_CMD_ERROR_CMS
enumerator AT_CMD_ERROR_CME
enumerator AT_CMD_PENDING

Functions

int modem_slm_init(slm_data_handler_t handler)

Initialize Modem SLM library.

Parameters:
Returns:

Zero on success, non-zero otherwise.

int modem_slm_uninit(void)

Un-initialize Modem SLM library.

int modem_slm_register_ind(slm_ind_handler_t handler, bool wakeup)

Register callback for MODEM_SLM_INDICATE_PIN indication.

Parameters:

  • handler – Pointer to a handler function of type slm_ind_handler_t.

  • wakeup – Enable/disable System Off wakeup by GPIO Sense.

Return values:

  • Zero – Success.

  • -EFAULT – if MODEM_SLM_INDICATE_PIN is not defined.

int modem_slm_wake_up(void)

Wakeup nRF9160 SiP via MODEM_SLM_WAKEUP_PIN.

Returns:

Zero on success, non-zero otherwise.

void modem_slm_reset_uart(void)

Reset the RX function of the serial interface.

int modem_slm_send_cmd(const char *const command, uint32_t timeout)

Function to send an AT command in SLM command mode.

This function wait until command result is received. The response of the AT command is received via the slm_ind_handler_t registered in modem_slm_init.

Parameters:

  • command – Pointer to null terminated AT command string without command terminator

  • timeout – Response timeout for the command in seconds, Zero means infinite wait

Return values:

  • state – at_cmd_state if command execution succeeds.

  • -EAGAIN – if command execution times out.

  • other – if command execution fails.

int modem_slm_send_data(const uint8_t *const data, size_t datalen)

Function to send raw data in SLM data mode.

Parameters:

  • data – Raw data to send

  • datalen – Length of the raw data

Returns:

Zero on success, non-zero otherwise.

static inline void slm_monitor_pause(struct slm_monitor_entry *mon)

Pause monitor.

Pause monitor mon from receiving notifications.

Parameters:

  • mon – The monitor to pause.

static inline void slm_monitor_resume(struct slm_monitor_entry *mon)

Resume monitor.

Resume forwarding notifications to monitor mon.

Parameters:

  • mon – The monitor to resume.

struct slm_monitor_entry
#include <modem_slm.h>

SLM monitor entry.

Public Members

const char *filter

The filter for this monitor.

const slm_monitor_handler_t handler

Monitor callback.

uint8_t paused

Monitor is paused.