ｽﾀｯｸﾁｬﾝのファームウェアは、ｽﾀｯｸﾁｬﾝの基本動作を提供するプログラム（ホスト）とユーザアプリケーション（MOD）から構成されます。 一度ホストを書き込んでしまえば、ユーザアプリケーションのインストールは短時間で終わるため高速な開発が可能です。 最初にホストを書き込み、必要に応じて MOD の書き込みを行います。
ホストと MOD はそれぞれ、設定用のマニフェストファイル（manifest.json）、JavaScript モジュールのソースコード、画像や音声などのリソースから構成されます。 マニフェストファイルでは、JavaScript モジュールの名前と場所（modules）や、モジュール内から参照できる設定（config）などを含みます。 また、マニフェストファイルは他のマニフェストファイルを含める（include）こともできます。
全ての設定項目はModdable の公式ドキュメント（英語）を参照してください。
ｽﾀｯｸﾁｬﾝが使うモータの種類やピンアサインなどをマニフェストファイルから変更できます。
ユーザが変更する設定はstack-chan/firmware/stackchan/manifest_local.jsonにまとまっています。
"config"キーの配下に次のような設定が書けます。
| キー | 説明 | 使用可能な値 |
|---|---|---|
| driver.type | モータドライバの種類 | "dynamixel" |
| driver.panId | パン軸（首の横回転）に使うシリアルサーボの ID | 1~254 |
| driver.tiltId | チルト軸（首の縦回転）に使うシリアルサーボの ID | 1~254 |
| tts.type | TTS の種類 | "local", "voicevox" |
| tts.host | TTS がサーバと通信する場合のホスト名 | "localhost", "ttsserver.local" などの文字列 |
| tts.port | TTS がサーバと通信する場合のポート番号 | 1~65535 |
また、"include"キーの配下にリスト形式で他のマニフェストファイルのパスを指定できます。
前述の通りｽﾀｯｸﾁｬﾝのファームウェアは基本プログラム（ホスト）とユーザアプリケーション（MOD）から構成されます。
esp-idfのバージョンが5.xからesp32に接続しているPSRAMの扱いが変わっています。デフォルト設定ではスムーズに動かないため一部変更しています。
環境構築の設定変更スクリプト実行時に、~/.local/share/moddable/build/devices/esp32/targets/m5stack_cores3/sdkconfig/sdkconfig.defaultsに記述されたCONFIG_SPIRAM=yをCONFIG_SPIRAM=nに書き換えています。
次のコマンドで基本プログラム（ホスト）の書き込みを行います。
コマンドにsudoをつける必要はありません。
$ cd ~/stack-chan/firmware
$ npm run build --target=esp32/m5stack_cores3
$ npm run deploy --target=esp32/m5stack_cores3Ubuntuの場合、書き込みポートがReadOnlyになっています。sudo chmod 666 /dev/ttyACM0でモードを書き換えるが、永続的にUSBポートの使用権限を変更する場合は、次のコマンドを実行してPCを再起動します。
$sudo usermod -aG dialout $USERビルドしたプログラムは$MODDABLE/build/ディレクトリ配下に保存されます。
正しく書き込めていれば起動から数秒後にｽﾀｯｸﾁｬﾝの顔が表示されます。 M5Stack のボタンを押すと次のように変わります。
- A ボタン（CoreS3 の場合は画面左下の領域） ... ｽﾀｯｸﾁｬﾝが 5 秒おきにランダムな方向を見る
- B ボタン（CoreS3 の場合は画面中央下の領域） ... ｽﾀｯｸﾁｬﾝが左、右、下、上を向く
- C ボタン（CoreS3 の場合は画面右下の領域） ... ｽﾀｯｸﾁｬﾝの顔の色が反転する
modを書き込みをした場合、上の動作ができなくなります。初期状態に戻すには、Flashの内容を消去してdeployで書き込む必要があります。
$ ~/.espressif/python_env/idf5.3_py3.12_env/bin/esptool.py erase_flash
$ cd ~/stack-chan/firmware
$ npm run deploy --target=esp32/m5stack_cores3次のコマンドでプログラムのデバッグが可能です
$ npm run debug --target=esp32/m5stack_cores3このコマンドはModdableのデバッガxsbugを開き、M5Stackと接続します。
xsbugを使うとログの確認やブレークポイントの設定（プログラムの特定行で一時停止する）、ステップ実行（プログラムを1行ずつ実行する）などができます。
xsbugの詳しい使い方は公式ドキュメント（英語）を参照してください。
次のコマンドでユーザアプリケーション（MOD）の書き込みを行います。
コマンドにsudoをつける必要はありません。
書き込みが完了するとcompleteのメッセージが表示されます。
表示されない場合は、書き込みができない可能性か高いです。
そのときはｽﾀｯｸﾁｬﾝをリセットし、素早くmodを書き込むがリセットボタンを3秒以上押し続けて強制書き込みモードにする必要があります。
$ npm run mod --target=esp32/m5stack_cores3 [modのマニフェストファイルのパス]例: mods/look_aroundをインストールする
$ npm run mod --target=esp32/m5stack_cores3 ./mods/look_around/manifest.json
> [email protected] mod
> mcrun -d -m -p ${npm_config_target=esp32/m5stack} ${npm_argument} "./mods/look_around/manifest.json"
# xsc mod.xsb
# xsc check.xsb
# xsc mod/config.xsb
# xsl look_around.xsa
Installing mod...completeポートが見つからず "/bin/sh: 1: [[ not found"のメッセージが表示され書き込みができないことがあります。その時は、npmの前にポートを指定します。
以下はwindows(WLS2)のmods/cherrup_ble_liteを書き込むときの例です。
$ UPLOAD_PORT=/dev/ttyACM0 npm run mod --target=esp32/m5stack_cores3 ./mods/cheerup_ble_lite/manifest.json- mods/README_ja.md: 同梱のサンプル MOD の紹介です。
- API: ｽﾀｯｸﾁｬﾝの API ドキュメントです。