# hiwonder-official/hiwonder-servo-sdk architecture

> Architecture diagram of the GitHub repository hiwonder-official/hiwonder-servo-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hiwonder-official/hiwonder-servo-sdk
- Repository: https://github.com/hiwonder-official/hiwonder-servo-sdk

## Overview

hiwonder-servo-sdk provides APIs for controlling HX-30HM bus servos from Python, ESP32, Raspberry Pi, and STM32. The usual workflow is to create a bus, issue motion or configuration commands through a servo API, and exchange packets with servos over half-duplex UART; status reads return telemetry. Separate sync helpers support coordinated multi-servo motion. The graph reflects documented capabilities and sampled implementations; some platform internals were not sampled, so their wiring is shown only where the README or source supports it.

Main entry points: [`python/hiwonder/servo.py`](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py) (Python bus), [`raspberrypi/hiwonder_servo_rpi.py`](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/raspberrypi/hiwonder_servo_rpi.py) (Raspberry Pi bus), [`esp32/HiwonderServo.cpp`](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp) (UART bus), [`stm32/hiwonder_servo_stm32.c`](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c) (STM32 bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python SDK"]
  node_python_bus["Python bus<br/>[servo.py]"]
  node_python_servo["Servo API<br/>[servo.py]"]
  node_python_sync["Sync motion<br/>[servo.py]"]
end

subgraph group_esp32["ESP32 SDK"]
  node_esp_bus["UART bus<br/>[HiwonderServo.cpp]"]
  node_esp_servo["Servo API<br/>[HiwonderServo.cpp]"]
  node_esp_sync["Sync motion<br/>[HiwonderServo.cpp]"]
end

subgraph group_rpi["Raspberry Pi SDK"]
  node_rpi_bus["Raspberry Pi bus"]
end

subgraph group_stm32["STM32 SDK"]
  node_stm_bus["STM32 bus"]
  node_stm_servo["Servo operations"]
  node_stm_sync["Sync operations"]
end

subgraph group_reference["Protocol Reference"]
  node_protocol_ref["Protocol reference<br/>[protocol.md]"]
  node_register_ref["Register map<br/>[register_table.md]"]
end

node_engineer(("SDK user"))
node_servo_device{{"HX-30HM servos"}}

node_engineer -->|"uses"| node_python_servo
node_engineer -->|"requests sync"| node_python_sync
node_engineer -->|"uses"| node_esp_servo
node_engineer -->|"requests sync"| node_esp_sync
node_engineer -->|"uses"| node_rpi_bus
node_engineer -->|"uses"| node_stm_servo
node_engineer -->|"requests sync"| node_stm_sync
node_python_servo -->|"reads and writes"| node_python_bus
node_python_sync -->|"sends sync write"| node_python_bus
node_python_bus -->|"UART packets"| node_servo_device
node_esp_servo -->|"reads and writes"| node_esp_bus
node_esp_sync -->|"sends sync write"| node_esp_bus
node_esp_bus -->|"UART packets"| node_servo_device
node_rpi_bus -->|"extends"| node_python_bus
node_rpi_bus -->|"UART packets"| node_servo_device
node_stm_servo -->|"calls bus operations"| node_stm_bus
node_stm_sync -->|"sends sync write"| node_stm_bus
node_stm_bus -->|"UART packets"| node_servo_device
node_engineer -.->|"consults"| node_protocol_ref
node_engineer -.->|"consults"| node_register_ref

click node_python_bus "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py"
click node_python_servo "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py"
click node_python_sync "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py"
click node_esp_bus "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp"
click node_esp_servo "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp"
click node_esp_sync "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp"
click node_rpi_bus "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/raspberrypi/hiwonder_servo_rpi.py"
click node_stm_bus "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c"
click node_stm_servo "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c"
click node_stm_sync "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c"
click node_protocol_ref "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/docs/protocol.md"
click node_register_ref "https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/docs/register_table.md"

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_python_bus,node_python_servo,node_python_sync,node_engineer toneBlue
class node_esp_bus,node_esp_servo,node_esp_sync toneAmber
class node_rpi_bus toneMint
class node_stm_bus,node_stm_servo,node_stm_sync toneRose
class node_protocol_ref,node_register_ref,node_servo_device toneIndigo
```

## Components

### Python SDK

- [Python bus](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py): `python/hiwonder/servo.py`
- [Servo API](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py): `python/hiwonder/servo.py`
- [Sync motion](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/python/hiwonder/servo.py): `python/hiwonder/servo.py`

### ESP32 SDK

- [UART bus](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp): `esp32/HiwonderServo.cpp`
- [Servo API](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp): `esp32/HiwonderServo.cpp`
- [Sync motion](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/esp32/HiwonderServo.cpp): `esp32/HiwonderServo.cpp`

### Raspberry Pi SDK

- [Raspberry Pi bus](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/raspberrypi/hiwonder_servo_rpi.py): `raspberrypi/hiwonder_servo_rpi.py`

### STM32 SDK

- [STM32 bus](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c): `stm32/hiwonder_servo_stm32.c`
- [Servo operations](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c): `stm32/hiwonder_servo_stm32.c`
- [Sync operations](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/stm32/hiwonder_servo_stm32.c): `stm32/hiwonder_servo_stm32.c`

### Protocol Reference

- [Protocol reference](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/docs/protocol.md): `docs/protocol.md`
- [Register map](https://github.com/hiwonder-official/hiwonder-servo-sdk/blob/main/docs/register_table.md): `docs/register_table.md`

### Other components

- **SDK user**
- **HX-30HM servos**

## Connections

- SDK user → Servo API: uses
- SDK user → Sync motion: requests sync
- SDK user → Servo API: uses
- SDK user → Sync motion: requests sync
- SDK user → Raspberry Pi bus: uses
- SDK user → Servo operations: uses
- SDK user → Sync operations: requests sync
- Servo API → Python bus: reads and writes
- Sync motion → Python bus: sends sync write
- Python bus → HX-30HM servos: UART packets
- Servo API → UART bus: reads and writes
- Sync motion → UART bus: sends sync write
- UART bus → HX-30HM servos: UART packets
- Raspberry Pi bus → Python bus: extends
- Raspberry Pi bus → HX-30HM servos: UART packets
- Servo operations → STM32 bus: calls bus operations
- Sync operations → STM32 bus: sends sync write
- STM32 bus → HX-30HM servos: UART packets
- SDK user → Protocol reference: consults
- SDK user → Register map: consults