diff --git a/doc/realtime_api.md b/doc/realtime_api.md index bb11427..559b6e0 100644 --- a/doc/realtime_api.md +++ b/doc/realtime_api.md @@ -1,28 +1,68 @@ # Realtime API - [概要](#概要) -- [設定方法](#設定方法) +- [ビルド方法](#ビルド方法) +- [設定方法① Web UIによる設定(推奨)](#設定方法-web-uiによる設定推奨) +- [設定方法② SDカードによる設定](#設定方法-sdカードによる設定) - [YAMLの設定① (Wi-Fi、APIキー)](#yamlの設定-wi-fiapiキー) - [YAMLの設定② (LLM)](#yamlの設定-llm) - [YAMLの設定③ (サーボ)](#yamlの設定-サーボ) - - [ビルド&書き込み](#ビルド書き込み) - [使い方](#使い方) - [リアルタイム会話](#リアルタイム会話) - [サーボ動作の停止、再開](#サーボ動作の停止再開) - [Function Calling及びMCP](#function-calling及びmcp) - [TTSとの組み合わせ (OpenAI Realtimeのみ)](#ttsとの組み合わせ-openai-realtimeのみ) - - [設定方法](#設定方法-1) + - [設定方法](#設定方法) ## 概要 Realtime APIを利用することで、従来よりもリアルタイムに近い応答速度で会話を楽しむことができます。OpenAI Realtime API 及び Gemini Live APIに対応しています。 -## 設定方法 -Realtime APIを有効にするために次の設定を行います。 +## ビルド方法 +下図のように、VSCode(PlatformIO)のGUIで"env:m5stack-xxx-realtime"を選択してビルド&書き込みを実行します。 -・YAMLファイル(3種類)を作成しSDカードに保存(※) -・ビルド&書き込み +> Note: +> PlatformIOで初めてプロジェクトを開いてビルドするまでの手順は、[基本的な利用方法 2.2.ビルド&書き込み](basic_usage.md#22-ビルド書き込み)を参照ください。 + + + + + +## 設定方法① Web UIによる設定(推奨) +SDカード不要の、Web UIによる設定方法です。次の手順で設定します。 -> ※ AtomS3RはSDカード非対応のため、SPIFFSにYAMLファイルを書き込みます。書き込み方法は[こちら](./atoms3r.md)を参照ください。 +① M5Stackの電源ON。 + +② 初回はWi-Fi未設定のため、次のようなモード選択画面が表示される。 + 「Config AP」を選択してAPモードで起動する。 + +- Config AP : APモードで起動しWeb UIで設定を行うモード +- Offline : オフラインのまま起動するモード + +  + +③ APモードで起動すると次のような画面になるので、表示されているSSIDにスマートフォンやPCで接続し、表示されているURL(もしくはQRコード)によりConfigページにアクセスする。 + +  + +④ Configページの各タブで設定を入力し、Saveボタンで保存する。 +> Note: +> 全タブ入力後にSaveボタンを1度押せば、全タブの内容が保存されます。 + +- Wi-Fi:接続先Wi-FiアクセスポイントのSSIDとパスワードの設定 +- AI Service:利用するリアルタイムAPIの選択、及びAPIキーの設定 +- Servo:サーボの種類、ピン番号の設定 +- MCPs(Option):MCPサーバーの設定(任意) + +  + +⑤ RestartボタンでM5Stackを再起動すると設定が反映される。 + +## 設定方法② SDカードによる設定 +従来のようにSDカードのYAMLファイルで設定する方法です。 +以下の3種類のYAMLファイルをSDカードに保存し、M5Stackのスロットに挿入して電源を入れなおすことで反映されます。 + +> Note: +> AtomS3RはSDカード非対応のため、SPIFFSにYAMLファイルを書き込みます。書き込み方法は[こちら](./atoms3r.md)を参照ください。 ### YAMLの設定① (Wi-Fi、APIキー) SDカードフォルダ:/yaml @@ -61,11 +101,6 @@ SDカードフォルダ:/yaml サーボの種類、ポート等を[基本的な利用方法 2.1.YAMLによる初期設定](./basic_usage.md#sc_basicconfigyaml)に従い設定します。サーボを使わない場合は省略して問題ありません。 -### ビルド&書き込み -下図のように、VSCode(Platformio)のGUIで"env:m5stack-xxx-realtime"を選択してビルド&書き込みを実行します。 - - - ## 使い方 ### リアルタイム会話 @@ -73,6 +108,7 @@ SDカードフォルダ:/yaml ② M5Core画面の上部(アバターの額のあたり)をタッチすると吹き出しが"Listening..."に変わり、リアルタイム会話を開始します(もう一度タッチするとリアルタイム会話を停止します)。 +> Note: > AtomS3Rは画面自体が物理ボタンになっているため、画面中央を少し強めに押し込んでください。 ③ 30秒以上会話が無い状態が続くとリアルタイム会話を終了し、吹き出しが"Please touch"に戻ります。 diff --git a/doc/realtime_api_en.md b/doc/realtime_api_en.md index 8c15b73..b71d213 100644 --- a/doc/realtime_api_en.md +++ b/doc/realtime_api_en.md @@ -1,11 +1,12 @@ # Realtime API - [Overview](#overview) -- [How to setup](#how-to-setup) +- [How to build](#how-to-build) +- [Setup Method 1: Web UI (Recommended)](#setup-method-1-web-ui-recommended) +- [Setup Method 2: SD Card](#setup-method-2-sd-card) - [YAML① (Wi-Fi、API key)](#yaml-wi-fiapi-key) - [YAML② (LLM)](#yaml-llm) - [YAML③ (Servo)](#yaml-servo) - - [Build and write](#build-and-write) - [How to use](#how-to-use) - [Real-time conversation](#real-time-conversation) - [Stopping and restarting servo operation](#stopping-and-restarting-servo-operation) @@ -15,11 +16,51 @@ By using Realtime API, you can enjoy conversations with response speeds closer to real time than ever before. Compatible with OpenAI Realtime API and Gemini Live API. -## How to setup -To enable the Realtime API, do the following: +## How to build +As shown below, select "env:m5stack-xxx-realtime" in the VSCode (PlatformIO) GUI, then build and upload the firmware. -・Create YAML files (3 types) and save them to the SD card -・Build and write +> Note: +> If this is your first time opening and building the project with PlatformIO, see [Basic Usage 2.2. Build & Flash](basic_usage_en.md#22-build--flash). + + + + +## Setup Method 1: Web UI (Recommended) +This method uses the Web UI and does not require an SD card. Follow these steps to configure the device. + +① Turn on the M5Stack device. + +② Because Wi-Fi is not configured on first startup, a mode selection screen like the one below appears. + Select "Config AP" to start the device in AP mode. + +- Config AP: Starts the device in AP mode so you can configure it using the Web UI +- Offline: Starts the device in offline mode + +  + +③ After the device starts in AP mode, a screen like the one below appears. Connect your smartphone or PC to the displayed SSID, then access the Config page using the displayed URL or QR code. + +  + +④ Enter the settings on each tab of the Config page, then click Save. +> Note: +> After completing all tabs, you only need to click Save once to save the settings from every tab. + +- Wi-Fi: SSID and password for the Wi-Fi access point to connect to +- AI Service: Realtime API selection and API key +- Servo: Servo type and pin number +- MCPs (Optional): MCP server settings + +  + +⑤ Click Restart to restart the M5Stack device and apply the settings. + +## Setup Method 2: SD Card +This is the conventional method of configuring the device with YAML files on an SD card. +Save the following three YAML files to the SD card, insert it into the M5Stack device, and restart the device to apply the settings. + +> Note: +> AtomS3R does not support SD cards, so write the YAML files to SPIFFS instead. See [AtomS3R](./atoms3r.md) for instructions. ### YAML① (Wi-Fi、API key) SD card folder:/yaml @@ -58,19 +99,15 @@ File name:SC_BasicConfig.yaml Configure the servo type, port, etc. according to [Basic Usage 2.1.Initial Setup with YAML](./basic_usage_en.md#sc_basicconfigyaml). If you are not using servos, you can omit this. - -### Build and write -As shown below, select "env:m5stack-core2(s3)-realtime" in the VSCode (Platformio) GUI and run build and write. - - - - ## How to use ### Real-time conversation ① After starting M5Core and the avatar is displayed, the text in the speech bubble will change from "Connecting..." to "Please touch." ② When you touch the top of the M5Core screen (around the avatar's forehead), the speech bubble will change to "Listening..." and real-time conversation will begin (Touch again to stop real-time conversation). +> Note: +> On AtomS3R, the screen itself is a physical button, so press the center of the screen a little firmly. + ③ If there is no conversation for more than 30 seconds, the real-time conversation will end and the speech bubble will return to "Please touch." ### Stopping and restarting servo operation diff --git a/firmware/doc/codex/steering/20260630-web-config-spiffs.md b/firmware/doc/codex/steering/20260630-web-config-spiffs.md new file mode 100644 index 0000000..844879f --- /dev/null +++ b/firmware/doc/codex/steering/20260630-web-config-spiffs.md @@ -0,0 +1,283 @@ +# Web Config on SPIFFS + +## 目的 + +SD カードの YAML 設定と同等の内容を M5Stack 内蔵 Web アプリから設定できるようにし、SD カードが無い状態でも Wi-Fi と API キーを設定できる導線を追加する。 + +初期実装は、Wi-Fi と API key を含む `SC_SecConfig.yaml` の設定導線を全ビルド共通にし、`SC_ExConfig.yaml` など Realtime API 固有または構成差分が大きい設定編集は `REALTIME_API` ビルドのみを対象にする。 + +## 対象範囲 + +- 起動時の設定読み込み順序 + - SD カードに設定 YAML がある場合は SD を優先する。 + - SD カードまたは SD 上の YAML が使えない場合は SPIFFS の YAML を使う。 + - SPIFFS にも設定が無い場合は既存のデフォルト値と未設定扱いで起動し、設定用 AP または Wi-Fi なし起動を選べるようにする。 +- Wi-Fi 接続失敗時のユーザー選択 + - YAML の Wi-Fi 設定で接続できない場合、画面上のボタンで AP モード起動または Wi-Fi なし起動を選択する。 + - SmartConfig は廃止し、AP モードでの Web 設定を標準導線にする。 +- 設定用 AP + - AP モードで起動した場合は Web サーバーを起動し、画面に設定用 Web アプリ URL の QR コードを表示する。 + - AP の SSID、パスワード、IP は固定デフォルトを持たせ、必要なら後続で変更可能にする。 +- Web アプリ設定保存 + - 全ビルドで `SC_SecConfig.yaml` を Web UI から編集またはフォーム入力し、既存 YAML フォーマットで SPIFFS に保存できるようにする。 + - `REALTIME_API` ビルドでは `SC_ExConfig.yaml` と必要に応じた `SC_BasicConfig.yaml` の編集も扱う。 + - SD カードの YAML を SPIFFS にコピーするボタンを Web UI に設ける。 + +## Phase1 実装範囲 + +最初の実装では、設定対象を `SC_SecConfig.yaml` のみに限定する。 + +- 実装する + - SPIFFS の `/SC_SecConfig.yaml` 読み書き。 + - Web UI の `home.html` / `config.html` / `config.js` 追加。 + - `GET /config`、`POST /config`、`POST /config/restart`。 + - YAML の Wi-Fi 設定だけを使った接続。 + - 接続失敗時の AP/Offline 選択。 + - AP モードでの Web サーバー起動と QR 表示。 + - `SC_ExConfig.yaml`、`SC_SecConfig.yaml`、`SC_BasicConfig.yaml` の一式が揃わない場合は通常機能を起動せず、設定 Web へ誘導する。 +- 実装しない + - `SC_ExConfig.yaml` の Web 編集。 + - `SC_BasicConfig.yaml` の Web 編集。 + - Realtime API 固有タブやフォーム。 + +Phase1 後の追加実装で、`REALTIME_API` ビルドに限って `SC_ExConfig.yaml` と必要に応じた `SC_BasicConfig.yaml` を拡張する。 + +設定ファイル一式が不足している場合は、`REALTIME_API` ビルドでは `SC_SecConfig.yaml` だけを読み込んで Wi-Fi 接続を試す。接続できれば STA 接続上で設定 Web を起動し、接続できなければ Config AP を起動する。AtomS3R は画面が小さいため QR は表示せず、Wi-Fi 接続失敗時は Config AP へ直接進む。`REALTIME_API` 以外のビルドでは、不完全な設定を画面に表示して待機する。 + +## Phase2 実装範囲 + +Phase2 では `REALTIME_API` ビルド向けに、`SC_SecConfig.yaml`、`SC_BasicConfig.yaml`、`SC_ExConfig.yaml` をフォーム入力から生成して SPIFFS に保存する。 + +- 実装する + - Config page を YAML 直書き textarea から項目別フォームへ変更する。 + - `GET /config` を JSON 応答に変更し、現在値、設定元、設定ファイル一式の状態を返す。 + - `POST /config` を JSON 入力に変更し、フォーム値から 3 つの YAML を生成して SPIFFS に保存する。 + - `SC_SecConfig.yaml` + - `wifi.ssid` + - `wifi.password` + - `apikey.aiservice` + - `apikey.tts` + - `apikey.stt` + - `SC_BasicConfig.yaml` + - Servo 関連のみ生成する。 + - Servo 以外の BasicConfig 項目は AI_StackChan_Ex では使わないため YAML から省略する。 + - `SC_ExConfig.yaml` + - `llm.type` + - `llm.enableMemory` + - Realtime API ビルドで不要な ExConfig 項目は YAML から省略する。 + - Realtime AI Service の選択肢 + - OpenAI Realtime -> `llm.type: 0` + - Google Gemini Live -> `llm.type: 3` + - モデル名は Realtime API ビルドでは固定のため設定対象外。 + - Servo Type 選択時は、Pin/Offset/Center/Limit/Enable Takao Base のプリセット適用前に確認ダイアログを出す。 + - Save 成功後は「設定した値を有効にするために、Restart する前に SD カードを抜く」注意を表示する。 +- 実装しない + - Copy from SD ボタン。仕様が複雑になるため Phase2 で削除する。 + - Realtime API 以外のビルド向けフォーム拡張。 + - Realtime API で使わない `tts`、`stt`、`wakeword`、`audio`、`moduleLLM`、`mcpServers`、`customEndpoint` などのフォーム項目。 + +### Phase2 API + +- `GET /config` + - JSON を返す。 + - 例: + - `source`: `sd` / `spiffs` / `partial` / `none` + - `complete`: 3 YAML が揃っているか + - `sec`: Wi-Fi と API key + - `basic`: Servo 設定 + - `ex`: Realtime AI Service と memory 設定 +- `POST /config` + - JSON を受け取る。 + - 入力値を検証し、`SC_SecConfig.yaml`、`SC_BasicConfig.yaml`、`SC_ExConfig.yaml` を SPIFFS へ保存する。 + - 保存後は RAM 上の `system_config` に反映できる範囲は反映するが、実運用上は Restart を促す。 +- `POST /config/copy_sd` + - Phase2 で削除する。 +- `POST /config/restart` + - 既存どおり再起動する。 + +### Phase2 YAML 生成方針 + +生成する YAML は、動作に必要な最小キーのみを含める。 + +- `SC_SecConfig.yaml` + - `wifi` + - `apikey` +- `SC_BasicConfig.yaml` + - `servo` + - `takao_base` + - `servo_type` +- `SC_ExConfig.yaml` + - `llm.type` + - `llm.enableMemory` + +既存 YAML を読み込める場合でも、Phase2 の Save ではフォーム対象外項目を SPIFFS 側の生成 YAML へ持ち越さない。 + +## 主な変更候補ファイル + +- `src/main.cpp` + - 設定読み込み元の選択、Wi-Fi 接続失敗時の AP/Offline 選択、AP 起動、QR 表示。 +- `src/StackchanExConfig.*` + - 必要に応じて、読み込み元状態や設定保存補助の追加。ただし既存 `StackchanSystemConfig::loadConfig()` の使い方を優先する。 +- `src/WebAPI.*` + - 設定取得、保存、検証、SD から SPIFFS へのコピー API を追加する。 +- `incbin/personalize.html` +- `incbin/personalize.js` + - 既存 Personalize 画面に設定ページへの導線を追加するか、設定用 HTML/JS を別ファイルとして incbin する。 +- `incbin/home.html` + - Web アプリの入口。Personalize と Config への分岐を置く。 +- `incbin/config.html` +- `incbin/config.js` + - SPIFFS 設定編集用 UI。 +- `doc/fw_design.md` + - 起動時設定優先順位、SPIFFS 永続化ファイル、Web API を追記する。 + +## 設計方針 + +### 設定ファイル配置 + +SPIFFS 側のファイル名は既存 AtomS3R の配置に合わせる。 + +- `/SC_BasicConfig.yaml` +- `/SC_SecConfig.yaml` +- `/SC_ExConfig.yaml` + +SD 側は現行の `loadConfig(SD, "/app/AiStackChanEx/SC_ExConfig.yaml")` に合わせ、既存ライブラリのデフォルトパスである `/yaml/SC_SecConfig.yaml` と `/yaml/SC_BasicConfig.yaml` を使う。SD から SPIFFS へのコピーでは、この 3 ファイルを対象にする。 + +### 読み込み優先順位 + +1. SPIFFS は全ボードで先に `begin()` する。 +2. SD が利用可能で、少なくとも SD の主要 YAML が開ける場合は SD から `system_config.loadConfig()` する。 +3. SD が利用できない、または SD 設定が不足する場合は SPIFFS から `system_config.loadConfig()` する。 +4. どちらも無い場合は SPIFFS から存在しないファイルとして読み込み、既存の default/callback に寄せる。ただし SD 無しを理由に再起動しない。 + +SD 優先を保つため、SD が存在する場合に SPIFFS 設定を暗黙に上書きしない。SD から SPIFFS への反映は Web UI の明示操作のみとする。 + +### Wi-Fi 起動状態 + +Wi-Fi 接続は読み込んだ YAML の `wifi.ssid` / `wifi.password` のみで試す。 + +1. `wifi.ssid` が空の場合は接続を試さず、画面に AP/Offline 選択 UI を表示する。 +2. `wifi.ssid` がある場合は `WiFi.begin(ssid, password)` で接続を試す。 +3. 接続に失敗した場合、画面に選択 UI を表示する。 + - BtnA または画面左: AP モードで設定する。 + - BtnC または画面右: Wi-Fi なしで起動する。 + +AP モード選択時は `WiFi.mode(WIFI_AP)` と `WiFi.softAP()` を使い、Web サーバーを起動する。AP モードは「設定可能だが通常のオンライン AI サービスは未接続」として扱うため、会話処理は offline 相当にする。 + +引数なしの `WiFi.begin()` による前回接続情報の試行は行わない。SmartConfig 廃止後は前回接続情報と YAML 設定の二重管理を避け、起動時の接続元を YAML に一本化する。 + +### QR 表示 + +QR は既存 `avatar.updateSubWindowQrcode()` の利用を第一候補にする。ただし Avatar 初期化前の起動中画面で必要な場合は、M5GFX の QR 描画 API または簡易表示関数を別途確認して使う。 + +表示 URL は AP IP に合わせて `http://192.168.4.1/` を基本とする。 + +### Web API + +`SC_SecConfig.yaml` を扱う最小 API は全ビルドで有効化する。`SC_ExConfig.yaml` や Realtime API 固有項目を扱う API は `REALTIME_API` ビルドのみで有効化する。 + +- `GET /config` + - SPIFFS 上の YAML 内容と、現在の設定読み込み元を返す。 + - 全ビルドでは `SC_SecConfig.yaml` を返す。 + - `REALTIME_API` ビルドでは `SC_ExConfig.yaml` と必要に応じた `SC_BasicConfig.yaml` も返す。 +- `POST /config` + - YAML 文字列または JSON フォーム入力を受け取り、YAML として SPIFFS に保存する。 + - 全ビルドでは `SC_SecConfig.yaml` のみ保存対象にする。 + - `REALTIME_API` ビルドでは `SC_ExConfig.yaml` と必要に応じた `SC_BasicConfig.yaml` も保存対象にする。 + - 最初の実装では YAML 文字列保存を優先し、フォーム UI は主要項目から段階的に増やす。 +- `POST /config/restart` + - 保存後に再起動するための明示 API。自動再起動は UI 側で確認してから呼ぶ。 + +保存前に `deserializeYml()` で最低限の構文検証を行い、壊れた YAML を保存しない。 + +### `StackchanExConfig` の追加責務 + +`StackchanSystemConfig` は外部ライブラリ配下のため直接変更しない。派生クラスである `StackchanExConfig` に、Web UI から扱う設定ファイルの薄い保存・検証 API を追加する。 + +`SC_SecConfig.yaml` は親クラスの protected メンバー `_secret_config` と protected 関数 `setSecretConfig()` / `loadSecretConfig()` が担当しているため、`StackchanExConfig` 側ではこれらを public な用途別関数で包む。 + +追加候補の public 関数: + +- `bool validateSecretConfigYaml(const String& yaml, String* error = nullptr)` + - Web UI から受け取った YAML を `deserializeYml()` で構文検証する。 + - `wifi.ssid`、`wifi.password`、`apikey.aiservice`、`apikey.tts`、`apikey.stt` のキーが扱える形か確認する。 + - API key は空文字を許可する。Wi-Fi SSID も、意図的に未設定で保存する余地を残すため空文字自体はエラーにしない。 +- `bool saveSecretConfigYaml(fs::FS& fs, const char* path, const String& yaml, String* error = nullptr, bool apply_now = true)` + - `validateSecretConfigYaml()` で検証する。 + - `path + ".tmp"` に一度書き込み、成功後に本ファイルへ反映する。 + - `apply_now` が true の場合は、保存した YAML を `setSecretConfig()` に渡して RAM 上の `_secret_config` へ反映する。 + - ただし Wi-Fi 再接続はこの関数では行わず、Web UI から再起動を促す。 +- `bool loadSecretConfigYaml(fs::FS& fs, const char* path, uint32_t yaml_size = 2048)` + - 起動時や保存後の明示再読み込み用の wrapper。 + - 内部では親クラスの `loadSecretConfig()` を呼ぶ。 +- `String exportSecretConfigYaml(bool mask_secret = false)` + - RAM 上の `_secret_config` から `SC_SecConfig.yaml` 形式の YAML を生成する。 + - `mask_secret` が true の場合は password/API key を伏せた表示用文字列にする。 + - 実保存や編集用には原則として SPIFFS 上のファイル内容を返し、ファイルが無い場合の初期テンプレートとして使う。 + +追加候補の private 関数: + +- `bool writeFileAtomic(fs::FS& fs, const char* path, const String& data, String* error)` + - 一時ファイルへの書き込み、flush/close、rename をまとめる。 +- `bool parseSecretConfigYaml(const String& yaml, DynamicJsonDocument& doc, String* error)` + - 検証と `setSecretConfig()` の両方で使う YAML parse 共通処理。 + +Web UI から `SC_SecConfig.yaml` を保存する内部処理は次の流れにする。 + +1. `config.js` が `/config` へ対象 `SC_SecConfig.yaml` と YAML 本文を POST する。 +2. `WebAPI.cpp` が本文を受け取り、`system_config.saveSecretConfigYaml(SPIFFS, "/SC_SecConfig.yaml", body, &error)` を呼ぶ。 +3. `StackchanExConfig` が YAML を parse し、壊れた YAML や想定外のトップレベル構造を拒否する。 +4. 検証成功時だけ SPIFFS へ一時ファイル経由で保存する。 +5. 保存後、RAM 上の `_secret_config` を更新する。 +6. `WebAPI.cpp` は成功を返し、UI は「再起動すると新しい Wi-Fi 設定で接続する」旨を表示して `/config/restart` の操作を促す。 + +この分担により、Web API 側は HTTP とファイル種別の分岐に集中し、YAML の意味や `_secret_config` の更新は `StackchanExConfig` に閉じ込める。 + +### Web UI + +初期実装では設定の完全性と実装リスクを優先し、以下の二段構えにする。 + +- YAML 編集ビュー + - 全ビルドでは `SC_SecConfig.yaml` を編集。 + - `REALTIME_API` ビルドでは `SC_SecConfig.yaml`、`SC_ExConfig.yaml`、必要なら `SC_BasicConfig.yaml` をタブで編集。 + - 保存、再読み込み、再起動、SD からコピーの操作を提供する。 +- 主要項目フォーム + - Wi-Fi SSID/password。 + - OpenAI/Realtime API 用 API key。 + - Realtime API で必要な最小限のモデルや音量など。 + +既存 `personalize.html/js` は Role/Memory 用として残し、設定 UI は `config.html/js` を追加する方針を第一候補にする。 + +### 画面切り替え + +Web アプリの入口として `home.html` を追加し、`/` は `home.html` を返す。`home.html` には次の 2 つの導線を置く。 + +- Personalize + - 既存の `/personalize.html` に遷移する。 + - Role と Memory の管理を行う。 +- Config + - 新規の `/config.html` に遷移する。 + - Wi-Fi、API key、Realtime API 用 YAML 設定、SD から SPIFFS へのコピーを行う。 + +設定用 AP モードで QR に載せる URL も `/` とし、スマートフォンで開いた直後に用途を選べるようにする。既存利用者向けに `/personalize.html` はそのまま残す。 + +`home.html` は説明を増やしすぎず、2 つの大きな操作ボタンと現在の接続状態または設定読み込み元の短い表示に留める。AP モードでは Config を主導線として上に配置し、通常 STA 接続時は Personalize と Config を並列に扱う。 + +## 設計上の注意点 + +- API キーや Wi-Fi パスワードをログへ出さない。既存ログに表示される箇所は今回の実装時に抑制を検討する。 +- SPIFFS 保存中の電源断で設定が壊れる可能性があるため、可能なら一時ファイルへ書いてからリネームする。 +- AP モードで Web サーバーを動かす場合、`isOffline` の意味が「Web サーバー停止」と衝突する。`wifiMode` のような状態を分ける設計にする。 +- `StackchanSystemConfig` は外部ライブラリ配下のため、直接変更せず `StackchanExConfig` と起動側で吸収する。 +- AtomS3R は画面とボタン制約が異なるため、初期実装の対象デバイス確認を Core2/CoreS3 優先にする。 +- `SC_SecConfig.yaml` の AP 設定導線は全ビルドに入るため、`WebAPI.cpp` の基本ルートと SPIFFS 書き込み処理は `REALTIME_API` に依存しない構成にする。 +- `REALTIME_API` 以外のビルドでは、Config UI 上の Realtime API 固有タブや項目は表示しない。 + +## 確認方法 + +- `m5stack-core2-realtime` または `m5stack-cores3-realtime` でビルド確認する。 +- SD あり、SD なし、SPIFFS 設定あり、SPIFFS 設定なしの起動分岐をログで確認する。 +- Wi-Fi 接続失敗時に AP/Offline を選択できることを確認する。 +- AP 接続後、QR の URL から Web UI に到達できることを確認する。 +- Web UI で SPIFFS に YAML 保存し、再起動後に設定が読み込まれることを確認する。 +- SD から SPIFFS へのコピー後、SD を抜いた状態で同じ設定が使われることを確認する。 diff --git a/firmware/doc/codex/steering/20260718-gemini-root-ca-bundle.md b/firmware/doc/codex/steering/20260718-gemini-root-ca-bundle.md new file mode 100644 index 0000000..204315d --- /dev/null +++ b/firmware/doc/codex/steering/20260718-gemini-root-ca-bundle.md @@ -0,0 +1,78 @@ +# Gemini Live Root CA バンドル化 + +## 目的 + +Gemini Live API 接続時に、利用環境によって Google から提示される証明書チェーンが異なり、単一の信頼証明書では TLS 検証に失敗する問題を軽減する。 +`src/rootCA/rootCAgoogleGemini.h` に複数の Google 向け CA 証明書を連結した PEM バンドルを組み込み、mbedTLS が提示されたチェーンに対応する信頼アンカーを選択できるようにする。 + +## 対象範囲 + +- Gemini Live API の WebSocket TLS 接続で使用する組み込み CA 証明書 +- 対象ホスト: `generativelanguage.googleapis.com:443` +- `WebSocketsClient::beginSslWithCA()` へ渡す CA データの内容 + +Custom OpenAI Endpoint 用の `customRootCAFile` / `customRootCAFiles`、Google Speech-to-Text、OpenAI Realtime API、TTS の CA 設定は変更しない。 + +## 主な変更ファイル + +- `src/rootCA/rootCAgoogleGemini.h` + - 単一証明書を、複数の PEM 証明書を連結した Google 向け CA バンドルへ変更する。 + - 各証明書の Subject、Issuer、有効期限、SHA-256 fingerprint、取得元をコメントで記録する。 +- `doc/codex/steering/20260718-gemini-root-ca-bundle.md` + - 本作業の方針と確認方法を記録する。 + +既存の接続処理を変更する必要がなければ、`src/llm/Gemini/GeminiLive.cpp` は変更しない。 + +## 実装方針 + +1. Google Trust Services の公式リポジトリを基準に、実際に報告された複数の証明書チェーンを検証できる CA 証明書を選定する。 +2. `openssl s_client` が表示したサーバー証明書をそのまま採用せず、Subject、Issuer、fingerprint を照合して証明書の位置付けを確認する。 +3. 選定した証明書を、各 `BEGIN CERTIFICATE` / `END CERTIFICATE` ブロックの間に改行を入れて1つの文字列へ連結する。 +4. 既存の変数名 `root_ca_google_gemini` と `beginSslWithCA()` の呼び出しを維持し、変更範囲を証明書ヘッダーに限定する。 +5. 古い証明書を無条件に残すのではなく、Google公式情報、実環境で観測されたチェーン、証明書の有効期限を根拠に必要な証明書だけを含める。 +6. CAを無効化する `setInsecure()` は使用しない。 + +## 設計上の注意点 + +- 複数CAの組み込みは、環境ごとに異なる証明書チェーンへ対応するための信頼候補を増やすものであり、証明書検証を無効化するものではない。 +- バンドルに含まれない将来のGoogle証明書チェーンには対応できないため、ファームウェア更新時にGoogle Trust Servicesの公開情報を再確認する。 +- 端末時刻の未同期、TLSインスペクションによる独自CAへの差し替え、古いmbedTLSの暗号方式非対応は、本変更だけでは解決しない。 +- Googleは特定の中間CAやRoot CAの固定を避けるよう案内している。一方、組み込み機器では一般的なOSのRoot Storeを自動更新できないため、本実装では対象をGoogle向けの必要最小限のCAバンドルに限定し、ファームウェア更新で保守する。 +- 複数PEMによるフラッシュ使用量と、TLSハンドシェイク時のヒープ使用量増加を確認する。 +- APIキー、Wi-Fi情報などの秘密情報は証明書ヘッダーやログへ追加しない。 + +## 確認方法 + +### 証明書の静的確認 + +- 各PEMをOpenSSLで解析できることを確認する。 +- Subject、Issuer、有効期限、SHA-256 fingerprintがGoogle公式情報と一致することを確認する。 +- PEMブロック数と区切りを確認し、文字列の欠落や重複定義がないことを確認する。 + +### 接続確認 + +- 従来接続できていた環境でGemini Live APIへ接続し、回帰がないことを確認する。 +- エラー報告があった環境で接続し、`X509 - Certificate verification failed` が解消することを確認する。 +- 可能であれば、各環境で次のコマンドにより提示チェーンを採取し、バンドル内のCAへ検証経路が到達することを確認する。 + +```sh +openssl s_client -connect generativelanguage.googleapis.com:443 -servername generativelanguage.googleapis.com -showcerts -verify_return_error +``` + +### ビルド確認 + +- `m5stack-core2-realtime` +- `m5stack-cores3-realtime` +- `m5stack-atoms3r-realtime` + +依存ライブラリ取得などでネットワークアクセスが必要な場合は、実行前にユーザーの了承を得る。 + +## 戻し方 + +`src/rootCA/rootCAgoogleGemini.h` のCA文字列を変更前の単一証明書へ戻す。接続処理や設定構造は変更しないため、証明書ヘッダーの差し戻しだけで元の動作へ復帰できる。 + +## 残リスク + +- Google側で新しいCAや証明書チェーンへ切り替わった場合は、バンドルの再更新が必要になる。 +- 報告環境でTLSインスペクションが行われている場合、Google公式CAの追加だけでは接続できない。 +- 実機を用意できない環境については、ビルドと証明書チェーンの静的検証までとなる。 diff --git a/firmware/doc/codex/steering/20260719-config-page-tabs.md b/firmware/doc/codex/steering/20260719-config-page-tabs.md new file mode 100644 index 0000000..9665ac7 --- /dev/null +++ b/firmware/doc/codex/steering/20260719-config-page-tabs.md @@ -0,0 +1,57 @@ +# Config Page Tabs + +## 目的 + +Web UI の Config ページを Wi-Fi、AI Service、Servo の3つのタブに整理し、設定項目を探しやすくする。 +Save、Reload、Restart はタブ共通の操作としてタブ領域の外に置き、Save では表示中のタブに限らず全タブの入力値をまとめて保存する。 + +## 対象範囲 + +- `incbin/config.html` のタブUIと設定パネルの構造、スタイル +- `incbin/config.js` のタブ切り替え処理 +- `doc/fw_design.md` の Config page 設計記述 + +Web API、JSON形式、YAML生成処理、設定項目そのものは変更しない。 + +## 主な変更ファイル + +- `incbin/config.html` +- `incbin/config.js` +- `doc/fw_design.md` +- `doc/codex/steering/20260719-config-page-tabs.md` + +## 実装方針 + +1. Configフォーム内に `Wi-Fi`、`AI Service`、`Servo` のタブボタンを追加する。 +2. 既存の3つの設定領域を、それぞれ対応するタブパネルとして構成する。 +3. 初期表示は `Wi-Fi` タブとする。 +4. タブ選択時は対応するパネルのみ表示し、ほかのパネルは非表示にする。非表示パネル内の入力要素はDOM上に保持し、入力値を失わないようにする。 +5. Save、Reload、Restart とステータス/エラーメッセージはタブパネルの外に配置する。 +6. Save は既存の `collectConfig()` を使用し、全タブの入力値から従来どおり1つのJSONを生成して `/config` にPOSTする。 +7. Reload は全設定を再取得して全タブへ反映し、現在選択中のタブは維持する。 +8. タブには `role="tablist"`、`role="tab"`、`role="tabpanel"` と対応するARIA属性を設定する。クリックに加え、左右矢印、Home、Endキーでタブを移動できるようにする。 +9. 狭い画面でも3つのタブ名が収まり、共通操作ボタンが既存どおり扱えるレスポンシブ表示にする。 + +## 設計上の注意点 + +- タブ切り替えだけではフォーム送信やAPI通信を行わない。 +- タブを切り替えても未保存の入力値を保持する。 +- `fieldset` と見出しの意味構造を維持しつつ、選択中タブが視覚的に明確になるようにする。 +- パスワード表示切り替え、Servo Type変更確認、Pin Presetなど既存のイベント処理を維持する。 +- Save成功後のSDカード取り外し案内とRestart確認ダイアログを維持する。 +- 埋め込みファイル容量への影響を小さくし、外部ライブラリは追加しない。 + +## 確認方法 + +- 初期表示で Wi-Fi タブだけが表示されること。 +- 各タブをクリックおよびキーボードで切り替えられること。 +- タブをまたいで入力した値が、切り替え後も保持されること。 +- Save時のJSONに Wi-Fi、AI Service、Servo の全設定が含まれること。 +- Reloadで全タブの値が更新され、選択中のタブが維持されること。 +- Save、Reload、Restartがどのタブからも操作できること。 +- デスクトップ幅とスマートフォン幅で、タブ、入力欄、操作ボタンに重なりやはみ出しがないこと。 +- `m5stack-core2-realtime` と `m5stack-cores3-realtime` をビルドし、埋め込みWeb UIを含めてコンパイルできること。 + +## 戻し方 + +タブボタンとタブ切り替え処理を削除し、3つの設定領域を常時表示へ戻す。APIおよび保存形式は変更しないため、設定データの移行や復元は不要。 diff --git a/firmware/doc/codex/steering/20260719-incbin-build-dependencies.md b/firmware/doc/codex/steering/20260719-incbin-build-dependencies.md new file mode 100644 index 0000000..8e0440e --- /dev/null +++ b/firmware/doc/codex/steering/20260719-incbin-build-dependencies.md @@ -0,0 +1,104 @@ +# incbin Build Dependencies + +> **実装保留中:** 本ファイルは検討中の設計方針を記録するものであり、現時点ではビルドスクリプト、`platformio.ini`、`WebAPI.cpp`の変更を行わない。実装開始前に方式と警告条件を再レビューする。 + +## 目的 + +`incbin`内のHTML/JavaScriptを変更したときに、対象ファイルを埋め込む`WebAPI.cpp`が自動的に再コンパイルされるようにする。 + +また、今後Web UIファイルを追加した際に`IMPORT_FILE()`への登録を忘れた場合、ビルド時に検出できるようにする。 + +## 現状と課題 + +`WebAPI.cpp`の`IMPORT_FILE()`は、インラインアセンブラの`.incbin`ディレクティブで`incbin`内のファイルを取り込んでいる。 + +`.incbin`のファイルパスはC/C++の通常のinclude依存解析では認識されないため、HTML/JavaScriptだけを変更しても`WebAPI.cpp`が再コンパイルされず、変更前の内容がファームウェアへ残る場合がある。 + +依存ファイル一覧をビルドスクリプト側へ手作業で重複定義すると、Web UIファイル追加時に一覧の更新を忘れる可能性が残る。 + +## 対象範囲 + +- `src/WebAPI.cpp`内の`IMPORT_FILE()`による埋め込み +- `incbin/*.html` +- `incbin/*.js` +- PlatformIOの追加ビルドスクリプト +- 全PlatformIOビルド環境で共通となる`extra_scripts`設定 + +Web APIのルーティング、MIME type、HTML/JavaScriptの内容、設定保存処理は本作業の対象外とする。 + +## 想定する主な変更ファイル + +- `platformio.ini` +- 新規PlatformIOビルドスクリプト(配置先とファイル名は実装前に決定する) +- `src/WebAPI.cpp` + - `IMPORT_FILE()`付近への保守コメントのみ +- `doc/fw_design.md` +- `doc/codex/steering/20260719-incbin-build-dependencies.md` + +## 実装方針案 + +1. PlatformIOのPRE追加スクリプトからBuild Middlewareを登録する。 +2. ビルドスクリプトで`src/WebAPI.cpp`を読み、文字列リテラルを指定した`IMPORT_FILE()`呼び出しから埋め込みファイル名を抽出する。 +3. 抽出した各ファイルを、`WebAPI.cpp`から生成されるオブジェクトファイルの依存関係としてSConsへ登録する。 +4. 埋め込みファイルの更新日時または内容が変化した場合、PlatformIOの通常の差分ビルドによって`WebAPI.cpp`を再コンパイルする。 +5. `incbin`直下の`.html`と`.js`を走査し、`IMPORT_FILE()`から参照されていないファイルをビルド時に警告する。 +6. `IMPORT_FILE()`から参照されているファイルが存在しない場合は、埋め込み不能であるためビルドエラーとする。 +7. `WebAPI.cpp`の`IMPORT_FILE()`付近に、依存関係がビルドスクリプトによって生成されることと、未参照ファイルが警告対象になることを短いコメントで記載する。 + +## 検出ルール案 + +### 警告 + +次の条件を満たすファイルがある場合、ファイル名を含む警告を表示する。 + +- `incbin`直下に存在する +- 拡張子が`.html`または`.js` +- `WebAPI.cpp`の`IMPORT_FILE()`から参照されていない + +警告例: + +```text +Warning: incbin/settings.html is not referenced by IMPORT_FILE() +``` + +未参照ファイルを直ちにビルドエラーにはせず、開発途中で配置したファイルも扱えるよう警告に留める案とする。 + +### エラー + +次の条件ではビルドを停止する。 + +- `IMPORT_FILE()`で指定されたファイルが`incbin`内に存在しない +- `IMPORT_FILE()`の記述を安全に解釈できず、依存関係を正しく登録できない + +## 設計上の注意点 + +- 埋め込み対象の正は`WebAPI.cpp`の`IMPORT_FILE()`呼び出しとし、Python側に同じファイル一覧を手書きしない。 +- マクロ定義そのものではなく、文字列リテラルを使用した呼び出しだけを抽出対象とする。 +- コメントアウトされた`IMPORT_FILE()`を誤検出しない方法を検討する。単純な正規表現で十分か、軽量な前処理が必要かは実装前に確認する。 +- ファイル名にサブディレクトリを許可するか、現在どおり`incbin`直下だけに限定するかを実装前に決定する。 +- `.css`、画像、JSONなどを将来埋め込む場合に、警告対象拡張子を容易に追加できる構造とする。 +- Build Middlewareの対象指定がPlatformIOの各環境で同じように`src/WebAPI.cpp`へ一致することを確認する。 +- IDEのコード解析など、通常ビルド以外のIntegration Dumpでは不要な警告や副作用を発生させない。 +- Web UIファイルにAPIキー、Wi-Fiパスワードなどの実データを追加しない。 + +## 実装前に再確認する事項 + +- 追加スクリプトの配置先と命名 +- 未参照ファイルを警告に留めるか、CIではエラーに昇格させるか +- コメントアウトされた`IMPORT_FILE()`の扱い +- `incbin`サブディレクトリと追加拡張子をサポートするか +- Build Middlewareで依存関係を付与する対象ノードの指定方法 + +## 確認方法 + +1. 変更のない状態で連続ビルドし、`WebAPI.cpp`が不要に再コンパイルされないことを確認する。 +2. `incbin/config.html`だけを変更し、`WebAPI.cpp`が自動的に再コンパイルされることを確認する。 +3. `incbin/config.js`だけを変更した場合も同様に確認する。 +4. テスト用HTML/JavaScriptを`incbin`へ追加し、`IMPORT_FILE()`未登録の警告が表示されることを確認する。 +5. `IMPORT_FILE()`から存在しないファイルを参照し、分かりやすいビルドエラーになることを確認する。 +6. `m5stack-core2-realtime`、`m5stack-cores3-realtime`、`m5stack-atoms3r-realtime`で動作を確認する。 +7. 必要に応じてRealtime API以外の環境でも共通スクリプトが問題なく動作することを確認する。 + +## 戻し方 + +`platformio.ini`から追加スクリプトの登録を削除し、追加したビルドスクリプトと`WebAPI.cpp`の案内コメントを削除する。`IMPORT_FILE()`による現在の埋め込み方式自体は変更しないため、ファームウェア側の復元作業は不要。 diff --git a/firmware/doc/codex/steering/20260720-config-page-mcp-settings.md b/firmware/doc/codex/steering/20260720-config-page-mcp-settings.md new file mode 100644 index 0000000..dbf0566 --- /dev/null +++ b/firmware/doc/codex/steering/20260720-config-page-mcp-settings.md @@ -0,0 +1,68 @@ +# Config Page MCP Settings + +## 目的 + +Web UI の Config ページに任意設定用の `MCPs (Option)` タブを追加し、`SC_ExConfig.yaml` の `llm.mcpServers` を最大5件まで編集、保存できるようにする。 +MCPサーバー設定は `REALTIME_API` ビルドでも利用される既存設定であり、今回そのWeb UI未対応部分を補う。 + +## 対象範囲 + +- `incbin/config.html` の4つ目のタブとMCPサーバー入力欄 +- `incbin/config.js` のMCPサーバー設定の読込、入力値収集、画面側の検証 +- `src/WebAPI.cpp` の `llm.mcpServers` のJSON応答と `SC_ExConfig.yaml` 生成 +- `src/StackchanExConfig.h`、`src/StackchanExConfig.cpp` のMCPサーバー最大件数と安全な読込 +- `doc/fw_design.md` の Config page、API、保存形式の設計記述 + +MCPサーバー設定の形式と既存のMCPクライアント処理は変更しない。 + +## 主な変更ファイル + +- `incbin/config.html` +- `incbin/config.js` +- `src/WebAPI.cpp` +- `src/StackchanExConfig.h` +- `src/StackchanExConfig.cpp` +- `doc/fw_design.md` +- `doc/codex/steering/20260720-config-page-mcp-settings.md` + +## 実装方針 + +1. Configページの既存タブ列へ、4つ目の `MCPs (Option)` タブを追加する。 +2. MCPタブには5件分の入力枠を固定表示し、各枠で既存設定形式に対応する `name`、`disabled`、`url`、`port` を編集可能にする。`disabled` は `true` / `false` のドロップダウンで選択する。 +3. `LLM_N_MCP_SERVERS_MAX` を10件から5件へ変更し、Web UI、設定読込、ランタイムの上限を統一する。 +4. `StackchanExConfig` はYAML内の `mcpServers` を共通上限まで読み込み、6件目以降を無視して配列範囲外へ書き込まないようにする。 +5. `GET /config` の `ex.llm.mcpServers` に、SPIFFS上の `SC_ExConfig.yaml` から読み込んだ設定を返す。SPIFFS設定がない場合はRAM上の `StackchanExConfig` から返す。 +6. Web UIのReload時は取得した配列を5枠へ反映し、残りの枠を空にする。 +7. Save時は、未使用の空欄を除外し、入力済みの枠だけを表示順に `ex.llm.mcpServers` 配列へ格納する。 +8. 使用する枠は `name` と `url` を必須とし、`port` は1から65535の整数として検証する。入力途中など一部だけ値がある枠は保存せず黙って捨てるのではなく、エラー表示して保存を中止する。 +9. `disabled` はドロップダウンの選択値を既存YAML形式の真偽値で保持する。空欄の枠は `disabled` の状態にかかわらず配列へ含めない。 +10. `POST /config` は受け取った配列を共通上限で検証し、既存の `llm.type`、`llm.enableMemory` とともに `SC_ExConfig.yaml` の `llm.mcpServers` として生成する。 +11. YAML文字列は既存のクォート処理を利用し、名前やURLにYAMLの予約文字が含まれても構造を壊さないようにする。 +12. 既存のタブ切り替え、全タブ一括Save、選択中タブを維持するReload、Restartの動作を維持する。 + +## 設計上の注意点 + +- `LLM_N_MCP_SERVERS_MAX` を唯一のランタイム上限とし、固定配列とMCPクライアント配列も5件に統一する。 +- 既存の `SC_ExConfig.yaml` に6件以上ある場合は先頭5件だけを使用する。Web APIから6件以上を保存する要求はエラーにする。 +- MCPサーバー設定は任意であり、0件の `mcpServers` 配列を保存可能にする。 +- `url` は既存 `MCPClient` が接続先ホストとして扱う値をそのまま保存し、今回URLスキームの変換や接続確認は追加しない。 +- API側でも配列型、件数、必須文字列、ポート範囲を確認し、不正な入力から壊れたYAMLを生成しない。 +- JSONドキュメント容量は5件分の文字列を扱えるよう見直し、組み込み機器のヒープ消費を必要以上に増やさない。 +- 外部ライブラリは追加しない。 + +## 確認方法 + +- `MCPs (Option)` タブをクリックおよびキーボード操作で選択できること。 +- MCPサーバーを0件から5件まで入力し、Save後の `SC_ExConfig.yaml` に `name`、`disabled`、`url`、`port` が正しい配列として保存されること。 +- 各入力枠の `disabled` を `true` / `false` のドロップダウンで選択でき、Reload後も選択値が復元されること。 +- Reloadおよびページ再読込で、保存済みの最大5件が同じ順序と値で復元されること。 +- 空欄の入力枠が保存配列へ含まれないこと。 +- 一部項目だけ入力した枠、範囲外または整数でないport、6件以上を含む直接APIリクエストがエラーになること。 +- MCP設定を0件で保存しても、既存のWi-Fi、AI Service、Servo設定が維持されること。 +- 既存YAMLに6件以上あっても配列範囲外アクセスが発生せず、先頭5件だけが読み込まれること。 +- デスクトップ幅とスマートフォン幅で、4つのタブと5件分の入力欄に重なりや横方向のはみ出しがないこと。 +- `m5stack-core2-realtime` と `m5stack-cores3-realtime` をビルドし、埋め込みWeb UIとAPI変更を含めてコンパイルできること。 + +## 戻し方 + +`MCPs (Option)` タブとWeb UIのMCP入出力処理を削除し、`GET /config`、`POST /config`、`SC_ExConfig.yaml` 生成を従来の `llm.type` と `llm.enableMemory` のみに戻す。`LLM_N_MCP_SERVERS_MAX` を10へ戻し、`StackchanExConfig` の上限処理を戻す。MCP設定形式自体は変更しないため、データ移行は不要。 diff --git a/firmware/doc/fw_design.md b/firmware/doc/fw_design.md index e34bbce..94aece8 100644 --- a/firmware/doc/fw_design.md +++ b/firmware/doc/fw_design.md @@ -2,11 +2,16 @@ Notes on FW design, etc. - [Task](#task) -- [ESP-NOW Remote Control Mod](#esp-now-remote-control-mod) -- [Realtime API Function Calling](#realtime-api-function-calling) +- [Mod](#mod) + - [ESP-NOW Remote Control Mod](#esp-now-remote-control-mod) +- [Function Calling](#function-calling) - [Avatar Expression](#avatar-expression) +- [Wi-Fi config portal](#wi-fi-config-portal) - [Web App](#web-app) + - [Home page](#home-page) + - [Config page](#config-page) - [Personalize page](#personalize-page) +- [Status Monitor](#status-monitor) - [Head Touch Sensor](#head-touch-sensor) @@ -23,7 +28,8 @@ Notes on FW design, etc. | asyncTtsStreamTask | TTS streaming play | 5 * 1024 | 2 | | webSocketLoopTask | WebSocket processing for LLM Realtime API | 6 * 1024 | 3 | -## ESP-NOW Remote Control Mod +## Mod +### ESP-NOW Remote Control Mod 初期実装では `src/mod/EspNowRemote` に Receiver 固定の Mod を追加する。 @@ -37,7 +43,7 @@ Notes on FW design, etc. - ESP-NOW Mod 実行中は Wi-Fi channel 変更により Web/FTP/Realtime API と干渉する可能性がある。 - ESP-NOW Mod 離脱時は ESP-NOW を停止し、offline mode でなければ Wi-Fi STA の再接続を最大 5 秒待つ。 -## Realtime API Function Calling +## Function Calling ### Avatar Expression @@ -57,9 +63,166 @@ Realtime API ビルドでは、Function Calling により AI が会話中の感 - `json_Functions` は通常 ChatGPT や Gemini Live からも参照されるため、この関数の schema と実行処理は `#if defined(REALTIME_API)` で限定する。 - `systemRole_realtimeAvatarExpression` は Realtime 系 LLM の `load_role()` で `systemRole_memory` または `systemRole_noMemory` に追加する。 + +## Wi-Fi config portal + +SmartConfig は使わず、起動時の Wi-Fi 接続元は YAML の `wifi.ssid` / `wifi.password` のみにする。 + +- SD に設定 YAML がある場合は SD を優先する。 +- SD が無い、または主要 YAML が無い場合は SPIFFS の YAML を使う。 +- `SC_ExConfig.yaml`、`SC_SecConfig.yaml`、`SC_BasicConfig.yaml` の一式が揃っていない場合は通常機能を起動しない。 + - `REALTIME_API` ビルドでは、`SC_SecConfig.yaml` がある場合は Wi-Fi 接続だけ試し、成功したら STA 接続上で設定 Web を起動する。 + - `REALTIME_API` ビルドでは、Wi-Fi 接続できない場合、または `SC_SecConfig.yaml` も無い場合は Config AP を起動する。 + - `REALTIME_API` 以外のビルドでは、不完全な設定を画面に表示し、そのまま待機する。 +- 設定一式が揃っている通常起動時は、`wifi.ssid` が空、または接続に失敗した場合に画面上で Config AP 起動または Offline 起動を選ぶ。 +- Config AP は SSID `StackChanEx-Config-NNNNNN`、password `stackchan` で起動し、`http://192.168.4.1/` の QR コードを画面に表示する。SSID 末尾の 6 桁数字は AP 起動時に生成する。 +- AP モード中は会話機能は offline 相当として扱うが、Web サーバーは動かし続ける。 +- AtomS3R は画面が小さいため QR コードは表示せず、Wi-Fi 接続失敗時は Config AP を直接起動する。 + + ## Web App WebAPI.cpp のインラインアセンブラ(マクロ:IMPORT_FILE)で incbinフォルダ内のhtmlファイルやjsファイルをプログラム領域に埋め込む。 +### Home page +Web アプリの入口 `/` として `home.html` を返す。`home.html` には次の 2 つの導線を置く。 + +- Personalize + - `/personalize.html` に遷移する。 + - Role と Memory の管理を行う。 +- Config + - `/config.html` に遷移する。 + - Wi-Fi、API key、Realtime API 用 YAML 設定、SD から SPIFFS へのコピーを行う。 + +設定用 AP モードで QR に載せる URL も `/` とし、スマートフォンで開いた直後に用途を選べるようにする。 + +### Config page + +- Wi-Fi、AI Service、Servo、MCPs (Option) の設定領域をタブで切り替えて表示する。 +- タブを切り替えても未保存の入力値は保持し、Save は全タブの設定内容をまとめて保存する。 +- Save、Reload、Restart と処理結果のメッセージはタブ領域の外に配置し、どのタブからでも操作可能とする。 +- Reload は全タブの設定値を更新し、現在選択中のタブは維持する。 + +- ファイル構成 + - `incbin/config.html` + - `incbin/config.js` +- 言語 + - ページやダイアログ内の言語は英語版のみ。 +- 概要 + - 画面の入力内容を SC_SecConfig.yaml、SC_BasicConfig.yaml、SC_ExConfig.yaml のフォーマットにしてAPIで設定する。 + - 画面表示時、更新時、Reloadボタン押下時はAPIで設定値を取得して画面の入力値に反映する。 +- 画面構成 + - Wi-Fi + - SSID + - Password (値は'*'で隠す/表示するを切り換え可能とする) + - Realtime AI Service + - ドロップダウン内の以下サービスから選択 + - OpenAI Realtime + - Google Gemini Live + - API Key (値は'*'で隠す/表示するを切り換え可能とする) + - Enable Memory (true or false を設定) + - MCPs (Option) + - MCPサーバーを最大5件設定する。未使用の入力枠は保存しない。 + - 各サーバーに Name、Disabled、URL / Host、Port を設定する。 + - Disabled は `true` / `false` のドロップダウンで選択する。 + - Name、URL / Host、Port の一部だけが入力された場合は保存エラーとする。 + - Servo + - 以下項目を設定。詳細は [Servo Setting Details](#servo-setting-details) に記載 + - Type + - Pin + - Offset + - Center + - Lower limit + - Upper limit + - Enable Takao Base + - Save ボタン + - 画面の入力値をSC_SecConfig.yaml、SC_BasicConfig.yaml、SC_ExConfig.yaml のフォーマットにしてAPIで設定する。 + - Reload ボタン + - APIで現在の設定を取得し、画面の入力値を更新する。 + - Restart ボタン + - 設定内容をシステムに反映するためのシステムリセットを実行。 + +#### Servo Setting Details + +- Type + - ドロップダウン内の以下タイプから選択 + - PWM : SG90PWMServo + - SCS : Feetech SCS0009 + - DYN_XL330 : Dynamixel XL330 + - RT_DYN_XL330 : RTVersion + - M5_SCS : M5StackChan Servo +- Pin (x, y) + - 選んだTypeに応じて選択肢をドロップダウンで提示 (シリアルサーボは(x:RX, y:TX)に読み替え)。任意の値に変更も可。 + - PWM, SCS, DYN_XL330 + - Core2 PortA x:33, y:32 + - Core2 PortB x:36, y:26 + - Core2 PortC x:13, y:14 + - CoreS3 PortA x:2, y:1 + - CoreS3 PortB x:9, y:8 + - CoreS3 PortC x:17, y:18 + - RT_DYN_XL330 + - x:6, y:7 + - M5_SCS + - x:7, y:6 +- Offset (x, y) + - Typeによらないが、Typeを選んだときに x:0, y:0 に初期化。任意の値に変更も可。 +- Center (x, y) + - サーボの初期位置を、選択したTypeに応じて以下のように初期化。任意の値に変更も可。 + - PWM + - x:90, y:90 + - SCS + - x:150, y:150 + - DYN_XL330 + - x:180, y:270 + - RT_DYN_XL330 + - x:180, y:5 + - M5_SCS + - x:150, y:85 +- Lower limit (x, y) + - サーボの可動範囲の下限を、選択したTypeに応じて以下のように初期化。任意の値に変更も可。 + - PWM + - x:0, y:60 + - SCS + - x:0, y:120 + - DYN_XL330 + - x:0, y:220 + - RT_DYN_XL330 + - x:90, y:-5 + - M5_SCS + - x:0, y:0 +- Upper limit (x, y) + - サーボの可動範囲の上限を、選択したTypeに応じて以下のように初期化。任意の値に変更も可。 + - PWM + - x:180, y:90 + - SCS + - x:300, y:150 + - DYN_XL330 + - x:360, y:270 + - RT_DYN_XL330 + - x:270, y:15 + - M5_SCS + - x:300, y:90 +- Enable Takao Base + - ドロップダウンで true か false を選択。Type選択時は false に初期化。 + +#### API +- `GET /config`: JSONで現在の設定値を返す。SPIFFS の設定ファイルが無い場合はデフォルト値またはRAM上の設定値を返す。 + - `source`: `spiffs` または `none` + - `complete`: SPIFFS に `SC_SecConfig.yaml`、`SC_BasicConfig.yaml`、`SC_ExConfig.yaml` が揃っているか + - `sec`: Wi-Fi と API key + - `basic`: Servo 設定 + - `ex`: Realtime AI Service、Enable Memory、最大5件のMCPサーバー設定 +- `POST /config`: POST body の JSON を検証し、SPIFFS に `SC_SecConfig.yaml`、`SC_BasicConfig.yaml`、`SC_ExConfig.yaml` として保存する。 +- `POST /config/restart`: 設定反映のため再起動する。 + +#### 保存処理 +- `SC_SecConfig.yaml` は `StackchanExConfig::saveSecretConfigYaml()` が `deserializeYml()` で構文と `wifi` / `apikey` セクションを検証する。 +- `SC_BasicConfig.yaml` は Servo 関連、`takao_base`、`servo_type` のみを生成する。 +- `SC_ExConfig.yaml` は `llm.type`、`llm.enableMemory`、`llm.mcpServers` を生成する。MCPサーバーは最大5件とし、各要素に `name`、`disabled`、`url`、`port` を保存する。 +- `LLM_N_MCP_SERVERS_MAX` は5とし、設定読込、Web API、MCPクライアント配列で共通の上限として使用する。YAMLに6件以上ある場合は先頭5件だけを読み込む。 +- 保存後は RAM 上の `_secret_config` も更新するが、Wi-Fi 再接続は行わず Web UI から再起動を促す。 +- Save成功時は、設定した値を有効にするため Restart 前に SD カードを抜くよう画面に表示する。 + + ### Personalize page - ファイル構成 - incbin/personalize.html @@ -68,6 +231,7 @@ WebAPI.cpp のインラインアセンブラ(マクロ:IMPORT_FILE)で incbin - ページやダイアログ内の言語は英語版のみ。 - 画面構成 - Role (Custom Instructions) + - Memory #### Role (Custom Instructions) - 構成 @@ -88,6 +252,20 @@ WebAPI.cpp のインラインアセンブラ(マクロ:IMPORT_FILE)で incbin - 画面更新時の動作 - API /memory_get をPOSTし、記憶内容を取得してフォームに表示する。 +## Status Monitor + +`StatusMonitorMod` shows runtime state in tab form on the avatar sub-window. + +| Tab | Contents | +| --- | --- | +| System | Existing system status: firmware version, Wi-Fi IP/MAC, heap, battery. | +| AI Service | AI service name, memory enabled/disabled, MCP server list. | + +The AI Service tab reads `llm.type`, `llm.enableMemory`, and `llm.mcpServers` from `StackchanExConfig`. The old Function Call info view is not shown because it belongs to the previous Function Calling design. + +The graphical tab header is drawn through `Avatar::updateSubWindowCustom()`. This keeps Avatar running and lets `StatusMonitorMod` render directly into the SubWindow during the Avatar draw cycle. +The tabs are touch targets. `StatusMonitorMod` owns tab `box_t` hit areas aligned with the drawn tab rectangles, while physical BtnA/BtnC still move to the previous/next tab. + ## Head Touch Sensor `src/driver/HeadTouchSensor.*` provides the shared polling driver for the official CoreS3 head touch sensor. diff --git a/firmware/incbin/config.html b/firmware/incbin/config.html new file mode 100644 index 0000000..3ea4e3d --- /dev/null +++ b/firmware/incbin/config.html @@ -0,0 +1,393 @@ + + +
+ +Open configuration or personalization.
+ +