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

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.