Teach のトラブルシューティング¶

IPRO AI Teach でよくある問題をトピック別にまとめています。画面とコンソールのメッセージは、照合しやすいように表示どおりに引用しています。各ツールのページにも、それぞれトラブルシューティングの表があります。

最初に確認すること¶

USB-C ケーブルがデータ通信に対応していること。 充電専用ケーブルではボードは点灯しますが、コンピューターは USB デバイスを認識しません。
USB-C が Reef 自身の USB-C（USB1）に接続されていること。 IPRO Debug Probe の USB ポートはコンソールと書き込みにのみ使われ、Teach ツールは使いません。
ボードで Edge AI ファームウェアが動作していること。 コンソールの起動ログに IPRO7AI Reef Teach: image, voice, sensor と mode: 行があります。
ボードのモードがページと一致していること。 Teach には image、Audio には voice、Sensor には sensor です。一致しない場合、ページ上部に Switch to … が表示されます。
ボードの USB シリアルポートをほかのプログラムが使用していないこと。 一度に開けるプログラムは 1 つだけです。

接続とモード¶

症状	原因	対処
コンピューターに Reef の USB デバイスが表示されない	ケーブルが充電専用、またはファームウェアが起動していない	データ通信対応のケーブルを使います。コンソールの起動ログを確認します
LED2（電源）が消灯している	USB-C に電源が来ていない、または過電流でヒューズが作動した	別のケーブルや USB ポートを試します。40 ピンヘッダーに取り付けた拡張ボードを外します
Studio に `The Reef is in <mode> mode.` と表示される	ボードが別のモードになっている	ページの Switch to … を押します
Switch to … の後に `This Reef's firmware runs one Teach only.` と表示される	ボードで動作しているのが Edge AI ファームウェアではなく、単一ツールのファームウェア	Edge AI ファームウェアの書き込みのとおりに `ipro_reef_teach` を書き込みます
Switch to … の後に `The Reef did not switch.` と表示される	ポートが使用中であるなどの理由で、切り替えコマンドが完了しなかった	ボードのポートを使っているほかのプログラムを閉じてもう一度押すか、コンソールで `mode <mode>` と入力します
ページが別のボードを見つけた	複数の Reef が接続されている	1 台ずつ接続します。コマンドラインでは `--port` を使います
起動ログまたは `ipro-ai model list` に `install_interrupted` と表示される	前回のデプロイが完了しなかった（電源断、リセット、ケーブルの抜け）	もう一度デプロイします
起動ログまたは `ipro-ai model list` に `crc` と表示される	コミット済みのモデルが破損している	もう一度デプロイします
起動ログまたは `ipro-ai model list` に `no_xip` と表示される	パーティションを読み取れない	`partition_reef_teach.toml` でファームウェアを書き込み直します
デプロイが拒否され、メッセージに `size` が含まれる	モデルがスロットより大きい	より小さいモデルを使います（センサーでは Medium または Small、画像では MobileNetV1 0.25）

書き込み¶

症状	原因	対処
書き込みツールは終了したが、出力に `[All Success]` がない	書き込みに失敗した。ツールは失敗時も 0 で終了する	ダウンロードモードとポートを確認して、もう一度書き込みます
ハンドシェイクは成功するが、Flash ID が `00000000`、ErrorCode が `003D`	Flash ピンの設定が間違っている	コマンドに `--chip-variant IPRO7AI` を追加します
書き込みツールがハンドシェイクの失敗を報告する、またはポートを開けない	ターミナルプログラムがまだポートを使用している、またはボードがダウンロードモードではない	ターミナルプログラムを閉じます。もう一度ダウンロードモードに入ります
macOS で `utils/ipro_flash.sh` が `[Errno 83] Device error`、ErrorCode `0003` を報告する	プローブが Reef をダウンロードモードにした直後、プローブのポートが一時的に消える	1～2 秒待ってから、同じコマンドをもう一度実行します
macOS でシリアルポートを開くと応答しなくなる	`/dev/tty.*` デバイスを使った	`/dev/cu.*` を使います
コンソールに何も表示されず、`reboot_dl` も効かない	ファームウェアがハングしており、シェルが動作していない	ボタン（SW1 を押したまま SW2 を押し、SW1 を離す）またはプローブでダウンロードモードに入り、書き込み直します
コンソールにまったく文字が表示されない	ケーブルの両端のピン順が逆になっていない、または開いているプローブのポートが違う	両端のピン順が逆のケーブルを使います。プローブの「IPRO7 UART」ポートを 115200 baud で開きます
別のボードに書き込んでしまった	複数のボードが接続されていて、`--port` で別のボードを指定した	先にコンソールの起動ログでボードを確認します。迷ったらボードを 1 台だけ接続します
Edge AI ファームウェアを書き込んだ後、画像とセンサーにモデルがない	以前のファームウェアは標準パーティションテーブルを使っており、スロットの位置が異なる	想定どおりの動作です。Studio からもう一度デプロイします
Studio の Board ページの Flash で書き込んだ後、Teach ツールが正しく動作しない	Board ページは標準パーティションテーブルで書き込み、mfg ペイロードを書き込まない	Edge AI ファームウェアの書き込みのとおりに、IntelProCube で書き込み直します

