Boltwatch station network

Set up your feeder agent

You need Python 3.10 or newer, an internet connection, and a station token from the pilot. No extra Python packages are required. The agent sends health reports; it does not sample radio signals or locate lightning.

  1. 1. Register your station

    Use your pilot invitation on the station page. Save the token it gives you. Your exact coordinates stay private.

  2. 2. Download and inspect the agent

    Download boltwatch_feeder.py and its MIT licence. Read the source before running it, then save it in a directory of your choice.

  3. 3. Configure your connection

    python3 boltwatch_feeder.py configure

    The setup asks for the Boltwatch origin, your hidden station token, and an optional receiver health JSON file. Leave the file path blank to check the agent connection first. The configuration file contains your secret and is created with owner-only permissions.

  4. 4. Send a heartbeat

    python3 boltwatch_feeder.py run --once
python3 boltwatch_feeder.py run

    The first command sends one heartbeat. The second keeps running, normally every 30 seconds. Open your station dashboard to see the result. Press Ctrl+C to stop the agent.

  5. 5. Connect real receiver measurements

    Your receiver or an adapter must write a JSON file with the fields below. Replace the file atomically after each measurement window. No hardware-specific adapter is included yet. Missing measurements remain unknown; the agent never invents them.

    {
  "reported_at": "2026-09-30T09:00:00Z",
  "window_seconds": 60,
  "gnss_locked": true,
  "timing_uncertainty_ns": 800,
  "noise_floor_dbfs": -52,
  "clipped_fraction": 0.001,
  "dropped_samples": 0,
  "received_signals": 50,
  "submitted_signals": 46,
  "sample_rate_hz": 500000
}

    This is an illustrative report, not sample data to run as a receiver. Use the actual UTC report time and counts for that measurement window. Keep that timestamp unchanged when sending the same report again.

Reading the diagnostics

Timing above 1 microsecond, clipping above 1% and any dropped samples trigger pilot warnings. These are initial diagnostic thresholds, not certified accuracy limits. The noise floor is shown without a universal pass/fail threshold because receivers differ. Local storm sensors, including AS3935 devices, are tracked separately from GNSS-timed VLF receivers.

Your station and your data

Boltwatch stores your station name, receiver type, private coordinates and the latest telemetry. It stores a hash of your token. Your token stays in this browser’s memory while the dashboard is open, and in your agent’s private configuration file. Delete the station in the dashboard to remove the active records and revoke the token. Server backups may retain deleted records until they expire.

Telemetry permission does not grant rights to redistribute waveform recordings or third-party lightning feeds. Those need a separate agreement before the network accepts them.