What should a Starlink wall tell you when the link matters?

Start with the operator, not the constellation

The research question was not “can we draw Starlink satellites?” It was “what would someone leave running on a wall if this connection mattered?”

Jan Daniel Semrau's Code Clinic demonstrated the enabling chain: public orbital elements, SGP4 propagation through satellite.js, and a Cesium globe. That established a credible starting point for live constellation geometry. We changed the viewpoint from an Earth-scale animation to one observer at one latitude and longitude.

From that position, the calculations become operationally legible: what is above the local horizon, what is above 25 or 45 degrees, which object is highest, and which high passes are predicted over the next two hours. The terminal became the natural surface because it can stay open, avoid a browser shell, and install as one command.

The product changed between v0.1 and v0.2

Version 0.1 proved the geometry loop. It loaded a Starlink catalog, propagated every valid object, rendered a local polar plot, counted elevation bands, and predicted high passes. It looked like a constellation instrument.

The first design review exposed the missing answer: is the connection healthy? Version 0.2 moved a rolling internet-path panel to the primary position and added current, median and p95 latency, jitter, failed-probe percentage, outage duration, and local dish-address reachability. Orbital information remained, but stopped pretending to explain network performance.

v0.1  observer → orbital elements → SGP4 → sky plot

v0.2  computer → HTTPS path → health state
      observer → orbital elements → local geometry
      boundary → geometry is not service quality

Five stages, with the source boundary visible

The implementation is deliberately small. Configuration, data acquisition, orbital math, network sampling, and rendering are separate modules. Each can fail or evolve without turning the others into evidence they do not contain.

1. 01

   Observer contract

   Latitude, longitude, altitude, and a label are validated, then stored under ~/.config. Coordinates are not sent to Lyon Industries or the orbital-data provider.

   Local only

2. 02

   Orbital data

   CelesTrak OMM records are cached for two hours. A stale cache or compressed package snapshot keeps the wall useful when the source is unavailable.

   Live / cached / bundled

3. 03

   Geometry engine

   satellite.js propagates each record with SGP4. Observer-relative look angles produce elevation, bearing, range, altitude, and two-hour pass windows.

   Calculated estimate

4. 04

   Network sampler

   A repeated HTTPS request measures the machine's real internet path. A separate local-address check reports whether a standard Starlink dish endpoint responds.

   Computer path

5. 05

   Terminal renderer

   Ink and React compose stable compact and wall layouts. Braille cells carry the sky plot; text, not colour alone, carries state and uncertainty.

   80 × 24 or wide

One malformed orbital record is skipped. A failed live download falls back to cache, then to the compressed catalog shipped with the release.

Every number needs a boundary

Diagnostics become dangerous when a plausible number is given a stronger name than its source supports. The wall keeps network observations and orbital calculations in separate panels and states their limits in the interface.

Design for a glance, then for an investigation

A terminal UI has no room for ornamental navigation. The primary state must be visible across a room; the reason for that state must be available when someone steps closer. Fixed panels, compact labels, sparklines, and one-key help create those two reading distances.

Release

v0.2.0 / 11 July 2026

Runtime

Node.js 20+ / TypeScript / Ink / React

Orbital propagation

satellite.js 6 / SGP4 / OMM input

Network window

120 samples / 5-second interval / 10 minutes

Automated checks

8 tests / coordinate, status, and visual helpers

Direct dish telemetry

Not implemented

Install the release or rebuild it

The packaged release is the shortest path. It avoids the Git-dependency build step that caused the first global-install failure and uses the Node 20-compatible dependency set shipped in v0.2.0.

# Node.js 20 or newer
npm install --global \
  https://github.com/lyon-industries/starlink-wall/releases/download/v0.2.0/starlink-wall-0.2.0.tgz

starlink-wall

# Change the saved observer later
starlink-wall setup

First run asks for a label, decimal latitude and longitude, and altitude. The coordinates remain in ~/.config/starlink-wall/config.json. Orbital data is cached separately under ~/.cache/starlink-wall/.

To inspect or modify the implementation, clone the source and use the standard TypeScript workflow:

git clone https://github.com/lyon-industries/starlink-wall.git
cd starlink-wall
npm install
npm run dev

npm test
npm run typecheck
npm run build

What the current evidence proves

The tests exercise deterministic boundaries, not the whole Starlink service. A passing classifier proves how samples become a state. It does not prove what caused the samples or whether a dish, beam, gateway, or remote endpoint failed.

The next useful contributions are at the boundaries

The orbital core and terminal composition are deliberately reusable. The highest-value extensions would add evidence without blurring its source: optional authenticated dish telemetry in its own panel, configurable elevation masks, obstruction overlays, exported pass windows, and a browser wall that shares the same calculation modules.

Contributions should preserve the central rule: a new signal receives its own source label, time window, uncertainty, failure state, and test. More data is useful only when the operator can tell what it means.