From 219bb4e9867d318bf609a151c10ebafc9270dffc Mon Sep 17 00:00:00 2001
From: Silvano Seva <silseva@fastwebnet.it>
Date: Tue, 12 Aug 2025 19:23:01 +0200
Subject: [PATCH] core: gps: added new API for GPS device management

---
 openrtx/include/core/gps.h            | 47 ++++++++++++++++++++++++++-
 openrtx/include/interfaces/platform.h |  9 +++++
 tests/unit/convert_minmea_coord.c     |  1 +
 3 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/openrtx/include/core/gps.h b/openrtx/include/core/gps.h
index 0fb32de6..a1e0b33d 100644
--- a/openrtx/include/core/gps.h
+++ b/openrtx/include/core/gps.h
@@ -21,8 +21,8 @@
 #define GPS_H
 
 #include <datetime.h>
+#include <stddef.h>
 #include <stdint.h>
-#include <minmea.h>
 
 /**
  * Data structure representing a single satellite as part of a GPS fix.
@@ -57,6 +57,51 @@ typedef struct
 }
 gps_t;
 
+/**
+ * Data structure for GPS device managment.
+ */
+struct gpsDevice {
+    void *priv;
+    void (*enable)(void *priv);
+    void (*disable)(void *priv);
+    int  (*getSentence)(void *priv, char *buf, const size_t bufSize);
+};
+
+/**
+ * Enable the GPS.
+ *
+ * @param dev: pointer to GPS device handle.
+ */
+static inline void gps_enable(const struct gpsDevice *dev)
+{
+    dev->enable(dev->priv);
+}
+
+/**
+ * Disable the GPS.
+ *
+ * @param dev: pointer to GPS device handle.
+ */
+static inline void gps_disable(const struct gpsDevice *dev)
+{
+    dev->disable(dev->priv);
+}
+
+/**
+ * Get a full NMEA sentence from the GPS.
+ * This function is nonblocking.
+ *
+ * @param dev: pointer to GPS device handle.
+ * @param buf: pointer to a buffer where to write the sentence.
+ * @param bufSize: size of the destination buffer.
+ * @return the length of the extracted sentence, -1 if the sentence is
+ * longer than the maximum allowed size or zero if no sentence is available.
+ */
+static inline int gps_getSentence(const struct gpsDevice *dev, char *buf, const size_t bufSize)
+{
+    return dev->getSentence(dev->priv, buf, bufSize);
+}
+
 /**
  * This function perfoms the task of reading data from the GPS module,
  * if available, enabled and ready, decode NMEA sentences and update
diff --git a/openrtx/include/interfaces/platform.h b/openrtx/include/interfaces/platform.h
index 18226e15..5561775f 100644
--- a/openrtx/include/interfaces/platform.h
+++ b/openrtx/include/interfaces/platform.h
@@ -75,6 +75,7 @@ typedef struct
 
 } hwInfo_t;
 
+struct gpsDevice;
 
 /**
  * This function handles device hardware initialization.
@@ -168,6 +169,14 @@ void platform_setTime(datetime_t t);
  */
 const hwInfo_t *platform_getHwInfo();
 
+#ifdef CONFIG_GPS
+/**
+ * Detect and initialize the on-board GPS.
+ * @return a GPS device handle or NULL if no device has been detected.
+ */
+const struct gpsDevice *platform_initGps();
+#endif
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/tests/unit/convert_minmea_coord.c b/tests/unit/convert_minmea_coord.c
index fe01793f..34899cf5 100644
--- a/tests/unit/convert_minmea_coord.c
+++ b/tests/unit/convert_minmea_coord.c
@@ -1,3 +1,4 @@
+#include <minmea.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <gps.h>