DOCSEARCHbyAlgolia
Submit Docs

starlink-grpc-tools

repository·main·Indexed 20 days ago

https://github.com/sparky8512/starlink-grpc-tools

A suite of Python and Docker-based tools for interacting with the gRPC service on Starlink user terminals. It includes the starlink-grpc-core package for developers and scripts for collecting status and history data, generating obstruction maps, controlling dish settings (reboot, stow, sleep), and scheduling firmware updates. Supports multiple output backends including InfluxDB 1.x/2.x, SQLite, MQTT, Prometheus, and CSV.

Tokens
3.4K
Snippets
13
Records
17
Agent score
72%

What's inside starlink-grpc-tools

  1. Prerequisites for connecting to the Starlink dish

    main

    All tools in this repository expect the Starlink user terminal (the dish) to be reachable at its fixed IP address: 192.168.100.1.

    Network Configuration Note: If you are using a router other than the official Starlink router, you may need additional configuration to ensure the dish's IP is reachable on your local network. If the official Starlink mobile app cannot connect to the dish on your network, these scripts will also fail to connect.

  2. Configure polling intervals and history aggregation

    main

    Due to firmware changes, the dish only returns the most recent 15 minutes of history data. To avoid data loss, ensure your polling interval (-t) is less than 900 seconds.

    To compute statistics over periods longer than the 15-minute buffer, combine the -t (interval) and -o (aggregation count) options. The statistics will be computed against a period of (-t * -o) seconds.

    Example: Polling every 60 seconds but computing statistics once per hour (60 * 60 = 3600s).

    # Poll history data once per minute, but compute statistics once per hour
python3 dish_grpc_text.py -t 60 -o 60 ping_drop

  3. Run starlink-grpc-tools using Docker or Podman

    main

    The project provides a multi-arch Docker image (supporting linux/amd64 and linux/arm64) hosted on GitHub Packages. If using Podman, replace docker with podman in all commands.

    To pull the latest sanity-tested image:

    docker pull ghcr.io/sparky8512/starlink-grpc-tools

    To run a specific script, use the following pattern:

    docker run --name=starlink-grpc-tools ghcr.io/sparky8512/starlink-grpc-tools <script_name>.py <script args...>

    Example: Print current status info and exit:

    docker run --name=starlink-grpc-tools ghcr.io/sparky8512/starlink-grpc-tools dish_grpc_text.py -v status alert_detail
    docker pull ghcr.io/sparky8512/starlink-grpc-tools

docker run --name=starlink-grpc-tools ghcr.io/sparky8512/starlink-grpc-tools dish_grpc_text.py -v status alert_detail

  4. Use and contribute user-contributed dashboards

    main

    The dashboards/ directory contains community-contributed dashboards designed to visualize data collected by the scripts in this project.

    If you create a new dashboard, you can contribute it to the repository by filing a pull request. Alternatively, you can host your dashboard elsewhere and update the Dashboards Wiki article with a link to it. The project Wiki is open for editing by anyone with a GitHub login.

  5. Install starlink-grpc-tools using Docker or Podman

    main
    If you prefer not to manage Python dependencies locally, you can run the tools within a container. This requires Docker or Podman to be installed and configured. When using a container, you only need to ensure that the Starlink dish IP address is reachable from your host environment.

  6. Install and run via SystemD (Debian/Ubuntu)

    main

    To run scripts like dish_grpc_influx2 as a system service, follow these steps to set up a Python virtual environment and a SystemD unit:

    1. Install python3-venv.
    2. Clone the repository to /opt/starlink-grpc-tools.
    3. Create and activate a virtual environment.
    4. Install dependencies via pip3 install -r requirements.txt.
    5. Copy the service file from systemd/starlink-influx2.service to /etc/systemd/system/.
    6. Edit the service file to set your InfluxDB URL, token, bucket, and org.
    7. Enable and start the service.
    sudo apt instlall python3-venv
