Cellular Interface

Cellular interface. More...

Data Structures
struct	cellular_network
	Cellular network structure. More...
struct	cellular_evt_modem_info
	Payload for CELLULAR_EVENT_MODEM_INFO_CHANGED. More...
struct	cellular_driver_api
	Cellular driver API. More...

Typedefs
typedef uint32_t	cellular_event_mask_t
typedef void(*	cellular_event_cb_t) (const struct device *dev, enum cellular_event event, const void *payload, void *user_data)
	Prototype for cellular event callbacks.
typedef int(*	cellular_api_configure_networks) (const struct device *dev, const struct cellular_network *networks, uint8_t size)
	API for configuring networks.
typedef int(*	cellular_api_get_supported_networks) (const struct device *dev, const struct cellular_network **networks, uint8_t *size)
	API for getting supported networks.
typedef int(*	cellular_api_get_signal) (const struct device *dev, const enum cellular_signal_type type, int16_t *value)
	API for getting network signal strength.
typedef int(*	cellular_api_get_modem_info) (const struct device *dev, const enum cellular_modem_info_type type, char *info, size_t size)
	API for getting modem information.
typedef int(*	cellular_api_get_registration_status) (const struct device *dev, enum cellular_access_technology tech, enum cellular_registration_status *status)
	API for getting registration status.
typedef int(*	cellular_api_set_apn) (const struct device *dev, const char *apn)
	API for programming APN.
typedef int(*	cellular_api_set_callback) (const struct device *dev, cellular_event_mask_t mask, cellular_event_cb_t cb, void *user_data)
	API for registering an asynchronous callback.

Enumerations
enum	cellular_access_technology {   CELLULAR_ACCESS_TECHNOLOGY_GSM = 0 , CELLULAR_ACCESS_TECHNOLOGY_GPRS , CELLULAR_ACCESS_TECHNOLOGY_UMTS , CELLULAR_ACCESS_TECHNOLOGY_EDGE ,   CELLULAR_ACCESS_TECHNOLOGY_LTE , CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M1 , CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M2 , CELLULAR_ACCESS_TECHNOLOGY_NB_IOT }
	Cellular access technologies. More...
enum	cellular_signal_type { CELLULAR_SIGNAL_RSSI , CELLULAR_SIGNAL_RSRP , CELLULAR_SIGNAL_RSRQ }
	Cellular signal type. More...
enum	cellular_modem_info_type {   CELLULAR_MODEM_INFO_IMEI , CELLULAR_MODEM_INFO_MODEL_ID , CELLULAR_MODEM_INFO_MANUFACTURER , CELLULAR_MODEM_INFO_FW_VERSION ,   CELLULAR_MODEM_INFO_SIM_IMSI , CELLULAR_MODEM_INFO_SIM_ICCID }
	Cellular modem info type. More...
enum	cellular_registration_status {   CELLULAR_REGISTRATION_NOT_REGISTERED = 0 , CELLULAR_REGISTRATION_REGISTERED_HOME , CELLULAR_REGISTRATION_SEARCHING , CELLULAR_REGISTRATION_DENIED ,   CELLULAR_REGISTRATION_UNKNOWN , CELLULAR_REGISTRATION_REGISTERED_ROAMING }
enum	cellular_event { CELLULAR_EVENT_MODEM_INFO_CHANGED = BIT(0) }
	Events emitted asynchronously by a cellular driver. More...

Functions
static int	cellular_configure_networks (const struct device *dev, const struct cellular_network *networks, uint8_t size)
	Configure cellular networks for the device.
static int	cellular_get_supported_networks (const struct device *dev, const struct cellular_network **networks, uint8_t *size)
	Get supported cellular networks for the device.
static int	cellular_get_signal (const struct device *dev, const enum cellular_signal_type type, int16_t *value)
	Get signal for the device.
static int	cellular_get_modem_info (const struct device *dev, const enum cellular_modem_info_type type, char *info, size_t size)
	Get modem info for the device.
static int	cellular_get_registration_status (const struct device *dev, enum cellular_access_technology tech, enum cellular_registration_status *status)
	Get network registration status for the device.
static int	cellular_set_apn (const struct device *dev, const char *apn)
	Set the APN used for PDP context.
static int	cellular_set_callback (const struct device *dev, cellular_event_mask_t mask, cellular_event_cb_t cb, void *user_data)
	Subscribe to asynchronous cellular events.

Detailed Description

Cellular interface.

