adsb-tui 0.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. adsb_tui-0.11.0.dist-info/METADATA +112 -0
  2. adsb_tui-0.11.0.dist-info/RECORD +59 -0
  3. adsb_tui-0.11.0.dist-info/WHEEL +4 -0
  4. adsb_tui-0.11.0.dist-info/entry_points.txt +2 -0
  5. adsb_tui-0.11.0.dist-info/licenses/LICENSE +121 -0
  6. adsbtui/__init__.py +3 -0
  7. adsbtui/__main__.py +171 -0
  8. adsbtui/alerts.py +189 -0
  9. adsbtui/config.py +641 -0
  10. adsbtui/config_write.py +210 -0
  11. adsbtui/data/icao_ranges.csv +73 -0
  12. adsbtui/dispatch.py +402 -0
  13. adsbtui/enrich/__init__.py +55 -0
  14. adsbtui/enrich/derived.py +329 -0
  15. adsbtui/enrich/providers.py +332 -0
  16. adsbtui/enrich/registry_update.py +736 -0
  17. adsbtui/firstrun.py +175 -0
  18. adsbtui/geo.py +148 -0
  19. adsbtui/history.py +262 -0
  20. adsbtui/logsetup.py +71 -0
  21. adsbtui/model.py +116 -0
  22. adsbtui/normalize.py +190 -0
  23. adsbtui/output.py +616 -0
  24. adsbtui/pipeline.py +397 -0
  25. adsbtui/sources/__init__.py +125 -0
  26. adsbtui/sources/demo.py +125 -0
  27. adsbtui/sources/http.py +96 -0
  28. adsbtui/sources/jsonfile.py +33 -0
  29. adsbtui/sources/receiver.py +102 -0
  30. adsbtui/textwidth.py +51 -0
  31. adsbtui/tracker.py +80 -0
  32. adsbtui/ui/__init__.py +0 -0
  33. adsbtui/ui/app.py +464 -0
  34. adsbtui/ui/bars.py +116 -0
  35. adsbtui/ui/columns.py +563 -0
  36. adsbtui/ui/controller.py +194 -0
  37. adsbtui/ui/effects.py +30 -0
  38. adsbtui/ui/frame.py +22 -0
  39. adsbtui/ui/keys.py +50 -0
  40. adsbtui/ui/mouse.py +100 -0
  41. adsbtui/ui/radar.py +268 -0
  42. adsbtui/ui/render.py +459 -0
  43. adsbtui/ui/screen_stack.py +162 -0
  44. adsbtui/ui/screens/__init__.py +15 -0
  45. adsbtui/ui/screens/columns.py +248 -0
  46. adsbtui/ui/screens/data.py +486 -0
  47. adsbtui/ui/screens/detail.py +199 -0
  48. adsbtui/ui/screens/filters.py +158 -0
  49. adsbtui/ui/screens/help.py +154 -0
  50. adsbtui/ui/screens/settings.py +574 -0
  51. adsbtui/ui/screens/setup.py +606 -0
  52. adsbtui/ui/screens/sort.py +174 -0
  53. adsbtui/ui/screens/watchlist.py +290 -0
  54. adsbtui/ui/sorting.py +137 -0
  55. adsbtui/ui/theme.py +174 -0
  56. adsbtui/ui/view.py +187 -0
  57. adsbtui/ui/widgets.py +971 -0
  58. adsbtui/units.py +88 -0
  59. adsbtui/watchlist.py +166 -0
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.5
2
+ Name: adsb-tui
3
+ Version: 0.11.0
4
+ Summary: A curses TUI for tracking nearby aircraft from a dump1090/readsb ADS-B feed
5
+ Author: WPTK
6
+ License-Expression: CC0-1.0
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Provides-Extra: windows
10
+ Requires-Dist: windows-curses>=2.3; extra == 'windows'
11
+ Description-Content-Type: text/markdown
12
+
13
+ # ADSB-TUI
14
+
15
+ 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.
16
+
17
+ ## Prerequisites
18
+
19
+ - Python 3.11+
20
+ - A `readsb` or `dump1090-fa` receiver whose `aircraft.json` you can reach by URL or file path (or use `--demo`, below)
21
+ - Windows only: `windows-curses`, installed by the `windows` extra
22
+
23
+ ![adsbtui showing live traffic around SFO: the aircraft table with altitude-coloured rows and the radar scope](docs/screenshots/main.png)
24
+
25
+ ## Quickstart
26
+
27
+ 1. Install:
28
+
29
+ ```bash
30
+ git clone https://github.com/WPTK/ADSB-TUI.git
31
+ cd ADSB-TUI
32
+ pip install -e . # Windows: pip install -e ".[windows]"
33
+ ```
34
+
35
+ **Raspberry Pi OS** blocks plain `pip install`. Use pipx:
36
+
37
+ ```bash
38
+ sudo apt install pipx && pipx ensurepath # then open a new shell
39
+ pipx install --editable .
40
+ ```
41
+
42
+ To update, `git pull` and restart adsbtui. A pipx install made without `--editable` won't pick
43
+ up the pull; fix it once with `pipx install --force --editable .`.
44
+
45
+ **Windows without Python:** each [GitHub Release](https://github.com/WPTK/ADSB-TUI/releases)
46
+ includes `adsb-tui-<version>-windows-x64.exe`. Download it and run it from Windows Terminal
47
+ (it is a terminal program; double-clicking opens a window that closes on exit). The exe is
48
+ unsigned, so SmartScreen may warn "Windows protected your PC": choose More info, then Run anyway.
49
+ To verify the download against the `.sha256` file from the same release:
50
+
51
+ ```powershell
52
+ (Get-FileHash .dsb-tui-<version>-windows-x64.exe -Algorithm SHA256).Hash.ToLower()
53
+ Get-Content .dsb-tui-<version>-windows-x64.exe.sha256
54
+ ```
55
+
56
+ The two hashes must match. Then run `.dsb-tui-<version>-windows-x64.exe` in place of `adsbtui` below.
57
+
58
+ 2. Start the app:
59
+
60
+ ```bash
61
+ adsbtui
62
+ ```
63
+
64
+ The first run starts a setup wizard that finds your receiver and home location and writes
65
+ `~/.config/adsbtui/config.toml`. To skip it:
66
+
67
+ ```bash
68
+ adsbtui --url 192.0.2.10 --lat 37.7749 --lon -122.4194
69
+ ```
70
+
71
+ `--url` takes a receiver address (the usual `aircraft.json` paths are probed), an exact URL, or
72
+ a local file such as `/run/readsb/aircraft.json`.
73
+
74
+ No receiver yet? `adsbtui --demo` shows scripted traffic around your home position (or San
75
+ Francisco if none is set). It needs no config and no network, never sends an alert, and writes
76
+ nothing to disk. The status line says DEMO.
77
+
78
+ ## Keys
79
+
80
+ | Key | Action |
81
+ |---|---|
82
+ | `F1` / `?` | Help |
83
+ | `F2` / `,` | Settings (every option, saved to `config.toml`) |
84
+ | `F8` / `D` | Aircraft registry: status and manual update |
85
+ | `Enter` | Details for the selected aircraft |
86
+ | `Up` `Down` / `k` `j`, `PgUp` `PgDn`, `Home` `End` | Move the selection |
87
+ | `d` | Details (same as `Enter`) |
88
+ | `s` / `S` | Sort screen / reverse the sort |
89
+ | `f` or `/` / `c` / `w` | Filter and search / columns / watchlist |
90
+ | `r` / `u` / `p` | Toggle radar / cycle units / pause |
91
+ | `+` / `-` | Grow / shrink the radius |
92
+ | `q` / `F10` | Quit |
93
+
94
+ `F3`–`F7` open filters, sort, columns and watchlist as in the key bar. Help (`F1`) lists every key and scrolls.
95
+
96
+
97
+ 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.
98
+
99
+ ![The detail pane for one aircraft, with closest approach and squawk](docs/screenshots/detail.png)
100
+
101
+ ## Configuration
102
+
103
+ Press `F2` in the app to edit every option. The config file is `$ADSBTUI_CONFIG`, else
104
+ `$XDG_CONFIG_HOME/adsbtui/config.toml` (`~/.config/adsbtui/config.toml` by default); the current
105
+ directory is never searched. Flags override `ADSBTUI_<SECTION>_<KEY>` environment
106
+ variables, which override `config.toml`. The full key list, column meanings and the watchlist
107
+ format are in [docs/configuration.md](docs/configuration.md).
108
+
109
+ ## License
110
+
111
+ [CC0 1.0](LICENSE): public domain, no warranty. Downloaded registry data has its own terms,
112
+ shown in the app: the FAA extract is public domain, tar1090-db is non-commercial use only.
@@ -0,0 +1,59 @@
1
+ adsbtui/__init__.py,sha256=dsjmdWYTBunpAK4__svQrX2Zmjd1X7p-JjPlZe6aKpA,119
2
+ adsbtui/__main__.py,sha256=4TzWuPK6yYljaK--Xamb66t1yg5c8yDVzoW2AaETiWA,6520
3
+ adsbtui/alerts.py,sha256=Xza_WplhPLs4J8LuASFZT1CARlPArGBFJflI3D-SVG0,7637
4
+ adsbtui/config.py,sha256=MmXxOisgTBZFi77e1UUigHW3-dzKx0Do9GUPR9vy7Tk,24683
5
+ adsbtui/config_write.py,sha256=9pA5ICJj-A3iLUxTJaJ6E1FiBO2_mkkYjd3yNMphv48,8705
6
+ adsbtui/dispatch.py,sha256=GfiKpNYDucX05SfMGByA4LDCc_u1tRO8OQTDH_qskdo,15916
7
+ adsbtui/firstrun.py,sha256=a9qjhm0g2dW3HpCA-VJhyqoZIhb2Jk1_GDtLDmDtg3s,6563
8
+ adsbtui/geo.py,sha256=iCUtM1599kBvEbeKhM5UqIPPbcdttL-RJa3U9L3gtHw,5858
9
+ adsbtui/history.py,sha256=VrB4DrmdW_hE0jCM3PmTa89z0SrcF6kSgZREjeeE5H8,9102
10
+ adsbtui/logsetup.py,sha256=J3aYG7PDhDj5ntxPyPzjr5NEs8hWJRbeRjj2YyZRlp4,3273
11
+ adsbtui/model.py,sha256=mW1Gid3S7uLm7tiQdlsa_vAksrsl_kxgSCFcKKBvkWY,3864
12
+ adsbtui/normalize.py,sha256=utAHF6INRWap-23WD0Bp-l3YyoVUryyzumNktyJQ9wE,7228
13
+ adsbtui/output.py,sha256=ErkuqBKfYjbvsMzSLERCn3VPrfUslU4uxAafznmctic,25799
14
+ adsbtui/pipeline.py,sha256=ogwRAD0jOL07kCbisFRPe6nSQNYqhAh189gzvahSfsk,17158
15
+ adsbtui/textwidth.py,sha256=OeJJxzBI2SNMsUHhbXPZaZPdZZ8dMCIM0KHg921fQ1Q,1659
16
+ adsbtui/tracker.py,sha256=HCFl1KakIcsnI-3kE1l4iU_eYLuBCiZFQgQQd422bnE,3450
17
+ adsbtui/units.py,sha256=VksD42P0PUWyaVOIODhOvyzEhz2Jop1dwk0U-Ihll0E,2825
18
+ adsbtui/watchlist.py,sha256=CGNk3exV-Qlf8SdzGKnk4hMTUwnw2zifmbR5GAiChOg,5461
19
+ adsbtui/data/icao_ranges.csv,sha256=86vVx2p-Z226e1pyEXWQBI9dSOJVivQtxGvahnauHDI,2449
20
+ adsbtui/enrich/__init__.py,sha256=6wiGs3d2zqOPKI4JotHNoHCwtLeUiRnCGsthC4dGKtE,1539
21
+ adsbtui/enrich/derived.py,sha256=r_5fN7shuULXT1Py9aSZfT0-UUgZwUcAWAqaTk6RxUk,12260
22
+ adsbtui/enrich/providers.py,sha256=T5XD70qQzYnqLg9mZH48WJpFx8AJjoEqrjqTl621bNM,13053
23
+ adsbtui/enrich/registry_update.py,sha256=g2uw9gSdWSqkus_7QuKTlgrDJ8oOGQbqnxkOyfzTShA,26429
24
+ adsbtui/sources/__init__.py,sha256=UVm9tc6Immj4egjPyMq4jo6bFo8vOuWioreYXmakmbA,4984
25
+ adsbtui/sources/demo.py,sha256=bbxloMEQ0CLPXCXWVhtKPMiO4c77l5CHYxZFCv3_xoU,4994
26
+ adsbtui/sources/http.py,sha256=3kFHAjwKgwqcBK20t1CD9c-advpbqx_Ywu0shFwxdzM,3942
27
+ adsbtui/sources/jsonfile.py,sha256=iZUFoIlTlOtylUQALm3hTTczvaQ-Udnap2T5YJeKWEU,1239
28
+ adsbtui/sources/receiver.py,sha256=rgiZiCetycqLlMVKrCDZkyQ6ktZmI9rbS08hKaFgWIc,4183
29
+ adsbtui/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
30
+ adsbtui/ui/app.py,sha256=LmO6NCpfXiC5Fzhw6VepZu4njW5B-2-02OahltIzRPo,20062
31
+ adsbtui/ui/bars.py,sha256=VeG_BgsMFN6_8LcNk3DI03S1sS4XB3G22msDABbZQ9k,4177
32
+ adsbtui/ui/columns.py,sha256=PUXbRVT6_0r6IZjdxOCvWndZsl4PP7rMNY7gb1-PsjA,22346
33
+ adsbtui/ui/controller.py,sha256=O07WmQVzcVLU7p-1q8NUnKhnxTNeXhZxpJTUCDAnWhY,7053
34
+ adsbtui/ui/effects.py,sha256=qc8dzUatYyo31zULbRICKXP9YdoteDOfZlOyG0D3Hpw,1087
35
+ adsbtui/ui/frame.py,sha256=jq62Sh_jm3Xt7Q53ZBQJStl8CMUWBsh708pK5gIcyQI,837
36
+ adsbtui/ui/keys.py,sha256=rGVW0zMQpb3rn6fwf2JVzMcOOM8b3lfqfZgyczKa59Q,2391
37
+ adsbtui/ui/mouse.py,sha256=zsZQdgPm76-Kc2ihGbNs8hqVJePrzpUGe60NxrSW-uk,3313
38
+ adsbtui/ui/radar.py,sha256=zpT10f0EQ39De2B-FGG7LCHJuoX4gZrY6ua9iXzJO8s,11197
39
+ adsbtui/ui/render.py,sha256=WVA8BPVSQZniv2CRUPg-BUnBclOHz6PPfmidRRiEgl8,18783
40
+ adsbtui/ui/screen_stack.py,sha256=Sex4Ot3FiwDwnp78uXzsSroTQ70e88_RiPGZMMwC3as,6670
41
+ adsbtui/ui/sorting.py,sha256=VyD2Y7bXIiJVC7gaqmKL_cHb2L5u1Mwf5g9y8-BttB4,5706
42
+ adsbtui/ui/theme.py,sha256=e7lrD940IPbeH1GGiGU0CQJwAeucRp8fPkdYjCEB4fY,6513
43
+ adsbtui/ui/view.py,sha256=8BUeyg2cmRmRXdKlTKhVNPYQ0Ohw5OCbH-M4yUR_AL8,7185
44
+ adsbtui/ui/widgets.py,sha256=s5khnEIVu0KogVAagOSwjt3kDWppI0JF4KT9I0ZXVx4,35058
45
+ adsbtui/ui/screens/__init__.py,sha256=F_rkkrBAiKbE8m7bhrxaoVLWAJqy9Fn70tUnYpEyXzw,729
46
+ adsbtui/ui/screens/columns.py,sha256=H22V8twf1tbbXZSRAvTU9Emems0jKK6fYA1afx4ipV4,9850
47
+ adsbtui/ui/screens/data.py,sha256=0tMGOaOj7grhCcQuDJEOQmJR_t2imtoTHqB2ISxjGV4,17963
48
+ adsbtui/ui/screens/detail.py,sha256=oiQs2762RP-xQNl6EkLPFzDIykJNkXTJsVqBKrK6CoQ,7828
49
+ adsbtui/ui/screens/filters.py,sha256=0oKZxD5PQT1Eh4_vxSlYtFL5A6Of6T55GQqcXehmGT8,6894
50
+ adsbtui/ui/screens/help.py,sha256=-lufgjLjxMIhwpgs2uzdK2iQ5SZaEcT__XTbcK7Vn8g,6459
51
+ adsbtui/ui/screens/settings.py,sha256=9W9b670LQKX_BiCYH3OE5HGXy17N4ydGOH0KqtQGgLE,22606
52
+ adsbtui/ui/screens/setup.py,sha256=HagTr5grsBVB44-Inz6HRuX8Jjg7lEmsFckd0ogaOdA,24377
53
+ adsbtui/ui/screens/sort.py,sha256=QN-hf1kfRlHqmCeDkgIbJF_Z9naLYRlDIpsaZlHvTd8,7052
54
+ adsbtui/ui/screens/watchlist.py,sha256=Ugy9lpQjxKSEzFiwBwTzRfEZQ9jvChzB3PAFPfEISxA,11069
55
+ adsb_tui-0.11.0.dist-info/METADATA,sha256=qPfxLEoxoBcpuuz2NgFSoQSptcz7fXWvimXzqWkVQIY,4523
56
+ adsb_tui-0.11.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
57
+ adsb_tui-0.11.0.dist-info/entry_points.txt,sha256=Dcx3gkv-CJf1fLPZBGsI4s5NGJu7jZw-dykTa_HWsi4,50
58
+ adsb_tui-0.11.0.dist-info/licenses/LICENSE,sha256=ogEPNDSH0_dhiv_lT3ifVIdgIzHAqNA_SemnxUfPBJk,7048
59
+ adsb_tui-0.11.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ adsbtui = adsbtui.__main__:main
@@ -0,0 +1,121 @@
1
+ Creative Commons Legal Code
2
+
3
+ CC0 1.0 Universal
4
+
5
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
6
+ LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
7
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
8
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
9
+ REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
10
+ PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
11
+ THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
12
+ HEREUNDER.
13
+
14
+ Statement of Purpose
15
+
16
+ The laws of most jurisdictions throughout the world automatically confer
17
+ exclusive Copyright and Related Rights (defined below) upon the creator
18
+ and subsequent owner(s) (each and all, an "owner") of an original work of
19
+ authorship and/or a database (each, a "Work").
20
+
21
+ Certain owners wish to permanently relinquish those rights to a Work for
22
+ the purpose of contributing to a commons of creative, cultural and
23
+ scientific works ("Commons") that the public can reliably and without fear
24
+ of later claims of infringement build upon, modify, incorporate in other
25
+ works, reuse and redistribute as freely as possible in any form whatsoever
26
+ and for any purposes, including without limitation commercial purposes.
27
+ These owners may contribute to the Commons to promote the ideal of a free
28
+ culture and the further production of creative, cultural and scientific
29
+ works, or to gain reputation or greater distribution for their Work in
30
+ part through the use and efforts of others.
31
+
32
+ For these and/or other purposes and motivations, and without any
33
+ expectation of additional consideration or compensation, the person
34
+ associating CC0 with a Work (the "Affirmer"), to the extent that he or she
35
+ is an owner of Copyright and Related Rights in the Work, voluntarily
36
+ elects to apply CC0 to the Work and publicly distribute the Work under its
37
+ terms, with knowledge of his or her Copyright and Related Rights in the
38
+ Work and the meaning and intended legal effect of CC0 on those rights.
39
+
40
+ 1. Copyright and Related Rights. A Work made available under CC0 may be
41
+ protected by copyright and related or neighboring rights ("Copyright and
42
+ Related Rights"). Copyright and Related Rights include, but are not
43
+ limited to, the following:
44
+
45
+ i. the right to reproduce, adapt, distribute, perform, display,
46
+ communicate, and translate a Work;
47
+ ii. moral rights retained by the original author(s) and/or performer(s);
48
+ iii. publicity and privacy rights pertaining to a person's image or
49
+ likeness depicted in a Work;
50
+ iv. rights protecting against unfair competition in regards to a Work,
51
+ subject to the limitations in paragraph 4(a), below;
52
+ v. rights protecting the extraction, dissemination, use and reuse of data
53
+ in a Work;
54
+ vi. database rights (such as those arising under Directive 96/9/EC of the
55
+ European Parliament and of the Council of 11 March 1996 on the legal
56
+ protection of databases, and under any national implementation
57
+ thereof, including any amended or successor version of such
58
+ directive); and
59
+ vii. other similar, equivalent or corresponding rights throughout the
60
+ world based on applicable law or treaty, and any national
61
+ implementations thereof.
62
+
63
+ 2. Waiver. To the greatest extent permitted by, but not in contravention
64
+ of, applicable law, Affirmer hereby overtly, fully, permanently,
65
+ irrevocably and unconditionally waives, abandons, and surrenders all of
66
+ Affirmer's Copyright and Related Rights and associated claims and causes
67
+ of action, whether now known or unknown (including existing as well as
68
+ future claims and causes of action), in the Work (i) in all territories
69
+ worldwide, (ii) for the maximum duration provided by applicable law or
70
+ treaty (including future time extensions), (iii) in any current or future
71
+ medium and for any number of copies, and (iv) for any purpose whatsoever,
72
+ including without limitation commercial, advertising or promotional
73
+ purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
74
+ member of the public at large and to the detriment of Affirmer's heirs and
75
+ successors, fully intending that such Waiver shall not be subject to
76
+ revocation, rescission, cancellation, termination, or any other legal or
77
+ equitable action to disrupt the quiet enjoyment of the Work by the public
78
+ as contemplated by Affirmer's express Statement of Purpose.
79
+
80
+ 3. Public License Fallback. Should any part of the Waiver for any reason
81
+ be judged legally invalid or ineffective under applicable law, then the
82
+ Waiver shall be preserved to the maximum extent permitted taking into
83
+ account Affirmer's express Statement of Purpose. In addition, to the
84
+ extent the Waiver is so judged Affirmer hereby grants to each affected
85
+ person a royalty-free, non transferable, non sublicensable, non exclusive,
86
+ irrevocable and unconditional license to exercise Affirmer's Copyright and
87
+ Related Rights in the Work (i) in all territories worldwide, (ii) for the
88
+ maximum duration provided by applicable law or treaty (including future
89
+ time extensions), (iii) in any current or future medium and for any number
90
+ of copies, and (iv) for any purpose whatsoever, including without
91
+ limitation commercial, advertising or promotional purposes (the
92
+ "License"). The License shall be deemed effective as of the date CC0 was
93
+ applied by Affirmer to the Work. Should any part of the License for any
94
+ reason be judged legally invalid or ineffective under applicable law, such
95
+ partial invalidity or ineffectiveness shall not invalidate the remainder
96
+ of the License, and in such case Affirmer hereby affirms that he or she
97
+ will not (i) exercise any of his or her remaining Copyright and Related
98
+ Rights in the Work or (ii) assert any associated claims and causes of
99
+ action with respect to the Work, in either case contrary to Affirmer's
100
+ express Statement of Purpose.
101
+
102
+ 4. Limitations and Disclaimers.
103
+
104
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
105
+ surrendered, licensed or otherwise affected by this document.
106
+ b. Affirmer offers the Work as-is and makes no representations or
107
+ warranties of any kind concerning the Work, express, implied,
108
+ statutory or otherwise, including without limitation warranties of
109
+ title, merchantability, fitness for a particular purpose, non
110
+ infringement, or the absence of latent or other defects, accuracy, or
111
+ the present or absence of errors, whether or not discoverable, all to
112
+ the greatest extent permissible under applicable law.
113
+ c. Affirmer disclaims responsibility for clearing rights of other persons
114
+ that may apply to the Work or any use thereof, including without
115
+ limitation any person's Copyright and Related Rights in the Work.
116
+ Further, Affirmer disclaims responsibility for obtaining any necessary
117
+ consents, permissions or other rights required for any use of the
118
+ Work.
119
+ d. Affirmer understands and acknowledges that Creative Commons is not a
120
+ party to this document and has no duty or obligation with respect to
121
+ this CC0 or use of the Work.
adsbtui/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """ADSB-TUI: a curses terminal UI for tracking nearby aircraft from a dump1090/readsb feed."""
2
+
3
+ __version__ = "0.11.0"
adsbtui/__main__.py ADDED
@@ -0,0 +1,171 @@
1
+ """Console entry point: assemble config, data source, and a run mode.
2
+
3
+ This module is deliberately thin. It owns exactly three decisions -- which config to
4
+ build, which source to open, and which run mode to hand them to -- and delegates
5
+ everything else. Keeping it that small is what lets every other module stay independently
6
+ testable: nothing here does I/O of its own beyond printing a startup error.
7
+
8
+ Run modes, in the order they are checked:
9
+
10
+ --check one fetch, print a one-line verdict, exit (for healthchecks)
11
+ --once one fetch, print the table/json/csv, exit
12
+ --watch N N fetch-and-print cycles, then exit
13
+ --batch a line-per-event stream on stdout, for piping
14
+ --headless fetch/log loop with no output, for running as a service
15
+ (default) the curses TUI
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import contextlib
21
+ import curses
22
+ import logging
23
+ import signal
24
+ import sys
25
+ import threading
26
+
27
+ from . import __version__, firstrun
28
+ from .config import ConfigError, build_argparser, load_config
29
+ from .logsetup import configure_logging
30
+ from .output import run_batch, run_headless, run_once, run_watch
31
+ from .sources import SourceError, make_source
32
+ from .sources.demo import DemoSource, apply_demo_settings
33
+ from .ui.app import App, run_check
34
+
35
+ log = logging.getLogger("adsbtui")
36
+
37
+
38
+ def _stop_predicate_from_signals() -> threading.Event:
39
+ """Return an Event set by SIGINT/SIGTERM, so headless mode exits cleanly on Ctrl-C
40
+ or `systemctl stop` instead of dying with a traceback mid-fetch."""
41
+ stop = threading.Event()
42
+
43
+ def _handler(signum, frame): # noqa: ARG001 - signal handler signature is fixed
44
+ stop.set()
45
+
46
+ for sig in (signal.SIGINT, signal.SIGTERM):
47
+ # Not on the main thread, or the platform lacks the signal: the loop still works,
48
+ # it just will not be interruptible this way.
49
+ with contextlib.suppress(ValueError, OSError):
50
+ signal.signal(sig, _handler)
51
+ return stop
52
+
53
+
54
+ def _parse_args_quietly(argv: list[str] | None):
55
+ """Re-parse argv for the first-run check, returning None if it will not parse.
56
+
57
+ load_config() raised before it could attach the parsed arguments, but deciding whether
58
+ to offer the wizard needs to know which mode was asked for. argparse exits the process
59
+ on a bad argument, which would be the wrong outcome while handling a different error.
60
+ """
61
+ try:
62
+ return build_argparser().parse_args(argv)
63
+ except SystemExit:
64
+ return None
65
+
66
+
67
+ def _terminal_can_draw() -> bool:
68
+ """False when TERM names a terminal without cursor addressing (TERM=dumb): curses would
69
+ start and paint a blank screen. An unset or unknown TERM is left to curses, which
70
+ already refuses it with its own message. Windows has no terminfo (PDCurses answers None
71
+ for every capability), so the check cannot say anything there."""
72
+ if sys.platform == "win32":
73
+ return True
74
+ try:
75
+ curses.setupterm()
76
+ return curses.tigetstr("cup") is not None
77
+ except curses.error:
78
+ return True
79
+
80
+
81
+ def main(argv: list[str] | None = None) -> int:
82
+ """Entry point for the `adsbtui` console script. Returns a process exit code.
83
+
84
+ Exit codes: 0 success/clean quit, 2 configuration error, 4 the source was
85
+ unreachable or returned unusable data.
86
+ """
87
+ try:
88
+ cfg = load_config(argv)
89
+ if getattr(cfg._args, "demo", False):
90
+ apply_demo_settings(cfg)
91
+ except ConfigError as exc:
92
+ # A person at a terminal with no config yet is exactly who the setup wizard is
93
+ # for, so offer it rather than sending them to the README. Scripted runs and
94
+ # non-interactive terminals fall through to the error and exit code below --
95
+ # see firstrun.should_offer_setup for the conditions.
96
+ parsed = _parse_args_quietly(argv)
97
+ started = firstrun.first_run(parsed)
98
+ if started is None:
99
+ print(f"Configuration error: {exc}", file=sys.stderr)
100
+ print(
101
+ "Run 'adsbtui --help', or see the README's Configuration section.",
102
+ file=sys.stderr,
103
+ )
104
+ return 2
105
+ cfg, _written = started
106
+ cfg._args = parsed
107
+
108
+ configure_logging(
109
+ log_file=cfg.logging.file,
110
+ level="DEBUG" if getattr(cfg._args, "debug", False) else cfg.logging.level,
111
+ max_bytes=cfg.logging.max_bytes,
112
+ backup_count=cfg.logging.backup_count,
113
+ )
114
+ log.info("adsbtui %s starting (config: %s)", __version__, cfg._config_path or "defaults")
115
+
116
+ demo = bool(getattr(cfg._args, "demo", False))
117
+ try:
118
+ if demo:
119
+ source = DemoSource(cfg.home.lat, cfg.home.lon)
120
+ else:
121
+ source = make_source(cfg.source.url, max_bytes=cfg.source.max_bytes)
122
+ except (SourceError, ValueError) as exc:
123
+ print(f"Cannot use source {cfg.source.url!r}: {exc}", file=sys.stderr)
124
+ return 2
125
+
126
+ args = cfg._args
127
+ fmt = getattr(args, "format", None) or "table"
128
+
129
+ if getattr(args, "check", False):
130
+ return run_check(cfg, source)
131
+
132
+ if getattr(args, "once", False):
133
+ return run_once(cfg, source, fmt)
134
+
135
+ watch_n = getattr(args, "watch", None)
136
+ if watch_n is not None:
137
+ return run_watch(cfg, source, fmt, cfg.source.refresh_s, iterations=watch_n)
138
+
139
+ if getattr(args, "batch", False):
140
+ stop = _stop_predicate_from_signals()
141
+ try:
142
+ for line in run_batch(cfg, source, diff_only=False):
143
+ print(line, flush=True)
144
+ if stop.is_set():
145
+ break
146
+ except KeyboardInterrupt:
147
+ pass
148
+ return 0
149
+
150
+ if getattr(args, "headless", False):
151
+ stop = _stop_predicate_from_signals()
152
+ return run_headless(cfg, source, stop_predicate=stop.is_set)
153
+
154
+ # Default: the curses TUI. curses.wrapper restores the terminal even if run() raises.
155
+ if not _terminal_can_draw():
156
+ print("This terminal cannot move the cursor, so the TUI cannot draw.", file=sys.stderr)
157
+ print("Try 'adsbtui --once' instead, or set TERM to a real terminal.", file=sys.stderr)
158
+ return 2
159
+ app = App(cfg, source)
160
+ try:
161
+ return curses.wrapper(app.run)
162
+ except KeyboardInterrupt:
163
+ return 0
164
+ except curses.error as exc:
165
+ print(f"Terminal error: {exc}", file=sys.stderr)
166
+ print("If this terminal cannot run curses, try 'adsbtui --once' instead.", file=sys.stderr)
167
+ return 2
168
+
169
+
170
+ if __name__ == "__main__":
171
+ sys.exit(main())
adsbtui/alerts.py ADDED
@@ -0,0 +1,189 @@
1
+ """Alert grading: pure logic that decides how alarmed the UI should be about an aircraft.
2
+
3
+ This module only grades -- it never rings a bell, sends a webhook, or writes a log line.
4
+ Delivery/dispatch (cooldowns, quiet hours, webhook formatting, etc.) belongs in a later
5
+ module that sits on top of grade()'s output. Like model.py and geo.py, this module is pure:
6
+ no curses calls, no network calls, no global state, so it can be unit-tested without a
7
+ terminal or a feed.
8
+
9
+ Functions take plain keyword arguments mirroring the [alerts] and [filter] TOML config
10
+ keys rather than importing config.py directly, to avoid a circular dependency between the
11
+ config loader and the alert grader.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from adsbtui.model import Aircraft, AlertLevel
17
+
18
+ #: Emitter category -> short display label, for the subset of ADS-B categories that are
19
+ #: interesting enough in a terminal-width table to abbreviate. Anything not in this table
20
+ #: is passed through as-is by decode_category() rather than being dropped.
21
+ _CATEGORY_LABELS = {
22
+ "A1": "Light",
23
+ "A2": "Small",
24
+ "A3": "Large",
25
+ "A4": "HVortex",
26
+ "A5": "Heavy",
27
+ "A6": "HiPerf",
28
+ "A7": "Rotor",
29
+ "B1": "Glider",
30
+ "B2": "LTA",
31
+ "B4": "UltraLt",
32
+ "B6": "UAV",
33
+ "B7": "Space",
34
+ "C1": "Vehicle",
35
+ }
36
+
37
+ #: dbFlags bitfield -> short tag, in bit order (bit0 first). decode_db_flags() emits tags
38
+ #: in this order regardless of which bits are set.
39
+ _DB_FLAG_TAGS = [
40
+ (0x1, "MIL"),
41
+ (0x2, "INT"),
42
+ (0x4, "PIA"),
43
+ (0x8, "LADD"),
44
+ ]
45
+
46
+ #: Unicode and ASCII glyphs for each vertical trend, keyed by the strings classify_trend()
47
+ #: returns. "unknown" is deliberately blank in both sets so the UI can render nothing
48
+ #: instead of a misleading "level" arrow when there is no rate data at all.
49
+ _TREND_GLYPHS_UNICODE = {
50
+ "climb": "↑", # ^
51
+ "descend": "↓", # v
52
+ "level": "→", # >
53
+ "unknown": "",
54
+ }
55
+ _TREND_GLYPHS_ASCII = {
56
+ "climb": "^",
57
+ "descend": "v",
58
+ "level": "-",
59
+ "unknown": "",
60
+ }
61
+
62
+
63
+ def grade(
64
+ aircraft: Aircraft,
65
+ squawks: list[int] | list[str],
66
+ emergency_enabled: bool,
67
+ proximity_mi: float,
68
+ cpa_enabled: bool,
69
+ cpa_distance_mi: float,
70
+ cpa_horizon_s: float,
71
+ cpa_min_gs_kt: float,
72
+ ) -> AlertLevel:
73
+ """The single source of truth for how alarmed the UI should be about this aircraft.
74
+
75
+ Replaces the original tool's only signal ("is it closer than N miles?") with a
76
+ priority-ordered set of checks; the first one that matches wins. Kept deliberately
77
+ simple -- this is a heuristic for a terminal UI, not a collision-avoidance system.
78
+
79
+ Priority order:
80
+ 1. EMERGENCY -- squawking one of the watched codes, or reporting an emergency state.
81
+ 2. OVERHEAD -- currently within the proximity radius (NEARBY if on the ground).
82
+ 3. INBOUND -- not close yet, but its current track/speed will bring it within the
83
+ CPA distance inside the CPA horizon, and it's moving fast enough for
84
+ that projection to be meaningful.
85
+ 4. OUTBOUND -- was recently close and is now moving away (a receding CPA solution).
86
+ 5. NONE -- nothing above applies.
87
+ """
88
+ # 1. EMERGENCY: a watched squawk code, or any reported emergency state, if enabled.
89
+ if emergency_enabled:
90
+ watched_squawks = {str(s) for s in squawks}
91
+ if aircraft.squawk is not None and aircraft.squawk in watched_squawks:
92
+ return AlertLevel.EMERGENCY
93
+ if aircraft.emergency is not None:
94
+ return AlertLevel.EMERGENCY
95
+
96
+ # A stale or lingering-lost aircraft is a last-known position, not a present one, so it
97
+ # must not raise a proximity alert (only the emergency check above still applies).
98
+ if aircraft.is_stale or aircraft.is_lost:
99
+ return AlertLevel.NONE
100
+
101
+ # 2. OVERHEAD: currently inside the proximity radius. An aircraft on the ground is not
102
+ # overhead of anything; at an airport every taxiing aircraft would otherwise ring the
103
+ # bell. It is graded NEARBY instead, which is displayed but never dispatched.
104
+ if aircraft.distance_mi is not None and aircraft.distance_mi <= proximity_mi:
105
+ return AlertLevel.NEARBY if aircraft.on_ground else AlertLevel.OVERHEAD
106
+
107
+ # 3. INBOUND: projected to close within cpa_distance_mi inside cpa_horizon_s, moving
108
+ # fast enough (cpa_min_gs_kt) that the projection isn't just ground-track noise from an
109
+ # aircraft that is essentially parked. cpa_seconds must be strictly in the future (> 0)
110
+ # -- 0 or negative means "now or already past", which OVERHEAD or OUTBOUND handle instead.
111
+ if (
112
+ cpa_enabled
113
+ and aircraft.cpa_distance_mi is not None
114
+ and aircraft.cpa_seconds is not None
115
+ and aircraft.cpa_distance_mi <= cpa_distance_mi
116
+ and 0 < aircraft.cpa_seconds <= cpa_horizon_s
117
+ and (aircraft.ground_speed_kt or 0) >= cpa_min_gs_kt
118
+ ):
119
+ return AlertLevel.INBOUND
120
+
121
+ # 4. OUTBOUND: still within twice the proximity radius, airborne, and
122
+ # geo.closest_point_of_approach returned a cpa_distance_mi with no cpa_seconds -- that
123
+ # combination means the closest approach on its current track is already behind it
124
+ # (a receding target), i.e. it is heading away rather than about to arrive.
125
+ if (
126
+ not aircraft.on_ground
127
+ and aircraft.distance_mi is not None
128
+ and aircraft.distance_mi <= proximity_mi * 2
129
+ and aircraft.cpa_distance_mi is not None
130
+ and aircraft.cpa_seconds is None
131
+ ):
132
+ return AlertLevel.OUTBOUND
133
+
134
+ # 5. Nothing above applies.
135
+ return AlertLevel.NONE
136
+
137
+
138
+ def classify_trend(
139
+ baro_rate_fpm: float | None,
140
+ geom_rate_fpm: float | None,
141
+ threshold_fpm: float,
142
+ ) -> str:
143
+ """Classify vertical motion as "climb", "descend", "level", or "unknown".
144
+
145
+ Prefers barometric rate (baro_rate_fpm); falls back to geometric rate (geom_rate_fpm)
146
+ only when baro is missing. Returns "unknown" -- not "level" -- when neither rate is
147
+ available, so the UI can render a blank cell instead of a false "level" arrow.
148
+ """
149
+ rate = baro_rate_fpm if baro_rate_fpm is not None else geom_rate_fpm
150
+ if rate is None:
151
+ return "unknown"
152
+ if rate >= threshold_fpm:
153
+ return "climb"
154
+ if rate <= -threshold_fpm:
155
+ return "descend"
156
+ return "level"
157
+
158
+
159
+ def trend_glyph(trend: str, ascii_only: bool = False) -> str:
160
+ """Single-character glyph for a classify_trend() result.
161
+
162
+ Unicode set: up-arrow for climb, down-arrow for descend, right-arrow for level, empty
163
+ for unknown. ASCII set (ascii_only=True): "^", "v", "-", and empty for unknown.
164
+ """
165
+ glyphs = _TREND_GLYPHS_ASCII if ascii_only else _TREND_GLYPHS_UNICODE
166
+ return glyphs.get(trend, "")
167
+
168
+
169
+ def decode_db_flags(db_flags: int) -> list[str]:
170
+ """Decode the dbFlags bitfield into its present tags: MIL, INT, PIA, LADD.
171
+
172
+ bit0=military(1), bit1=interesting(2), bit2=PIA(4), bit3=LADD(8). Tags are returned in
173
+ that bit order; bits outside this table (and a falsy/None input) are simply ignored.
174
+ """
175
+ if not db_flags:
176
+ return []
177
+ return [tag for bit, tag in _DB_FLAG_TAGS if db_flags & bit]
178
+
179
+
180
+ def decode_category(category: str | None) -> str | None:
181
+ """Map a common ADS-B emitter category (e.g. "A5") to a short display label.
182
+
183
+ Returns None if category is None. Returns the raw category string unchanged for any
184
+ code not in the table below, rather than dropping it -- an unrecognized but present
185
+ category is still more useful to show than nothing.
186
+ """
187
+ if category is None:
188
+ return None
189
+ return _CATEGORY_LABELS.get(category, category)