README

A collection of PHP tools for working with Starlink dish telemetry — currently a parser for the get_status protobuf response returned by the dish's local gRPC API. Ships the generated protobuf classes for the Starlink Device API so consuming applications don't need to carry hundreds of generated files or a .proto toolchain themselves.

Installation

composer require webplace/starlink-tools

{
  "repositories": [
    { "type": "vcs", "url": "git@gitlab.com:webplace/starlink-tools.git" }
  ],
  "require": {
    "webplace/starlink-tools": "^1.0"
  }
}

Tools

StarlinkStatusParser

Parses a base64-encoded get_status gRPC response into a plain PHP array.

use Webplace\StarlinkTool\StarlinkStatusParser;

$status = (new StarlinkStatusParser())->parse($base64Payload);

Returns an associative array grouped by topic:

[
    'api_version' => 42,
    'device' => ['id' => '...', 'hardware_version' => '...', 'software_version' => '...', 'bootcount' => 12, 'build_id' => '...'],
    'uptime_s' => 123456,
    'network' => ['pop_ping_latency_ms' => 24.3, 'pop_ping_drop_rate' => 0.001, 'downlink_bps' => 95000000.0, 'uplink_bps' => 8500000.0],
    'obstruction' => ['fraction_obstructed' => 0.0, 'patches_valid' => 3600],
    'alignment' => ['tilt_angle_deg' => 0.0, 'attitude_uncertainty_deg' => 0.5, 'boresight_azimuth_deg' => 1.2, 'boresight_elevation_deg' => 34.5],
    'outage' => ['cause' => 'NO_OUTAGE', 'cause_code' => 0, 'start_timestamp_ns' => 0],
    'gps' => ['pnt_filter_state' => 3],
    'ready_states' => ['scp' => true, 'l1l2' => true, 'xphy' => true, 'aap' => true, 'rf' => true],
    'flags' => [
        'software_update_state' => 'IDLE', 'sw_update_state_code' => 1,
        'class_of_service' => 'CONSUMER', 'class_of_service_code' => 1,
        'has_signed_cals' => true, 'stow_requested' => false,
        'is_snr_above_noise' => true, 'eth_speed_mbps' => 100,
    ],
    'connected_routers' => ['Router-0100000000000000000EE5'],
]

Any of obstruction, alignment, outage, gps, ready_states may be null if the field is absent from the dish's response — the parser is version-tolerant and doesn't throw on missing fields.

try {
    $status = $parser->parse($base64Payload);
} catch (\InvalidArgumentException $e) {
    // $base64Payload is not valid base64
} catch (\RuntimeException $e) {
    // parsed fine, but it isn't a dishGetStatus response
}

ObstructionMapRenderer

Renders a dish's obstruction_map grid into a "dot radar" PNG matching the official Starlink app. See docs/obstruction-map-renderer.md for full usage.

More tools built on top of Starlink telemetry are expected to land here over time, each as its own class under Webplace\StarlinkTool\.

What's in the package

• src/ — the tools themselves (StarlinkStatusParser today, more to follow).
• generated/SpaceX/API/** — generated protobuf message and enum classes for the Starlink Device API (SpaceX\API\ namespace).
• generated/GPBMetadata/SpacexApi/** — protobuf schema descriptors required by the classes above (GPBMetadata\SpacexApi\ namespace).

Well-known types (Google\Protobuf\Timestamp, StringValue, etc.) are not duplicated here — they're provided by the official google/protobuf composer package, listed under require.

Regenerating the protobuf classes

If Starlink changes its protobuf schema, the classes under generated/ need to be regenerated from a fresh protoset pulled off a live dish. See docs/schema-extraction.md for the full walkthrough.

Requirements

• PHP ^8.2
• google/protobuf ^5.35
• ext-gd

License

MIT — see LICENSE.