Typedef Documentation

cellular_api_configure_networks

typedef int(* cellular_api_configure_networks) (const struct device *dev, const struct cellular_network *networks, uint8_t size)

#include <zephyr/drivers/cellular.h>

API for configuring networks.

cellular_api_get_modem_info

typedef int(* cellular_api_get_modem_info) (const struct device *dev, const enum cellular_modem_info_type type, char *info, size_t size)

#include <zephyr/drivers/cellular.h>

API for getting modem information.

cellular_api_get_registration_status

typedef int(* cellular_api_get_registration_status) (const struct device *dev, enum cellular_access_technology tech, enum cellular_registration_status *status)

#include <zephyr/drivers/cellular.h>

API for getting registration status.

cellular_api_get_signal

typedef int(* cellular_api_get_signal) (const struct device *dev, const enum cellular_signal_type type, int16_t *value)

#include <zephyr/drivers/cellular.h>

API for getting network signal strength.

cellular_api_get_supported_networks

typedef int(* cellular_api_get_supported_networks) (const struct device *dev, const struct cellular_network **networks, uint8_t *size)

#include <zephyr/drivers/cellular.h>

API for getting supported networks.

cellular_api_set_apn

typedef int(* cellular_api_set_apn) (const struct device *dev, const char *apn)

#include <zephyr/drivers/cellular.h>

API for programming APN.

cellular_api_set_callback

typedef int(* cellular_api_set_callback) (const struct device *dev, cellular_event_mask_t mask, cellular_event_cb_t cb, void *user_data)

#include <zephyr/drivers/cellular.h>

API for registering an asynchronous callback.

cellular_event_cb_t

typedef void(* cellular_event_cb_t) (const struct device *dev, enum cellular_event event, const void *payload, void *user_data)

#include <zephyr/drivers/cellular.h>

Prototype for cellular event callbacks.

Parameters

dev	Cellular device that generated the event
event	Which cellular_event occurred
payload	Pointer to the kind-specific payload (NULL if the kind defines no payload).
user_data	Pointer supplied when the callback was registered

Note

The driver calls the callback directly from its own context. Off-load heavy processing to a work-queue if required.

cellular_event_mask_t

typedef uint32_t cellular_event_mask_t

#include <zephyr/drivers/cellular.h>

Enumeration Type Documentation

cellular_access_technology

enum cellular_access_technology

#include <zephyr/drivers/cellular.h>

Cellular access technologies.

Enumerator
CELLULAR_ACCESS_TECHNOLOGY_GSM
CELLULAR_ACCESS_TECHNOLOGY_GPRS
CELLULAR_ACCESS_TECHNOLOGY_UMTS
CELLULAR_ACCESS_TECHNOLOGY_EDGE
CELLULAR_ACCESS_TECHNOLOGY_LTE
CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M1
CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M2
CELLULAR_ACCESS_TECHNOLOGY_NB_IOT

cellular_event

enum cellular_event

#include <zephyr/drivers/cellular.h>

Events emitted asynchronously by a cellular driver.

Enumerator
CELLULAR_EVENT_MODEM_INFO_CHANGED	One or more modem-info field changed (e.g. IMSI became available).

cellular_modem_info_type

enum cellular_modem_info_type

#include <zephyr/drivers/cellular.h>

Cellular modem info type.

Enumerator
CELLULAR_MODEM_INFO_IMEI	International Mobile Equipment Identity.
CELLULAR_MODEM_INFO_MODEL_ID	Modem model ID.
CELLULAR_MODEM_INFO_MANUFACTURER	Modem manufacturer.
CELLULAR_MODEM_INFO_FW_VERSION	Modem fw version.
CELLULAR_MODEM_INFO_SIM_IMSI	International Mobile Subscriber Identity.
CELLULAR_MODEM_INFO_SIM_ICCID	Integrated Circuit Card Identification Number (SIM)

cellular_registration_status

enum cellular_registration_status

#include <zephyr/drivers/cellular.h>

Enumerator
CELLULAR_REGISTRATION_NOT_REGISTERED
CELLULAR_REGISTRATION_REGISTERED_HOME
CELLULAR_REGISTRATION_SEARCHING
CELLULAR_REGISTRATION_DENIED
CELLULAR_REGISTRATION_UNKNOWN
CELLULAR_REGISTRATION_REGISTERED_ROAMING

cellular_signal_type

enum cellular_signal_type

#include <zephyr/drivers/cellular.h>

