Project files

Environment Setup

English

Requirements for development

• Host PC (Windows, Mac, or Linux)
  • Tested in the following environment
    • Linux (Ubuntu 24.04)
• M5Stack (Basic, Core2, or CoreS3)
• USB Type-C cable
• git (opens in a new tab)
• Node.js (opens in a new tab)
  • Tested with v22

ｽﾀｯｸﾁｬﾝリポジトリのクローン

Clone this repository.

$ git clone https://github.com/stack-chan/stack-chan.git
$ cd stack-chan/firmware
$ npm i

Setting Up the ModdableSDK

On your host PC, install the ModdableSDK (opens in a new tab) and ESP-IDF (opens in a new tab). There are three ways to do this.

• Use the CLI (recommended)
• Use a Docker image
• Set up manually

Using xs-dev (recommended)

Stack-chan provides npm scripts for the setup steps. Run the following command in the stack-chan/firmware directory.

$ npm run setup
$ npm run setup -- --device=esp32

Internally, it uses xs-dev (opens in a new tab) to automate the setup of the ModdableSDK and ESP-IDF.

Using the Docker Image (Linux Only)

This repository provides a build environment defined by a Dockerfile. You can build and flash the firmware and debug it inside a Docker container.

Note: Operation has been verified on Linux (Ubuntu 24.04). Because issues (opens in a new tab) have been reported where connecting to the device from inside the container does not work on Windows (WSL) or macOS, those platforms are not recommended.

From the terminal

Run the following command in the stack-chan/firmware directory:

$ ./docker/build-container.sh
$ ./docker/launch-container.sh

# コンテナ内で以下を実行
$ npm install

From VSCode

We include DevContainer configuration for VSCode. You can open the project inside the container with the following steps.

• Open the command palette (ctrl+shift+p)
• Run >Remote-Containers: Reopen in Container

Manual setup

Install the ModdableSDK and ESP-IDF by following the official site instructions (in English) (opens in a new tab). If the CLI or Docker does not set up correctly, use this approach instead.

(Optional) Updating the Moddable SDK

Updates to this repository may require an update to the Moddable SDK to add features or resolve bugs.

Using xs-dev (recommended)

Stack-chan also provides its update procedure as npm scripts. Run the following command in the stack-chan/firmware directory.

$ npm run update
$ npm run update -- --device=esp32

Manual process

Update the ModdableSDK and ESP-IDF by following the official site instructions (in English) (opens in a new tab).

Testing the Environment

You can test your environment with the npm run doctor command. If the installation succeeded, it displays the Moddable SDK version as shown below, and esp32 appears under Supported target devices.

$ npm run doctor

> stack-chan@1.0.0 doctor
> xs-dev doctor

xs-dev environment info:
  CLI Version                0.32.7                                                                 
  OS                         Linux                                                                  
  Arch                       x64                                                                    
  Shell                      /bin/bash                                                              
  NodeJS Version             v22.9.0 (/home/sskw/.nvm/versions/node/v22.9.0/bin/node)               
  Python Version             3.12.3 (/home/sskw/.espressif/python_env/idf5.3_py3.12_env/bin/python) 
  Moddable SDK Version       5.3.3 (/home/sskw/.local/share/moddable)                               
  Supported target devices   lin, esp32                                                             
  ESP32 IDF Directory        /home/sskw/.local/share/esp32/esp-idf 

If this is related to an error when using the CLI, please create an issue at "https://github.com/hipsterbrown/xs-dev/issues/new" with the above info.

Next steps

• Building and flashing the program