Gazebo Sim 逻辑音频传感器(LogicalAudioSensorPlugin)完全指南:SDF 配置、音量衰减模型与启停服务
Gazebo Sim 逻辑音频传感器(LogicalAudioSensorPlugin)完全指南:SDF 配置、音量衰减模型与启停服务
逻辑音频传感器(LogicalAudioSensorPlugin)是 Gazebo Sim(gz-sim)中用于模拟"声音能否被听到"的系统插件:它在仿真环境中放置逻辑音频源(source)与逻辑麦克风(microphone),在每个仿真步结束时计算麦克风位置处能接收到的音量,并发布检测结果。它不向扬声器等真实音频设备播放任何声音,而是回答"该位置理论上能否听到某声源"这一问题,非常适合用于声学可听性(acoustic detectability)相关的仿真测试,例如机器人感知、安防监控、声音触发事件等场景。读完本文,你将掌握如何在 SDF 中配置音频源与麦克风的全部参数、理解音量衰减的数学原理,并通过话题(topic)与服务(service)完成检测观察与声源启停控制。
逻辑音频传感器是什么
LogicalAudioSensorPlugin 是 gz-sim 内置系统插件之一,其核心行为在插件头文件中有明确描述(见 src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh):
- 每个
<plugin>标签可以挂载多个传感器,即多个声源(source)和/或麦克风(microphone); - 在每个仿真步(simulation step)结束之后,每个麦克风都会检查世界中的所有声源,判断自己是否"听到了"音频;
- 插件不会向扬声器之类的音频设备播放真实声音,它只计算"某个位置理论上能否听到某个声源"。
从实现上看,插件同时继承并实现了三个系统接口(LogicalAudioSensorPlugin.hh):ISystemConfigure(配置阶段创建实体)、ISystemPreUpdate(更新前处理声源启停状态)、ISystemPostUpdate(更新后计算音量并发布检测消息)。插件在文件末尾通过 GZ_ADD_PLUGIN 与 GZ_ADD_PLUGIN_ALIAS 注册,对外名称为 gz::sim::systems::LogicalAudioSensorPlugin,SDF 中使用的 filename 为 gz-sim-logicalaudiosensorplugin-system(见 LogicalAudioSensorPlugin.cc)。
工作原理总览(源码级)
结合 LogicalAudioSensorPlugin.cc 的实现,插件的工作流程分为三个阶段:
- Configure:创建实体。插件克隆 SDF 元素,遍历所有
<source>与<microphone>子元素,分别调用CreateAudioSource与CreateMicrophone(见 LogicalAudioSensorPlugin.cc)。每个源/麦克风都会在 ECM(EntityComponentManager)中创建一个独立实体,并挂载Name、Sensor、Pose等组件以及对应的逻辑音频组件。 - PreUpdate:维护声源启停状态。插件遍历所有声源实体,读取
LogicalAudioSourcePlayInfo组件;在首次更新时记录startTime;随后根据 play/stop 服务调用标志位更新playing状态,并检查DurationExceeded(播放时长是否超限)以自动停止声源(见 LogicalAudioSensorPlugin.cc)。服务调用与 PreUpdate 之间通过playSourceMutex/stopSourceMutex互斥锁保证线程安全。 - PostUpdate:计算音量并发布检测。对每个麦克风,插件取出其世界位姿,遍历所有
LogicalAudioSource与LogicalAudioSourcePlayInfo组件,调用logical_audio::computeVolume计算该麦克风位置接收到的音量,再用logical_audio::detect与麦克风的volumeDetectionThreshold比较;若达到阈值,则通过<PREFIX>/mic_<id>/detection话题发布一条gz.msgs.Double消息(见 LogicalAudioSensorPlugin.cc)。
其中涉及的 ECM 组件类型定义在 include/gz/sim/components/LogicalAudio.hh:
components::LogicalAudioSource:承载声源属性结构体logical_audio::Source(id、衰减函数、衰减形状、内半径、衰减距离、发射音量);components::LogicalAudioSourcePlayInfo:承载播放信息结构体logical_audio::SourcePlayInfo(是否播放中playing、播放时长playDuration、最近开始播放时间startTime);components::LogicalMicrophone:承载麦克风属性结构体logical_audio::Microphone(id、检测音量阈值)。
在 SDF 中定义逻辑音频源
完整 SDF 示例
以示例世界 examples/worlds/logical_audio_sensor_plugin.sdf 中挂载在 red_box 模型上的音频源为例,SDF 写法如下:
<plugin filename="gz-sim-logicalaudiosensorplugin-system" name="gz::sim::systems::LogicalAudioSensorPlugin">
<source>
<id>1</id>
<pose>.5 0 0 0 0 0</pose>
<attenuation_function>linear</attenuation_function>
<attenuation_shape>sphere</attenuation_shape>
<inner_radius>1.0</inner_radius>
<falloff_distance>5.0</falloff_distance>
<volume_level>.8</volume_level>
<playing>true</playing>
<play_duration>10</play_duration>
</source>
</plugin>
source 子标签速查表
<source> 标签的全部子标签说明如下(完整说明见 LogicalAudioSensorPlugin.hh):
| 子标签 | 类型/取值 | 说明 |
|---|---|---|
<id> |
整数,≥ 0 | 声源 ID,用于通过服务操作该声源。必填。同一父实体(model)下所有声源的 ID 必须唯一;不同模型下的声源可以共用相同 ID。ID < 0 为未定义行为 |
<pose> |
"x y z roll pitch yaw" |
声源位姿,各坐标以空格分隔。可选,默认 {0, 0, 0, 0, 0, 0}。位姿相对于插件父实体:插件在 <model> 内则相对模型位姿,插件在 <world> 内则相对世界(即绝对位姿) |
<attenuation_function> |
linear |
衰减函数,字符串不区分大小写。当前唯一可用的取值为 linear;无法识别时将置为 UNDEFINED,此时音量计算返回 -1 |
<attenuation_shape> |
sphere |
衰减形状,字符串不区分大小写。当前唯一可用的取值为 sphere;无法识别时将置为 UNDEFINED |
<inner_radius> |
浮点数,≥ 0 | 衰减形状的内半径。必填。距离小于等于该值的听点,接收到的音量等于声源的发射音量 <volume_level> |
<falloff_distance> |
浮点数,> 内半径 | 衰减距离。必填。定义音量衰减为 0 的距离 |
<volume_level> |
浮点数,0.0 ~ 1.0 | 声源发射音量,0.0 表示 0% 音量,1.0 表示 100% 音量。必填 |
<playing> |
true / false |
声源是否立即开始播放。必填。true 表示仿真开始即播放,false 表示需要手动通过服务启动 |
<play_duration> |
整数(秒),≥ 0 | 播放时长。必填。0 表示无限时长播放,直到用户手动调用 stop 服务 |
参数校验规则
源码 LogicalAudio.cc 中提供了参数校验逻辑,理解这些规则可以避免配置出"静默失效"的声源:
validateInnerRadiusAndFalloffDistance(LogicalAudio.cc):内半径若为负则被修正为0.0;若衰减距离 ≤ 内半径,则被强制修正为内半径 + 1.0。该函数在CreateAudioSource解析 SDF 后立即调用(见 LogicalAudioSensorPlugin.cc)。validateVolumeLevel(LogicalAudio.cc):发射音量会被裁剪到[0.0, 1.0]区间,小于 0 置 0,大于 1 置 1。- 若声源缺失
id、attenuation_function、attenuation_shape、inner_radius、falloff_distance、volume_level、playing、play_duration中的任一必填标签,插件会在日志中输出Skipping the creation of this source.并跳过该声源的创建(见 LogicalAudioSensorPlugin.cc);pose缺失时仅告警并使用默认位姿。
音量衰减模型(computeVolume 数学原理)
logical_audio::computeVolume(LogicalAudio.cc)实现了当前唯一的组合:球形衰减形状(SPHERE)+ 线性衰减函数(LINEAR)。设源发射音量为 V0、内半径为 r_inner、衰减距离为 r_falloff,听点与源的距离为 d,则:
- 声源未播放(
playing == false)或发射音量为 0:返回0.0; - 衰减函数或形状为
UNDEFINED:返回-1.0(非法状态标记); d <= r_inner:接收音量 =V0;d >= r_falloff:接收音量 =0.0;r_inner < d < r_falloff:按线性插值计算,斜率m = -V0 / (r_falloff - r_inner),接收音量V(d) = m * (d - r_inner) + V0。
该实现同样被单元测试 LogicalAudio_TEST.cc 覆盖,测试用例逐一验证了内半径内、内半径处、内外半径之间、衰减距离处、衰减距离之外、未播放、非法函数/形状等多种边界情形。值得注意的是,setAttenuationFunction 与 setAttenuationShape(LogicalAudio.cc)先将输入字符串转为小写再查映射表,因此 "linear"、"LINEAR"、"LiNeA r" 等写法均有效,但带首尾空格(如 " linear"、"sphere ")会被判为无效——这正是示例文件中出现 <attenuation_function> linear</attenuation_function> 这种带空格写法的原因,不过测试表明这会导致 UNDEFINED,因此生产配置中不建议在取值前后加空格。
在 SDF 中定义逻辑麦克风
完整 SDF 示例
以挂载在 green_box 模型上的麦克风为例:
<plugin filename="gz-sim-logicalaudiosensorplugin-system" name="gz::sim::systems::LogicalAudioSensorPlugin">
<microphone>
<id>1</id>
<pose>0 .5 0 0 0 0</pose>
<volume_threshold>.4</volume_threshold>
</microphone>
</plugin>
microphone 子标签速查表
<microphone> 标签的全部子标签说明如下(完整说明见 LogicalAudioSensorPlugin.hh):
| 子标签 | 类型/取值 | 说明 |
|---|---|---|
<id> |
整数,≥ 0 | 麦克风 ID。必填。同一父实体(model)下所有麦克风的 ID 必须唯一;不同模型下的麦克风可以共用相同 ID。ID < 0 为未定义行为 |
<pose> |
"x y z roll pitch yaw" |
麦克风位姿,规则与声源的 <pose> 完全相同:相对插件父实体,可选,默认 {0, 0, 0, 0, 0, 0} |
<volume_threshold> |
浮点数,0.0 ~ 1.0 | 麦克风可检测的最低音量。可选,默认 0.0。阈值越低,麦克风能"听到"的范围越大 |
麦克风的判定逻辑 logical_audio::detect(LogicalAudio.cc)为:接收音量小于 0.00001 一律视为不可检测(即使阈值为 0.0 也如此,避免静默状态被误报);否则当接收音量 ≥ 阈值时判定为检测到。
示例世界剖析:四个盒子
示例世界 examples/worlds/logical_audio_sensor_plugin.sdf 定义了 4 个挂载音频对象的盒子模型:red_box 与 blue_box 挂载逻辑音频源,green_box 与 yellow_box 挂载逻辑麦克风。四个模型的完整配置对比如下:
| 模型 | 模型位姿 | 传感器类型 | id | 传感器位姿(相对模型) | 内半径 | 衰减距离 | 发射音量/阈值 | 播放状态 |
|---|---|---|---|---|---|---|---|---|
| red_box | (0, 0, 0.5) |
source | 1 | (0.5, 0, 0) |
1.0 | 5.0 | 0.8 | playing,时长 10 秒 |
| blue_box | (3, 3, 0.5) |
source | 1 | (0, 0, 0) |
5.0 | 100.0 | 0.6 | 未播放,时长无限(0) |
| green_box | (0, 2, 0.5) |
microphone | 1 | (0, 0.5, 0) |
— | — | 阈值 0.4 | — |
| yellow_box | (-5, 4, 0.5) |
microphone | 1 | (0.5, 0.5, 0.5) |
— | — | 阈值 0.3 | — |
关于 <id> 与 <pose> 的语义,从该世界可以直观验证两点:
- ID 作用域:
red_box与blue_box的源 ID 都是 1,这是合法的——ID 只需要在同一父实体(模型)内唯一。一个模型可以挂多个源/麦克风,各自 ID 必须互不相同。 - 位姿相对性:源/麦克风的
<pose>相对其挂载模型的位姿。例如red_box模型位姿为(0, 0, 0.5)(相对世界),其源位姿(0.5, 0, 0)(相对模型),则源在世界坐标系下的位姿为(0.5, 0, 0.5)。
另外,blue_box 的 <play_duration> 为 0,表示该源将无限时长播放,除非用户手动调用 stop 服务停止它(源码中 DurationExceeded 对 playDuration.count() == 0 的声源不做超时判定,见 LogicalAudioSensorPlugin.cc)。
音量计算的实战推演
利用前面给出的线性衰减公式,可以手工复现文档中的检测输出,验证对原理的理解:
- green_box 麦克风听到 red_box 源,音量 ≈ 0.49:green_box 麦克风的世界位姿为
(0, 2.5, 0.5)(模型(0, 2, 0.5)+ 麦克风(0, 0.5, 0)),red_box 源的世界位姿为(0.5, 0, 0.5),两者距离d = sqrt(0.5² + 2.5²) = sqrt(6.5) ≈ 2.5495。因1.0 < d < 5.0,代入线性衰减公式:V = 0.8 - (0.8 / (5.0 - 1.0)) * (2.5495 - 1.0) ≈ 0.490098,与下文观察到的消息数据0.4900980486407216完全一致。 - green_box 麦克风听到 blue_box 源,音量 = 0.6:blue_box 源世界位姿
(3, 3, 0.5),与 green 麦克风距离d = sqrt(3² + 0.5²) ≈ 3.041 < 5.0(内半径),因此接收音量直接等于发射音量0.6。 - yellow_box 麦克风听不到 red_box 源:yellow 麦克风世界位姿
(-4.5, 4.5, 1.0),与 red 源距离约6.75 > 5.0(衰减距离),音量为 0。
运行示例世界并观察检测
启动仿真
在终端中运行以下命令启动示例世界:
gz sim logical_audio_sensor_plugin.sdf
启动后可以看到四个彩色盒子悬浮在网格地面上(如上图所示)。
列出检测话题
仿真保持运行,另开一个终端,列出当前可用的话题:
gz topic -l
输出中应包含以下两个检测话题(_1 后缀是 SDF 中为麦克风分配的 ID):
/model/green_box/sensor/mic_1/detection
/model/yellow_box/sensor/mic_1/detection
话题命名规则为 <PREFIX>/mic_<id>/detection,其中 <PREFIX> 是麦克风实体的作用域名(scoped name),<id> 来自 SDF 的 <id> 标签。同理,每个源实体也会生成 <PREFIX>/source_<id>/play 与 <PREFIX>/source_<id>/stop 两个服务(见 LogicalAudioSensorPlugin.hh)。
观察无检测的情况
先观察 yellow_box 的麦克风能否听到任何声音:
gz topic -e -t /model/yellow_box/sensor/mic_1/detection
该命令没有任何输出——这意味着 yellow_box 的麦克风检测不到任何正在播放的声源(red_box 的源距离已超过其 5.0 的衰减距离,blue_box 的源当前未播放)。
观察检测消息与时间戳
接着观察 green_box 的麦克风:
gz topic -e -t /model/green_box/sensor/mic_1/detection
此时会看到类似如下的输出:
header {
stamp {
}
data {
key: "world/logical_audio_sensor/model/red_box/sensor/source_1"
}
}
data: 0.4900980486407216
消息类型为 gz.msgs.Double:header.data 中的 key 字段是被检测到声源的完整作用域名(world/logical_audio_sensor/model/red_box/sensor/source_1),data 字段是麦克风位置检测到的音量(0.0 为 0% 音量,1.0 为 100% 音量)。这里 data: 0.49 说明该麦克风听到了 red_box 的源,接收音量约为 49%。
注意此时消息的 stamp 为空——因为仿真尚未开始(处于暂停状态)。点击界面左下角的 play 按钮启动仿真后,检测消息会带上时间戳:
header {
stamp {
sec: 8
nsec: 925000000
}
data {
key: "world/logical_audio_sensor/model/red_box/sensor/source_1"
}
}
data: 0.4900980486407216
由于 red_box 的源在 SDF 中配置了 <play_duration>10</play_duration>,green_box 检测话题发布的最后一条消息时间戳为 10 秒——10 秒(仿真时间)后该源自动停止播放,不再有新的检测消息。这正是 play_duration 的自动停止机制:源码在 PreUpdate 中计算 当前仿真时间 - 开始播放时间,一旦超过 playDuration 就置 playing = false(见 LogicalAudioSensorPlugin.cc)。
通过服务启停音频源
逻辑音频源可以通过 Gazebo 服务手动启动/停止。仿真运行期间,另开终端执行:
gz service -l
在服务列表中可以看到如下 4 个音频源服务(_1 是 SDF 中为源分配的 ID):
/model/blue_box/sensor/source_1/play
/model/blue_box/sensor/source_1/stop
/model/red_box/sensor/source_1/play
/model/red_box/sensor/source_1/stop
启动 blue_box 的音频源
blue_box 的源在 SDF 中配置为 playing: false,默认不播放。调用其 play 服务启动它:
gz service -s /model/blue_box/sensor/source_1/play --reqtype gz.msgs.Empty --reptype gz.msgs.Boolean --timeout 1000 --req 'unused: false'
回到显示 green_box 麦克风检测输出的终端,可以看到该麦克风开始检测到 blue_box 的源(key 字段中出现 blue_box):
header {
stamp {
sec: 255
nsec: 673000000
}
data {
key: "world/logical_audio_sensor/model/blue_box/sensor/source_1"
}
}
data: 0.6
同时,yellow_box 的麦克风也能检测到 blue_box 的源(可对其检测话题执行 gz topic -e -t /model/yellow_box/sensor/mic_1/detection 验证)。
移动模型观察音量阈值效果
由于 blue_box 的源配置了 <play_duration>0</play_duration>,它不会自动停止,必须手动调用 stop 服务。在调用 stop 之前,用**变换控制工具(transform control tool)**拖动 blue_box 远离麦克风:当源到达麦克风位置的接收音量低于麦克风的检测阈值(SDF 中的 <volume_threshold>)时,麦克风检测话题将停止发布消息。拖动回来,音量恢复到阈值之上,消息又会恢复发布——这是观察"音量衰减 + 阈值判定"最直观的方式。
停止 blue_box 的音频源
将 blue_box 拖回原位附近,直到看到 green_box 和/或 yellow_box 的麦克风重新发布检测消息,然后调用 stop 服务:
gz service -s /model/blue_box/sensor/source_1/stop --reqtype gz.msgs.Empty --reptype gz.msgs.Boolean --timeout 1000 --req 'unused: false'
此时两个麦克风话题都不再发布新消息——因为当前没有任何声源在播放。
play/stop 服务的幂等性
- 对已经在播放的源调用 play 服务不会生效:例如
red_box的源正在播放时再次调用 play,它并不会重新计时 10 秒,仍会在原定的 10 秒节点停止。源码中的处理是:仅当playInfo.playing为 false 时才重置startTime(见 LogicalAudioSensorPlugin.cc)。 - 对已经停止的源调用 stop 服务同样不会生效。
这些行为也在集成测试 test/integration/logical_audio_sensor_plugin.cc 中得到了验证:测试分别对"播放中的源(id=1)"调用 stop、对"未播放的源(id=2)"调用 play,并确认服务调用后 ECM 中两个源的 playing 状态正确翻转。
测试验证
该插件在仓库中配有完整的单元测试与集成测试,可作为理解行为边界的可靠参考:
- 单元测试 src/systems/logical_audio_sensor_plugin/LogicalAudio_TEST.cc:
- 集成测试 test/integration/logical_audio_sensor_plugin.cc:
LogicalAudioDetections(L56-L210):使用 test/worlds/logical_audio_sensor_plugin.sdf(源 id=1、内半径 3.0、衰减距离 8.0、音量 0.9、无限播放;近距离麦克风阈值 0.1、远距离麦克风阈值 0.0),验证近距离麦克风收到检测消息、远距离麦克风始终无消息,并校验消息key为world/logical_audio_sensor/model/source_model/sensor/source_1;LogicalAudioServices(L213-L327):使用 test/worlds/logical_audio_sensor_plugin_services.sdf,验证 play/stop 服务被正确广播并改变源的状态。
小结与进一步阅读
LogicalAudioSensorPlugin 提供了一种轻量、确定性的"声音可听性"仿真手段:通过 <source> 与 <microphone> 两组 SDF 标签即可完成配置,音量随距离按线性函数在球形衰减形状内衰减,检测结果通过话题发布、源启停通过服务控制。它适合用于验证"机器人/传感器在给定布局下能否听到某个声源"这类逻辑判定,而不需要引入真实音频渲染。
本文涉及的关键仓库文件汇总:
- 教程原文:tutorials/logical_audio_sensor.md
- 示例世界:examples/worlds/logical_audio_sensor_plugin.sdf
- 插件实现:src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.cc、src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh
- 音量计算与校验:src/systems/logical_audio_sensor_plugin/LogicalAudio.cc、src/systems/logical_audio_sensor_plugin/LogicalAudio.hh
- ECM 组件定义:include/gz/sim/components/LogicalAudio.hh
- 单元测试:src/systems/logical_audio_sensor_plugin/LogicalAudio_TEST.cc
- 集成测试:test/integration/logical_audio_sensor_plugin.cc 及测试世界 test/worlds/logical_audio_sensor_plugin.sdf、test/worlds/logical_audio_sensor_plugin_services.sdf
