Skip to content

Capability 008: Telemetry Values

Status: Accepted

Context

The Robot Operator commands the robot but does not see how it responds: whether the motors turn as commanded and how much charge the battery has left. Since its capability 005, the Superordinate Controller pushes both as a Telemetry Stream.

With this capability, the Web App shows the latest Telemetry Snapshot in the Status Pane. Following the principle Safe when silent of the mission statement, a value shows only while the stream delivers it: when the stream falls silent, the values turn unknown instead of showing their last state.

References

Details

Telemetry Values

Below the Health Indicators, under the heading Telemetry, the Status Pane shows one Telemetry Value per quantity, each as a label and a text next to it. The Telemetry Values stand side by side and wrap onto the next line where the Status Pane is too narrow, like the Health Indicators:

Label Field of the Telemetry Snapshot Text Example
Battery batteryVoltage Volts with one decimal, rounded half away from zero, and V 36.3 V for 36.25
Speed M1 motorSpeeds[0] Whole percent with its sign and % -50 %
Speed M2 motorSpeeds[1] As for Speed M1 50 %
Speed M3 motorSpeeds[2] As for Speed M1 0 %

A Telemetry Value shows unknown while its field is null, before the first Telemetry Snapshot, and while the Telemetry Stream is silent.

Timing

Name Value
Silence limit 3 s without a valid Telemetry Snapshot
Reopen interval 5 s between two attempts to open the Telemetry Stream

Functional Requirements

  1. When the page loads, the Web App opens the Telemetry Stream at the base URL of capability 003.
  2. It shows the fields of the latest valid Telemetry Snapshot as given under Telemetry Values.
  3. When no valid Telemetry Snapshot has arrived for the Silence limit, every Telemetry Value shows unknown until the next one arrives.
  4. When the Telemetry Stream cannot be opened or ends, the Web App opens it anew every Reopen interval.

Non-Functional Requirements

None.

Technical Requirements

  1. The Web App reads the Telemetry Stream with the EventSource of the browser, which every browser of ADR-001 provides; it needs no library.

Error Handling

  1. A Telemetry Snapshot that is no JSON, or whose type is not telemetry, whose version is not 1, or whose batteryVoltage or motorSpeeds violate the schema of remote_control_api.json, is no valid Telemetry Snapshot: the Web App ignores it, so that the values turn unknown at the Silence limit if no valid one follows.
  2. A refused Telemetry Stream, e.g. 503 because too many clients hold one, is treated like a silent one and opened anew as given in Functional Requirement 4.

Out of Scope

  • Entries in the Event Log for the telemetry or for a silent Telemetry Stream
  • Showing the age or the timestamp of a Telemetry Snapshot
  • Charts or a history of the values
  • Warning colors, e.g. for a low battery
  • Pausing the Telemetry Stream while the page is hidden

Acceptance Criteria

All criteria except the last run against a mocked Remote Control API with a mocked Telemetry Stream.

  1. Page loaded, the stream sends batteryVoltage 36.25 and motorSpeeds [-50, 50, 0]: Battery shows 36.3 V, Speed M1 -50 %, Speed M2 50 %, Speed M3 0 %.
  2. Page loaded, before the first Telemetry Snapshot: every Telemetry Value shows unknown.
  3. The stream sends batteryVoltage null and motorSpeeds [null, 7, null]: Battery, Speed M1, and Speed M3 show unknown, Speed M2 7 %.
  4. The stream sends one Telemetry Snapshot and then nothing: the values show it, and every Telemetry Value shows unknown 3 s after it.
  5. The stream sends a Telemetry Snapshot with version 2, then one with motorSpeeds [101, 0, 0], then one that is no JSON: none of them shows; the previous values stay until the Silence limit.
  6. The stream is refused with 503 and accepted 5 s later: the values show the Telemetry Snapshot of the second attempt.
  7. Battery Voltage texts: 36.25 shows 36.3 V, 36.0 36.0 V, 9.95 10.0 V, 0 0.0 V.
  8. With the Superordinate Controller on the robot: the Telemetry Values follow a Rotation and a Translation as for its capability 005, Acceptance Criterion 10; unplugging the CAN Adapter turns them unknown within 4 s (manual test test/manual/robot.md).

Decisions

  1. The Web App judges silence by itself, with a limit of 3 s. The Superordinate Controller marks a value it has not received for 3 s as null, but when the stream itself falls silent, only the Web App notices. 3 s are three missed Telemetry Snapshots at the default interval of the Superordinate Controller. Consequence: with a TELEMETRY_INTERVAL above 3 s, the values turn unknown between two Telemetry Snapshots.
  2. The Web App shows the values as the Superordinate Controller computes them. Conversion to volts and percent, and the sign of each motor, belong to the controller (its capability 005, Decision 2); the Web App only formats them. Consequence: the Web App needs no knowledge of the Drive, only of the geometry of the robot where it derives a movement from the values (capability 010).
  3. The Web App reopens a refused or ended stream itself, every 5 s. EventSource reconnects by itself after a lost connection, but not after an error status such as 503. 5 s match the Health Poll Interval of capability 005. Consequence: after a refusal, the values stay unknown for at least 5 s.