FX ROS 시스템 통합 개요

개요

BATCAM FX는 v1.0.3b 개발 펌웨어 버전부터 ROS 2 기반 데이터 송신을 지원하며, 해당 기능은 정식 릴리스 펌웨어 v1.0.3에 포함되어 있습니다. 이 문서를 통해 BATCAM FX가 퍼블리시하는 ROS 2 토픽(빔포밍 맵, 오디오, 영상, PRPD 분류 결과)을 호스트 PC의 ROS 2 노드에서 구독하고, ROS 2 액션으로 빔포밍·오버레이 설정을 제어할 수 있습니다.

ROS 2 데이터 채널은 기존 데이터 채널(RTSP 영상, WebSocket/Protobuf)과 독립적으로 동작합니다. 기존 데이터 채널에 대해서는 BATCAM FX 개요 문서를 참고하시기 바랍니다.

ROS 2 데이터 채널은 기존 데이터 채널과 독립적으로 작동합니다.

BATCAM FX는 데이터 송신을 위해 FX Stream Message 타입을 사용합니다. 카메라에는 ROS 2 Humble Hawksbill 기반으로 빌드된 바이너리가 펌웨어에 포함되어 있으며, 메세지 포맷은 다음 공개 레포지터리에 상세히 정의되어 있습니다.

SMI OSS - fx-stream-msgs

이 메세지들은 ROS 2 인터페이스 타입으로 정의되어 있으며, 센서에서 수집한 데이터를 퍼블리시하는데 사용됩니다.

이 문서에서 다루는 내용은 다음과 같습니다.

다루는 것: 전제조건(펌웨어·ROS 2 환경·네트워크), 빠른 시작(빌드·구독 확인), 토픽/메세지 명세, 액션 명세, 트러블슈팅
다루지 않는 것: RTSP/WebSocket 채널 연동(BATCAM FX 개요), REST API 상세(FX API 플레이그라운드), ROS Domain ID 변경 절차 상세(ROS Domain ID 설정)

전제조건

펌웨어 버전

ROS 2 관련 기능은 펌웨어 버전에 따라 단계적으로 추가되었습니다. 자세한 변경 이력은 FX 펌웨어 릴리스 노트를 참고하시기 바랍니다.

기능	최초 지원 펌웨어	비고
ROS 2 토픽 송신 (beamforming / image / lpoint_audio / ws_audio / prpd)	v1.0.3b (개발 펌웨어)	정식 릴리스 v1.0.3에 포함
설정 액션 (setting_beamforming / setting_overlay)	v1.0.3c	정식 릴리스 v1.0.3에 포함
ROS Domain ID 조회·설정 REST API (`/ros/domain`)	v1.0.3c	ROS Domain ID 설정 참고

사용 중인 카메라의 펌웨어 버전은 REST API GET /setting/status(기기정보 조회)로 확인할 수 있습니다. 자세한 명세는 FX API 플레이그라운드를 참고하세요.

ROS 2 환경

구분	환경	비고
카메라 (펌웨어 내장 바이너리)	ROS 2 Humble Hawksbill	펌웨어에 포함되어 별도 설치 불필요
호스트 메세지 패키지 (fx-stream-msgs)	ROS 2 Humble 사용 전제	Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04) 환경에서 빌드 후 BATCAM FX와의 데이터 송수신 테스트로 검증됨

💡 참고: fx-stream-msgs는 ROS 2 Humble에서의 사용을 전제로 작성되었으며, ROS 2 Jazzy (Ubuntu 24.04) 환경에서의 빌드와 BATCAM FX 간 데이터 송수신 테스트를 통해 검증되었습니다.

네트워크

카메라의 ROS 2 스택은 UDPv4 기반의 Fast DDS 설정을 사용합니다 (v1.0.3c 릴리스 노트 기준). 카메라와 호스트 PC가 같은 네트워크에서 서로 통신 가능해야 합니다.
카메라와 호스트의 ROS_DOMAIN_ID가 일치해야 토픽이 보입니다. v1.0.3b 개발 펌웨어부터 카메라의 기본 ROS_DOMAIN_ID는 123이며, 펌웨어 1.0.3c 이상에서는 REST API(GET·PATCH /ros/domain)로 조회·변경할 수 있습니다. 자세한 내용은 ROS Domain ID 설정 문서를 참고하세요.
전체 토픽 구독 시 fx_stream_msgs 토픽 합계 기준 약 3.6 MB/s(image 토픽 제외)의 대역폭이 필요합니다. 안정적인 수신을 위해 유선 연결을 권장합니다.

빠른 시작

