FX ROS Firmware BF/Overlay Parameter Setting (베타)

⚠️ 베타: 이 문서는 베타 기능을 다루며, 인터페이스와 내용이 펌웨어 업데이트에 따라 변경될 수 있습니다. 버전별 변경 사항은 펌웨어 릴리즈 노트를 참조하세요.

개요

BATCAM FX는 ROS 2의 Action 인터페이스를 통해 빔포밍(Beamforming) 및 오버레이(Overlay) 설정을 변경할 수 있습니다. 이 문서에서는 두 설정 액션의 이름과 필드, 터미널(CLI) 및 Python 코드에서의 호출 방법을 안내합니다.

각 액션이 다루는 값은 REST API(/beamforming/setting, /beamforming/overlay)와 같은 값 체계를 사용합니다. REST API 명세는 API Playground (FX)에서 확인할 수 있습니다.

메시지 타입의 정의 및 형식은 ROS Integration 문서 또는 SMI OSS - fx-stream-msgs 저장소를 참조하시기 바랍니다.

전제조건

펌웨어 버전: 이 문서의 설정 액션(setting action)은 FX 펌웨어 v1.0.3c(2025.05.27)부터 지원됩니다. ROS 2 기반 데이터 송신 자체는 v1.0.3b 개발 펌웨어부터 지원됩니다. 자세한 내용은 펌웨어 릴리즈 노트를 참조하세요.
ROS 2 환경: BATCAM FX의 ROS 2 기능은 ROS 2 Humble Hawksbill 기반입니다. fx-stream-msgs 패키지는 ROS 2 Humble에서의 사용을 전제로 하며, Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04) 환경에서 빌드 및 검증되었습니다.
fx_stream_msgs 패키지: 액션 타입 정의는 fx-stream-msgs 저장소에서 제공됩니다. 명령을 실행할 환경의 워크스페이스에서 해당 패키지를 빌드하고 소싱해야 아래 예시의 타입을 사용할 수 있습니다.
네트워크 및 ROS_DOMAIN_ID: 카메라와 같은 네트워크에서, 카메라와 동일한 ROS_DOMAIN_ID를 사용해야 합니다. 카메라의 Domain ID 설정 방법은 ROS Domain ID 문서를 참조하세요.

액션 이름과 hardware_id

BATCAM FX는 카메라의 하드웨어 ID를 기준으로 다음 두 개의 설정 액션을 생성합니다.

액션 이름	액션 타입	설정 대상
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	빔포밍 파라미터
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	오버레이 파라미터

{hardware_id}는 카메라와 같은 ROS 2 네트워크에서 ros2 action list를 실행하면 액션 이름에서 확인할 수 있습니다.

ros2 action list

# 출력 예시
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

이 문서의 예시는 hardware_id가 276730383020104인 카메라를 기준으로 작성되었습니다.

각 액션의 Goal은 setting 필드 하나로 구성되며, 그 안에 설정값 전체를 담아 전송합니다. Goal에서 명시하지 않은 필드는 타입 기본값(0, False)으로 전송되므로, 모든 필드를 채워서 보내는 것을 권장합니다. Result에는 Goal과 동일한 setting 구조로 적용된 설정값이 반환되며, 액션 명세에는 같은 구조의 Progress(피드백) 항목도 정의되어 있습니다.

Beamforming 설정

/fx_{hardware_id}/setting_beamforming

빔포밍 파라미터의 값을 설정합니다. REST API의 GET/PATCH /beamforming/setting 엔드포인트와 같은 값 체계를 사용하며, Listening Point만 표기가 다릅니다. REST에서는 index_l 하나의 필드에 쉼표로 구분한 3개 값을 전송하지만, ROS에서는 l_point_0 ~ l_point_2 세 필드로 나뉩니다.

필드 요약

