DishPulse

Local-first Starlink micro-outage monitor with telemetry, outage analytics, and a visual dashboard.

DishPulse is a small local monitoring tool for investigating short Starlink connectivity drops. It continuously checks internet reachability, detects outage events, collects local Starlink telemetry when available, and visualizes the results in a web dashboard.

The project was created to better understand intermittent Starlink micro-outages in a real home network where partial sky obstruction may affect connection quality.

---

Overview

Short network drops are often hard to troubleshoot because they may last only a few seconds and happen irregularly. Standard speed tests usually miss them, and manual observation is unreliable.

DishPulse focuses on these short events by combining:

• frequent multi-target connectivity checks
• outage event detection
• local Starlink telemetry
• latency and obstruction visualization
• historical analytics
• readable recommendations based on collected data

The goal is to make short connectivity problems easier to observe, measure, and understand.

---

Key questions this tool helps answer

• How often does the connection drop?
• How long do outages last?
• Are outages random, or do they appear around certain time windows?
• Do latency spikes happen before or during outages?
• Does Starlink report obstruction or alerts?
• Is the current dish placement likely contributing to the problem?
• Would a backup WAN connection be useful?

---

Features

Connectivity monitoring

• Multi-target internet checks
• Ping and HTTP checks
• Default check interval: 2 checks per second
• Configurable timeout in milliseconds
• Outage detection only when all configured targets fail
• Configurable outage start and recovery thresholds

Outage analytics

• Outage event table
• Uptime percentage
• Total downtime
• Longest outage
• Outages by hour
• Outage duration distribution
• Weekly heatmap
• Detected recurring windows

Starlink telemetry

• Local Starlink telemetry integration through optional gRPC tools
• Starlink connection state
• Latency
• Obstruction fraction
• Current obstruction status
• Dish direction: azimuth and elevation
• Alerts
• Throughput telemetry
• Power and usage data where available

Visual dashboard

• Live connection status
• Starlink quick insight
• Tree/obstruction impact gauge
• Human-readable recommendation text
• Dish direction compass
• Latency and obstruction graphs
• Obstruction-focused chart
• Light and dark mode
• RU/EN interface switch

Speedtest

• Manual speedtest
• Optional scheduled speedtest
• Configurable schedule frequency in hours

Telegram alerts

• Optional Telegram notifications
• Configurable alert types
• Test notification button
• Outage started/recovered alerts
• Optional speedtest alerts

Windows convenience

• PowerShell runner
• Virtual environment auto-creation
• Optional Windows autostart through Task Scheduler

---

Tech stack

• Python
• FastAPI
• SQLite
• HTML/CSS/JavaScript
• Chart.js
• httpx
• speedtest-cli
• Optional: starlink-grpc-tools / starlink-grpc-core

---

Architecture

DishPulse
├── FastAPI backend
│   ├── connectivity monitor worker
│   ├── Starlink telemetry worker
│   ├── speedtest worker
│   ├── outage detection engine
│   └── SQLite persistence layer
│
├── SQLite database
│   ├── settings
│   ├── connectivity checks
│   ├── outage events
│   ├── Starlink telemetry
│   └── speedtest results
│
└── Web dashboard
    ├── dashboard
    ├── live checks
    ├── outages
    ├── analytics
    ├── Starlink telemetry
    ├── speedtest
    └── settings

---

Project structure

dishpulse/
├── app/
│   ├── main.py               # FastAPI app and API routes
│   ├── monitor.py            # monitoring loops, Starlink telemetry, speedtest, Telegram
│   ├── db.py                 # SQLite schema and queries
│   └── static/
│       ├── index.html        # web UI
│       ├── app.js            # frontend logic and charts
│       └── style.css         # responsive UI styling
│
├── requirements.txt          # main dependencies
├── requirements-starlink.txt # optional Starlink telemetry dependencies
├── run.ps1                   # Windows runner
├── .env.example              # example config placeholder
├── .gitignore
├── LICENSE
└── README.md

---

Installation

1. Install prerequisites

You need:

• Git for Windows
• Python 3.12 recommended
• Windows PowerShell

Python 3.12 is recommended because some Python networking and telemetry dependencies may lag behind very new Python releases.

2. Clone the repository

git clone https://github.com/aibr442/dishpulse.git
cd dishpulse

3. Run the app

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\run.ps1

The script will:

• create .venv
• install dependencies
• try to install optional Starlink telemetry dependencies
• start the FastAPI server

Open:

http://127.0.0.1:8010

---

Optional Starlink telemetry setup

DishPulse works without Starlink telemetry, but the Starlink page becomes much more useful when the optional gRPC package is available.

If optional telemetry did not install automatically, run:

cd C:\projects\dishpulse
. .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-starlink.txt

You can also check if the Starlink gRPC port is reachable:

Test-NetConnection 192.168.100.1 -Port 9200

If TcpTestSucceeded is True, local Starlink telemetry should be reachable from your PC.

---

Telegram alerts setup

1. Open Telegram.
2. Search for @BotFather.
3. Send:

/newbot

4. Follow the instructions and copy the bot token.
5. Open your new bot in Telegram and press Start.
6. Send any message to your bot, for example:

hello

7. Open this URL in a browser, replacing TOKEN with your real token:

https://api.telegram.org/botTOKEN/getUpdates

8. Find:

"chat": {
  "id": 123456789
}

9. Put the bot token and chat ID into:

DishPulse → Settings → Telegram

10. Enable Telegram alerts and click Send Telegram test.

---

Configuration

Most settings are available directly in the web UI:

• check interval
• timeout
• ping targets
• HTTP targets
• outage thresholds
• Starlink telemetry on/off
• scheduled speedtest on/off
• speedtest frequency in hours
• Telegram settings
• Windows autostart
• language
• light/dark theme

---

Security and privacy

DishPulse is designed as a local-first tool.

Before publishing or sharing your own copy, make sure not to commit:

• Telegram bot tokens
• Telegram chat IDs
• SQLite databases with real monitoring history
• .venv
• logs
• local .env files

The provided .gitignore excludes common runtime and secret files.

---

Notes

This project currently targets local Windows usage and home-network diagnostics. It is not intended to replace professional network monitoring systems, but it can be useful for observing short Starlink interruptions and collecting evidence before changing dish placement, network topology, or adding backup connectivity.

---

Roadmap

v1

• Connectivity monitoring
• Outage detection
• Starlink telemetry
• Dashboard
• Analytics
• Telegram alerts
• Speedtest
• Light/dark theme
• RU/EN UI

v2

• CSV export
• Docker support
• Demo mode with sample data
• Screenshot gallery
• Better documentation
• Dual-WAN recommendation engine

v3

• Router integration
• Predictive failover recommendation
• Optional failover scripts
• More advanced anomaly detection

---

Suggested GitHub repository description

Local-first Starlink micro-outage monitor with FastAPI, SQLite, telemetry, outage analytics, and a visual dashboard.

---

Suggested GitHub topics

starlink
network-monitoring
fastapi
sqlite
observability
dashboard
outage-detection
telemetry
python
chartjs
windows

---

License

MIT License.