Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
cellular.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2023 Bjarki Arge Andreasen
3 * Copyright (c) 2023 Lucas Denefle
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
13
14#ifndef ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_
15#define ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_
16
23
24#include <zephyr/types.h>
25#include <zephyr/device.h>
26#include <errno.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
71
84
91
107
135
145
146/* Opaque bit-mask large enough for all current & future events */
148
153
158
163
176typedef void (*cellular_event_cb_t)(const struct device *dev, enum cellular_event event,
177 const void *payload, void *user_data);
178
180typedef int (*cellular_api_configure_networks)(const struct device *dev,
181 const struct cellular_network *networks,
182 uint8_t size);
183
185typedef int (*cellular_api_get_supported_networks)(const struct device *dev,
186 const struct cellular_network **networks,
187 uint8_t *size);
188
190typedef int (*cellular_api_get_signal)(const struct device *dev,
191 const enum cellular_signal_type type, int16_t *value);
192
194typedef int (*cellular_api_get_modem_info)(const struct device *dev,
195 const enum cellular_modem_info_type type, char *info,
196 size_t size);
197
199typedef int (*cellular_api_get_registration_status)(const struct device *dev,
201 enum cellular_registration_status *status);
202
204typedef int (*cellular_api_set_apn)(const struct device *dev, const char *apn);
205
207typedef int (*cellular_api_set_callback)(const struct device *dev, cellular_event_mask_t mask,
208 cellular_event_cb_t cb, void *user_data);
209
220
242static inline int cellular_configure_networks(const struct device *dev,
243 const struct cellular_network *networks, uint8_t size)
244{
245 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
246
247 if (api->configure_networks == NULL) {
248 return -ENOSYS;
249 }
250
251 return api->configure_networks(dev, networks, size);
252}
253
265static inline int cellular_get_supported_networks(const struct device *dev,
266 const struct cellular_network **networks,
267 uint8_t *size)
268{
269 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
270
271 if (api->get_supported_networks == NULL) {
272 return -ENOSYS;
273 }
274
275 return api->get_supported_networks(dev, networks, size);
276}
277
290static inline int cellular_get_signal(const struct device *dev,
291 const enum cellular_signal_type type, int16_t *value)
292{
293 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
294
295 if (api->get_signal == NULL) {
296 return -ENOSYS;
297 }
298
299 return api->get_signal(dev, type, value);
300}
301
315static inline int cellular_get_modem_info(const struct device *dev,
316 const enum cellular_modem_info_type type, char *info,
317 size_t size)
318{
319 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
320
321 if (api->get_modem_info == NULL) {
322 return -ENOSYS;
323 }
324
325 return api->get_modem_info(dev, type, info, size);
326}
327
340static inline int cellular_get_registration_status(const struct device *dev,
342 enum cellular_registration_status *status)
343{
344 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
345
346 if (api->get_registration_status == NULL) {
347 return -ENOSYS;
348 }
349
350 return api->get_registration_status(dev, tech, status);
351}
352
369static inline int cellular_set_apn(const struct device *dev, const char *apn)
370{
371 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
372
373 if (api->set_apn == NULL) {
374 return -ENOSYS;
375 }
376
377 return api->set_apn(dev, apn);
378}
379
394static inline int cellular_set_callback(const struct device *dev, cellular_event_mask_t mask,
395 cellular_event_cb_t cb, void *user_data)
396{
397 const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
398
399 if (api->set_callback == NULL) {
400 return -ENOSYS;
401 }
402
403 return api->set_callback(dev, mask, cb, user_data);
404}
405
406#ifdef __cplusplus
407}
408#endif
409
413
414#endif /* ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_ */
System error numbers.
static int cellular_get_signal(const struct device *dev, const enum cellular_signal_type type, int16_t *value)
Get signal for the device.
Definition cellular.h:290
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.
Definition cellular.h:194
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.
Definition cellular.h:199
cellular_access_technology
Cellular access technologies (3GPP TS 27.007 AcT)
Definition cellular.h:33
cellular_event
Events emitted asynchronously by a cellular driver.
Definition cellular.h:137
static int cellular_set_apn(const struct device *dev, const char *apn)
Set the APN used for PDP context.
Definition cellular.h:369
int(* cellular_api_get_supported_networks)(const struct device *dev, const struct cellular_network **networks, uint8_t *size)
API for getting supported networks.
Definition cellular.h:185
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.
Definition cellular.h:265
int(* cellular_api_configure_networks)(const struct device *dev, const struct cellular_network *networks, uint8_t size)
API for configuring networks.
Definition cellular.h:180
cellular_registration_status
Cellular registration status (3GPP TS 27.007)
Definition cellular.h:109
cellular_signal_type
Cellular signal type.
Definition cellular.h:86
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.
Definition cellular.h:315
int(* cellular_api_get_signal)(const struct device *dev, const enum cellular_signal_type type, int16_t *value)
API for getting network signal strength.
Definition cellular.h:190
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.
Definition cellular.h:394
uint32_t cellular_event_mask_t
Definition cellular.h:147
static int cellular_configure_networks(const struct device *dev, const struct cellular_network *networks, uint8_t size)
Configure cellular networks for the device.
Definition cellular.h:242
int(* cellular_api_set_apn)(const struct device *dev, const char *apn)
API for programming APN.
Definition cellular.h:204
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
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.
Definition cellular.h:207
cellular_modem_info_type
Cellular modem info type.
Definition cellular.h:93
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.
Definition cellular.h:340
@ CELLULAR_ACCESS_TECHNOLOGY_EC_GSM_IOT
Extended Coverage GSM for IoT (2G, 3GPP Rel 13)
Definition cellular.h:51
@ CELLULAR_ACCESS_TECHNOLOGY_UTRAN
UMTS Terrestrial Radio Access Network (3G, 3GPP Rel 99)
Definition cellular.h:39
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRA_NR_DUAL
LTE/E-UTRA & NR dual connectivity (5G, 3GPP Rel 15)
Definition cellular.h:61
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_NB_S1
EUTRAN Narrowband-IoT (4G, 3GPP Rel 13)
Definition cellular.h:53
@ CELLULAR_ACCESS_TECHNOLOGY_NG_RAN
Next Generation RAN (5G, 3GPP Rel 15)
Definition cellular.h:59
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN
Evolved UTRAN (4G, 3GPP Rel 8)
Definition cellular.h:49
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_NB_S1_SAT
Narrowband-IoT over Satellite (4G, 3GPP Rel 17)
Definition cellular.h:63
@ CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSDPA_HSUPA
UTRAN with HSDPA and HSUDP (HSPA) (3.75G, 3GPP Rel 6)
Definition cellular.h:47
@ CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSUPA
UTRAN with High Speed Uplink Packet Access (3.75G, 3GPP Rel 6)
Definition cellular.h:45
@ CELLULAR_ACCESS_TECHNOLOGY_GSM
Global System for Mobile communications (2G, 3GPP Rel 99)
Definition cellular.h:35
@ CELLULAR_ACCESS_TECHNOLOGY_UNKNOWN
Unknown access technology.
Definition cellular.h:69
@ CELLULAR_ACCESS_TECHNOLOGY_GSM_EGPRS
GSM Enhanced General Packet Radio Service (2.5G, 3GPP Rel 99)
Definition cellular.h:41
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_WB_S1_SAT
LTE (wideband) over Satellite (4G, 3GPP Rel 17)
Definition cellular.h:65
@ CELLULAR_ACCESS_TECHNOLOGY_NR_5G_CN
New Radio with 5G Core Network (5G, 3GPP Rel 15)
Definition cellular.h:57
@ CELLULAR_ACCESS_TECHNOLOGY_E_UTRA_5G_CN
LTE/E-UTRA connected to 5G Core Network (5G, 3GPP Rel 15)
Definition cellular.h:55
@ CELLULAR_ACCESS_TECHNOLOGY_NG_RAN_SAT
Next Generation RAN over Satellite (5G, 3GPP Rel 17)
Definition cellular.h:67
@ CELLULAR_ACCESS_TECHNOLOGY_GSM_COMPACT
Bandwidth & Spectrum limited variant of GSM (2G, 3GPP Rel 99)
Definition cellular.h:37
@ CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSDPA
UTRAN with High Speed Downlink Packet Access (3.5G, 3GPP Rel 5)
Definition cellular.h:43
@ CELLULAR_EVENT_MODEM_COMMS_CHECK_RESULT
Result of a communications link check to the modem.
Definition cellular.h:143
@ CELLULAR_EVENT_MODEM_INFO_CHANGED
One or more modem-info field changed (e.g.
Definition cellular.h:139
@ CELLULAR_EVENT_REGISTRATION_STATUS_CHANGED
Cellular network registration status changed.
Definition cellular.h:141
@ CELLULAR_REGISTRATION_UNKNOWN
Unknown (e.g.
Definition cellular.h:119
@ CELLULAR_REGISTRATION_CSFB_NOT_PREFERRED_ROAMING
Registered for "CSFB not preferred", roaming network.
Definition cellular.h:131
@ CELLULAR_REGISTRATION_SEARCHING
Not registered, searching for an operator.
Definition cellular.h:115
@ CELLULAR_REGISTRATION_DENIED
Registration denied.
Definition cellular.h:117
@ CELLULAR_REGISTRATION_SMS_ONLY_HOME
Registered for "SMS only", home network.
Definition cellular.h:123
@ CELLULAR_REGISTRATION_SMS_ONLY_ROAMING
Registered for "SMS only", roaming network.
Definition cellular.h:125
@ CELLULAR_REGISTRATION_REGISTERED_HOME
Registered, home network.
Definition cellular.h:113
@ CELLULAR_REGISTRATION_NOT_REGISTERED
Not registered, not searching.
Definition cellular.h:111
@ CELLULAR_REGISTRATION_CSFB_NOT_PREFERRED_HOME
Registered for "CSFB not preferred", home network.
Definition cellular.h:129
@ CELLULAR_REGISTRATION_RLOS
Attached for access to "Restricted Local Operator Services".
Definition cellular.h:133
@ CELLULAR_REGISTRATION_EMERGENCY_ONLY
Attached for emergency bearer services only.
Definition cellular.h:127
@ CELLULAR_REGISTRATION_REGISTERED_ROAMING
Registered, roaming.
Definition cellular.h:121
@ CELLULAR_SIGNAL_RSRQ
Definition cellular.h:89
@ CELLULAR_SIGNAL_RSRP
Definition cellular.h:88
@ CELLULAR_SIGNAL_RSSI
Definition cellular.h:87
@ CELLULAR_MODEM_INFO_SIM_IMSI
International Mobile Subscriber Identity.
Definition cellular.h:103
@ CELLULAR_MODEM_INFO_MANUFACTURER
Modem manufacturer.
Definition cellular.h:99
@ CELLULAR_MODEM_INFO_MODEL_ID
Modem model ID.
Definition cellular.h:97
@ CELLULAR_MODEM_INFO_SIM_ICCID
Integrated Circuit Card Identification Number (SIM)
Definition cellular.h:105
@ CELLULAR_MODEM_INFO_FW_VERSION
Modem fw version.
Definition cellular.h:101
@ CELLULAR_MODEM_INFO_IMEI
International Mobile Equipment Identity.
Definition cellular.h:95
#define BIT(n)
Unsigned integer with bit position n set (signed in assembly language).
Definition util_macro.h:44
#define ENOSYS
Function not implemented.
Definition errno.h:82
#define NULL
Definition iar_missing_defs.h:20
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
__INT16_TYPE__ int16_t
Definition stdint.h:73
Cellular driver API.
Definition cellular.h:211
cellular_api_get_supported_networks get_supported_networks
Definition cellular.h:213
cellular_api_set_apn set_apn
Definition cellular.h:217
cellular_api_set_callback set_callback
Definition cellular.h:218
cellular_api_get_registration_status get_registration_status
Definition cellular.h:216
cellular_api_get_signal get_signal
Definition cellular.h:214
cellular_api_get_modem_info get_modem_info
Definition cellular.h:215
cellular_api_configure_networks configure_networks
Definition cellular.h:212
Payload for CELLULAR_EVENT_MODEM_COMMS_CHECK_RESULT.
Definition cellular.h:160
bool success
Communications to modem checked successfully.
Definition cellular.h:161
Payload for CELLULAR_EVENT_MODEM_INFO_CHANGED.
Definition cellular.h:150
enum cellular_modem_info_type field
Which field changed.
Definition cellular.h:151
Payload for CELLULAR_EVENT_REGISTRATION_STATUS_CHANGED.
Definition cellular.h:155
enum cellular_registration_status status
New registration status.
Definition cellular.h:156
Cellular network structure.
Definition cellular.h:73
uint16_t * bands
List of bands, as defined by the specified cellular access technology, to enables.
Definition cellular.h:80
uint16_t size
Size of bands.
Definition cellular.h:82
enum cellular_access_technology technology
Cellular access technology.
Definition cellular.h:75
Runtime device structure (in ROM) per driver instance.
Definition device.h:510
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:516