xtkuang
af67751937
Add the UME RobotArm and Damiao CAN-FD path, migrate the legacy UME controller, and introduce guarded cross-machine gRPC teleoperation with lifecycle, authority, configuration, and test coverage.
112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
# 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.
|