Capability 006: Translation

Status: Accepted

Context

The Robot Operator moves the robot in a direction, without turning it, from the Web App: a Translation. The Superordinate Controller keeps a Remote Drive Command active only for the Remote Drive Command Timeout; following the principle Safe when silent of the mission statement, the robot stops when the Web App falls silent. The Web App therefore repeats the command for the duration the Robot Operator asks for.

References

• Remote Drive Command (POST /v1/drive-commands) and Remote Drive Command Timeout: remote_control_api.json, capability 002 of the Superordinate Controller
• Stop, the Event Log, the base URL, and the messages for failures: capability 003
• Command Pane: capability 002
• Target picture: target_picture.md
• Accessibility: directives in user_experience.md

Details

Translation Form

The Command Pane holds, above the box Safe Mode of capability 003, a box of its own with the heading Translation, three input fields, and the button Translate:

Label	Values	Default	Becomes
Speed (%)	Whole number, 0 to 100	20	speed
Direction (deg)	Whole number, 0 to 359; 0 forward, 90 right, 180 backward, 270 left, seen from above	0	direction
Duration (s)	Whole number, 1 to 10	2	Duration of the Translation

A field with a value outside its range shows below it, e.g., Speed must be a whole number from 0 to 100.

Repetition

A click on Translate sends a Remote Drive Command with the values of the fields at once, and again every Repetition Interval, until the duration has elapsed: a duration of 2 s yields 8 commands, at 0 ms, 250 ms, and so on up to 1,750 ms. The robot stops by itself one Remote Drive Command Timeout after the last one.

Name	Value
Repetition Interval	250 ms, half the Remote Drive Command Timeout
Response timeout	2 s, as for capability 003

Event Log

Event	Severity	Message
Translate clicked with valid values	INFO	Translation started: direction <direction> deg, speed <speed> %, for <duration> s.
The duration elapsed	INFO	Translation ended.
A command answered 503	ERROR	Translation failed: the robot is unavailable (<detail>). Check the CAN Adapter of the Superordinate Controller.
A command answered any other status	ERROR	Translation failed: <status> <title> (<detail>). Check the log of the Superordinate Controller.
A command without response within 2 s, or no connection	ERROR	Translation failed: the Superordinate Controller at <base URL> does not respond. Check that it runs and allows this origin.

<detail> and <title> are taken as for capability 003. An accepted command adds no entry, so that 4 commands per second do not flood the Event Log.

Functional Requirements

1. A click on Translate with valid values starts a Translation as given under Repetition, and records its start and its end in the Event Log as given under Event Log.
2. A click on Translate during a Translation ends it and starts a new one with the current values.
3. A click on Stop during a Translation ends it at once; no Remote Drive Command of it follows the Stop Command.
4. A click on Translate with a value outside its range sends nothing and shows the message under the field as given under Translation Form.

Non-Functional Requirements

1. Two consecutive Remote Drive Commands of a Translation leave the browser at most 300 ms apart, measured by the request times in the browser over a Translation of 10 s against the mocked Remote Control API.

Technical Requirements

None.

Error Handling

1. The first failed command ends the Translation and is an ERROR entry as given under Event Log; the Web App sends no further command of it and never retries on its own.
2. A message never repeats the request body or internals of the Web App.

Out of Scope

• Rotation: capability 007
• Showing the remaining time of a Translation
• Disabling Translate while a Health Indicator is red
• Steering with keyboard or joystick, or changing the values of a running Translation
• Bounding the requests outstanding while the Superordinate Controller does not respond

Acceptance Criteria

All criteria except the last run against a mocked Remote Control API, with a mocked clock where time matters.

1. Page loaded: the box Translation stands above the box Safe Mode, and its fields show 20, 0, and 2.
2. Speed 20, direction 90, duration 2, Translate clicked, the API answers 202: 8 POST /v1/drive-commands with {"direction": 90, "speed": 20} are sent within 2 s, none after; the Event Log shows INFO Translation started: direction 90 deg, speed 20 %, for 2 s., then INFO Translation ended. on top.
3. Duration 2, Translate clicked, Stop clicked 1 s later: the Stop Command is sent, and no Remote Drive Command after it.
4. Direction 0, duration 2, Translate clicked; 1 s later direction 180, Translate clicked again: from then on, every command carries direction 180, for 2 s from the second click.
5. Translate clicked, the API answers the third command with 503: no fourth command is sent, and the newest entry is ERROR with the message for 503 under Event Log.
6. Translate clicked, the API does not answer within 2 s: the newest entry is ERROR with the message for no response, naming the base URL, and no command follows that entry.
7. Translate clicked with speed 101, -1, 2.5, or empty, direction 360, or duration 0 or 11: no command is sent, and the field shows its message.
8. Translate clicked with duration 10: no two consecutive commands leave the browser more than 300 ms apart.
9. On the lifted robot, at speed 20, for 2 s each, directions 0, 90, 180, and 270: the wheels turn as for driving forward, right, backward, and left, and stop within 1 s after the duration (manual test test/manual/robot.md).

Decisions

1. The Web App repeats the command, not the Superordinate Controller. The Remote Drive Command Timeout stops the robot as soon as the Web App, the browser, or the network falls silent. Consequence: a Translation lasts only while the page stays open and connected.
2. A Translation lasts at most 10 s. A mistyped duration must not let the robot run away while the Robot Operator looks elsewhere. Consequence: a longer distance takes several clicks.
3. The default speed is 20 %. It is the speed at which the manual tests drive on the floor; a higher speed is a deliberate choice. Consequence: the first click after loading moves the robot slowly.
4. The first failure ends the Translation. As for the Stop Command, the Robot Operator decides; without commands the robot stops anyway. Consequence: a single lost request ends the Translation early.