LinuxからMesh NCPを制御する:Silicon Labs BGAPI入門
Silicon Labsの公式pyBGAPIサンプルでLinuxとMesh NCPを接続。XAPIとファームウェア、UARTフロー制御、起動イベント、ノードとProvisionerの役割を整理。
以前、Bluetooth Mesh ゲートウェイのチップ選定について書いた際、Linux ホストが業務ロジックを担当し、Silicon Labs のモジュールが無線プロトコルスタックを担当して、その間をシリアル通信でつなぐ構成に触れた。
一言で済む話に聞こえる。しかし実際に接続を始めると、「シリアルポートは開けるのに、モジュールが指示を受け付けない」というところで詰まりやすい。
原因は、照明を点灯するための特別なコマンドが一つ足りないことではなく、モジュールに書き込まれたファームウェア、ホストが使用する API 定義、シリアルのフロー制御、そして Mesh デバイスのネットワーク内での役割といった前提がそろっていないことが多い。
この記事では、公式の NCP 資料と Python サンプルをもとに、この接続経路を段階ごとに整理する。本文はソースコードに基づく接続ガイドであり、特定の開発ボードを使った実機での結合検証は完了していない。具体的なピン、ボーレート、ファームウェアのコンポーネントは、手元のハードウェアと SDK に照らして確認する必要がある。
Linux ホストが制御するのはプロトコルスタックへの入口
NCP、すなわちネットワークコプロセッサモードでは、アプリケーションロジックはホスト上で動作し、Bluetooth プロトコルスタックはターゲットチップ上で動作する。Silicon Labs は両者の間のコマンド、応答、イベントを BGAPI で定義しており、UART は一般的な通信手段である。[1][2]
経路は次のように捉えられる。
Linux の業務プログラム → BGAPI ホストライブラリ → シリアルポート → Silicon Labs の NCP ファームウェア → Bluetooth Mesh ネットワーク。
BGAPI は Silicon Labs のホストインターフェースプロトコルであり、無線上の Mesh プロトコルでも、任意の Bluetooth シリアルモジュールが解釈できる AT コマンドセットでもない。
ホストがコマンドを送ると、ターゲットから応答が返り、イベントも非同期に通知される。「バイト列を送って 1 秒待つ」だけのループを書き、例外が出なかったことをもって操作完了とみなすことはできない。
ここには完了の段階にも違いがある。シリアルへの書き込み成功、ターゲットによるコマンドの受け付け、Mesh の相手側からのステータス応答、照明の実際の状態変化は、同じ結果ではない。トラブルシューティング用のログでは、これらの段階を分けて記録すべきだ。
ステップ 1:ファームウェアとホスト API が対応しているか確認する
チップの型番が Bluetooth に対応していても、現在書き込まれているファームウェアが必要な Mesh NCP 機能を提供しているとは限らない。
公式の pyBGAPI サンプルは、通常の Bluetooth サンプルと Bluetooth Mesh サンプルを区別している。Mesh サンプルは sl_bt.xapi と sl_btmesh.xapi という二つの API 定義を使用する。通常の BLE ファームウェア、Mesh ノード用ファームウェア、プロビジョニング管理向けファームウェアも、いずれも「NCP」と呼ばれているからといって交換可能ではない。[1]
XAPI は、ホストライブラリがコマンドをどうエンコードし、返された内容をどう解析するかを記述する。ターゲットのファームウェアとホストの API 定義が一致しない場合、コマンドがサポートされない、パラメータが不足する、解析で例外が発生するといったことがあり得る。公式サンプルは起動時に一部のバージョン情報を比較して警告を出すが、その警告チェックは互換性の全面的な確認に代わるものではない。
始める前に、次の四点を書き出しておくことを勧める。
- 開発ボードとチップの型番、および使用するハードウェアインターフェース。
- ファームウェアのサンプル名、SDK のバージョン、有効化されている Mesh コンポーネント。
- ホストプログラムのバージョン、API 定義ファイルの入手元、Python ライブラリのバージョン。
- ターゲットの役割:プロビジョニングされるノードなのか、ほかのノードを管理する Provisioner なのか。
問題が起きてからすべてのコンポーネントを繰り返しアップグレードするより、この短いチェックリストのほうが役に立つ。アップグレードでインターフェースが変わる可能性があり、最新のホストライブラリが古いファームウェアと常に互換性を持つとは仮定できない。
ステップ 2:UART とフロー制御の設定をそろえる
シリアルデバイスのノードが存在することは、Linux がシリアルインターフェースを認識したことを示すだけで、ターゲットのファームウェアが準備できていることまでは示さない。
配線前には、ボードの資料に従って電圧レベル、GND、TX/RX、およびハードウェアフロー制御を有効にする場合の RTS/CTS を確認する。RS-232 レベルのインターフェースを、そのままチップの UART ピンにつないではいけない。開発ボードの仮想シリアルポートを経由する場合は、オンボードデバッガのシリアル設定も確認する必要がある。
旧版の AN1259 にある NCP サンプルでは、ハードウェアフロー制御がデフォルトで有効になっており、ターゲット側と開発ボード側のフロー制御設定を一致させる必要があると特に強調されている。[2] これは、シリアルポートは開けるのにデータが先へ進まないという、よくある現象の説明になる。一方が相手からのフロー制御信号を待っているためだ。
ただし、そこから「すべての BGAPI インターフェースには必ず 4 本の信号線が必要」と一般化することはできない。使用する通信方式とフロー制御の設定は、ファームウェアとハードウェアによる。本文での提案は、RTS/CTS がデフォルトで有効なサンプルから始めるなら、まずその設定を一式維持して一致させることだ。データ線だけを 2 本つなぎながら、ソフトウェア側ではフロー制御信号を待たせたままにしない。
また、シリアルポートをターミナルプログラムと業務プロセスが同時に使用していないこと、現在のユーザーにアクセス権があることも確認する。権限の問題があれば、まずデバイスの権限とユーザーグループを調べ、長期的に root で動かすことを標準的な解決策にしない。
ステップ 3:公式の最小サンプルで起動までの経路を確認する
今回確認した公式 pybgapi-examples のコミットは 87d004f である。[1] コミットを固定すると再現しやすくなるが、このコミット自体が手元のあらゆる SDK への対応を保証するわけではない。まず、同梱されている API 定義とターゲットのファームウェアを照合すべきだ。
新しいローカルディレクトリで、独立した Python 環境を用意し、サンプルの引数を確認できる。
git clone https://github.com/SiliconLabs/pybgapi-examples.git
cd pybgapi-examples
git checkout 87d004f1db3993bfa35783bec1ac58c32b5303e4
python3 -m venv .venv
. .venv/bin/activate
python -m pip install pybgapi
python example/btmesh_empty/app.py -h
インストールに成功したら、実際にインストールされたライブラリのバージョンを記録する。ここでは、検証していない「どの環境でも使えるバージョンの組み合わせ」は提示しない。SDK が一致しない場合は、ファームウェアに対応するサンプルと API ファイルに切り替え、インターフェースを改めて確認する必要がある。
再起動してもよいテストボードを使用し、ファームウェアが対応していて、シリアル設定も一致することを確認したうえで、公式サンプルでは次のように位置引数でシリアルポートを指定できる。
python example/btmesh_empty/app.py /dev/ttyACM0
/dev/ttyACM0 は例示用のパスなので、実際のデバイスに置き換える。リポジトリ内の接続用ヘルパー関数は開発ボードのデフォルト設定を対象としている。シリアルのパラメータを変える場合はライブラリのインターフェースに従って調整し、存在しないボーレートやフロー制御のオプションをコマンドに勝手に追加してはいけない。[3]
このプログラムはターゲットデバイスを操作するものであり、読み取り専用の検出処理ではない。確認したコードでは、起動時に再起動を要求し、bt_evt_system_boot を受信すると btmesh.node.init() を呼び、その後、サンプルがノード初期化イベントを処理する。ノードが未プロビジョニングであれば、未プロビジョニング状態のアドバタイズを開始する。[3][4]
この段階の目標は、ホストとターゲットの間で起動とノード初期化が完了することを確認することであり、家庭の照明をすぐに制御することではない。
公式リポジトリの README には、Mesh サンプルの reset で元のノード設定が消去されるという記述が残っている。一方、今回確認した BtMeshApp.reset() のコードが呼んでいるのは bt.system.reboot() であり、両者は一致しない。本文では固定したコミットのコードに基づいて説明し、サンプルの起動をそのまま工場出荷状態への初期化と同一視しない。実際に使用する際は、使用バージョンの動作を確認し、特に本番ネットワークへ参加済みのデバイスで、意味が不明確な reset を試さないこと。[1][3]
ステップ 4:誰がプロビジョニングし、誰が制御するか決める
btmesh_empty の基底クラスが初期化するのは Node の役割である。未プロビジョニング状態のアドバタイズは「このノードがネットワークへの参加を待っている」という意味であり、「このノードがほかの照明のプロビジョニングを始める」という意味ではない。
ゲートウェイで未プロビジョニングのデバイスをスキャンし、ネットワーク上の識別情報を割り当てて設定するなら、SDK の Host Provisioner の経路に沿って設計し、対応するファームウェア、役割、ホストアプリケーションを確認する必要がある。Empty サンプルの後ろに照明を点灯する呼び出しを 1 行追加するだけでは済まない。[1][2]
デバイスのプロビジョニングが成功していても、アプリケーション層の設定まで自動的に完了するわけではない。照明を制御するには、対応するエレメントとモデル、使用する AppKey、モデルのバインド方法、制御先がユニキャストアドレスかグループアドレスか、サブスクリプションの関係が正しいかを把握する必要がある。
これらの関係はBluetooth Mesh のプロビジョニングは成功したのに、なぜ照明を制御できないのか?で詳しく説明している。シリアル接続の NCP はプロトコルスタックへアクセスする入口を提供するだけで、これらの手順を省略してくれるわけではない。
最初の結合確認では、制御側を一つ、テストノードを一つだけ使うことを勧める。まずモデルの設定を明確にし、それから操作を 1 回実行してステータスを 1 回確認する。単一デバイスでの経路が明確になってから、グループ宛ての送信、再試行、複数デバイスの同期を取り入れる。
ステップ 5:イベントループを通信のために空けておく
公式サンプルの共通クラスはイベントを受信し、対応するハンドラへ渡す。[1][3] ここはホストプログラムが複雑になりやすい箇所でもある。メッセージを受け取ったついでにクラウド API を呼び、データベースへ書き込み、時間のかかる計算をすると、後続のイベントがすべて滞ってしまう。
私の提案は、通信処理をできるだけ短く保つことだ。メッセージを解析・検証し、必要なコンテキストを記録したら、時間のかかる業務処理はほかのワーカーに渡す。これはアプリケーション設計上の提案であり、このサンプルのすべてのスレッド動作について性能を保証するものではない。
コマンドの処理では、タイムアウト後にどうするかも明確にしなければならない。結果を受信していなくても、ターゲットデバイスが実行しなかったとは限らない。そのまま再送すると、操作が 2 回実行される可能性がある。再試行するかどうか、要求とステータスをどう対応付けるかは、具体的な API、モデル、業務上の意味に合わせて設計する必要がある。
ホストプロセスの再起動と NCP の再起動も混同できない。再接続後はまずターゲットの状態を確認し、それから何を復旧するか決めるべきだ。再接続のたびに無条件でノードを消去したり、ネットワークを作り直したり、プロビジョニングを繰り返したりしてはいけない。鍵、アドレス割り当て、デバイスの対応関係をどこに保存し、どうバックアップするかは、複数デバイスの段階に進む前に明確にしておく必要がある。
行き詰まったら、層ごとに切り分ける
| 観測された現象 | 優先して確認すること | まだ導けない結論 |
|---|---|---|
| シリアルデバイスがない、または開けない | ドライバ、接続、権限、デバイスの占有 | チップが Mesh に対応していない |
| シリアルポートは開けるが、起動イベントを受信できない | ファームウェアの種類、ボーレート、フロー制御、リセット方法、API による解析 | 無線信号が弱すぎる |
| 起動イベントは見えるが、コマンドがサポートされない | API とファームウェアのバージョン、コンポーネント、役割、初期化順序 | 送信回数を増やせば解決する |
| Mesh の初期化は成功したが、照明を制御できない | プロビジョニング、AppKey、モデルのバインド、宛先アドレス、サブスクリプション | BGAPI の通信経路が必ず壊れている |
| 小規模では正常だが、負荷が増えると不安定になる | イベント処理にかかる時間、バッファ、フロー制御、再試行方針 | すべての問題は無線リレーに起因する |
各段階で観測可能な結果を残すほうが、最初から完全なゲートウェイを作るより問題を特定しやすい。まずホストと NCP が正しく対話できることを示し、次に Mesh の設定が正しいことを示して、最後に Matter と上位の業務ロジックへ接続する。
これは以前のゲートウェイ結合検証の受け入れチェックリストにもつながる。「シリアル送信が成功した」という段階から、スマートフォン上で正しいデバイス状態を確認できる段階までには、個別に検証すべき経路がまだいくつもある。
参考資料
確認日:2026-11-09。今回は公式のオンライン SDK ドキュメントページの読み込みがタイムアウトしたため、本文はコミットを固定した公式サンプルと、バージョンが明記されたアプリケーションノートを根拠としている。最新 SDK のすべてのインターフェースを網羅しているとは主張しない。
- Silicon Labs pyBGAPI Examples:コミットを固定した README。NCP の役割分担、API の整合、Node と Provisioner の役割、およびサンプルの説明。
- AN1259:Bluetooth Stack v3.x and Higher in NCP Mode,Rev. 1.5。2、16、41、47~49 ページなど。PDF の冒頭には、Simplicity SDK Suite 2024.12.2 のリリース後に廃止されたことが明記されている。本文では対応する旧サンプルのアーキテクチャとフロー制御の説明にのみ使用し、画面、パス、コマンドが最新版でも同じであるとは保証しない。
- 公式のホスト共通クラスとシリアル接続用ヘルパー。
- 公式 Bluetooth Mesh Empty サンプル。
AI生成の概念図です。製品の実測写真、実際の画面、配線図ではありません。
コメント・議論
質問や実践の経験をお寄せください。コメントは承認後に表示されます。メールアドレスは公開されません。 コメントのプライバシー
コメントを読み込み中…