发那科（FANUC）机械臂 ROS2 入门教程

echo "Installing and configuring git-lfs"
sudo apt install git-lfs
git lfs install

echo "Checking out GitHub repositories"
mkdir ~/ws_fanuc/src -p
cd ~/ws_fanuc/src
git clone https://github.com/FANUC-CORPORATION/fanuc_description.git
git clone --recurse-submodules https://github.com/FANUC-CORPORATION/fanuc_driver.git

echo "Installing FANUC dependencies"
cd ~/ws_fanuc
sudo apt update
rosdep update
rosdep install --ignore-src --from-paths src -y

echo "Building FANUC libraries"
colcon build --symlink-install --cmake-args -DBUILD_TESTING=1 -DBUILD_EXAMPLES=1

2.2.2 Debian系统安装FANUC软件包

Debian软件包将于未来日期提供。

2.3 启动URDF可视化

view_crx启动文件可在Rviz中可视化URDF模型，并提供滑块条以可视化特定关节状态。

source /opt/ros/humble/setup.bash
source ~/ws_fanuc/install/setup.bash
ros2 launch fanuc_crx_description view_crx.launch.py robot_model:=crx10ia

2.4 创建Moveit配置文件

fanuc_moveit_config是一个示例MoveIt配置包，支持以下机器人型号：

CRX-5iA
CRX-10iA
CRX-10iA/L
CRX-20iA/L
CRX-30iA
CRX/30-18A

若需使用其他型号，请参照本页说明创建专属的MoveIt配置包。

2.5 模拟硬件启动

fanuc_moveit启动文件将通过ros2_control与MoveIt2启动ROS进程，用于控制URDF模型。

source /opt/ros/humble/setup.bash
source ~/ws_fanuc/install/setup.bash
ros2 launch fanuc_moveit_config fanuc_moveit.launch.py robot_model:=crx10ia use_mock:=true

RViz将启动CRX-10iA的可视化展示。

拖动3D箭头为机器人设定目标姿势。然后点击“规划与执行”按钮，模拟机器人规划并执行到达目标的运动轨迹。

2.5.1 动态缩放轨迹执行

fanuc_moveit启动文件配置了缩放关节轨迹控制器（SJTC），使我们能够在轨迹执行过程中减速和暂停。

通过滑块发布器将轨迹速度缩放因子设为10%。拖动IMarker至新位置并点击“规划与执行”，机器人将缓慢移动至目标点。现在将速度缩放因子设为0%，观察其暂停动作。恢复至100%后，机器人将以额定速度完成剩余轨迹。

2.6 物理硬件启动

现在我们将使用相同的SJTC在物理硬件上运行。使用相同的fanuc_moveit启动文件，但提供不同的参数集，以使用物理硬件接口而非模拟硬件。

2.6.1 机器人控制器设置

所需软件版本：

R-30iB Plus、R-30iB Mate Plus：V9.40P/81或更高版本
R-30iB Mini Plus：V9.40P/77或更高版本
R-50iA系列：V10.10P/26或更高版本

所需软件选项：

J519 流式运动控制与 R912 远程运动控制，或
S636 外部控制套件（含 J519 和 R912）

确认已安装所需机器人控制器软件

显示完整菜单。
选择状态。
选择版本标识。
选择配置。

注释

软件选项按字母顺序排列。
光标移动至找到Stream Motion J519和Remote Motion R912或S636外部控制套件为止。
若无法找到Stream Motion J519和Remote Motion R912，或S636外部控制套件，请联系发那科获取软件选项。

2.6.2 设置有效载荷参数

精确设置机器人的有效载荷至关重要。

ROS 2驱动程序v1.1.0及控制器软件V9.40P/84之前版本

修改有效载荷需客户端执行以下步骤：

使机器人停止运行。
停用硬件接口。
修改有效载荷调度计划。
重新激活硬件接口。
恢复应用程序运行。

ROS 2驱动程序v1.1.0及控制器软件V9.40P/84之后版本

可通过ROS 2服务实时调整有效载荷值或补偿参数。详见《设置有效载荷值与补偿参数》。

2.6.3 驱动程序网络配置

