Loading files
## Build and flash firmware
[日本語](./flashing-firmware_ja.md)
## Firmware architecture
### Host and MOD
Stack-chan's firmware consists of a program that provide the basic operation of Stack-chan (host), and a user application (mod).
Once the host is written, the mod can be installed in a short time for fast development.
First write the host, and then write the mods as needed.
### Manifest File
The host and the MOD each consist of a manifest file (manifest.json), source code for JavaScript modules, and resources such as images and audio. The manifest file includes the names and locations of the JavaScript modules (`modules`) , as well as the configurations that can be referenced within the modules (`config`). Additionally, the manifest file can include other manifest files (`include`).
For all configuration items, please refer to the [Moddable official documentation](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/manifest.md).
## Configuration
StackChan can change settings such as motor types and pin assignments from the manifest file. You can modify [`stack-chan/firmware/stackchan/manifest_local.json`](../stackchan/manifest_local.json) for local settings. The following settings can be written under the `"config"` key.
| Key | Description | Available values |
| ----------------- | -------------------------------------------------------------------------- | ------------------------------------ |
| driver.type | Type of motor driver | "scservo", "rs30x", "pwm", "none", "dynamixel" |
| driver.panId | ID of the serial servo used for pan axis (horizontal rotation of the neck) | 1~254 |
| driver.tiltId | ID of the serial servo used for tilt axis (vertical rotation of the neck) | 1~254 |
| driver.offsetPan | Offset of the pan axis | -90~90 |
| driver.offsetTilt | Offset of the tilt axis | -90~90 |
| tts.type | [TTS](./text-to-speech.md) type | "local", "voicevox", "remote", "voicevox-web", "elevenlabs", "openai" |
| tts.host | Host name when TTS communicates with server | "localhost", "ttsserver.local", etc. |
| tts.port | Port number when TTS communicates with server | 1~65535 |
| tts.volume | Volume when play TTS | 0~1 |
Additionally, you can specify the paths of other manifest files in a list format under the `"include"` key.
### Configuration Example: the Stack-chan M5Bottom Kit
This is an example configuration for running [Stack-chan Assembly Kit M5Bottom Version](https://mongonta.booth.pm/) distributed by Takao Akaki ([@mongonta0716](https://github.com/mongonta0716)) with the firmware in this repository. The M5Bottom version does not use a dedicated board, but connects to the M5Bottom port and servo.
When using Port.A of M5Stack Core2:
`manifest_local.json`
```json
{
// ...
"config": {
"driver": {
"type": "pwm",
"pwmPan": 33,
"pwmTilt": 32
}
}
}
```
When using Port.C of M5Stack Core2:
`manifest_local.json`
```json
{
// ...
"config": {
"driver": {
"type": "pwm",
"pwmPan": 13,
"pwmTilt": 14
}
}
}
```
When using Port.C of M5Stack Basic:
`manifest_local.json`
```json
{
// ...
"config": {
"driver": {
"type": "pwm",
"pwmPan": 16,
"pwmTilt": 17
}
}
}
```
If Stack-chan is shaking her head left and right, the configuration has been successful.
Reference: [About the firmware for Stack-chan M5Go Bottom version (Japanese)](https://raspberrypi.mongonta.com/softwares-for-stackchan/)
### Configuration example: increase mod write space
Moddable currently doesn't have an SD Card driver, so resources like audio and images are compiled and saved within the mod itself.
However, if you have a lot of audio files, the mod may not be able to write beyond the default partition size of 4MB on the stack chan due to limitations.
If you have a recent M5Stack with 16MB of Flash,
you can include the [stackchan/manifest_8mb_flash.json](. /stackchan/manifest_8mb_flash.json) file
to increase the size of the partition where the mod is saved.
Simply add the following code to your manifest file:
```json
{
"include": [". /manifest_8mb_flash.json"]
}
```
## Writing the base program (hosts)
As stated above, Stack-chan's firmware comprises a base program (host) and a user application (MOD).
The following commands are used to build and write a host.
_No `sudo` required for the command._
```console
# For M5Stack Basic/Gray/Fire
$ npm run build
$ npm run deploy
# For M5Stack Core2
$ npm run build --target=esp32/m5stack_core2
$ npm run deploy --target=esp32/m5stack_core2
# For M5Stack CoreS3
$ npm run build --target=esp32/m5stack_cores3
$ npm run deploy --target=esp32/m5stack_cores3
```
The program will be saved under the `$MODDABLE/build/` directory.
## Debugging
You can debug the program using the following commands:
```
# For M5Stack Basic/Gray/Fire
$ npm run debug
# For M5Stack Core2
$ npm run debug --target=esp32/m5stack_core2
# For M5Stack CoreS3
$ npm run debug --target=esp32/m5stack_cores3
```
These commands will open Moddable's debugger `xsbug` and connect it to the M5Stack.
Using `xsbug`, you can check logs, set breakpoints (temporarily pause the program at specific lines), and perform step-by-step execution.
For detailed instructions on how to use `xsbug`, please refer to the [official documentation](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/xs/xsbug.md).
## (Optional) Writing user application (mods)
The following command is used to build and write a mod.
_No `sudo` required for the command._
```console
# For M5Stack Basic/Gray/Fire
$ npm run mod [mod manifest file path]
# For M5Stack Core2
$ npm run mod --target=esp32/m5stack_core2 [mod manifest file path]
# For M5Stack CoreS3
$ npm run mod --target=esp32/m5stack_cores3 [mod manifest file path]
```
If written correctly, the face of Stack-chan will appear a few seconds after startup.
The M5Stack buttons will change Stack-chan's behavior as follows:
- **A Button** (in the case of CoreS3, the bottom-left area of the screen) ... Stack-chan will look in a random direction every 5 seconds.
- **B Button** (in the case of CoreS3, the bottom-center area of the screen) ... Stack-chan will look left, right, down, and up.
- **C Button** (in the case of CoreS3, the bottom-right area of the screen) ... The color of Stack-chan's face will invert.
**Example: Installing [`mods/look_around`](../mods/look_around/)**
```console
$ npm run mod ./mods/look_around/manifest.json
> stack-chan@0.2.1 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
```
## (Optional)erase flash
After writing the MOD, if you want to revert to the behavior before the MOD was written, you can erase the written MOD with the following command.
> [!NOTE]
> When you execute the command, it erases not only the MOD area but the entire flash area.
> Please note that if you are using Preferences to write settings, those settings will also be erased.
> Additionally, after executing the command, you will need to write to the host again.
```console
$ npm run erase-flash
> stack-chan@0.2.1 erase-flash
> esptool.py erase_flash
esptool.py v4.8.dev4
Found 2 serial ports
Serial port /dev/cu.usbserial-01F05597
Connecting....
Detecting chip type... Unsupported detection protocol, switching and trying again...
Connecting.........
Detecting chip type... ESP32
Chip is ESP32-D0WDQ6-V3 (revision v3.0)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 8c:aa:b5:81:6c:1c
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 25.4s
Hard reset
## Next Step
- [mods/README.md](../mods/README.md): The list of example mods
- [API](./api.md): API document
7163b0b32This file is pinned to the selected release. Download the original to open it in your design tool.