Starlink Client Python Library

The starlink-client is a Python library designed to provide programmatic access and control over Starlink satellite internet systems. It acts as a client that facilitates communication with Starlink hardware, specifically the dish antenna and router, enabling users to retrieve operational data and manage various configurations. This library offers two primary modes of connection to the Starlink system: directly via the local network or remotely through the Starlink API.

For connections established within the local network where the Starlink system is accessible, the library communicates directly with the gRPC server running on the Starlink dish, typically on port 9200. This local connection does not require authentication, simplifying direct interaction and real-time data access. For remote interactions, the library utilizes the Starlink API, communicating over gRPC-Web and REST protocols. Remote access necessitates authentication, which is handled by extracting a session cookie from a logged-in browser interface. While these cookies have a typical validity period of 15 days, the library incorporates a cookie refresh mechanism, allowing for extended use if the client is utilized within this refresh window.

Key Features and Capabilities

The starlink-client library offers a comprehensive suite of functionalities for managing and monitoring a Starlink system. These capabilities are exposed through predefined Python methods, though direct gRPC calls using the protobuf messages are also supported for advanced use cases.

• Account and Device Information Retrieval: Users can fetch detailed account data, including email and customer names. The library also provides device location, offering precise real-time coordinates when connected locally, or the associated H3 cell ID for remote connections.
• Network Statistics Monitoring: Essential network performance metrics such as latency and current download speed can be retrieved, enabling users to monitor their internet connection's health and performance.
• Dish Management: The library allows for remote rebooting of the Starlink dish, a useful feature for troubleshooting or routine maintenance. It also supports setting various dish configurations, such as activating snow melt mode for colder climates or enabling power-saving modes.
• Telemetry Data Access: Comprehensive telemetry data from both the dish and the router can be accessed. This includes crucial operational information, status alerts, errors, and warnings, providing deep insights into the system's operational state.
• WiFi Configuration and Status: Users can retrieve the status of the Starlink router's WiFi, including connected client information and SSID details. Furthermore, the library enables modification of WiFi settings, such as changing the SSID name, toggling SSID visibility, updating passwords, and enabling bypass mode.

Technical Details and Implementation

The foundation of starlink-client lies in its interaction with the Starlink system's gRPC interfaces. The developers reverse-engineered the communication protocols by extracting the .proto files directly from the Starlink antenna firmware using tools like grpc-curl. These protobuf definitions are then compiled for specific languages, leveraging tools like ConnectRPC, although this library specifically implements the Python client. The library is compatible with Python 3.9 and newer versions. Authentication for remote access relies on securely handling session cookies obtained from the Starlink web interface, with built-in mechanisms to manage cookie expiration and refresh.

Target Audience and Use Cases

This library is an invaluable resource for a diverse range of users, including:

• Developers and System Integrators: Those looking to integrate Starlink system data and control into custom applications, smart home systems, or centralized network management platforms.
• Network Administrators and IT Professionals: Individuals responsible for monitoring and managing multiple Starlink installations, enabling automated diagnostics, configuration, and proactive maintenance.
• Researchers and Hobbyists: Users interested in exploring the technical aspects of the Starlink system, collecting data for analysis, or building personal monitoring dashboards.
• Power Users: Individuals who desire more granular control over their Starlink system than what is typically offered through the standard user interface, enabling automation of tasks like dish reboots or WiFi configuration changes.

Open-Source Nature

Distributed under the MIT License, starlink-client is an open-source project. This allows for community contributions, auditing, and ensures its accessibility for a wide range of applications. It is important to note that this project is an independent endeavor, created by a fan of the service, and is not officially affiliated with SpaceX or Starlink.