cmvr-es/docs/teleoperation/ume_cmvr_architecture.md

# UME to CMVR-ES Teleoperation Architecture

## Scope

This document freezes the first implementation stage of the wired,
cross-machine teleoperation path:

- both edge computers run `cmvr_es`;
- the UME computer owns the Damiao SocketCAN-FD interfaces;
- `UmeRobotArm` is a `RobotArm` backend;
- the UME computer performs the leader/follower model calculations;
- the robot computer validates and executes joint-servo references;
- the transport is a versioned gRPC bidirectional stream;
- the original UME algorithm is migrated before any SEW fusion work.

SEW fusion, passivity research, paper experiments, and physical human testing
are deliberately outside this implementation stage.

## Target process and ownership boundary

```text
UME cmvr_es
  UmeRobotArm
    Damiao SocketCAN-FD
    UmeHapticLoop
    local safety guard
       |
       +-- UmeLegacyAlgorithm
       |
  UmeTeleopTask
    GrpcArmTeleopClient
                  |
                  | wired Ethernet / gRPC bidi stream
                  v
Robot cmvr_es
  ArmTeleopService
    control lease
    latest-only command slot
    watchdog
    safe servo executor
       |
       v
    RobotArm
```

The UME high-frequency loop never performs a network RPC. Network workers and
hardware loops exchange only bounded latest-state snapshots.

## Implemented boundary in this revision

This revision establishes the device, algorithm-library, session-transport and
robot-backend boundaries, but it intentionally does not connect them into a
physical end-to-end controller:

- `UmeRobotArm` owns one eight-axis Damiao bus and a bounded local torque loop.
  It starts passive, requires an explicit fresh torque command before
  `torqueOn`, and latches watchdog/transport faults.
- a successful SocketCAN send means that the complete frame batch was accepted
  by the local kernel before its deadline. The current MIT transport has no
  reviewed Disable acknowledgement, so software must not describe that result
  as actuator-confirmed torque-off.
- the original UME dynamics, friction, stiction and haptic projection code is a
  standalone tested library under `algorithms/controllers/ume_legacy`;
- `UmeTeleopTask` owns reconnect, heartbeat, sequence and a capacity-one
  outbound mailbox. Its `submitSetpoint()` input is deliberately an algorithm
  boundary; no production source calls it yet;
- the server-side `RobotArmTeleopBackend` is implemented and tested behind an
  explicit capability gate. The current `MotorRobotArm` remains unavailable
  because its `servoJ` path is sequential per joint rather than an accepted
  atomic/timed group primitive;
- server state is currently returned with session events. The configured
  requested state rate is not yet an independent periodic publisher;
- follower effort is validated and transported when a backend declares a
  verified source, but it is not yet consumed by a UME haptic coordinator.

Accordingly, this code is an M0-M9 fail-closed framework and original-algorithm
migration, not a claim of runnable force-feedback teleoperation. The next
integration step must add a concrete UME-to-follower retargeting producer,
connect verified follower effort to the local haptic coordinator, and retain
the high-frequency/network-thread separation above.

## Safety invariants

1. Opening a CAN interface never enables a motor.
2. Clearing a fault never arms a motor.
3. A reconnect creates a new session and never restores active motion.
4. Cross-machine `steady_clock` values are diagnostic only. A receiver derives
   command expiry from its local receive time plus `valid_for_us`.
5. Commands are strictly increasing by sequence within one session.
6. Queues on the cyclic path are latest-only and bounded.
7. Invalid or stale follower effort ramps haptic feedback to zero.
8. Model, joint order, units, and calibration hashes must match before motion.
9. New physical hardware configurations remain disabled by default.
10. A software stop does not replace an independent physical emergency stop.
11. UME hardware enable also requires an explicit firmware-reviewed feedback
    status whitelist and raw temperature thresholds; empty values never mean
    "accept all".
12. UME shutdown timing is diagnosed against a configured budget, but physical
    torque removal still requires an independent emergency-stop path until a
    reviewed actuator Disable acknowledgement exists.

## Initial rate boundary

- UME local hardware/haptic loop: configurable, initially 800 Hz to match the
  legacy UME setup.
- network command rate: configurable independently of the local loop.
- robot servo rate: selected from the robot backend capability and never
  inferred from the network rate.

No hard real-time or stability claim is made until the target computers and
physical devices have completed staged validation.