Capability 003: Stop and Event Log

Status: Accepted

Context

The Robot Operator stops the robot from the Web App with a Stop Command of the Remote Control API. The Event Log in the Status Pane shows whether the Superordinate Controller accepted it, and if not, why, so that the Robot Operator can act on it.

The Stop Command is the simplest request of the Remote Control API. It connects the Web App to the Superordinate Controller before the commands that move the robot follow.

References

• Remote Control API and Stop Command: remote_control_api.json, capability 002 of the Superordinate Controller
• Panes: capability 002
• Target picture: target_picture.md
• Error messages: directives in user_experience.md

Details

Stop Button

The Command Pane holds a box of its own with the heading Safe Mode and the button Stop. A click sends a Stop Command.

Event Log

The Status Pane holds the Event Log under the heading Event Log. Each entry shows the local time with seconds, a severity, and a message, e.g. 18:30:05 INFO Stop Command accepted. The newest entry is on top; the Event Log keeps the 2,000 newest entries.

Outcome of the Stop Command	Severity	Message
202 Accepted	INFO	Stop Command accepted.
503 Service Unavailable	ERROR	Stop Command failed: the robot is unavailable (<detail>). Check the CAN Adapter of the Superordinate Controller.
Any other status	ERROR	Stop Command failed: <status> <title> (<detail>). Check the log of the Superordinate Controller.
No response within 2 s, or no connection	ERROR	Stop Command failed: the Superordinate Controller at <base URL> does not respond. Check that it runs and allows this origin.

<detail> and <title> are taken from the problem detail of the response; without one, the parenthesis is left out.

Functional Requirements

1. A click on Stop sends a Stop Command to the Remote Control API.
2. The Event Log records the outcome of every Stop Command as given under Event Log.

Non-Functional Requirements

1. The entry of an outcome appears in the Event Log at most 100 ms after the response, or after 2 s without a response, measured in the browser.

Technical Requirements

1. The base URL of the Remote Control API, i.e. the address of the Superordinate Controller such as http://<pi>:8081, is configurable when the Web App is built, default http://localhost:8081. It is fixed in the build output: the dev server takes it at its start, and a container image holds the base URL it was built with.

Error Handling

1. Every failed Stop Command is an ERROR entry in the Event Log as given under Event Log; the Web App never fails silently and never retries on its own.
2. A message never repeats the request body or internals of the Web App.

Out of Scope

• Commands that move the robot
• Telemetry, and events that the Superordinate Controller reports
• Keeping Stop visible while the page scrolls
• Filtering or saving the Event Log
• Configuring the base URL when the container starts, so that one image serves every Superordinate Controller

Acceptance Criteria

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

1. Stop clicked, the API answers 202: one POST /v1/stop-commands is sent, and the newest entry of the Event Log is INFO with Stop Command accepted.
2. Stop clicked, the API answers 503 with the problem detail The CAN Adapter is unavailable.: the newest entry is ERROR with the message for 503 under Event Log, including that detail.
3. Stop clicked, the API answers 500: the newest entry is ERROR with the message for any other status.
4. Stop clicked, the API does not answer within 2 s: the newest entry is ERROR with the message for no response, naming the base URL.
5. Stop clicked twice, the API answers 202, then 500: the Event Log shows 2 entries, the ERROR on top. The Event Log keeps the 2,000 newest entries; a unit test of the Event Log verifies it, since 2,001 clicks would stretch the end-to-end tests by minutes.
6. Page loaded: Stop stands in a box of its own under the heading Safe Mode.
7. With the Superordinate Controller running on the notebook against /dev/null: Stop yields an INFO entry; with the controller stopped, an ERROR entry for no response (manual test test/manual/remote_control_api.md).

Decisions

1. The button reads Stop, not Emergency halt. The Stop Command travels over the network and is lost with it; it is no emergency stop in the sense of safety engineering. What stops the robot in an emergency is Safe when silent and the power switch. Consequence: the Web App promises no more than the Remote Control API delivers.
2. The Web App does not retry a failed Stop Command. The Robot Operator sees the failure in the Event Log and decides; without commands, the Superordinate Controller stops the robot anyway. Consequence: a lost Stop Command costs at most the Remote Drive Command Timeout.
3. The base URL is fixed when the Web App is built, not when it starts. It is the simplest way: Vite takes it from an environment variable while building. The Robot Operator works with the dev server, which rebuilds at its start anyway. Consequence: a container image reaches only the Superordinate Controller it was built for; reaching another one needs another build, until a later capability configures the base URL when the container starts.