# longh-do/teleop_openarm_system architecture

> Architecture diagram of the GitHub repository longh-do/teleop_openarm_system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/longh-do/teleop_openarm_system
- Repository: https://github.com/longh-do/teleop_openarm_system

## Overview

This repository is a Raspberry Pi–hosted teleoperation system for driving two OpenArm arms from a Meta Quest browser. The primary workflow is controller input in the headset, pose and control processing in the teleoperation server, inverse kinematics, then joint targets over localhost UDP to the motor loop and CAN-connected motors. Supporting branches cover calibration and gain tuning, plus simulation and model inspection. The graph uses README statements and shown source/index references; unsampled page and subsystem details are represented only where documented, so some internal links are omitted.

Main entry points: [`pi/motor_loop.py`](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/motor_loop.py) (Motor Loop), [`pi/kinematics.py`](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/kinematics.py) (Kinematics), [`pi/teleop_server.py`](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/teleop_server.py) (Teleop Server), [`pi/damiao.py`](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/damiao.py) (DAMIAO Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_headset["Headset Interface"]
  node_quest_page["Quest Page<br/>[index.html]"]
end

subgraph group_teleop["Teleoperation"]
  node_teleop_server["Teleop Server<br/>[teleop_server.py]"]
  node_arm_brain["Arm Brain<br/>[teleop_server.py]"]
  node_kinematics["Kinematics<br/>[kinematics.py]"]
end

subgraph group_motor["Motor Control"]
  node_motor_loop["Motor Loop<br/>[motor_loop.py]"]
  node_damiao["DAMIAO Protocol<br/>[damiao.py]"]
  node_can_buses["CAN Buses"]
  node_gain_data["Gain Settings<br/>[gains.json]"]
end

subgraph group_calibration["Calibration Tools"]
  node_calibration_data["Calibration Data<br/>[calib.json]"]
  node_find_stops["Find Joint Stops<br/>[find_stops.py]"]
  node_grip_stops["Find Grip Stops<br/>[grip_stops.py]"]
  node_straighten["Straighten Joints<br/>[straighten.py]"]
  node_untwist["Untwist Readout<br/>[untwist.py]"]
  node_ik_move["IK Move Check<br/>[ik_move.py]"]
  node_tune_gains["Tune Gains<br/>[tune_gains.py]"]
  node_model_tools["Model Inspection<br/>[fk_plot.py]"]
end

subgraph group_simulation["Simulation"]
  node_fake_motors["Fake Motors<br/>[fake_motors.py]"]
  node_fake_quest["Fake Quest<br/>[fake_quest.py]"]
end

node_operator(("Operator"))
node_openarm["OpenArm Arms"]

node_operator -->|"uses controls"| node_quest_page
node_quest_page -->|"sends controls"| node_teleop_server
node_teleop_server -->|"dispatches input"| node_arm_brain
node_arm_brain -->|"solves IK"| node_kinematics
node_teleop_server -->|"sends UDP targets"| node_motor_loop
node_motor_loop -->|"uses protocol"| node_damiao
node_motor_loop -->|"transmits frames"| node_can_buses
node_can_buses -->|"drives motors"| node_openarm
node_motor_loop -->|"loads gains"| node_gain_data
node_kinematics -->|"loads calibration"| node_calibration_data
node_find_stops -->|"uses limits"| node_kinematics
node_find_stops -->|"writes stops"| node_calibration_data
node_grip_stops -->|"commands gripper"| node_damiao
node_grip_stops -->|"records stops"| node_calibration_data
node_straighten -->|"uses calibration"| node_kinematics
node_straighten -->|"sends targets"| node_motor_loop
node_untwist -->|"converts angles"| node_kinematics
node_ik_move -->|"plans motion"| node_kinematics
node_ik_move -->|"sends targets"| node_motor_loop
node_tune_gains -->|"starts and tests"| node_motor_loop
node_tune_gains -->|"reads settings"| node_gain_data
node_model_tools -->|"uses model"| node_kinematics
node_fake_motors -->|"emulates protocol"| node_damiao
node_fake_motors -->|"simulates bus"| node_motor_loop

click node_quest_page "https://github.com/longh-do/teleop_openarm_system/blob/main/quest/index.html"
click node_teleop_server "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/teleop_server.py"
click node_arm_brain "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/teleop_server.py"
click node_kinematics "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/kinematics.py"
click node_motor_loop "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/motor_loop.py"
click node_damiao "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/damiao.py"
click node_calibration_data "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/calib.json"
click node_gain_data "https://github.com/longh-do/teleop_openarm_system/blob/main/pi/gains.json"
click node_find_stops "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/find_stops.py"
click node_grip_stops "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/grip_stops.py"
click node_straighten "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/straighten.py"
click node_untwist "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/untwist.py"
click node_ik_move "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/ik_move.py"
click node_tune_gains "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/tune_gains.py"
click node_model_tools "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fk_plot.py"
click node_fake_motors "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fake_motors.py"
click node_fake_quest "https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fake_quest.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_quest_page toneBlue
class node_teleop_server,node_arm_brain,node_kinematics toneAmber
class node_motor_loop,node_damiao,node_can_buses,node_gain_data toneMint
class node_calibration_data,node_find_stops,node_grip_stops,node_straighten,node_untwist,node_ik_move,node_tune_gains,node_model_tools toneRose
class node_fake_motors,node_fake_quest,node_operator,node_openarm toneIndigo
```

## Components

### Headset Interface

- [Quest Page](https://github.com/longh-do/teleop_openarm_system/blob/main/quest/index.html): `quest/index.html`

### Teleoperation

- [Teleop Server](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/teleop_server.py): `pi/teleop_server.py`
- [Arm Brain](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/teleop_server.py): `pi/teleop_server.py`
- [Kinematics](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/kinematics.py): `pi/kinematics.py`

### Motor Control

- [Motor Loop](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/motor_loop.py): `pi/motor_loop.py`
- [DAMIAO Protocol](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/damiao.py): `pi/damiao.py`
- **CAN Buses**
- [Gain Settings](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/gains.json): `pi/gains.json`

### Calibration Tools

- [Calibration Data](https://github.com/longh-do/teleop_openarm_system/blob/main/pi/calib.json): `pi/calib.json`
- [Find Joint Stops](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/find_stops.py): `tools/find_stops.py`
- [Find Grip Stops](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/grip_stops.py): `tools/grip_stops.py`
- [Straighten Joints](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/straighten.py): `tools/straighten.py`
- [Untwist Readout](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/untwist.py): `tools/untwist.py`
- [IK Move Check](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/ik_move.py): `tools/ik_move.py`
- [Tune Gains](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/tune_gains.py): `tools/tune_gains.py`
- [Model Inspection](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fk_plot.py): `tools/fk_plot.py`

### Simulation

- [Fake Motors](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fake_motors.py): `tools/fake_motors.py`
- [Fake Quest](https://github.com/longh-do/teleop_openarm_system/blob/main/tools/fake_quest.py): `tools/fake_quest.py`

### Other components

- **Operator**
- **OpenArm Arms**

## Connections

- Operator → Quest Page: uses controls (evidence: `README.md`)
- Quest Page → Teleop Server: sends controls (evidence: `pi/teleop_server.py`)
- Teleop Server → Arm Brain: dispatches input (evidence: `pi/teleop_server.py`)
- Arm Brain → Kinematics: solves IK (evidence: `pi/teleop_server.py`)
- Teleop Server → Motor Loop: sends UDP targets (evidence: `README.md`)
- Motor Loop → DAMIAO Protocol: uses protocol (evidence: `pi/motor_loop.py`)
- Motor Loop → CAN Buses: transmits frames (evidence: `README.md`)
- CAN Buses → OpenArm Arms: drives motors (evidence: `README.md`)
- Motor Loop → Gain Settings: loads gains (evidence: `README.md`)
- Kinematics → Calibration Data: loads calibration (evidence: `pi/kinematics.py`)
- Find Joint Stops → Kinematics: uses limits (evidence: `tools/find_stops.py`)
- Find Joint Stops → Calibration Data: writes stops (evidence: `README.md`)
- Find Grip Stops → DAMIAO Protocol: commands gripper (evidence: `tools/grip_stops.py`)
- Find Grip Stops → Calibration Data: records stops (evidence: `README.md`)
- Straighten Joints → Kinematics: uses calibration (evidence: `tools/straighten.py`)
- Straighten Joints → Motor Loop: sends targets (evidence: `README.md`)
- Untwist Readout → Kinematics: converts angles (evidence: `tools/untwist.py`)
- IK Move Check → Kinematics: plans motion (evidence: `tools/ik_move.py`)
- IK Move Check → Motor Loop: sends targets (evidence: `tools/ik_move.py`)
- Tune Gains → Motor Loop: starts and tests (evidence: `tools/tune_gains.py`)
- Tune Gains → Gain Settings: reads settings (evidence: `README.md`)
- Model Inspection → Kinematics: uses model (evidence: `tools/fk_plot.py`)
- Fake Motors → DAMIAO Protocol: emulates protocol (evidence: `tools/fake_motors.py`)
- Fake Motors → Motor Loop: simulates bus (evidence: `README.md`)
