Interactive map viewer for the terminal with vector or raster tiles rendered as ASCII, Unicode quadrants, or braille.
Latest update provides massive performance improvements and an easy to run Windows executable. Click here for the release.
Windows (PowerShell):
.\setup.ps1
macOS / Linux:
./setup.sh
This makes a venv, installs CartoTUI, and builds the native renderer if a C
compiler is present (otherwise the Python renderer is used). It then offers to
set up the ADS-B connection; skip that step with -SkipAdsb (or --skip-adsb).
Then run:
python -m cartotui --mvt-url "https://tiles.versatiles.org/tiles/osm/{z}/{x}/{y}" --lat 43.2081 --lon -71.5376 --zoom 14
CartoTUI can overlay live aircraft on the map. Pick and test a source:
.\configure.ps1 adsb # Windows
./configure.sh adsb
The quickest path is a free public feed, no receiver required:
./configure.sh adsb --source api
It follows the map centre as you pan. Providers: airplanes.live (default),
adsb.lol, adsb.fi.
| Source | What it is |
|---|---|
api |
Free public feed over the internet. No hardware |
sbs1 |
dump1090 / readsb / PiAware, local or on the network (SBS-1, TCP 30003) |
lakeshark |
LakeShark receiver on a USB serial port |
lakeshark_tui |
LakeShark receiver, ESP_LOG console format |
replay |
Play back a recorded .jsonl capture |
./configure.sh adsb --source sbs1 --host 192.168.1.50 --port 30003
./configure.sh adsb --source api --provider adsb.lol --radius 150
./configure.sh adsb --test # re-probe the saved source
./configure.sh adsb --list-ports # show serial ports
./configure.sh adsb --disable
CartoTUI only reads ADS-B, something has to decode 1090MHz off an SDR and serve it. To see what this machine has, and what it could install:
./configure.sh adsb --server-status
./configure.sh adsb --install-server # shows the plan only
./configure.sh adsb --install-server --yes # actually runs it
| Host | Backend |
|---|---|
| Raspberry Pi (ARM Debian: bullseye/bookworm/trixie) | dump1090-fa from the FlightAware repo. Serves SBS on 30003 out of the box |
| Debian/Ubuntu amd64 | dump1090-mutability, where the distro still ships it |
| Anything else Linux | readsb via the wiedehopf install script |
| Windows | Guided only - see below |
FlightAware builds dump1090-fa for armhf/arm64 Debian only, so it is not
offered on amd64 or Ubuntu, where apt could not resolve it.
--install-server prints the exact commands and does nothing without --yes.
On Windows there is no packaged ADS-B server, and the SDR's driver must be
replaced with WinUSB via Zadig, an admin GUI step no
script can safely drive. --install-server prints the steps instead. Once
dump1090.exe --net --net-sbs-port 30003 is running, point CartoTUI at it:
.\configure.ps1 adsb --source sbs1 --host localhost --port 30003
Edit config.json without hunting for the file:
.\configure.ps1 set ui.theme dark # Windows
./configure.sh set render.vector_scale 8
./configure.sh list --flat
./configure.sh themes
Full documentation is in docs/wiki.
| Installation | Setup, the native renderer, where files live |
| Keybindings | Every key |
| Rendering | View modes, palettes, dither, thresholds, Looks |
| Image adjust | Brightness, contrast, gamma, saturation, levels |
| Themes | Built-in themes and writing your own |
| Configuration | Everything in config.json |
| ADS-B | Live aircraft, sources, receivers |
| Overlays | Weather radar |
| Settings | Unified settings and tools, including keyboard navigation |
| Snapshots | PNG and HTML export |
| Troubleshooting | When something is wrong |
| Architecture | How the code fits together |