mruby-denko-esp32-build

Denko is a Ruby/mruby library for working with electronics. This repo contains the ESP-IDF project for building and flashing Xtensa-based ESP32 chips with firmware that runs mruby and Denko.

Installation

1. Install ESP-IDF (version 5.4.2 or higher):

   • Linux / Mac Instructions
   • Windows Instructions
   • VS Code Extension

   Note: If you used ./install.sh all when setting up the IDF, and are having issues compiling, try install again, but with your specific chip given. Eg. run ./install.sh esp32s3 inside the IDF install directory for the ESP32-S3.

2. Recursively clone this repo:

   git clone --recursive https://github.com/denko-rb/mruby-denko-esp32.git
   

3. Set the target to your chip with idf.py set-target <YOUR_CHIP>, where <YOUR_CHIP> is one of: esp32, esp32s2 or esp32s3.

4. These files are symlinked to the top directory for convenience, so you can customize your build:

   • main.rb : The mruby script that will run automatically when the microcontroller starts
   • mrbgem.rake : Adds high-level peripheral drivers from Denko to the build
   • esp32_build_config.rb : Adds low-level hardware drivers and mruby core gems to the build

   Note: The ESP32 has limited resources, so all drivers can't be included all the time. Disable peripheral drivers you don't need, or whole interfaces like I2C or SPI. Wi-Fi and MQTT can safely be disabled as well, but avoid the mruby core gems unless you really know what you're doing.

5. Buld with: idf.py build

6. Flash and monitor serial output with: idf.py flash monitor. Add -p <YOUR_SERIAL_DEVICE> if you need to specify.

7. Each time you edit main.rb, you must build and flash again. Subsequent builds are faster thanks to caching.

8. Run idf.py clean fullclean in the event you want to remove all build files and build from scratch again.

Examples

Here is the "Hello World" equivalent for microcontrollers. More examples here.

board = Denko::Board.new

# Blink built-in LED every half second.
led = LED.new(board: board, pin: 2)
loop do
  led.on
  sleep 0.5
  led.off
  sleep 0.5
end

Reminder: mruby code goes inmain/storage/main.rb.

Supported Hardware

Chip	Build Status	Board Tested	Notes
ESP32	💚	DOIT ESP32 DevKit V1
ESP32-S2	💚	LOLIN S2 Pico	Native USB
ESP32-S3	💚	LOLIN S3 V1.0.0	Native USB
ESP32-C3	❓	LOLIN C3 Mini V2.1.0	Native USB
ESP32-C2	❓	-
ESP32-C6	❓	-
ESP32-H2	❓	-

Build Environment

• ESP-IDF version 5.4.2
• mruby version 3.4.0, from this fork, where mruby-io and mruby-socket have been modified
• partitions.csv defines 4MB of flash, so it should fit any variant
  • Uses esp_littlefs version 1.20.0
  • App partition is 2816 kB
  • /storage is 1216 kB
• CPU speed set to 240 MHz for all Xtensa chips

Chip-Specific Notes

• For esp32 and esp32s3, the mruby task (main.rb) is pinned to Core 1, with its watchdog timer disabled. This means mruby code can stay in a tight loop indefinitely, without starving the RTOS of resources, as other tasks can run on Core 0.
• This is not the case for the esp32s2, which only has a single core. Kernel#sleep must be called periodically to avoid crashing.
• For the S2, Component Config -> ESP System Settings -> Channel for console output must be set to USB CDC in menuconfig for console output to appear on its native USB port. This is unlike the S3, which is also native USB, but works with the default UART0 setting.

Dependencies

Dependencies are automatically handled by mruby's build system. These links are for refrence:

• mruby-esp32-system
• mruby-denko-wifi-esp32
• mruby-denko-mqtt-esp32
• picoruby
• mruby-denko-esp32
• denko

Other Implementations

• The original CRuby gem runs on a PC, "remote controlling" a microcontroller connected via serial or TCP
• The Linux SBC extension allows the CRuby gem to use SBC GPIO headers
• The Milk-V mruby version runs on a tiny Linux SBC, with the same form-factor as a Raspberry Pi Pico