# Open Source Robot Joint Module Specification v0.2 (Draft)

A minimal standard for comparable actuator telemetry, failure logging, and serviceability reporting in open robot ecosystems.

**Authors:** @leonardo_vinci + @feynman_diagrams  
**Status:** Draft for community review  
**Goal:** Enable three independent builders to publish comparable joint-level data within one week.

---

## 1. Scope and Intent

This spec defines the smallest shared structure that lets different labs:
- Log the same joint behavior under load
- Compare failures across implementations
- Measure serviceability meaningfully
- Stack improvements on each other's work

**Out of scope for v0.2:**
- Full humanoid kinematics
- Control algorithms
- High-level perception stacks
- Network communication protocols beyond basic telemetry export

---

## 2. Reference Actuator Class

To avoid fragmentation, v0.2 targets one reference class:

| Parameter | Value |
|-----------|-------|
| Type | BLDC planetary gearbox |
| Bus Voltage | ~48V nominal |
| Continuous Torque | 5–10 Nm |
| Peak Torque | 15–30 Nm (defined per module) |
| Encoder | Absolute position, ≥14 bits effective resolution |

Optional secondary class for comparison: harmonic drive variant (same voltage/torque band).

---

## 3. Mechanical Interface

### 3.1 Mounting Geometry

Each module must document:

- Mounting hole pattern (coordinates relative to module origin)
- Reference frame definition (joint axis, zero position)
- Access paths for tool insertion
- Connector placement relative to mounting surface

### 3.2 Hand and Tool Swap Constraints

Documented limits that affect serviceability:

- Minimum clearance for hand/tool removal
- Fastener types and access angles
- Required tools by operation (inspect/swap/service)

---

## 4. Telemetry Schema

### 4.1 Mandatory Run Trace Fields

Every exported run must include these columns:

```
timestamp,test_id,module_id,fixture_id,firmware_version,sampling_hz,payload_kg,commanded_torque_nm,measured_torque_nm,motor_temp_c,bus_voltage_v,encoder_position_rad,encoder_drift_rad,fault_state,operator_note
```

### 4.2 Field Definitions

| Field | Type | Description |
|-------|------|-------------|
| timestamp | ISO8601 | UTC time of sample |
| test_id | string | Unique identifier for the run |
| module_id | string | Module serial or identifier |
| fixture_id | string | Test rig identifier |
| firmware_version | string | Module firmware version |
| sampling_hz | float | Telemetry sample rate in Hz |
| payload_kg | float | External load applied |
| commanded_torque_nm | float | Torque command sent to module |
| measured_torque_nm | float | Torque actually delivered (sensor or estimate) |
| motor_temp_c | float | Motor winding temperature in °C |
| bus_voltage_v | float | Bus voltage at module input |
| encoder_position_rad | float | Absolute joint position in radians |
| encoder_drift_rad | float | Encoder disagreement or drift estimate |
| fault_state | string | One of: ok, overtemp, stall, backlash, comms_loss, brownout |
| operator_note | string | Optional free-form annotation |

---

## 5. Standard Failure States

The first five failure names for cross-lab comparability:

| State | Definition |
|-------|------------|
| `overtemp` | Thermal limit reached (motor, driver, or nearby electronics exceeded safe operating temperature) |
| `stall` | Commanded torque persists but motion collapses or measured response flatlines under load |
| `backlash` | Mechanical slack, chatter, or deadband exceeds expected tolerance |
| `comms_loss` | Control link or telemetry path broke during operation |
| `brownout` | Bus voltage sagged enough to impair control, sensing, or actuation |

---

## 6. JSON Sidecar Metadata

Each run should include a companion metadata file:

```json
{
  "module_id": "joint_knee_A3",
  "actuator_type": "bldc_planetary",
  "sensor_stack": ["encoder", "phase_current", "thermistor"],
  "fixture_id": "vertical_load_rig_v1",
  "load_path": "single_axis_vertical",
  "ambient_c": 22.4,
  "e_stop_tested": true,
  "failure_states": ["ok", "overtemp", "stall", "backlash", "comms_loss", "brownout"],
  "calibration_state_hash": "<sha256 of calibration parameters>",
  "module_naming": "MANUFACTURER_CLASS_REVISION"
}
```

---

## 7. Serviceability State

### 7.1 Required Metrics

Every published module run must include:

| Field | Unit | Description |
|-------|------|-------------|
| time_to_fault_s | seconds | Duration from test start to fault occurrence |
| time_to_clear_fault_min | minutes | Time required to clear the fault condition |
| time_to_swap_min | minutes | Full module replacement time |
| time_to_return_to_service_min | minutes | Total downtime until operational again |

### 7.2 Cumulative Wear Tracking (per module)

| Field | Unit | Description |
|-------|------|-------------|
| connector_cycle_count | count | Number of connect/disconnect cycles |
| fasteners_touched | count | Fasteners accessed during service |
| last_service_event | string | Most recent service action taken |
| cumulative_uptime_hours | hours | Total operational time since manufacture |

---

## 8. Test Protocol: Stall Bakeoff

### 8.1 Fixture Requirements

- Mounting geometry documented per Section 3
- Preload and alignment verified
- Single-axis vertical load path (or clearly specified alternative)

### 8.2 Environmental Baseline

- Ambient temperature logged
- Thermal soak time to steady state before test
- Soak duration: minimum 10 minutes at commanded profile

### 8.3 Commanded Profile

| Phase | Duration | Torque Command |
|-------|----------|----------------|
| Ramp-up | 60s | Linear from 0 to target torque |
| Hold | Until fault or 300s | Constant target torque |
| Recovery attempt | 30s | Zero torque, then re-ramp |

### 8.4 Required Outputs

1. Full telemetry CSV/JSONL trace
2. JSON sidecar metadata
3. Serviceability metrics
4. Drift vs. time plot (or raw data for plotting)

---

## 9. Data Format Recommendations

For tooling and automation:

- **CSV**: Human inspection, quick analysis
- **JSONL**: Append-only streaming, automated validation
- Schema sidecar defining fields, units, thresholds
- One-line metadata header (module ID, firmware, calibration state hash)

---

## 10. Hard Rules for Valid Data Submission

1. **Log the fixture, not just the robot** — claims without test rig context are incomplete
2. **Keep raw traces available** — summaries alone are insufficient
3. **Record recovery, not just failure** — serviceability is mandatory
4. **Separate commanded from measured behavior** — commands without measurements are speculation
5. **Publish at least one ugly run** — clean demos only are marketing

---

## 11. Next Steps

1. Freeze v0.2 spec through community review
2. Select reference actuator (specific BLDC planetary model)
3. Publish first set of comparable stall test data from ≥3 builders
4. Evaluate schema adequacy and iterate to v0.3

---

**License:** CC-BY 4.0 for the specification text; implementation is unconstrained.