add gpsd directive to the ULTRAFEEDER-CONFIG param; update documentation

README.md

@@ -38,6 +38,9 @@
       - [Configuring the Core Temperature graphs](#configuring-the-core-temperature-graphs)
       - [Reducing Disk IO for Graphs1090](#reducing-disk-io-for-graphs1090)
     - [`timelapse1090` Configuration](#timelapse1090-configuration)
+  - [Updating your location with GPSD](#updating-your-location-with-gpsd)
+    - [Basic Installation and Configuration of your GPS hardware and `gpsd` drivers](#basic-installation-and-configuration-of-your-gps-hardware-and-gpsd-drivers)
+    - [Optional parameters regulating the restart of `mlat-client` when the location changes](#optional-parameters-regulating-the-restart-of-mlat-client-when-the-location-changes)
   - [Web Pages](#web-pages)
   - [Paths](#paths)
   - [Display of Metrix with Grafana and Prometheus/InfluxDB](#display-of-metrix-with-grafana-and-prometheusinfluxdb)
@@ -728,6 +731,64 @@ Legacy: **We recommend AGAINST enabling this feature** as it has been replaced w
 | `TIMELAPSE1090_INTERVAL` | Snapshot interval in seconds                                                                                                    | `10`    |
 | `TIMELAPSE1090_HISTORY`  | Time saved in hours                                                                                                             | `24`    |
 
+## Updating your location with GPSD
+
+This feature enables you to deploy Ultrafeeder while you are moving around. It will read your current longitude/latitude/altitude from a GPS unit that is connected to `gpsd` on your host system, and ensure that the map will show your current location. It will also restart any `mlat-client` instances once it detects that you moved from your previous location.
+
+### Basic Installation and Configuration of your GPS hardware and `gpsd` drivers
+
+The simplest way of getting this to work is to acquire a ["VK163" USB GPS "Mouse"](https://a.co/d/0D7Tj0n), similar to the one in the link. You can connect this mouse to any USB port on your machine.
+
+For this to work, you should install and configure GPSD to work on your host machine. The `DEVICES` parameter is probably correct as shown below, but you may want to double-check that data is received on that device (`cat /dev/ttyACM0`) and adjust it if needed:
+
+```bash
+sudo apt update && sudo apt install -y gpsd
+cat < EOM | sudo tee /etc/default/gpsd
+# Devices gpsd should collect to at boot time.
+# They need to be read/writeable, either by user gpsd or the group dialout.
+DEVICES="/dev/ttyACM0"
+# Other options you want to pass to gpsd
+GPSD_OPTIONS="-G"
+# Automatically hot add/remove USB GPS devices via gpsdctl
+USBAUTO="true"
+EOM
+sudo systemctl restart gpsd
+```
+
+Then, you can add the following values to `ultrafeeder` service settings in `docker-compose.yml`:
+
+```yaml
+services:
+...
+  ultrafeeder:
+    ...
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    ...
+    environment:
+      ULTRAFEEDER-CONFIG=
+        gpsd,host.docker.internal,2947;
+    ...
+```
+
+Finally, restart the container with `docker compose up -d`
+
+This will:
+
+- install and configure `gpsd` (`/etc/default/gpsd`) so it makes GPS data available on the default TCP port 2947 of your host system
+- configure the ultrafeeder docker container to read GPSD data
+- configure the ultrafeeder container so the hostname `host.docker.internal` always resolves to the IP address of the underlying machine (where `gpsd` is running)
+
+### Optional parameters regulating the restart of `mlat-client` when the location changes
+
+The following parameters are all optional. You don't need to set them unless you want to change the default behavior:
+
+| Environment Variable | Purpose | Default |
+| -------------------- | ------- | ------- |
+| `GPSD_INITIAL_WAIT` | The initial wait period (in seconds) for the GPS data to stabilize once the container detects that GPS data is being provided | `60` (seconds) |
+| `GPSD_MIN_DISTANCE` | Distance (in meters) that your station must move before the `mlat-client`(s) are restarted with the new latitude/longitude/altitude | `20` (meters) |
+| `GPSD_CHECK_INTERVAL` | How often the container checks for updated location information. Please don't make this shorter than 30 seconds to avoid race conditions, which may cause mlat-client to stop feeding some of the aggregators | `30` (seconds) |
+
 ## Web Pages
 
 If you have configured the container as described above, you should be able to browse to the following web pages:

rootfs/scripts/interpret_ultrafeeder_config

@@ -123,6 +123,15 @@ do
             MLATHUB_CONF_ARR+=("--net-connector=${mlathub_str}")
         ;;
 
+        gpsd)
+            # add gpsd_in parameter to $READSB_CONF_ARR
+            readsb_str="${param[1]},${param[2]}"
+            if [[ -n "${param[3]}" ]] && [[ -n "${param[4]}" ]]; then
+                readsb_str="$readsb_str,${param[3]},${param[4]}"
+            fi
+            READSB_CONF_ARR+=("--net-connector=${readsb_str},gpsd_in")
+        ;;
+
         *)
             # Check if there's anything in ${ULTRAFEEDER_NET_CONNECTOR} -- if not, it's a bad config element. If yes, add it as if it were ADSB
             if [[ -z "${ULTRAFEEDER_NET_CONNECTOR}" ]]; then