SatNavSCII

A terminal-based satnav. Perspective-tilted map rendering, route navigation, and real-time GPS tracking, all in Braille characters.

Built on the shoulders of mapscii by Michael Strassburger, the original terminal map viewer that proved you could render the whole world in a console. SatNavSCII takes that rendering engine and turns it into a driving experience.

Navigating from Digital Jersey Exchange to Digital Jersey Hub. Roads rendered in Braille, route highlighted in cyan, turn-by-turn directions above the horizon.

Quick start

# Perspective map, keyboard steering
npx tsx main.ts --tilt

# Navigate a route with auto-drive animation
npx tsx main.ts --route "Digital Jersey Exchange, Jersey;Digital Jersey Hub, Jersey" --animate

# Replay a GPX track file
npx tsx main.ts --simulate track.gpx

# Real GPS tracking (requires gpsd)
npx tsx main.ts --gps

# Download tiles for offline use
npx tsx main.ts download --region "Berlin" --zoom 10-16

Run with containers

# Build
podman build -t SatNavSCII -f Containerfile .

# Interactive tilt mode
podman run -it --rm SatNavSCII --tilt

# Route animation
podman run -it --rm SatNavSCII --route "St Helier, Jersey;Gorey, Jersey" --animate

# With GPS (forward gpsd socket)
podman run -it --rm --network=host SatNavSCII --gps

Docker works the same way, just replace podman with docker.

Install from source

Requires Node.js >= 18.

git clone https://github.com/hest-hq/SatNavSCII.git
cd SatNavSCII
npm install
npx tsx main.ts --tilt

CLI flags

Flag	Short	Description
--tilt	-T	Perspective driving mode
--simulate <file>	-S	Replay a GPX track (implies --tilt)
--route "A;B"	-r	Calculate and display route
--animate	-A	Auto-drive along a route
--gps	-G	Real-time GPS via gpsd
--kiosk	-K	Raspberry Pi appliance mode
--osrm <url>		Custom OSRM server
--latitude <n>	--lat	Initial latitude
--longitude <n>	--lon	Initial longitude
--zoom <n>	-z	Initial zoom level
--braille	-b	Braille rendering (default: on)
--headless	-H	No keyboard/mouse input

Download subcommand

npx tsx main.ts download --region "San Francisco" --zoom 10-16

Downloads all map tiles for a region so you can navigate offline.

Keyboard controls

Tilt mode (driving)

• Left/Right arrows rotate heading
• Up/Down arrows move forward/backward
• a/z zoom in/out
• w/s adjust camera pitch
• t toggle between tilt and flat mode
• c toggle Braille/ASCII characters
• q quit

Flat mode (classic mapscii)

• Arrow keys pan the map
• a/z zoom in/out
• t switch to tilt mode
• q quit

Raspberry Pi setup

SatNavSCII can run as a dedicated car dashboard on a Raspberry Pi.

1. Install Node.js 18+ and gpsd
2. Clone this repo to /home/pi/SatNavSCII
3. Plug in a USB GPS dongle
4. Install the systemd service:

sudo cp SatNavSCII.service /etc/systemd/system/
sudo systemctl enable SatNavSCII
sudo systemctl start SatNavSCII

The service auto-starts on boot, connects to gpsd, and restarts on crash.

---

Build a Raspberry Pi 5 car satnav

A complete guide to building a dedicated terminal satnav for your car using a Raspberry Pi 5.

Parts list

Part	Notes	Approx. cost
Raspberry Pi 5 (4GB or 8GB)	The 4GB model is plenty	~$60
Official Pi 5 power supply (27W USB-C)	Or a USB-C car charger that does 5V/5A (PD 27W)	~$12
USB-C car charger (PD 27W+)	Anker 535 or similar. Must support 5V/5A for the Pi 5	~$20
USB-C to USB-C cable (short, 30cm)	Keep it tidy on the dash	~$8
MicroSD card (32GB+)	For the OS. A fast one (A2 rated) helps boot time	~$10
USB GPS dongle	VK-162 or BU-353S4. Any gpsd-compatible receiver works	~$15
Small HDMI display (5" or 7")	Waveshare, Elecrow, or any HDMI portable monitor. Touchscreen not needed	~$35-60
Micro-HDMI to HDMI cable (short)	Pi 5 uses micro-HDMI	~$8
Case or mount	3D-printed dash mount, or just velcro the Pi to the back of the screen	~$5-15
Total		~$170-210

Optional but nice:

• A short USB extension cable if the GPS dongle blocks other ports
• Heatsink or fan case for the Pi 5 (it runs warm)
• A USB keyboard for initial setup (not needed after, kiosk mode runs headless)

Step 1: Flash the OS

1. Download Raspberry Pi OS Lite (64-bit) using the Raspberry Pi Imager
2. In the imager, click the gear icon and configure:
   • Hostname: SatNavSCII
   • Enable SSH (password or key)
   • Set username/password
   • Configure WiFi (for initial setup, not needed in the car)
3. Flash to the microSD card and boot the Pi

Step 2: Install podman and gpsd

SSH into the Pi and run:

sudo apt update && sudo apt upgrade -y
sudo apt install -y podman gpsd gpsd-clients

That's it. No Node.js install needed. SatNavSCII runs entirely inside a container.

Step 3: Configure the GPS dongle

Plug in your USB GPS dongle and find it:

ls /dev/ttyACM* /dev/ttyUSB*

Usually it shows up as /dev/ttyACM0 or /dev/ttyUSB0. Configure gpsd:

sudo nano /etc/default/gpsd

Set these values:

START_DAEMON="true"
GPSD_OPTIONS="-n"
DEVICES="/dev/ttyACM0"
USBAUTO="true"

Start gpsd and verify it's receiving data:

