# rub-syssec/dronesecurity architecture

> Architecture diagram of the GitHub repository rub-syssec/dronesecurity, 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/rub-syssec/dronesecurity
- Repository: https://github.com/rub-syssec/dronesecurity

## Overview

##### Project Type and Purpose
- This is a Python-based proof-of-concept receiver for DJI’s proprietary Drone-ID protocol. It can operate in two modes:
- Offline mode: reads raw I/Q sample files from disk
- Live mode: captures I/Q samples in real time from an SDR (e.g., Ettus USRP B205-mini via UHD)
- The goal is to reverse-engineer, detect, decode, and display Drone-ID frames, optionally in a GUI for debugging.

##### File-Structure Analysis
Top-level:
src/ directory:
- droneid_receiver_offline.py – CLI entry point for offline decoding
- droneid_receiver_live.py – CLI entry point for live decoding via UHD
- SpectrumCapture.py – captures or loads raw samples and performs packet detection
- Packet.py – per-frame processing: CFO estimation, timing, ZC sequence detection
- zcsequence.py – Zadoff–Chu sequence correlation routines
- qpsk.py – QPSK demodulation logic (brute-force orientation, soft bits)
- packetizer.py / droneid_packet.py – descrambling, turbo-decode, unpack bitstream into fields
- .py / helpers.py / goldgen.py – coordinate transformations, plotting, helper utilities

##### README Insights
- Describes the staged pipeline: capture → detection → synchronization → OFDM demod → decoding → CRC check → statistics & plotting.
- Lists external dependencies: Python3, numpy, scipy, matplotlib, UHD driver, inspectrum for offline visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inputs
    subgraph "Input Modes"
        direction TB
        LiveReceiver["Live Mode Entry\n(droneid_receiver_live.py)"]:::capture
        OfflineReceiver["Offline Mode Entry\n(droneid_receiver_offline.py)"]:::capture
    end

    %% Capture Stage
    SpectrumCapture["SpectrumCapture\n(capture or load I/Q samples)"]:::capture

    %% Packet Processing
    PacketProc["Packet Processing\n(CFO estimation, frame segmentation)"]:::sync
    ZC["ZC Sequence Correlation\n(zcsequence)"]:::sync

    %% Demodulation Stage
    QPSK["QPSK Demodulation\n(qpsk.py)"]:::demod

    %% Decoding Stage
    Packetizer["Descrambler & Turbo Decoder\n(packetizer.py)"]:::decode
    DronePacket["DroneIDPacket & CRC Check\n(droneid_packet.py)"]:::decode

    %% Output Stage
    CLI["CLI Output\n(JSON payload & stats)"]:::output
    GUI["Debug GUI\n(gui.py)"]:::output
    Map["Map Plotter\n(map.py)"]:::output

    %% Utilities
    subgraph "Utilities"
        direction TB
        Helpers["Helper Utilities\n(helpers.py)"]:::util
        Goldgen["Reference Bit Pattern Generator\n(goldgen.py)"]:::util
    end

    %% Data Flow
    LiveReceiver -->|"I/Q samples via UHD"| SpectrumCapture
    OfflineReceiver -->|"I/Q files"| SpectrumCapture
    SpectrumCapture -->|"raw I/Q samples"| PacketProc
    PacketProc -->|"time sync & frames"| ZC
    ZC -->|"correlated signals"| PacketProc
    PacketProc -->|"OFDM symbols"| QPSK
    QPSK -->|"soft bits"| Packetizer
    Packetizer -->|"bitstream"| DronePacket
    DronePacket -->|"decoded JSON"| CLI
    DronePacket -->|"decoded JSON"| GUI
    DronePacket -->|"coordinates"| Map

    %% Utilities connections
    PacketProc --> Helpers
    Packetizer --> Helpers
    Packetizer --> Goldgen

    %% Click Events
    click LiveReceiver "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/droneid_receiver_live.py"
    click OfflineReceiver "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/droneid_receiver_offline.py"
    click SpectrumCapture "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/SpectrumCapture.py"
    click PacketProc "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/Packet.py"
    click ZC "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/zcsequence.py"
    click QPSK "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/qpsk.py"
    click Packetizer "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/packetizer.py"
    click DronePacket "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/droneid_packet.py"
    click GUI "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/gui.py"
    click Map "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/map.py"
    click Helpers "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/helpers.py"
    click Goldgen "https://github.com/rub-syssec/dronesecurity/blob/public_squash/src/goldgen.py"

    %% Styles
    classDef capture fill:#cce5ff,stroke:#3399ff,color:#000
    classDef sync fill:#ffe5b4,stroke:#ff9900,color:#000
    classDef demod fill:#d4edda,stroke:#28a745,color:#000
    classDef decode fill:#e2f0d9,stroke:#6c757d,color:#000
    classDef output fill:#f5e6ff,stroke:#800080,color:#000
    classDef util fill:#f0f0f0,stroke:#666666,color:#000
    classDef external fill:#e8f4f8,stroke:#5bc0de,color:#000
```
