Merge pull request #125 from meganetaaan/feature/config-doc

Add docs for manifest and config
stack-chan · Feb 14, 2023 · 18822c7 · 18822c7
2 parents 43d0654 + fe7171f
commit 18822c7
Show file tree

Hide file tree

Showing 2 changed files with 121 additions and 1 deletion.
diff --git a/firmware/docs/flashing-firmware.md b/firmware/docs/flashing-firmware.md
@@ -2,12 +2,69 @@
 
 ## Firmware architecture
 
+### Host and MOD
+
 ![firmware architecture](./images/host-and-mod.jpg)
 
 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 [`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"           |
+| 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 tilt axis                            | -90~90                                      |
+| driver.offsetTilt | Offset of the tilt axis                            | -90~90                                      |
+| tts.type          | [TTS](./text-to-speech.md) type                                      | "local", "voicevox"                         |
+| tts.host          | Host name when TTS communicates with server           | "localhost", "ttsserver.local", etc. |
+| tts.port          | Port number when TTS communicates with server          | 1~65535                                     |
+
+### 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.C of M5Stack Core2:
+
+```json
+{
+    "config": {
+        "driver": {
+            "type": "pwm",
+            "pwmPan": 13,
+            "pwmTilt": 14
+        }
+    }
+}
+```
+
+When using Port.C of M5Stack Basic:
+
+```json
+{
+    "config": {
+        "driver": {
+            "type": "pwm",
+            "pwmPan": 16,
+            "pwmTilt": 17
+        }
+    }
+}
+```
+
+Reference: [About the firmware for Stack-chan M5Go Bottom version (Japanese)](https://raspberrypi.mongonta.com/softwares-for-stackchan/)
+
 ## Writing hosts
 
 The following commands are used to build and write a host.

diff --git a/firmware/docs/flashing-firmware_ja.md b/firmware/docs/flashing-firmware_ja.md
@@ -2,11 +2,74 @@
 
 ## ｽﾀｯｸﾁｬﾝのプログラム構成について
 
+### ホストと MOD
+
 ![ｽﾀｯｸﾁｬﾝのプログラム構成](./images/host-and-mod.jpg)
 
 ｽﾀｯｸﾁｬﾝのファームウェアは、ｽﾀｯｸﾁｬﾝの基本動作を提供するプログラム（ホスト）とユーザアプリケーション（MOD）から構成されます。
 一度ホストを書き込んでしまえば、ユーザアプリケーションのインストールは短時間で終わるため高速な開発が可能です。
-最初にホストを書き込み、必要に応じてMODの書き込みを行います。
+最初にホストを書き込み、必要に応じて MOD の書き込みを行います。
+
+### マニフェストファイル
+
+ホストと MOD はそれぞれ、設定用のマニフェストファイル（manifest.json）、JavaScript モジュールのソースコード、画像や音声などのリソースから構成されます。
+マニフェストファイルでは、JavaScript モジュールの名前と場所（modules）や、モジュール内から参照できる設定（config）などを含みます。
+また、マニフェストファイルは他のマニフェストファイルを含める（include）こともできます。
+
+全ての設定項目は[Moddable の公式ドキュメント（英語）](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/manifest.md)を参照してください。
+
+## 設定変更
+
+ｽﾀﾝｸﾁｬﾝが使うモータの種類やピンアサインなどをマニフェストファイルから変更できます。
+ユーザが変更する設定は[`stackchan/manifest_local.json`](../stackchan/manifest_local.json)にまとまっています。
+`"config"`キーの配下に次のような設定が書けます。
+
+| キー              | 説明                                            | 使用可能な値                                |
+| ----------------- | ----------------------------------------------- | ------------------------------------------- |
+| driver.type       | モータドライバの種類                            | "scservo", "rs30x", "pwm", "none"           |
+| driver.panId      | パン軸（首の横回転）に使うシリアルサーボの ID   | 1~254                                       |
+| driver.tiltId     | チルト軸（首の横回転）に使うシリアルサーボの ID | 1~254                                       |
+| driver.offsetPan  | チルト軸のオフセット                            | -90~90                                      |
+| driver.offsetTilt | チルト軸のオフセット                            | -90~90                                      |
+| tts.type          | [TTS](./text-to-speech_ja.md) の種類                                      | "local", "voicevox"                         |
+| tts.host          | TTS がサーバと通信する場合のホスト名            | "localhost", "ttsserver.local" などの文字列 |
+| tts.port          | TTS がサーバと通信する場合のポート番号          | 1~65535                                     |
+
+### 設定例: ｽﾀｯｸﾁｬﾝ M5Bottom版キットを動かす
+
+紅木タカオ氏（[@mongonta0716](https://github.com/mongonta0716)）が頒布する
+[ｽﾀｯｸﾁｬﾝ組み立てキット M5Bottom版](https://mongonta.booth.pm/)を本リポジトリのファームウェアで動かすための設定例です。
+M5Bottom版は本リポジトリと違って専用基板を使わず、M5Bottomのポートとサーボを接続します。
+
+M5Stack Core2のPort.Cを使う場合:
+
+```json
+{
+    "config": {
+        "driver": {
+            "type": "pwm",
+            "pwmPan": 13,
+            "pwmTilt": 14
+        }
+    }
+}
+```
+
+M5Stack BasicのPort.Cを使う場合:
+
+```json
+{
+    "config": {
+        "driver": {
+            "type": "pwm",
+            "pwmPan": 16,
+            "pwmTilt": 17
+        }
+    }
+}
+```
+
+参考: [ｽﾀｯｸﾁｬﾝ M5GoBottom版のファームウェアについて \| M5Stack沼人の日記](https://raspberrypi.mongonta.com/softwares-for-stackchan/)
 
 ## ホストの書き込み