sudo systemctl enable gpsd
sudo systemctl start gpsd
cgps -s

You should see latitude/longitude updating. If you're indoors, take the Pi near a window or outside. Cold starts can take 30-60 seconds.

Step 4: Pull the container image

podman pull ghcr.io/hest-hq/SatNavSCII:latest

Or build it yourself:

git clone https://github.com/hest-hq/SatNavSCII.git
cd SatNavSCII
podman build -t SatNavSCII -f Containerfile .

Test it works:

podman run -it --rm SatNavSCII --tilt

You should see the perspective map. Press q to quit.

Step 5: Download offline tiles

Before heading to the car, download tiles for your area. We mount a volume so tiles persist outside the container:

mkdir -p ~/.local/share/mapscii

# Download your city/region at zoom levels good for driving
podman run -it --rm \
  -v ~/.local/share/mapscii:/root/.local/share/mapscii:Z \
  SatNavSCII download --region "San Francisco Bay Area" --zoom 10-16

# Or for a road trip, download a larger area at lower zoom
podman run -it --rm \
  -v ~/.local/share/mapscii:/root/.local/share/mapscii:Z \
  SatNavSCII download --region "California" --zoom 8-13

A city at zoom 10-16 is typically 50-200MB.

Step 6: Set up auto-start with systemd

Create the container service unit:

sudo tee /etc/systemd/system/SatNavSCII.service << 'EOF'
[Unit]
Description=SatNavSCII - Terminal Satnav (Container)
After=gpsd.service network-online.target
Wants=gpsd.service

[Service]
Type=simple
ExecStartPre=-/usr/bin/podman rm -f SatNavSCII
ExecStart=/usr/bin/podman run --name SatNavSCII \
  -it --rm \
  --network=host \
  -v /root/.local/share/mapscii:/root/.local/share/mapscii:Z \
  -e TERM=xterm-256color \
  SatNavSCII --kiosk
Restart=always
RestartSec=3
StandardOutput=tty
StandardInput=tty
TTYPath=/dev/tty1
TTYReset=yes
TTYVHangup=yes

[Install]
WantedBy=multi-user.target
EOF

Configure auto-login on tty1 so the Pi boots straight to SatNavSCII:

sudo mkdir -p /etc/systemd/system/getty@tty1.service.d
sudo tee /etc/systemd/system/getty@tty1.service.d/autologin.conf << 'CONF'
[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin root --noclear %I $TERM
CONF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable SatNavSCII
sudo systemctl start SatNavSCII

Step 7: Mount in the car

1. Connect the HDMI display to the Pi
2. Plug in the USB GPS dongle
3. Power the Pi from your USB-C car charger
4. Mount the screen on your dash (suction cup, vent mount, or velcro)

The Pi boots in about 15 seconds, gpsd acquires a fix in 30-60 seconds, and SatNavSCII starts automatically in kiosk mode. The map tilts, the heading follows your direction of travel, and zoom adjusts with speed.

Step 8: Test drive

Take it for a spin. What you should see:

• Perspective Braille map tilted toward the horizon
• Roads stretching ahead of you
• Map auto-rotating as you turn
• Zoom pulling back on highways, zooming in on city streets
• HUD at the bottom showing coordinates and compass heading

Tips

• First boot outdoors. GPS cold start needs clear sky. After the first fix, subsequent starts are faster (warm start).
• Power on before starting the car. Some car USB ports lose power briefly during ignition. A PD car charger with the engine already running is most reliable.
• Font size matters. If the Braille characters are too small on your display, reduce the terminal font size or increase the display resolution. A 7" 1024x600 display with a monospace font at 14px works well.
• Night driving. The dark theme (default) is good for night. If you want even less glare, reduce the display brightness.
• No internet needed. Once tiles are downloaded, everything works offline. GPS doesn't need internet. Only route calculation needs a network connection (or run your own OSRM instance).
• Run your own OSRM. For fully offline routing, run OSRM as another container on the Pi. Download OSM data for your region, process it, and run the OSRM container alongside SatNavSCII. Point SatNavSCII at it with --osrm http://localhost:5000. See OSRM Docker setup.
• Updating. Pull the latest container image with podman pull ghcr.io/hest-hq/SatNavSCII:latest and restart the service with sudo systemctl restart SatNavSCII. Your offline tiles are stored in a volume so they survive container updates.
• Logs. Check what's happening with sudo journalctl -u SatNavSCII -f.

Architecture

main.ts ──> Mapscii.ts ──> Renderer.ts (flat, original)
                │
                ├──> PerspectiveRenderer.ts (tilted, Mode 7 projection)
                │         ├── Camera.ts (position, heading, pitch, FOV)
                │         ├── HUD (speed, ETA, turn-by-turn, minimap)
                │         └── Route overlay (OSRM polyline)
                │
                ├──> RoutingService.ts (OSRM + Nominatim geocoding)
                ├──> GPSInput.ts (gpsd integration + jump filter)
                ├──> GPXReplay.ts (track file playback)
                └──> TileDownloader.ts (offline region download)

The perspective renderer uses Mode 7-style projection: each map-space point is rotated by the camera heading and projected through a focal point. Near points appear at the bottom of the screen (foreground), far points compress toward the horizon. The math is ~20 lines.

Acknowledgments

SatNavSCII would not exist without mapscii by Michael Strassburger. The entire rendering pipeline, Braille character encoding, vector tile parsing, and canvas abstraction come from mapscii. SatNavSCII adds the perspective projection, routing, GPS, and navigation layers on top.

Map data from OpenStreetMap, licensed under ODbL. Routing by OSRM. Geocoding by Nominatim.

Special thanks to:

• lukasmartinelli and manuelroth for OSM2VectorTiles
• mourner for earcut, rbush, and simplify-js

License

MIT