# techpaul/ps2keyadvanced architecture

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

- Interactive diagram: https://gitdiagram.com/techpaul/ps2keyadvanced
- Repository: https://github.com/techpaul/ps2keyadvanced

## Overview

##### Project Type and Purpose
- Type: Embedded C++ Arduino library (“PS2KeyAdvanced”)
- Purpose: Provide full PS/2 keyboard protocol support on Arduino‐compatible boards (AVR, SAM, STM32, ESP32, etc.), decoding scan codes into 16‑bit key events, plus bi‑directional functions (LED control, reset, set scan code set).

##### File Structure
Top‑level files:
– library.properties, keywords.txt → Arduino meta
– README.md, LICENSE → documentation
src/
– PS2KeyAdvanced.cpp / .h → core driver class
– PS2KeyCode.h → keycode constants and bitfield definitions
– PS2KeyTable.h → scan‑code→keycode lookup tables
examples/
– SimpleTest.ino → serial‑only demo
– advcodetest.ino → bi‑directional tests (commands ←→ keyboard)
– KeyToLCD.ino → LCD display of key events
extra/
– Porting.md, PS2 Keyboard.pdf → platform‑specific notes

##### README for Insights
– Interrupt‑driven, two‑wire PS/2 protocol
– Buffering, parity checking, resend logic
– Full 16‑bit return value encoding make/break, modifiers, scan‑code type
– Optional commands: set LEDs, reset, read ID

##### Main Components
A. Hardware Layer
1. PS/2 Keyboard (clock line, data line, pull‑ups)
2. Level Translator (for 3.3V boards)
3. Arduino‑compatible MCU (pins: dataPin, irqPin)
4. Optional Peripherals (Serial USB, LCD module)
B. Driver Layer (PS2KeyAdvanced Library)
1. Interrupt Service Routine (ISR) on falling clock edge
2. Bit‑banging state machine (bit count, parity check)
3. Scan‑code assembly → look up in PS2KeyTable → PS2KeyCode constants
4. Circular buffer (holds 16‑bit key events)
5. Command transmit FSM (send commands back to keyboard, handle _PS2_BUSY)
C. Application Layer (User Sketch / Examples)
1. setup(): keyboard.begin(dataPin, irqPin)
2. loop(): if (keyboard.available()) { key = keyboard.read(); … }
3. Optional: keyboard.setLEDs(), keyboard.write(), etc.
4. Output: Serial.print or LCD.setCursor()/print

##### Relationships and Data Flow
– ISR → Driver State Machine → Buffer
– Application loop ← reads buffer
– Application → Driver Command Transmit → PS/2 Keyboard
– Optionally: Application → Serial or LCD

##### Architectural Patterns
– Layered design: Hardware abstraction (pins) → Protocol driver → Public API
– Interrupt‑driven bit‑banging for reliable timing
– Lookup table pattern (PS2KeyTable) for fast code translation
– Circular buffer for decoupling ISR from main loop

##### Technologies and Frameworks
– Arduino core (Hardware abstraction, attachInterrupt)
– C++ classes (.cpp/.h)
– IDE Integration (library.properties, keywords.txt)
– PlatformIO or native Arduino IDE