FANUC ROS 2驱动程序需通过网络连接至机器人，可选用端口1或端口2。建议驱动程序与机器人间的通信端口需与所有其他以太网通信隔离。

首先为每个以太网连接设置IP地址。

若您的计算机拥有两个网络接口（一个用于连接互联网，另一个用于连接机器人控制器），则需为每个接口创建不同的连接配置文件。设置时请点击屏幕右上角的箭头，然后依次点击设置 > 网络。

拔掉计算机与网络基础设施之间的以太网线。此时两个有线接口中的一个将显示为“电缆未插入”。点击该有线适配器旁的齿轮图标。

在“标识”选项卡下，为该配置文件命名（如“互联网”）。
点击“应用”接受其他设置的默认值。
重新插入以太网线。

现在点击另一网络适配器旁的齿轮图标。

在“标识”选项卡下，为连接配置文件命名（如“机器人”）。
在“IPv4”选项卡中，将IPv4方法设为“手动”。
地址栏输入192.168.1.101，子网掩码输入255.255.255.0。
点击“应用”。

2.6.4 机器人网络配置

定义端口后，您需要通过主机通信界面配置该端口。

2.6.5 启动带驱动程序的CRX-10iA

source /opt/ros/humble/setup.bash
source ~/ws_fanuc/install/setup.bash
ros2 launch fanuc_moveit_config fanuc_moveit.launch.py robot_model:=crx10ia robot_ip:="192.168.1.100"

您可以使用之前相同的IMarker工作流来控制运动。

注意

请参阅控制器使用说明以了解可用控制器的更多信息。

2.6.6 设置I/O值

要通过操作箱监控I/O状态，请在操作箱上遵循以下说明。

随后将显示以下窗口，其中列出了所有I/O类型及其当前状态。

现在通过ROS 2命令行界面修改一个布尔输入输出：

ros2 service call /fanuc_gpio_controller/set_bool_io fanuc_msgs/srv/SetBoolIO "{io_type: {type: 'DO'}, index: 1, value: true}"

该吊坠现在将显示I/O状态为ON：

注意

请参阅控制器定制部分，了解如何通过 ros2_control 和命令行监控及设置 I/O。

2.6.7 获取支持

请联系您所在地区的发那科销售代表。为加快处理您的请求，请提供机器人型号、配置和应用等信息，以便我们确定最佳支持方案。

三、fanuc_description

3.1 概述

本仓库包含适用于发那科机器人的URDF xacros和网格资产，以及URDF组合与可视化的示例。

3.1.1 仓库结构

├── fanuc_crx_description
│   ├── launch
│   │   └── view_crx.launch.py
│   ├── meshes
│   │   ├── crx10ia
│   │   │   ├── collision
│   │   │   │   └── ...
│   │   │   └── visual
│   │   │       └── ...
│   │   └── ... other models
│   ├── robot
│   │   ├── crx10ia.urdf.xacro
│   │   └── ... other example top-level xacro files
│   ├── rviz
│   │   └── view_crx.rviz
│   ├── urdf
│   │   ├── crx10ia_urdf_macro.xacro
│   │   └── ... other models
│   ├── CMakeLists.txt
│   └── package.xml
└── README.md

描述文件按发那科机器人手臂型号系列进行组织。

3.1.2 软件包结构

软件包包含以下子目录：

meshes/：各机器人的视觉网格与碰撞网格。
urdf/：生成特定机器人模型描述（URDF格式）的基础xacro宏文件。
robot/：生成完整URDF文件（含机器人模型）的示例顶级xacro文件。
launch/和rviz/：用于在robot/目录中可视化机器人的Launch文件及配置。

3.2 扩展机器人模型

3.2.1 Xacro命名规范

为提高文件复用性，我们采用以下Xacro命名规范：

*.urdf.xacro：此为顶级Xacro文件，启动文件将通过它生成完整的机器人描述（以URDF格式呈现）。
*_urdf_macro.xacro：仅包含生成URDF的xacro:macro定义，供*_urdf.xacro或其他*_urdf_macro.xacro文件使用。
*_ros2_control_macro.xacro：同理，此文件仅包含生成URDF用ros2_control标签的xacro:macro定义。

3.2.2 顶级xacro组合示例

