日本語

The M5Stack factory firmware preinstalled on M5StackChan and the Stack-chan firmware in this repository are separate firmware implementations. Use the latest release when you need a stable environment. The default develop branch may change internal structures and APIs while preparing the next release.

AI Stack-chan is a separate Arduino-based application developed primarily by @robo8080. If you are looking for AI Stack-chan, see AI_StackChan2.

If you are comfortable with the Arduino IDE and use PWM servos, stack-chan-tester by @mongonta0716 is another option.

For a first trial, the Stack-chan browser tools let you start without installing a local development environment.

1. Connect M5StackChan to a computer with a data-capable USB cable.
2. Open the Web firmware installer in Chrome or Edge, select "M5StackChan CoreS3," and install the firmware.
3. Choose a MOD from the MOD Gallery and try it in the simulator or on the device.

The standard firmware target is M5StackChan CoreS3. To change the source code, run these commands from the firmware directory:

npm i
npm run setup
npm run setup -- --device=esp32
npm run doctor
npm run flash

npm run flash builds and flashes the standard host. For Stack-chan RT or Takao Core2 + SG90, use npm run flash:stackchan_rt or npm run flash:takao_core2_sg90. When updating only a MOD, pass its manifest: npm run mod -- mods/examples/look_around/manifest.json. The command builds a MOD archive, discovers the device's xs partition, and writes it directly with esptool. Because it does not use the xsbug install channel, the installed host can be either a debug or release build.

• Develop MODs in JavaScript or TypeScript.
• Update a MOD quickly without rebuilding the host because the host program and MODs are separate.
• Use capability-oriented context APIs for faces, motion, input, audio, camera, and connectivity.
• Run Stack-chan with multiple motor configurations, including Feetech, FUTABA, DYNAMIXEL, and PWM servos.
• Generate speech through Stack-chan Voice, VOICEVOX, ElevenLabs, or OpenAI.
• Access firmware installation, BLE preferences, the MOD Gallery, the block editor, the face editor, and the WebAssembly simulator from a browser.
• Use the firmware and Web UI in Japanese, English, or Simplified Chinese.

Use the repository npm scripts for firmware development. They manage the Moddable output directory and keep host, MOD, and test build artifacts under firmware/dist/:

• Programs are written under firmware/dist/bin/ and intermediate files under firmware/dist/tmp/.
• The host application name is stack-chan-host.
• npm run clean removes all generated files under firmware/dist/.
• Do not pass a custom -o or invoke mcconfig, mcrun, or mcpack directly when using the repository workflow.
• npm run bundle builds every release target under firmware/dist/ and stages validated target artifacts in firmware/dist/bundle-targets/. It writes the assembled directory and ZIP under firmware/host/app/.
• Use the named build:release:<target> scripts for individual release builds. CI uses the same scripts before bundle:package assembles their artifacts.

See Building and Writing Programs for target-specific commands and detailed output paths.

• host: Host application and firmware modules.
• mods: Source code of mods.
• scripts: Development scripts for builds, validation, tests, and speech generation.
• typings: TypeScript definitions that supplement some Moddable SDK modules and Stack-chan-specific APIs.
• dist/: Generated firmware programs and intermediate build files. Build scripts manage this directory, and Git ignores it.

• Browser tools
• Flash firmware from a browser
• Change preferences from a browser
• MOD Gallery

• Set up the development environment
• Build and flash programs
• API
• MODs
• Localization
• Mini apps (experimental, Japanese)
• v1.0.0 release notes