– All components and files clearly labeled.
– Layers (HW, driver, API, application) visually separated.
– Call out any timing‑critical paths (ISR, bit‑banging).
– Optionally, annotate performance or footprint metrics if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        PS2Keyboard["PS/2 Keyboard"]:::hardware
        LevelTranslator["Level Translator"]:::hardware
        MCU["Arduino MCU\n(dataPin, irqPin)"]:::hardware
        SerialUSB["Serial USB"]:::hardware
        LCDModule["LCD Module"]:::hardware
    end

    %% Driver Layer
    subgraph "Driver Layer"
        direction TB
        ISR["Interrupt Service Routine"]:::driver
        StateMachine["Bit‑banging State Machine"]:::driver
        ScanLookup["Scan‑Code Lookup\n(PS2KeyTable.h)"]:::driver
        KeycodeDef["Keycode Definitions\n(PS2KeyCode.h)"]:::driver
        Buffer["Circular Buffer\n(16‑bit events)"]:::datastore
        CommandFSM["Command Transmit FSM"]:::driver
        PS2KeyAdv["PS2KeyAdvanced\n(PS2KeyAdvanced.cpp/.h)"]:::driver
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        SimpleDemo["SimpleTest Demo"]:::app
        BiDirDemo["advcodetest Demo"]:::app
        LCDDemo["KeyToLCD Demo"]:::app
    end

    %% Documentation Sidebar
    subgraph "Documentation & Extras"
        direction TB
        LibraryMeta["library.properties\nkeywords.txt"]:::doc
        MainDocs["README.md\nLICENSE"]:::doc
        PortingNotes["Porting.md"]:::doc
        ProtocolPDF["PS2 Keyboard.pdf"]:::doc
        CodesList["codes.txt"]:::doc
        ReadmeExtra["readme.txt"]:::doc
        Websites["websites.txt"]:::doc
    end

    %% Connections Hardware -> Driver
    PS2Keyboard -->|"PS/2 clock & data"| LevelTranslator
    LevelTranslator --> MCU
    MCU -->|"IRQ on falling clock"| ISR

    %% Driver internal flow
    ISR -->|"raw bits"| StateMachine
    StateMachine -->|"assembled scan code"| ScanLookup
    ScanLookup -->|"keycode bits"| KeycodeDef
    KeycodeDef -->|"16-bit key event"| Buffer
    CommandFSM -->|"commands"| PS2Keyboard
    PS2KeyAdv --> ISR
    PS2KeyAdv --> StateMachine
    PS2KeyAdv --> ScanLookup
    PS2KeyAdv --> KeycodeDef
    PS2KeyAdv --> Buffer
    PS2KeyAdv --> CommandFSM

    %% Application interactions
    SimpleDemo -->|"keyboard.begin() / available() / read()"| PS2KeyAdv
    BiDirDemo -->|"keyboard.setLEDs()/write()"| PS2KeyAdv
    LCDDemo -->|"LCD.print() of read()"| PS2KeyAdv
    SimpleDemo --> SerialUSB
    BiDirDemo --> SerialUSB
    LCDDemo --> LCDModule

    %% Documentation links
    PS2KeyAdv -.->|uses| LibraryMeta
    PS2KeyAdv -.->|refers| MainDocs
    PS2KeyAdv -.->|porting notes| PortingNotes
    PS2KeyAdv -.->|protocol ref| ProtocolPDF
    PS2KeyAdv -.->|code tables| CodesList
    PS2KeyAdv -.->|additional notes| ReadmeExtra
    PS2KeyAdv -.->|web refs| Websites

    %% Click Events
    click PS2KeyAdv "https://github.com/techpaul/ps2keyadvanced/blob/master/src/PS2KeyAdvanced.cpp"
    click KeycodeDef "https://github.com/techpaul/ps2keyadvanced/blob/master/src/PS2KeyCode.h"
    click ScanLookup "https://github.com/techpaul/ps2keyadvanced/blob/master/src/PS2KeyTable.h"
    click SimpleDemo "https://github.com/techpaul/ps2keyadvanced/blob/master/examples/SimpleTest/SimpleTest.ino"
    click BiDirDemo "https://github.com/techpaul/ps2keyadvanced/blob/master/examples/advcodetest/advcodetest.ino"
    click LCDDemo "https://github.com/techpaul/ps2keyadvanced/blob/master/examples/KeyToLCD/KeyToLCD.ino"
    click LibraryMeta "https://github.com/techpaul/ps2keyadvanced/blob/master/library.properties"
    click MainDocs "https://github.com/techpaul/ps2keyadvanced/blob/master/README.md"
    click PortingNotes "https://github.com/techpaul/ps2keyadvanced/blob/master/extra/Porting.md"
    click ProtocolPDF "https://github.com/techpaul/ps2keyadvanced/blob/master/extra/PS2 Keyboard.pdf"
    click CodesList "https://github.com/techpaul/ps2keyadvanced/blob/master/extra/codes.txt"
    click ReadmeExtra "https://github.com/techpaul/ps2keyadvanced/blob/master/extra/readme.txt"
    click Websites "https://github.com/techpaul/ps2keyadvanced/blob/master/extra/websites.txt"

    %% Styles
    classDef hardware fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef driver fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef doc fill:#FFFACD,stroke:#333,stroke-width:1px;
```