1. 카메라 hardware_id 확인

BATCAM FX의 토픽과 액션 이름에는 카메라의 하드웨어 ID가 포함됩니다 (예: /fx_{hardware_id}/beamforming). 하드웨어 ID는 REST API GET /setting/status로 확인할 수 있습니다. 모든 REST 엔드포인트는 HTTP Basic 인증이 필요합니다 (FX API 플레이그라운드 참고).

curl -u admin:{password} http://192.168.0.30/setting/status
# 사용하시는 환경에 맞게 IP 주소와 비밀번호를 변경하여 사용하시기 바랍니다.

응답 예시:

{
  "error": 0,
  "result": {
    "hardware_id": "3287162925128",
    "sbrio_version": "1.0.14",
    "firmware_version": "v0.0.1"
  }
}

이 예시의 카메라라면 토픽 접두사는 /fx_3287162925128이 됩니다. 아래 단계의 예시는 모두 이 값을 사용합니다.

2. 호스트 ROS_DOMAIN_ID 설정

호스트 셸에서 카메라와 같은 도메인 ID를 설정합니다. 카메라에 설정된 값은 GET /ros/domain(펌웨어 1.0.3c 이상)으로 확인할 수 있으며, v1.0.3b 개발 펌웨어부터 기본값은 123입니다.

export ROS_DOMAIN_ID=123
# 카메라에 설정된 값과 동일하게 지정합니다.

3. fx-stream-msgs 빌드

호스트에서 fx_stream_msgs 메세지 타입을 사용하려면 공개 레포지터리를 받아 워크스페이스에서 빌드합니다.

mkdir -p ~/fx_ws/src
cd ~/fx_ws/src
git clone https://gitlab.com/smins-oss/sound-camera/framework/protocol/fx-stream-msgs.git
cd ~/fx_ws
colcon build
source install/setup.bash

새 터미널을 열 때마다 source ~/fx_ws/install/setup.bash를 다시 실행해야 합니다.

4. 토픽·액션 확인

카메라가 켜져 있고 네트워크로 연결된 상태에서 토픽 목록을 확인합니다.

ros2 topic list

예상 출력:

/fx_3287162925128/beamforming
/fx_3287162925128/image
/fx_3287162925128/lpoint_audio
/fx_3287162925128/prpd
/fx_3287162925128/ws_audio
/parameter_events
/rosout

액션 목록도 확인할 수 있습니다.

ros2 action list

예상 출력:

/fx_3287162925128/setting_beamforming
/fx_3287162925128/setting_overlay

5. 데이터 수신 확인

PRPD 토픽에서 메세지 1개를 수신해 봅니다.

ros2 topic echo /fx_3287162925128/prpd --once

예상 출력 (값은 측정 상황에 따라 다릅니다):

noise:
- -0.96
- 4.48
- -6.54
corona:
- 2.98
- 5.88
- -1.39
floating:
- -3.55
- -5.45
- 0.73
surface:
- 0.3
- -1.51
- 0.45
---

각 배열은 LPoint 채널 CH0~CH2에 대응하는 부분방전 유형별 logit score입니다. 해석 방법은 AI PRPD 분류기 문서를 참고하세요.

6. 최소 구독 노드 예제 (Python)

다음은 Beamforming 토픽을 구독하여 BF Map의 최대값을 출력하는 최소 노드의 전체 파일 예제입니다.

fx_beamforming_listener.py

import rclpy
from rclpy.node import Node
from fx_stream_msgs.msg import Beamforming

HARDWARE_ID = '3287162925128'  # GET /setting/status 로 확인한 값으로 변경

class FxBeamformingListener(Node):
    def __init__(self):
        super().__init__('fx_beamforming_listener')
        self.subscription = self.create_subscription(
            Beamforming,
            f'/fx_{HARDWARE_ID}/beamforming',
            self.listener_callback,
            10)

    def listener_callback(self, msg: Beamforming):
        # bf는 40x30 BF Map을 1x1200으로 펼친 배열이며,
        # v1.0.2 펌웨어 이상에서는 스케일 변환이 필요없는 dB 값입니다.
        self.get_logger().info(
            f'BF max: {max(msg.bf):.1f} dB (gain={msg.gain})')

def main():
    rclpy.init()
    node = FxBeamformingListener()
    rclpy.spin(node)

if __name__ == '__main__':
    main()

실행:

source ~/fx_ws/install/setup.bash
python3 fx_beamforming_listener.py

예상 출력 (값은 측정 상황에 따라 다릅니다):

