Zephyr API Documentation 4.3.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
modem_cellular.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2026 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_CELLULAR_INTERNAL_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_CELLULAR_INTERNAL_H_
14
15#include <zephyr/drivers/cellular.h>
16#include <zephyr/modem/backend/uart.h>
17#include <zephyr/drivers/uart.h>
18#include <zephyr/drivers/gpio.h>
19#include <zephyr/pm/device.h>
20#include <zephyr/modem/chat.h>
21#include <zephyr/modem/cmux.h>
22#include <zephyr/modem/pipe.h>
23#include <zephyr/modem/pipelink.h>
24#include <zephyr/modem/ppp.h>
25
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
45
46#define MODEM_CELLULAR_DATA_IMEI_LEN (16)
47#define MODEM_CELLULAR_DATA_MODEL_ID_LEN (65)
48#define MODEM_CELLULAR_DATA_IMSI_LEN (23)
49#define MODEM_CELLULAR_DATA_ICCID_LEN (22)
50#define MODEM_CELLULAR_DATA_MANUFACTURER_LEN (65)
51#define MODEM_CELLULAR_DATA_FW_VERSION_LEN (65)
52#define MODEM_CELLULAR_DATA_APN_LEN (32)
53#define MODEM_CELLULAR_MAX_APN_CMDS (2)
54#define MODEM_CELLULAR_APN_BUF_SIZE (64)
55
56enum modem_cellular_state {
57 MODEM_CELLULAR_STATE_IDLE = 0,
58 MODEM_CELLULAR_STATE_RESET_PULSE,
59 MODEM_CELLULAR_STATE_AWAIT_RESET,
60 MODEM_CELLULAR_STATE_POWER_ON_PULSE,
61 MODEM_CELLULAR_STATE_AWAIT_POWER_ON,
62 MODEM_CELLULAR_STATE_SET_BAUDRATE,
63 MODEM_CELLULAR_STATE_RUN_INIT_SCRIPT,
64 MODEM_CELLULAR_STATE_CONNECT_CMUX,
65 MODEM_CELLULAR_STATE_OPEN_DLCI1,
66 MODEM_CELLULAR_STATE_OPEN_DLCI2,
67 MODEM_CELLULAR_STATE_WAIT_FOR_APN,
68 MODEM_CELLULAR_STATE_RUN_APN_SCRIPT,
69 MODEM_CELLULAR_STATE_RUN_DIAL_SCRIPT,
70 MODEM_CELLULAR_STATE_AWAIT_REGISTERED,
71 MODEM_CELLULAR_STATE_CARRIER_ON,
72 MODEM_CELLULAR_STATE_DORMANT,
73 MODEM_CELLULAR_STATE_INIT_POWER_OFF,
74 MODEM_CELLULAR_STATE_RUN_SHUTDOWN_SCRIPT,
75 MODEM_CELLULAR_STATE_POWER_OFF_PULSE,
76 MODEM_CELLULAR_STATE_AWAIT_POWER_OFF,
77};
78
79enum modem_cellular_event {
80 MODEM_CELLULAR_EVENT_RESUME = 0,
81 MODEM_CELLULAR_EVENT_SUSPEND,
82 MODEM_CELLULAR_EVENT_SCRIPT_SUCCESS,
83 MODEM_CELLULAR_EVENT_SCRIPT_FAILED,
84 MODEM_CELLULAR_EVENT_CMUX_CONNECTED,
85 MODEM_CELLULAR_EVENT_CMUX_DISCONNECTED,
86 MODEM_CELLULAR_EVENT_DLCI1_OPENED,
87 MODEM_CELLULAR_EVENT_DLCI2_OPENED,
88 MODEM_CELLULAR_EVENT_TIMEOUT,
89 MODEM_CELLULAR_EVENT_REGISTERED,
90 MODEM_CELLULAR_EVENT_DEREGISTERED,
91 MODEM_CELLULAR_EVENT_BUS_OPENED,
92 MODEM_CELLULAR_EVENT_BUS_CLOSED,
93 MODEM_CELLULAR_EVENT_PPP_DEAD,
94 MODEM_CELLULAR_EVENT_MODEM_READY,
95 MODEM_CELLULAR_EVENT_APN_SET,
96 MODEM_CELLULAR_EVENT_RING,
97};
98
99struct modem_cellular_event_cb {
100 cellular_event_mask_t mask;
101 cellular_event_cb_t fn;
102 void *user_data;
103};
104
105struct modem_cellular_data {
106 /* UART backend */
107 struct modem_pipe *uart_pipe;
108 struct modem_backend_uart uart_backend;
109 uint8_t uart_backend_receive_buf[CONFIG_MODEM_CELLULAR_UART_BUFFER_SIZES];
110 uint8_t uart_backend_transmit_buf[CONFIG_MODEM_CELLULAR_UART_BUFFER_SIZES];
111 uint32_t original_baudrate;
112
113 /* CMUX */
114 struct modem_cmux cmux;
115 uint8_t cmux_receive_buf[MODEM_CMUX_WORK_BUFFER_SIZE];
116 uint8_t cmux_transmit_buf[MODEM_CMUX_WORK_BUFFER_SIZE];
117
118 struct modem_cmux_dlci dlci1;
119 struct modem_cmux_dlci dlci2;
120 struct modem_pipe *dlci1_pipe;
121 struct modem_pipe *dlci2_pipe;
122 /* Points to dlci2_pipe or NULL. Used for shutdown script if not NULL */
123 struct modem_pipe *cmd_pipe;
124 uint8_t dlci1_receive_buf[MODEM_CMUX_WORK_BUFFER_SIZE];
125 /* DLCI 2 is only used for chat scripts. */
126 uint8_t dlci2_receive_buf[MODEM_CMUX_WORK_BUFFER_SIZE];
127
128 /* Modem chat */
129 struct modem_chat chat;
130 uint8_t chat_receive_buf[CONFIG_MODEM_CELLULAR_CHAT_BUFFER_SIZE];
131 uint8_t *chat_delimiter;
132 uint8_t *chat_filter;
133 uint8_t *chat_argv[32];
134 uint8_t script_failure_counter;
135
136 /* Status */
137 enum cellular_registration_status registration_status_gsm;
138 enum cellular_registration_status registration_status_gprs;
139 enum cellular_registration_status registration_status_lte;
140 uint8_t rssi;
141 uint8_t rsrp;
142 uint8_t rsrq;
143 uint8_t imei[MODEM_CELLULAR_DATA_IMEI_LEN];
144 uint8_t model_id[MODEM_CELLULAR_DATA_MODEL_ID_LEN];
145 uint8_t imsi[MODEM_CELLULAR_DATA_IMSI_LEN];
146 uint8_t iccid[MODEM_CELLULAR_DATA_ICCID_LEN];
147 uint8_t manufacturer[MODEM_CELLULAR_DATA_MANUFACTURER_LEN];
148 uint8_t fw_version[MODEM_CELLULAR_DATA_FW_VERSION_LEN];
149 uint8_t apn[MODEM_CELLULAR_DATA_APN_LEN];
150
151 struct modem_chat_script_chat apn_chats[MODEM_CELLULAR_MAX_APN_CMDS];
152 struct modem_chat_script apn_script;
153 char apn_buf[MODEM_CELLULAR_MAX_APN_CMDS][MODEM_CELLULAR_APN_BUF_SIZE];
154
155 /* PPP */
156 struct modem_ppp *ppp;
157 struct net_mgmt_event_callback net_mgmt_event_callback;
158
159 enum modem_cellular_state state;
160 const struct device *dev;
161 struct k_work_delayable timeout_work;
162
163 /* Power management */
164 struct k_sem suspended_sem;
165
166 /* Event dispatcher */
167 struct k_work event_dispatch_work;
168 uint8_t event_buf[8];
169 struct k_pipe event_pipe;
170
171 struct k_mutex api_lock;
172 struct modem_cellular_event_cb cb;
173
174 /* Ring interrupt */
175 struct gpio_callback ring_gpio_cb;
176};
177
178struct modem_cellular_user_pipe {
179 struct modem_cmux_dlci dlci;
180 uint8_t dlci_address;
181 uint8_t *dlci_receive_buf;
182 uint16_t dlci_receive_buf_size;
183 struct modem_pipe *pipe;
184 struct modem_pipelink *pipelink;
185};
186
187struct modem_cellular_config {
188 const struct device *uart;
189 struct gpio_dt_spec power_gpio;
190 struct gpio_dt_spec reset_gpio;
191 struct gpio_dt_spec wake_gpio;
192 struct gpio_dt_spec ring_gpio;
193 struct gpio_dt_spec dtr_gpio;
194 uint16_t power_pulse_duration_ms;
195 uint16_t reset_pulse_duration_ms;
196 uint16_t startup_time_ms;
197 uint16_t shutdown_time_ms;
198 bool autostarts;
199 bool hold_reset_on_suspend;
200 bool reset_on_resume;
201 bool reset_on_recovery;
202 bool cmux_enable_runtime_power_save;
203 bool cmux_close_pipe_on_power_save;
204 bool use_default_pdp_context;
205 bool use_default_apn;
206 k_timeout_t cmux_idle_timeout;
207 const struct modem_chat_script *init_chat_script;
208 const struct modem_chat_script *dial_chat_script;
209 const struct modem_chat_script *periodic_chat_script;
210 const struct modem_chat_script *shutdown_chat_script;
211 const struct modem_chat_script *set_baudrate_chat_script;
212 struct modem_cellular_user_pipe *user_pipes;
213 uint8_t user_pipes_size;
214};
215
219int modem_cellular_init(const struct device *dev);
220
221int modem_cellular_pm_action(const struct device *dev, enum pm_device_action action);
222
223extern const struct cellular_driver_api modem_cellular_api;
224
225void modem_cellular_chat_callback_handler(struct modem_chat *chat,
226 enum modem_chat_script_result result,
227 void *user_data);
229
238
239#define MODEM_CELLULAR_INST_NAME(name, inst) \
240 CONCAT(name, _, DT_DRV_COMPAT, inst)
241
242#define MODEM_CELLULAR_DEFINE_USER_PIPE_DATA(inst, name, size) \
243 MODEM_PIPELINK_DT_INST_DEFINE(inst, name); \
244 static uint8_t MODEM_CELLULAR_INST_NAME(name, inst)[size] \
245
246#define MODEM_CELLULAR_INIT_USER_PIPE(_inst, _name, _dlci_address) \
247 { \
248 .dlci_address = _dlci_address, \
249 .dlci_receive_buf = MODEM_CELLULAR_INST_NAME(_name, _inst), \
250 .dlci_receive_buf_size = sizeof(MODEM_CELLULAR_INST_NAME(_name, _inst)), \
251 .pipelink = MODEM_PIPELINK_DT_INST_GET(_inst, _name), \
252 }
253
254#define MODEM_CELLULAR_DEFINE_USER_PIPES(inst, ...) \
255 static struct modem_cellular_user_pipe MODEM_CELLULAR_INST_NAME(user_pipes, inst)[] = { \
256 __VA_ARGS__ \
257 }
258
259#define MODEM_CELLULAR_GET_USER_PIPES(inst) \
260 MODEM_CELLULAR_INST_NAME(user_pipes, inst)
261
262/* Extract the first argument (pipe name) from a pair */
263#define MODEM_CELLULAR_GET_PIPE_NAME_ARG(arg1, ...) arg1
264
265/* Extract the second argument (DLCI address) from a pair */
266#define MODEM_CELLULAR_GET_DLCI_ADDRESS_ARG(arg1, arg2, ...) arg2
267
268/* Define user pipe data using instance and extracted pipe name */
269#define MODEM_CELLULAR_DEFINE_USER_PIPE_DATA_HELPER(_args, inst) \
270 MODEM_CELLULAR_DEFINE_USER_PIPE_DATA(inst, \
271 MODEM_CELLULAR_GET_PIPE_NAME_ARG _args, \
272 CONFIG_MODEM_CELLULAR_USER_PIPE_BUFFER_SIZES)
273
274/* Initialize user pipe using instance, extracted pipe name, and DLCI address */
275#define MODEM_CELLULAR_INIT_USER_PIPE_HELPER(_args, inst) \
276 MODEM_CELLULAR_INIT_USER_PIPE(inst, \
277 MODEM_CELLULAR_GET_PIPE_NAME_ARG _args, \
278 MODEM_CELLULAR_GET_DLCI_ADDRESS_ARG _args)
279
280/*
281 * Define and initialize user pipes dynamically
282 * Takes an instance and pairs of (pipe name, DLCI address)
283 */
284#define MODEM_CELLULAR_DEFINE_AND_INIT_USER_PIPES(inst, ...) \
285 FOR_EACH_FIXED_ARG(MODEM_CELLULAR_DEFINE_USER_PIPE_DATA_HELPER, \
286 (;), inst, __VA_ARGS__); \
287 MODEM_CELLULAR_DEFINE_USER_PIPES( \
288 inst, \
289 FOR_EACH_FIXED_ARG(MODEM_CELLULAR_INIT_USER_PIPE_HELPER, \
290 (,), inst, __VA_ARGS__) \
291 );
292
293/* Helper to define modem instance */
294#define MODEM_CELLULAR_DEFINE_INSTANCE(inst, power_ms, reset_ms, startup_ms, shutdown_ms, start, \
295 set_baudrate_script, init_script, dial_script, \
296 periodic_script, shutdown_script) \
297 static const struct modem_cellular_config MODEM_CELLULAR_INST_NAME(config, inst) = { \
298 .uart = DEVICE_DT_GET(DT_INST_BUS(inst)), \
299 .power_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_power_gpios, {}), \
300 .reset_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_reset_gpios, {}), \
301 .wake_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_wake_gpios, {}), \
302 .ring_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_ring_gpios, {}), \
303 .dtr_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_dtr_gpios, {}), \
304 .power_pulse_duration_ms = (power_ms), \
305 .reset_pulse_duration_ms = (reset_ms), \
306 .startup_time_ms = (startup_ms), \
307 .shutdown_time_ms = (shutdown_ms), \
308 .autostarts = DT_INST_PROP_OR(inst, autostarts, (start)), \
309 .hold_reset_on_suspend = \
310 DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior, hold_on_suspend), \
311 .reset_on_resume = DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior, \
312 toggle_on_resume), \
313 .reset_on_recovery = DT_INST_ENUM_HAS_VALUE(inst, zephyr_mdm_reset_behavior, \
314 toggle_on_recovery), \
315 .cmux_enable_runtime_power_save = \
316 DT_INST_PROP_OR(inst, cmux_enable_runtime_power_save, 0), \
317 .cmux_close_pipe_on_power_save = \
318 DT_INST_PROP_OR(inst, cmux_close_pipe_on_power_save, 0), \
319 .use_default_pdp_context = DT_INST_PROP_OR(inst, zephyr_use_default_pdp_ctx, 0), \
320 .use_default_apn = DT_INST_PROP_OR(inst, zephyr_use_default_apn, 0), \
321 .cmux_idle_timeout = K_MSEC(DT_INST_PROP_OR(inst, cmux_idle_timeout_ms, 0)), \
322 .set_baudrate_chat_script = (set_baudrate_script), \
323 .init_chat_script = (init_script), \
324 .dial_chat_script = (dial_script), \
325 .periodic_chat_script = (periodic_script), \
326 .shutdown_chat_script = (shutdown_script), \
327 .user_pipes = MODEM_CELLULAR_GET_USER_PIPES(inst), \
328 .user_pipes_size = ARRAY_SIZE(MODEM_CELLULAR_GET_USER_PIPES(inst)), \
329 }; \
330 \
331 PM_DEVICE_DT_INST_DEFINE(inst, modem_cellular_pm_action); \
332 \
333 DEVICE_DT_INST_DEFINE(inst, modem_cellular_init, PM_DEVICE_DT_INST_GET(inst), \
334 &MODEM_CELLULAR_INST_NAME(data, inst), \
335 &MODEM_CELLULAR_INST_NAME(config, inst), POST_KERNEL, \
336 CONFIG_MODEM_CELLULAR_INIT_PRIORITY, &modem_cellular_api);
337
339
340#ifdef __cplusplus
341}
342#endif
343
345
346#endif /* ZEPHYR_INCLUDE_DRIVERS_CELLULAR_INTERNAL_H_ */
cellular.h
Main header file for cellular modem driver API.
gpio.h
Main header file for GPIO driver API.
uart.h
Main header file for UART driver API.
cellular_registration_status
cellular_registration_status
Cellular registration status (3GPP TS 27.007).
Definition cellular.h:109
cellular_event_mask_t
uint32_t cellular_event_mask_t
Definition cellular.h:147
cellular_event_cb_t
void(* cellular_event_cb_t)(const struct device *dev, enum cellular_event event, const void *payload, void *user_data)
Prototype for cellular event callbacks.
Definition cellular.h:176
modem_chat_script_result
modem_chat_script_result
Definition chat.h:156
pm_device_action
pm_device_action
Device PM actions.
Definition device.h:144
state
state
Definition parser_state.h:29
uint32_t
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
uint8_t
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
uint16_t
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
cellular_driver_api
Cellular driver API.
Definition cellular.h:211
device
Runtime device structure (in ROM) per driver instance.
Definition device.h:513
modem_chat
Chat instance internal context.
Definition chat.h:223