# kenyoshizoe/ember architecture

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

- Interactive diagram: https://gitdiagram.com/kenyoshizoe/ember
- Repository: https://github.com/kenyoshizoe/ember

## Overview

##### Main Components
- Hardware Platform:
- STM32F3 microcontroller and its associated peripherals (ADC, DMA, GPIO, I2C, USB, TIM, etc.).
- PCB design which consists of separate boards/files for the top plate, bottom plate, and the main board. These are available in the “pcb” directory.
- Firmware:
- Core layer: Contains startup code (startup_stm32f303xc.s), main application logic (main.c in Core/Src), and configuration and initialization code.
- Drivers: Provided by CMSIS and STM32F3xx_HAL_Driver directories. These wrap the low-level hardware interactions.
- USB Device Stack: The USB_DEVICE directory (with App and Target subdirectories) and dependency on the tinyusb library show that the keyboard operates as a composite USB device (HID & CDC).
- Application Modules:
- Keyboard module: Files under ember/include/ember/keyboard and ember/src/keyboard.
- Communication module: Handles the sending/receiving of configuration data over USB with COBS encoding, as described in the README. The related code can be found in ember/include/ember/commnication and ember/src/communication.
- Module support: Example modules for flash and key multiplexing (see ember/module).
- Utilities such as COBS encoding (under ember/include/ember/utils).
- External Scripts / Tools:
- Python scripts in the script directory are used for calibration, serial communication, key setting configuration, and DFU operations.
- Build and Development Infrastructure:
- Makefile exists, as do IDE project files (e.g., .ioc, .mxproject, .vscode folder). These indicate the use of either a vendor-specific IDE (Keil or similar) or generic toolchain.

##### Relationships and Interactions
- The Hardware Layer (PCB components, sensors, and the microcontroller) provides electrical interfaces to handle key sensing (Hall effect sensors) and USB connectivity.
- The Firmware’s Core Layer initializes the hardware using drivers (CMSIS and HAL) and sets up the USB composite device.
- The USB Device Stack handles enumeration and communication with the host computer, exposing the keyboard as both HID (for key reports) and CDC (for configuration).
- The Application Layer processes incoming USB CDC messages. It uses a packet structure (detailed in the README) to perform configuration read/writes and calibration. COBS is used for framing the query/response packets.
- External Python scripts communicate with the CDC interface to send configuration or calibration commands.
- The PCB design component (KiCAD-generated files) is largely independent but must match the firmware’s hardware expectations (e.g., pin assignments, USB connector layout).

##### Architectural Patterns and Design Principles
- Layered Architecture: A clear separation exists between the hardware abstraction (drivers), application logic (key handling, communication, calibration), and peripheral interfacing (USB stack).
- Modularity: Individual modules (keyboard, communication, utilities) are maintained in separate directories that encourage reusability and ease of testing.
- Encapsulation: Hardware-specific code is abstracted behind well-defined interfaces (CMSIS/HAL drivers), making it easier to manage changes.
- Composite USB Device Implementation: The firmware supports multiple interfaces (HID and CDC) on a single device which is central to user configuration.
- Data Encoding: The use of COBS for encoding/decoding of USB communication highlights attention to robust communication protocols.

##### Technologies, Frameworks, and Libraries
- Microcontroller firmware framework based on STM32Cube/HAL along with CMSIS for ARM-based MCUs.
- TinyUSB library integrated for handling USB device functionality.
- SEGGER_RTT library for real-time terminal output and debugging support.
- KiCAD 7 for PCB design (electronic schematic and layout).
- Python (scripts/calibration.py, etc.) for external device configuration and testing.

