Add apl-feed CLI improvements

README.md

@@ -1,117 +1,167 @@
 # airplanes.live feed client
 
-- These scripts aid in setting up your current ADS-B receiver to feed [airplanes.live](https://airplanes.live/).
-- This will not disrupt any existing feed clients already present.
-- When setting up new feeders, a decoder such as [readsb](https://github.com/wiedehopf/adsb-scripts/wiki/Automatic-installation-for-readsb) must be installed separately.
+Use this installer to feed your existing ADS-B receiver data to
+[airplanes.live](https://airplanes.live/). It does not replace your decoder or
+remove other feed clients.
 
-## 1: Find antenna coordinates and elevation
+If you do not already have a decoder installed, install one first, such as
+[readsb](https://github.com/wiedehopf/adsb-scripts/wiki/Automatic-installation-for-readsb).
+
+## Install
+
+Find your antenna coordinates and elevation:
 
 <https://www.freemaptools.com/elevation-finder.htm>
 
-## 2: Install the feed client
+Then install the feed client:
 
 ```
 curl -L -o /tmp/feed.sh https://raw.githubusercontent.com/airplanes-live/feed/main/install.sh
 sudo bash /tmp/feed.sh
 ```
 
-## 3: Use netstat to check that your feed is working
-The feed IP for airplanes.live is 78.46.234.18
+## Check Your Feed
+
+Run:
 
 ```
-netstat -t -n | grep -E '30004|31090'
+sudo apl-feed status
 ```
-Expected Output:
+
+Example:
+
 ```
-tcp        0    182 localhost:43530     78.46.234.18:31090      ESTABLISHED
-tcp        0    410 localhost:47332     78.46.234.18:30004      ESTABLISHED
+airplanes.live feed check
+
+OK    Feed service         running
+OK    MLAT service         running
+OK    Receiver input       connected at 127.0.0.1:30005
+OK    Airplanes.live link  connected
+OK    Feeder ID            11111111-2222-3333-4444-555555555555
+OK    Claim secret         present
+OK    Website claim        registered, not yet claimed (v1)
+OK    Website feed         last data seen 1m ago
+
+Result: feeding looks healthy
 ```
 
-## 4: Optional: Install [local interface](https://github.com/wiedehopf/tar1090) for your data
+`OK` means that part is working. `CHECK` means the feeder may still work, but
+something needs attention. `FIX` means that part is not working.
 
-The interface will be available at http://192.168.X.XX/airplanes  
-Replace the IP address with the address of your Raspberry Pi.
+## Claim Your Feeder
+
+Claiming connects this feeder to your airplanes.live account.
 
-Install / Update:
 ```
-sudo bash /usr/local/share/airplanes/git/install-or-update-interface.sh
+sudo apl-feed claim show
 ```
-Remove:
+
+Then sign in at:
+
+<https://airplanes.live/feeder/claim>
+
+Enter the UUID and secret shown by the command.
+
+If the website says the feeder is not registered yet, run:
+
 ```
-sudo bash /usr/local/share/tar1090/uninstall.sh airplanes
+sudo apl-feed claim register
 ```
 
-### Update the feed client without reconfiguring
+## Back Up And Restore
+
+Back up before replacing a Raspberry Pi, reinstalling the OS, or wiping an SD
+card:
 
 ```
-curl -L -o /tmp/update.sh https://raw.githubusercontent.com/airplanes-live/feed/main/update.sh
-sudo bash /tmp/update.sh
+sudo apl-feed backup airplanes-feeder-backup.json
 ```
 
-### If you encounter issues, please do a reboot and then supply these logs on Discord (last 20 lines for each is sufficient):
+Keep the backup private. It contains the identity that lets the website
+recognize this feeder.
+
+Restore it on the new install:
 
 ```
-sudo journalctl -u airplanes-feed --no-pager
-sudo journalctl -u airplanes-mlat --no-pager
+sudo apl-feed restore airplanes-feeder-backup.json
 ```
 
-### Display the configuration
+Check a backup before restoring it:
 
 ```
-cat /etc/default/airplanes
+sudo apl-feed restore --check airplanes-feeder-backup.json
 ```
 
-### Changing the configuration
+If the new install already created a different feeder identity, use:
 
-This is the same as the initial installation.
-If the client is up to date it should not take as long as the original installation,
-otherwise this will also update the client which will take a moment.
+```
+sudo apl-feed restore airplanes-feeder-backup.json --force
+```
+
+## Update
+
+Update without reconfiguring:
 
 ```
-curl -L -o /tmp/feed.sh https://raw.githubusercontent.com/airplanes-live/feed/main/install.sh
-sudo bash /tmp/feed.sh
+curl -L -o /tmp/update.sh https://raw.githubusercontent.com/airplanes-live/feed/main/update.sh
+sudo bash /tmp/update.sh
 ```
 
-### Disable / Enable airplanes.live MLAT-results in your main decoder interface (readsb / dump1090-fa)
+## Local Map
 
-This is enabled by default. You probably don't need to change that.
+Optional: install a local map interface for your data:
 
-- Disable:
+```
+sudo bash /usr/local/share/airplanes/git/install-or-update-interface.sh
+```
+
+Open it at:
 
 ```
-sudo sed --follow-symlinks -i -e 's/RESULTS=.*/RESULTS=""/' /etc/default/airplanes
-sudo systemctl restart airplanes-mlat
+http://192.168.X.XX/airplanes
 ```
-- Enable:
+
+Replace `192.168.X.XX` with the address of your Raspberry Pi.
+
+Remove the local map:
 
 ```
-sudo sed --follow-symlinks -i -e 's/RESULTS=.*/RESULTS="--results beast,connect,127.0.0.1:30104"/' /etc/default/airplanes
-sudo systemctl restart airplanes-mlat
+sudo bash /usr/local/share/tar1090/uninstall.sh airplanes
 ```
 
-### Restart the feed client
+## Change Settings
+
+Run the installer again to change your feeder settings:
 
 ```
-sudo systemctl restart airplanes-feed
-sudo systemctl restart airplanes-mlat
+curl -L -o /tmp/feed.sh https://raw.githubusercontent.com/airplanes-live/feed/main/install.sh
+sudo bash /tmp/feed.sh
 ```
 
-### Show status
+## Support
+
+Start with:
 
 ```
-sudo systemctl status airplanes-feed
-sudo systemctl status airplanes-mlat
+sudo apl-feed status
 ```
 
-### Removal / disabling the services
+If you ask for help on Discord, include the last 20 lines from:
 
 ```
-sudo bash /usr/local/share/airplanes/uninstall.sh
+sudo journalctl -u airplanes-feed --no-pager
+sudo journalctl -u airplanes-mlat --no-pager
 ```
 
-If the above doesn't work, you can just disable the services and the scripts won't run anymore:
+Restart the feed client:
 
 ```
-sudo systemctl disable --now airplanes-feed
-sudo systemctl disable --now airplanes-mlat
+sudo systemctl restart airplanes-feed
+sudo systemctl restart airplanes-mlat
+```
+
+Remove the feed client:
+
+```
+sudo bash /usr/local/share/airplanes/uninstall.sh
 ```

scripts/apl-feed.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# apl-feed - feeder-side management CLI for airplanes.live.
+
+set -euo pipefail
+
+resolve_lib_dir() {
+    local script_dir
+    script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+    if [[ -d "$script_dir/apl-feed" ]]; then
+        printf '%s\n' "$script_dir/apl-feed"
+    else
+        printf '%s\n' '/usr/local/share/airplanes/apl-feed'
+    fi
+}
+
+APL_FEED_LIB_DIR="${APL_FEED_LIB_DIR:-$(resolve_lib_dir)}"
+
+# shellcheck source=scripts/apl-feed/common.sh
+source "$APL_FEED_LIB_DIR/common.sh"
+# shellcheck source=scripts/apl-feed/http.sh
+source "$APL_FEED_LIB_DIR/http.sh"
+# shellcheck source=scripts/apl-feed/claim.sh
+source "$APL_FEED_LIB_DIR/claim.sh"
+# shellcheck source=scripts/apl-feed/status.sh
+source "$APL_FEED_LIB_DIR/status.sh"
+# shellcheck source=scripts/apl-feed/backup.sh
+source "$APL_FEED_LIB_DIR/backup.sh"
+
+main() {
+    local cmd="${1:-}"
+    case "$cmd" in
+        status)
+            shift
+            feed_status "$@"
+            ;;
+        claim)
+            shift
+            dispatch_claim "$@"
+            ;;
+        backup)
+            shift
+            config_backup "$@"
+            ;;
+        restore)
+            shift
+            config_restore "$@"
+            ;;
+        -h|--help|'')
+            usage
+            ;;
+        *)
+            die "unknown command: $cmd"
+            ;;
+    esac
+}
+
+main "$@"