# leonelnieto/uart_sniffer architecture

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

- Interactive diagram: https://gitdiagram.com/leonelnieto/uart_sniffer
- Repository: https://github.com/leonelnieto/uart_sniffer

## Overview

##### Project type and purpose
- This is a desktop GUI application written in Python, using PySide6/Qt6 for the interface and pyserial for UART communication.
- Its sole purpose is to sniff and display UART traffic on two channels (TX and RX), in real time, with logging capabilities.

##### File structure
- Top‐level files:
- sniffer_app.py – main application entry point and logic
- ui_sniffer_uart.py – auto-generated Qt UI layout
- uart_sniffer.ui – Qt Designer form (source of ui_sniffer_uart.py)
- requirements.txt – Python dependencies
- README.md, LICENSE, .gitignore
- Runtime‐generated logs/ directory (not under source control)

##### README for additional insights
- Dual‐threaded model: one thread per UART channel, communicating via Qt signals.
- MVC‐style separation: UI (UserInterface) vs. worker threads (UART readers) vs. data persistence (log files).
- Configuration options exposed in the UI for COM port and baud rate.
- Data flow: Serial port → Worker thread → Qt signal → UI display → Optional log writer

##### Main components
a. Frontend/UI Layer
- UserInterface (QMainWindow subclass)
- Ui_MainWindow (layout and controls)
- Configuration panel (port selectors, baudrate dropdowns, enable/disable checkboxes)
- Control buttons (Start, Stop, Save)
- Tab widget (TX tab, RX tab, Combined tab)
b. Backend/Worker Layer
- TX Reader Thread (pyserial.Serial reader)
- RX Reader Thread (pyserial.Serial reader)
- UartSignals (custom Qt signals for data emission)
c. Persistence Layer
- Log Writer (file I/O module writing to logs/log_YYYY_MM_DD_HH_MM_SS.txt)
d. External Interfaces
- Physical UART devices (two COM ports)
- Filesystem (logs directory)
e. Resources

##### Relationships and interactions
- On “Start”: UI creates/configures each serial thread (TX and/or RX), opens ports
- Worker threads read bytes asynchronously, package them into hex strings
- Worker threads emit Qt signals (via UartSignals) carrying data payloads
- UI slots receive signals and append text to the appropriate tab(s)
- UI “Save” action invokes the Log Writer, writing accumulated data to a timestamped file
- On “Stop” or exit: threads are signaled to terminate, ports are closed, resources cleaned up

##### Architectural patterns and design principles
- Model–View–Controller separation:
- Model: Data coming from UART and data stored in logs
- View: Qt UI elements, tabs, text widgets
- Controller: sniffer_app.py orchestrates threads and signal-slot wiring
- Producer–Consumer pattern: UART reading threads produce data, UI consumes via queued signals
- Threading for non-blocking UI: daemon threads + Qt signal/event loop for thread-safe updates

##### Relevant technologies and frameworks
- PySide6/Qt6: UI framework, signals & slots, threading integration
- pyserial: Serial port communication
- Python standard library: threading, logging, file I/O
- Qt Designer: ui_sniffer_uart.ui

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        COM_TX["UART COM Port TX"]:::external
        COM_RX["UART COM Port RX"]:::external
        FILESYS["Filesystem (logs/)"]:::external
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        TXThread["TX Reader Thread"]:::worker
        RXThread["RX Reader Thread"]:::worker
        UartSignals["UartSignals (Qt signals)"]:::worker
    end

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        direction TB
        UI["UserInterface (QMainWindow)"]:::ui
        UiMain["Ui_MainWindow (layout & controls)"]:::ui
        ConfigPanel["Configuration Panel"]:::ui
        ControlButtons["Control Buttons (Start/Stop/Save)"]:::ui
        TabWidget["Tab Widget (TX/RX/Combined)"]:::ui
        ResourceQRC["resources/resourcer.qrc"]:::ui
        ResourceRC["resources/resourcer_rc.py"]:::ui
        UiForm["uart_sniffer.ui"]:::ui
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        LogWriter["Log Writer (file I/O)"]:::persistence
    end

    %% Documentation & Config
    subgraph "Project Files"
        direction TB
        MainApp["sniffer_app.py"]:::docs
        Requirements["requirements.txt"]:::docs
        Readme["README.md"]:::docs
        GitIgnore[".gitignore"]:::docs
        License["LICENSE"]:::docs
        UiModule["ui_sniffer_uart.py"]:::docs
    end

    %% Connections External to Worker
    COM_TX -->|"bytes in"| TXThread
    COM_RX -->|"bytes in"| RXThread

    %% Worker to Signals
    TXThread -->|"bytes→hex string"| UartSignals
    RXThread -->|"bytes→hex string"| UartSignals

    %% Signals to UI
    UartSignals -->|"signal emit"| UI

    %% UI composition
    UI --> UiMain
    UI --> ConfigPanel
    UI --> ControlButtons
    UI --> TabWidget
    UI --> ResourceRC
    ResourceQRC --> ResourceRC
    UiForm -.-> UiMain

    %% UI to Log Writer
    UI -->|"Save action"| LogWriter

    %% Log Writer to Filesystem
    LogWriter -->|"write file"| FILESYS

    %% Application orchestration
    MainApp --> TXThread
    MainApp --> RXThread
    MainApp --> UI
    MainApp --> LogWriter

    %% Documentation connections
    MainApp --> Requirements
    MainApp --> Readme
    MainApp --> GitIgnore
    MainApp --> License
    MainApp --> UiModule

    %% Click Events
    click MainApp "https://github.com/leonelnieto/uart_sniffer/blob/main/sniffer_app.py"
    click UiModule "https://github.com/leonelnieto/uart_sniffer/blob/main/ui_sniffer_uart.py"
    click UiForm "https://github.com/leonelnieto/uart_sniffer/blob/main/uart_sniffer.ui"
    click ResourceQRC "https://github.com/leonelnieto/uart_sniffer/blob/main/resources/resourcer.qrc"
    click ResourceRC "https://github.com/leonelnieto/uart_sniffer/blob/main/resources/resourcer_rc.py"
    click Requirements "https://github.com/leonelnieto/uart_sniffer/blob/main/requirements.txt"
    click Readme "https://github.com/leonelnieto/uart_sniffer/blob/main/README.md"
    click GitIgnore "https://github.com/leonelnieto/uart_sniffer/blob/main/.gitignore"
    click License "https://github.com/leonelnieto/uart_sniffer/tree/main/LICENSE"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef worker fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef persistence fill:#FFD700,stroke:#000,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px
```
