企业官网建设流程全解析

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件

LightWare GRF250 / GRF500 是专为云台吊舱设计的轻量化激光测距模块，分别具备 250 m 与 500 m 的测量量程，可应用于远距离避障、精准着陆与地形跟随等场景。本文以 PX4 官方传感器文档为核心，结合仓库内lightware_grf_serial驱动的完整源码，系统讲解如何在 PX4 Autopilot 中启用该驱动、完成串口与参数配置、理解其底层二进制协议与初始化状态机，并通过 MAVLink 观测验证测距数据是否正常输出。

产品与驱动概览

GRF250 与 GRF500 是 LightWare 推出的紧凑型激光雷达模块，两者硬件结构相同，区别主要在最大测距量程（250 m / 500 m），因此在 PX4 参数中需要通过传感器型号参数加以区分。二者均通过串口（UART）与飞控通信，属于典型的外部测距传感器（rangefinder）。

PX4 为其提供了串口驱动lightware_grf_serial，源码位于 src/drivers/distance_sensor/lightware_grf_serial，模块名称为lightware_grf_serial，分类为driver / distance_sensor。

需要注意：该驱动不包含在 PX4 默认固件构建中。从 Kconfig 可以看到其配置项默认值为default n，即默认关闭。因此使用 GRF250/GRF500 前，必须先通过菜单配置或直接编辑板级配置文件的方式把驱动加入构建，再重新编译固件并刷写。

硬件连接

激光雷达通过串口与飞控通信，可以连接到任意空闲的串口，例如TELEM2：

• 将模块的 TX 连接飞控对应串口的 RX，模块 RX 连接飞控 TX，并共地；
• 供电要求请以模块数据手册为准，注意与飞控电源共地，避免电平漂移导致通信异常；
• 串口波特率由驱动固定配置为115200 baud，8 数据位、无校验、1 停止位、无硬件流控（详见下文源码解析）。

连接完成后，具体使用哪个串口以及传感器朝向等属性，通过 PX4 参数进行配置，见下一节。

PX4 配置

PX4 侧的配置分为两步：先把驱动加入固件构建，再通过参数指定串口与传感器型号。

添加驱动到 PX4 构建

有两种等效方式，任选其一。

方式一：使用 menuconfig（推荐交互式操作）

1. 安装并打开 PX4 的 menuconfig，参见 移植与配置指南；
2. 依次进入Drivers > Distance sensors；
3. 勾选（启用）lightware_grf_serial；
4. 保存配置。

方式二：手动编辑板级配置文件default.px4board

打开目标板卡对应的*.px4board配置文件。例如为fmu-v6x系列板卡添加驱动时，编辑 boards/px4/fmu-v6x/default.px4board，在文件中加入以下配置项并保存：

CONFIG_DRIVERS_DISTANCE_SENSOR_LIGHTWARE_GRF_SERIAL=y

该配置键与 Kconfig 中的菜单项DRIVERS_DISTANCE_SENSOR_LIGHTWARE_GRF_SERIAL一一对应，启用后 CMakeLists.txt 会把lightware_grf_serial.cpp、lightware_grf_serial.hpp、lightware_grf_serial_main.cpp三个源文件编入固件，并依赖drivers_rangefinder与px4_work_queue两个库。

从 module.yaml 可见，该驱动只支持单实例（num_instances: 1），同一时刻只能连接一台 GRF 激光雷达。

配置完成后，按 PX4 编译指南 为你的飞控目标板编译固件，并刷写新固件。

参数配置

需要配置三个参数。先按 串口配置 指定传感器连接的串口，再设置传感器朝向等属性。参数含义与取值范围如下表：

参数在 module.yaml 中定义，要点如下：

• GRF_RATE_CFG：官方说明“提高更新率可获得更高的分辨率”，因此在不超出模块能力的前提下可依据应用需求提高采样频率。修改后需要重启（reboot_required: true）。
• GRF_SENS_MODEL：用于区分 GRF250 与 GRF500，因为两者的最大测距量程不同（250 m 与 500 m）。默认值为0（禁用），必须显式设为 1 或 2，否则驱动不会正常工作；修改后同样需要重启。

参数修改可通过 QGroundControl 的参数界面进行，修改完成后重启飞控生效。当SENS_EN_GRF_CFG指向某个串口后，系统会自动以如下命令启动驱动（对应 module.yaml 中的serial_config）：

lightware_grf_serial start -d ${SERIAL_DEV}

其中${SERIAL_DEV}即该串口对应的设备节点（如/dev/ttyS1）。

驱动工作原理：串口协议与初始化状态机

要理解“为什么这样配置”，值得深入驱动源码，其实现位于 lightware_grf_serial.cpp 与 lightware_grf_serial.hpp。

串口参数

驱动在Run()中打开串口设备（O_RDWR | O_NOCTTY | O_NONBLOCK，非阻塞读写），并通过termios配置：

• 波特率固定115200（B115200）；
• 清除CSTOPB | PARENB | CRTSCTS，即 1 停止位、无奇偶校验、无硬件流控；
• 清除ONLCR标志，避免把 LF 自动转换成 CR/LF 而破坏二进制帧。

接线与串口配置时必须与上述参数一致。

GRF 二进制帧格式

驱动与传感器之间采用 GRF 自定义二进制协议（见 grf_commands.h 与grf_get_and_handle_request()/grf_send()实现），帧结构为：

