# retsediv/wifi_csi_based_har architecture

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

- Interactive diagram: https://gitdiagram.com/retsediv/wifi_csi_based_har
- Repository: https://github.com/retsediv/wifi_csi_based_har

## Overview

##### Project Type & Purpose
- This is a research-oriented full-pipeline system:
- Embedded C code on two routers: one sends packets, the other extracts CSI and forwards them.
- A Python/Qt “data_retrieval” service that listens over UDP, visualizes, and persists raw CSI.
- A Python “model” package that calibrates data, labels activities, builds datasets, trains deep models (LSTM, InceptionTime, etc.), runs experiments, and provides EDA notebooks.

##### High-Level Components
- Hardware Layer
- Router A (sendData.c)
- Router B (recvCSI + csi_fun.c/h)
- Networking
- UDP link from Router B → Data Retrieval Server
- Data Retrieval & Storage
- Python server (`run_visualization_server.py`)
- Test client (`run_test_client.py`) for emulation
- Raw CSI files in `data_retrieval/data/`
- Preprocessing & Calibration
- `data_retrieval/csi_extraction` module: calibration, parsing, log reading
- Labeling
- `model/label_activities.py` (activity labels)
- Dataset & Metrics
- `model/dataset.py` (dataset abstraction)
- `model/metrics.py` (evaluation metrics)
- Model Training & Experiments
- Model definitions in `model/models/*.py` (FCN, LSTM, InceptionTime)
- Training scripts (`model/train_lstm.py`, `model/main.py`)
- Learning rate schedulers (`model/schedulers`)
- Experiment directories (`model/experiments/1x1_vs_2x2`)
- Visualization & Analysis
- Jupyter notebooks in `model/notebooks` for EDA and result visualization
- External Dependencies
- Wi-Fi CSI Atheros user-space tool (fork)
- PyTorch, fastai, torchtimeseries, Qt (for UI), NumPy/Pandas/Matplotlib

##### Relationships & Data Flow
1. Router A sends data packets over Wi-Fi → Router B.
2. Router B runs `recvCSI` C code → extracts CSI → wraps into binary UDP payloads → sends to PC.
3. On the PC, `run_visualization_server.py` listens on UDP port → decodes streams with `csi_extraction` → optionally displays UI (`window.ui`) → writes raw CSI to disk.
4. Offline, Python scripts load raw CSI files → run calibration (`csi_calibration.py`) → label events with YOLO model on video frames → produce a cleaned, labeled dataset.
5. Dataset feeds into deep learning pipeline: instantiate models → train with schedulers → evaluate with `metrics.py` → store results under `model/experiments`.
6. Notebooks consume experiment artifacts for plotting and EDA.

