# bigheadg/mmwave architecture

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

- Interactive diagram: https://gitdiagram.com/bigheadg/mmwave
- Repository: https://github.com/bigheadg/mmwave

## Overview

##### Project type and purpose
- This is an SDK & Examples repository (not a monolithic full-stack web app).
- It hosts many demo sub-projects (DRN, HAM, LPD, PC3, … ZOD), each a Python (and sometimes Arduino) app that:
– Communicates with a Batman-Kit mmWave sensor over UART (or SPI/USB).
– Parses raw radar data frames.
– Runs domain-specific signal-processing algorithms (range‐profile, Doppler, point-cloud, occupancy, people counting, etc.).
– Visualizes results interactively using pyqtgraph (2D/3D plots).
– Optionally logs raw or processed data to CSV.

##### File structure
- Top-level directories: one per demo type (DRN, HAM, LPD, …, ZOD).
- Inside each:
– Python scripts (e.g., `*_ex0.py`, `*_pyqtgraph*.py`) for data‐acquisition, processing, UI.
– Some include Arduino sketches under an `Arduino/` subfolder (for on-board configuration).
– README.md per demo explaining its purpose.
- Shared concerns:
– All Python scripts import the external mmWave library (mmWave pip package).
– Visualization uses pyqtgraph, PyQt5/Qt Widgets, numpy, pandas, scikit-learn.
– Serial comm uses pySerial (and optionally RPi.GPIO on Raspberry Pi).
– Build/deploy is manual: copy scripts to host (RPi/Jetson/Windows/Mac/NUC), install pip deps, enable UART.

##### Extract additional insights from the root README
- Lists all demo types and associated hardware requirements.
- Describes installation of dependencies (mmWave lib, tkinter, numpy, pandas, pyqtgraph, etc.).
- Mentions threading for UART reads, special handling for pyqtgraph v0.13.1, and workarounds for MQTT.

1) Hardware Layer (green):
– mmWave sensor modules (IWR6843-DRN, IWR1642-HAM, IWR6843-LPD, …).
– Host board (Raspberry Pi, Jetson Nano, Windows PC, Mac, Intel NUC).
2) Communication Layer (orange):
– UART interface (ttyS0/ttyAMA0) or SPI/USB link.
– pySerial / RPi.GPIO drivers.
3) Core SDK Layer (blue):
– mmWave Python library (frame decoder, API wrappers).
4) Application Layer (purple):
– Demo-specific Python scripts (threaded UART reader, data packet parser, algorithm module).
– Optional Arduino firmware for on-sensor config.
5) Processing & Analytics (yellow):
– Signal-processing routines (range FFT, Doppler processing, CFAR detection).
– Machine learning modules (scikit-learn for classification, clustering).
6) Visualization & UI (pink):
– pyqtgraph 2D/3D plotting components.
– PyQt5/QtWidgets event loop.
– tkinter (in some demos).
7) Storage & Logging (gray):
– CSV writers (pandas) for raw data or processed output.
8) External Services (if used):
– MQTT broker for remote telemetry (optional demos/troubleshooting).

– Hardware → Communication: raw data frames over UART.
– Communication → Core SDK: ring‐buffer or thread posts raw bytes to frame‐decoder.
– Core SDK → Application: passing parsed point cloud or radar metrics via Python API calls.
– Application → Processing: invoke signal-processing algorithms.
– Processing → Visualization: push numeric arrays or PyQt graph items to UI event loop.
– Application → Storage: write CSV files (logging thread or callback).
– Optionally, Application ↔ Arduino: configuration commands over serial.
– Optionally, Application → MQTT: publish telemetry.

c. Architectural patterns & design principles
– Layered architecture: hardware/comm → core SDK → application → UI.
– Pipeline pattern: data flows through acquisition → parsing → analytics → presentation.
– Modularity: each demo folder is a self-contained module relying on the common mmWave lib.
– Concurrency: separate threads for UART I/O vs. UI/event loop.

d. Key technologies & libraries:
– Python 3.6+
– mmWave (pip) library for sensor APIs
– pySerial, RPi.GPIO
– numpy, pandas, scikit-learn
– PyQt5 / tkinter / pyqtgraph for GUI and plotting
– Arduino IDE (INO files for sensor firmware)

