How openblink/openblink-demo-m5 works
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.