コンテンツにスキップ
SMI Developer Center

BATCAM FX 概要

BATCAM FX 開発概要

1. はじめに

BATCAM FX は SM Instruments のリアルタイム音響カメラです。1600×1200 解像度の光学映像と 40×30 ビームフォーミング（BF）マップを併せて提供し、音が発生している位置を映像上に可視化できます。

本ドキュメントは BATCAM FX 連携開発の出発点です。装置が提供するインターフェースを一覧で紹介し、最も代表的な連携作業であるオーバーレイ映像合成のデータフローと接続方法を案内します。パラメータ制御、ROS 2 統合、ファームウェアアップデートなどの詳細なトピックは、それぞれの詳細ドキュメントへリンクしています。開発者センター全体の構成や他製品（BATCAM FX2、FX Viewer）のドキュメントについては、開発者センターを始めるを参照してください。

2. 提供インターフェース一覧

インターフェース用途関連ドキュメント
RTSPカメラの原本映像ストリームの受信。ファームウェア 1.0.3 以上では、装置が自ら合成したオーバーレイ映像も RTSP で提供できます。オーバーレイパラメータ
WebSocket + Protobufビームフォーミング（BF Map）・オーディオ・AI 部分放電（PRPD）分類結果のリアルタイムストリーミング本ドキュメント、Python Protobuf サンプル
REST APIアカウント管理、装置設定（ネットワーク・ファームウェア・再起動・機器情報）、イベントトリガー、ビームフォーミング・オーバーレイパラメータ、ROS Domain IDBATCAM FX API プレイグラウンド
ROS 2トピック/アクションベースのデータ受信および設定（v1.0.3b 開発ファームウェアより対応）ROS Integration
ファームウェアアップデートWeb ページまたはシェル（SSH）を通じたファームウェアのインストールWeb アップデート、シェルアップデート

REST API の全エンドポイント仕様は API プレイグラウンドで確認でき、ブラウザから直接呼び出して試すことができます。WebSocket で送信されるメッセージのフォーマットは fx-stream-protocol スキーマと Python Protobuf サンプルのドキュメントを参照してください。

3. オーバーレイ映像合成のデータフロー

BATCAM FX のデータは、RTSP を通じたカメラの原本映像データと、WebSocket を通じた Protobuf プロトコルでエンコードされたデータとして送信されます。オーバーレイされた映像を直接取得したい場合は、以下の順序で映像を合成します。

BATCAM FX オーバーレイ映像合成のデータフロー図: RTSP の原本映像と WebSocket/Protobuf のビームフォーミングデータを組み合わせ

  1. RTSP（rtsp://{device_ip}/raw）から原本映像を受信します。

  2. WebSocket を通じて Protobuf 形式でエンコードされた Beamforming メッセージを受信し、これをデコードして合計 1200 個の Float 値で構成される配列（Float Array）に変換します。この配列は 40x30 構造の BF Map を 1x1200 構造に展開したもので、25Hz 周期で送信されます。

  3. Float Array を補間（インターポレーション）して、オーバーレイする画像を生成します。40×30 の BF Map は 1600×1200 の光学映像に合わせてマッピングされます。

  4. RTSP 映像ストリームと受信した音源データを組み合わせて、リアルタイムで Beamforming オーバーレイ映像を生成できます。

💡 参考: ファームウェア 1.0.3 以上では、BATCAM FX が自らオーバーレイ画像を合成した RTSP ストリームの提供に対応しているため、直接合成しない構成も可能です。設定方法は オーバーレイパラメータのドキュメントを、BF Map の座標系と Listening Point の指定は Listening Point 座標のドキュメントを参照してください。

4. 接続情報と認証

以下の表の {device_ip} は装置の IP アドレスです。IP 設定は REST API（/setting/ip）で照会・変更でき、装置のファームウェアバージョンは機器情報照会 API（/setting/status）で確認できます。詳細な仕様は API プレイグラウンドを参照してください。

項目値備考
RTSP 映像ストリームrtsp://{device_ip}/rawユーザー認証が必要
WebSocket ストリーミングws://{device_ip}/wsSubProtocol の指定が必須
WebSocket SubProtocolSubscribeサンプルによっては小文字の subscribe 表記も使用されます
REST APIhttp://{device_ip}装置が API を直接提供
ファームウェアアップデートページhttp://{device_ip}/firmwareWeb アップデートを参照
ファームウェアアップデートログws://{device_ip}/firmware/wsアップデート進行ログの受信
認証方式HTTP BasicREST・RTSP・WebSocket 共通

