pull updates from 'main' into 'dev' (#114)

.github/workflows/pre-commit-updates.yaml

@@ -6,19 +6,13 @@ on:
     - cron: 0 0 * * 0
 
 jobs:
-  update:
+  pre-commit-update:
     runs-on: ubuntu-latest
+    name: Updates
     steps:
-      - uses: actions/[email protected]
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: Update pre-commit hooks
+        uses: brokenpip3/[email protected]
         with:
-          fetch-depth: 0
-      - uses: vrslev/[email protected]
-      - uses: peter-evans/[email protected]
-        with:
-          branch: pre-commit-autoupdate
-          title: "chore(deps): Update pre-commit hooks"
-          commit-message: "chore(deps): Update pre-commit hooks"
-          body: Update pre-commit hooks
-          labels: dependencies
-          delete-branch: True
-          assignees: "fredclausen"
+          github-token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1 @@
+.DS_Store

.pre-commit-config.yaml

@@ -41,7 +41,7 @@ repos:
       - id: shellcheck
 
   - repo: https://github.com/sirosen/check-jsonschema
-    rev: 0.28.5
+    rev: 0.29.0
     hooks:
       - id: check-github-actions
       - id: check-github-workflows

README.md

@@ -21,6 +21,7 @@
         - [Alternate Configuration Method with `READSB_NET_CONNECTOR`](#alternate-configuration-method-with-readsb_net_connector)
       - [Optional Networking Parameters](#optional-networking-parameters)
       - [MLAT configuration](#mlat-configuration)
+      - [MLAT troubleshooting](#mlat-troubleshooting)
       - [Configuring the built-in MLAT Hub](#configuring-the-built-in-mlat-hub)
     - [Web Gui (`tar1090`) Configuration](#web-gui-tar1090-configuration)
       - [`tar1090` Core Configuration](#tar1090-core-configuration)
@@ -437,6 +438,34 @@ Note - the optional parameters can be given in any order.
 
 The `MLAT_USER` parameter is passed to the MLAT Client and server, and will show up as a "friendly" name on MLAT related stats at your MLAT aggregator. This parameter can only contain alphanumeric (a-z, A-Z, 0-9) characters, dashes (-), or underscores (_).
 
+#### MLAT troubleshooting
+
+Sometimes, MLAT appears not to be working correctly and you will see messages with high `bad_sync_timeout` values, like this:
+
+```text
+[2024-06-29 11:31:20.385][mlat-client][in.adsb.lol] peer_count:  15 outlier_percent: 4.6 bad_sync_timeout: 870
+```
+
+Here are a few things you may want to try to fix this:
+
+- Ensure your longitude, latitude, and altitude are ACCURATE
+- Make sure your device's clock is synced continuously with a reliable NTP service. We recommend `chronyd` over `systemd.timesyncd`
+- Do not try to send MLAT data from a centralized instance when you are using a remote receiver. Instead, feed MLAT directly from the remote station
+- On Raspberry Pi 3/3B+, disable HealthCheck by adding the following to the ultrafeeder service section in your `docker-compose.yml` file. (This has to do with docker resource spikes that mess with MLAT timing on slower machines like the Pi3/3B+) :
+
+  ```yaml
+    ultrafeeder:
+    ...
+      healthcheck:
+        disable: true
+  ```
+
+- MLAT often fails when you run your receiver on a Virtual Machine rather than directly on the hardware. Avoid virtual machines (including ProxMox and container-in-container setups) or disable MLAT on them
+- For FlightAware MLAT, make sure that your location and altitude are PRECISELY defined in your dashboard on the FlightAware website
+- Never, ever, ever resend MLAT results back to ADSB or MLAT aggregators. Please DO NOT. This will ensure your data is discarded and may get you banned from the aggregator
+- If you feed your data to multiple aggregators, please do not enable MLAT for FlightRadar24 (per their request). Note that MLAT for FR24 using our containerized setup is disabled by default
+
+
 #### Configuring the built-in MLAT Hub
 
 An "MLAT Hub" is an aggregator of MLAT results from several sources. Since the container is capable of sending MLAT data to multiple ADSB aggregators (like adsb.lol/fi/one, etc), we built in a capability to:
@@ -619,6 +648,7 @@ Note - due to design limitations of `readsb`, the `tar1090` graphical interface
 | `GRAPHS1090_DISABLE_CHART_DISK_IOPS`         | Set to `true` to disable the GRAPHS1090 Disk IOPS chart                                                                                   | Unset     |
 | `GRAPHS1090_DISABLE_CHART_DISK_BANDWIDTH`    | Set to `true` to disable the GRAPHS1090 Disk Bandwidth chart                                                                              | Unset     |
 | `ENABLE_AIRSPY`                              | Optional, set to any non-empty value if you want to enable the special AirSpy graphs. See below for additional configuration requirements | Unset     |
+| `URL_AIRSPY`                                 | Optional, set to the URL where the airspy stats are available, for example `http://airspy_adsb`                                           | Unset     |
 
 #### Enabling UAT data
 
@@ -627,30 +657,26 @@ ADS-B over UAT data is transmitted in the 978 MHz band, and this is used in the
 1. Set the following environment parameters:
 
 ```yaml
-- URL_978=http://dump978/skyaware978
+      - ENABLE_978=yes
+      - URL_978=http://dump978/skyaware978
 ```
 
 2. Install the [`docker-dump978` container](https://github.com/sdr-enthusiasts/docker-dump978). Note - only containers downloaded/deployed on/after Feb 8, 2023 will work.
 
-Note that you **must** configure `URL_978` to point at a working skyaware978 website with `aircraft.json` data feed. This means that the URL `http://dump978/skyaware978/data/aircraft.json` must return valid JSON data to this `tar1090` container.
+Note that you \*_must_- configure `URL_978` to point at a working skyaware978 website with `aircraft.json` data feed. This means that the URL `http://dump978/skyaware978/data/aircraft.json` must return valid JSON data to this `tar1090` container.
 
 #### Enabling AirSpy graphs
 
 Users of AirSpy devices can enable extra `graphs1090` graphs by configuring the following:
 
-- Set the following environment parameter:
+1. Set the following environment parameters:
 
 ```yaml
       - ENABLE_AIRSPY=yes
+      - URL_AIRSPY=http://airspy_adsb
 ```
 
-- To provide the container access to the AirSpy statistics, map a volume in your `docker-compose.yml` file as follows:
-
-```yaml
-    volumes:
-      - /run/airspy_adsb:/run/airspy_adsb
-      ...
-```
+2. Install the [`airspy_adsb` container](https://github.com/sdr-enthusiasts/airspy_adsb). Note - only containers downloaded/deployed on/after May 9th, 2024 will work with this method.
 
 #### Enabling Disk IO and IOPS data
 
@@ -802,6 +828,8 @@ This will:
 - 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)
 
+If you have any issues, readsb will use verbose output if you add the `GPSD_DEBUG=true` as an environment variable.
+
 ### Optional parameters regulating the restart of `mlat-client` when the location changes
 
 The following parameters are all optional and are subject to change. You don't need to set them unless you want to change the default behavior:

rootfs/etc/s6-overlay/scripts/mlathub

@@ -29,7 +29,7 @@ if ! [[ "$LOGLEVEL" =~ ^(verbose|error|none)$ ]]; then
     LOGLEVEL="verbose"
 fi
 
-if [[ -z "${MLAT_CONFIG}" ]] && [[ -z "$MLATHUB_NET_CONNECTOR" ]]; then
+if [[ -z "${MLAT_CONFIG}" ]] && [[ -z "$MLATHUB_NET_CONNECTOR" ]] && [[ ${#MLATHUB_CONF_ARR[@]} == 0 ]]; then
     "${s6wrap[@]}" --args echo "No MLAT servers have been defined in MLAT_CONFIG and no external sources have been defined in MLATHUB_NET_CONNECTOR - no need to start MLATHUB"
     exec sleep infinity
 fi

rootfs/etc/s6-overlay/scripts/readsb

@@ -139,6 +139,10 @@ if [ -n "${READSB_DEBUG}" ]; then
     READSB_CMD+=("--debug=$READSB_DEBUG")
 fi
 
+if chk_enabled "$GPSD_DEBUG"; then
+    READSB_CMD+=("--devel=debugGPS")
+fi
+
 # Handle --write-state-only-on-exit
 if chk_enabled "${READSB_WRITE_STATE_ONLY_ON_EXIT}"; then
     READSB_CMD+=("--write-state-only-on-exit")
@@ -272,7 +276,7 @@ if [[ -n "$READSB_NET_VRS_PORT" ]]; then
 fi
 
 # make sure the db file exists, and if it does, use it
-if [[ "$TAR1090_ENABLE_AC_DB" == "true" ]]; then
+if chk_enabled "$TAR1090_ENABLE_AC_DB"; then
     if [[ -e $TAR1090_UPDATE_DIR/aircraft.csv.gz ]]; then
         READSB_CMD+=("--db-file=$TAR1090_UPDATE_DIR/aircraft.csv.gz")
     elif [[ -e $TAR1090_INSTALL_DIR/aircraft.csv.gz ]]; then