stack-chan

# Stack-chan firmware

[日本語](./README_ja.md)

## NOTE

* __To those who arrived here looking for AI Stack-chan__ You may not find the information you're looking for here! "AI Stack-chan" is an Arduino-based application under development, primarily by @robo8080.
    * https://github.com/robo8080/AI_StackChan2
* The firmware part is under active development. Breaking changes to the API may occur.
* We are currently working on [issue](https://github.com/stack-chan/stack-chan/issues/65) to make install steps more user friendly. Please post your feedback if any problem.
* If you are friendly with Arduino IDE, [stack-chan-tester](https://github.com/mongonta0716/stack-chan-tester) by @mongonta0716 is another option to try (only for PWM servo).

## Features

* Programming possible using JavaScript
* Supports multiple types of servo motors (Feetech, FUTABA, DYNAMIXEL, PWM servo)
* Supports cloud-based text-to-speech (VOICEVOX, ElevenLabs)
* Designed with separate host program and user applications (MODs). Flashing only MODs is very fast, allowing for an efficient development cycle.
* [Supports firmware flashing from a web browser](docs/flashing-firmware-web_ja.md)

## First commands

The standard firmware target is M5StackChan CoreS3.
If this is your first time, start with:

```console
$ npm i
$ npm run setup
$ npm run doctor
$ npm run flash
```

`npm run flash` builds and flashes the standard host.
For Stack-chan RT or the Takao Core2 + SG90 build, use `npm run flash:stackchan_rt` or `npm run flash:takao_core2_sg90`.
When iterating on a MOD, pass the MOD manifest: `npm run mod -- mods/examples/look_around/manifest.json`.
The command builds the archive without the xsbug install channel, then discovers and writes the device's `xs`
partition with `esptool`, so the installed host may be either a debug or release build.

## Build output

Use the repository npm scripts for firmware development. They manage the Moddable output directory and keep normal 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/`, stages validated target artifacts in `firmware/dist/bundle-targets/`, and 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](docs/flashing-firmware.md) for target-specific commands and detailed output paths.

## Directory structure

- [host](./host/): Host application and firmware modules.
- [mods](./mods/): Source code of mods.
- [scripts](./scripts/): Scripts for Stack-chan's voice synthesis, etc.
- [typings](./typings/): TypeScript type definition files (d.ts).
    - Stack-chan firmware is implemented in TypeScript, so no separate type definition files are needed.
- `dist/`: Generated firmware programs and intermediate build files. This directory is managed by the build scripts and ignored by Git.

## Documents

- [Building Environment](docs/getting-started.md)
- [Building and Writing Programs](docs/flashing-firmware.md)
- [API](docs/api.md)
- [MOD](mods/README.md)