From 50e168cf73bff76d0e3eb7b6eb7223a0e815cd19 Mon Sep 17 00:00:00 2001
From: Mat Booth <mat.booth@gmail.com>
Date: Fri, 22 May 2026 17:51:43 +0100
Subject: [PATCH] GPS Firmware API/Events

Major changes:

* Remove the graphical app portion, the firmware now runs in the
  background only
* Provide 3 API methods for getting the current position as a (lat, lon)
  tuple, ground speed in knots, and course in degrees from true north
* Add a GPSEvent type and emit events every time a location fix message is
  received from the GPS
* In both the API and the GPSEvent, when the fix is lost, the position
  value will be None instead of a tuple

Other fixes:

* Firmware version bumped to 2
* Add a character timeout to the UART configuration to improve the
  ability of uart.readline() to read a full line, and reduce parsing
  errors caused by reading partial lines
* Override background_task to manage sleep for longer between UART
  message bursts, to reduce the impact of the blocking UART timeout on
  other apps
---
 EEPROM/gps.mpy | Bin 1470 -> 1352 bytes
 EEPROM/gps.py  | 163 ++++++++++++++++++++++++++++++-------------------
 2 files changed, 100 insertions(+), 63 deletions(-)

diff --git a/EEPROM/gps.mpy b/EEPROM/gps.mpy
index 5f3d9dda6cac3bddbaecc36a57f3a97ebac38838..ca6ece88edb4192a16a6ff31759fadf44405ba65 100644
GIT binary patch
literal 1352
zcmYjO-*3}a6h3y+Gz}qfY~vZ)fg7hZ$x44@!N4FaZ5#?{K-|`YOxmK<af>O5BiltS
z(=^+(Tg9}uz3g>Qd$bey1NikcX%bJP(zHEH`v<m%z3w^%Hd*(4-#Pc*?|$d_S_Dok
z;>W7h+R}|{GwWS*y1Na@NVD68MAO{vD4GsYOKYnTtKL&P7R1#6Odtlhx@p33bKA7k
z_Vn9ARGwd2fk;j3K%(7LZfhMC;)}KAc_bPM0)dhPH9oHBoi%M8$VOK;HA~YwKr~j>
zrlED#A>J^%s@j6Er310r+-w<5OGVihM7l^kY-~Xy@TPBC5Z!DV7T^X%wT_0;w%$@9
zazkDLw~F5f;;nq*je6`r{P=29*;qI9%}%RfHO&nmEKS)k8*LNl1J=^k)*$`AW1HPp
zV1zL5s%kel=zJM(sY>voJLmHF6vQ)&wWVv70Ivs#&jY>;_)UnaZRGB}lN)O^(2yJI
zR#!KyMgwL}olbmQU0S|!<2o{H=v~#Yw&9RVxu@Ii;aE$(Yc(OZc2{p&z{(vhc&%y}
zx&ivU6b;Qz&kkkLSh+QAi~IbGDQ?glV%$bYx6CQ-b=Ro!)Pvm>mc&k;yfigsd~4a#
zD9+$0hL{kFVJ2)7LwRg8GB(5v)oo%J@#xqvGmQ8M5zFJFhsH*jk+B#PtFIJ*h^KJs
za52QhQ*lO+6l}N1@$tP_x$@1(!_nL2;M+++>I`$1h%@J0=7Zo;A~l4rB&0mH?2Tg>
zlT4j2;6;oXM;JnwMi@rO7lxQjA;L_0%CPeh#1ebSR(YV6V9phQNft1sC@Hv8`!P%=
zOXGanCNde{W5;_Q%lADtEh)}yE?O+vM|g}r?NQ?%#d}m*2q}AK|G=`z3njv4?@aKm
z%!FFboKUhe8hLR7{3A&L>OJW<u|j^R_I#F*d^W{{&yqo)9{MazjyS}TwEYthOpkiU
zmI)StBNIn`iZ1S9K6?!1uI#g;J~c{@5$}>Q>bT%SJxEVD0#>(umXnlQBeC(4UF19}
z74US)K8HA|IB+z^m+XriS@tN(E#k^f?Ma!<l<Wm=lAFw}m(P%4dP0CF2k;cZ$(}FZ
z&pdjvFJRBf5S@J_R=!_YOgr~IivC-`K9g?OdruY;lJecHdzU9m^L9<k<+O=>M$BgT
z*|}V)l;yMhT>cI>*=n7g=F{Fyiu3>cghiH+YXQV1kK)p{@=ClisMx3v<otE{=j1E#
zvgENT+hZw@I!5ONc-j+xbuPcadURd@`aQI!h*JXgtdB-Ey<fQ!;LN`GgVT3qVs>BL
zama=K16gvXak+>MxGN2K`ocedJx7IIS$gnhb60-w-{y<{j!ew$i<L(&pZC9#i2|aJ
zU%nvAk9LbVS$>RS9!Ktw#@9$2c|>e)z(_P>=NC~7jHAVo!}R+eoj|Rj4fH#N5Nh-)
Zd6TS=B3UIb<-@;=mHJie(<P;*{0mq~bt3=(

literal 1470
zcmYjO&vVmO5MIfSt0s<lksKk2AwhN$$4#8z8Urc663al`#IbA(>dr96mX+XQOR6Q)
zzy(<$P&&gu(dmJsmB94g!l^TzVR|UcFzu=T0GA%=lM~u%p5DIwzVGes+g<a)_%-rq
zCX+9$ug!1jMqIxOhkR9ChoiNQX=-YvS*<Be17aAf$XZL+R7Ew7xT)P%R09IbeU$;+
zvQ#Rq=PIRgK2rovxzkrQRJ~&Y>U*`00mqHIhN-mT{{qQ^@^wcs%*$F^*=%bawVv-7
zw=(W+m^$E!rlv3H`aT#xh+xRKlzOMBwD)5fKuJr568Q2B6#}iQe5;`<;J=bD;+x=e
zx3FK<)Q!d__;joxO(3^`Yy(*XvI(eG?bO><Qvt8J1>QEMIzTnlh6z+lt1IAJmr7t~
z$a{crQ>w;YRR+=ke_iQ|?2Fwwe|jmG&a6Ur7_~6iY8VPoN(+bJYgPI7{_`pwz3!&z
z-p5yEH?n=w4wJLsk6g(Y*3z!cxt3f4vIyjLAXT7nY2N_7p{ZuYXxziqv^Q%&w-wo}
zs+&!mW~0$;;&*Fzl!~bVWhz@H`0(q2TCJLkc-PcL;N+?*E6x3p0=0~bf>5R6PFC5{
zwYFKQ!2H~)z_m=FxU!yuA)B#JwY(MFlu8{2H=0`21bf~d<|MV@)}Cp%wKix=-ii#A
zXCa;#@E4V8+im`4JRXNfAudSVoSIF{CJIk-mN-VTq=h^&V$2)zu%5Do29PgCj(rpw
zU<X1z)`t-avmb{jmcr*jG=y1yXpkKY4Y5NQ8Abt&910Dy!=V5hD3=m|&<M$lBt0w|
zL98Ik#P&IE41GH^5&n*@-+aJ47=@7xdl@12N|(JV#)x9?1Q0BpAlOKPWTz4yb~fQ<
z&-CPh#}mI1Q}jxfu>!Hla3qSq$l3XsI{o=1IHPn5%DdtpLYiJxb{&q{WrCLEaHH6E
zv1PHfu{}%=I7!0cIMLyb(8FDHl(&8XH0Cg)DC96~@*yUVIn3eUaWqZ`n2D4PW!F8?
zO%dh$4#(3}Fia0QOvFif%A#yXzrTbc*)?loVtU45$le=4?0wMpm}9|7T$m_7`Xa_p
zWpmclL_B(VdUa)HW@R$gW4Pcn?L$#1MF=_9o5A8<Fy`(IZ~ZQ;;%uMLgS{kyv-hqu
zyz|$W9N&+h0-=CKyd}RDR{DtLYM3K#Bn<z0=(T`L;f{#%6J3qZ;^b#1qC$9KJj|az
z9}P#tb92+PZiRCx_-R-8v3vCgVmBC1L2w@b3+QBu_<7HgP~xp{)wQ3#O&9iT2_@gA
zvwPc;klEXj(#xVuuVYWN<D`@%`e$40pZRltzk7j!9ZB5&K<-G}|B)~E9!Tia8zKGd
z)r-A{5=!CY^H(qFJS{%kNs>td7w<aH51i9hkK?oGI$fZPbSdWfQ%IMy#0^n?%q?<f
zvXYgHTsS?MyteSv;m$h2MJo(e$`kyIe^0rqtK*gO2G8N{x@^}a&+|9<T#5`{Ko<|X
t_mzXe_q5dqFX4W^!^A%Jw2v+InA0w{od2IP><)<bIA|HAlQw}T{tsP8l=}bx

diff --git a/EEPROM/gps.py b/EEPROM/gps.py
index 3e36ce0..716d6dc 100644
--- a/EEPROM/gps.py
+++ b/EEPROM/gps.py
@@ -1,89 +1,126 @@
-# Minimal length method names to make the mpy file as small as possible so it will fit in the 2k hexpansion EEPROM.
-# Minimal functionality to get a GPS fix and display it
-#
 import app
-from app_components.tokens import button_labels
-from events.input import Buttons, BUTTON_TYPES
+import asyncio
+import time
+
+from events import Event
 from system.eventbus import eventbus
-from system.scheduler.events import RequestForegroundPushEvent, RequestStopAppEvent
 from machine import UART, Pin
 
-class GPSApp(app.App):         # pylint: disable=no-member
-    """ App to get GPS data from a GPS module connected to the hexpansion and display it on the badge. """
-    VERSION = 1             # Increment this when making changes to the app that require the hexpansion app to be re-flashed with the new code.
+
+class GPSApp(app.App):
+    """Provides a GPS API for apps to use directly and GPS Events that other apps may subscribe to."""
+
+    VERSION = 2 # Increment this when making changes to the app that require the hexpansion app to be re-flashed with the new code.
+
+    class GPSEvent(Event):
+        def __init__(self, position, speed, bearing):
+            self.position = position
+            self.speed = speed
+            self.bearing = bearing
+
+        def __str__(self):
+            return f"GPS fix {self.position}, speed {self.speed} knots, bearing {self.bearing}°"
+
     def __init__(self, config=None):
         super().__init__()
+
+        # Config is mandatory, we're running from the EEPROM
         if config is None:
-            raise TypeError     # The app should not be run without a config as it won't work (shouldn't happen anyway if run from the hexpansion EEPROM)
-        self.config = config    # Enables HexManager to check which port app is associated with
-        self.t = config.pin[0]
-        self.x = config.pin[1]
+            raise TypeError
+        self.config = config
+
+        # GPS fix data
+        self._position = None
+        self._bearing = 0.0
+        self._speed = 0.0
+
+        # Specifying a small time out to wait before giving up on receiving
+        # more characters ensures we always read full messages from the UART
+        # This reduces parse errors due to only having half a message
+        self.to = 10
+        self.uart = UART(1, baudrate=9600, tx=config.pin[0], rx=config.pin[1], timeout=self.to)
+
+        # Reset pin
         self.r = config.pin[2]
-        self.b = Buttons(self)
-        self.l = None           # Last GPS fix as a string in the format "lat,lon" or None if no fix yet. Latitude and longitude are rounded to 5 decimal places which gives a precision of about 1 meter, more than enough for badgebot's purposes.
-        self.u = UART(1, baudrate=9600, tx=self.t, rx=self.x)
         self.r.init(mode=Pin.OUT)
         self.r.value(1)
-        self.z = -1             # Ticks timer - time since GPS reset, used to control when to release the GPS from reset after resetting it
-                                # and then used to time how long since last valid GPS fix.
-                                # also used as a flag (-1) to indicate that ForegroundPushEvent has not yet been emitted
-        eventbus.on_async(RequestStopAppEvent, self.s, self)
 
-    async def s(self, _e: RequestStopAppEvent):
-        """ handle app stop """
-        if _e.app == self:
-            self.r.value(1)
-            self.u.deinit()
+        # Time since last valid GPS fix
+        self.z = 0
+
+    @property
+    def position(self):
+        """Position as a (latitude, longitude) tuple"""
+        return self._position
+
+    @property
+    def bearing(self):
+        """Course over ground in degrees from true north"""
+        return self._bearing
 
-    def update(self, _d):
-        """ Update the app state - expire last_fix if it is too old """
-        if self.b.get(BUTTON_TYPES["CANCEL"]):
-            self.b.clear()
-            self.minimise()
+    @property
+    def speed(self):
+        """Ground speed in knots"""
+        return round(self._speed, 2)
 
-        if self.z < 0:
-            eventbus.emit(RequestForegroundPushEvent(self))
+    async def background_task(self):
+        """Override the default background task behaviour to give more time to other apps"""
+        last = time.ticks_ms()
+        while True:
+            start = time.ticks_ms()
+            delta = time.ticks_diff(start, last)
+            result = self.background_update(delta)
+            # Get successive messages fast, but yield more time to other apps
+            # if there was nothing to read, this lowers the frequency of
+            # occurrances of blocking for the full read timeout to elapse when
+            # nothing is being sent over the UART
+            await asyncio.sleep_ms(25 if result else 250 - self.to)
+            last = start
 
-        self.z +=_d
+    def background_update(self, delta):
+        self.z += delta
 
+        # Delay releasing the reset pin a little bit
         if self.r.value():
             if self.z > 99:
                 self.r.value(0)
 
-        if self.l:
+        # Clear fix data if we haven't had a fix for a while
+        if self._position:
             if self.z > 9999:
-                self.l = None
+                self._position = None
+                self._speed = 0
 
-    def background_update(self, _d):
-        """ Update the app state in the background - read GPS data """
-        l = self.u.readline()
+        l = self.uart.readline()
         if l:
-            #print(l)
             try:
                 p = l.decode().strip().split(',')
-                if (p[0] != "$GPRMC" and p[0] != "$GNRMC") or p[2] != "A" or not p[3] or not p[5]:
-                    return None
-                t = float(p[3][:2]) + float(p[3][2:]) / 60
-                n = float(p[5][:3]) + float(p[5][3:]) / 60
-                if p[4] == "S":
-                    t = -t
-                if p[6] == "W":
-                    n = -n
-                self.l = str(round(t, 5))
-                self.n = str(round(n, 5))
-                self.z = 0
-            except (UnicodeError, ValueError, AttributeError):
+                if p[0] == "$GPRMC" or p[0] == "$GNRMC":
+                    if p[2] == "A":
+                        lat = float(p[3][:2]) + float(p[3][2:]) / 60
+                        lon = float(p[5][:3]) + float(p[5][3:]) / 60
+                        if p[4] == "S":
+                            lat = -lat
+                        if p[6] == "W":
+                            lon = -lon
+                        self._position = (round(lat, 5), round(lon, 5))
+                        self._speed = float(p[7])
+                        self._bearing = float(p[8])
+
+                        # Eliminate satellite jitter when stationary by rounding
+                        # very small velocities to zero
+                        if self._speed < 1:
+                            self._speed = 0
+
+                        # Reset the time since last fix if we successfully got a valid fix message
+                        self.z = 0
+
+                    # Send event to subscribers
+                    eventbus.emit(self.GPSEvent(self._position, self._speed, self._bearing))
+            except (UnicodeError, ValueError, AttributeError, IndexError):
                 pass
+            return True
+        return False
+
 
-    def draw(self, _c):
-        _c.font_size = 40   # not using defined sizes to save bytes in the mpy file
-        _c.rgb(0, 0.2, 0).rectangle(-120, -120, 240, 240).fill()
-        _c.rgb(0, 1, 0).move_to(-35, -50).text("GPS")
-        if self.l:
-            _c.move_to(-110,  0).text("Lat:" + self.l)
-            _c.move_to(-110, 40).text("Lon:" + self.n)
-        else:
-            _c.move_to(-110,  0).text("Searching...")
-        button_labels(_c, cancel_label="Back")
-
-__app_export__ = GPSApp     #pylint: disable=invalid-name
+__app_export__ = GPSApp # pylint: disable=invalid-name