The latest development version of this page may be more current than this released 3.7.0 version.

Modem modules

This service provides modules necessary to communicate with modems.

Modems are self-contained devices that implement the hardware and software necessary to perform RF (Radio-Frequency) communication, including GNSS, Cellular, WiFi etc.

The modem modules are inter-connected dynamically using data-in/data-out pipes making them independently testable and highly flexible, ensuring stability and scalability.

Modem pipe

This module is used to abstract data-in/data-out communication over a variety of mechanisms, like UART and CMUX DLCI channels, in a thread-safe manner.

A modem backend will internally contain an instance of a modem_pipe structure, alongside any buffers and additional structures required to abstract away its underlying mechanism.

The modem backend will return a pointer to its internal modem_pipe structure when initialized, which will be used to interact with the backend through the modem pipe API.

group modem_pipe

Modem Pipe.

Typedefs

typedef void (*modem_pipe_api_callback)(struct modem_pipe *pipe, enum modem_pipe_event event, void *user_data)

Enums

enum modem_pipe_event

Modem pipe event.

Values:

enumerator MODEM_PIPE_EVENT_OPENED = 0
enumerator MODEM_PIPE_EVENT_RECEIVE_READY
enumerator MODEM_PIPE_EVENT_TRANSMIT_IDLE
enumerator MODEM_PIPE_EVENT_CLOSED

Functions

int modem_pipe_open(struct modem_pipe *pipe)

Open pipe.

Warning

Be cautious when using this synchronous version of the call. It may block the calling thread, which in the case of the system workqueue can result in a deadlock until this call times out waiting for the pipe to be open.

Parameters:

  • pipe – Pipe instance

Return values:

  • 0 – if pipe was successfully opened or was already open

  • -errno – code otherwise

int modem_pipe_open_async(struct modem_pipe *pipe)

Open pipe asynchronously.

Note

The MODEM_PIPE_EVENT_OPENED event is invoked immediately if pipe is already opened.

Parameters:

  • pipe – Pipe instance

Return values:

  • 0 – if pipe open was called successfully or pipe was already open

  • -errno – code otherwise

void modem_pipe_attach(struct modem_pipe *pipe, modem_pipe_api_callback callback, void *user_data)

Attach pipe to callback.

Note

The MODEM_PIPE_EVENT_RECEIVE_READY event is invoked immediately if pipe has pending data ready to receive.

Parameters:

  • pipe – Pipe instance

  • callback – Callback called when pipe event occurs

  • user_data – Free to use user data passed with callback

int modem_pipe_transmit(struct modem_pipe *pipe, const uint8_t *buf, size_t size)

Transmit data through pipe.

Warning

This call must be non-blocking

Parameters:

  • pipe – Pipe to transmit through

  • buf – Data to transmit

  • size – Number of bytes to transmit

Return values:

  • Number – of bytes placed in pipe

  • -EPERM – if pipe is closed

  • -errno – code on error

int modem_pipe_receive(struct modem_pipe *pipe, uint8_t *buf, size_t size)

Receive data through pipe.

Warning

This call must be non-blocking

Parameters:

  • pipe – Pipe to receive from

  • buf – Destination for received data; must not be already in use in a modem module.

  • size – Capacity of destination for received data

Return values:

  • Number – of bytes received from pipe

  • -EPERM – if pipe is closed

  • -errno – code on error

void modem_pipe_release(struct modem_pipe *pipe)

Clear callback.

Parameters:

  • pipe – Pipe instance

int modem_pipe_close(struct modem_pipe *pipe)

Close pipe.

Warning

Be cautious when using this synchronous version of the call. It may block the calling thread, which in the case of the system workqueue can result in a deadlock until this call times out waiting for the pipe to be closed.

Parameters:

  • pipe – Pipe instance

Return values:

  • 0 – if pipe open was called closed or pipe was already closed

  • -errno – code otherwise

int modem_pipe_close_async(struct modem_pipe *pipe)

Close pipe asynchronously.

Note

The MODEM_PIPE_EVENT_CLOSED event is invoked immediately if pipe is already closed.

Parameters:

  • pipe – Pipe instance

Return values:

  • 0 – if pipe close was called successfully or pipe was already closed

  • -errno – code otherwise

Modem PPP

This module defines and binds a L2 PPP network interface, described in L2 Layer Management, to a modem backend. The L2 PPP interface sends and receives network packets. These network packets have to be wrapped in PPP frames before being transported via a modem backend. This module performs said wrapping.

group modem_ppp

Modem PPP.

Defines

MODEM_PPP_DEFINE(_name, _init_iface, _prio, _mtu, _buf_size)

Define a modem PPP module and bind it to a network interface.

This macro defines the modem_ppp instance, initializes a PPP L2 network device instance, and binds the modem_ppp instance to the PPP L2 instance.