画像認識¶

症状	原因	対処
カメラの一覧に IPRO7 UVC Cam がない。Studio に `No board with the Teach firmware on USB.` と表示される	ボードが `image` モードではない、またはケーブルが充電専用	`image` モードに切り替えます。データ通信対応のケーブルを使います
Teach ページに `IPRO AI Studio is not allowed to use the camera.` と表示される	macOS のカメラの権限が拒否された	システム設定 → プライバシーとセキュリティ → カメラで IPRO AI Studio をオンにして、Studio を開き直します
Windows で Teach ページにカメラ映像が表示されない	システムのカメラのプライバシー設定で、デスクトップアプリがブロックされている	設定 → プライバシーとセキュリティ → カメラで、デスクトップアプリがカメラにアクセスできるようにします
macOS でどのプログラムにもカメラ映像が表示されない	ほかのプログラムがまだカメラを使用している	そのプログラムを終了し、USB-C を抜き差しします
コンソールに `no camera answers` が繰り返し表示される	カメラが接続されていない、または SW7 が CAM になっていない	USB-C を抜き、カメラケーブルを確認して、SW7 を CAM にします
40 ピンヘッダーの一部の GPIO が動作しない	それらのピンはカメラスイッチを経由しており、SW7 が CAM になっている	カメラ使用中は正常です。それらの GPIO を使うには SW7 を GPIO にします（カメラの電源は切れます）
映像に `NO MODEL: NO MODEL IN MFG` と表示される	モデルがまだデプロイされていない	Teach ページからデプロイします
映像に `NO MODEL: DEPLOY INTERRUPTED` と表示される	前回のデプロイが完了していない	もう一度デプロイします
映像に `NO MODEL: NO MFG PARTITION` と表示される	書き込みに使ったパーティションテーブルに mfg パーティションがない	`partition_reef_teach.toml` でファームウェアを書き込み直します
映像に `NO MODEL: WRONG MODEL` と表示される	スロットに別の種類のモデルが入っている	もう一度デプロイします
デプロイ後、Camera エリアに `The board went away. Waiting for it…` と表示される	ボードが再起動中	正常です。カメラは自動的に戻ります。戻らない場合は USB-C を抜き差しします
学習結果に `<A> taken for <B>` と表示される	記録中に物体が枠から出た	両方のクラスで Review を押し、不良なクロップを除外して、再度学習します
実際の使用で、あるクラスが別のクラスとしてよく認識される	一部の角度や照明でのデータが不足している、または 2 つの見た目が似ている	その角度と照明で追加記録し、学習してデプロイします

声紋認識¶

症状	原因	対処
Audio ページにボードに声紋モデルがないと表示される、またはコンソールに `NO MODEL` と表示される	ボードに有効な声紋モデルがない	`--mfg` 付きで書き込み直すか、`ipro-ai deploy` で声紋モデルをデプロイします。声紋モデルの変更を参照してください
ボードのシリアルポートを開けない	ほかのプログラムが使用している	そのポートを使っているほかのプログラムを閉じて、もう一度試します
登録が `Too little speech was heard` で失敗する	聞き取れた発話が少なすぎる	もっと大きな声で、または近くで話し、時間が終わるまで読み続けます
登録されていない人に、登録済みの人の名前が表示され続ける	通常モードとしては名前しきい値が低い。特にスピーカー再生時	Stranger モードをオンにするか、Name match を上げます
登録済みの人が Speaker k と表示されることが多い	実際の使用時とは異なる場所、マイク、音量で登録した、または名前しきい値が高すぎる	実際の位置で Reef のマイクを使って登録し直すか、Name match を少し下げます
1 人が複数の話者に分かれる	新規話者しきい値が高すぎる	New speaker を下げるか、どちらかに名前を付けます
誰も話していないのにラベルが表示される	音楽、テレビ、その他の継続的な音が発話とみなされている	背景音を取り除き、静かな部屋で使います
声紋モデルを変更した後、登録済みの人が全員いなくなった	声紋はモデルに結び付いている	新しいモデルで登録し直します
漢字を含む名前をコンソールで入力できない	コンソールは ASCII のみ受け付ける	Audio ページで名前を入力します

センサー認識¶

