Stack-chan: A JavaScript-Driven Robot on M5Stack Hardware

What Stack-chan solves, and for whom

Stack-chan is a robot project where the application layer is JavaScript rather than C++. The README describes it as "an open-source, JavaScript-driven, super-kawaii robot built with M5Stack." That single design decision shapes everything else: the repository ships a firmware image, a set of user applications the project calls MODs, browser development tools, cases and schematics.

The intended audience is split in two. The first group is people who want a working desktop robot without a toolchain. The getting started path says to buy a preassembled M5StackChan, flash it from a browser page, and pick a MOD from the gallery. The README states plainly that you do not need to install the Moddable SDK or ESP-IDF for that route. The second group is people who want to modify the thing: the repository contains firmware sources, a block editor, a face editor, a simulator, 3D-printable case models and schematics. Both groups are served by the same repository, which is unusual and also the source of most of its complexity.

The MOD model and how a Stack-chan application runs

The unit of application code is the MOD. The README lists MODs alongside the firmware and browser tools as one of the things the repository provides, and points to firmware/mods/README.md for MOD development. Published MODs and mini apps live in the MOD Gallery, and the README notes that block-based samples can be opened directly in the block editor and changed.

There are two execution targets. On hardware, the firmware runs the MOD on the device. In the browser, the simulator runs MODs against a WebAssembly build of the firmware plus a 3D model, so you can watch behaviour change without flashing anything. The block editor and the simulator are connected: a MOD you assemble with Blockly can be run in the simulator or installed on a device. Firmware API documentation lives at firmware/docs/api.md, which matters because a MOD is only as capable as the API surface exposed to it.

Two supporting tools sit around this loop. Preferences are changed over BLE through a browser page, which is how Wi-Fi and device settings get set without a serial console. MediaPipe BLE tracking sends tracked face and hand movement over BLE, so a host machine can drive the robot's reactions. The firmware itself is written in TypeScript, which is the repository's primary language.

Flashing firmware and running a first MOD

The documented path assumes a preassembled M5StackChan and a desktop browser. Connect the device with a data-capable USB cable, then open the Web firmware installer in Chrome or Edge and select M5StackChan CoreS3 as the device. The README states that this replaces the factory firmware supplied by M5Stack, and that restoring it means following the restore procedure in the M5Stack product documentation with M5Burner. That warning is worth reading before you start, not after.

The getting started flow is browser-driven, so the repository gives no shell command for it. The only configuration you supply is the device selection in the installer page:

# Web firmware installer
https://stack-chan.github.io/stack-chan/web/flash/

# device to select
M5StackChan CoreS3

Once firmware is on the device, the MOD Gallery is the next stop. The README describes choosing a MOD and then running it in the simulator or installing it on a device:

# MOD Gallery
https://stack-chan.github.io/stack-chan/web/mod-gallery/

For a first real use, opening a block-based sample in the block editor and watching it in the simulator is the lowest-risk way to understand the MOD lifecycle before you install anything on hardware:

# Block editor
https://stack-chan.github.io/stack-chan/web/editor/

If you are building firmware from source rather than flashing the distributed image, the README directs you to firmware/README.md for target-specific commands and constraints. That is where the M5Stack, Core2, CoreS3 and M5StackChan CoreS3 targets are covered.

Where Stack-chan is the wrong tool

The supported hardware list is narrow. The distributed firmware supports M5Stack, M5Stack Core2, M5Stack CoreS3 and M5StackChan CoreS3. The README says M5StackChan CoreS3 is the standard configuration and the target used for physical-device release validation. Firmware for Stack-chan RT and Takao Core2 + SG90 can be built from source, but the README frames that as a separate exercise with its own target-specific commands and constraints rather than a supported default.

That means if you already own an ESP32 board that is not on the list, the browser installer is not the path for you. You are in source-build territory, and the README does not promise release validation there.

The second limitation is the flashing model. The installer overwrites factory firmware. The README does not document a rollback inside this repository; it points at M5Stack's product documentation and M5Burner for restoring the original image. If you need to keep the factory behaviour intact, plan that restore route before flashing. A project that ships an irreversible-in-repo flashing step should be treated as a device you dedicate, not one you experiment with casually.

Finally, this is a robot with a specific form factor and a specific set of peripherals. If you want a general programmable platform, the case models and schematics are useful, but the firmware is tuned to the M5StackChan configuration and the release validation follows it.

Stack-chan compared with Moddable-only firmware work

The obvious alternative is to work with the Moddable SDK directly on an ESP32 board and write your own application layer, skipping the Stack-chan firmware and its MOD conventions. The difference is in what you inherit. With Stack-chan you get a defined MOD interface, a gallery of existing applications, a browser simulator backed by a WebAssembly build of the firmware, a block editor, and a face editor for arranging eyes and a mouth. With a bare Moddable setup you get the JavaScript runtime and the freedom to design everything above it yourself, including how a user installs an application.

That trade is real in both directions. Stack-chan's MOD model constrains how applications are packaged and what the firmware exposes through firmware/docs/api.md. In exchange, a MOD can be tried in a simulator and installed from a gallery without you writing any of that infrastructure. If your goal is to learn the runtime, the bare route is shorter. If your goal is a robot that other people can add applications to, the MOD conventions are doing work you would otherwise have to build.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-12. Release history shows v1.0.0rc in October 2023, then a long gap before v1.0.0 on 2026-07-21 and v1.1.0 on 2026-08-25. That gap is the most useful signal about upgrade cost: the project sat on a release candidate for roughly two and a half years and then shipped two numbered releases within about five weeks. If you adopted during the rc period, the jump to 1.x is the migration to plan for, and the release notes in docs/ are where that would be described.

The repository also carries a .changeset/ directory, which is the conventional mechanism for recording pending version bumps and changelog entries. Combined with the recent release cadence, the practical upgrade cost for MOD authors is tracking the firmware API document rather than reading the firmware sources.

Licensing is straightforward on paper: the README states that the resources in this repository are distributed under the Apache License 2.0, with the text in LICENSE. Apache-2.0 covers the firmware, the web tools, the case models and the schematics as repository resources. Note that the hardware is bought from M5Stack, not from this project, and the README links to M5Stack's own product pages and documentation for the device and its factory firmware. This is not legal advice; if you plan to redistribute a modified firmware image or a printed case commercially, read LICENSE and the contribution guide yourself.

Editorial conclusion

Adopt Stack-chan if you want a small M5Stack robot whose behaviour you can write in JavaScript and iterate on in a browser simulator before touching hardware. Skip it if you need a general purpose robotics platform or a supported path for boards outside the documented list, since the distributed firmware targets M5Stack, M5Stack Core2, M5Stack CoreS3 and M5StackChan CoreS3, and RT or Takao Core2 + SG90 builds come from source. Before buying, confirm the M5StackChan AI Desktop Robot (K151) package matches the standard configuration, and check the firmware guide for the target-specific commands you will need.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. stack-chan/stack-chan on GitHub