필드	타입	단위	범위	스텝 / 허용값	설명
`autogain`	bool	-	False / True	Boolean	마이크 자동 증폭 사용 여부. True인 동안 `gain` 값은 사용되지 않습니다.
`gain`	float64	-	1 ~ 1000	허용값 `1`, `10`, `100`, `1000`만 사용 가능	마이크 증폭 값. 변경하려면 먼저 `autogain`을 False로 설정해야 합니다.
`x_cal`	float64	-	0 ~ 1	스텝 0.01	카메라 영상과 오버레이 이미지의 x좌표 오차 보정.
`y_cal`	float64	-	0 ~ 1	스텝 0.01	카메라 영상과 오버레이 이미지의 y좌표 오차 보정.
`distance`	float64	-	1 ~ 10	스텝 1	측정할 소음원까지의 거리.
`high_cut`	float64	Hz	low_cut 초과 ~ 100,000	스텝 100	표시할 최대 주파수. 로우패스 필터로, 이 값 위의 소리는 걸러집니다.
`low_cut`	float64	Hz	1,000 ~ high_cut 미만	스텝 100	표시할 최저 주파수. 하이패스 필터로, 이 값 밑의 소리는 걸러집니다.
`l_point_0` ~ `l_point_2`	int32	-	0 ~ 1199	스텝 1	Listening Point 인덱스. 3개를 모두 지정해야 합니다. 좌표 체계는 Listening Point 좌표 문서를 참조하세요.

각 파라미터의 상세 설명과 최소/최대/기준 값은 Beamforming Parameters 문서를 참조하시기 바랍니다.

터미널 예시

ros2 action send_goal /fx_276730383020104/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
}
}"

성공 시 다음과 같은 흐름으로 출력되며, 상태가 SUCCEEDED로 종료됩니다.

Waiting for an action server to become available...
Sending goal:
...
Goal accepted with ID: ...
Result:
setting: ...
Goal finished with status: SUCCEEDED

Result의 setting에는 카메라에 적용된 설정값이 Goal과 동일한 구조로 반환됩니다.

반영 확인

REST API의 GET /beamforming/setting으로 현재 저장된 빔포밍 설정값을 조회할 수 있습니다. 명세는 API Playground (FX)를 참조하세요.
ROS에서 /fx_{hardware_id}/beamforming 토픽을 구독하면 실시간 빔포밍 데이터에서 gain 값 등을 확인할 수 있습니다. 자동 증폭이 활성화된 경우 퍼블리시되는 gain 값은 마지막으로 설정된 값 또는 -1이 반환됩니다.

Overlay 설정

/fx_{hardware_id}/setting_overlay

Full View 모드의 오버레이 이미지 생성 파라미터 및 소스 탐지 모드를 설정합니다. 오버레이 기능은 BATCAM FX 펌웨어 1.0.3 버전 이상부터 지원되며, REST API의 GET/PATCH /beamforming/overlay 엔드포인트와 같은 필드 구성을 사용합니다.

필드 요약

필드	타입	단위	범위	스텝 / 허용값	설명
`enable_overlay`	bool	-	False / True	Boolean	오버레이 이미지 출력 여부. True 설정 시 RTSP 및 ROS로 전달되는 이미지에 오버레이가 표시됩니다.
`enable_source_mode`	bool	-	False / True	Boolean	소스 탐지 모드 사용 여부. 오버레이가 켜져 있어야 동작하며, `number_of_sources` 값에 따라 단일 또는 다중 소스 모드가 활성화됩니다.
`number_of_sources`	int32	-	1 ~ 5	스텝 1	동시에 추적할 소스의 개수. 최대 5개까지 지정할 수 있으나 3개까지를 권장합니다.
`average`	int32	-	0 ~ 10	스텝 1	평균값을 적용할 빔포밍 맵의 개수. 높을수록 결과가 부드러워집니다. 소스 탐지 모드 활성 시 적용되지 않습니다.
`threshold`	float64	-	0 ~ 120	스텝 1	소스로 판단할 최소 강도값. 높을수록 더 강한 소스만 표시됩니다. 소스 탐지 모드 활성 시 적용되지 않습니다.
`range`	float64	-	0 ~ 10	스텝 0.1	소스에 대한 오버레이 이미지 크기. 높을수록 오버레이가 커집니다. 소스 탐지 모드 활성 시 적용되지 않습니다.

각 파라미터의 상세 설명과 최소/최대/기준 값은 Overlay Parameters 문서를 참조하시기 바랍니다.

터미널 예시

ros2 action send_goal /fx_276730383020104/setting_overlay fx_stream_msgs/action/OverlaySetting \
"{
setting: {
enable_overlay: true,
enable_source_mode: true,
number_of_sources: 3,
range: 5.0,
threshold: 15.0,
average: 1
}
}"

실행 결과의 흐름은 Beamforming 설정과 동일합니다. 성공 시 SUCCEEDED 상태로 종료되며, Result의 setting에 적용된 오버레이 설정값이 반환됩니다.

반영 확인