症状	原因	対処
Put it on the board に `Connect a Reef running the Edge AI firmware to its own USB-C port.` と表示される	`sensor` モードのボードが見つからない	ファームウェアとケーブルを確認します。USB-C は Reef 自身のポートに接続する必要があります
`Not ready to train`	ボードが接続されていない、または記録のあるクラスが 2 つ未満（異常検知ではちょうど 1 つが必要）	ボードを接続し、各クラスを記録します
`too short: hold for at least one window`	押していた時間が 1 ウィンドウ未満	もっと長く押し続けます
`<k> of <n> classes have no held-out data`	一部のクラスの 1 回あたりの記録が短すぎる	毎回ウィンドウ長の 2 倍以上押し続けます
Import CSV… で `<N> columns` と表示される	CSV の列数がソースのチャネル数と一致しない	1 チャネル 1 列、1 サンプル 1 行にします
Open… で `Not a Sensor Teach folder` と表示される	フォルダーに `sensor_teach.json` がない	Save… で保存したフォルダーを開きます
デプロイが `the board did not come back with the model within 30 s` で失敗する	ボードが 30 秒以内に新しいモデルで復帰しなかった	USB-C を抜き差しし、コンソールの起動ログを確認して、もう一度デプロイします
ソースを変更した後、学習済みのモデルが動作しない	モデルは学習に使ったソースでのみ動作する	新しいソースで記録し直して学習します
リアルタイムの結果で、状態の切り替わり時に `UNKNOWN` が表示される	ウィンドウに両方の状態が含まれている	正常です。連続するいくつかの結果から判断してください
重いが正常な負荷で、異常検知がアラームを出す	正常データがその負荷をカバーしていない	すべての正常な負荷と速度で正常データを記録し、学習し直します

実行中の問題とウォッチドッグ¶

症状	原因	対処
ボードが勝手に再起動する（コンソールに起動ログが再び表示される）	システムが停止し、約 5.6～8 秒後にファームウェアのウォッチドッグがボードを再起動した（例：NPU が破損したモデルを実行した）	ボードは同じモードとモデルで復帰します。検証済みのモデルをもう一度デプロイします。そのとき行っていた操作とコンソールの出力を記録し、INTELPRO に報告してください
ウォッチドッグが有効かどうかを確認したい		コンソールで `watchdog` と入力すると状態が表示されます。`watchdog test` はフィードを停止し、ボードは数秒以内に再起動するはずです
デプロイ中に USB-C が抜けた、またはボードがリセットされた	コミット前にデプロイが中断された	そのツールにはモデルがありません（`install_interrupted`）。もう一度デプロイします。ほかの 2 つのツールのモデルには影響しません

ipro-ai コマンドライン¶

ipro-ai のデバイスコマンドとモデルコマンドは、決まった終了コードで結果を返します。--json を付けると、標準出力には 1 つの JSON ドキュメントだけが出力され、その error.type がエラーの種類を示します。

終了コード	意味	対処
`0`	成功
`1`	チェックに失敗：パッケージの破損、`verify` の不一致、またはデプロイ後に読み戻した CRC やサイズが正しくない	ボードのモデルの CRC がパッケージと一致するか確認します。パッケージを作り直します
`2`	使用方法のエラー：引数の誤り、ファイルを読み取れない、`--port` なしで USB 上に複数のボードがある	引数を修正します。`--port` でボードを指定します
`3`	デバイスが見つからない、またはシリアルポートが消えた	USB-C ケーブルとファームウェアを確認します。`ipro-ai device list` を実行します
`4`	ボードが拒否した（例：`TDEP ERR crc`）、または応答を解釈できなかった	応答の内容に従って対処し、もう一度デプロイします
`5`	タイムアウト：ボードが応答しなかった、または再起動後に復帰しなかった	コンソールの起動ログを確認します。`ipro-ai device list` を実行します
`6`	非互換：ファームウェアにその機能がない（例：Edge AI ファームウェアにはロールバックがない）、ツールや ABI が一致しない、またはモデルが収まらない	メッセージに従い、適切なモデルやコマンドを使います
`7`	ツールの内部エラー	`--json` の出力を保存し、INTELPRO に報告してください

問題の報告¶

INTELPRO に問い合わせる際は、次の情報を添えてください：

起動から問題発生までのコンソール出力全体（IPRO Debug Probe の「IPRO7 UART」ポート、115200 baud）。
ipro-ai device info --json の出力：ファームウェア、プラットフォームのバージョン、モード、ボード上のモデル。
IPRO AI Studio のバージョン（Windows では Help メニュー、macOS ではアプリケーションメニューにある About IPRO AI Studio）と、お使いの OS。
行った手順と、画面に表示された正確なメッセージ。