##### Detail and coverage
- Entire pipeline from sensor to UI/storage.
- External dependencies (pip packages, hardware requirements) are shown.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        SensorModules["mmWave Sensor Modules"]:::hardware
        HostBoard["Host Board"]:::hardware
        ArduinoH["HAM Arduino Sketches"]:::hardware
        ArduinoT["TMD_kv Arduino Sketches"]:::hardware
        ArduinoZ["ZOD Arduino Sketches"]:::hardware
    end

    %% Communication Layer
    subgraph "Communication Layer"
        direction TB
        UARTInterface["UART/SPI Interface"]:::comm
        pySerial["pySerial / RPi.GPIO Drivers"]:::comm
        DRN_ex0["DRN_ex0.py"]:::comm
        HAM_thread["HAM_ex1_Thread.py"]:::comm
        PMB_thread["PMB_ex1_Thread.py"]:::comm
    end

    %% Core SDK Layer
    subgraph "Core SDK Layer"
        direction TB
        PC3_core["PC3_ex0.py"]:::sdk
        FDS_core["lpdFDS_raw_ex0.py"]:::sdk
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        DRN_app1["DRN_ex0.py"]:::app
        DRN_app2["pyqtgraph_drn.py"]:::app
        HAM_app1["HAM_ex0.py"]:::app
        HAM_app2["HAM_ex3_rangeProfile.py"]:::app
        LPD_app1["lpd_v09_raw_ex0.py"]:::app
        LPD_app2["lpd_v24_2d_pyqtgraph_xyz_50m.py"]:::app
        PC3_app1["PC3_ex0.py"]:::app
        PC3_app2["PC3_ex1_pandas.py"]:::app
    end

    %% Processing & Analytics
    subgraph "Processing & Analytics"
        direction TB
        RangeProfileProc["Range Profile Processing"]:::proc
        PC3_occupancy["Point-Cloud Clustering / Occupancy"]:::proc
        DopplerAnalysis["Doppler & Frequency Analysis"]:::proc
    end

    %% Visualization & UI
    subgraph "Visualization & UI"
        direction TB
        DRN_viz["pyqtgraph_3d_drn.py"]:::viz
        LPD_v13["lpd_v24_2d_pyqtgraph_v13_xyz_50m.py"]:::viz
        PC3_xyz["pyqtgraph_3d_pc3_xyz.py"]:::viz
        VED_wf["pyqtgraph_VED_waterfall.py"]:::viz
        VSD_ui["UI_vsd.py"]:::viz
        ZOD_heat["zod_ex1_heatMap.py"]:::viz
    end

    %% Storage & Logging
    subgraph "Storage & Logging"
        direction TB
        PC3_record["PC3_ex2_record.py"]:::storage
        FDS_rec["lpdFDS_raw_v7_recorder.py"]:::storage
        CSV_log["pc3_2021-12-19-21-25-28.csv"]:::storage
        PC3v2_rec["PC3_v2/PC3_ex2_record.py"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MQTT_client["jb_FDS_client_Windows_v01.py"]:::external
    end

    %% Connections
    SensorModules -->|"Raw binary frame (UART)"| UARTInterface
    HostBoard --> UARTInterface
    UARTInterface --> pySerial
    pySerial --> PC3_core
    pySerial --> FDS_core

    PC3_core --> PC3_app1
    PC3_core --> PC3_app2
    FDS_core --> LPD_app1

    PC3_app1 --> PC3_occupancy
    HAM_app2 --> RangeProfileProc
    PC3_app1 --> DopplerAnalysis

    DRN_app2 --> DRN_viz
    LPD_app2 --> LPD_v13
    PC3_app1 --> PC3_xyz
    PC3_app2 --> PC3_occupancy
    VED_wf
    VSD_ui
    ZOD_heat

    PC3_app1 --> PC3_record
    FDS_rec
    CSV_log
    PC3v2_rec

    PC3_app1 --> MQTT_client

    HAM_app2 --> ArduinoH
    LPD_app1 --> ArduinoT
    DRN_app1 --> ArduinoZ

    %% Click Events
    click ArduinoH "https://github.com/bigheadg/mmwave/blob/master/HAM/Arduino/jb_VI809_highAccuracy_onDue_released.ino"
    click ArduinoT "https://github.com/bigheadg/mmwave/blob/master/TMD_kv/Arduino/README.md"
    click ArduinoZ "https://github.com/bigheadg/mmwave/blob/master/ZOD/Arduino/jb_ZOD_V2211_ino_release.ino"
    click DRN_ex0 "https://github.com/bigheadg/mmwave/blob/master/DRN/DRN_ex0.py"
    click HAM_thread "https://github.com/bigheadg/mmwave/blob/master/HAM/python/HAM_ex1_Thread.py"
    click PMB_thread "https://github.com/bigheadg/mmwave/blob/master/PMB/PMB_ex1_Thread.py"
    click PC3_core "https://github.com/bigheadg/mmwave/blob/master/PC3/PC3_ex0.py"
    click FDS_core "https://github.com/bigheadg/mmwave/blob/master/FDS/lpdFDS_raw_ex0.py"
    click DRN_app1 "https://github.com/bigheadg/mmwave/blob/master/DRN/DRN_ex0.py"
    click DRN_app2 "https://github.com/bigheadg/mmwave/blob/master/DRN/pyqtgraph_drn.py"
    click HAM_app1 "https://github.com/bigheadg/mmwave/blob/master/HAM/python/HAM_ex0.py"
    click HAM_app2 "https://github.com/bigheadg/mmwave/blob/master/HAM/python/HAM_ex3_rangeProfile.py"
    click LPD_app1 "https://github.com/bigheadg/mmwave/blob/master/LPD/lpd_v09_raw_ex0.py"
    click LPD_app2 "https://github.com/bigheadg/mmwave/blob/master/LPD/lpd_v24_2d_pyqtgraph_xyz_50m.py"
    click PC3_app1 "https://github.com/bigheadg/mmwave/blob/master/PC3/PC3_ex0.py"
    click PC3_app2 "https://github.com/bigheadg/mmwave/blob/master/PC3/PC3_ex1_pandas.py"
    click PC3_occupancy "https://github.com/bigheadg/mmwave/blob/master/PC3/pyqtgraph_3d_pc3_occupancy.py"
    click DopplerAnalysis "https://github.com/bigheadg/mmwave/blob/master/PCR/pyqtgraph_3d_pc3_uDoppler_Freq_df.py"
    click DRN_viz "https://github.com/bigheadg/mmwave/blob/master/DRN/pyqtgraph_3d_drn.py"
    click LPD_v13 "https://github.com/bigheadg/mmwave/blob/master/LPD/pyqtgraph_13/lpd_v24_2d_pyqtgraph_v13_xyz_50m.py"
    click PC3_xyz "https://github.com/bigheadg/mmwave/blob/master/PC3/pyqtgraph_3d_pc3_xyz.py"
    click VED_wf "https://github.com/bigheadg/mmwave/blob/master/VED/pyqtgraph_VED_waterfall.py"
    click VSD_ui "https://github.com/bigheadg/mmwave/blob/master/VSD/UI_vsd.py"
    click ZOD_heat "https://github.com/bigheadg/mmwave/blob/master/ZOD/Python/zod_ex1_heatMap.py"
    click PC3_record "https://github.com/bigheadg/mmwave/blob/master/PC3/PC3_ex2_record.py"
    click FDS_rec "https://github.com/bigheadg/mmwave/blob/master/FDS/lpdFDS_raw_v7_recorder.py"
    click CSV_log "https://github.com/bigheadg/mmwave/blob/master/PC3/pc3_2021-12-19-21-25-28.csv"
    click PC3v2_rec "https://github.com/bigheadg/mmwave/blob/master/PC3_v2/PC3_ex2_record.py"
    click MQTT_client "https://github.com/bigheadg/mmwave/blob/master/PCT_FDS/jb_FDS_client_Windows_v01.py"

    %% Styles
    classDef hardware fill:#e5ffe5,stroke:#228B22
    classDef comm fill:#ffe5cc,stroke:#FFA500
    classDef sdk fill:#cce5ff,stroke:#0000CD
    classDef app fill:#e5ccff,stroke:#800080
    classDef proc fill:#ffffcc,stroke:#CCCC00
    classDef viz fill:#ffccf2,stroke:#FF1493
    classDef storage fill:#eeeeee,stroke:#808080
    classDef external fill:#f2e6d9,stroke:#A0522D
```
