starlink-grpc-tools/get_history_notes.txt

22 lines
3.4 KiB
Text

This file 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, 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 43200 element) ring buffers. In other words: If "current" is less than 43200, 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 43200, then all array elements contain valid data, but it will be ordered within each array as index "current" mod 43200 (oldest data sample) through index 43199, then index 0 through index ("current" mod 43200) - 1 (latest data sample). If the data arrays are different size in the future, then use that size in the modulo arithmetic instead of 43200.
"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.
"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.
"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.
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.