Capability 007: Rotation

Status: Accepted

Context

The Robot Operator turns the robot around its center from the Web App: a Rotation. As a Translation of capability 006, it repeats its Remote Drive Command for the duration the Robot Operator asks for, so that the robot stops when the Web App falls silent.

References

• Remote Drive Command for a rotation (POST /v1/rotation-commands): remote_control_api.json, capability 003 of the Superordinate Controller
• Repetition, response timeout, and the messages for failures: capability 006
• Stop and the Event Log: capability 003
• Target picture: target_picture.md
• Accessibility: directives in user_experience.md

Details

Rotation Form

The Command Pane holds, between the box Translation and the box Safe Mode, a box of its own with the heading Rotation, two input fields, a selection, and the button Rotate:

Label	Values	Default	Becomes
Speed (%)	Whole number, 0 to 100	20	Magnitude of speed
Direction	clockwise or counterclockwise, seen from above	clockwise	Sign of speed: positive clockwise, negative counterclockwise
Duration (s)	Whole number, 1 to 10	2	Duration of the Rotation

A field with a value outside its range shows its message below it, as for capability 006. A direction other than clockwise or counterclockwise, e.g., from a manipulated page, shows Direction must be clockwise or counterclockwise.

Repetition

A click on Rotate sends POST /v1/rotation-commands with the values of the fields at once, and again every Repetition Interval of capability 006, until the duration has elapsed: a duration of 2 s yields 8 commands.

Event Log

Event	Severity	Message
Rotate clicked with valid values	INFO	Rotation started: <direction>, speed <speed> %, for <duration> s.
The duration elapsed	INFO	Rotation ended.
A command failed	ERROR	The message of capability 006 for the failure, with Rotation failed: in place of Translation failed:

As for a Translation, an accepted command adds no entry.

Functional Requirements

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

Non-Functional Requirements

None; the Rotation shares the repetition of the Translation, whose timing capability 006 measures.

Technical Requirements

None.

Error Handling

1. As for capability 006: the first failed command ends the Rotation and is an ERROR entry; the Web App never retries on its own.
2. The Web App checks every value before it sends a command, even that of the selection. The Superordinate Controller validates every command on its own and answers an invalid one with 400 (its capability 003), so the Remote Control API stays safe without the Web App.

Out of Scope

• A Translation and a Rotation at once, e.g., to drive a curve
• Showing the remaining time of a Rotation
• Steering with keyboard or joystick, or changing the values of a running Rotation

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 Rotation stands between the boxes Translation and Safe Mode, and shows 20, clockwise, and 2.
2. Speed 20, clockwise, duration 2, Rotate clicked, the API answers 202: 8 POST /v1/rotation-commands with {"speed": 20} are sent within 2 s, none after; the Event Log shows INFO Rotation started: clockwise, speed 20 %, for 2 s., then INFO Rotation ended. on top.
3. Speed 30, counterclockwise, Rotate clicked: every command carries {"speed": -30}.
4. Duration 2, Rotate clicked, Stop clicked 1 s later: the Stop Command is sent, and no Remote Drive Command after it.
5. Translate clicked, Rotate clicked 1 s later: no POST /v1/drive-commands follows the click on Rotate; and the other way round, no POST /v1/rotation-commands follows a click on Translate.
6. Rotate clicked, the API answers the third command with 503: no fourth command is sent, and the newest entry is ERROR Rotation failed: the robot is unavailable (<detail>). Check the CAN Adapter of the Superordinate Controller.
7. Rotate clicked with speed 101 or empty, or duration 0 or 11: no command is sent, and the field shows its message.
8. On the lifted robot, at speed 20, for 2 s each, clockwise and counterclockwise: the wheels turn the robot as seen from above, and stop within 1 s after the duration (manual test test/manual/robot.md).

Decisions

1. The direction is a selection, the speed stays positive. The Robot Operator thinks in turning left or right, not in signed numbers; the Web App maps the selection to the sign the Remote Control API expects. Consequence: the speed field takes the same values as for a Translation.
2. A new movement replaces the running one. Two movements at once would send conflicting Remote Drive Commands, each overriding the other at the Superordinate Controller. Consequence: a curve is not possible.