How techpaul/ps2keyadvanced works
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.