如何快速接入 PX4 距离传感器：22 款驱动从使能、启动到调优的完整指南
【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址: https://gitcode.com/gh_mirrors/px/PX4-Autopilot
本文基于 PX4-Autopilot 源码，覆盖src/drivers/distance_sensor下全部 22 款距离传感器驱动（激光、ToF、超声波、雷达、红外）的命令语法、默认地址、使能参数与调优方法，帮你在真实飞控上完成"选型 → 使能 → 启动 → 校准 → 验证 → 排障"全流程。
一、能力总览：先认清你的传感器走哪条路
所有驱动的能力差异集中在四个维度：通信总线、默认地址、是否需要参数使能、能否自动启动。下表一次看全（源码依据：src/drivers/distance_sensor/ 各驱动 Kconfig 与parameters.yaml）：
| 驱动 | 总线 | 默认地址/串口 | 使能参数（默认值） | 自动启动 |
|---|---|---|---|---|
| afbrs50 | S2PI（SPI 协议栈） | — | 无 | 否 |
| vl53l0x / vl53l1x | I2C | 0x29（41） | SENS_EN_VL53L0X/SENS_EN_VL53L1X（关） | 否 |
| lightware_laser_i2c | I2C | 0x66（102） | SENS_EN_SF1XX选型号 | 否 |
| ll40ls | I2C | 0x62（98），兼容 0x42 | SENS_EN_LL40LS=2（默认关） | 否 |
| ll40ls_pwm | PWM | — | SENS_EN_LL40LS=1 | 否 |
| tf02pro | I2C | 0x10（16） | SENS_EN_TF02PRO（关） | 否 |
| teraranger | I2C | 0x30（48） | SENS_EN_TRANGER=0（默认关，1=自动检测） | 否 |
| mappydot | I2C | 扫描 | SENS_EN_MPDT=0（关，1=自动检测） | 否 |
| gy_us42 | I2C | 0x70（112） | 无 | 否 |
| srf02 | I2C | 0x70（112） | 无 | 否 |
| mb12xx | I2C | 112 起自动扫描 | SENS_EN_MB12XX（关） | 否 |
| srf05 | GPIO 触发/回显 | — | SENS_EN_SR05（关） | 否 |
| pga460 | UART | 需指定 | SENS_EN_PGA460（关） | 否 |
| cm8jl65 | UART | 需指定 | SENS_CM8JL65_CFG（0=关） | 是 |
| leddar_one | UART | 需指定 | SENS_LEDDAR1_CFG（0=关） | 是 |
| tfmini | UART | 需指定 | SENS_TFMINI_CFG（0=关） | 是 |
| lightware_laser_serial | UART | 需指定 | SENS_EN_SF0X=1 +SENS_SF0X_CFG | 是 |
| lightware_grf_serial | UART | 需指定 | GRF_SENS_MODEL=0（默认关）+SENS_EN_GRF_CFG | 是 |
| lightware_sf45_serial | UART | 需指定 | SENS_EN_SF45_CFG（0=关） | 是 |
| sony_asdt1 | UART | 需指定 | SENS_ASDT1_CFG（0=关） | 是 |
| ulanding_radar | UART | 默认/dev/ttyS3 | SENS_ULAND_CFG（0=关） | 是 |
两点说明：
- "自动启动"指驱动在 module.yaml 中声明了
serial_config：PX4 启动脚本发现SENS_*_CFG指向某串口后，自动执行start -d <该串口>。串口类驱动基本都不需要手动start。 - 编译开关：src/drivers/distance_sensor/Kconfig 提供
COMMON_DISTANCE_SENSOR一键选项，默认选中 Lightware I2C/串行、LL40LS、TF02PRO、TFMINI、uLanding 雷达、VL53L0X/L1X 八项常用驱动；afbrs50、cm8jl65、pga460、sony 等其余驱动需各自勾选DRIVERS_DISTANCE_SENSOR_<名称>。
二、统一抽象层：一套命令 + 一条消息
2.1 三类命令语法
所有驱动共有：start、stop、status三个子命令，status打印驱动运行状态，是排障第一入口。
I2C 类通用参数（vl53l0x、teraranger、tf02pro 等几乎一致）：
start [-I] 内部 I2C 总线（板载传感器） [-X] 外部 I2C 总线（连接器/共享总线） [-b <val>] 指定某条板级总线（默认全部） [-f <val>] 总线频率，单位 kHz [-q] 静默启动：没找到设备也不报错 [-a <val>] I2C 地址（各驱动默认值不同，见速查卡） [-R <val>] 安装朝向，默认 25（朝下）为什么-I/-X分开？因为多数飞控的板载传感器和外部扩展传感器挂在不同 I2C 总线上，-I只扫内部总线可避免误扫到扩展口上的其它设备。
UART 类通用参数：
start -d /dev/ttyS1 [-R 25]例外有两处，别踩坑：
leddar_one的朝向参数是小写-r；pga460不用-d，设备路径直接跟在start后面：pga460 start /dev/ttyS6；lightware_grf_serial不支持-R，朝向靠其它参数或默认。
2.2 统一输出消息
除少数例外（下文会标出），每个驱动都是把原始读数换算成标准距离后，发布 uORB 主题distance_sensor，定义在 msg/DistanceSensor.msg。EKF2 高度融合、避障、地形跟随消费的都是这条消息，所以驱动层与上层算法完全解耦——换传感器不改上层代码。
两个例外：
sony_asdt1与lightware_sf45_serial额外发布obstacle_distance（多区域测距，带扇区角度信息），前者见 sony/sony_asdt1.cpp 中的_obstacle_distance；cm8jl65发布的是obstacle_distance（红外多区域），见 CM8JL65.cpp。
三、接入三要素：接线、编译开关、启动
按传感器类型走对应路线，三要素缺一不可：
路线 A：I2C 传感器（vl53l0x/1x、tf02pro、teraranger、ll40ls、lightware I2C、srf02、mb12xx、gy_us42、mappydot）
- 接线到飞控 I2C 口（或经扩展器），确认上拉电阻与电平兼容；
- menuconfig 勾选对应
DRIVERS_DISTANCE_SENSOR_*（COMMON_DISTANCE_SENSOR已覆盖常用款），编译烧录； - 若驱动有使能参数（见能力总览表），置为启用并重启生效——所有
SENS_EN_*参数都是reboot_required； - 手动验证：
vl53l0x start -I -a 41，然后vl53l0x status看是否识别到器件。
路线 B：UART 传感器（tfmini、leddar_one、GRF/SF45、AS-DT1、uLanding、cm8jl65、pga460）
- 接线到空闲串口，注意 TX/RX 交叉；
- menuconfig 勾选编译开关，编译烧录；
- 把
SENS_*_CFG设为目标串口（QGC 参数里选SERIAL1/SERIAL2等对应的端口编号，而非设备路径）； - 重启后驱动自动启动，用
tfmini status之类确认。无需手动 start。
路线 C：特殊接口
ll40ls_pwm：PWM 信号线接飞控，SENS_EN_LL40LS=1使能；srf05（HC-SR04/HC-SR05）：GPIO 触发/回显两脚，SENS_EN_SR05=1使能；afbrs50：S2PI 接口（SPI 协议栈），afbrs50 start手动启动，另有cal校准子命令（见第五章）。
# I2C 最小命令集 vl53l0x start -I -a 41 -R 25 vl53l0x status # UART 手动命令集（通常自动启动，无需执行） tfmini start -d /dev/ttyS1 tfmini status四、逐驱动速查卡
以下卡片格式统一：一句话定位 / 总线与默认地址 / 使能参数 / 启动示例 / 关键参数 / 特殊能力 / 源码路径。
afbrs50
- 定位：Broadcom AFBR-S50 长距 ToF 激光测距仪，PX4 中精度调优参数最全的驱动。
- 总线与地址：S2PI（SPI 协议栈），无 I2C 地址概念。
- 使能参数：无。
- 启动示例：
afbrs50 start - 关键参数：
| 参数 | 含义 | 默认 | 取值 |
|---|---|---|---|
SENS_AFBR_MODE | 测量模式（短距/长距/高速短距/高速长距/高精度短距） | -1（自动） | -1~4 |
SENS_AFBR_RATE | 测量速率，越低曝光预算越大、辐射量程越远；低于 5 Hz 会被钳制 | 0（模块默认） | 0~100 |
SENS_AFBR_DFM | 双频模式，将基础无歧义量程×4 或×8 | -1（自动，LV85D/LX85D 选 4X） | -1~2 |
SENS_AFBR_SNM | 散粒噪声监测模式 | 3（动态增强） | 0~3 |
SENS_AFBR_PROF | 性能档：0=保量程（20/15 Hz），1=高帧率（50/25 Hz） | 0 | 0~1 |
SENS_AFBR_QMIN | 最低信号质量门槛 | 0 | 0~100 |
SENS_AFBR_OFS_LO/HI | 低/高激光功率级距离偏移（米），由 cal 写入 | 0.0 | float |
- 特殊能力：绝对距离偏移校准，
afbrs50 cal start 0.3（对准 0.3 m 目标）→afbrs50 cal status查看结果，偏移持久化到SENS_AFBR_OFS_*并在每次启动时叠加在出厂校准之上。 - 源码：src/drivers/distance_sensor/broadcom/afbrs50/，参数定义见 parameters.yaml。
vl53l0x / vl53l1x
- 定位：ST 低成本 ToF 测距，几十厘米量程，适合定高与近距避障。
- 总线与地址：I2C，默认 0x29（十进制 41，见 VL53L0X.hpp 中
VL53L0X_BASEADDR）。多模块同总线需-a改址（利用 XSHUT 逐台上电）。 - 使能参数：
SENS_EN_VL53L0X/SENS_EN_VL53L1X，布尔，默认关。 - 启动示例：
vl53l0x start -I -a 41 -R 25 - 关键参数：仅使能参数，无其它可调项。
- 源码：src/drivers/distance_sensor/vl53l0x/、src/drivers/distance_sensor/vl53l1x/。
lightware_laser_i2c
- 定位：Lightware SF10 系列、LW20/LW30、GRF250/500 的 I2C 版。
- 总线与地址：I2C，默认 0x66（102，见 lightware_laser_i2c.cpp）。
- 使能参数：
SENS_EN_SF1XX选择硬件型号。 - 启动示例：
lightware_laser_i2c start -I -a 102 - 源码：src/drivers/distance_sensor/lightware_laser_i2c/。
ll40ls / ll40ls_pwm
- 定位：LidarLite V3/V3HP，I2C 与 PWM 两种接口各一个驱动。
- 总线与地址：I2C 默认 0x62（98），旧版板卡 0x42 也会尝试（见 LidarLiteI2C.h 双地址表）；PWM 版无地址。
- 使能参数：
SENS_EN_LL40LS：0=关（默认）、1=PWM、2=I2C——一个参数决定跑哪个驱动。 - 启动示例：
ll40ls start -I -a 98 -R 25；PWM 版ll40ls_pwm start -R 25。 - 关键参数：
SENS_LL40LS_SMIN（V3HP 最低信号强度，默认 70，0~254），用于过滤弱回波。 - 特殊能力：
ll40ls regdump可导出寄存器快照辅助调试。 - 源码：src/drivers/distance_sensor/ll40ls/、src/drivers/distance_sensor/ll40ls_pwm/。
tf02pro
- 定位：Benewake TF02 Pro，小型 I2C 激光测距。
- 总线与地址：I2C，默认 0x10（16，见 TF02PRO.hpp）。
- 使能参数：
SENS_EN_TF02PRO，默认关。 - 启动示例：
tf02pro start -I -a 16 -R 25 - 源码：src/drivers/distance_sensor/tf02pro/。
teraranger
- 定位：Bosch TeraRanger 系列（TROne / TREvo），中距激光。
- 总线与地址：I2C，默认 0x30（48，见 TERARANGER.hpp）。
- 使能参数：
SENS_EN_TRANGER：0=关（默认）、1=自动检测、2~5=TROne/TREvo60m/TREvo600Hz/TREvo3m。 - 启动示例：
teraranger start -I -a 48 -R 25 - 源码：src/drivers/distance_sensor/teraranger/。
mappydot
- 定位：MappyDot 光学测距模块。
- 总线与地址：I2C，无固定默认地址，靠检测逻辑扫描。
- 使能参数：
SENS_EN_MPDT：0=关（默认）、1=自动检测。 - 启动示例：
mappydot start -I -q - 源码：src/drivers/distance_sensor/mappydot/。
gy_us42
- 定位：GY-US42 超声波模块，I2C 接口。
- 总线与地址：I2C，默认 0x70（112，见 GY_US42.hpp）。
- 使能参数：无。
- 启动示例：
gy_us42 start -I -R 25 - 源码：src/drivers/distance_sensor/gy_us42/。
srf02
- 定位：Pololu SRF02 超声波。
- 总线与地址：I2C，默认 0x70（112，见 SRF02.hpp）。
- 使能参数：无。
- 启动示例：
srf02 start -I -a 112 -R 25 - 源码：src/drivers/distance_sensor/srf02/。
mb12xx
- 定位：MaxBotix mb12xx 超声波，支持最多 12 个实例。
- 总线与地址：I2C，默认 112，但启动时从 112 向 90 逐地址扫描，自动发现多个传感器（见 mb12xx.cpp 扫描循环）。
- 使能参数：
SENS_EN_MB12XX，默认关。 - 启动示例：
mb12xx start -I（不支持-R） - 关键参数：
SENS_MB12_0_ROT~SENS_MB12_11_ROT逐实例设置朝向（0~7 仅 Yaw 方向）。 - 特殊能力：
set_address -a <val>子命令改写传感器地址（默认 112），解决多设备地址冲突。 - 源码：src/drivers/distance_sensor/mb12xx/。
srf05
- 定位：HY-SRF05 / HC-SR05、HC-SR04，GPIO 触发/回显式超声波。
- 总线与地址：GPIO 两线（触发+回显），无总线参数。
- 使能参数：
SENS_EN_SR05，默认关。 - 启动示例：
srf05 start -R 25 - 源码：src/drivers/distance_sensor/srf05/。
pga460
- 定位：TI PGA460 超声波，以 NuttX task 而非 work_queue 运行——因为驱动需要阻塞式 UART 轮询，工作队列不支持。
- 总线与地址：UART，需指定设备路径。
- 使能参数：
SENS_EN_PGA460，默认关。 - 启动示例：
pga460 start /dev/ttyS6 - 特殊能力：驱动内置假读数检测，数据无效或不稳定时完全不发布该帧，保证输出质量。
- 源码：src/drivers/distance_sensor/pga460/。
cm8jl65
- 定位：兰宝 PSK-CM8JL65-CC5 红外多区域测距，发布
obstacle_distance多扇区数据。 - 总线与地址：UART，自动启动。
- 使能参数：
SENS_CM8JL65_CFG（0=关，选串口）。 - 启动示例（自动）：等效于
cm8jl65 start -d <串口> -R 25 - 关键参数：
SENS_CM8JL65_R_0安装朝向（默认 25 朝下，支持朝前/后/左/右/上）。 - 源码：src/drivers/distance_sensor/cm8jl65/，配置见 module.yaml。
leddar_one
- 定位：LeddarOne 长距激光（数百米），常用于测地物距离。
- 总线与地址：UART，自动启动。
- 使能参数：
SENS_LEDDAR1_CFG（0=关，选串口）。 - 启动示例：
leddar_one start -d /dev/ttyS1 -r 25（注意小写-r）。 - 源码：src/drivers/distance_sensor/leddar_one/。
tfmini
- 定位：Benewake TFmini 低成本串口激光，40 m 级量程，入门首选。
- 总线与地址：UART，自动启动。
- 使能参数：
SENS_TFMINI_CFG（0=关，选串口）。 - 启动示例：
tfmini start -d /dev/ttyS1 -R 25 - 关键参数：
SENS_TFMINI_HW：1=TFmini、2=IstrA24、3=IstrA24-100m（量程与视场不同，默认 1）。 - 源码：src/drivers/distance_sensor/tfmini/。
lightware_laser_serial
- 定位：Lightware SF02/F、SF10、SF11、SF30、LW20/c 的串口版。
- 总线与地址：UART，自动启动。
- 使能参数：
SENS_EN_SF0X选型号（1=SF02、2=SF10/a、3=SF10/b、4=SF10/c、5=SF11/c、6/7=SF30/b/c、8=LW20/c，默认 1）+SENS_SF0X_CFG选串口。 - 启动示例：
lightware_laser_serial start -d /dev/ttyS1 -R 25 - 源码：src/drivers/distance_sensor/lightware_laser_serial/，帧解析逻辑与单元测试在同目录
parser.cpp。
lightware_grf_serial
- 定位：Lightware GRF250/GRF500 长距激光串口版。
- 总线与地址：UART，自动启动。
- 使能参数：
GRF_SENS_MODEL：0=关（默认）、1=GRF250、2=GRF500；SENS_EN_GRF_CFG选串口。 - 启动示例：
lightware_grf_serial start -d /dev/ttyS1 - 关键参数：
GRF_RATE_CFG输出速率 1~50 Hz（默认 4=5 Hz）。 - 源码：src/drivers/distance_sensor/lightware_grf_serial/。
lightware_sf45_serial
- 定位：Lightware SF45/b 超高帧率激光（最高 5000 Hz）。
- 总线与地址：UART，自动启动。
- 使能参数：
SENS_EN_SF45_CFG（0=关，选串口）。 - 启动示例：
lightware_sf45_serial start -d /dev/ttyS1 - 关键参数：
SF45_UPDATE_CFG（50 Hz~5000 Hz，默认 5=500 Hz）；SF45_ORIENT_CFG（24 朝上/25 朝下，默认 24）；SF45_YAW_CFG（0/2/4/6 对应前/右/后/左，默认 0）。 - 特殊能力：额外发布
obstacle_distance主题。 - 源码：src/drivers/distance_sensor/lightware_sf45_serial/。
sony_asdt1
- 定位：Sony AS-DT1 多点多段激光，同时输出多方向距离与方位。
- 总线与地址：UART，自动启动；驱动会探测 921600 与 115200 两种波特率并把传感器配置为二进制流模式（见 sony_asdt1.cpp）。
- 使能参数：
SENS_ASDT1_CFG（0=关，选串口）。 - 启动示例：
sony_asdt1 start -d /dev/ttyS4；调试用sony_asdt1 start -d /dev/ttyS4 -s（只发 flshow 命令打印响应，不开始测量）。 - 关键参数：
SENS_ASDT1_MODE：0=30MSTD、1=30M15F、2=30M30F、3=20M、4=40M（默认 0）；SENS_ASDT1_ROT传感器相对机体前向的 Yaw 偏移角，单位度（默认 0，-360~360）。 - 源码：src/drivers/distance_sensor/sony/。
ulanding_radar
- 定位：Aerotenna uLanding 毫米波雷达，雨天穿透性好，发布
RADAR类型。 - 总线与地址：UART，自动启动；
-d默认值/dev/ttyS3。 - 使能参数：
SENS_ULAND_CFG（0=关，选串口）。 - 启动示例：
ulanding_radar start -d /dev/ttyS1 -R 25 - 源码：src/drivers/distance_sensor/ulanding_radar/。
五、朝向与坐标系：为什么默认值是 25
距离读数本身是标量，下游估计器需要知道"这个距离朝哪个方向"才能把它变成机体坐标系里的矢量。PX4 用MAV_SENSOR_ORIENTATION枚举表达朝向，定义直接写在 msg/DistanceSensor.msg：
| 常量 | 值 | 含义 |
|---|---|---|
ROTATION_YAW_0~YAW_315 | 0~7 | 水平面内每 45° 一档（0=朝前，2=朝右，4=朝后，6=朝左） |
ROTATION_UPWARD_FACING | 24 | 朝上（Pitch 90°） |
ROTATION_DOWNWARD_FACING | 25 | 朝下（Pitch 270°） |
ROTATION_CUSTOM | 100 | 自定义，配合消息里的四元数q字段 |
设置途径按优先级：启动参数-R <val>（或 leddar_one 的-r）> 驱动专属参数（SENS_AFBR_ROT、SENS_MB12_x_ROT、SF45_ORIENT_CFG、SENS_CM8JL65_R_0等）> 默认 25。
三个常见场景：
- 传感器水平朝前安装（如前视避障）：
-R 0；朝后-R 4； - 机顶朝上安装（测净空高度）：
-R 24； - 非正交安装（如斜装 45°）：
-R 1（Yaw 45°）等档位；再特殊的情况由部分驱动经orientation=ROTATION_CUSTOM加四元数描述。
mb12xx的逐实例SENS_MB12_x_ROT只给了 0~7（水平 Yaw），因为它的传感器安装面默认朝下，只需转水平角；若你的 mb12xx 装得不朝下，这个驱动就表达不了，应换用支持 24/25 的驱动或参数。
六、校准与调优
6.1 校准命令
目前只有 afbrs50 提供正式校准流程——绝对距离偏移校准，原理是把读数与已知真实距离的差值存为偏移量，下次启动叠加在出厂校准上：
afbrs50 cal start 0.3 # 对准 0.3 m 的平面目标 afbrs50 cal status # 查看结果 afbrs50 cal stop校准结果写入SENS_AFBR_OFS_LO/SENS_AFBR_OFS_HI（低/高激光功率级各一个偏移），置 0 即恢复出厂。其余驱动依赖出厂校准 + 朝向参数，无在线校准命令；I2C 类驱动可用status、ll40ls 可用regdump辅助确认硬件状态。
6.2 信号质量门槛
signal_quality字段（0~100%）是"读数可信度"的统一表达。afbrs50 的SENS_AFBR_QMIN是唯一在驱动层做门槛过滤的参数：低于门槛的测量会以质量 0（无效）发布——消费方丢弃该帧但仍认为传感器在线。调高它会拒绝抖动读数，但远距弱回波恰好是低质量的，也会被一并滤掉，需按场景权衡。ll40ls 的SENS_LL40LS_SMIN对 V3HP 起类似作用。
6.3 帧率与量程的权衡
这是长距 ToF 的普遍矛盾：单帧曝光时间越长，信噪比越高，可探测距离越远，但更新率越低。
- afbrs50：
SENS_AFBR_PROF一档搞定——Range 档在 LV85D/LX85D 上取 20/15 Hz 保量程，Fast 档取原生 50/25 Hz 供光流与近地地形跟随；也可用SENS_AFBR_RATE/SENS_AFBR_DFM细调（显式设置会覆盖 profile）。DFM 开启后基础无歧义量程（LV85D 12.5 m、LX85D 25 m）×4 或 ×8，代价是帧时间变长。 - GRF：
GRF_RATE_CFG1~50 Hz 可选，默认 5 Hz——长距激光不必追求高帧率，提高速率换取的是时间分辨率。 - SF45：
SF45_UPDATE_CFG最高 5000 Hz，是 PX4 中帧率上限最高的距离驱动，适合需要密集时序的场景。
七、DistanceSensor.msg 字段逐项解读
结合 msg/DistanceSensor.msg 源码，各字段含义与消费方关注点：
| 字段 | 类型 | 含义 | 下游怎么用 |
|---|---|---|---|
timestamp | uint64 | 系统启动以来的微秒时间戳 | 多传感器时间对齐 |
device_id | uint32 | 器件唯一 ID（总线类型+总线号+器件类型编码） | 区分同总线多传感器，重启后不变 |
min_distance/max_distance | float32 | 可测量程上下限（米） | 读数越界时判定为无效 |
current_distance | float32 | 当前距离（米） | EKF2 高度融合、定高、地形跟随的直接输入 |
variance | float32 | 测量方差（m²）；0 表示未知/无效 | 融合时的权重依据 |
signal_quality | int8 | 0~100%，0=无效，-1=未知 | 消费方据此丢帧，如SENS_AFBR_QMIN配合它工作 |
type | uint8 | 0=LASER、1=ULTRASOUND、2=INFRARED、3=RADAR | 不同物理原理的量程特性差异，估计器可区别对待 |
h_fov/v_fov | float32 | 水平/垂直视场角（弧度） | 光流融合、覆盖范围计算 |
orientation+q | uint8 + float32[4] | 朝向枚举或自定义四元数 | 把标量距离变换到机体坐标系的方向向量来源 |
mode | uint8 | 1=启用、2=禁用、0=未知 | 健康状态上报 |
每个驱动在初始化时通过set_rangefinder_type()声明自己的type（如 AerotennaULanding.cpp 声明 RADAR、SRF02.cpp 声明 ULTRASOUND），下游无需关心具体硬件。
八、故障诊断：按症状找原因
| 症状 | 可能原因 | 排查动作 |
|---|---|---|
start报找不到设备 | 总线选错（-I/-X 与实际挂载不符）；地址错 | 换-X/-b <总线号>重试；确认-a与硬件地址一致；I2C 工具（如i2c扫描命令）列出总线上实际器件 |
| 启动即退出、无提示 | 非静默模式下驱动未检测到器件就退出 | 加-q静默启动后再status查看内部状态；确认驱动 Kconfig 开关已编入固件 |
| 地址冲突（读到别人的数据/总线错误） | 同总线多 I2C 器件地址相同 | -a指定正确地址；mb12xx 用set_address改写传感器自身地址；VL53 系列利用 XSHUT 逐台改址 |
| 读数方向反了/偏了 90° | 安装朝向没设 | 核对-R/SENS_*_ROT；朝下=25、朝前=0、朝上=24（见第五章） |
| 串口驱动不自动启动 | SENS_*_CFG未设置或指向的串口被占用 | QGC 参数里确认该 CFG 参数选了正确端口编号；log查看启动脚本是否执行了对应 start 命令 |
| 数据抖动、频繁跳变 | 目标表面弱反射/吸波（超声波尤其敏感）；质量门槛过低 | 提高SENS_AFBR_QMIN或SENS_LL40LS_SMIN；检查安装面下方是否有遮挡、格栅；雷达类确认目标材质 |
| 读数恒为最大量程 | 超出物理量程或信号过弱 | 用标准距离验证：靠近目标后读数应下降；afbrs50 可调SENS_AFBR_MODE/SENS_AFBR_PROF换量程模式 |
| 参数改完没反应 | 绝大多数SENS_EN_*与朝向参数reboot_required | 改参后重启，或reboot后再验证 |
九、选型决策清单
| 你的需求 | 推荐 | 理由 |
|---|---|---|
| 预算有限、入门定高/简单避障 | tfmini（串口）或 vl53l1x（I2C） | 价格最低，自动启动省心，驱动最活跃 |
| 20 m 内中距定高，I2C 总线 | teraranger（TREvo 系列） | 自动检测型号，48 默认地址，量程覆盖好 |
| 长距（百米级）激光测地 | leddar_one 或 lightware_grf_serial | 量程数百米，GRF 支持 50 Hz |
| 需要最高帧率时序 | lightware_sf45_serial | 最高 5000 Hz，且额外发布 obstacle_distance |
| 雨天/低能见度探测 | ulanding_radar | 毫米波穿透雨雾，RADAR 类型，自动启动 |
| 多方向/扇区测距 | sony_asdt1 或 cm8jl65 | 前者激光多点，后者红外多区域，均发布 obstacle_distance |
| 近距（<10 m）超声波，抗强光 | mb12xx / srf02 / pga460 | 声波不受光照影响；mb12xx 支持 12 实例环绕布阵，pga460 自带假读数过滤 |
| PWM 接口老机型 | ll40ls（PWM 模式） | 一个SENS_EN_LL40LS=1切换 |
| 需要绝对精度、可调优空间最大 | afbrs50 | 唯一带在线校准命令，参数族覆盖模式/帧率/DFM/质量门槛 |
| 前视避障（水平安装） | GRF / sf45 / tfmini +-R 0 | 支持水平朝向档位，量程满足前视需求 |
结语
PX4 用"统一 CLI + 统一 uORB 消息"把 22 款物理原理各异的距离传感器收敛成一套可预期的接入流程：接对线、开对 Kconfig、设对使能与朝向参数，剩下的调优空间就藏在几个质量门槛与帧率量程参数里。
【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址: https://gitcode.com/gh_mirrors/px/PX4-Autopilot
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
