Family mruby

日本語

What is Family mruby

A development platform that enables mruby development and execution directly on microcontrollers. It features audio and graphics capabilities and is designed to run on the ESP32 series.

There are two hardware generations:

• Family mruby Retro — the NARYA board (two chips: ESP32-S3 + ESP32-WROVER). A retro-style setup that connects to a TV over NTSC video output
• Family mruby Modern — the ESP32-P4 variant. Currently runs standalone on the M5Stack Tab5, with a high-resolution touch screen (a dedicated board is under development)

For more details, please refer to the following blog post: Family mruby OS - FreeRTOS-based microRuby Multi-VM Architecture

Demo Video

Long version on YouTube

Documentation

family-mruby-doc

Comprehensive documentation including usage instructions and design information for Family mruby.

https://family-mruby.github.io

Quick Way to Try It Out

In a Browser, with Nothing Installed

The whole machine -- the FreeRTOS kernel, the Ruby VM, the desktop, the editor and the sound chip -- compiled to WebAssembly. Open the page and click the screen to switch it on; the click is also what lets the browser make sound.

https://family-mruby.github.io/studio/

It is the same firmware the boards run, so the apps, the editor and Japanese input behave as they do on hardware. What you save stays in your browser and can be carried out as one file. Desktop Chrome or Firefox, and a keyboard.

Flash Real Hardware from the Web Installer

If you have the hardware (a NARYA board or an M5Stack Tab5), you can flash the firmware from your browser alone:

https://family-mruby.github.io/family-mruby-installer/

It uses WebSerial, so a desktop Chrome / Edge / Opera browser is required.

Try with Docker VNC Desktop

You can try Family mruby OS without any hardware or build environment. A pre-built Docker image includes all binaries and is provided as a VNC desktop.

docker run --rm -p 6080:6080 ghcr.io/family-mruby/fmruby-desktop:latest

Open http://localhost:6080/vnc.html in your browser. The Family mruby OS desktop will appear in the VNC viewer.

Tested on Linux and Windows (WSL2). No VNC client is required -- everything runs in the browser via noVNC. An ARM64 image is also available, so it should work on Mac as well, though this has not been verified.

Note: Audio is not supported in the VNC environment.

Project Components

fmruby-core

Firmware that provides the core functionality of Family mruby. It includes the Family mruby OS runtime environment, abstraction layer, and system resource management features. It targets both Retro (ESP32-S3) and Modern (ESP32-P4), and can also run on Linux for debugging purposes.

GitHub Repository

fmruby-graphics-audio

Firmware for the Retro (NARYA board) sub-microcontroller (ESP32-WROVER). It handles NTSC video output and I2S audio output. Modern is a single-chip configuration and does not use this firmware.

GitHub Repository

narya-board

The circuit board used as the development and execution environment for Family mruby Retro. Contains KiCAD design data. Modern runs on the off-the-shelf M5Stack Tab5.

GitHub Repository

Development

Prerequisites (Ubuntu / Debian)

Install the packages you need based on what you plan to run:

# Base tools (required for rake fetch / build:linux / build:esp32)
sudo apt install git ruby-rake ruby-dev build-essential curl

# The firmware itself is compiled inside the ESP-IDF container, so Docker is
# required for every build. See https://docs.docker.com/engine/install/
sudo apt install docker.io   # or Docker Engine / Docker Desktop

# Generating the editor's type database is a host-side step of the build
gem install rbs

# For rake build:tools (fmrb-audio-tools)
sudo apt install cmake pkg-config libsdl2-dev

The firmware build is not entirely containerized: parts of the system are Ruby compiled ahead of time to C by the Spinel compiler, which runs on the host. The first build fetches and builds that compiler automatically -- hence build-essential and curl -- and gem install rbs covers the other host-side step, the type database behind the editor's completion and hover. See fmruby-core/README.md for the details and for how to rebuild the compiler when its pin moves.

Setup

First time only, fetch the repositories listed in .repos (fmruby-core, fmruby-graphics-audio and fmrb-audio-tools):

rake fetch

Building

For Retro, build both fmruby-core (ESP32-S3) and fmruby-graphics-audio (ESP32):

rake build:esp32

For Modern (M5Stack Tab5), build fmruby-core only (single-chip configuration, fmruby-graphics-audio is not needed). The target is selected either on the command line or by editing FMRB_HW_TARGET in fmruby-core/.env; the command line wins:

cd fmruby-core
FMRB_HW_TARGET=TAB5 rake build:esp32      # M5Stack Tab5
FMRB_HW_TARGET=NARYAv4 rake build:esp32   # NARYA v4 prototype (ESP32-P4-Nano + LT8912B HDMI)

Tab5 and NARYA v4 are both ESP32-P4, but their binaries are not interchangeable: they pin different chip revisions.

Switching the target changes the chip, so run rake clean_all first when the previous build was for the other one.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