Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Bjarki Arge Andreasen
3 : * Copyright (c) 2023 Lucas Denefle
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file drivers/cellular.h
10 : * @brief Public cellular network API
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_
15 :
16 : /**
17 : * @brief Cellular interface
18 : * @defgroup cellular_interface Cellular Interface
19 : * @ingroup io_interfaces
20 : * @{
21 : */
22 :
23 : #include <zephyr/types.h>
24 : #include <zephyr/device.h>
25 : #include <errno.h>
26 :
27 : #ifdef __cplusplus
28 : extern "C" {
29 : #endif
30 :
31 : /** Cellular access technologies */
32 0 : enum cellular_access_technology {
33 : CELLULAR_ACCESS_TECHNOLOGY_GSM = 0,
34 : CELLULAR_ACCESS_TECHNOLOGY_GPRS,
35 : CELLULAR_ACCESS_TECHNOLOGY_UMTS,
36 : CELLULAR_ACCESS_TECHNOLOGY_EDGE,
37 : CELLULAR_ACCESS_TECHNOLOGY_LTE,
38 : CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M1,
39 : CELLULAR_ACCESS_TECHNOLOGY_LTE_CAT_M2,
40 : CELLULAR_ACCESS_TECHNOLOGY_NB_IOT,
41 : };
42 :
43 : /** Cellular network structure */
44 1 : struct cellular_network {
45 : /** Cellular access technology */
46 1 : enum cellular_access_technology technology;
47 : /**
48 : * List of bands, as defined by the specified cellular access technology,
49 : * to enables. All supported bands are enabled if none are provided.
50 : */
51 1 : uint16_t *bands;
52 : /** Size of bands */
53 1 : uint16_t size;
54 : };
55 :
56 : /** Cellular signal type */
57 0 : enum cellular_signal_type {
58 : CELLULAR_SIGNAL_RSSI,
59 : CELLULAR_SIGNAL_RSRP,
60 : CELLULAR_SIGNAL_RSRQ,
61 : };
62 :
63 : /** Cellular modem info type */
64 1 : enum cellular_modem_info_type {
65 : /** International Mobile Equipment Identity */
66 : CELLULAR_MODEM_INFO_IMEI,
67 : /** Modem model ID */
68 : CELLULAR_MODEM_INFO_MODEL_ID,
69 : /** Modem manufacturer */
70 : CELLULAR_MODEM_INFO_MANUFACTURER,
71 : /** Modem fw version */
72 : CELLULAR_MODEM_INFO_FW_VERSION,
73 : /** International Mobile Subscriber Identity */
74 : CELLULAR_MODEM_INFO_SIM_IMSI,
75 : /** Integrated Circuit Card Identification Number (SIM) */
76 : CELLULAR_MODEM_INFO_SIM_ICCID,
77 : };
78 :
79 0 : enum cellular_registration_status {
80 : CELLULAR_REGISTRATION_NOT_REGISTERED = 0,
81 : CELLULAR_REGISTRATION_REGISTERED_HOME,
82 : CELLULAR_REGISTRATION_SEARCHING,
83 : CELLULAR_REGISTRATION_DENIED,
84 : CELLULAR_REGISTRATION_UNKNOWN,
85 : CELLULAR_REGISTRATION_REGISTERED_ROAMING,
86 : };
87 :
88 : /** API for configuring networks */
89 1 : typedef int (*cellular_api_configure_networks)(const struct device *dev,
90 : const struct cellular_network *networks,
91 : uint8_t size);
92 :
93 : /** API for getting supported networks */
94 1 : typedef int (*cellular_api_get_supported_networks)(const struct device *dev,
95 : const struct cellular_network **networks,
96 : uint8_t *size);
97 :
98 : /** API for getting network signal strength */
99 1 : typedef int (*cellular_api_get_signal)(const struct device *dev,
100 : const enum cellular_signal_type type, int16_t *value);
101 :
102 : /** API for getting modem information */
103 1 : typedef int (*cellular_api_get_modem_info)(const struct device *dev,
104 : const enum cellular_modem_info_type type,
105 : char *info, size_t size);
106 :
107 : /** API for getting registration status */
108 1 : typedef int (*cellular_api_get_registration_status)(const struct device *dev,
109 : enum cellular_access_technology tech,
110 : enum cellular_registration_status *status);
111 :
112 : /** Cellular driver API */
113 1 : __subsystem struct cellular_driver_api {
114 0 : cellular_api_configure_networks configure_networks;
115 0 : cellular_api_get_supported_networks get_supported_networks;
116 0 : cellular_api_get_signal get_signal;
117 0 : cellular_api_get_modem_info get_modem_info;
118 0 : cellular_api_get_registration_status get_registration_status;
119 : };
120 :
121 : /**
122 : * @brief Configure cellular networks for the device
123 : *
124 : * @details Cellular network devices support at least one cellular access technology.
125 : * Each cellular access technology defines a set of bands, of which the cellular device
126 : * will support all or a subset of.
127 : *
128 : * The cellular device can only use one cellular network technology at a time. It must
129 : * exclusively use the cellular network configurations provided, and will prioritize
130 : * the cellular network configurations in the order they are provided in case there are
131 : * multiple (the first cellular network configuration has the highest priority).
132 : *
133 : * @param dev Cellular network device instance.
134 : * @param networks List of cellular network configurations to apply.
135 : * @param size Size of list of cellular network configurations.
136 : *
137 : * @retval 0 if successful.
138 : * @retval -EINVAL if any provided cellular network configuration is invalid or unsupported.
139 : * @retval -ENOTSUP if API is not supported by cellular network device.
140 : * @retval Negative errno-code otherwise.
141 : */
142 1 : static inline int cellular_configure_networks(const struct device *dev,
143 : const struct cellular_network *networks, uint8_t size)
144 : {
145 : const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
146 :
147 : if (api->configure_networks == NULL) {
148 : return -ENOSYS;
149 : }
150 :
151 : return api->configure_networks(dev, networks, size);
152 : }
153 :
154 : /**
155 : * @brief Get supported cellular networks for the device
156 : *
157 : * @param dev Cellular network device instance
158 : * @param networks Pointer to list of supported cellular network configurations.
159 : * @param size Size of list of cellular network configurations.
160 : *
161 : * @retval 0 if successful.
162 : * @retval -ENOTSUP if API is not supported by cellular network device.
163 : * @retval Negative errno-code otherwise.
164 : */
165 1 : static inline int cellular_get_supported_networks(const struct device *dev,
166 : const struct cellular_network **networks,
167 : uint8_t *size)
168 : {
169 : const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
170 :
171 : if (api->get_supported_networks == NULL) {
172 : return -ENOSYS;
173 : }
174 :
175 : return api->get_supported_networks(dev, networks, size);
176 : }
177 :
178 : /**
179 : * @brief Get signal for the device
180 : *
181 : * @param dev Cellular network device instance
182 : * @param type Type of the signal information requested
183 : * @param value Signal strength destination (one of RSSI, RSRP, RSRQ)
184 : *
185 : * @retval 0 if successful.
186 : * @retval -ENOTSUP if API is not supported by cellular network device.
187 : * @retval -ENODATA if device is not in a state where signal can be polled
188 : * @retval Negative errno-code otherwise.
189 : */
190 1 : static inline int cellular_get_signal(const struct device *dev,
191 : const enum cellular_signal_type type, int16_t *value)
192 : {
193 : const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
194 :
195 : if (api->get_signal == NULL) {
196 : return -ENOSYS;
197 : }
198 :
199 : return api->get_signal(dev, type, value);
200 : }
201 :
202 : /**
203 : * @brief Get modem info for the device
204 : *
205 : * @param dev Cellular network device instance
206 : * @param type Type of the modem info requested
207 : * @param info Info string destination
208 : * @param size Info string size
209 : *
210 : * @retval 0 if successful.
211 : * @retval -ENOTSUP if API is not supported by cellular network device.
212 : * @retval -ENODATA if modem does not provide info requested
213 : * @retval Negative errno-code from chat module otherwise.
214 : */
215 1 : static inline int cellular_get_modem_info(const struct device *dev,
216 : const enum cellular_modem_info_type type, char *info,
217 : size_t size)
218 : {
219 : const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
220 :
221 : if (api->get_modem_info == NULL) {
222 : return -ENOSYS;
223 : }
224 :
225 : return api->get_modem_info(dev, type, info, size);
226 : }
227 :
228 : /**
229 : * @brief Get network registration status for the device
230 : *
231 : * @param dev Cellular network device instance
232 : * @param tech Which access technology to get status for
233 : * @param status Registration status for given access technology
234 : *
235 : * @retval 0 if successful.
236 : * @retval -ENOSYS if API is not supported by cellular network device.
237 : * @retval -ENODATA if modem does not provide info requested
238 : * @retval Negative errno-code from chat module otherwise.
239 : */
240 1 : static inline int cellular_get_registration_status(const struct device *dev,
241 : enum cellular_access_technology tech,
242 : enum cellular_registration_status *status)
243 : {
244 : const struct cellular_driver_api *api = (const struct cellular_driver_api *)dev->api;
245 :
246 : if (api->get_registration_status == NULL) {
247 : return -ENOSYS;
248 : }
249 :
250 : return api->get_registration_status(dev, tech, status);
251 : }
252 :
253 : #ifdef __cplusplus
254 : }
255 : #endif
256 :
257 : /**
258 : * @}
259 : */
260 :
261 : #endif /* ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_ */
|