BATCAM FX には、デフォルトで admin、user の 2 つのアカウントがあらかじめ設定されています。アカウントの作成は /auth/create、全アカウント一覧の照会は /auth/all、個別アカウントの照会・削除・パスワード再設定は /auth/account エンドポイントで行います。

⚠️ 注意: 出荷時の初期パスワードは必ず変更してからご使用ください。

Authorization ヘッダーの構成 — ご使用の WebSocket ライブラリが認証に対応している場合は Username と Password を指定し、対応していない場合は WebSocket 接続を要求する Header に Authorization キーを追加し、{username}:{password} の文字列を base64 でエンコードして含めます。

Authorization: Basic base64({username}:{password})


# 例: username=admin, password=password の場合
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

購読（Subscribe）の開始 — WebSocket を接続した直後にメッセージが受信されるわけではなく、Protobuf の事前生成コードで提供される Subscribe オブジェクトを利用して、必要なデータストリームに対する購読をカメラへ送信する必要があります。ストリームごとの Subscribe ID は次のとおりです。

Subscribe IDメッセージ内容送信頻度
0Beamforming40×30 BF Map（1×1200 Float 配列）25 Hz
1WsAudio8000 サンプルの Float オーディオ（200 kHz × 40 ms）25 Hz
2LPointAudioListening Point 3 チャンネルのビームフォーミングオーディオ25 Hz
3PrpdAI 部分放電分類結果（ファームウェア v1.0.3c 以上、AI PRPD 分類を参照）4 Hz

5. サンプルコードと Protobuf スキーマ

Protobuf と WebSocket を利用してデータを送受信するサンプルは、当社の GitHub（C# サンプル）で公開されています。当該サンプルは上記のオーバーレイ合成の過程をすべて含んでおり、GUI サンプルも含まれています。

次は、WebSocket 接続、購読の送信、最初のメッセージのデコードまでの流れを示す Python のサンプルです。

import asyncio
import base64
import websockets
import fx_protocol_pb2 as pb  # fx-stream-protocol の事前生成ファイル


async def stream(ip: str, user: str, password: str):
    cred = base64.b64encode(f"{user}:{password}".encode()).decode()
    headers = {
        "Authorization": f"Basic {cred}",
        "Sec-WebSocket-Protocol": "subscribe",
    }
    uri = f"ws://{ip}/ws"


    async with websockets.connect(uri, additional_headers=headers, subprotocols=["subscribe"]) as ws:
        # Beamforming(ID 0) の購読を開始
        sub = pb.Subscribe()
        sub.id = 0
        sub.type = pb.Subscribe.SUBSCRIBE
        await ws.send(sub.SerializeToString())


        async for raw in ws:
            event = pb.Event()
            event.ParseFromString(raw)
            if event.WhichOneof("data") == "beamforming":
                bf = event.beamforming
                print(f"bf count={len(bf.bf)} gain={bf.gain}")  # bf count=1200


asyncio.run(stream("192.168.0.30", "admin", "password"))

環境設定、Python バインディングの生成、メッセージタイプ別の詳細なサンプルは、Python Protobuf サンプルのドキュメントで段階的に案内します。

Protobuf をエンコード/デコードするために必要なスキーマと事前生成ファイルは、当社の OSS GitLab（fx-stream-protocol）で確認できます。本ドキュメントは v0.0.2 タグの事前生成ファイルを基準に案内しており、他のバージョンはリポジトリのタグ一覧で確認してください。

6. よく発生する問題（Troubleshooting）

症状原因解決
WebSocket 接続が確立されないSubProtocol の未指定接続時に WebSocket SubProtocol を必ず Subscribe に指定します（ライブラリの subprotocols オプション）。
接続はされるがメッセージが受信されない購読（Subscribe）メッセージの未送信接続の直後に Subscribe オブジェクト（id, type）を送信して購読を開始します。（C# 参考リンク）
認証エラー（401）で接続が拒否される認証情報の欠落、または誤ったアカウント情報ライブラリの認証機能に Username/Password を指定するか（C# 参考リンク）、Authorization ヘッダーを上記の形式で直接構成します。アカウント・パスワードが正しいかご確認ください。

7. 次のステップ