[INFO] [fx_beamforming_listener]: BF max: 45.2 dB (gain=100.0)
[INFO] [fx_beamforming_listener]: BF max: 45.4 dB (gain=100.0)

토픽 레퍼런스

BATCAM FX는 카메라의 하드웨어 ID를 기준으로 다음 토픽을 생성합니다.

토픽	메세지 타입	주기	평균 대역폭	메세지당 크기
`/fx_{hardware_id}/beamforming`	`fx_stream_msgs/msg/Beamforming`	25 Hz	~250 KB/s	9.84 KB
`/fx_{hardware_id}/image`	`sensor_msgs/msg/CompressedImage`	25 Hz (25 fps)	—	—
`/fx_{hardware_id}/lpoint_audio`	`fx_stream_msgs/msg/LPointAudio`	25 Hz	~2.5 MB/s	0.10 MB
`/fx_{hardware_id}/ws_audio`	`fx_stream_msgs/msg/WsAudio`	25 Hz	~850 KB/s	32.02 KB
`/fx_{hardware_id}/prpd`	`fx_stream_msgs/msg/Prpd`	25 Hz	~220 B/s	52 B

LevelTrigger를 제외한 모든 메세지는 25 Hz (25 fps) 간격으로 주기적으로 퍼블리시됩니다. fx_stream_msgs 토픽의 평균 대역폭 합계는 약 3.6 MB/s(image 토픽 제외)입니다.

데이터 해석 주의사항

WsAudio, LPointAudio, Beamforming 메세지에 포함된 gain 값은, 카메라의 자동 증폭 기능이 활성화 된 경우, 마지막으로 설정된 값 또는 -1 이 반환됩니다.
WsAudio, LPointAudio 의 ws, lpoint0~2 값들은 8000 샘플 길이의 float 배열이며, IEEE 754 형식의 Float Wave Format으로 구성됩니다. 25 Hz 주기 기준 초당 200,000 샘플로, 카메라의 마이크 샘플링 레이트(200 kHz)에 해당합니다.
v1.0.2 펌웨어부터 Beamforming 메세지의 bf의 값은 스케일 변환이 필요없는 dB 값입니다.

WsAudio.msg

타입	이름	설명
float64	`gain`	수신 시점의 마이크 증폭 값. 자동 증폭(autogain) 활성 시 마지막 설정값 또는 `-1`
float32[]	`ws`	8000 샘플 길이의 오디오 신호 (IEEE 754 Float Wave Format)

LPointAudio.msg

타입	이름	설명
float64	`gain`	수신 시점의 마이크 증폭 값. 자동 증폭(autogain) 활성 시 마지막 설정값 또는 `-1`
float32[]	`lpoint0`	Listening Point 0 위치에서 빔포밍된 오디오 신호, 8000 샘플 float 배열 (IEEE 754 Float Wave Format)
float32[]	`lpoint1`	Listening Point 1 위치의 오디오 신호 (형식 동일)
float32[]	`lpoint2`	Listening Point 2 위치의 오디오 신호 (형식 동일)

Listening Point의 좌표 체계와 설정 제약은 Listening Point 좌표 문서를 참고하세요.

Beamforming.msg

타입	이름	설명
float64	`gain`	수신 시점의 마이크 증폭 값. 자동 증폭(autogain) 활성 시 마지막 설정값 또는 `-1`
float64[]	`bf`	40×30 BF Map을 1×1200으로 펼친 배열. v1.0.2 펌웨어부터 스케일 변환이 필요없는 dB 값 (BF Map 구조·좌표계 참고)
float64[]	`level`	—
int32[]	`param1`	—
int32[]	`param2`	—
int32[]	`theta`	—
int32[]	`pos_x`	—
int32[]	`pos_y`	—
int32[]	`v_pos_x`	—
int32[]	`v_pos_y`	—

Prpd.msg

각 필드는 LPoint 채널 CH0~CH2에 대응하는 길이 3의 배열이며, 값은 부분방전 유형별 정규화되지 않은 logit score입니다. argmax·softmax를 이용한 해석 방법과 예제 코드는 AI PRPD 분류기 문서를 참고하세요.

타입	이름	설명
float32[3]	`noise`	채널별 Noise(비방전 소음) logit score
float32[3]	`corona`	채널별 Corona 방전 logit score
float32[3]	`floating`	채널별 Floating 방전 logit score
float32[3]	`surface`	채널별 Surface 방전 logit score

LevelTrigger.msg ( 미사용 예정 )

메세지 타입으로 정의되어 있으나 미사용 예정이며, 위의 토픽 목록에는 포함되지 않습니다.

