Line data Source code
1 1 : /** @file
2 : * @brief Simcom SIM7080 modem public API header file.
3 : *
4 : * Copyright (C) 2021 metraTec GmbH
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : #ifndef ZEPHYR_INCLUDE_DRIVERS_MODEM_SIMCOM_SIM7080_H
10 : #define ZEPHYR_INCLUDE_DRIVERS_MODEM_SIMCOM_SIM7080_H
11 :
12 : #include <zephyr/types.h>
13 :
14 : #include <stdint.h>
15 : #include <time.h>
16 :
17 : #ifdef __cplusplus
18 : extern "C" {
19 : #endif
20 :
21 : /** Maximum Length of GNSS UTC data */
22 1 : #define SIM7080_GNSS_DATA_UTC_LEN 20
23 : /** Maximum SMS length */
24 1 : #define SIM7080_SMS_MAX_LEN 160
25 : /** Maximum UE system information band size */
26 1 : #define SIM7080_UE_SYS_INFO_BAND_SIZE 32
27 : /** Maximum number of DNS retries */
28 1 : #define SIM7080_DNS_MAX_RECOUNT 10
29 : /** Maximum timeout for DNS queries in milliseconds */
30 1 : #define SIM7080_DNS_MAX_TIMEOUT_MS 60000
31 :
32 : /** Sim7080 modem state */
33 1 : enum sim7080_state {
34 : SIM7080_STATE_INIT = 0, /**< Initial modem state */
35 : SIM7080_STATE_IDLE, /**< Modem idle */
36 : SIM7080_STATE_NETWORKING, /**< Network active */
37 : SIM7080_STATE_GNSS, /**< GNSS active */
38 : SIM7080_STATE_OFF, /**< Modem off */
39 : };
40 :
41 : /** Sim7080 gnss data structure */
42 1 : struct sim7080_gnss_data {
43 : /**
44 : * Whether gnss is powered or not.
45 : */
46 1 : bool run_status;
47 : /**
48 : * Whether fix is acquired or not.
49 : */
50 1 : bool fix_status;
51 : /**
52 : * UTC in format yyyyMMddhhmmss.sss
53 : */
54 1 : char utc[SIM7080_GNSS_DATA_UTC_LEN];
55 : /**
56 : * Latitude in 10^-7 degree.
57 : */
58 1 : int32_t lat;
59 : /**
60 : * Longitude in 10^-7 degree.
61 : */
62 1 : int32_t lon;
63 : /**
64 : * Altitude in mm.
65 : */
66 1 : int32_t alt;
67 : /**
68 : * Horizontal dilution of precision in 10^-2.
69 : */
70 1 : uint16_t hdop;
71 : /**
72 : * Course over ground un 10^-2 degree.
73 : */
74 1 : uint16_t cog;
75 : /**
76 : * Speed in 10^-1 km/h.
77 : */
78 1 : uint16_t kmh;
79 : };
80 :
81 : /** Possible sms states in memory. */
82 1 : enum sim7080_sms_stat {
83 : SIM7080_SMS_STAT_REC_UNREAD = 0, /**< Message unread */
84 : SIM7080_SMS_STAT_REC_READ, /**< Message read*/
85 : SIM7080_SMS_STAT_STO_UNSENT, /**< Message stored unsent */
86 : SIM7080_SMS_STAT_STO_SENT, /**< Message stored sent */
87 : SIM7080_SMS_STAT_ALL, /**< Status count */
88 : };
89 :
90 : /** Possible ftp return codes. */
91 1 : enum sim7080_ftp_rc {
92 : SIM7080_FTP_RC_OK = 0, /**< Operation finished correctly. */
93 : SIM7080_FTP_RC_FINISHED, /**< Session finished. */
94 : SIM7080_FTP_RC_ERROR, /**< An error occurred. */
95 : };
96 :
97 : /**
98 : * Buffer structure for sms.
99 : */
100 1 : struct sim7080_sms {
101 : /** First octet of the sms. */
102 1 : uint8_t first_octet;
103 : /** Message protocol identifier. */
104 1 : uint8_t tp_pid;
105 : /** Status of the sms in memory. */
106 1 : enum sim7080_sms_stat stat;
107 : /** Index of the sms in memory. */
108 1 : uint16_t index;
109 : /** Time the sms was received. */
110 : struct {
111 1 : uint8_t year; /**< Current Year */
112 1 : uint8_t month; /**< Month of the year */
113 1 : uint8_t day; /**< Day of the month */
114 1 : uint8_t hour; /**< Hour of the day */
115 1 : uint8_t minute; /**< Minute */
116 1 : uint8_t second; /**< Second */
117 1 : uint8_t timezone; /**< Current timezone */
118 1 : } time;
119 : /** Buffered sms. */
120 1 : char data[SIM7080_SMS_MAX_LEN + 1];
121 : /** Length of the sms in buffer. */
122 1 : uint8_t data_len;
123 : };
124 :
125 : /**
126 : * Buffer structure for sms reads.
127 : */
128 1 : struct sim7080_sms_buffer {
129 : /** sms structures to read to. */
130 1 : struct sim7080_sms *sms;
131 : /** Number of sms structures. */
132 1 : uint8_t nsms;
133 : };
134 :
135 : /** UE system mode */
136 1 : enum sim7080_ue_sys_mode {
137 : SIM7080_UE_SYS_MODE_NO_SERVICE, /**< No service */
138 : SIM7080_UE_SYS_MODE_GSM, /**< GSM */
139 : SIM7080_UE_SYS_MODE_LTE_CAT_M1, /**< LTE CAT M1 */
140 : SIM7080_UE_SYS_MODE_LTE_NB_IOT, /**< LTE NB IOT */
141 : };
142 :
143 : /** UE operating mode */
144 1 : enum sim7080_ue_op_mode {
145 : SIM7080_UE_OP_MODE_ONLINE, /**< Online */
146 : SIM7080_UE_OP_MODE_OFFLINE, /**< Offline */
147 : SIM7080_UE_OP_MODE_FACTORY_TEST_MODE, /**< Factory test mode */
148 : SIM7080_UE_OP_MODE_RESET, /**< Reset */
149 : SIM7080_UE_OP_MODE_LOW_POWER_MODE, /**< Low power mode */
150 : };
151 :
152 : /**
153 : * Sim7080 ue system information structure for gsm.
154 : */
155 1 : struct sim7080_ue_sys_info_gsm {
156 : /** Mobile country code */
157 1 : uint16_t mcc;
158 : /** Mobile network code */
159 1 : uint16_t mcn;
160 : /** Location area code */
161 1 : uint16_t lac;
162 : /** Cell ID */
163 1 : uint16_t cid;
164 : /** Absolute radio frequency channel number */
165 1 : uint8_t arfcn[SIM7080_UE_SYS_INFO_BAND_SIZE + 1];
166 : /** RX level in dBm */
167 1 : int16_t rx_lvl;
168 : /** Track LO adjust */
169 1 : int16_t track_lo_adjust;
170 : /** C1 coefficient */
171 1 : uint16_t c1;
172 : /** C2 coefficient */
173 1 : uint16_t c2;
174 : };
175 :
176 : /**
177 : * Sim7080 ue system information structure for LTE.
178 : */
179 1 : struct sim7080_ue_sys_info_lte {
180 : /** Mobile country code */
181 1 : uint16_t mcc;
182 : /** Mobile network code */
183 1 : uint16_t mcn;
184 : /** Tracing area code */
185 1 : uint16_t tac;
186 : /** Serving Cell ID */
187 1 : uint32_t sci;
188 : /** Physical Cell ID */
189 1 : uint16_t pci;
190 : /** Frequency band */
191 1 : uint8_t band[SIM7080_UE_SYS_INFO_BAND_SIZE + 1];
192 : /** E-UTRA absolute radio frequency channel number */
193 1 : uint16_t earfcn;
194 : /** Downlink bandwidth in MHz */
195 1 : uint16_t dlbw;
196 : /** Uplink bandwidth in MHz */
197 1 : uint16_t ulbw;
198 : /** Reference signal received quality in dB */
199 1 : int16_t rsrq;
200 : /** Reference signal received power in dBm */
201 1 : int16_t rsrp;
202 : /** Received signal strength indicator in dBm */
203 1 : int16_t rssi;
204 : /** Reference signal signal to noise ratio in dB */
205 1 : int16_t rssnr;
206 : /** Signal to interference plus noise ratio in dB */
207 1 : int16_t sinr;
208 : };
209 :
210 : /**
211 : * Sim7080 ue system information structure.
212 : */
213 1 : struct sim7080_ue_sys_info {
214 : /** Refer to sim7080_ue_sys_mode */
215 1 : enum sim7080_ue_sys_mode sys_mode;
216 : /** Refer to sim7080_ue_op_mode */
217 1 : enum sim7080_ue_op_mode op_mode;
218 : union {
219 : /** Only set if sys_mode is GSM */
220 1 : struct sim7080_ue_sys_info_gsm gsm;
221 : /** Only set if sys mode is LTE CAT-M1/NB-IOT */
222 1 : struct sim7080_ue_sys_info_lte lte;
223 1 : } cell; /**< Cell information */
224 : };
225 :
226 : /**
227 : * Get the current state of the modem.
228 : *
229 : * @return The current state.
230 : */
231 1 : enum sim7080_state mdm_sim7080_get_state(void);
232 :
233 : /**
234 : * @brief Power on the Sim7080.
235 : *
236 : * @return 0 on success. Otherwise -1 is returned.
237 : */
238 1 : int mdm_sim7080_power_on(void);
239 :
240 : /**
241 : * @brief Power off the Sim7080.
242 : *
243 : * @return 0 on success. Otherwise -1 is returned.
244 : */
245 1 : int mdm_sim7080_power_off(void);
246 :
247 : /**
248 : * Forcefully reset the modem by pulling pwrkey for 15 seconds.
249 : * @note The state of the modem may be undefined after calling
250 : * this function. Call mdm_sim7080_power_on after force reset.
251 : */
252 1 : void mdm_sim7080_force_reset(void);
253 :
254 : /**
255 : * @brief Activates the network operation mode of the modem.
256 : *
257 : * @return 0 on success. Otherwise <0 is returned.
258 : * @note The modem needs to be booted for this function to work.
259 : * Concurrent use of network and gnss is not possible.
260 : */
261 1 : int mdm_sim7080_start_network(void);
262 :
263 : /**
264 : * @brief Stops the networking operation mode of the modem.
265 : *
266 : * @return 0 on success. Otherwise <0 is returned.
267 : */
268 1 : int mdm_sim7080_stop_network(void);
269 :
270 : /**
271 : * @brief Starts the modem in gnss operation mode.
272 : *
273 : * @return 0 on success. Otherwise <0 is returned.
274 : * @note The modem needs to be booted for this function to work.
275 : * Concurrent use of network and gnss is not possible.
276 : */
277 1 : int mdm_sim7080_start_gnss(void);
278 :
279 : /**
280 : * @brief Starts the modem in gnss operation mode with xtra functionality.
281 : *
282 : * @return 0 on success. Otherwise <0 is returned.
283 : * @note The modem needs to be booted for this function to work.
284 : * Concurrent use of network and gnss is not possible.
285 : * @note If enabling xtra functionality fails a normal cold start will be performed.
286 : */
287 1 : int mdm_sim7080_start_gnss_xtra(void);
288 :
289 : /**
290 : * @brief Stops the modem gnss operation mode.
291 : *
292 : * @return 0 on success. Otherwise <0 is returned.
293 : */
294 1 : int mdm_sim7080_stop_gnss(void);
295 :
296 : /**
297 : * @brief Download the XTRA file for assisted gnss.
298 : *
299 : * @param server_id Id of the server to download XTRA file from.
300 : * @param f_name The name of the XTRA file to download.
301 : * @return 0 on success. Otherwise <0 is returned.
302 : */
303 1 : int mdm_sim7080_download_xtra(uint8_t server_id, const char *f_name);
304 :
305 : /**
306 : * @brief Query the validity of the XTRA file.
307 : *
308 : * @param diff_h Difference between the local time and the XTRA inject time in hours.
309 : * @param duration_h Valid time of the XTRA file in hours.
310 : * @param inject Injection time of the XTRA file.
311 : */
312 1 : int mdm_sim7080_query_xtra_validity(int16_t *diff_h, int16_t *duration_h, struct tm *inject);
313 :
314 : /**
315 : * @brief Query gnss position form the modem.
316 : *
317 : * @return 0 on success. If no fix is acquired yet -EAGAIN is returned.
318 : * Otherwise <0 is returned.
319 : */
320 1 : int mdm_sim7080_query_gnss(struct sim7080_gnss_data *data);
321 :
322 : /**
323 : * Get the sim7080 manufacturer.
324 : */
325 1 : const char *mdm_sim7080_get_manufacturer(void);
326 :
327 : /**
328 : * Get the sim7080 model information.
329 : */
330 1 : const char *mdm_sim7080_get_model(void);
331 :
332 : /**
333 : * Get the sim7080 revision.
334 : */
335 1 : const char *mdm_sim7080_get_revision(void);
336 :
337 : /**
338 : * Get the sim7080 imei number.
339 : */
340 1 : const char *mdm_sim7080_get_imei(void);
341 :
342 : /**
343 : * Get the sim7080 iccid number.
344 : */
345 1 : const char *mdm_sim7080_get_iccid(void);
346 :
347 : /**
348 : * Read sms from sim module.
349 : *
350 : * @param buffer Buffer structure for sms.
351 : * @return Number of sms read on success. Otherwise -1 is returned.
352 : *
353 : * @note The buffer structure needs to be initialized to
354 : * the size of the sms buffer. When this function finishes
355 : * successful, nsms will be set to the number of sms read.
356 : * If the whole structure is filled a subsequent read may
357 : * be needed.
358 : */
359 1 : int mdm_sim7080_read_sms(struct sim7080_sms_buffer *buffer);
360 :
361 : /**
362 : * Delete a sms at a given index.
363 : *
364 : * @param index The index of the sms in memory.
365 : * @return 0 on success. Otherwise -1 is returned.
366 : */
367 1 : int mdm_sim7080_delete_sms(uint16_t index);
368 :
369 : /**
370 : * Set the level of one of the module's GPIO pins
371 : *
372 : * @param gpio GPIO pin number
373 : * @param level New logical level of the GPIO
374 : * @return 0 on success. Otherwise -1 is returned.
375 : *
376 : * @note The GPIO will be configured as output implicitly.
377 : */
378 1 : int mdm_sim7080_set_gpio(int gpio, int level);
379 :
380 : /**
381 : * Start a ftp get session.
382 : *
383 : * @param server The ftp servers address.
384 : * @param user User name for the ftp server.
385 : * @param passwd Password for the ftp user.
386 : * @param file File to be downloaded.
387 : * @param path Path to the file on the server.
388 : * @return 0 if the session was started. Otherwise -1 is returned.
389 : */
390 1 : int mdm_sim7080_ftp_get_start(const char *server, const char *user, const char *passwd,
391 : const char *file, const char *path);
392 :
393 : /**
394 : * Read data from a ftp get session.
395 : *
396 : * @param dst The destination buffer.
397 : * @param size Initialize to the size of dst. Gets set to the number
398 : * of bytes actually read.
399 : * @return According sim7080_ftp_rc.
400 : */
401 1 : int mdm_sim7080_ftp_get_read(char *dst, size_t *size);
402 :
403 : /**
404 : * Read voltage, charge status and battery connection level.
405 : *
406 : * @param bcs [out] Charge status.
407 : * @param bcl [out] Battery connection level.
408 : * @param voltage [out] Battery voltage in mV.
409 : * @return 0 on success. Otherwise a negative error is returned.
410 : */
411 1 : int mdm_sim7080_get_battery_charge(uint8_t *bcs, uint8_t *bcl, uint16_t *voltage);
412 :
413 : /**
414 : * Read the ue system information
415 : *
416 : * @param info Destination buffer for information.
417 : * @return 0 on success. Otherwise a negative error is returned.
418 : */
419 1 : int mdm_sim7080_get_ue_sys_info(struct sim7080_ue_sys_info *info);
420 :
421 : /**
422 : * Get the local time of the modem.
423 : *
424 : * @param t Time structure to fill.
425 : * @return 0 on success. Otherwise a negative error is returned.
426 : * @note Time is set by network. It may take some time for it to get valid.
427 : */
428 1 : int mdm_sim7080_get_local_time(struct tm *t);
429 :
430 : /**
431 : * Set the dns query lookup parameters.
432 : *
433 : * @param recount Number of retries per query.
434 : * Maximum @c SIM7080_DNS_MAX_RECOUNT
435 : * @param timeout Timeout for a dns query in milliseconds.
436 : * Maximum @c SIM7080_DNS_MAX_TIMEOUT_MS
437 : * @return 0 on success. Otherwise a negative error is returned.
438 : */
439 1 : int mdm_sim7080_dns_set_lookup_params(uint8_t recount, uint16_t timeout);
440 :
441 : /**
442 : * Get the dns query lookup parameters.
443 : *
444 : * @param recount [out] Number of retries per query.
445 : * @param timeout [out] Timeout for a dns query in milliseconds.
446 : */
447 1 : void mdm_sim7080_dns_get_lookup_params(uint8_t *recount, uint16_t *timeout);
448 :
449 : #ifdef __cplusplus
450 : }
451 : #endif
452 :
453 : #endif /* ZEPHYR_INCLUDE_DRIVERS_MODEM_SIMCOM_SIM7080_H */
|
