# trustcrypto/onlykey-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/trustcrypto/onlykey-firmware
- Repository: https://github.com/trustcrypto/onlykey-firmware

## Overview

##### Project Type and Purpose
- Type: Embedded firmware for a USB security token (OnlyKey).
- Purpose: Implements USB HID (keyboard + raw HID) interfaces, handles cryptographic operations, and maps user inputs to secure key outputs.

##### File Structure
Top-level items:
- OnlyKey/OnlyKey.ino         → Main Arduino-style entry point
- usb_dev.c / usb_dev.h        → USB device initialization & core HAL
- usb_desc.c / usb_desc.h      → USB descriptors (HID, configuration, device IDs)
- usb_keyboard.c               → USB Keyboard HID class implementation
- usb_rawhid.c / usb_rawhid.h  → Raw HID class for custom commands
- keylayouts.c / keylayouts.h  → Scancode maps for different keyboard layouts
- Libraries (external, not in tree): MBED TLS, micro-ECC, Yubico-C, ArduinoLibs crypto

##### Extract Architectural Insights from README
- Cryptographic libraries are linked statically into firmware.
- Firmware features are modular and added per release.
- Communication with host over standard USB HID and custom Raw HID protocols.

##### Main Components
a. Hardware & Host
- USB Host (PC, OS HID driver)
- OnlyKey hardware (MCU, Flash, Crypto co-processor if used)
b. Firmware Layers
1. Hardware Abstraction Layer (usb_dev)
2. USB Descriptor Layer (usb_desc)
3. USB Class Drivers
– HID Keyboard (usb_keyboard)
– HID Raw (usb_rawhid)
4. Application Layer
– Keylayout Manager (keylayouts)
– Crypto Engine (MBED TLS, micro-ECC, Yubico-C via ArduinoLibs)
– Command Dispatcher (parses Raw HID commands, invokes crypto or keystroke routines)
5. Main Loop (OnlyKey.ino) – initialization, event loop, power management

##### Relationships and Data Flows
- On Startup: OnlyKey.ino → initialize usb_dev → usb_desc registers descriptors → register USB class handlers
- Host sends HID requests → usb_dev ISR → usb_rawhid or usb_keyboard dispatch
- Raw HID commands → Command Dispatcher → Crypto Engine → Response via usb_rawhid
- Key press simulation → Keylayout Manager → usb_keyboard → host

##### Architectural Patterns & Principles
- Layered design (HAL → USB stack → class drivers → application)
- Modular separation (separate modules for descriptors, class drivers, layouts, crypto)
- Event-driven model (USB interrupts → dispatch handlers)
- Resource constraints (small footprint, static linking of crypto libraries)

##### Technologies, Frameworks, Libraries
- Language: C/C++ (Arduino)
- Build: Arduino IDE or makefile utilizing avr-gcc
- Crypto: MBED TLS, micro-ECC, Yubico-C, ArduinoLibs
- USB: Native USB support via usb_dev, descriptors, HID drivers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Host & Hardware"
        HOST["USB Host (PC)"]:::external
        HW["OnlyKey Hardware (MCU, Flash)"]:::external
    end

    %% Main Loop
    MAIN["OnlyKey.ino (Main Loop)"]:::app
    click MAIN "https://github.com/trustcrypto/onlykey-firmware/blob/master/OnlyKey/OnlyKey.ino"

    %% HAL Layer
    subgraph "Hardware Abstraction Layer"
        USBDEV["usb_dev.c/.h"]:::hal
    end
    click USBDEV "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_dev.c"
    click USBDEV "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_dev.h"

    %% USB Descriptor Layer
    subgraph "USB Descriptor Layer"
        USBDESC["usb_desc.c/.h"]:::usbstack
    end
    click USBDESC "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_desc.c"
    click USBDESC "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_desc.h"

    %% USB Class Drivers
    subgraph "USB Class Drivers"
        KEYBD["usb_keyboard.c"]:::usbstack
        RAWHID["usb_rawhid.c/.h"]:::usbstack
    end
    click KEYBD "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_keyboard.c"
    click RAWHID "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_rawhid.c"
    click RAWHID "https://github.com/trustcrypto/onlykey-firmware/blob/master/usb_rawhid.h"

    %% Application Layer
    subgraph "Application Layer"
        CMD["Command Dispatcher"]:::app
        KEYLAY["keylayouts.c/.h"]:::app
        CRYPTO["Crypto Engine"]:::crypto
    end
    click KEYLAY "https://github.com/trustcrypto/onlykey-firmware/blob/master/keylayouts.c"
    click KEYLAY "https://github.com/trustcrypto/onlykey-firmware/blob/master/keylayouts.h"

    %% Flows
    HOST -->|"USB D+/D-"| USBDEV
    HW -->|"MCU Init"| USBDEV
    MAIN -->|"init()"| USBDEV
    USBDEV -->|"registerDescriptors()"| USBDESC
    USBDESC -->|"setupClasses()"| KEYBD
    USBDESC -->|"setupClasses()"| RAWHID

    HOST -->|"HID Keystroke"| KEYBD
    KEYLAY -->|"map scancode"| KEYBD
    RAWHID -->|"parse command"| CMD
    CMD -->|"invoke crypto"| CRYPTO
    CRYPTO -->|"response"| RAWHID
    CMD -->|"trigger keystroke"| KEYBD

    %% Styling
    classDef external fill:#DDDDDD,stroke:#888,stroke-width:1px
    classDef hal fill:#B3E5FC,stroke:#0288D1,stroke-width:2px
    classDef usbstack fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
    classDef app fill:#FFE0B2,stroke:#EF6C00,stroke-width:2px
    classDef crypto fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px
```