타입	이름	설명
float64	`decibel`	레벨 값 (dB)

액션 레퍼런스

BATCAM FX는 카메라의 하드웨어 ID를 기준으로 다음 액션을 생성합니다 (펌웨어 v1.0.3c 이상).

액션	액션 타입	용도
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	빔포밍 파라미터 설정
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	오버레이 이미지 생성 파라미터 및 소스 모드 설정

액션을 이용한 설정의 상세 예시는 ROS 액션을 이용한 Beamforming·Overlay 설정 (베타) 문서를 참고하세요. 같은 설정은 REST API로도 가능합니다 (FX API 플레이그라운드).

BeamformingSetting.action

Goal, Result, Progress는 모두 BeamformingSetting 메세지 타입의 setting 필드 하나로 구성됩니다.

구획	타입	이름
Goal	BeamformingSetting	`setting`
Result	BeamformingSetting	`setting`
Progress	BeamformingSetting	`setting`

BeamformingSetting.msg — 각 필드의 최소/최대/기준 값은 Beamforming 파라미터 문서를 참고하세요.

타입	이름	설명	범위 (단위/스텝)
bool	`autogain`	마이크 자동 증폭 사용 여부. 소리 크기에 따라 카메라가 자동으로 Gain을 결정	True / False
float64	`gain`	마이크 증폭 값. `autogain`이 False일 때만 적용	1 ~ 1000 (1, 10, 100, 1000만 허용)
float64	`x_cal`	카메라 영상과 오버레이 이미지의 x좌표 오차 보정	0 ~ 1 (스텝 0.01)
float64	`y_cal`	카메라 영상과 오버레이 이미지의 y좌표 오차 보정	0 ~ 1 (스텝 0.01)
float64	`distance`	측정할 소음원까지의 거리. 지정된 거리로 더 정밀한 빔포밍 시도	1 ~ 10 (스텝 1)
float64	`high_cut`	표시할 최대 주파수 (로우패스 필터). 이 값 위의 소리는 걸러짐	low_cut 초과 ~ 100,000 Hz (스텝 100)
float64	`low_cut`	표시할 최저 주파수 (하이패스 필터). 이 값 밑의 소리는 걸러짐	1,000 Hz ~ high_cut 미만 (스텝 100)
int32	`l_point_0`	Listening Point 0의 인덱스 (40×30 그리드). 3개 모두 지정 필요	0 ~ 1199
int32	`l_point_1`	Listening Point 1의 인덱스	0 ~ 1199
int32	`l_point_2`	Listening Point 2의 인덱스	0 ~ 1199

Listening Point 간 최소 거리 제한 등 좌표 관련 제약은 Listening Point 좌표 문서를 참고하세요. REST API에서는 같은 값이 index_l 필드(쉼표로 구분된 3개 값)로 전송됩니다.

터미널 예시:

ros2 action send_goal /fx_3287162925128/setting_beamforming fx_stream_msgs/action/BeamformingSetting \
"{
setting: {
autogain: false,
gain: 1,
x_cal: 0.0,
y_cal: 0.0,
distance: 5.0,
high_cut: 60000.0,
low_cut: 25000.0,
l_point_0: 580,
l_point_1: 20,
l_point_2: 290
}
}"

OverlaySetting.action

Goal, Result, Progress는 모두 OverlaySetting 메세지 타입의 setting 필드 하나로 구성됩니다.

구획	타입	이름
Goal	OverlaySetting	`setting`
Result	OverlaySetting	`setting`
Progress	OverlaySetting	`setting`

OverlaySetting.msg — 각 필드의 최소/최대/기준 값은 Overlay 파라미터 문서를 참고하세요.

타입	이름	설명	범위 (단위/스텝)
bool	`enable_overlay`	오버레이 이미지 출력 여부. True 시 RTSP 및 ROS로 전달되는 이미지에 오버레이 표시	True / False
bool	`enable_source_mode`	소스 탐지 모드. 오버레이가 켜져 있어야 사용 가능	True / False
int32	`number_of_sources`	동시에 추적할 소스 개수 (권장 3개 이하)	1 ~ 5 (스텝 1)
int32	`average`	평균값을 적용할 빔포밍 맵 개수. 소스 탐지 모드 활성 시 미적용	0 ~ 10 (스텝 1)
float64	`threshold`	소스로 판단할 최소 강도값. 소스 탐지 모드 활성 시 미적용	0 ~ 120 (스텝 1)
float64	`range`	소스에 대한 오버레이 이미지 크기. 소스 탐지 모드 활성 시 미적용	0 ~ 10 (스텝 0.1)