# openblink/openblink-demo-m5 architecture

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

- Interactive diagram: https://gitdiagram.com/openblink/openblink-demo-m5
- Repository: https://github.com/openblink/openblink-demo-m5

## Overview

##### Project Type and Purpose
- This project is an open source embedded demo that focuses on enabling wireless code updates ("Blink") on M5 hardware platforms, specifically targeting devices like the M5 StampS3.
- Its purpose is to allow developers to use a lightweight language (mruby) on embedded devices for tasks such as RGB LED control via a built-in API. The system supports rapid code reloads over Bluetooth LE, ensuring the microprocessor does not reset.

##### File Structure
- Top-level directories and key files:
- Source code is mainly in the “src” directory. This contains several subdirectories:
▪ api – Provides API functions (e.g., LED control, blink functionality).
▪ app – Contains application-level code, likely including example routines and higher-level logic (beginning with blink.c/h and init.c/h).
▪ drv – Contains drivers for hardware functionality such as Bluetooth LE (ble.c/h) and LED control, indicating direct communication with the hardware.
▪ lib – A couple of key libraries:
- “crc” – Likely utility functions for error checking.
- “mrubyc” – The port of mruby/c which is instrumental in interpreting Ruby scripts.
- “include” and “lib” directories also expose their own headers and library files that are integrated into the build.
- Other directories (e.g., “doc”, “test”, and “sample_rb”) provide documentation, testing frameworks, and sample Ruby code respectively.
- Build-related files include several CMakeLists.txt files, a platformio.ini, and sdkconfig files, which signal support for multiple hardware configurations and a flexible build system.

##### Key Components
a. Hardware Platform:
▪ M5 StampS3 (or similar variants as noted in the README).
▪ Actual device components such as the RGB LED and Bluetooth module.

b. Embedded Software Subsystems:
▪ Main Entrypoint:
- “src/main.c” and “src/main.h” which bootstraps the system.
▪ API Layer (src/api):
- Provides core functions like LED control (e.g., LED.set) and checking for a reload (Blink.req_reload?).
▪ App Layer (src/app):
- Contains sample or production application routines, which likely coordinate the blinking behavior with the API.
▪ Drivers (src/drv):
- BLE driver (files like ble.c/h) to manage the Bluetooth LE connection for wireless code updates.
- LED driver for direct control of hardware.
▪ mrubyc Runtime (src/lib/mrubyc):
- Integrates mruby/c, enabling execution of Ruby scripts on the device.
▪ Utility Libraries:
- E.g., the CRC library from “src/lib/crc” for error checking and other utilities (in “src/lib/fn.h”).
▪ M5U Module (src/m5u):
- Contains additional functions, graphics, touch, and sound interface routines – helpful for advanced hardware interactions on the M5 platform.

c. External Tools / Interfaces:
▪ Sample Ruby Code (sample_rb):
- Provides examples, like “mexicanhat.rb”, showing how Ruby can be used to interact with the API.
▪ Build and Configuration Files:
- CMakeLists.txt, platformio.ini, and sdkconfig files indicate the multi-target nature and various build configurations.

##### Relationships and Data Flows
- The main application (src/main.c) initializes and coordinates the operation of the device.
- The API layer acts as an intermediary, accessed by both the native C/C++ application and by the mruby runtime to execute user scripts.
- The mrubyc library allows the execution of Ruby code (such as the sample codes in src/rb and sample_rb) and provides the “Blink” functionality – enabling wireless code updates via Bluetooth.
- The BLE driver (src/drv/ble.c, ble_blink.c) facilitates seamless communication with external devices used for code updates and debugging.
- The LED driver works in tandem with the API to control the onboard RGB LED based on commands from the application or scripts.
- The m5u module suggests a tier of additional control (touch, display, audio) that can be visually or interactively managed, which might be optional based on project specifics.

##### Architectural Patterns and Design Principles
- Layered Architecture:
- A clear separation exists between the hardware drivers, the API layer, and the application layer.
- Modularity:
- The code is modularized (directories such as api, app, drv, and lib) so each component improves maintainability and scalability.
- Event and Callback Handling:
- The “Blink.req_reload?” pattern indicates event-based programming, ensuring the system can gracefully handle updates without resetting the hardware.
- Integration of Scripting via mruby:
- Embedding a scripting language (mruby/c) enables dynamic code execution and simplifies the development and debugging process for embedded systems.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Main Controller/Runtime (src/main)"]:::controller
    B["API Layer (src/api)"]:::api
    C["App Layer (src/app)"]:::app
    D["mrubyc Interpreter (src/lib/mrubyc)"]:::mrubyc
    E["BLE Driver (src/drv)"]:::driver
    F["LED Driver (src/drv)"]:::driver
    G["CRC Utility (src/lib/crc)"]:::utility
    H["M5U Module (src/m5u)"]:::m5u
    I["Sample Ruby Scripts (sample_rb & src/rb)"]:::sample
    J["Bluetooth Module"]:::hardware
    K["RGB LED"]:::hardware
    L["Build Tools & Config"]:::build

    A -->|"init"| B
    A -->|"init"| C
    A -->|"runs"| D
    A -->|"loads"| H
    A -->|"configured_by"| L

    B -->|"calls"| F
    B -->|"calls"| E
    B -->|"utilizes"| G

    C -->|"uses"| B

    D -->|"executes"| B

    I -->|"sends_scripts"| D

    E -->|"communicates_with"| J
    F -->|"controls"| K

    classDef controller fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef api fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef app fill:#FAD7A0,stroke:#D98880,stroke-width:2px;
    classDef mrubyc fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef driver fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef utility fill:#F7DC6F,stroke:#B7950B,stroke-width:2px;
    classDef m5u fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef sample fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef hardware fill:#F5CBA7,stroke:#BA4A00,stroke-width:2px;
    classDef build fill:#A3E4D7,stroke:#117864,stroke-width:2px;

    click A "https://github.com/openblink/openblink-demo-m5/blob/main/src/main.c"
    click B "https://github.com/openblink/openblink-demo-m5/tree/main/src/api"
    click C "https://github.com/openblink/openblink-demo-m5/tree/main/src/app"
    click D "https://github.com/openblink/openblink-demo-m5/tree/main/src/lib/mrubyc"
    click E "https://github.com/openblink/openblink-demo-m5/blob/main/src/drv/ble.c"
    click F "https://github.com/openblink/openblink-demo-m5/blob/main/src/drv/led.c"
    click G "https://github.com/openblink/openblink-demo-m5/tree/main/src/lib/crc"
    click H "https://github.com/openblink/openblink-demo-m5/tree/main/src/m5u"
    click I "https://github.com/openblink/openblink-demo-m5/blob/main/sample_rb/mexicanhat.rb"
```
