# rust-embedded-community/pc-keyboard architecture

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

- Interactive diagram: https://gitdiagram.com/rust-embedded-community/pc-keyboard
- Repository: https://github.com/rust-embedded-community/pc-keyboard

## Overview

##### Project Type and Purpose
- This is a Rust library (“crate”) providing a driver for PC keyboards.
- It supports multiple scancode sets (Set 1 for legacy PCs, Set 2 for PS/2, USB HID) and various keyboard layouts (QWERTY, AZERTY, Dvorak, etc.).
- Its public API revolves around a Keyboard struct that, given a ScancodeSet and Layout, turns raw bytes into KeyEvents.

##### File Structure
- Top-level:
– Cargo.toml, README.md, examples/, src/, .github/
- src directory:
– src/lib.rs
– src/scancodes/ (mod.rs, set1.rs, set2.rs, usbhid.rs)
– src/layouts/ (mod.rs plus one file per supported layout)
- examples/: sample usage demonstrating decoder, layout mapping, printing, scancode iteration.

##### README for Insights
- Confirms crate role: “simple driver for handling PC keyboards.”
- References documentation on docs.rs and points to src/lib.rs.

##### Main Components to Model
a. Input Sources
– Physical keyboard over PS/2 or USB
– In code: raw byte streams passed into the driver
b. Scancode Decoder Modules
– ScancodeSet1
– ScancodeSet2
– USBHID
c. Core Driver
– Keyboard struct (generic over ScancodeSet and Layout)
– decode() / process_byte() API that emits raw KeyCode events
d. Layout Mapper Modules
– Multiple layout files (us104, uk105, azerty, colemak, dvorak, etc.)
– map_keycode() → HostKeyEvent (with shifts, modifiers applied)
e. Output
– High-level KeyEvent / HostKeyEvent stream back to application
f. Examples (optional, for illustrating API usage)

##### Relationships and Data Flow
- Data flow is strictly unidirectional:
[ Input Source ]
│ raw bytes
▼
[ Scancode Decoder Module ]
│ intermediate KeyCode
▼
[ Keyboard Core Driver ]
│ KeyCode + state (modifiers)
▼
[ Layout Mapper Module ]
│ HostKeyEvent
▼
[ Application / Example Consumer ]
- Each Scancode decoder module implements a common trait (ScancodeSet) consumed by the Keyboard struct.
- Each Layout implements a Layout trait used by the Keyboard to map keycodes to characters or host events.

##### Architectural Patterns and Principles
- Modular separation of concerns: decoding vs. mapping vs. API surface.
- Generic/trait-based design: ScancodeSet and Layout traits enable easy extension.
- No global state: all state is owned by Keyboard instance.
- Examples folder demonstrates composition of modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Input
    Hardware["Physical Keyboard\n(PS/2 or USB)"]:::external

    %% Scancode Decoders Container
    subgraph "Scancode Decoders"
        direction TB
        SC_Trait["ScancodeSet Trait\n(interface)"]:::trait
        SC1["ScancodeSet1 Module"]:::decoder
        SC2["ScancodeSet2 Module"]:::decoder
        USBHID["USBHID Module"]:::decoder
    end

    %% Core Driver
    Keyboard["Keyboard<Set, Layout>\n(core driver)"]:::core

    %% Layouts Container
    subgraph "Layouts"
        direction TB
        L_Trait["Layout Trait\n(interface)"]:::trait
        US104["US104 Layout"]:::layout
        UK105["UK105 Layout"]:::layout
        AZERTY["AZERTY Layout"]:::layout
        COLEMAK["COLEMAK Layout"]:::layout
        DVORAK["Dvorak Layout"]:::layout
        DVORAKP["Dvorak Programmer Layout"]:::layout
        DE105["DE105 Layout"]:::layout
        FI_SE["FI/SE105 Layout"]:::layout
        JIS109["JIS109 Layout"]:::layout
        NO105["NO105 Layout"]:::layout
    end

    %% Application Consumers
    Application["Example Consumers\n(application)"]:::external

    %% Data Flow
    Hardware -->|"Raw Bytes"| SC1
    Hardware -->|"Raw Bytes"| SC2
    Hardware -->|"Raw Bytes"| USBHID
    SC1 -->|"KeyCode"| Keyboard
    SC2 -->|"KeyCode"| Keyboard
    USBHID -->|"KeyCode"| Keyboard
    Keyboard -->|"HostKeyEvent"| US104
    Keyboard -->|"HostKeyEvent"| UK105
    Keyboard -->|"HostKeyEvent"| AZERTY
    Keyboard -->|"HostKeyEvent"| COLEMAK
    Keyboard -->|"HostKeyEvent"| DVORAK
    Keyboard -->|"HostKeyEvent"| DVORAKP
    Keyboard -->|"HostKeyEvent"| DE105
    Keyboard -->|"HostKeyEvent"| FI_SE
    Keyboard -->|"HostKeyEvent"| JIS109
    Keyboard -->|"HostKeyEvent"| NO105
    Keyboard -->|"HostKeyEvent"| Application

    %% Trait Dependencies
    SC1 --> SC_Trait
    SC2 --> SC_Trait
    USBHID --> SC_Trait
    US104 --> L_Trait
    UK105 --> L_Trait
    AZERTY --> L_Trait
    COLEMAK --> L_Trait
    DVORAK --> L_Trait
    DVORAKP --> L_Trait
    DE105 --> L_Trait
    FI_SE --> L_Trait
    JIS109 --> L_Trait
    NO105 --> L_Trait
    Keyboard --> SC_Trait
    Keyboard --> L_Trait

    %% Click Events
    click SC1 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/scancodes/set1.rs"
    click SC2 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/scancodes/set2.rs"
    click USBHID "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/scancodes/usbhid.rs"
    click SC_Trait "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/scancodes/mod.rs"
    click Keyboard "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/lib.rs"
    click L_Trait "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/mod.rs"
    click US104 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/us104.rs"
    click UK105 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/uk105.rs"
    click AZERTY "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/azerty.rs"
    click COLEMAK "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/colemak.rs"
    click DVORAK "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/dvorak104.rs"
    click DVORAKP "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/dvorak_programmer104.rs"
    click DE105 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/de105.rs"
    click FI_SE "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/fi_se105.rs"
    click JIS109 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/jis109.rs"
    click NO105 "https://github.com/rust-embedded-community/pc-keyboard/blob/main/src/layouts/no105.rs"
    click Application "https://github.com/rust-embedded-community/pc-keyboard/tree/main/examples/"

    %% Styles
    classDef decoder fill:#cce5ff,stroke:#3385ff,stroke-width:1px
    classDef layout fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef core fill:#ffe5b4,stroke:#ff851b,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef trait fill:#e8d0ff,stroke:#a259ff,stroke-width:1px,endMarker:none, startMarker:none
```