以下示例展示如何复用提供的描述文件。树形结构反映了xacro文件的xacro:include层级关系。

3.2.2.1 用于URDF可视化

package://fanuc_crx_description/crx10ia.urdf.xacro 提供了一个基础URDF构造示例，未包含ros2_control扩展功能。

├── package://fanuc_crx_description/crx10ia.urdf.xacro
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro

3.2.2.2 对于物理硬件

package://fanuc_hardware_interface/crx10ia.urdf.xacro 提供了一个示例，展示如何使用 fanuc_crx_description 的 xacro:macro 定义，并通过添加 ros2_control 标签进行扩展。

├── package://fanuc_hardware_interface/crx10ia.urdf.xacro
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro
│   ├── package://fanuc_hardware_interface/crx_physical_ros2_control_macro.xacro

3.2.2.3 对于模拟硬件

package://fanuc_hardware_interface/crx10ia.urdf.xacro 接受一个 xacro 参数 use_mock，用于选择使用哪个打包的 ros2_control xacro:macro 定义文件。当 use_mock 设置为 true 时，系统将选择 crx_mock_ros2_control_macro.xacro 文件替代 crx_physical_ros2_control_macro.xacro。

├── package://fanuc_hardware_interface/crx10ia.urdf.xacro
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro
│   ├── package://fanuc_hardware_interface/crx_mock_ros2_control_macro.xacro

3.2.2.4 用于您的定制仿真

此文件结构支持在使用其他仿真器时，通过自定义 ros2_control 标签轻松复用 CRX URDF 宏。此时，您的顶级 xacro 将暴露额外参数以选择其他仿真器，并使用对应的 ros2_control xacro:macro 定义文件。

├── package://MY_WORKCELL/crx10ia.urdf.xacro
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro
│   ├── package://CUSTOM_SIMULATOR/crx_CUSTOM_ros2_control_macro.xacro

3.2.3 用于配备抓取器的定制工作单元

最后，当您向机器人集成额外的URDF和ros2_control定义时，建议采用类似下文的文件结构。

├── package://MY_WORKCELL/MY_ROBOT_GEN1.urdf.xacro # Defines the robot base geometry
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro
│   ├── package://fanuc_hardware_interface/crx_physical_ros2_control_macro.xacro
│   ├── package://GRIPPER_VENDOR_DESCRIPTION/GRIPPER_urdf_macro.xacro
│   ├── package://GRIPPER_VENDOR_DESCRIPTION/GRIPPER_physical_ros2_control_macro.xacro

随着机器人的不断改进，这将提升其组合能力。

├── package://MY_WORKCELL/MY_ROBOT_GEN2.urdf.xacro # Defines the robot base geometry
│   ├── package://fanuc_crx_description/crx10ia_urdf_macro.xacro
|       ├── package://fanuc_crx_description/fanuc_common_urdf_macro.xacro
│   ├── package://fanuc_hardware_interface/crx_physical_ros2_control_macro.xacro
│   ├── package://GRIPPER_VENDOR_2_DESCRIPTION/GRIPPER_urdf_macro.xacro
│   ├── package://GRIPPER_VENDOR_2_DESCRIPTION/GRIPPER_physical_ros2_control_macro.xacro

四、fanuc_driver

4.1 概述

本仓库包含FANUC硬件接口实现、ros2_control缩放关节轨迹控制器（SJTC）、ros2_control配置文件、MoveIt2配置文件，以及使用模拟硬件和物理硬件启动运动规划的示例。

4.1.1 仓库结构

Folder	Description
fanuc_controllers	专为发那科机械手设计的控制器。
fanuc_forward_command	使用ros2_controllers中的forward_command_controller与发那科机械手进行配置及示例。详细文档请参阅fanuc_forward_command/README.md
fanuc_hardware_interface	FANUC机器人控制器的硬件接口。FANUC机器人模型的URDF文件位于fanuc_hardware_interface/robot目录。
fanuc_libs	FANUC外部控制协议的库函数。
fanuc_msgs	提供FANUC控制器支持的消息与服务。
fanuc_moveit_config	FANUC机器人的MoveIt配置方案。
slider_publisher	为缩放关节轨迹控制器提供缩放输入。

4.1.2 功能列表