cd /opt/
sudo mkdir starlink-grpc-tools
sudo chown <your non-root user>
git clone <git url>
cd starlink-grpc-tools
python3 -m venv venv
source venv/bin/activate.sh
pip3 install -r requirements.txt
sudo cp systemd/starlink-influx2.service /etc/systemd/system/starlink-influx2.service
sudo <your favorite editor> /etc/systemd/system/starlink-influx2.service
# Set influx url, token, bucket and org
sudo systemctl enable starlink-influx2
sudo systemctl start starlink-influx2

  7. Install starlink-grpc-tools via pip

    main

    To use the tools locally without Docker, you must have Python 3.7 or later installed. It is recommended to use a virtual environment (venv). You can install all required dependencies by running the following command:

    pip install --upgrade -r requirements.txt

    If you encounter permission issues on certain OS distributions, you can use the --user flag, though this will limit availability to that specific user.

  9. Use the starlink_grpc module in Python

    main

    Once installed, the starlink_grpc module is available in your Python environment. You can import it directly to access low-level core functionality for the Starlink user terminal gRPC service. For specific function signatures and details, refer to the docstrings within the starlink_grpc.py module itself.

    import starlink_grpc

# Call functions from the module as needed

  10. Use the gRPC data collection scripts

    main

    The grpc scripts are the primary tools for collecting Starlink dish data. They support various output backends:

    • dish_grpc_text.py: Writes to standard output (default: CSV, use -v for human-readable).
    • dish_grpc_influx.py / dish_grpc_influx2.py: Sends data to InfluxDB 1.x or 2.x.
    • dish_grpc_sqlite.py: Writes to a SQLite database.
    • dish_grpc_mqtt.py: Sends data to an MQTT broker.
    • dish_grpc_prometheus.py: Exposes an HTTP endpoint for Prometheus scraping.

    All scripts support processing status data (real-time dish info) and history data (statistics). You select data groups by passing their mode names as arguments. Use -h to see available modes.

    Key Options:

    • -t <seconds>: Run in a periodic loop with the specified interval.
    • -o <count>: Aggregate data for statistics (used with -t).
    • -v: Human-readable output (for dish_grpc_text.py).
    • bulk_history: A special mode for collecting full second-by-second data instead of summaries.
    # Output all available status groups to stdout in CSV format
python3 dish_grpc_text.py status obstruction_detail alert_detail

# Capture status info to InfluxDB every 30 seconds
python3 dish_grpc_influx.py -t 30 status

# Collect bulk history data in a loop
python3 dish_grpc_influx.py -t 30 bulk_history

  11. Enable access to location data

    main

    Warning

    As of 2026-May, location data is no longer available via gRPC for most service plans.

    If you are on a compatible plan and wish to use the location data group with the gRPC scripts, you must manually enable access via the Starlink mobile app (version 2022.09.0 or later). Enabling this allows any device on your local network to access the dish's physical GPS location.

    Steps to enable via the Starlink mobile app:

    1. Log in to your Starlink account in the app (tap the user icon in the upper left).
    2. Navigate to SETTINGS.
    3. Select ADVANCED.
    4. Select DEBUG DATA.
    5. Scroll to the STARLINK LOCATION section.
    6. Toggle "allow access on local network" to ON.

  12. Configure InfluxDB 1.x for Docker usage

    main

    The default command for the container is dish_grpc_influx.py status alert_detail. This requires an InfluxDB 1.x server. You must provide connection details via environment variables:

    • INFLUXDB_HOST: InfluxDB Hostname
    • INFLUXDB_PORT: Port (usually 8086)
    • INFLUXDB_USER: (Optional) InfluxDB Username
    • INFLUXDB_PWD: (Optional) InfluxDB Password
    • INFLUXDB_DB: Pre-created DB name (e.g., starlinkstats)

    Note: This uses the legacy InfluxDB 1.x client.

    docker run --name=starlink-grpc-tools -e INFLUXDB_HOST={InfluxDB Hostname} \
    -e INFLUXDB_PORT={Port, 8086 usually} \
    -e INFLUXDB_USER={Optional, InfluxDB Username} \
    -e INFLUXDB_PWD={Optional, InfluxDB Password} \
    -e INFLUXDB_DB={Pre-created DB name, starlinkstats works well} \
    ghcr.io/sparky8512/starlink-grpc-tools