# ksdreamer/hand_exoskeleton architecture

> Architecture diagram of the GitHub repository ksdreamer/hand_exoskeleton, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ksdreamer/hand_exoskeleton
- Repository: https://github.com/ksdreamer/hand_exoskeleton

## Overview

##### Project Type and Purpose
- This is an embedded “full‐stack” mechatronics system:
- Mechanical subsystem (linkage + tendon exoskeleton)
- Electronics subsystem (ESP32 microcontroller, SC09 servo bus, power)
- Firmware & web server (Arduino sketch + HTML/JS/CSS UI)
- User devices (PC, phone) interact via Wi-Fi

##### File Structure
- Top‐level folders:
- mechanics/ (CAD parts in SolidWorks, 3D‐print STL & 3MF files)
- program/ServoDriver (Arduino .ino + driver headers + webpage code)
- images/ (documentation)
- Notable files:
- BOARD_DEV.h, STSCTRL.h, CONNECT.h, WEBPAGE.h (modules of firmware)
- ServoDriver.ino (main loop + setup)

##### Architectural Insights from README
- ESP32 runs a built-in web server and SC09 servo bus driver
- Seven SC09 servos arranged as a bus; each servo drives a finger linkage
- Web front end offers on‐device GUI for real-time control over Wi-Fi
- Serial (Type-C) used for firmware upload and debug console

##### Main Components and Their Relationships
a. Mechanical Subsystem
- CAD parts (SolidWorks models) → 3D‐print STL parts → assembly
- Linkage networks for four fingers; tendon lines for thumb
- Mounted directly on servo horns/arms
b. Electronics Subsystem
- Power supply (6–12 V adapter or 2×18650 battery pack) → DC jack on ESP32 dev board
- ESP32 board ↔ SC09 servo bus (SDA/SCL or serial bus lines) → 7 servos
- USB Type-C port for code upload & serial debug
c. Firmware & Software Modules
- ServoDriver.ino (setup(): initialize Wi-Fi AP, servo IDs; loop(): handle web requests & sync writes)
- STSCTRL.h / RGB_CTRL.h (low‐level servo command wrappers)
- .h (“case” actions: openHand(), moveThumb(), etc.)
- WEBPAGE.h (embedded HTML/JS/CSS)
d. User Interaction
- User device connects to ESP32_AP SSID → browser to 192.168.4.1
- HTTP requests / WebSocket (if used) → ESP32 server
- Server processes requests → CONNECT module → STSCTRL → Servo bus → mechanical movement

##### Architectural Patterns & Design Principles
- Layered decomposition: physical (mechanical), electronic, firmware, UI
- Event‐driven (button clicks → case dispatch in CONNECT.h)
- Modular firmware: separate headers for hardware abstraction, control logic, UI
- Single‐board host with built-in web server (no separate PC backend)

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Layer
    subgraph "User Layer"
        UserDevice["User Device\n(PC/Phone)"]:::network
    end

    %% Network Layer
    subgraph "Network Layer"
        AP["Wi-Fi AP\nSSID: ESP32_AP\nIP:192.168.4.1"]:::network
    end

    %% ESP32 Host
    subgraph "ESP32 Host"
        ESP32["ESP32 Dev Module\n(Wi-Fi, USB Type-C, DC Jack)"]:::electronics

        subgraph "Firmware Modules"
            Sketch["ServoDriver.ino"]:::firmware
            BoardDefs["BOARD_DEV.h"]:::firmware
            STSCTRL["STSCTRL.h"]:::firmware
            RGB["RGB_CTRL.h"]:::firmware
            Connect["CONNECT.h"]:::firmware
            Webpage["WEBPAGE.h"]:::firmware
            Preferences["PreferencesConfig.h"]:::firmware
        end

        Serial["Serial Debug\nUSB Type-C"]:::electronics
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        PowerSupply["Power Supply\n6–12V Adapter/2×18650"]:::electronics
        DCJack["DC Jack"]:::electronics
        Bus["SC09 Servo Bus\n(SDA/SCL)"]:::electronics
        Servos["7× SC09 Servos"]:::electronics
        Linkages["Mechanical Linkages"]:::mechanical
        CAD["CAD Models"]:::mechanical
        Printing["3D-print Parts\n(STL/3MF)"]:::mechanical
        Assembly["Linkage Assembly"]:::mechanical
        Doc["Documentation & Diagrams"]:::mechanical
    end

    %% Connections
    UserDevice -->|HTTP requests| AP
    AP -->|Wi-Fi| ESP32
    ESP32 -->|servos commands| Bus
    Bus --> Servos
    Servos -->|mechanical motion| Linkages
    PowerSupply --> DCJack
    DCJack --> ESP32
    DCJack --> Bus
    ESP32 -->|debug console| Serial

    ESP32 --> Sketch
    Sketch -->|includes| BoardDefs
    Sketch -->|calls| STSCTRL
    Sketch -->|calls| RGB
    Sketch -->|dispatches| Connect
    Sketch -->|serves UI| Webpage
    Sketch -->|uses| Preferences

    %% Click Events
    click CAD "https://github.com/ksdreamer/hand_exoskeleton/tree/main/mechanics/CAD_SolidWorks/"
    click Printing "https://github.com/ksdreamer/hand_exoskeleton/tree/main/mechanics/FDM_3DPrinting/"
    click BoardDefs "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/BOARD_DEV.h"
    click Sketch "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/ServoDriver.ino"
    click Webpage "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/WEBPAGE.h"
    click STSCTRL "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/STSCTRL.h"
    click RGB "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/RGB_CTRL.h"
    click Connect "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/CONNECT.h"
    click Preferences "https://github.com/ksdreamer/hand_exoskeleton/blob/main/program/ServoDriver/PreferencesConfig.h"
    click Doc "https://github.com/ksdreamer/hand_exoskeleton/tree/main/images/"

    %% Styles
    classDef firmware fill:#cfe2f3,stroke:#0366d6,color:#0366d6
    classDef electronics fill:#d1e7dd,stroke:#1e7e34,color:#1e7e34
    classDef mechanical fill:#fde2b2,stroke:#d97706,color:#d97706
    classDef network fill:#e2d5f9,stroke:#6b21a8,color:#6b21a8
```