4.1.2.1 自ROS 2驱动程序v1.0.0及控制器软件V9.40P/77起支持

缩放关节轨迹控制器。
自动处理丢失的命令数据包。
当指令超出机器人的加速度和加加速度限制时自动平滑处理。
GPIO控制器。
读取和设置I/O及数值寄存器。
获取机器人状态。
设置有效载荷调度。

4.1.2.2 自ROS 2驱动程序v1.1.0及控制器软件V9.40P/84版本起支持：

当指令超出机器人协作速度限制时自动限速。
前向位置控制器。
获取与设置位置寄存器。
设置有效载荷值及有效载荷补偿。

4.2 发那科开箱指南

本文详细说明如何为使用ros2_control驱动程序的用户配置新发那科机器人。

4.2.1 发那科设置

必须完成以下连接：

Cable	Robot Base	Robot Controller	ROS 2 PC
Ethernet		x	x
Power	x
Teach Pendant		x
RMP / Robot Connection Cable	x	x
GND	x	x

例如，下图展示了CRX-10iA/L机器人在R-30iB Mini Plus控制器上的连接方式。其他机器人型号请参阅发那科机器人文档。

4.2.2 网络设置

4.2.2.1 网络设备注意事项

良好的网络设计对可靠运行至关重要。必须特别关注布线规范及影响电缆系统和设备的环境条件。同时需控制网络流量，避免浪费网络带宽和设备资源。

请牢记以下布线规范与环境考量：

使用符合1Gbps以太网应用及环境要求的5e类双绞线（或更高规格）。需权衡屏蔽与非屏蔽双绞线缆的选择。
严格遵守布线规范，例如交换机至设备的最大距离（100米）。
切勿超过所用线缆的推荐弯曲半径。
选用适配环境的连接器。除标准开放式RJ45接口外，还应根据适用场景选用各类工业以太网连接器。
布线时应避开电气或磁场干扰源，或以90度角度交叉布线，以最大限度减少以太网网络中的感应噪声。

4.2.2.2 管理网络流量时请谨记以下要点

通过限制碰撞域来控制或消除冲突。
通过限制广播域来控制广播流量。
使用支持IGMP监听的多播感知交换机控制多播流量。
在高要求应用中采用QOS（服务质量）技术。

以太网网络中碰撞问题由来已久，但通过采用交换机（而非集线器）及全双工连接可完全规避。任何以太网网络都必须使用交换机和全双工连接，这能将碰撞域缩小至单个设备，从而杜绝碰撞发生。机器人接口默认采用自动协商机制，将使用最快的连接方式。

4.3 控制器用法

当前支持的FANUC专用控制器包括：

scaled_joint_trajectory_controller：标准joint_trajectory_controller的变体，支持将速度在0%至100%范围内进行缩放调节。
fanuc_gpio_controller：提供访问控制器数据的功能，包括I/O、数值寄存器、位置寄存器、机器人状态及有效载荷。

4.3.1 fanuc_controllers/scaled_joint_trajectory_controller

此控制器是标准关节轨迹控制器的变体，支持将速度在0%至100%范围内进行缩放调节。

4.3.1.1 速度缩放

速度缩放值为0至100之间的浮点数，代表机器人沿轨迹执行的速度百分比。
scaled_joint_trajectory_controller订阅此速度缩放值，并生成自动调节速度的指令，使速度在0%（机器人停止）至100%（机器人全速运行）之间变化。
提供/speed_scaling_factor主题以实现机器人速度调节。

4.3.1.2 协作速度钳位功能

协作机器人配备协作速度钳位功能。机器人控制器会自动降低指令速度，确保其不超过协作速度限制。
scaled_joint_trajectory_controller通过状态接口从fanuc_driver接收Status/collaborative_speed_scaling值，从而最小化指令位置与实际位置的偏差。
当协作速度限速禁用输入为ON时，该功能失效。详情参见《协作机器人功能手册》。

注意

当原始轨迹不平滑或超出机器人模型能力时，即使启用限速功能，运动仍可能出现抖动或超速风险。

由于机器人控制器无法预知未来轨迹，系统会基于保守假设在接近极限前提前降速。为实现最佳性能，请禁用该功能并设计使机器人所有部位均保持在协作速度限制以下的运动轨迹。