Parameters:

  • _name – Name of the statically defined modem_ppp instance

  • _init_iface – Hook for the PPP L2 network interface init function

  • _prio – Initialization priority of the PPP L2 net iface

  • _mtu – Max size of net_pkt data sent and received on PPP L2 net iface

  • _buf_size – Size of partial PPP frame transmit and receive buffers

Typedefs

typedef void (*modem_ppp_init_iface)(struct net_if *iface)

L2 network interface init callback.

Functions

int modem_ppp_attach(struct modem_ppp *ppp, struct modem_pipe *pipe)

Attach pipe to instance and connect.

Parameters:

  • ppp – Modem PPP instance

  • pipe – Pipe to attach to modem PPP instance

struct net_if *modem_ppp_get_iface(struct modem_ppp *ppp)

Get network interface modem PPP instance is bound to.

Parameters:

  • ppp – Modem PPP instance

Returns:

Pointer to network interface modem PPP instance is bound to

void modem_ppp_release(struct modem_ppp *ppp)

Release pipe from instance.

Parameters:

  • ppp – Modem PPP instance

Modem CMUX

This module is an implementation of CMUX following the 3GPP 27.010 specification. CMUX is a multiplexing protocol, allowing for multiple bi-directional streams of data, called DLCI channels. The module attaches to a single modem backend, exposing multiple modem backends, each representing a DLCI channel.

group modem_cmux

Modem CMUX.

Typedefs

typedef void (*modem_cmux_callback)(struct modem_cmux *cmux, enum modem_cmux_event event, void *user_data)

Enums

enum modem_cmux_event

Values:

enumerator MODEM_CMUX_EVENT_CONNECTED = 0
enumerator MODEM_CMUX_EVENT_DISCONNECTED

Functions

void modem_cmux_init(struct modem_cmux *cmux, const struct modem_cmux_config *config)

Initialize CMUX instance.

Parameters:

  • cmux – CMUX instance

  • config – Configuration to apply to CMUX instance

struct modem_pipe *modem_cmux_dlci_init(struct modem_cmux *cmux, struct modem_cmux_dlci *dlci, const struct modem_cmux_dlci_config *config)

Initialize DLCI instance and register it with CMUX instance.

Parameters:

  • cmux – CMUX instance which the DLCI will be registered to

  • dlci – DLCI instance which will be registered and configured

  • config – Configuration to apply to DLCI instance

int modem_cmux_attach(struct modem_cmux *cmux, struct modem_pipe *pipe)

Attach CMUX instance to pipe.

Parameters:

  • cmux – CMUX instance

  • pipe – Pipe instance to attach CMUX instance to

int modem_cmux_connect(struct modem_cmux *cmux)

Connect CMUX instance.

This will send a CMUX connect request to target on the serial bus. If successful, DLCI channels can be now be opened using modem_pipe_open()

Note

When connected, the bus pipe must not be used directly

Parameters:

  • cmux – CMUX instance

int modem_cmux_connect_async(struct modem_cmux *cmux)

Connect CMUX instance asynchronously.

This will send a CMUX connect request to target on the serial bus. If successful, DLCI channels can be now be opened using modem_pipe_open().

Note

When connected, the bus pipe must not be used directly

Parameters:

  • cmux – CMUX instance

int modem_cmux_disconnect(struct modem_cmux *cmux)

Close down and disconnect CMUX instance.

This will close all open DLCI channels, and close down the CMUX connection.

Note

The bus pipe must be released using modem_cmux_release() after disconnecting before being reused.

Parameters:

  • cmux – CMUX instance

int modem_cmux_disconnect_async(struct modem_cmux *cmux)

Close down and disconnect CMUX instance asynchronously.

This will close all open DLCI channels, and close down the CMUX connection.

Note

The bus pipe must be released using modem_cmux_release() after disconnecting before being reused.

Parameters:

  • cmux – CMUX instance

void modem_cmux_release(struct modem_cmux *cmux)

Release CMUX instance from pipe.

Releases the pipe and hard resets the CMUX instance internally. CMUX should be disconnected using modem_cmux_disconnect().

Note

The bus pipe can be used directly again after CMUX instance is released.

Parameters:

  • cmux – CMUX instance

struct modem_cmux_config
#include <cmux.h>

Contains CMUX instance configuration data.

Public Members

modem_cmux_callback callback

Invoked when event occurs.

void *user_data

Free to use pointer passed to event handler when invoked.

uint8_t *receive_buf

Receive buffer.

uint16_t receive_buf_size

Size of receive buffer in bytes [127, …].

uint8_t *transmit_buf

Transmit buffer.

uint16_t transmit_buf_size

Size of transmit buffer in bytes [149, …].

struct modem_cmux_dlci_config
#include <cmux.h>

CMUX DLCI configuration.

Public Members

uint8_t dlci_address

DLCI channel address.

uint8_t *receive_buf

Receive buffer used by pipe.

uint16_t receive_buf_size

Size of receive buffer used by pipe [127, …].