Safe Robot Commands from Flutter: Latency, Acknowledgements, and Guardrails

#architecture #flutter #performance #robotics

Safe Robot Commands from Flutter: Latency, Acknowledgements, and Guardrails

Focus: ROS 2 command gateway and operator controls\
Audience: Flutter, Android, edge AI, and robotics engineers

The problem

A mobile interface is not a real-time safety controller. Network delay,
duplicate taps, stale state, or reconnect behavior can make a command
appear successful when the robot has not executed it.

What this guide covers

This tutorial focuses on practical architecture and performance
engineering for production systems. The central principle is to measure
the complete pipeline, keep latency-sensitive work close to the
hardware, and make failure states visible to the operator.

Reference architecture

Flutter command UI → authenticated command API →
validation/authorization gateway → ROS 2 action/service → robot
controller → acknowledgement/result event → UI. Safety-rated stops and
interlocks remain in the robot's validated control system.

Implementation plan

Use command IDs and idempotency keys so retries do not create duplicate actions.
Represent command lifecycle as submitted, accepted, running, succeeded, rejected, cancelled, or timed out.
Require the robot to validate mode, permissions, workspace, and preconditions; never rely only on UI disabling.
Set deadlines and cancel requests that are no longer relevant.
Display acknowledgement and actual robot state separately from the fact that the user tapped a button.

Example

enum CommandPhase { submitted, accepted, running, succeeded, rejected, timedOut, cancelled }\n\nclass RobotCommandResult {\n  const RobotCommandResult(this.id, this.phase, {this.message});\n  final String id;\n  final CommandPhase phase;\n  final String? message;\n}

The snippets are illustrative starting points, not drop-in integrations.
Match APIs and version requirements to the exact SDK, OS image, hardware
revision, and runtime in your project.

Performance checklist

Measure end-to-end latency, not only one function or model invocation.
Report p50 and p95/p99 latency alongside throughput, memory use, and dropped work.
Bound queues and define what happens when consumers fall behind.
Avoid repeated frame copies and expensive work on Flutter's UI isolate.
Test sustained workloads after the device reaches thermal equilibrium.
Keep UI state, device state, and robot state distinct.
Add timeouts, cancellation, reconnection, and explicit stale-data indicators.
Profile on the actual target hardware using a reproducible build.

Common pitfalls

Never present a network timeout as proof that a robot stopped.
Do not implement emergency-stop functionality as an ordinary best-effort cloud request.
Do not allow stale UI state to bypass server-side authorization.

Hands-on exercise

Inject delayed acknowledgements, duplicate submissions, and a network
drop. Verify that the app never reports success before receiving a valid
result.