4.3.2 fanuc_controllers/fanuc_gpio_controller

此控制器提供访问控制器数据的功能，包括I/O、数值寄存器、位置寄存器、机器人状态及有效载荷等。

4.3.2.1 已发布主题

~/io_cmd [fanuc_msgs/msg/IOCmd]: 同步布尔I/O命令（如DO、RO、F）
~/io_state [fanuc_msgs/msg/IOState]: 同步布尔I/O状态（如DO、DI、RO、RI、F）
~/analog_io_cmd [fanuc_msgs/msg/AnalogIOCmd]：同步模拟I/O命令（如AO）
~/analog_io_state [fanuc_msgs/msg/AnalogIOState]：同步模拟I/O状态（如AO、AI）
~/num_reg_cmd [fanuc_msgs/msg/NumRegCmd]：同步数值寄存器命令
~/num_reg_state [fanuc_msgs/msg/NumRegState]：同步数值寄存器状态
~/connection_status [fanuc_msgs/msg/ConnectionStatus]：发布机器人是否连接状态。若此值为false，则无法向机器人发送命令。
~/robot_status [fanuc_msgs/msg/RabotStatus]: 同步机器人状态（例如：in_error, tp_enabled, e_stopped, motion_possible, contact_stop_mode）。contact_stop_mode 发布整数值，定义如下：
0: 无效（机器人非协作模式或安全传感器禁用）

1: 安全模式

2: 停止状态

3: DSBL模式

4: ESCP模式
~/robot_status_ext [fanuc_msgs/msg/RobotStatusExt]: 异步机器人状态（如错误代码、运动中、驱动器通电、原生覆盖、速度钳位限制）
~/协作速度钳位 [fanuc_msgs/msg/CollaborativeSpeedScaling]: 发布机器人控制器的协作速度钳位缩放值，取值0或1。对于非协作机器人，此值始终为1。该值将通过状态接口自动应用于scaled_joint_trajectory_controller控制器，以最小化路径偏差。若需自定义缩放系数，可使用主题/speed_scaling_factor。

4.3.2.2 广告服务

~/get_bool_io [fanuc_msgs/srv/GetBoolIO]：获取异步布尔I/O（如DO、DI、RO、RI、F）
~/get_analog_io [fanuc_msgs/srv/GetAnalogIO]：获取异步模拟I/O（如AO、AI）
~/get_group_io [fanuc_msgs/srv/GetGroupIO]: 获取异步组I/O（如GO、GI）
~/get_num_reg [fanuc_msgs/srv/GetNumReg]: 获取异步数值寄存器
~/get_pos_reg [fanuc_msgs/srv/GetPosReg]: 获取异步位置寄存器
~/set_bool_io [fanuc_msgs/srv/SetBoolIO]: 设置异步布尔I/O（如DO、RO、F）
~/set_analog_io [fanuc_msgs/srv/SetAnalogIO]: 设置异步模拟I/O（如AO）
~/set_group_io [fanuc_msgs/srv/SetGroupIO]: 设置异步组I/O（如GO）
~/set_num_reg [fanuc_msgs/srv/SetNumReg]: 设置异步数值寄存器
~/set_pos_reg [fanuc_msgs/srv/SetPosReg]: 设置异步位置寄存器
~/set_gen_override [fanuc_msgs/srv/SetGenOverride]: 设置机器人代数覆盖值。当硬件接口处于活动状态时，此值需保持为100。
~/set_payload_id [fanuc_msgs/srv/SetPayloadID]: 设置机器人负载调度编号。
~/set_payload_value [fanuc_msgs/srv/SetPayloadValue]: 设置机器人有效载荷数值。
~/set_payload_comp [fanuc_msgs/srv/SetPayloadComp]: 设置机器人有效载荷补偿值。

4.3.2.3 获取和设置异步位置寄存器

机器人控制器软件V9.40P/80及以上版本与ROS 2驱动程序v1.1.0及以上版本支持通过ROS 2服务获取和设置异步位置寄存器。

4.3.2.3.1 获取异步位置寄存器 [fanuc_gpio_controller/get_pos_reg]