Cellular signal type.

Enumerator
CELLULAR_SIGNAL_RSSI
CELLULAR_SIGNAL_RSRP
CELLULAR_SIGNAL_RSRQ

Function Documentation

cellular_configure_networks()

int cellular_configure_networks ( const struct device * dev, const struct cellular_network * networks, uint8_t size )

inlinestatic

#include <zephyr/drivers/cellular.h>

Configure cellular networks for the device.

Cellular network devices support at least one cellular access technology. Each cellular access technology defines a set of bands, of which the cellular device will support all or a subset of.

The cellular device can only use one cellular network technology at a time. It must exclusively use the cellular network configurations provided, and will prioritize the cellular network configurations in the order they are provided in case there are multiple (the first cellular network configuration has the highest priority).

Parameters

dev	Cellular network device instance.
networks	List of cellular network configurations to apply.
size	Size of list of cellular network configurations.

Return values

0	if successful.
-EINVAL	if any provided cellular network configuration is invalid or unsupported.
-ENOTSUP	if API is not supported by cellular network device.
Negative	errno-code otherwise.

cellular_get_modem_info()

int cellular_get_modem_info ( const struct device * dev, const enum cellular_modem_info_type type, char * info, size_t size )

inlinestatic

#include <zephyr/drivers/cellular.h>

Get modem info for the device.

Parameters

dev	Cellular network device instance
type	Type of the modem info requested
info	Info string destination
size	Info string size

Return values

0	if successful.
-ENOTSUP	if API is not supported by cellular network device.
-ENODATA	if modem does not provide info requested
Negative	errno-code from chat module otherwise.

cellular_get_registration_status()

int cellular_get_registration_status ( const struct device * dev, enum cellular_access_technology tech, enum cellular_registration_status * status )

inlinestatic

#include <zephyr/drivers/cellular.h>

Get network registration status for the device.

Parameters

dev	Cellular network device instance
tech	Which access technology to get status for
status	Registration status for given access technology

Return values

0	if successful.
-ENOSYS	if API is not supported by cellular network device.
-ENODATA	if modem does not provide info requested
Negative	errno-code from chat module otherwise.

cellular_get_signal()

int cellular_get_signal ( const struct device * dev, const enum cellular_signal_type type, int16_t * value )

inlinestatic

#include <zephyr/drivers/cellular.h>

Get signal for the device.

Parameters

dev	Cellular network device instance
type	Type of the signal information requested
value	Signal strength destination (one of RSSI, RSRP, RSRQ)

Return values

0	if successful.
-ENOTSUP	if API is not supported by cellular network device.
-ENODATA	if device is not in a state where signal can be polled
Negative	errno-code otherwise.

cellular_get_supported_networks()

int cellular_get_supported_networks ( const struct device * dev, const struct cellular_network ** networks, uint8_t * size )

inlinestatic

#include <zephyr/drivers/cellular.h>

Get supported cellular networks for the device.

Parameters

dev	Cellular network device instance
networks	Pointer to list of supported cellular network configurations.
size	Size of list of cellular network configurations.

Return values

0	if successful.
-ENOTSUP	if API is not supported by cellular network device.
Negative	errno-code otherwise.

cellular_set_apn()

int cellular_set_apn ( const struct device * dev, const char * apn )

inlinestatic

#include <zephyr/drivers/cellular.h>

Set the APN used for PDP context.

Drivers are expected to copy the string immediately and return once the request has been queued internally.

Parameters

dev	Cellular device
apn	Zero-terminated APN string (max length is driver-specific)

Return values

0	if successful.
-ENOSYS	if API is not supported by cellular network device.
-EINVAL	if APN string invalid or too long.
-EALREADY	if APN identical to current one, nothing to do
-EBUSY	if modem is already dialled, APN cannot be changed
Negative	errno-code otherwise.

cellular_set_callback()

int cellular_set_callback ( const struct device * dev, cellular_event_mask_t mask, cellular_event_cb_t cb, void * user_data )

inlinestatic

#include <zephyr/drivers/cellular.h>

Subscribe to asynchronous cellular events.

Parameters

dev	Cellular device
mask	Event mask to subscribe to
cb	Callback to call when the event occurs, or NULL to unsubscribe
user_data	Pointer to user data that will be passed to the callback

Return values

0	Success
-ENOSYS	Driver does not support event callbacks
-EINVAL	Bad parameters
-ENOMEM	No space left for another subscriber
<0	Driver-specific error