# t-vk/esp32-ble-keyboard architecture

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

- Interactive diagram: https://gitdiagram.com/t-vk/esp32-ble-keyboard
- Repository: https://github.com/t-vk/esp32-ble-keyboard

## Overview

This project is a single-purpose Arduino-compatible library that transforms an ESP32 device into a Bluetooth LE keyboard. Its main function is to enable key emulation over BLE, allowing the ESP32 to send keystrokes, text, and media key commands to a host device. The design is focused entirely on implementing and exposing the BLE keyboard interface, with optional support for NimBLE (a lighter BLE stack).

##### Main components
- BleKeyboard Core Module: Represented by BleKeyboard.cpp and BleKeyboard.h. This is the heart of the library, handling BLE initialization, connection management, and key event generation.
- Arduino Sketch / Example Application: Represent the example “SendKeyStrokes.ino” as a client that calls the library’s API. This shows how an end user or application utilizes the BleKeyboard library.
- Configuration/Metadata: A small module representing configuration and metadata files (library.properties and keywords.txt) which are used by the Arduino IDE to recognize, install, and provide code hints for the library.

##### Relationships and interactions
- The Example Application uses the BleKeyboard API (calls begin(), write(), print(), etc.) to send keystroke data.
- The BleKeyboard Core communicates with the BLE/NimBLE Stack component to set up advertising, manage connections, and send Bluetooth data packets.
- There is a clear flow from the application (user’s sketch) to the core library, and from there to the BLE stack which finally communicates with the paired host (Android, Windows, Linux, etc.).

##### Important architectural patterns and design principles
- Modularity: The core library abstracts BLE keyboard functionality into well-defined methods, making it easy to maintain and extend.
- Conditional Compilation: The use of preprocessor directives (e.g., #define USE_NIMBLE) to toggle between BLE stacks demonstrates a flexibility design pattern tailored for resource management.
- Abstraction: The interface mirrors the standard USB keyboard interface available in Arduino, adhering to familiar patterns for ease-of-use.

##### Relevant technologies and frameworks
- The ESP32 platform with its specific BLE capabilities.
- Arduino IDE as the development environment.
- BLE and optionally NimBLE libraries that handle the low-level Bluetooth interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Application Layer"
        A["Example Application"]:::example
    end

    subgraph "Library Layer"
        B["BleKeyboard Library"]:::library
        subgraph "Configuration/Metadata"
            F["library.properties"]:::config
            G["keywords.txt"]:::config
        end
    end

    subgraph "BLE Module"
        D["BLE/NimBLE Stack"]:::ble
    end

    subgraph "External Device"
        E["Remote Host (PC/Mobile)"]:::external
    end

    A -->|"calls"| B
    B -->|"configured_by"| F
    B -->|"configured_by"| G
    B -->|"communicates_with"| D
    D -->|"transmits_keystrokes_to"| E

    click A "https://github.com/t-vk/esp32-ble-keyboard/blob/master/examples/SendKeyStrokes/SendKeyStrokes.ino"
    click B "https://github.com/t-vk/esp32-ble-keyboard/blob/master/BleKeyboard.cpp"
    click B "https://github.com/t-vk/esp32-ble-keyboard/blob/master/BleKeyboard.h"
    click F "https://github.com/t-vk/esp32-ble-keyboard/blob/master/library.properties"
    click G "https://github.com/t-vk/esp32-ble-keyboard/blob/master/keywords.txt"

    classDef example fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef library fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef config fill:#ffc0cb,stroke:#333,stroke-width:2px;
    classDef ble fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