##### Architectural Patterns & Principles
- Layered, modular pipeline:
Hardware → Data Ingestion → Preprocessing → Labeling → Modeling → Visualization
- Separation of Concerns: embedded C for CSI capture; Python service for ingestion; pure-Python ML for training & analysis.
- Extensibility points:
- New models can be dropped into `model/models/`
- New schedulers in `model/schedulers/`
- New labeling methods via additional scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Router Layer
    subgraph "Router Layer"
        direction TB
        A1["sendData.c"]:::hardware
        A2["sendData_con.c"]:::hardware
        A3["Makefile"]:::hardware
        B1["main.c"]:::hardware
        B2["csi_fun.c"]:::hardware
        B3["csi_fun.h"]:::hardware
        B4["Makefile"]:::hardware
    end

    %% Data Retrieval Layer
    subgraph "Data Retrieval Layer"
        direction TB
        Server["run_visualization_server.py"]:::service
        UI["window.ui"]:::service
        TestClient["run_test_client.py"]:::service
        RawStore[(Raw CSI Data Store)]:::storage
    end

    %% Preprocessing & Labeling
    subgraph "Preprocessing & Labeling"
        direction TB
        subgraph "CSI Extraction & Calibration"
            direction TB
            Cal["csi_calibration.py"]:::service
            ReadCSI["read_csi.py"]:::service
            ReadLog["read_log_file.py"]:::service
        end
        LabAct["label_activities.py"]:::service
        LabBox["label_human_boxes.py"]:::service
        YCfg["yolov3.cfg"]:::storage
        CNam["coco.names"]:::storage
    end

    %% Modeling & Experiments
    subgraph "Modeling & Experiments"
        direction TB
        DS["dataset.py"]:::ml
        MT["metrics.py"]:::ml
        subgraph "Models"
            direction TB
            M1["FCNBaseline.py"]:::ml
            M2["LSTMClassifier.py"]:::ml
            M3["SimpleLSTMClassifier.py"]:::ml
            M4["InceptionTime.py"]:::ml
            MU["utils.py"]:::ml
        end
        subgraph "Schedulers"
            direction TB
            Sch["CycleLR.py"]:::ml
        end
        TrainLSTM["train_lstm.py"]:::ml
        Main["main.py"]:::ml
        ExpRes[(Experiment Results)]:::storage
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis"
        direction TB
        NB1["fastai_timeseries notebooks"]:::ml
        NB2["torchtimeseries notebooks"]:::ml
    end

    %% Data Flows
    A1 -->|"Wi-Fi CSI Packets"| B1
    B1 -->|"UDP CSI Stream"| Server
    Server -->|"Display UI"| UI
    Server -->|"Write .dat files"| RawStore
    TestClient -.->|"Emulate UDP"| Server

    RawStore --> Cal
    Cal --> ReadCSI
    Cal --> ReadLog
    Cal --> LabAct
    Cal --> LabBox

    LabAct --> DS
    LabBox --> DS

    DS --> TrainLSTM
    DS --> Main
    Sch --> TrainLSTM
    TrainLSTM --> MT
    Main --> MT
    MT --> ExpRes

    ExpRes --> NB1
    ExpRes --> NB2

    %% Click Events
    click A1 "https://github.com/retsediv/wifi_csi_based_har/blob/master/router/sendData/sendData.c"
    click A2 "https://github.com/retsediv/wifi_csi_based_har/blob/master/router/sendData/sendData_con.c"
    click A3 "https://github.com/retsediv/wifi_csi_based_har/tree/master/router/sendData/Makefile"
    click B1 "https://github.com/retsediv/wifi_csi_based_har/blob/master/router/recvCSI/main.c"
    click B2 "https://github.com/retsediv/wifi_csi_based_har/blob/master/router/recvCSI/csi_fun.c"
    click B3 "https://github.com/retsediv/wifi_csi_based_har/blob/master/router/recvCSI/csi_fun.h"
    click B4 "https://github.com/retsediv/wifi_csi_based_har/tree/master/router/recvCSI/Makefile"
    click Server "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/run_visualization_server.py"
    click UI "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/window.ui"
    click TestClient "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/run_test_client.py"
    click RawStore "https://github.com/retsediv/wifi_csi_based_har/tree/master/data_retrieval/data/"
    click Cal "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/csi_extraction/csi_calibration.py"
    click ReadCSI "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/csi_extraction/read_csi.py"
    click ReadLog "https://github.com/retsediv/wifi_csi_based_har/blob/master/data_retrieval/csi_extraction/read_log_file.py"
    click LabAct "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/label_activities.py"
    click LabBox "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/label_human_boxes.py"
    click YCfg "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/yolo_data/yolov3.cfg"
    click CNam "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/yolo_data/coco.names"
    click DS "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/dataset.py"
    click MT "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/metrics.py"
    click M1 "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/models/FCNBaseline.py"
    click M2 "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/models/LSTMClassifier.py"
    click M3 "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/models/SimpleLSTMClassifier.py"
    click M4 "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/models/InceptionTime.py"
    click MU "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/models/utils.py"
    click TrainLSTM "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/train_lstm.py"
    click Main "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/main.py"
    click Sch "https://github.com/retsediv/wifi_csi_based_har/blob/master/model/schedulers/CycleLR.py"
    click ExpRes "https://github.com/retsediv/wifi_csi_based_har/tree/master/model/experiments/1x1_vs_2x2"
    click NB1 "https://github.com/retsediv/wifi_csi_based_har/tree/master/model/notebooks/fastai_timeseries/"
    click NB2 "https://github.com/retsediv/wifi_csi_based_har/tree/master/model/notebooks/torchtimeseries/"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef service fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef storage fill:#ffff99,stroke:#333,stroke-width:1px;
    classDef ml fill:#ffcc99,stroke:#333,stroke-width:1px;
```
