Skip to content

Installation and Setup

Jump to bottom
PurpleSentinel edited this page Oct 20, 2026 · 2 revisions

Installation and setup

Prepare the Linux host

Use Raspberry Pi OS Bookworm or newer, Debian 12+, or another Linux distribution with Python 3.11+. The dashboard service uses Python's standard library and does not need third-party Python packages for its basic runtime. Node.js is needed only to rebuild the committed dashboard frontend.

Follow the repository's SBC setup guide. In outline:

  1. Clone the repository and create a private .env from .env.example.
  2. Set separate, strong DASHBOARD_TOKEN and GATEWAY_TOKEN values. Point GATEWAY_URL to the S3's reserved LAN address.
  3. Select a persistent DB_PATH for the SQLite database and protect backups.
  4. Run the service manually for initial setup, or install the supplied systemd unit for unattended startup.
  5. Open the dashboard at http://HOST:8080 on the trusted LAN.

For temporary remote access, an SSH tunnel avoids exposing the dashboard port on the LAN:

ssh -L 8080:127.0.0.1:8080 USER@SBC_HOST

Then open http://127.0.0.1:8080 on the computer running SSH.

Optional Starlink monitoring

Starlink monitoring is disabled until configured and does not require a Starlink cloud account. On Raspberry Pi OS, install python3-grpcio and python3-protobuf with apt, or install the repository's requirements-starlink.txt in the dashboard service's Python environment. Restart the service after installing packages. Under Configuration & Setup → Starlink, enter the router and dish private IPv4 targets and ports independently. The usual defaults are 192.168.1.1:9000 for the router and 192.168.100.1:9200 for the dish; the actual route depends on the local Starlink network. See Operating the system for how to read partial telemetry results.

Configure and flash the gateway

Use the full firmware build and flashing guide. Configure the S3 with the existing 2.4 GHz Wi-Fi network and a unique API token before building. Use the correct image for each chip. Reserve a stable DHCP address for the gateway and SBC.

Do not paste tokens into public issues or commit .env, generated SDK configuration, flash backups or database files. See Data, security and privacy.

First connection

  1. Start the SBC service and confirm it reports the gateway connected and ready.
  2. Connect to the dashboard with the dashboard token.
  3. Open Configuration & Setup and pair one device at a time.
  4. Discover endpoints and clusters, then use the model-specific setup flow where available.
  5. Assign devices to locations and confirm fresh measurements arrive before relying on charts.

Pairing creates network membership; it does not guarantee that a sleepy sensor has completed reporting configuration. See Operating the system and compatibility.

Clone this wiki locally