驱动在接收侧逐字节解析帧（状态机GRF_PARSED_STATE：START → FLG_LOW → FLG_HIGH → ID → DATA → CRC_LOW → CRC_HIGH），校验 payload 长度（超过 17 字节判为异常）与 CRC，CRC 不匹配会累计通信错误计数（_comms_errors）并丢弃该帧重新同步。发送侧由grf_format_crc()对起始字节、flags、消息 ID 与数据逐字节计算同一 CRC 后写入帧尾。

四步初始化状态机

驱动启动后按GRF_SERIAL_STATE状态机与传感器完成握手（measure()/collect()）：

1. STATE_UNINIT：发送GRF_PRODUCT_NAME查询产品名，探测传感器是否在线，等待含产品名回复（CRC 校验通过后进入下一步）；
2. STATE_ACK_PRODUCT_NAME：发送GRF_UPDATE_RATE，把更新率写入传感器（驱动内部_update_rate即来自参数GRF_RATE_CFG，默认 5 Hz），并延时 100 ms；
3. STATE_ACK_UPDATE_RATE：发送GRF_DISTANCE_OUTPUT，配置输出内容为原始距离（last return）；
4. STATE_ACK_DISTANCE_OUTPUT：发送GRF_STREAM，启用按更新率持续自动输出，随后进入STATE_SEND_STREAM，持续接收距离数据。

之后驱动每个调度周期（_interval{200000}，即 200 ms）读取并解析一帧。若距离数据超过1 秒未收到（hrt_absolute_time() - _last_received_time >= 1_s），驱动会自动回到STATE_UNINIT重新初始化，实现断线自恢复。

距离数据换算与发布

距离帧GRF_DISTANCE_DATA_CM（44）的 payload 携带 24 位原始距离值（单位 cm），驱动在grf_process_replies()中按raw_distance * GRF_SCALE_FACTOR（缩放因子 0.1）换算为米，再调用_px4_rangefinder.update(now, distance_m)发布到 uORB 的distance_sensor主题（见 distance_sensor.msg），供 EKF、避障模块与 MAVLink 出口消费。

同时，驱动会根据 GRF_SENS_MODEL 设置测距上下限（start()中的switch (_model_type)）：

• GRF250：最小距离 0.1 m，最大距离 250.0 m；
• GRF500：最小距离 0.1 m，最大距离 500.0 m。

这解释了为何必须正确设置型号参数——选错型号会导致量程边界错误，进而影响 EKF 对测距数据的合法性判定。

命令行手动操作

即使不通过参数自动启动，也可以在 PX4 的 nsh 终端（或 MAVLink Shell）中手动管理驱动（命令用法见 lightware_grf_serial_main.cpp）：

# 在指定串口设备上启动驱动（示例：/dev/ttyS1） lightware_grf_serial start -d /dev/ttyS1 # 停止驱动 lightware_grf_serial stop # 查看驱动状态与统计（采样耗时、通信错误计数） lightware_grf_serial status

status会通过print_info()打印_sample_perf（每次读操作耗时统计）与_comms_errors（通信错误计数），可作为排查串口链路是否稳定的第一手依据。

测试验证

固件刷写并完成参数配置后，可按以下步骤确认传感器工作正常：

1. 连接 QGroundControl 地面站；
2. 打开MAVLink Inspector（分析视图）；
3. 观察是否存在DISTANCE_SENSOR消息流。

将传感器对准不同距离的平面来回移动，DISTANCE_SENSOR中的current_distance字段会随距离实时变化，即表明测距数据已正确进入 PX4 数据链路。若传感器朝向与安装姿态有关，还需在参数中配置安装朝向（rotation），使数据符合机体坐标系约定。

故障排查

• 确认驱动已编译进固件：先在 Kconfig 或 boards/px4/fmu-v6x/default.px4board 中确认CONFIG_DRIVERS_DISTANCE_SENSOR_LIGHTWARE_GRF_SERIAL=y生效并重新编译；默认固件中该驱动不存在，任何串口配置都不会生效。
• 串口被占用：若目标串口已被其他外设（GPS、数传等）占用，需要先按 串口配置 中的说明取消默认串口分配，再通过SENS_EN_GRF_CFG指定给激光雷达。
• 检查接线与共地：串口为 115200、无校验、无流控，务必确认 TX/RX 交叉连接且共地。
• 观察驱动统计信息：通过lightware_grf_serial status查看com_err计数是否持续增长；若通信错误持续累积，多半是接线/波特率/电平问题。
• 确认型号参数：GRF_SENS_MODEL必须设为1（GRF250）或2（GRF500），否则驱动量程配置错误，且该参数修改后需要重启飞控。
• 确认更新率参数：GRF_RATE_CFG修改后同样需要重启；若数据流频率异常，可先设为默认4（5 Hz）验证链路。

小结

在 PX4 Autopilot 中启用 LightWare GRF250/GRF500 的核心路径可概括为：将lightware_grf_serial驱动加入构建（menuconfig 或default.px4board）→ 重新编译刷写固件 → 通过SENS_EN_GRF_CFG绑定串口、GRF_SENS_MODEL选择型号、GRF_RATE_CFG设置更新率 → 在 QGroundControl 的 MAVLink Inspector 中验证DISTANCE_SENSOR.current_distance变化。理解驱动源码中的二进制帧协议、CRC-16 校验、四步初始化状态机与 1 秒超时自恢复机制，有助于在链路异常时快速定位问题，并在此基础上针对远距离测距应用做进一步的参数调优。

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件