get_history Notes - sparky8512/starlink-grpc-tools GitHub Wiki

WARNING: Some of the data on this page is out of date, if not completely obsolete. These were my original notes on the history data returned by the gRPC service running on the Starlink dish, but dish firmware changes that were made in mid to late 2021 made significant changes to this data and it's not clear there is much value to this information beyond explaining how the ring buffer formatting works. I have tried to mark the parts that were impacted by the changes, but make no guarantees that what's left is accurate.

This page contains notes about the data returned from a get_history gRPC request sent to a Starlink dish, based on observing the data over time and comparing it to what shows up in the Statistics page of the Starlink Android app (which appears to use this same data via the gRPC service). The names below are from the JSON format data that grpcurl spits out, so are slightly different from what would show up in .proto files that describe the data structures.

DISCLAIMER: This is not official documentation of this data format, and some of what is written here could be a misinterpretation of what the data actually means, and thus be utterly wrong.

Sample points are one per second, the entire data set covers up to 12 hours 15 minutes, and it is arranged in what appears to be a ring buffer. It's not clear what exactly a "ping" means in this data, or between which points it's measuring RTT, but the latency values correspond roughly with ICMP echo ping times from a PC on my home network and IP address 8.8.8.8, so it's presumably at least all the way through a ground station.

current is the total number of samples that have been written to the ring buffer, irrespective of buffer wrap. Since the samples are written once per second and the buffer resets on dish reboot, this value will be roughly equal to dish uptime in seconds. This value can be used to index into the data arrays to find the location of the current data sample. The data arrays are represented as fixed size (currently 900 element) ring buffers. In other words: If "current" is less than 900, then the valid data samples can be found in each array at index 0 (oldest data sample) through (and including) index "current" - 1 (latest data sample). If "current" is greater or equal to 900, then all array elements contain valid data, but it will be ordered within each array as index "current" mod 900 (oldest data sample) through index 899, then index 0 through index ("current" mod 900) - 1 (latest data sample). If the data arrays are different size in the future (again...), then use that size in the modulo arithmetic instead of 900.

popPingDropRate: Fraction of lost ping replies per sample. Given the small fractions reported for some, this implies the dish is collecting stats for many pings per second, and just reporting totals and/or averages per second, but that's just conjecture on my part.

popPingLatencyMs: Round trip time, in milliseconds. NOTE: Whenever the popPingDropRate value is 1 for a sample, it appears the popPingLatencyMs value will just repeat prior value rather than leaving a hole in the data.

downlinkThroughputBps, uplinkThroughputBps: The app labels these "Download Usage" and "Upload Usage", so this is presumably number of bits actually used, not what is available to be used. From the max values, it appears to be in bits per second.

snr: Signal to noise ratio, capped at 9. OBSOLETED: This field was removed from the protocol.

scheduled: When false, ping drop shows up as "No satellites" in app, so presumably true means at least 1 satellite is within geometric view of the dish. OBSOLETED: This field was removed from the protocol.

obstructed: When true, ping drop shows up as "Obstructed" in app, so presumably means dish has somehow detected the view in the direction of the satellite is obstructed. OBSOLETED: This field was removed from the protocol.

There is no specific data field that obviously correlates with "Beta Downtime", so I'm guessing those are the points where popPingDropRate is 1, but the reason could not be identified because "scheduled" is true and "obstructed" is false. OBSOLETED: The app no longer reports a summary of "Obstructed", "No Satellite", and "Beta Downtime" (AKA "Other") outage time, which is presumably why those fields were removed. Instead, it reports a list of outages that the dish believed were long enough to merit noting. This is supported by a new outages field in the history.