# ppw0021/key_pro architecture

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

- Interactive diagram: https://gitdiagram.com/ppw0021/key_pro
- Repository: https://github.com/ppw0021/key_pro

## Overview

##### Project type and purpose
- This is an embedded hardware-software project: a DIY, split ergonomic keyboard built around three Arduinos (one master Arduino Leonardo and two slave Arduino Pro Micros).
- Purpose: scan key matrices on left/right halves, communicate via I2C to master, and emulate a USB HID keyboard to a host computer.

##### File structure
- Top-level directories:
- master/   ← firmware for the Leonardo master controller
- slave_left/   ← firmware for left Pro Micro
- slave_right/  ← firmware for right Pro Micro
- matrix/  ← single-file sketch (probably legacy or reference .ino)
- .gitignore, platformio.ini files in each firmware folder → PlatformIO+VSCode projects
- master/src/main.cpp contains I2C polling loops, HID Keyboard library usage, keyMap & keyState arrays.
- slave_{left,right}/src/main.cpp contain identical matrix-scanning code with different keyMatrixMap definitions and I2C addresses (5 and 6).

##### Key README insights
- Master ↔ slaves communicate over I2C; master polls each slave for a 30-byte key-state update.
- Each slave uses a 6-column × 5-row key matrix to detect presses/releases, records state changes, and responds to master requests with ASCII codes or 255 for no-change.
- Master translates ASCII codes via keyMap to HID keypress events on the host computer.

##### Detailed capture of essential elements
- Pin-mapping callouts for the key matrix (colToPinArray & rowToPinArray) if needed for low-level hardware docs.
- Polling delays (delay(5), delay(10)) to show timing constraints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "USB HID Host"
        PC["Host PC\n(USB HID)"]:::hardware
    end

    subgraph "Master Controller\n(Arduino Leonardo)"
        MFW["Firmware\n(src/main.cpp)"]:::firmware
        MHS["Headers\n(include/)"]:::firmware
        MLIB["Libraries\n(lib/)"]:::firmware
        MPC["platformio.ini"]:::config
        MFW --> MHS
        MFW --> MLIB
    end

    subgraph "I2C Bus\n(SDA, SCL)"
        I2C["I2C SDA/SCL\nAddresses 0x05, 0x06"]:::bus
    end

    subgraph "Left Keypad Slave\n(Arduino Pro Micro)"
        LFW["Firmware\n(src/main.cpp)"]:::firmware
        LHS["Headers\n(include/)"]:::firmware
        LLIB["Libraries\n(lib/)"]:::firmware
        LPC["platformio.ini"]:::config
        LFW --> LHS
        LFW --> LLIB
    end

    subgraph "Right Keypad Slave\n(Arduino Pro Micro)"
        RFW["Firmware\n(src/main.cpp)"]:::firmware
        RHS["Headers\n(include/)"]:::firmware
        RLIB["Libraries\n(lib/)"]:::firmware
        RPC["platformio.ini"]:::config
        RFW --> RHS
        RFW --> RLIB
    end

    LEG["Legacy Matrix Sketch\n(matrix/matrix.ino)"]:::legacy

    subgraph "Test Suites"
        MTB["master/test/README"]:::test
        LTB["slave_left/test/README"]:::test
        RTB["slave_right/test/README"]:::test
    end

    LFW -->|"30-byte key events"| I2C
    RFW -->|"30-byte key events"| I2C
    I2C -->|"Poll every 5ms"| MFW
    MFW -->|"HID keypress/release"| PC

    classDef hardware fill:#b2dfdb,stroke:#00695c;
    classDef bus fill:#bbdefb,stroke:#1565c0;
    classDef firmware fill:#ffe0b2,stroke:#ef6c00;
    classDef config fill:#f0f4c3,stroke:#827717;
    classDef legacy fill:#e1bee7,stroke:#6a1b9a;
    classDef test fill:#f8bbd0,stroke:#ad1457;

    click MFW "https://github.com/ppw0021/key_pro/blob/main/master/src/main.cpp"
    click MHS "https://github.com/ppw0021/key_pro/tree/main/master/include/"
    click MLIB "https://github.com/ppw0021/key_pro/tree/main/master/lib/"
    click MPC "https://github.com/ppw0021/key_pro/blob/main/master/platformio.ini"
    click LFW "https://github.com/ppw0021/key_pro/blob/main/slave_left/src/main.cpp"
    click LHS "https://github.com/ppw0021/key_pro/tree/main/slave_left/include/"
    click LLIB "https://github.com/ppw0021/key_pro/tree/main/slave_left/lib/"
    click LPC "https://github.com/ppw0021/key_pro/blob/main/slave_left/platformio.ini"
    click RFW "https://github.com/ppw0021/key_pro/blob/main/slave_right/src/main.cpp"
    click RHS "https://github.com/ppw0021/key_pro/tree/main/slave_right/include/"
    click RLIB "https://github.com/ppw0021/key_pro/tree/main/slave_right/lib/"
    click RPC "https://github.com/ppw0021/key_pro/blob/main/slave_right/platformio.ini"
    click LEG "https://github.com/ppw0021/key_pro/blob/main/matrix/matrix.ino"
    click MTB "https://github.com/ppw0021/key_pro/tree/main/master/test/README"
    click LTB "https://github.com/ppw0021/key_pro/tree/main/slave_left/test/README"
    click RTB "https://github.com/ppw0021/key_pro/tree/main/slave_right/test/README"
```
