Skip to content

Capability 003: Remote Control API - Rotate

Status: Accepted

Context

With the Remote Control API of capability 002, the Robot Operator translates the robot in any direction and stops it. Rotating the robot around its center completes a simple navigation model: the Robot Operator turns the robot towards a target and drives it there.

A Remote Drive Command for a rotation follows the principle Safe when silent in the same way as one for a translation: the Web App repeats it, the Superordinate Controller does not.

References

Details

Endpoints

Method Path Request body Success
POST /v1/rotation-commands Remote Drive Command for a rotation 202 Accepted

Remote Drive Command for a Rotation

Field Type Range Meaning
speed integer -100–100 Speed of the rotation in percent of the maximum speed: positive clockwise, negative counterclockwise, seen from above

Kinematics

For a rotation at speed \(s\), every motor \(i\) gets the same target speed

\[v_i = -10 \cdot s\]

The sign follows from the kinematics of capability 002: a positive target speed on every motor rotates the robot counterclockwise. \(|v_i| \le 1000\), so every result lies in the range of DriveCommand.

speed Motor1TargetSpeed Motor2TargetSpeed Motor3TargetSpeed
100 -1000 -1000 -1000
-100 1000 1000 1000
20 -200 -200 -200
-20 200 200 200
0 0 0 0

Functional Requirements

  1. The Robot Operator sends a Remote Drive Command for a rotation. The Superordinate Controller computes the Drive Command from it as given under Kinematics and sends it at once. It does not repeat it.
  2. The Remote Drive Command Timeout, the replacement by a newer Remote Drive Command, and the Stop Command apply as in capability 002, Functional Requirements 2 and 3. A rotation and a translation replace each other.

Non-Functional Requirements

  1. Non-Functional Requirements 1 to 3 of capability 002 apply to a Remote Drive Command for a rotation as well.

Technical Requirements

None.

Error Handling

  1. The error handling of capability 002 applies to a Remote Drive Command for a rotation as well.

Out of Scope

  • Combining translation and rotation in one command
  • Rotating around a point other than the center of the robot
  • Telemetry of the robot

Acceptance Criteria

All criteria except the last run against a pseudo-terminal.

  1. A Remote Drive Command for a rotation of each row of the table under Kinematics: answered with 202 Accepted; the CAN Frame Line of the Drive Command with the target speeds of that row arrives as required by Non-Functional Requirement 1 of capability 002. Example: {"speed": 100} yields Motor1TargetSpeed -1000, Motor2TargetSpeed -1000, Motor3TargetSpeed -1000.
  2. One Remote Drive Command for a rotation, then none: no further CAN Frame Line with its target speeds, and the Neutral Drive Command arrives as required by Non-Functional Requirement 2 of capability 002, followed by the own cycle as in capability 001.
  3. Remote Drive Commands alternating between a rotation and a translation every 250 ms for 3 s: each Drive Command follows the last request received, no Neutral Drive Command in between.
  4. A Stop Command while a Remote Drive Command for a rotation is active: answered with 202 Accepted; the Neutral Drive Command arrives as required by Non-Functional Requirement 1 of capability 002.
  5. Invalid Remote Drive Commands for a rotation are answered with 400 Bad Request and an application/problem+json body, and yield no Drive Command of their own:
Request body Reason
{"speed": 100 malformed JSON
{} missing field
{"speed": 100, "direction": 0} unknown field
{"speed": "fast"} wrong type
{"speed": 101} value out of range
{"speed": -101} value out of range
  1. The pseudo-terminal is closed: a Remote Drive Command for a rotation is answered with 503 Service Unavailable and an application/problem+json body that names no device path.
  2. On the robot, first lifted with free wheels and then on the floor: speed 20 rotates the robot clockwise, speed -20 counterclockwise, seen from above; it stops within 1 s after the Web App stops sending and at once on a Stop Command (manual test test/manual/robot.md).

Decisions

  1. A rotation has an endpoint of its own instead of a field that selects the movement in /v1/drive-commands. Each request keeps a strict schema of its own, and the request of capability 002 stays as it is. Consequence: combining translation and rotation in one command needs a request of its own.
  2. A positive speed rotates clockwise, seen from above. It matches direction of capability 002, whose angles grow clockwise. Consequence: a positive speed yields negative target speeds; the manual test on the robot verifies the sign.