adsb-tui 0.11.0__tar.gz

adsb_tui-0.11.0/.github/scripts/exe_entry.py

@@ -0,0 +1,8 @@
+"""PyInstaller entry point for the Windows release exe: runs the same main() as `adsbtui`."""
+
+import sys
+
+from adsbtui.__main__ import main
+
+if __name__ == "__main__":
+    sys.exit(main())

adsb_tui-0.11.0/.github/scripts/release_check.py

@@ -0,0 +1,86 @@
+"""Release gate: is the version in the source a valid next ZeroVer release?
+
+Used by .github/workflows/release.yml.
+Checks that `__version__` and pyproject.toml agree, that the version is ZeroVer
+(0.MINOR.PATCH, optionally rcN), and that it sorts above every existing v* tag. Whether the
+tag or release already exists on GitHub is checked by the workflow itself.
+
+Prints `version=...`, `tag=...` and `prerelease=true|false` for $GITHUB_OUTPUT.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+ZEROVER = re.compile(r"^0\.(0|[1-9]\d*)\.(0|[1-9]\d*)(rc([1-9]\d*))?$")
+
+
+class ReleaseError(Exception):
+    pass
+
+
+def sort_key(version: str) -> tuple[int, int, int, int, int]:
+    """Order versions as PEP 440 does: 0.10.0rc1 < 0.10.0rc2 < 0.10.0."""
+    match = ZEROVER.match(version)
+    if match is None:
+        raise ReleaseError(
+            f"{version!r} is not a ZeroVer version (0.MINOR.PATCH or 0.MINOR.PATCHrcN)"
+        )
+    minor, patch = int(match.group(1)), int(match.group(2))
+    if match.group(4) is None:
+        return (0, minor, patch, 1, 0)
+    return (0, minor, patch, 0, int(match.group(4)))
+
+
+def source_version(init_path: Path) -> str:
+    found = re.search(r'^__version__ = "([^"]+)"', init_path.read_text("utf-8"), re.MULTILINE)
+    if found is None:
+        raise ReleaseError(f"no __version__ in {init_path}")
+    return found.group(1)
+
+
+def check(init_version: str, pyproject_version: str, existing_tags: list[str]) -> str:
+    """Return the tag to create, or raise ReleaseError."""
+    if init_version != pyproject_version:
+        raise ReleaseError(
+            f"__version__ {init_version!r} and pyproject.toml {pyproject_version!r} differ"
+        )
+    new = sort_key(init_version)
+    tag = f"v{init_version}"
+    for existing in existing_tags:
+        name = existing.strip()
+        if not name:
+            continue
+        if name == tag:
+            raise ReleaseError(f"tag {tag} already exists; a published release is never replaced")
+        if name.startswith("v") and ZEROVER.match(name[1:]) and sort_key(name[1:]) >= new:
+            raise ReleaseError(f"{tag} does not sort above the existing tag {name}")
+    return tag
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--init", type=Path, default=Path("src/adsbtui/__init__.py"))
+    parser.add_argument("--pyproject", type=Path, default=Path("pyproject.toml"))
+    parser.add_argument("--tags", default="", help="existing tags, one per line")
+    args = parser.parse_args(argv)
+    try:
+        with open(args.pyproject, "rb") as handle:
+            declared = tomllib.load(handle)["project"]["version"]
+        version = source_version(args.init)
+        tag = check(version, declared, args.tags.splitlines())
+    except ReleaseError as exc:
+        print(f"release check failed: {exc}", file=sys.stderr)
+        return 1
+    print(f"version={version}")
+    print(f"tag={tag}")
+    print(f"prerelease={'true' if 'rc' in version else 'false'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

adsb_tui-0.11.0/.github/workflows/release.yml

@@ -0,0 +1,153 @@
+name: Release
+
+# Manual, from main only. Reads the version from the source (ZeroVer: 0.MINOR.PATCH, or
+# 0.MINOR.PATCHrcN for a pre-release), checks it, builds, and publishes a GitHub Release
+# tagged v<version>. It fails rather than replace: an existing tag or release stops it, and
+# nothing here deletes or overwrites a published release.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  check:
+    # Fails fast, before anything is built: bad version, existing tag, existing release.
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Check the version
+        id: version
+        run: |
+          python .github/scripts/release_check.py --tags "$(git tag --list 'v*')" | tee -a "$GITHUB_OUTPUT"
+
+      - name: Refuse an existing release
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "release $TAG already exists; refusing to replace it" >&2
+            exit 1
+          fi
+
+  build-windows:
+    # A PyInstaller one-file exe (unsigned). If this fails, release never runs and nothing is published.
+    needs: check
+    runs-on: windows-latest
+    env:
+      VERSION: ${{ needs.check.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Build the exe
+        shell: pwsh
+        run: |
+          python -m pip install ".[windows]" pyinstaller
+          pyinstaller --onefile --console --name adsb-tui --collect-submodules adsbtui --collect-data adsbtui .github/scripts/exe_entry.py
+
+      - name: The exe runs
+        shell: pwsh
+        run: |
+          $feed = Join-Path $env:RUNNER_TEMP "feed.json"
+          Set-Content -Path $feed -Value '{"now": 1, "aircraft": []}'
+          .\dist\adsb-tui.exe --check --url $feed --lat 37.7749 --lon -122.4194
+          if ($LASTEXITCODE -ne 0) { throw "--check exited $LASTEXITCODE" }
+          $got = (.\dist\adsb-tui.exe --version) -join ""
+          if ($got -ne "adsbtui $env:VERSION") { throw "version mismatch: '$got'" }
+
+      - name: Name the exe and write its checksum
+        shell: pwsh
+        run: |
+          $name = "adsb-tui-$env:VERSION-windows-x64.exe"
+          New-Item -ItemType Directory -Path out | Out-Null
+          Copy-Item dist\adsb-tui.exe "out\$name"
+          $hash = (Get-FileHash "out\$name" -Algorithm SHA256).Hash.ToLower()
+          [System.IO.File]::WriteAllText("$PWD\out\$name.sha256", "$hash  $name`n")
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: windows-exe
+          path: out/*
+          if-no-files-found: error
+
+  release:
+    needs: [check, build-windows]
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: windows-exe
+          path: windows
+
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: The built wheel runs from a clean environment
+        # Installs only the wheel into a fresh venv, away from the checkout, and runs the
+        # health check on an empty feed: catches a package that tests only because of the source tree.
+        run: |
+          python -m venv "$RUNNER_TEMP/smoke"
+          "$RUNNER_TEMP/smoke/bin/python" -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          echo '{"now": 1, "aircraft": []}' > feed.json
+          "$RUNNER_TEMP/smoke/bin/adsbtui" --check --url "$RUNNER_TEMP/feed.json" --lat 37.7749 --lon -122.4194
+          test "$("$RUNNER_TEMP/smoke/bin/adsbtui" --version)" = "adsbtui ${{ needs.check.outputs.version }}"
+
+      - name: The built version matches the tag
+        env:
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          python - <<'PY'
+          import glob, os, zipfile
+          (wheel,) = glob.glob("dist/*.whl")
+          with zipfile.ZipFile(wheel) as z:
+              name = next(n for n in z.namelist() if n.endswith(".dist-info/METADATA"))
+              meta = z.read(name).decode()
+          built = next(l.split(": ", 1)[1] for l in meta.splitlines() if l.startswith("Version: "))
+          assert built == os.environ["VERSION"], (built, os.environ["VERSION"])
+          print("wheel version", built)
+          PY
+
+      - name: Publish
+        # No --clobber, and the tag was checked above: gh creates the tag at this commit
+        # and fails if anything raced us.
+        env:
+          TAG: ${{ needs.check.outputs.tag }}
+          PRERELEASE: ${{ needs.check.outputs.prerelease }}
+        run: |
+          flags=""
+          if [ "$PRERELEASE" = "true" ]; then flags="--prerelease"; fi
+          gh release create "$TAG" dist/* windows/* --target "$GITHUB_SHA" --title "$TAG" --generate-notes $flags

adsb_tui-0.11.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.env
+*.log
+*.sqlite
+*.sqlite-journal
+config.toml
+MASTER.csv

adsb_tui-0.11.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

adsb_tui-0.11.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: adsb-tui
+Version: 0.11.0
+Summary: A curses TUI for tracking nearby aircraft from a dump1090/readsb ADS-B feed
+Author: WPTK
+License-Expression: CC0-1.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: windows
+Requires-Dist: windows-curses>=2.3; extra == 'windows'
+Description-Content-Type: text/markdown
+
+# ADSB-TUI
+
+A terminal UI that lists aircraft near you from the `aircraft.json` feed of your own `readsb` or `dump1090-fa` receiver. It renders a sortable table and a radar scope with curses.
+
+## Prerequisites
+
+- Python 3.11+
+- A `readsb` or `dump1090-fa` receiver whose `aircraft.json` you can reach by URL or file path (or use `--demo`, below)
+- Windows only: `windows-curses`, installed by the `windows` extra
+
+![adsbtui showing live traffic around SFO: the aircraft table with altitude-coloured rows and the radar scope](docs/screenshots/main.png)
+
+## Quickstart
+
+1. Install:
+
+```bash
+git clone https://github.com/WPTK/ADSB-TUI.git
+cd ADSB-TUI
+pip install -e .            # Windows: pip install -e ".[windows]"
+```
+
+**Raspberry Pi OS** blocks plain `pip install`. Use pipx:
+
+```bash
+sudo apt install pipx && pipx ensurepath   # then open a new shell
+pipx install --editable .
+```
+
+To update, `git pull` and restart adsbtui. A pipx install made without `--editable` won't pick
+up the pull; fix it once with `pipx install --force --editable .`.
+
+**Windows without Python:** each [GitHub Release](https://github.com/WPTK/ADSB-TUI/releases)
+includes `adsb-tui-<version>-windows-x64.exe`. Download it and run it from Windows Terminal
+(it is a terminal program; double-clicking opens a window that closes on exit). The exe is
+unsigned, so SmartScreen may warn "Windows protected your PC": choose More info, then Run anyway.
+To verify the download against the `.sha256` file from the same release:
+
+```powershell
+(Get-FileHash .dsb-tui-<version>-windows-x64.exe -Algorithm SHA256).Hash.ToLower()
+Get-Content .dsb-tui-<version>-windows-x64.exe.sha256
+```
+
+The two hashes must match. Then run `.dsb-tui-<version>-windows-x64.exe` in place of `adsbtui` below.
+
+2. Start the app:
+
+```bash
+adsbtui
+```
+
+The first run starts a setup wizard that finds your receiver and home location and writes
+`~/.config/adsbtui/config.toml`. To skip it:
+
+```bash
+adsbtui --url 192.0.2.10 --lat 37.7749 --lon -122.4194
+```
+
+`--url` takes a receiver address (the usual `aircraft.json` paths are probed), an exact URL, or
+a local file such as `/run/readsb/aircraft.json`.
+
+No receiver yet? `adsbtui --demo` shows scripted traffic around your home position (or San
+Francisco if none is set). It needs no config and no network, never sends an alert, and writes
+nothing to disk. The status line says DEMO.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `F1` / `?` | Help |
+| `F2` / `,` | Settings (every option, saved to `config.toml`) |
+| `F8` / `D` | Aircraft registry: status and manual update |
+| `Enter` | Details for the selected aircraft |
+| `Up` `Down` / `k` `j`, `PgUp` `PgDn`, `Home` `End` | Move the selection |
+| `d` | Details (same as `Enter`) |
+| `s` / `S` | Sort screen / reverse the sort |
+| `f` or `/` / `c` / `w` | Filter and search / columns / watchlist |
+| `r` / `u` / `p` | Toggle radar / cycle units / pause |
+| `+` / `-` | Grow / shrink the radius |
+| `q` / `F10` | Quit |
+
+`F3`–`F7` open filters, sort, columns and watchlist as in the key bar. Help (`F1`) lists every key and scrolls.
+
+
+The mouse works too: click a column header to sort by it (click again to reverse), click a row or a scope arrow to select it, and scroll the wheel to move the cursor. Hovering an arrow on the scope highlights its row and shows a tooltip; hover needs a terminal that reports mouse motion (most xterm-compatible ones) and is not available on every Windows console.
+
+![The detail pane for one aircraft, with closest approach and squawk](docs/screenshots/detail.png)
+
+## Configuration
+
+Press `F2` in the app to edit every option. The config file is `$ADSBTUI_CONFIG`, else
+`$XDG_CONFIG_HOME/adsbtui/config.toml` (`~/.config/adsbtui/config.toml` by default); the current
+directory is never searched. Flags override `ADSBTUI_<SECTION>_<KEY>` environment
+variables, which override `config.toml`. The full key list, column meanings and the watchlist
+format are in [docs/configuration.md](docs/configuration.md).
+
+## License
+
+[CC0 1.0](LICENSE): public domain, no warranty. Downloaded registry data has its own terms,
+shown in the app: the FAA extract is public domain, tar1090-db is non-commercial use only.

adsb_tui-0.11.0/README.md

@@ -0,0 +1,100 @@
+# ADSB-TUI
+
+A terminal UI that lists aircraft near you from the `aircraft.json` feed of your own `readsb` or `dump1090-fa` receiver. It renders a sortable table and a radar scope with curses.
+
+## Prerequisites
+
+- Python 3.11+
+- A `readsb` or `dump1090-fa` receiver whose `aircraft.json` you can reach by URL or file path (or use `--demo`, below)
+- Windows only: `windows-curses`, installed by the `windows` extra
+
+![adsbtui showing live traffic around SFO: the aircraft table with altitude-coloured rows and the radar scope](docs/screenshots/main.png)
+
+## Quickstart
+
+1. Install:
+
+```bash
+git clone https://github.com/WPTK/ADSB-TUI.git
+cd ADSB-TUI
+pip install -e .            # Windows: pip install -e ".[windows]"
+```
+
+**Raspberry Pi OS** blocks plain `pip install`. Use pipx:
+
+```bash
+sudo apt install pipx && pipx ensurepath   # then open a new shell
+pipx install --editable .
+```
+
+To update, `git pull` and restart adsbtui. A pipx install made without `--editable` won't pick
+up the pull; fix it once with `pipx install --force --editable .`.
+
+**Windows without Python:** each [GitHub Release](https://github.com/WPTK/ADSB-TUI/releases)
+includes `adsb-tui-<version>-windows-x64.exe`. Download it and run it from Windows Terminal
+(it is a terminal program; double-clicking opens a window that closes on exit). The exe is
+unsigned, so SmartScreen may warn "Windows protected your PC": choose More info, then Run anyway.
+To verify the download against the `.sha256` file from the same release:
+
+```powershell
+(Get-FileHash .dsb-tui-<version>-windows-x64.exe -Algorithm SHA256).Hash.ToLower()
+Get-Content .dsb-tui-<version>-windows-x64.exe.sha256
+```
+
+The two hashes must match. Then run `.dsb-tui-<version>-windows-x64.exe` in place of `adsbtui` below.
+
+2. Start the app:
+
+```bash
+adsbtui
+```
+
+The first run starts a setup wizard that finds your receiver and home location and writes
+`~/.config/adsbtui/config.toml`. To skip it:
+
+```bash
+adsbtui --url 192.0.2.10 --lat 37.7749 --lon -122.4194
+```
+
+`--url` takes a receiver address (the usual `aircraft.json` paths are probed), an exact URL, or
+a local file such as `/run/readsb/aircraft.json`.
+
+No receiver yet? `adsbtui --demo` shows scripted traffic around your home position (or San
+Francisco if none is set). It needs no config and no network, never sends an alert, and writes
+nothing to disk. The status line says DEMO.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `F1` / `?` | Help |
+| `F2` / `,` | Settings (every option, saved to `config.toml`) |
+| `F8` / `D` | Aircraft registry: status and manual update |
+| `Enter` | Details for the selected aircraft |
+| `Up` `Down` / `k` `j`, `PgUp` `PgDn`, `Home` `End` | Move the selection |
+| `d` | Details (same as `Enter`) |
+| `s` / `S` | Sort screen / reverse the sort |
+| `f` or `/` / `c` / `w` | Filter and search / columns / watchlist |
+| `r` / `u` / `p` | Toggle radar / cycle units / pause |
+| `+` / `-` | Grow / shrink the radius |
+| `q` / `F10` | Quit |
+
+`F3`–`F7` open filters, sort, columns and watchlist as in the key bar. Help (`F1`) lists every key and scrolls.
+
+
+The mouse works too: click a column header to sort by it (click again to reverse), click a row or a scope arrow to select it, and scroll the wheel to move the cursor. Hovering an arrow on the scope highlights its row and shows a tooltip; hover needs a terminal that reports mouse motion (most xterm-compatible ones) and is not available on every Windows console.
+
+![The detail pane for one aircraft, with closest approach and squawk](docs/screenshots/detail.png)
+
+## Configuration
+
+Press `F2` in the app to edit every option. The config file is `$ADSBTUI_CONFIG`, else
+`$XDG_CONFIG_HOME/adsbtui/config.toml` (`~/.config/adsbtui/config.toml` by default); the current
+directory is never searched. Flags override `ADSBTUI_<SECTION>_<KEY>` environment
+variables, which override `config.toml`. The full key list, column meanings and the watchlist
+format are in [docs/configuration.md](docs/configuration.md).
+
+## License
+
+[CC0 1.0](LICENSE): public domain, no warranty. Downloaded registry data has its own terms,
+shown in the app: the FAA extract is public domain, tar1090-db is non-commercial use only.

adsb_tui-0.11.0/contrib/adsb-tui-kiosk.service

@@ -0,0 +1,60 @@
+# adsb-tui-kiosk.service
+#
+# Runs adsbtui full-screen on a physical console (tty1), so a dedicated Raspberry Pi /
+# small-form-factor box boots straight into the aircraft table with no login prompt, no
+# desktop environment, and no SSH session required.
+#
+# Install adsbtui for the service user first, so ExecStart below exists:
+#   sudo -u adsbtui pipx install /path/to/ADSB-TUI     # puts it in /home/adsbtui/.local/bin
+#
+# Install:
+#   sudo useradd --system --create-home --shell /usr/sbin/nologin adsbtui   # if it doesn't exist
+#   sudo mkdir -p /home/adsbtui/.config/adsbtui
+#   sudo cp /path/to/your/config.toml /home/adsbtui/.config/adsbtui/config.toml
+#   sudo chown -R adsbtui:adsbtui /home/adsbtui/.config
+#   sudo cp contrib/adsb-tui-kiosk.service /etc/systemd/system/
+#   sudo systemctl disable --now getty@tty1.service   # free up tty1 first
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now adsb-tui-kiosk.service
+#
+# Watch it: sudo journalctl -u adsb-tui-kiosk.service -f
+# Get tty1 back later: sudo systemctl disable --now adsb-tui-kiosk.service && \
+#                       sudo systemctl enable --now getty@tty1.service
+
+[Unit]
+Description=ADSB-TUI kiosk (full-screen aircraft tracker on tty1)
+After=network-online.target getty@tty1.service
+Wants=network-online.target
+Conflicts=getty@tty1.service
+
+[Service]
+Type=simple
+User=adsbtui
+Group=adsbtui
+WorkingDirectory=/home/adsbtui
+
+# adsbtui looks for ~/.config/adsbtui/config.toml by default (see find_config_path() in
+# src/adsbtui/config.py); ADSBTUI_CONFIG overrides that, and any ADSBTUI_<SECTION>_<KEY>
+# variable overrides an individual TOML key without editing the file. Uncomment/adjust as
+# needed rather than baking secrets or hosts into this unit file directly.
+# Environment=ADSBTUI_CONFIG=/home/adsbtui/.config/adsbtui/config.toml
+# Environment=ADSBTUI_SOURCE_URL=http://192.0.2.10/skyaware/data/aircraft.json
+Environment=TERM=linux
+
+ExecStart=/home/adsbtui/.local/bin/adsbtui
+
+# Bind stdio directly to the physical console instead of the service manager's own
+# pty/journal plumbing, and take ownership of the console so no getty can race it.
+StandardInput=tty
+StandardOutput=tty
+StandardError=journal
+TTYPath=/dev/tty1
+TTYReset=yes
+TTYVHangup=yes
+TTYVTDisallocate=yes
+
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target