##### Additional Elements to Capture
- Build infrastructure (Makefile, IDE configurations) as a smaller inset to note the development and compilation process.
- Optionally mention the debugging pathway via SEGGER_RTT, which aids in monitoring the firmware’s operation.
- Configuration packet structures (Query/Response packets with addresses) as an annotation in or beside the communication module.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Tools
    subgraph "External Tools"
        E1["External PC (Host)"]:::external
        E2["Python Scripts"]:::external
    end

    %% Firmware Layer
    subgraph "Firmware"
        %% Core Layer
        subgraph "Core Layer"
            F1["Startup Code"]:::firmware
            F2["Main Application Logic"]:::firmware
            F3["Configuration Code"]:::firmware
        end

        %% Drivers
        subgraph "Drivers"
            F4["CMSIS Drivers"]:::firmware
            F5["STM32F3xx HAL Drivers"]:::firmware
        end

        %% USB Device Stack
        subgraph "USB Device Stack"
            F6["USB Device Implementation"]:::firmware
        end

        %% Application Modules
        subgraph "Application Modules"
            %% Keyboard Module
            K1["Keyboard Module Headers"]:::firmware
            K2["Keyboard Module Implementation"]:::firmware
            %% Communication Module
            C1["Communication Module Headers"]:::firmware
            C2["Communication Module Implementation"]:::firmware
            %% Module Support
            M1["Module Support Headers"]:::firmware
            M2["Module Support Implementation"]:::firmware
            %% Utilities
            U1["COBS Encoding"]:::firmware
        end
    end

    %% Hardware Platform
    subgraph "Hardware Platform"
        H1["Microcontroller (STM32F303CBTx)\n(ADC, DMA, GPIO, I2C, USB, TIM)"]:::hardware
        H2["PCB - Main Board"]:::hardware
        H3["PCB - Top Plate"]:::hardware
        H4["PCB - Bottom Plate"]:::hardware
    end

    %% Build and Development Infrastructure
    subgraph "Build Infrastructure"
        B1["Makefile"]:::build
        B2["IDE Project (.mxproject)"]:::build
        B3["VSCode Config (.vscode)"]:::build
        B4["iOC File"]:::build
    end

    %% Connections from External Tools to Firmware USB Device Stack
    E1 -->|"USB_Commands"| F6
    E2 -->|"USB_Commands"| F6

    %% Firmware Core relationships
    F1 -->|"initializes"| F2
    F1 -->|"configures"| F3
    F1 -->|"loads"| F4
    F1 -->|"loads"| F5
    F2 -->|"controls"| F6

    %% USB Device flows into Application Modules
    F6 -->|"routes config_data"| C2
    C2 -->|"uses_encoding"| U1
    C2 -->|"updates"| K2

    %% Module Support supporting Keyboard Module
    M1 -->|"defines"| M2
    M2 -->|"supports"| K2

    %% Firmware to Hardware
    F2 -->|"drives"| H1

    %% Microcontroller communicates with PCB parts
    H1 -->|"interfaces"| H2
    H1 -->|"interfaces"| H3
    H1 -->|"interfaces"| H4

    %% Build Infrastructure connects to Firmware development
    B1 ---|"builds"| F1
    B2 ---|"configures"| F1
    B3 ---|"configures"| F1
    B4 ---|"configures"| F1

    %% Click Events for Component Mapping
    click H2 "https://github.com/kenyoshizoe/ember/tree/main/pcb/ember"
    click H3 "https://github.com/kenyoshizoe/ember/tree/main/pcb/ember_top_plate"
    click H4 "https://github.com/kenyoshizoe/ember/tree/main/pcb/ember_bottom_plate"

    click F1 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/startup_stm32f303xc.s"
    click F2 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/Core/Src/main.c"
    click F3 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/Core/Inc/stm32f3xx_hal_conf.h"

    click F4 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/Drivers/CMSIS"
    click F5 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/Drivers/STM32F3xx_HAL_Driver"

    click F6 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/USB_DEVICE"

    click K1 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/include/ember/keyboard"
    click K2 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/src/keyboard"

    click C1 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/include/ember/commnication"
    click C2 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/src/communication"

    click M1 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/include/ember/module"
    click M2 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/src/module"

    click U1 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/include/ember/utils/cobs.h"

    click E2 "https://github.com/kenyoshizoe/ember/tree/main/script"

    click B1 "https://github.com/kenyoshizoe/ember/tree/main/firmware/ember/Makefile"
    click B2 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/.mxproject"
    click B3 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/.vscode"
    click B4 "https://github.com/kenyoshizoe/ember/blob/main/firmware/ember/ember.ioc"

    %% Styles
    classDef external fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef firmware fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef hardware fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef build fill:#ffffcc,stroke:#666600,stroke-width:2px;
```