REST API의 GET /beamforming/overlay로 현재 오버레이 설정값을 조회할 수 있습니다. 명세는 API Playground (FX)를 참조하세요.
enable_overlay를 True로 설정하면 RTSP 및 ROS로 전달되는 이미지에 오버레이가 표시되므로, 영상 스트림에서 직접 확인할 수 있습니다.

코드에서 호출하기 (Python)

실제 통합 시에는 터미널 CLI 대신 코드에서 액션을 호출하는 경우가 많습니다. 아래는 rclpy로 Beamforming 설정 액션을 호출하는 전체 예제입니다. Overlay 설정도 액션 이름과 타입(OverlaySetting), 필드만 바꾸면 같은 구조로 호출할 수 있습니다.

import rclpy
from rclpy.action import ActionClient
from rclpy.node import Node

from fx_stream_msgs.action import BeamformingSetting

HARDWARE_ID = '276730383020104'  # ros2 action list 로 확인한 값으로 변경

class BeamformingSettingClient(Node):
    def __init__(self):
        super().__init__('beamforming_setting_client')
        self._client = ActionClient(
            self,
            BeamformingSetting,
            f'/fx_{HARDWARE_ID}/setting_beamforming',
        )

    def send_goal(self):
        goal = BeamformingSetting.Goal()
        goal.setting.autogain = False
        goal.setting.gain = 1.0
        goal.setting.x_cal = 0.0
        goal.setting.y_cal = 0.0
        goal.setting.distance = 5.0
        goal.setting.high_cut = 60000.0
        goal.setting.low_cut = 25000.0
        goal.setting.l_point_0 = 580
        goal.setting.l_point_1 = 20
        goal.setting.l_point_2 = 290

        self._client.wait_for_server()
        return self._client.send_goal_async(goal)

def main():
    rclpy.init()
    node = BeamformingSettingClient()

    goal_future = node.send_goal()
    rclpy.spin_until_future_complete(node, goal_future)
    goal_handle = goal_future.result()

    if not goal_handle.accepted:
        node.get_logger().error('Goal rejected')
    else:
        result_future = goal_handle.get_result_async()
        rclpy.spin_until_future_complete(node, result_future)
        result = result_future.result().result
        node.get_logger().info(f'적용된 설정: {result.setting}')

    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

문제 해결 (Troubleshooting)

액션이 ros2 action list에 보이지 않는 경우:
- 카메라의 펌웨어가 v1.0.3c 이상인지 확인합니다. (펌웨어 릴리즈 노트)
- 실행 환경의 ROS_DOMAIN_ID가 카메라와 동일한지 확인합니다. (ROS Domain ID)
- 카메라와 같은 네트워크에 연결되어 있는지 확인합니다.
fx_stream_msgs 타입을 찾을 수 없다는 오류가 발생하는 경우:
- fx-stream-msgs 패키지를 빌드한 워크스페이스가 현재 셸에 소싱되어 있는지 확인합니다.
gain 변경이 반영되지 않는 경우:
- autogain이 True인 동안에는 gain 값이 사용되지 않습니다. 먼저 autogain을 False로 설정합니다.
- 펌웨어 v1.0.3(2025.10.04) 릴리즈에는 Gain 설정 제거 및 Auto Gain 비활성화 변경이 포함되어 있습니다. 사용 중인 펌웨어 버전의 동작은 펌웨어 릴리즈 노트를 확인하세요.
소스 탐지 모드가 동작하지 않는 경우:
- enable_source_mode는 enable_overlay가 True일 때만 동작합니다.
average / threshold / range 변경이 반영되지 않는 경우:
- 세 값은 소스 탐지 모드(enable_source_mode)가 활성화된 동안에는 적용되지 않습니다.
Listening Point 설정이 실패하는 경우:
- l_point_0 ~ l_point_2는 0 ~ 1199 범위에서 3개를 모두 지정해야 합니다. 좌표 체계는 Listening Point 좌표 문서를 참조하세요.
- 같은 값 체계를 쓰는 REST API에서는 잘못된 L Point 파라미터에 대해 lpoint parameter error를 반환합니다.

FX ROS Firmware BF/Overlay Parameter Setting (베타)

개요

전제조건

액션 이름과 hardware_id

Beamforming 설정

필드 요약

터미널 예시

반영 확인

Overlay 설정

필드 요약

터미널 예시

반영 확인

코드에서 호출하기 (Python)

문제 해결 (Troubleshooting)

관련 문서