# marshallrichards/turbodrone architecture

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

- Interactive diagram: https://gitdiagram.com/marshallrichards/turbodrone
- Repository: https://github.com/marshallrichards/turbodrone

## Overview

##### High-Level File Structure Analysis
- Top level
- README.md – project introduction, setup instructions, status & roadmap
- src/
- receive_video.py – module to connect to the drone’s video stream, decode frames, and display or process them
- remote_control.py – module to assemble and send control packets (throttle, yaw, pitch, roll) to the drone
- requirements.txt – Python dependencies (e.g., socket, curses, OpenCV if used)
- There are no web-frontends or databases—this is purely a networked CLI application.

##### Key Architectural Insights from README
- The drone exposes a Wi-Fi SSID (e.g., Hiturbo-S20-XXXX) that your computer must join.
- Video is received over a UDP stream.
- Control commands are sent via a custom UDP/TCP protocol that mimics the mobile app.
- All packet formats and heartbeats were reverse-engineered from decompiled Android APKs and verified with Wireshark.

##### Main Components
a. User’s Workstation (Left-hand side)
- Python Runtime + Virtual Environment (venv)
- receive_video.py module
- remote_control.py module
- OS Network Stack & Wi-Fi Dongle driver
b. Wireless Network Layer (Center)
- 802.11n/ac Wi-Fi channel
- SSID “Hiturbo-S20-XXXXXX”
c. Drone Hardware (Right-hand side)
- Flight Controller & Firmware
- Downward-facing optical flow sensor
- 1080p camera module
- Onboard Wi-Fi transceiver
d. External Tools (Optional/Overlay)
- Wireshark (for packet inspection during development)
- jadx (for APK decompilation)

##### Relationships & Data Flows
- receive_video.py → UDP video stream → Drone camera
- remote_control.py → UDP control packets → Drone flight controller
- Bidirectional heartbeats (UDP) maintain the session
- The Virtual Environment and Python interpreter wrap both modules in the same host boundary

##### Architectural Patterns & Design Principles
- Modular CLI design: separate concerns (video vs. control) in two executable modules
- Network-centric design: everything is modeled as packet streams over UDP
- Reverse-engineering feedback loop: external tools feed into protocol implementation

- Optional callouts for development tools (Wireshark, jadx) to show the engineering workflow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Environment Boundary
    subgraph "Python Environment" 
        direction TB
        VENV["Virtual Environment & Python Runtime"]:::env
        RV["receive_video.py"]:::module
        RC["remote_control.py"]:::module
        VENV --> RV
        VENV --> RC
    end

    %% Wireless Network Layer
    NET["802.11n/ac Wi-Fi\nSSID “Hiturbo-S20-XXXXXX”"]:::network

    %% Drone Hardware
    subgraph "Drone Hardware"
        direction TB
        FC["Flight Controller & Firmware"]:::hardware
        CAM["1080p Camera Module"]:::hardware
        OPT["Optical Flow Sensor"]:::hardware
        WIFI["Onboard Wi-Fi Transceiver"]:::hardware
        FC --> OPT
        FC --> CAM
        CAM --> WIFI
        OPT --> WIFI
    end

    %% Development Tools
    subgraph "Development Only" 
        direction TB
        WS["Wireshark"]:::tool
        JD["jadx"]:::tool
    end

    %% Connections and Data Flows
    RV -->|UDP 5600 → Video Feed| NET
    NET -->|Forward Stream| CAM
    RC -->|UDP 5556 ← Control Commands| NET
    NET -->|Forward Commands| FC
    VENV ---|UDP Heartbeat ↔| NET
    NET ---|UDP Heartbeat ↔| FC
    WS -.-> RV
    WS -.-> RC
    JD -.-> RC

    %% Repository Artifacts (dash border)
    subgraph "Repository Artifacts"
        direction TB
        README["README.md"]:::repo
        REQ["requirements.txt"]:::repo
        DOCS["docs/"]:::repo
        IMGS["docs/images/"]:::repo
        GITIGNORE[".gitignore"]:::repo
    end

    %% Click Events
    click RV "https://github.com/marshallrichards/turbodrone/blob/master/src/receive_video.py"
    click RC "https://github.com/marshallrichards/turbodrone/blob/master/src/remote_control.py"
    click REQ "https://github.com/marshallrichards/turbodrone/blob/master/src/requirements.txt"
    click README "https://github.com/marshallrichards/turbodrone/blob/master/README.md"
    click DOCS "https://github.com/marshallrichards/turbodrone/tree/master/docs/"
    click IMGS "https://github.com/marshallrichards/turbodrone/tree/master/docs/images/"
    click GITIGNORE "https://github.com/marshallrichards/turbodrone/blob/master/.gitignore"

    %% Styles
    classDef env fill:#e0f7fa,stroke:#006064,color:#004d40,stroke-width:2px;
    classDef module fill:#bbdefb,stroke:#0d47a1,color:#0d47a1,stroke-width:1px;
    classDef network fill:#fff9c4,stroke:#f57f17,color:#bf360c,stroke-width:2px,stroke-dasharray: 5 5;
    classDef hardware fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20,stroke-width:1px;
    classDef tool fill:#eeeeee,stroke:#616161,color:#212121,stroke-width:1px,stroke-dasharray: 2 2;
    classDef repo fill:none,stroke:#9e9e9e,color:#616161,stroke-dasharray: 4 4;
    class RV,RC module
    class VENV env
    class NET network
    class FC,CAM,OPT,WIFI hardware
    class WS,JD tool
    class README,REQ,DOCS,IMGS,GITIGNORE repo
```