若位置寄存器采用笛卡尔表示法，可读取配置参数与位置数据；若采用关节表示法，则可读取关节角度。
响应中无关字段仍将显示为零值，请忽略。

4.3.2.3.2 设置异步位置寄存器 [fanuc_gpio_controller/set_pos_reg]

若位置寄存器采用笛卡尔表示法，则需提供配置参数与位置参数；若采用关节表示法，则需提供关节角度参数。
表示法字符串（‘Cartesian’ 或 ‘Joint’）不区分大小写。若未指定或错误指定表示法，将默认采用笛卡尔表示法。
若服务调用中缺少必填字段，该字段将默认自动设为0。

4.3.2.4设置有效载荷值与有效载荷补偿

机器人控制器软件V9.40P/80及以上版本与ROS 2驱动程序v1.1.0及以上版本支持通过ROS 2服务实时设置有效载荷值与有效载荷补偿。

4.3.2.4.1 设置有效载荷值 [fanuc_gpio_controller/set_payload_value]

ROS 2 服务单位：
- 质量：kg
- 重心：m
- 惯性矩：kgm²
“use_in” 为布尔值，用于指示机器人是否设置惯性值。True 表示机器人将设置惯性值，False 表示机器人将忽略惯性值。
该服务的所有参数均为必填项。若调用时缺少参数，该参数将默认自动设置为 0。
本服务专为非协作机器人设计。协作机器人应使用专属服务设置有效载荷补偿。若协作机器人使用本服务，有效载荷值仍将被设置，但因有效载荷属于DCS设置范畴，流式运动与RMI将终止，ROS 2驱动程序将发布“不再流式传输”错误。用户需应用DCS、循环供电、确认有效载荷并重启ROS 2驱动程序才能继续。
若有效载荷调度编号无效或超出范围，服务将返回失败。

4.3.2.4.2 设置有效载荷补偿 [fanuc_gpio_controller/set_payload_comp]

ROS 2服务单位：
- 质量：kg
- 重心：m
- 惯性矩：kgm²
服务中所有参数均为必填项。若调用时参数缺失，该参数将默认自动设为0。
本服务仅适用于协作机器人。
满足以下任一条件时，服务调用将失败：
- 服务被用于非协作机器人。
- 有效载荷补偿计划与当前控制器有效载荷计划不匹配（即有效载荷补偿计划）。
- 机器人未完全启用有效载荷补偿功能（启用方法详见《操作手册（协作机器人功能）》）。

4.3.2.5 配置高频I/O

选定的GPIO主题支持高频更新。更新速率取决于机器人控制器的采样率。高频更新I/O的选择需通过YAML配置文件在驱动程序启动前完成配置。本节描述YAML文件的行为与限制，并概述其格式结构。

4.3.2.5.1 行为特性

GPIO控制器的YAML配置文件遵循以下行为规范：

GPIO YAML配置文件在启动过程中直接传递至硬件接口。驱动程序项目中提供了GPIO配置文件示例（fanuc_driver/fanuc_hardware_interface/config/example_gpio_config.yaml）。
硬件接口将在初始化早期验证YAML文件，并提示任何错误。
配置文件定义了每种主题类型的内存映射。
无效配置将导致硬件接口初始化失败，并在日志文件中报告错误。
若某主题未被配置（例如应用中无需模拟I/O），该主题将保持空状态。
当GPIO配置YAML文件的命令部分添加输出或数值寄存器时，ROS 2驱动程序启动后，控制器中的这些输出值和数值寄存器值将被设置为false或零。

4.3.2.5.2 限制条件

高频更新周期内可访问的数据点数量受限，因此需设置相应限制。将采用GPIO处理时间因子（PTF）来限制通信周期内访问的I/O数量。用户可根据PTF考量配置YAML文件。

GPIO PTF规格如下：

配置基于驱动启动时的YAML文件一次性设定。
当采样率为1ms时，PTF上限为32。PTF上限值为(32 * (采样率(毫秒)))。
PTF是所有YAML配置项（io_cmd、io_state、num_reg_cmd、num_reg_state等）的总和。
若YAML文件中指定了未分配的I/O，连接时将引发错误。
默认（最差）PTF值等同于YAML配置行的“length”参数值。

