diff --git a/README.md b/README.md index bfc00f8..a53c174 100644 --- a/README.md +++ b/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: diff --git a/rootfs/scripts/interpret_ultrafeeder_config b/rootfs/scripts/interpret_ultrafeeder_config index 811783d..ce70123 100755 --- a/rootfs/scripts/interpret_ultrafeeder_config +++ b/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