Serial Modem AT Client library

Note

This library is Experimental.

The Serial Modem AT Client library exposes the AT command interface of the Serial Modem application for external devices over a serial interface. This library is intended for applications running on an external MCU that are connected to an nRF91 Series SiP through UART.

Overview

The Serial Modem AT Client library allows you to perform the following functions:

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

  • Send raw data in Serial Modem data mode. Refer to Data mode.

  • Manage the UART power state of the host.

  • Manage the UART power state of the Serial Modem with DTR (Data Terminal Ready) and RI (Ring Indicator) pins. See UART configuration for more information.

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

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

Configuration

Configure the following Kconfig option to enable the library:

  • CONFIG_SM_AT_CLIENT - Enables the Serial Modem AT Client library.

Optionally configure the following Kconfig options based on need:

  • CONFIG_SM_AT_CLIENT_SHELL - Enables the shell function in the Serial Modem AT Client library, which is disabled by default.

  • CONFIG_SM_AT_CLIENT_AT_CMD_RESP_MAX_SIZE - Configures the size of the AT command response buffer. The default size is 2100 bytes, which is aligned with Serial Modem.

  • CONFIG_SM_AT_CLIENT_UART_RX_BUF_COUNT - Configures the number of RX buffers for the UART device. The default value is 3.

  • CONFIG_SM_AT_CLIENT_UART_RX_BUF_SIZE - Configures the size of the RX buffer for the UART device. The default value is 256 bytes.

  • CONFIG_SM_AT_CLIENT_UART_TX_BUF_SIZE - Configures the size of the TX buffer for the UART device. The default value is 256 bytes.

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

  • CONFIG_SM_AT_CLIENT_CR_TERMINATION - Enables <CR> as the termination character, which is selected by default.

  • CONFIG_SM_AT_CLIENT_LF_TERMINATION - Enables <LF> as the termination character.

  • CONFIG_SM_AT_CLIENT_CR_LF_TERMINATION - Enables <CR+LF> as the termination character.

You must configure the same termination character as that configured in Serial Modem on the nRF91 Series SiP. The library sends the termination character automatically after an AT command.

The application must configure the devicetree nodes for the UART, UART pins, and DTR GPIOs.

The following is an example overlay for configuring UART and DTR/RI GPIOs with the nrf54l15dk:

/ {
  chosen {
    ncs,sm-uart = &uart30;
  };
};

/* Serial Modem AT Client <-> Serial Modem UART */
&uart30 {
  compatible = "nordic,nrf-uarte";
  current-speed = <115200>;
  status = "okay";
  hw-flow-control;
};

/* DTR gpios for uart30 */
/ {
  dte_dtr: dte_dtr {
    compatible = "nordic,dte-dtr";
    dtr-gpios = <&gpio1 11 GPIO_ACTIVE_LOW>;
    ri-gpios = <&gpio1 12 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
  };
};

UART baud rate, hardware flow control, and parity must match the Serial Modem application configuration. UART pins must be wired correctly (TX to RX, RTS to CTS) to the Serial Modem application UART pins. DTR and RI GPIO must be wired to the corresponding DTR and RI pins of the Serial Modem application.

Shell usage

Serial Modem AT commands

Send AT commands for Serial Modem in shell:

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

OK

uart:~$ sm at%ptw?

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

OK

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

Host commands

Use smsh command to see commands for the Serial Modem AT Client library functions.

uart:~$ smsh
smsh - Commands handled in Serial Modem AT Client shell device
Subcommands:
  uart  : Enable/Disable DTR UART.

uart:~$ smsh uart
uart - Enable/Disable DTR UART.
Subcommands:
  auto     : [<inactivity_period>]
            (Default) Automatically enable DTR UART from RI. Disable DTR UART
            after inactivity period (default value is 100ms).
  enable   : Enable DTR UART. Disable automatic handling.
  disable  : Disable DTR UART. Disable automatic handling.

Enable or disable host UART and command Serial Modem to do the same with DTR:

uart:~$ smsh uart enable
Enable DTR UART.

uart:~$ smsh uart disable
Disable DTR UART.

Set the automatic UART handling to 1000 ms inactivity period:

uart:~$ smsh uart auto 1000
Automatic DTR UART. Inactivity timeout 1000 ms

When automatic UART and DTR handling is enabled, the UART’s will be suspended after the inactivity period. UARTs are resumed when there is an RI signal from the Serial Modem or when the host sends data.

Serial Modem AT Client Monitor usage

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

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

API documentation

Header file: include/sm_at_client.h
Source file: lib/sm_at_client/sm_at_client.c
Source file: lib/sm_at_client/sm_at_client_monitor.c
group sm_at_client

Public APIs for the Serial Modem AT Client library.

Defines

SM_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

SM_MONITOR(name, _filter, _handler, ...)

Define an Serial Modem 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 (*sm_data_handler_t)(const uint8_t *data, size_t datalen)

Handler to handle data received from Serial Modem, 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 sm_at_client_send_cmd. The data should be copied out by the application as soon as called.

Param data:

Data received from Serial Modem.

Param datalen:

Length of the data received.

typedef void (*sm_ri_handler_t)(void)

Handler to handle the Ring Indicate (RI) signal from Serial Modem.

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

Serial Modem 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 sm_at_client_init(sm_data_handler_t handler, bool automatic_uart, k_timeout_t inactivity_timeout)

Initialize Serial Modem AT Client library.

Parameters:

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

  • automatic_uart – If true, DTR and UART are automatically managed by the library.

  • inactivity_timeout – Inactivity timeout for DTR and UART disablement. Only used if automatic is true.

Returns:

Zero on success, non-zero otherwise.

int sm_at_client_uninit(void)

Un-initialize Serial Modem AT Client.

int sm_at_client_register_ri_handler(sm_ri_handler_t handler)

Register callback for Ring Indicate (RI) pin.

Parameters:

handler – Pointer to a handler function of type sm_ri_handler_t.

Return values:

Zero – on success. Otherwise, a (negative) error code is returned.

void sm_at_client_automatic_dtr_uart(k_timeout_t inactivity)

Configure automatic DTR UART handling.

If automatic DTR UART handling is enabled, the library will enable DTR UART when RI signal is detected, and disable it after inactivity timeout.

Parameters:

inactivity – Inactivity timeout for DTR UART disablement.

void sm_at_client_disable_dtr_uart(void)

Disable DTR UART.

Disables DTR UART. Disables automatic DTR UART handling.

void sm_at_client_enable_dtr_uart(void)

Enable DTR UART.

Enables DTR UART. Disables automatic DTR UART handling.

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

Function to send an AT command in Serial Modem command mode.

This function wait until command result is received. The response of the AT command is received through the sm_ind_handler_t registered in sm_at_client_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 sm_at_client_send_data(const uint8_t *const data, size_t datalen)

Function to send raw data in Serial Modem data mode.

Parameters:

  • data – Raw data to send

  • datalen – Length of the raw data

Returns:

Zero on success, non-zero otherwise.

static inline void sm_monitor_pause(struct sm_monitor_entry *mon)

Pause monitor.

Pause monitor mon from receiving notifications.

Parameters:

mon – The monitor to pause.

static inline void sm_monitor_resume(struct sm_monitor_entry *mon)

Resume monitor.

Resume forwarding notifications to monitor mon.

Parameters:

mon – The monitor to resume.

struct sm_monitor_entry
#include <sm_at_client.h>

Serial Modem monitor entry.

Public Members

const char *filter

The filter for this monitor.

const sm_monitor_handler_t handler

Monitor callback.

uint8_t paused

Monitor is paused.