How kenyoshizoe/ember works
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.