Skip to content

Capability 010: Measured Movement

Status: Accepted

Context

The Movement Preview of capability 009 shows what the Robot Operator has entered, not what the motors do. Whether a motor lags, stalls, or turns the wrong way shows only in three percentages of the Telemetry Values, which nobody reads as a direction.

With this capability, the Movement Preview also draws the Measured Movement: the Translation and Rotation that the Measured Speeds of the three motors amount to, as green arrows over the blue ones. Where green and blue differ, the robot does not do what it was told.

The Web App derives the Measured Movement from the Telemetry Snapshot by itself: the Remote Control API carries the measured values only, and the derivation needs the geometry of the robot, not knowledge of the Drive.

References

  • Movement Preview, Robot Circle, and the blue arrows: capability 009
  • Telemetry Snapshot and its silence: capability 008
  • Kinematics that the derivation inverts: Superordinate Controller, capabilities 002 and 003, sections Kinematics
  • Accessibility: directives in user_experience.md

Details

Derivation

The Superordinate Controller gives each target speed as \(v_i = 10\,s\sin(\theta_i - \alpha)\) for a Translation and as \(v_i = -10\,\omega\) for a Rotation, with the motors at \(\theta = 60°, 180°, 300°\). From the motorSpeeds \(p_1, p_2, p_3\) of the latest Telemetry Snapshot, which carry the sign of the target speed, the Web App derives

\[ \omega = -\frac{p_1 + p_2 + p_3}{3}, \qquad F = \frac{p_1 - p_3}{\sqrt{3}}, \qquad R = \frac{2p_2 - p_1 - p_3}{3} \]
\[ s = \sqrt{F^2 + R^2}, \qquad \alpha = \operatorname{atan2}(R, F) \bmod 360° \]

\(s\) is the speed of the measured Translation in percent, \(\alpha\) its direction in degrees as in the box Translation, and \(\omega\) the speed of the measured Rotation in percent: positive clockwise, negative counterclockwise.

Test vectors, the rows of the Kinematics tables of the Superordinate Controller in reverse:

motorSpeeds Measured Translation Measured Rotation
[87, 0, -87] 0°, 100 % none
[-50, 100, -50] 90°, 100 % none
[-87, 0, 87] 180°, 100 % none
[50, -100, 50] 270°, 100 % none
[26, 71, -97] 45°, 100 % none
[-50, -50, -50] none clockwise, 50 %
[20, 20, 20] none counterclockwise, 20 %
[-50, 0, -50] 90°, 33 % clockwise, 33 %
[1, 0, -1] none none

Directions are given to the whole degree and speeds to the whole percent; "none" means below the Noise limit.

Drawing

Element Shape Stroke
Measured Translation arrow Straight arrow from the origin in the direction \(\alpha\), with the length \(\min(s, 100) / 100\) of the radius of the Robot Circle Muted green, 2 pt
Measured Rotation arrow Arc on the radius of the Rotation arrow of capability 009, starting straight above the origin, over \(\min(\lvert\omega\rvert, 100) / 100 \cdot 45°\); its head ends right of the start for a positive \(\omega\), left of it for a negative one Muted green, 2 pt

The green arrows are drawn after the blue ones, so that a green arrow covers a blue one where they overlap.

Limits

Name Value
Noise limit 2 %: below it, \(s\) yields no Measured Translation arrow and \(\lvert\omega\rvert\) no Measured Rotation arrow

Functional Requirements

  1. The Movement Preview shows the Measured Movement of the latest valid Telemetry Snapshot as given under Derivation and Drawing.
  2. While a motorSpeeds entry is null, or the Telemetry Values show unknown after the Silence limit of capability 008, the Movement Preview shows no green arrow.
  3. A speed below the Noise limit yields no green arrow of its kind.
  4. The text alternative of the Movement Preview also names the Measured Movement, e.g. Movement Preview: Translation in direction 90°, Rotation clockwise, measured Translation in direction 90° at 100 %.

Non-Functional Requirements

None.

Technical Requirements

  1. The green reaches the contrast ratios of capability 009, Technical Requirement 1, for the blue.

Error Handling

  1. A Measured Movement is never derived from an incomplete or stale Telemetry Snapshot; the Movement Preview shows no green arrow instead, as given in Functional Requirement 2.

Out of Scope

  • The movement of the robot over the floor: the Measured Movement follows the wheels, which may slip or turn freely while the robot is lifted
  • Detecting an inconsistent Telemetry Snapshot: three motors leave no redundancy, so a stalled motor shows as a Translation and Rotation of its own
  • A history or trail of the Measured Movement

Acceptance Criteria

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

  1. Each row of the test vectors under Derivation yields its measured Translation and Rotation (unit test of the derivation).
  2. The stream sends motorSpeeds [-50, 100, -50]: the head of the Measured Translation arrow lies at \((r, 0)\) relative to the origin, within 1 px; no Measured Rotation arrow.
  3. The stream sends [-50, 0, -50]: the Measured Translation arrow points right with one third of the radius, and the Measured Rotation arrow runs clockwise over 15°.
  4. The stream sends [100, -100, -100]: the Measured Translation arrow ends on the Robot Circle.
  5. The stream sends [null, 7, null], and, after valid values, nothing for 3 s: no green arrow.
  6. The stream sends [1, 0, -1]: no green arrow.
  7. Every green arrow comes after the blue arrows in the drawing; it is drawn green with 2 pt, and the computed contrast ratio of the green is at least 3:1 against the background of the frame Telemetry and at least 5:1 against the black of the axes.
  8. Direction 90 and clockwise entered, the stream sends [-50, 100, -50]: the text alternative reads Movement Preview: Translation in direction 90°, Rotation clockwise, measured Translation in direction 90° at 100 %.
  9. With the Superordinate Controller on the robot, lifted with free wheels: during a Translation in direction 90 at 50 %, the green arrow points right with half the radius; during a Rotation clockwise at 50 %, the green arc runs clockwise over about 22° (manual test test/manual/robot.md).

Decisions

  1. The Web App derives the Measured Movement; the Superordinate Controller does not. The Remote Control API stays free of values that follow from others, and each consumer may derive what it needs. Knowledge of the Drive, the scaling to percent and the sign of each motor, stays with the Superordinate Controller. Consequence: the geometry of the robot stands in the Kinematics of the Superordinate Controller and in the Derivation here; a change of the robot changes both, verified by the same test vectors.
  2. The length of a green arrow shows its speed. The blue arrows show directions only; the green ones show how far the motors follow, so that a lagging motor shows as a short arrow. Consequence: at 100 %, a green arrow is as long as its blue one.