# manushyaaa/knob architecture

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

- Interactive diagram: https://gitdiagram.com/manushyaaa/knob
- Repository: https://github.com/manushyaaa/knob

## Overview

##### Project type and purpose
- This is a hardware-plus-software full-stack embedded control system.
- Purpose: provide a rotary-encoder “knob” device (Arduino + OLED) that sends events over USB serial to a host PC. A Python service listens, translates those events into system actions (volume, brightness), HTTP calls (WLED), or Spotify Web API calls, and sends display updates back to the Arduino.

##### File structure
- Top-level:
- README.md – project overview and usage
- get_device_info.py – helper to discover Arduino’s USB VID/PID
- v10/
– Arduino/knob_v1dot9.ino – firmware running on the Arduino MCU
– knob_v1dot9.py – main Python script that implements the controller logic
– productionF.pyw – Windows GUI wrapper (alternate entry point)
- No separate “frontend/backend” folders, but clear separation: one “frontend” on the device (Arduino+OLED) and one “backend” on the PC (Python service).

##### Insights from the README
- Hardware components: rotary encoder, push buttons, OLED screen, Arduino board
- Python dependencies: requests, serial, spotipy, pynput, screen_brightness_control
- Modes: Volume, Brightness, Spotify, WLED
- Bidirectional serial communication: events → Python → actions; time/mode/status → Arduino OLED

##### Main components
A. Hardware Device (Embedded Frontend)
- Rotary Encoder & Buttons
- OLED Display (Adafruit SSD1306)
- Arduino MCU (knob_v1dot9.ino)
B. Host PC Service (Backend)
- Serial Communication Module (pyserial)
- Command Mapping & Mode Manager
- Action Modules:
- System Volume Control (pynput or OS API)
- Screen Brightness Control (screen_brightness_control)
- Spotify Controller (spotipy → Spotify Web API)
- WLED Controller (requests → WLED HTTP API)
- Time & Status Updater (sends current time/mode back over serial)
C. External Services & Subsystems
- Operating System Audio Subsystem
- Operating System Display Subsystem
- Spotify Web API (external)
- WLED HTTP API (local/remote)

##### Relationships & data flows
1. User rotates encoder or presses button → Arduino firmware reads change
2. Arduino sends event message (e.g., “MODE=2, DIR=+1”) via USB serial → Python service
3. Python parses message → updates internal mode or executes corresponding action module
4. Action module call:
- OS volume/brightness API → adjusts system
- HTTP request → WLED controller
- Spotify Web API call → control music
5. Periodically (or on mode switch), Python queries system clock → sends formatted time/status via serial → Arduino updates OLED

##### Architectural patterns & principles
- Event-driven architecture: hardware events drive software actions
- Separation of concerns: embedded firmware vs. host service
- Modular design: each action (volume, brightness, Spotify, WLED) is a separate module
- Config-driven: a dictionary in the Python script holds VID/PID and service credentials

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Device
    subgraph "Hardware Device"
        Encoder["Rotary Encoder & Buttons"]:::hardware
        MCU["knob_v1dot9.ino on Arduino MCU"]:::hardware
        OLED["OLED Display (SSD1306)"]:::hardware
    end

    %% Host PC Service
    subgraph "Host PC Service"
        SerialIO["Serial Comm Module\n(pyserial)"]:::software
        Script["knob_v1dot9.py\n(Main Controller Script)"]:::software
        GUI["productionF.pyw\n(Windows GUI Wrapper)"]:::software
        VolCtrl["System Volume Control\n(pynput)"]:::software
        BrightCtrl["Screen Brightness Control\n(screen_brightness_control)"]:::software
        SpotifyCtrl["Spotify Controller\n(spotipy)"]:::software
        WLEDCtrl["WLED Controller\n(requests)"]:::software
        TimeUpdater["Time & Status Updater"]:::software
        Helper["get_device_info.py\n(USB Discovery)"]:::software
        README["README.md\n(Project Overview)"]:::docs
    end

    %% External Services & Subsystems
    subgraph "External Services & Subsystems"
        OS_Audio["OS Audio Subsystem"]:::external
        OS_Display["OS Display Subsystem"]:::external
        SpotifyAPI["Spotify Web API"]:::external
        WLED_API["WLED HTTP API"]:::external
    end

    %% Connections
    Encoder --> MCU
    MCU -->|"USB Serial (pyserial)"| SerialIO
    SerialIO --> Script
    Script --> ModeMgr(["Command Mapping & Mode Manager"]):::software
    ModeMgr --> VolCtrl
    ModeMgr --> BrightCtrl
    ModeMgr --> SpotifyCtrl
    ModeMgr --> WLEDCtrl
    VolCtrl -->|"OS API"| OS_Audio
    BrightCtrl -->|"OS API"| OS_Display
    SpotifyCtrl -->|"HTTP API"| SpotifyAPI
    WLEDCtrl -->|"HTTP API"| WLED_API
    ModeMgr -->|"periodic update"| TimeUpdater
    TimeUpdater -->|"USB Serial (pyserial)"| SerialIO
    SerialIO -->|"display update"| OLED
    Script --> GUI
    Script --> Helper
    Script --> README

    %% Click Events
    click MCU "https://github.com/manushyaaa/knob/blob/main/v10/Arduino/knob_v1dot9.ino"
    click Script "https://github.com/manushyaaa/knob/blob/main/v10/knob_v1dot9.py"
    click GUI "https://github.com/manushyaaa/knob/blob/main/v10/productionF.pyw"
    click Helper "https://github.com/manushyaaa/knob/blob/main/get_device_info.py"
    click README "https://github.com/manushyaaa/knob/blob/main/README.md"

    %% Styles
    classDef hardware fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef software fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef docs fill:#F9F,stroke:#333,stroke-width:1px
```
