# teganburns/arduinokeybridge architecture

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

- Interactive diagram: https://gitdiagram.com/teganburns/arduinokeybridge
- Repository: https://github.com/teganburns/arduinokeybridge

## Overview

##### Project Type and Purpose
- ArduinoKeyBridge is an embedded IoT firmware project written in C++/Arduino for the Arduino Uno R4 Wi-Fi.
- It turns a standard USB keyboard into a standalone, Wi-Fi–enabled input device with custom key mappings, remote command execution, status LEDs, and logging—no host PC software required.

##### File Structure
- Top-level sketch:
- ArduinoKeyBridge.ino – the entry point, `setup()` and `loop()`.
- Modular C++ components:
- WiFiConnection.* – manages SSID, sockets, HTTP or raw‐TCP interactions.
- JsonHandler.* – serializes/deserializes command payloads (JSON).
- CustomKeyboardParser.* – interprets raw HID key codes & maps them to actions.
- CustomKeyboardCommands.* – defines/executes user‐configured macros or operations.
- MinimalKeyboard.* and Magic_Keyboard_KeyMap.h – USB Host HID interface and vendor‐specific key maps.
- ArduinoKeyBridgeLogger.* – logs events to serial output or over network.
- ArduinoKeyBridgeNeoPixel.* – drives status LEDs for feedback.
- Utility script:
- upload_monitor.sh – automates firmware upload and serial monitoring.

##### Extract Insights from README
- Key features: customizable key functions, standalone operation, Wi-Fi integration.
- Hardware dependencies: USB HID Shield, Magic Keyboard, Arduino Uno R4 Wi-Fi.
- Use cases emphasize remote control, macros, IoT integration, accessibility.

##### Main Components
a. Hardware Layer
- USB Keyboard → SparkFun HID Keyboard Shield → Arduino Uno R4 Wi-Fi MCU
- NeoPixel Ring (or LED array) connected to a digital pin
- On-board Wi-Fi radio & antenna
b. Firmware Modules (Software Layer)
1. HID Interface (MinimalKeyboard & Magic_Keyboard_KeyMap)
2. Key Parsing (CustomKeyboardParser)
3. Command Execution (CustomKeyboardCommands)
4. Wi-Fi Stack & Networking (WiFiConnection)
5. Payload Handling (JsonHandler)
6. Status & Logging (ArduinoKeyBridgeNeoPixel & Logger)
c. External Services
- Remote Control Client (e.g., web UI or mobile app) – communicates via TCP/HTTP
- Optional backend or IoT platform receiving telemetry

##### Relationships & Data Flow
- USB Keyboard presses → HID Interface → Parser → Command Dispatcher
- Dispatcher may:
- Invoke local routines (macros, LED patterns, GPIO)
- Send/receive JSON over Wi-Fi via WiFiConnection
- Output logs via Serial or network to external monitoring
- LED module subscribes to status events (e.g., “connected,” “key pressed,” “error”).
- Logger records key events and network interactions.

##### Architectural Patterns & Design Principles
- Modular separation of concerns: each `.cpp/.h` pair is a single responsibility module.
- Event-driven workflow: parsing → dispatch → action.
- Layered approach: hardware abstraction (HID), business logic (commands), infrastructure (Wi-Fi, JSON).
- Extensibility: new commands or devices map into the existing parser/command modules.

##### Essential Elements
- Notes on protocols (USB HID, Wi-Fi—TCP or HTTP, JSON).
- Version of Arduino core or critical library dependencies if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        UK["USB Keyboard"]:::hardware
        SH["SparkFun HID Keyboard Shield"]:::hardware
        MCU["Arduino Uno R4 Wi-Fi MCU"]:::hardware
        LED["NeoPixel Ring"]:::hardware
    end

    %% Firmware Modules
    subgraph "Firmware Modules"
        direction TB
        SK["ArduinoKeyBridge.ino"]:::firmware
        HID1["MinimalKeyboard (HID Interface)"]:::firmware
        HID2["Magic_Keyboard_KeyMap"]:::firmware
        PARSER["CustomKeyboardParser"]:::firmware
        CMD["CustomKeyboardCommands"]:::firmware
        JSON["JsonHandler"]:::firmware
        WIFI["WiFiConnection"]:::firmware
        NEO["ArduinoKeyBridgeNeoPixel"]:::firmware
        LOG["ArduinoKeyBridgeLogger"]:::firmware
        UP["upload_monitor.sh"]:::firmware
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CLIENT["Remote Control Client"]:::external
        BACK["Optional Backend/IoT Platform"]:::external
    end

    %% Connections - Hardware to Firmware
    UK -->|"HID report"| SH
    SH -->|"USB HID"| MCU
    LED -->|"Status control"| MCU
    MCU -->|"Boot & main loop"| SK

    %% Firmware internal flow
    SK -->|"init HID"| HID1
    SK -->|"load keymap"| HID2
    HID1 -->|"raw key codes"| PARSER
    HID2 -->|"key map data"| PARSER
    PARSER -->|"Parsed keys"| CMD
    CMD -->|"Invoke routines"| NEO
    CMD -->|"Invoke routines"| LOG
    CMD -->|"JSON payload"| JSON
    JSON -->|"Formatted JSON"| WIFI
    WIFI -->|"TCP/HTTP"| CLIENT
    WIFI -->|"Telemetry"| BACK
    LOG -->|"Serial/Network logs"| CLIENT

    %% Utility Script
    UP -.-> SK

    %% Click Events
    click SK "https://github.com/teganburns/arduinokeybridge/blob/main/ArduinoKeyBridge.ino"
    click HID1 "https://github.com/teganburns/arduinokeybridge/blob/main/MinimalKeyboard.cpp"
    click HID2 "https://github.com/teganburns/arduinokeybridge/blob/main/Magic_Keyboard_KeyMap.h"
    click PARSER "https://github.com/teganburns/arduinokeybridge/blob/main/CustomKeyboardParser.cpp"
    click CMD "https://github.com/teganburns/arduinokeybridge/blob/main/CustomKeyboardCommands.cpp"
    click JSON "https://github.com/teganburns/arduinokeybridge/blob/main/JsonHandler.cpp"
    click WIFI "https://github.com/teganburns/arduinokeybridge/blob/main/WiFiConnection.cpp"
    click NEO "https://github.com/teganburns/arduinokeybridge/blob/main/ArduinoKeyBridgeNeoPixel.cpp"
    click LOG "https://github.com/teganburns/arduinokeybridge/blob/main/ArduinoKeyBridgeLogger.cpp"
    click UP "https://github.com/teganburns/arduinokeybridge/blob/main/upload_monitor.sh"

    %% Styles
    classDef hardware fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef firmware fill:#ABEBC6,stroke:#145A32,color:#0B5345
    classDef external fill:#F5B041,stroke:#935116,color:#78281F
```