4.3.2.5.3 PTF优化最佳实践

注意

数字I/O配置需满足：(PTF = INT((“length” + 31)/32))

配置需位于同一机架、插槽且I/O分配连续

数字输出附加条件：

YAML配置长度为32的倍数
([yaml起始索引] – [I/O配置RANGE起始索引] + [I/O配置START] - 1) 为32的倍数

数字I/O示例：

Robot I/O Assignment:
  #         RANGE       RACK  SLOT START
  1   DO [    1-   10]     0    0     0
  1   DO [   11-  100]    34    1     1

YAML:
  { type: DO, start: 11, length: 64} --> 2 PTF
  { type: DO, start: 21, length: 57} --> 57 PTF

对于模拟I/O：

最佳实践：（PTF将取为INT((“长度” + 1)/2))
- 配置需位于同一机架、插槽且I/O分配连续
- 模拟输出附加条件：
  - 配置长度为2的倍数
  - ([yaml起始索引] – [I/O配置索引] + [I/O配置通道号] - 1) 为2的倍数

数值寄存器中，PTF值与YAML“length”相同。

其他限制：

不支持 GI/GO。
不支持 I/O 仿真。始终访问真实 I/O 值。

4.3.2.5.4 YAML 文件结构

YAML 文件结构如下：

gpio_topic_config:
  io_state: [
    { type: < I/O type >, start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

  io_cmd: [
    { type: < I/O type >, start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

  analog_io_cmd: [
    { type: < I/O type >, start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

  analog_io_state: [
    { type: < I/O type >, start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

  num_reg_cmd: [
    { start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

  num_reg_state: [
    { start: < start pt. >, length: < number of consec. pts. > },
    { < array element N > }
  ]

示例 YAML 文件

gpio_topic_config:
  io_state:
    - type: DI
      start: 11
      length: 1
    - type: DO
      start: 11
      length: 1
    - type: RI
      start: 1
      length: 2
    - type: RO
      start: 1
      length: 2
    - type: F
      start: 1
      length: 32
  io_cmd:
    - type: DO
      start: 11
      length: 1
    - type: RO
      start: 1
      length: 1
    - type: F
      start: 1
      length: 32
  num_reg_state:
    - start: 1
      length: 3
  num_reg_cmd:
    - start: 3
      length: 1

4.4 控制器和广播器的定制化配置

4.4.1 默认GPIO配置

当前GPIO控制器默认启用了一组GPIO引脚。相关配置详见example_gpio_config.yaml文件

该配置文件包含四个主要部分：

io_state 显示所有子列出的IO类型的当前值/状态
io_cmd 命令可用于更改/更新任何子列出的gpio
num_reg_state 显示GPIO状态寄存器的当前值/状态
num_reg_cmd 用于更新GPIO寄存器的命令

各部分下列出的项目均可通过修改/删除/添加来更新GPIO控制器配置。

通过检查example_gpio_config.yaml的部分内容可知：

gpio_topic_config:
  io_state:
    - type: DI
      start: 101
      length: 12
    - type: DO
      start: 101
      length: 12
...
  io_cmd:
    - type: DO
      start: 101
      length: 12

在此，DI IO类型同时出现在io_state和io_cmd下，用户可实现高频读写！

未在配置文件中列出的IO类型仍可通过服务调用在/fanuc_gpio_controller/*主题下进行读写。

4.4.1.1 传递自定义配置文件

启动时可通过在默认ros2启动命令后添加`gpio_configuration:=/path/to/new/config/file`参数，传入独立的gpio配置文件。

4.4.2 使用CLI监控/切换GPIO

用户可通过ROS2提供的GPIO服务，在命令行界面监控或设置IO。

启动ros2后，可通过以下命令列出可用服务：

ros2 service list

GPIO服务位于主题/fanuc_gpio_controller/*下

可通过以下方式获取服务消息的类型：

ros2 service type /fanuc_gpio_controller/get_bool_io

#which would return
fanuc_msgs/srv/GetBoolIO

且所给消息详情可由

ros2 interface show fanuc_msgs/srv/GetBoolIO

# SPDX-FileCopyrightText: 2025, FANUC America Corporation
# SPDX-FileCopyrightText: 2025, FANUC CORPORATION
#
# SPDX-License-Identifier: Apache-2.0

# Supported types:
#  DI
#  DO
#  RI
#  RO
#  F
IOType io_type
 #
 string AI=AI
 string AO=AO
 string DI=DI
 string DO=DO
 string RI=RI
 string RO=RO
 string SI=SI
 string SO=SO
 string WI=WI
 string WO=WO
 string UI=UI
 string UO=UO
 string WSI=WSI
 string WSO=WSO
 string F=F
 string M=M
 string GI=GI
 string GO=GO
 string type
uint16 index
---
int32 result
bool value

从消息类型中可以看出，该服务期望接收名为io_type的字符串参数以及一个索引值，响应时会返回该索引位置下io_type的当前值。

例如，我们尝试先读取DO类型IO中第一个索引的当前状态。

ros2 service call /fanuc_gpio_controller/get_bool_io fanuc_msgs/srv/GetBoolIO "{io_type: {type: 'DO'}, index: 1}"

将响应为

waiting for service to become available...
requester: making request: fanuc_msgs.srv.GetBoolIO_Request(io_type=fanuc_msgs.msg.IOType(type='DO'), index=1)

response:
fanuc_msgs.srv.GetBoolIO_Response(result=0, value=False)

并且值=False

从吊坠上也能看出该端口已关闭。

此端口可通过调用以下命令启用：

ros2 service call /fanuc_gpio_controller/set_bool_io fanuc_msgs/srv/SetBoolIO "{io_type: {type: 'DO'}, index: 1, value: true}"

这将导致

waiting for service to become available...
requester: making request: fanuc_msgs.srv.SetBoolIO_Request(io_type=fanuc_msgs.msg.IOType(type='DO'), index=1, value=True)

response:
fanuc_msgs.srv.SetBoolIO_Response(result=0)

再次运行get_bool_io以查看当前IO状态显示

waiting for service to become available...
requester: making request: fanuc_msgs.srv.GetBoolIO_Request(io_type=fanuc_msgs.msg.IOType(type='DO'), index=1)

response:
fanuc_msgs.srv.GetBoolIO_Response(result=0, value=True)

该值为True

这也可以在吊坠上验证

4.5 创建专属MoveIt配置文件

本指南将演示如何创建基础MoveIt配置包，用于通过fanuc_driver驱动FANUC机器人。

注意

本指南使用以下名称。请根据您的机器人系统替换相应名称。

机器人型号：R-1000iA/100F

robot_model: r1000ia_100f（URDF文件名：r1000ia_100f.urdf.xacro）

机器人系列：r1000ia（描述包名称核心部分：fanuc_r1000ia_description）

MoveIt配置包名称：fanuc_r1000ia_moveit_config

4.5.1 MoveIt设置向导

请遵循官方MoveIt设置向导教程。

在机器人目录中选择一个 xacro 文件（例如 fanuc_r1000ia_description/robot/r1000ia_100f.urdf.xacro）作为启动屏幕加载的 URDF 文件。
创建从 base_link 到 flange 的运动学链作为规划组。
在ROS 2控制器页面和MoveIt控制器页面上点击“自动添加~”按钮即可。
在ros2_control URDF修改页面上选择位置命令、位置状态和速度状态，然后点击添加接口按钮。

4.5.2 修改说明

该配置包需要进行部分修改才能通过fanuc_hardware_interface驱动Fanuc机器人。

将fanuc_moveit_config/config/moveit_controllers.yaml复制到your_moveit_config_package/config目录。
将 fanuc_moveit_config/launch/fanuc_moveit_template.launch.py 复制到 your_moveit_config_package/launch 目录。

4.5.3 启动

# without physical robot
ros2 launch fanuc_r1000ia_moveit_config fanuc_moveit_template.launch.py robot_model:=r1000ia_100f robot_series:=r1000ia moveit_config:=fanuc_r1000ia_moveit_config use_mock:=true
# with physical robot
ros2 launch fanuc_r1000ia_moveit_config fanuc_moveit_template.launch.py robot_model:=r1000ia_100f robot_series:=r1000ia moveit_config:=fanuc_r1000ia_moveit_config use_mock:=false robot_ip:={your robot's ip address}