Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Trackunit Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file gnss.h
9 : * @brief Public GNSS API.
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_GNSS_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_GNSS_H_
14 :
15 : /**
16 : * @brief GNSS Interface
17 : * @defgroup gnss_interface GNSS Interface
18 : * @since 3.6
19 : * @version 0.1.0
20 : * @ingroup io_interfaces
21 : * @{
22 : */
23 :
24 : #include <zephyr/kernel.h>
25 : #include <zephyr/types.h>
26 : #include <zephyr/device.h>
27 : #include <zephyr/data/navigation.h>
28 : #include <errno.h>
29 :
30 : #ifdef __cplusplus
31 : extern "C" {
32 : #endif
33 :
34 : /** GNSS PPS modes */
35 1 : enum gnss_pps_mode {
36 : /** PPS output disabled */
37 : GNSS_PPS_MODE_DISABLED = 0,
38 : /** PPS output always enabled */
39 : GNSS_PPS_MODE_ENABLED = 1,
40 : /** PPS output enabled from first lock */
41 : GNSS_PPS_MODE_ENABLED_AFTER_LOCK = 2,
42 : /** PPS output enabled while locked */
43 : GNSS_PPS_MODE_ENABLED_WHILE_LOCKED = 3
44 : };
45 :
46 : /** API for setting fix rate */
47 1 : typedef int (*gnss_set_fix_rate_t)(const struct device *dev, uint32_t fix_interval_ms);
48 :
49 : /** API for getting fix rate */
50 1 : typedef int (*gnss_get_fix_rate_t)(const struct device *dev, uint32_t *fix_interval_ms);
51 :
52 : /** GNSS navigation modes */
53 1 : enum gnss_navigation_mode {
54 : /** Dynamics have no impact on tracking */
55 : GNSS_NAVIGATION_MODE_ZERO_DYNAMICS = 0,
56 : /** Low dynamics have higher impact on tracking */
57 : GNSS_NAVIGATION_MODE_LOW_DYNAMICS = 1,
58 : /** Low and high dynamics have equal impact on tracking */
59 : GNSS_NAVIGATION_MODE_BALANCED_DYNAMICS = 2,
60 : /** High dynamics have higher impact on tracking */
61 : GNSS_NAVIGATION_MODE_HIGH_DYNAMICS = 3
62 : };
63 :
64 : /** API for setting navigation mode */
65 1 : typedef int (*gnss_set_navigation_mode_t)(const struct device *dev,
66 : enum gnss_navigation_mode mode);
67 :
68 : /** API for getting navigation mode */
69 1 : typedef int (*gnss_get_navigation_mode_t)(const struct device *dev,
70 : enum gnss_navigation_mode *mode);
71 :
72 : /** Systems contained in gnss_systems_t */
73 1 : enum gnss_system {
74 : /** Global Positioning System (GPS) */
75 : GNSS_SYSTEM_GPS = BIT(0),
76 : /** GLObal NAvigation Satellite System (GLONASS) */
77 : GNSS_SYSTEM_GLONASS = BIT(1),
78 : /** Galileo */
79 : GNSS_SYSTEM_GALILEO = BIT(2),
80 : /** BeiDou Navigation Satellite System */
81 : GNSS_SYSTEM_BEIDOU = BIT(3),
82 : /** Quasi-Zenith Satellite System (QZSS) */
83 : GNSS_SYSTEM_QZSS = BIT(4),
84 : /** Indian Regional Navigation Satellite System (IRNSS) */
85 : GNSS_SYSTEM_IRNSS = BIT(5),
86 : /** Satellite-Based Augmentation System (SBAS) */
87 : GNSS_SYSTEM_SBAS = BIT(6),
88 : /** Indoor Messaging System (IMES) */
89 : GNSS_SYSTEM_IMES = BIT(7),
90 : };
91 :
92 : /** Type storing bitmask of GNSS systems */
93 1 : typedef uint32_t gnss_systems_t;
94 :
95 : /** API for enabling systems */
96 1 : typedef int (*gnss_set_enabled_systems_t)(const struct device *dev, gnss_systems_t systems);
97 :
98 : /** API for getting enabled systems */
99 1 : typedef int (*gnss_get_enabled_systems_t)(const struct device *dev, gnss_systems_t *systems);
100 :
101 : /** API for getting enabled systems */
102 1 : typedef int (*gnss_get_supported_systems_t)(const struct device *dev, gnss_systems_t *systems);
103 :
104 : /** API for getting timestamp of last PPS pulse */
105 1 : typedef int (*gnss_get_latest_timepulse_t)(const struct device *dev, k_ticks_t *timestamp);
106 :
107 : /** GNSS fix status */
108 1 : enum gnss_fix_status {
109 : /** No GNSS fix acquired */
110 : GNSS_FIX_STATUS_NO_FIX = 0,
111 : /** GNSS fix acquired */
112 : GNSS_FIX_STATUS_GNSS_FIX = 1,
113 : /** Differential GNSS fix acquired */
114 : GNSS_FIX_STATUS_DGNSS_FIX = 2,
115 : /** Estimated fix acquired */
116 : GNSS_FIX_STATUS_ESTIMATED_FIX = 3,
117 : };
118 :
119 : /** GNSS fix quality */
120 1 : enum gnss_fix_quality {
121 : /** Invalid fix */
122 : GNSS_FIX_QUALITY_INVALID = 0,
123 : /** Standard positioning service */
124 : GNSS_FIX_QUALITY_GNSS_SPS = 1,
125 : /** Differential GNSS */
126 : GNSS_FIX_QUALITY_DGNSS = 2,
127 : /** Precise positioning service */
128 : GNSS_FIX_QUALITY_GNSS_PPS = 3,
129 : /** Real-time kinematic */
130 : GNSS_FIX_QUALITY_RTK = 4,
131 : /** Floating real-time kinematic */
132 : GNSS_FIX_QUALITY_FLOAT_RTK = 5,
133 : /** Estimated fix */
134 : GNSS_FIX_QUALITY_ESTIMATED = 6,
135 : };
136 :
137 : /** GNSS info data structure */
138 1 : struct gnss_info {
139 : /** Number of satellites being tracked */
140 1 : uint16_t satellites_cnt;
141 : /** Horizontal dilution of precision in 1/1000 */
142 1 : uint32_t hdop;
143 : /** The fix status */
144 1 : enum gnss_fix_status fix_status;
145 : /** The fix quality */
146 1 : enum gnss_fix_quality fix_quality;
147 : };
148 :
149 : /** GNSS time data structure */
150 1 : struct gnss_time {
151 : /** Hour [0, 23] */
152 1 : uint8_t hour;
153 : /** Minute [0, 59] */
154 1 : uint8_t minute;
155 : /** Millisecond [0, 60999] */
156 1 : uint16_t millisecond;
157 : /** Day of month [1, 31] */
158 1 : uint8_t month_day;
159 : /** Month [1, 12] */
160 1 : uint8_t month;
161 : /** Year [0, 99] */
162 1 : uint8_t century_year;
163 : };
164 :
165 : /** GNSS API structure */
166 1 : __subsystem struct gnss_driver_api {
167 0 : gnss_set_fix_rate_t set_fix_rate;
168 0 : gnss_get_fix_rate_t get_fix_rate;
169 0 : gnss_set_navigation_mode_t set_navigation_mode;
170 0 : gnss_get_navigation_mode_t get_navigation_mode;
171 0 : gnss_set_enabled_systems_t set_enabled_systems;
172 0 : gnss_get_enabled_systems_t get_enabled_systems;
173 0 : gnss_get_supported_systems_t get_supported_systems;
174 0 : gnss_get_latest_timepulse_t get_latest_timepulse;
175 : };
176 :
177 : /** GNSS data structure */
178 1 : struct gnss_data {
179 : /** Navigation data acquired */
180 1 : struct navigation_data nav_data;
181 : /** GNSS info when navigation data was acquired */
182 1 : struct gnss_info info;
183 : /** UTC time when data was acquired */
184 1 : struct gnss_time utc;
185 : };
186 :
187 : /** Template for GNSS data callback */
188 1 : typedef void (*gnss_data_callback_t)(const struct device *dev, const struct gnss_data *data);
189 :
190 : /** GNSS callback structure */
191 1 : struct gnss_data_callback {
192 : /** Filter callback to GNSS data from this device if not NULL */
193 1 : const struct device *dev;
194 : /** Callback called when GNSS data is published */
195 1 : gnss_data_callback_t callback;
196 : };
197 :
198 : /** GNSS satellite structure */
199 1 : struct gnss_satellite {
200 : /** Pseudo-random noise sequence */
201 1 : uint8_t prn;
202 : /** Signal-to-noise ratio in dB */
203 1 : uint8_t snr;
204 : /** Elevation in degrees [0, 90] */
205 1 : uint8_t elevation;
206 : /** Azimuth relative to True North in degrees [0, 359] */
207 1 : uint16_t azimuth;
208 : /** System of satellite */
209 1 : enum gnss_system system;
210 : /** True if satellite is being tracked */
211 1 : uint8_t is_tracked : 1;
212 : };
213 :
214 : /** Template for GNSS satellites callback */
215 1 : typedef void (*gnss_satellites_callback_t)(const struct device *dev,
216 : const struct gnss_satellite *satellites,
217 : uint16_t size);
218 :
219 : /** GNSS callback structure */
220 1 : struct gnss_satellites_callback {
221 : /** Filter callback to GNSS data from this device if not NULL */
222 1 : const struct device *dev;
223 : /** Callback called when GNSS satellites is published */
224 1 : gnss_satellites_callback_t callback;
225 : };
226 :
227 : /**
228 : * @brief Set the GNSS fix rate
229 : *
230 : * @param dev Device instance
231 : * @param fix_interval_ms Fix interval to set in milliseconds
232 : *
233 : * @return 0 if successful
234 : * @return -errno negative errno code on failure
235 : */
236 1 : __syscall int gnss_set_fix_rate(const struct device *dev, uint32_t fix_interval_ms);
237 :
238 : static inline int z_impl_gnss_set_fix_rate(const struct device *dev, uint32_t fix_interval_ms)
239 : {
240 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
241 :
242 : if (api->set_fix_rate == NULL) {
243 : return -ENOSYS;
244 : }
245 :
246 : return api->set_fix_rate(dev, fix_interval_ms);
247 : }
248 :
249 : /**
250 : * @brief Get the GNSS fix rate
251 : *
252 : * @param dev Device instance
253 : * @param fix_interval_ms Destination for fix interval in milliseconds
254 : *
255 : * @return 0 if successful
256 : * @return -errno negative errno code on failure
257 : */
258 1 : __syscall int gnss_get_fix_rate(const struct device *dev, uint32_t *fix_interval_ms);
259 :
260 : static inline int z_impl_gnss_get_fix_rate(const struct device *dev, uint32_t *fix_interval_ms)
261 : {
262 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
263 :
264 : if (api->get_fix_rate == NULL) {
265 : return -ENOSYS;
266 : }
267 :
268 : return api->get_fix_rate(dev, fix_interval_ms);
269 : }
270 :
271 : /**
272 : * @brief Set the GNSS navigation mode
273 : *
274 : * @param dev Device instance
275 : * @param mode Navigation mode to set
276 : *
277 : * @return 0 if successful
278 : * @return -errno negative errno code on failure
279 : */
280 1 : __syscall int gnss_set_navigation_mode(const struct device *dev,
281 : enum gnss_navigation_mode mode);
282 :
283 : static inline int z_impl_gnss_set_navigation_mode(const struct device *dev,
284 : enum gnss_navigation_mode mode)
285 : {
286 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
287 :
288 : if (api->set_navigation_mode == NULL) {
289 : return -ENOSYS;
290 : }
291 :
292 : return api->set_navigation_mode(dev, mode);
293 : }
294 :
295 : /**
296 : * @brief Get the GNSS navigation mode
297 : *
298 : * @param dev Device instance
299 : * @param mode Destination for navigation mode
300 : *
301 : * @return 0 if successful
302 : * @return -errno negative errno code on failure
303 : */
304 1 : __syscall int gnss_get_navigation_mode(const struct device *dev,
305 : enum gnss_navigation_mode *mode);
306 :
307 : static inline int z_impl_gnss_get_navigation_mode(const struct device *dev,
308 : enum gnss_navigation_mode *mode)
309 : {
310 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
311 :
312 : if (api->get_navigation_mode == NULL) {
313 : return -ENOSYS;
314 : }
315 :
316 : return api->get_navigation_mode(dev, mode);
317 : }
318 :
319 : /**
320 : * @brief Set enabled GNSS systems
321 : *
322 : * @param dev Device instance
323 : * @param systems Systems to enable
324 : *
325 : * @return 0 if successful
326 : * @return -errno negative errno code on failure
327 : */
328 1 : __syscall int gnss_set_enabled_systems(const struct device *dev, gnss_systems_t systems);
329 :
330 : static inline int z_impl_gnss_set_enabled_systems(const struct device *dev,
331 : gnss_systems_t systems)
332 : {
333 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
334 :
335 : if (api->set_enabled_systems == NULL) {
336 : return -ENOSYS;
337 : }
338 :
339 : return api->set_enabled_systems(dev, systems);
340 : }
341 :
342 : /**
343 : * @brief Get enabled GNSS systems
344 : *
345 : * @param dev Device instance
346 : * @param systems Destination for enabled systems
347 : *
348 : * @return 0 if successful
349 : * @return -errno negative errno code on failure
350 : */
351 1 : __syscall int gnss_get_enabled_systems(const struct device *dev, gnss_systems_t *systems);
352 :
353 : static inline int z_impl_gnss_get_enabled_systems(const struct device *dev,
354 : gnss_systems_t *systems)
355 : {
356 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
357 :
358 : if (api->get_enabled_systems == NULL) {
359 : return -ENOSYS;
360 : }
361 :
362 : return api->get_enabled_systems(dev, systems);
363 : }
364 :
365 : /**
366 : * @brief Get supported GNSS systems
367 : *
368 : * @param dev Device instance
369 : * @param systems Destination for supported systems
370 : *
371 : * @return 0 if successful
372 : * @return -errno negative errno code on failure
373 : */
374 1 : __syscall int gnss_get_supported_systems(const struct device *dev, gnss_systems_t *systems);
375 :
376 : static inline int z_impl_gnss_get_supported_systems(const struct device *dev,
377 : gnss_systems_t *systems)
378 : {
379 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
380 :
381 : if (api->get_supported_systems == NULL) {
382 : return -ENOSYS;
383 : }
384 :
385 : return api->get_supported_systems(dev, systems);
386 : }
387 :
388 : /**
389 : * @brief Get the timestamp of the latest PPS timepulse
390 : *
391 : * @note The timestamp is considered valid when the timepulse pin is actively toggling.
392 : *
393 : * @param dev Device instance
394 : * @param timestamp Kernel tick count at the time of the PPS pulse
395 : *
396 : * @retval 0 if successful
397 : * @retval -ENOSYS if driver does not support API
398 : * @retval -ENOTSUP if driver does not have PPS pin connected
399 : * @retval -EAGAIN if PPS pulse is not considered valid
400 : */
401 1 : __syscall int gnss_get_latest_timepulse(const struct device *dev, k_ticks_t *timestamp);
402 :
403 : static inline int z_impl_gnss_get_latest_timepulse(const struct device *dev,
404 : k_ticks_t *timestamp)
405 : {
406 : const struct gnss_driver_api *api = (const struct gnss_driver_api *)dev->api;
407 :
408 : if (api->get_latest_timepulse == NULL) {
409 : return -ENOSYS;
410 : }
411 :
412 : return api->get_latest_timepulse(dev, timestamp);
413 : }
414 :
415 : /**
416 : * @brief Register a callback structure for GNSS data published
417 : *
418 : * @param _dev Device pointer
419 : * @param _callback The callback function
420 : */
421 : #if CONFIG_GNSS
422 : #define GNSS_DATA_CALLBACK_DEFINE(_dev, _callback) \
423 : static const STRUCT_SECTION_ITERABLE(gnss_data_callback, \
424 : _gnss_data_callback__##_callback) = { \
425 : .dev = _dev, \
426 : .callback = _callback, \
427 : }
428 : #else
429 1 : #define GNSS_DATA_CALLBACK_DEFINE(_dev, _callback)
430 : #endif
431 :
432 : /**
433 : * @brief Register a callback structure for GNSS satellites published
434 : *
435 : * @param _dev Device pointer
436 : * @param _callback The callback function
437 : */
438 : #if CONFIG_GNSS_SATELLITES
439 : #define GNSS_SATELLITES_CALLBACK_DEFINE(_dev, _callback) \
440 : static const STRUCT_SECTION_ITERABLE(gnss_satellites_callback, \
441 : _gnss_satellites_callback__##_callback) = { \
442 : .dev = _dev, \
443 : .callback = _callback, \
444 : }
445 : #else
446 1 : #define GNSS_SATELLITES_CALLBACK_DEFINE(_dev, _callback)
447 : #endif
448 :
449 : /**
450 : * @}
451 : */
452 :
453 : #ifdef __cplusplus
454 : }
455 : #endif
456 :
457 : #include <zephyr/syscalls/gnss.h>
458 :
459 : #endif /* ZEPHYR_INCLUDE_DRIVERS_GNSS_H_ */
|
