# juxi-technology/amazinghand architecture

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

- Interactive diagram: https://gitdiagram.com/juxi-technology/amazinghand
- Repository: https://github.com/juxi-technology/amazinghand

## Overview

AmazingHand is a collection of robotic-hand designs and control tools for SCS0009 bus servos and an ESP32-S3 PWM variant. Users issue poses or live tracking input through desktop or browser controls; those controls translate commands into servo motion. Separate tools support direct servo debugging and calibration, while the PWM firmware receives serial commands, dispatches gestures, and drives eight PWM channels. The graph preserves documented capabilities even where implementation files were not sampled; those unsampled subsystem links are omitted or marked unverified.

Main entry points: [`SCS0009_ServoController/src/gui/ft_debugger.py`](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/gui/ft_debugger.py) (Servo debugger), [`Amazinghand-web/server.py`](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web/server.py) (Web service), [`AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c`](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c) (Firmware tasks), [`AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_servo/hand_servo.c`](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_servo/hand_servo.c) (PWM servo driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser control"]
  node_webserver["Web service<br/>[server.py]"]
  node_webui["Browser interface<br/>[app.js]"]
  node_webtracking["Camera tracking<br/>[tracking.js]"]
  node_webtransport["Web transport<br/>[ws.js]"]
  node_webio["Servo I/O<br/>[io.js]"]
  node_webpwm["PWM transport<br/>[pwm.js]"]
end

subgraph group_desktop["Desktop control"]
  node_desktopgui["Control GUI"]
  node_desktoplogic["Pose and servo logic<br/>[hand_logic.py]"]
  node_desktopcli["Control CLI"]
end

subgraph group_pwm["PWM firmware"]
  node_pwmgui["PWM desktop GUI<br/>[hand_gui.py]"]
  node_tracking["PWM hand tracking<br/>[hand_tracking.py]"]
  node_firmware["Firmware tasks<br/>[main.c]"]
  node_protocol["Serial protocol<br/>[hand_protocol.c]"]
  node_gestures["Gesture dispatch<br/>[hand_gestures.c]"]
  node_pwmservo["PWM servo driver<br/>[hand_servo.c]"]
end

subgraph group_servo["Servo tooling"]
  node_debugger["Servo debugger<br/>[ft_debugger.py]"]
  node_factory["Factory calibration"]
  node_sdk["Servo protocol SDK"]
  node_port["Serial port handler<br/>[port_handler.py]"]
  node_scscl["Servo command layer<br/>[scscl.py]"]
  node_registers["Register definitions<br/>[scservo_def.py]"]
  node_xdat["XDAT parameters<br/>[xdat_utils.py]"]
  node_portutils["Port utilities<br/>[port_utils.py]"]
  node_i18n["Translations<br/>[i18n.py]"]
  node_translationdata["Translation tables<br/>[factory.py]"]
end

subgraph group_examples["Examples and demos"]
  node_originalexamples["Python hand examples"]
end

node_user(("Hand operator"))
node_hand["Robotic hand"]

node_user -->|"controls"| node_webui
node_webui -.->|"sends commands"| node_webserver
node_webserver -->|"serves interface"| node_webio
node_webserver -->|"receives WebSocket"| node_webtransport
node_webtracking -.->|"provides tracking"| node_webui
node_webserver -->|"drives servos"| node_hand
node_user -->|"controls"| node_desktopgui
node_desktopgui -->|"uses logic"| node_desktoplogic
node_desktopcli -->|"uses logic"| node_desktoplogic
node_desktopgui -.->|"controls servos"| node_hand
node_desktopcli -.->|"controls servos"| node_hand
node_user -->|"controls"| node_pwmgui
node_pwmgui -->|"uses tracking"| node_tracking
node_pwmgui -.->|"sends serial commands"| node_firmware
node_tracking -.->|"guides motion"| node_hand
node_firmware -->|"parses bytes"| node_protocol
node_firmware -->|"initializes driver"| node_pwmservo
node_firmware -->|"dispatches commands"| node_gestures
node_protocol -->|"dispatches gestures"| node_gestures
node_protocol -->|"sets servo state"| node_pwmservo
node_gestures -->|"moves fingers"| node_pwmservo
node_pwmservo -->|"drives PWM channels"| node_hand
node_user -->|"debugs servos"| node_debugger
node_debugger -->|"issues servo commands"| node_scscl
node_debugger -->|"opens serial port"| node_port
node_debugger -->|"loads parameters"| node_xdat
node_debugger -->|"uses port utilities"| node_portutils
node_debugger -->|"translates labels"| node_i18n
node_factory -->|"reuses debugger"| node_debugger
node_sdk -.->|"reads and writes"| node_port
node_scscl -->|"uses packet protocol"| node_sdk
node_sdk -->|"uses definitions"| node_registers
node_scscl -->|"uses definitions"| node_registers
node_i18n -.->|"loads translations"| node_translationdata
node_user -->|"runs demos"| node_originalexamples

click node_webserver "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web/server.py"
click node_webui "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/app.js"
click node_webtracking "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/tracking.js"
click node_webtransport "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/ws.js"
click node_webio "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/io.js"
click node_webpwm "https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/pwm.js"
click node_desktopgui "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/amazing_hand_gui.py"
click node_desktoplogic "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/hand_logic.py"
click node_desktopcli "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/amazing_hand_cmd.py"
click node_pwmgui "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/tools/hand_gui.py"
click node_tracking "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/tools/hand_tracking.py"
click node_firmware "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c"
click node_protocol "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_protocol/hand_protocol.c"
click node_gestures "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_gestures/hand_gestures.c"
click node_pwmservo "https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_servo/hand_servo.c"
click node_debugger "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/gui/ft_debugger.py"
click node_factory "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/gui/factory_calibration_tool.py"
click node_sdk "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/protocol_packet_handler.py"
click node_port "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/port_handler.py"
click node_scscl "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/scscl.py"
click node_registers "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/scservo_def.py"
click node_xdat "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/xdat_utils.py"
click node_portutils "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/port_utils.py"
click node_i18n "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/i18n.py"
click node_translationdata "https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/i18n_translations/factory.py"
click node_originalexamples "https://github.com/juxi-technology/amazinghand/tree/main/AmazingHand-main/PythonExample"

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_webserver,node_webui,node_webtracking,node_webtransport,node_webio,node_webpwm toneBlue
class node_desktopgui,node_desktoplogic,node_desktopcli toneAmber
class node_pwmgui,node_tracking,node_firmware,node_protocol,node_gestures,node_pwmservo toneMint
class node_debugger,node_factory,node_sdk,node_port,node_scscl,node_registers,node_xdat,node_portutils,node_i18n,node_translationdata toneRose
class node_originalexamples,node_user,node_hand toneIndigo
```

## Components

### Browser control

- [Web service](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web/server.py): `Amazinghand-web/server.py`
- [Browser interface](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/app.js): `Amazinghand-web-io/app.js`
- [Camera tracking](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/tracking.js): `Amazinghand-web-io/tracking.js`
- [Web transport](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/ws.js): `Amazinghand-web-io/ws.js`
- [Servo I/O](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/io.js): `Amazinghand-web-io/io.js`
- [PWM transport](https://github.com/juxi-technology/amazinghand/blob/main/Amazinghand-web-io/pwm.js): `Amazinghand-web-io/pwm.js`

### Desktop control

- [Control GUI](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/amazing_hand_gui.py): `AmazingHandControl/amazing_hand_gui.py`
- [Pose and servo logic](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/hand_logic.py): `AmazingHandControl/hand_logic.py`
- [Control CLI](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHandControl/amazing_hand_cmd.py): `AmazingHandControl/amazing_hand_cmd.py`

### PWM firmware

- [PWM desktop GUI](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/tools/hand_gui.py): `AmazingHand-PWM/tools/hand_gui.py`
- [PWM hand tracking](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/tools/hand_tracking.py): `AmazingHand-PWM/tools/hand_tracking.py`
- [Firmware tasks](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c): `AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c`
- [Serial protocol](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_protocol/hand_protocol.c): `AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_protocol/hand_protocol.c`
- [Gesture dispatch](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_gestures/hand_gestures.c): `AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_gestures/hand_gestures.c`
- [PWM servo driver](https://github.com/juxi-technology/amazinghand/blob/main/AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_servo/hand_servo.c): `AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_servo/hand_servo.c`

### Servo tooling

- [Servo debugger](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/gui/ft_debugger.py): `SCS0009_ServoController/src/gui/ft_debugger.py`
- [Factory calibration](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/gui/factory_calibration_tool.py): `SCS0009_ServoController/src/gui/factory_calibration_tool.py`
- [Servo protocol SDK](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/protocol_packet_handler.py): `SCS0009_ServoController/scservo_sdk/protocol_packet_handler.py`
- [Serial port handler](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/port_handler.py): `SCS0009_ServoController/scservo_sdk/port_handler.py`
- [Servo command layer](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/scscl.py): `SCS0009_ServoController/scservo_sdk/scscl.py`
- [Register definitions](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/scservo_sdk/scservo_def.py): `SCS0009_ServoController/scservo_sdk/scservo_def.py`
- [XDAT parameters](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/xdat_utils.py): `SCS0009_ServoController/src/xdat_utils.py`
- [Port utilities](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/port_utils.py): `SCS0009_ServoController/src/port_utils.py`
- [Translations](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/i18n.py): `SCS0009_ServoController/src/i18n.py`
- [Translation tables](https://github.com/juxi-technology/amazinghand/blob/main/SCS0009_ServoController/src/i18n_translations/factory.py): `SCS0009_ServoController/src/i18n_translations/factory.py`

### Examples and demos

- [Python hand examples](https://github.com/juxi-technology/amazinghand/tree/main/AmazingHand-main/PythonExample): `AmazingHand-main/PythonExample`

### Other components

- **Hand operator**
- **Robotic hand**

## Connections

- Hand operator → Browser interface: controls (evidence: `README.md`)
- Browser interface → Web service: sends commands (evidence: `Amazinghand-web/server.py`)
- Web service → Servo I/O: serves interface (evidence: `Amazinghand-web/server.py`)
- Web service → Web transport: receives WebSocket (evidence: `Amazinghand-web/server.py`)
- Camera tracking → Browser interface: provides tracking
- Web service → Robotic hand: drives servos (evidence: `Amazinghand-web/server.py`)
- Hand operator → Control GUI: controls (evidence: `README.md`)
- Control GUI → Pose and servo logic: uses logic (evidence: `AmazingHandControl/amazing_hand_gui.py`)
- Control CLI → Pose and servo logic: uses logic (evidence: `AmazingHandControl/amazing_hand_cmd.py`)
- Control GUI → Robotic hand: controls servos
- Control CLI → Robotic hand: controls servos
- Hand operator → PWM desktop GUI: controls (evidence: `README.md`)
- PWM desktop GUI → PWM hand tracking: uses tracking (evidence: `AmazingHand-PWM/tools/hand_gui.py`)
- PWM desktop GUI → Firmware tasks: sends serial commands
- PWM hand tracking → Robotic hand: guides motion
- Firmware tasks → Serial protocol: parses bytes (evidence: `AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c`)
- Firmware tasks → PWM servo driver: initializes driver (evidence: `AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c`)
- Firmware tasks → Gesture dispatch: dispatches commands (evidence: `AmazingHand-PWM/firmware/AmazingHand_Serial/main/main.c`)
- Serial protocol → Gesture dispatch: dispatches gestures
- Serial protocol → PWM servo driver: sets servo state (evidence: `AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_protocol/hand_protocol.c`)
- Gesture dispatch → PWM servo driver: moves fingers (evidence: `AmazingHand-PWM/firmware/AmazingHand_Serial/components/hand_gestures/hand_gestures.c`)
- PWM servo driver → Robotic hand: drives PWM channels (evidence: `README.md`)
- Hand operator → Servo debugger: debugs servos (evidence: `README.md`)
- Servo debugger → Servo command layer: issues servo commands (evidence: `SCS0009_ServoController/src/gui/ft_debugger.py`)
- Servo debugger → Serial port handler: opens serial port (evidence: `SCS0009_ServoController/src/gui/ft_debugger.py`)
- Servo debugger → XDAT parameters: loads parameters (evidence: `SCS0009_ServoController/src/gui/ft_debugger.py`)
- Servo debugger → Port utilities: uses port utilities (evidence: `SCS0009_ServoController/src/gui/ft_debugger.py`)
- Servo debugger → Translations: translates labels (evidence: `SCS0009_ServoController/src/gui/ft_debugger.py`)
- Factory calibration → Servo debugger: reuses debugger (evidence: `SCS0009_ServoController/src/gui/factory_calibration_tool.py`)
- Servo protocol SDK → Serial port handler: reads and writes
- Servo command layer → Servo protocol SDK: uses packet protocol (evidence: `SCS0009_ServoController/scservo_sdk/scscl.py`)
- Servo protocol SDK → Register definitions: uses definitions (evidence: `SCS0009_ServoController/scservo_sdk/protocol_packet_handler.py`)
- Servo command layer → Register definitions: uses definitions (evidence: `SCS0009_ServoController/scservo_sdk/scscl.py`)
- Translations → Translation tables: loads translations
- Hand operator → Python hand examples: runs demos (evidence: `README.md`)
