外部轴配置与直线导轨联动使用说明

1 简介

本文用于说明外部轴从配置到使用的基础流程，重点覆盖单直线导轨场景：控制柜配置文件准备、EtherCAT 网口编号配置、ARCS 界面添加外部轴、加入轴组、移动页点动验证，以及通过 moveJointWithAxisGroup 和 moveLineWithAxisGroup 执行机器人与导轨联动运动。

本文中的 GIF、视频和 single_rail_y_two_lines.lua 为同一个单直线导轨摆焊 demo，三者应配套参考：

• single_rail_y_two_lines.lua
• 单直线导轨摆焊 demo GIF
• 单直线导轨摆焊 demo 视频
• multi_rail_yxz_two_lines.lua
• 多自由度导轨摆焊 demo GIF
• 多自由度导轨摆焊 demo 视频

多直线导轨使用方式先保留占位，本文只说明参数组织规则，不展开完整示教流程。

2 资料与附件

资料中的验证环境为 ARCS 0.10.0-alpha.xx、App 0.32.1-alpha.xx 系列。现场使用时以当前项目发布版本为准，配置项名称和入口若有差异，优先按实际版本界面操作。

3 控制柜配置

3.1 配置 aubo_control.conf

将外部轴配置写入 /root/arcs_ws/config/aubo_control.conf。示例中关键点如下：

1. [[ExAxis]] 配置外部轴硬件接口，示例别名为 ecat_axis1。
2. [[RobotAlgorithm]] 中启用外部轴算法参数，例如 enable_axis = true、axis_name、axis_dir、行程和速度限制。
3. [[RobotModule]] 中通过 axis_hw = "ecat_axis1" 关联外部轴硬件。

3.2 放置 EtherCAT 配置文件

将 ecat/ 目录和 ecat_master.conf 放到 /root/arcs_ws/config/ 下。

ecat_master.conf 中重点确认：

1. eni_path 指向实际使用的 ENI 文件。
2. nic_number 保持未注释，并与 EtherCAT 网口编号一致。若网口名为 enpXs0，则 nic_number = X，例如 enp2s0 对应 nic_number = 2。
3. cyclic_time 与工程配置一致，示例为 4000，表示 4ms。
4. 被 # 注释的配置项不生效，示例中的 #nic_mac 不需要修改。

3.3 确认 EtherCAT 网口编号

在控制柜终端执行 ip link 或 ifconfig 查看外部轴 EtherCAT 接线网口名称，按 enpXs0 中的 X 配置 nic_number。

示例：

[[EtherCATMaster]]
    type="igh"
    instance_id=0
    nic_number=2
    cyclic_time=4000
    bind_cpu=1
    #nic_mac="96:96:95:32:D4:BD"

上例只需要关注未注释的 nic_number=2。#nic_mac 已被注释，不参与当前配置。

外部轴物理连接参考如下：

4 ARCS 界面配置

4.1 安装对应版本

安装支持外部轴配置的 App 和 ARCS 版本。资料中的联调版本如下图所示：

4.2 标定线坐标系

直线导轨需要先建立线坐标系。进入“配置 > 一般 > 坐标系”，选择“线”方式新建坐标系：

1. 第一示教点作为线坐标系原点。
2. 第一示教点指向第二示教点的方向，表示外部轴相对于 Base 坐标系的正方向。
3. 若后续点动方向与预期相反，优先检查两点顺序、轴方向配置和传动比符号。

4.3 添加外部轴

进入“配置 > 一般 > 外部轴”。

点击“添加轴”，选择状态为“正常”的目标外部轴。

当前资料中的外部轴类型按直线导轨使用，选择“导轨”。

4.4 配置导轨参数

在参数页确认外部轴名称、同步状态、坐标系、有效行程、最大速度、最大加速度和“每米跳数”。

界面中的“每米跳数”按资料含义实际表示：电机每转一圈，导轨产生的线性位移，单位建议统一为 m/rev。常用计算方式如下：

S = L / i

其中：

• S：电机每转一圈对应的导轨位移，单位 m/rev。
• L：导轨传动端每转一圈的直线位移，单位 m/rev。
• i：总减速比，定义为“电机转数 / 导轨传动端转数”。

常见机构可按下面计算，所有 mm 单位先换算为 m：

丝杠导轨：S = P / i
同步带导轨：S = Zb * Pb / i
齿轮齿条导轨：S = pi * d / i
齿轮齿条导轨：S = pi * m * z / i

参数含义：

• P：丝杠导程。
• Zb：同步带主动轮齿数。
• Pb：同步带齿距。
• d：小齿轮节圆直径。
• m：齿轮模数。
• z：小齿轮齿数。

例如齿轮齿条导轨的小齿轮齿数 z = 25、模数 m = 1.5 mm、减速比 i = 10，则：

S = pi * 0.0015 * 25 / 10 = 0.01178 m/rev

4.5 轴组管理

轴组用于把机器人和一个或多个外部轴组织成同一个联动对象。后续在移动页选择目标轴组，或在脚本中调用 moveJointWithAxisGroup()、moveLineWithAxisGroup() 时，传入的 group_name 都必须与该轴组名称一致。

轴组管理需要关注三件事：

1. 轴组名称：例如 "轴组_1"，脚本和界面中保持一致。
2. 外部轴顺序：外部轴加入轴组的顺序，就是后续 extq 的顺序。
3. 外部轴方向：每根直线导轨需要有相对 Base 坐标系的正方向，脚本里由 axisGroupAddAxis() 的最后一个参数指定。

进入目标轴组，点击“加入轴组”。

选择目标外部轴并添加。轴组中外部轴的加入顺序，就是后续 extq 参数的顺序。

脚本/API 与界面操作的对应关系如下：

单直线导轨示例：

local group = "轴组_1"

axisGroupDelete(group)
axisGroupAdd(group, {0, 0, 0}, "base")
axisGroupAddAxis(group, "fake_axis1", group, {0, 1, 0})
enableAxisGroup(group)

多直线导轨时，按机械串联关系依次加入外部轴，并保证后续 extq 按同样顺序传值：

local group = "rail2"

axisGroupDelete(group)
axisGroupAdd(group, {0, 0, 0}, "base")
axisGroupAddAxis(group, "rail_x", group, {1, 0, 0})
axisGroupAddAxis(group, "rail_y", "rail_x", {0, 1, 0})
enableAxisGroup(group)

-- extq 顺序：rail_x, rail_y
moveJointWithAxisGroup(q_target, 0.8, 0.8, 0, 0, group, {0.3, 0.1})

注意：

1. 不要在运动过程中修改轴组成员、父子关系或方向；需要修改时先停止运动，再重新配置并启用轴组。
2. axisGroupAddAxis() 中的 parent 表示该轴挂接到哪个父对象。单导轨通常挂到轴组本身，多导轨按串联关系挂到上一根轴。
3. axis_dir 只表达运动正方向，不表达行程、速度、加速度；这些参数仍在外部轴参数页或轴接口配置中设置。

4.6 点动验证

进入“移动”页面，选择目标联动/轴组，再切换到“外部轴”页签。

确认目标外部轴显示正常后，先用低速、小步长点动，观察位置值和实际运动方向。

基础模式可长按左右移动按钮连续运动；步进模式先设置步长，再点击左右移动按钮做间断移动。

5 单直线导轨联动使用

5.1 Demo 运行关系

single_rail_y_two_lines.lua 是单直线导轨联动 demo。脚本中的目标点变量需要由示教器程序提供，变量功能如下：

每个目标点支持两种写法：

-- 写法 1：前 6 个为机器人关节角 deg，第 7 个为外部轴位置 mm。
pose_2 = {0, -30, 90, 20, 90, 0, 120}

-- 写法 2：关节角和外部轴位置分开写。
pose_2 = {
    joint = {0, -30, 90, 20, 90, 0},
    axis_mm = 120
}

脚本内部会把机器人关节角从 deg 转为 rad，并把外部轴位置从 mm 转为 m：

local function joint_deg_to_rad(joint)
    local q = {}
    for i = 1, 6 do
        q[i] = math.rad(joint[i])
    end
    return q
end

local function mm_to_m(x)
    return x / 1000.0
end

5.2 轴组配置代码

脚本默认会重新配置单外部轴轴组：

local group = "轴组_1"
local configure_axis_group = true

if configure_axis_group then
    local fake_axis1 = app.api:getAxisInterface("fake_axis1")
    fake_axis1:setExtAxisType(1)
    fake_axis1:setExtAxisMaxPositionLimit(500)
    fake_axis1:setExtMinPositionLimit(-500)
    fake_axis1:setExtAxisMaxVelocityLimit(1000)
    fake_axis1:setExtAxisMaxAccelerationLimit(1000)
    fake_axis1:setReductionRatio(1)

    axisGroupDelete(group)
    axisGroupAdd(group, {0, 0, 0}, "base")
    axisGroupAddAxis(group, "fake_axis1", group, {0, 1, 0})
    enableAxisGroup(group)
end

现场使用真实外部轴时，至少确认下面三处：

1. "fake_axis1" 改为实际外部轴名称。
2. {0, 1, 0} 改为实际导轨在 Base 坐标系下的正方向单位向量。
3. 行程、速度、加速度和减速比按真实设备填写。

5.3 联动直线运动

脚本先用机器人关节位置和外部轴位置计算目标 TCP 位姿：

local pose2_tcp = target_pose("pose_2", pose2)

target_pose() 内部调用：

forwardKinematicsWithAxisGroup(target.joint, target.axis_q)

然后启动摆弧，并执行机器人和导轨同步直线运动：

weaveStart(DEFAULT_WEAVE_PARAMS)
moveLineWithAxisGroup(pose2_tcp, line_a, line_v, 0, 0, group, pose2.axis_q)
weaveEnd()

这里 pose2.axis_q 是外部轴目标位置表。单直线导轨只有 1 个外部轴，因此格式为：

{0.120} -- 单位 m，表示导轨目标位置 120 mm

脚本中的起始点、过渡点和返回点使用 moveJointWithAxisGroup，用于让机器人关节和导轨一起到达目标位置：

moveJointWithAxisGroup(origin.joint, joint_a, joint_v, 0, 0, group,
                       origin.axis_q)

Demo 效果如下。摆焊 GIF、高清视频和脚本为同一套资料：

高清视频可查看：单直线导轨摆焊 demo 视频。

6 轴组联动运动接口参数说明

6.1 moveJointWithAxisGroup

Lua 调用格式：

moveJointWithAxisGroup(q, a, v, blend_radius, duration, group_name, extq)

接口含义：执行机器人关节运动，同时让启用轴组中的外部轴同步运动到目标位置。该接口适合用于起始点、过渡点、退回点和返回点；它不保证 TCP 走直线。

常用写法：

-- 单直线导轨：机器人到 q_target，导轨到 120 mm。
moveJointWithAxisGroup(q_target, 0.8, 0.8, 0, 0, "轴组_1", {0.120})

6.2 moveLineWithAxisGroup

Lua 调用格式：

moveLineWithAxisGroup(pose, a, v, blend_radius, duration, group_name, extq)

接口含义：执行机器人 TCP 直线运动，同时让启用轴组中的外部轴参与同步运动。

常用写法：

-- 单直线导轨，明确指定导轨终点。
moveLineWithAxisGroup(target_pose, 0.5, 0.3, 0, 0, "轴组_1", {0.120})

-- 若版本支持外部轴终点不约束，可传空表，由算法协同求解导轨位置。
moveLineWithAxisGroup(target_pose, 0.5, 0.3, 0, 0, "轴组_1", {})

6.3 使用区别与注意事项

使用时注意：

1. group_name 不负责临时切换写权，调用前应确认轴组已正确启用。
2. extq 的维度必须与轴组中的外部轴数量一致；传空表只用于“外部轴终点不约束”的联动规划场景。
3. 直线导轨的外部轴位置单位是 m，界面和示教记录常用 mm 时必须转换。
4. 首次运行前先用低速和小行程验证方向、软限位和急停。

7 多直线导轨使用方式占位

多直线导轨完整示教流程暂不展开，先保留接口规则：

1. 轴组中可按顺序加入多根直线导轨。
2. axisGroupAddAxis() 的最后一个参数填写每根导轨在 Base 坐标系下的正方向单位向量。
3. moveLineWithAxisGroup() 的 extq 顺序与轴组添加顺序一致。
4. 2 根导轨时，extq 示例为 {rail1_m, rail2_m}；3 根导轨时，示例为 {rail1_m, rail2_m, rail3_m}。

占位示例：

local group = "rail2"

axisGroupDelete(group)
axisGroupAdd(group, {0, 0, 0}, "base")
axisGroupAddAxis(group, "rail_x", group, {1, 0, 0})
axisGroupAddAxis(group, "rail_y", "rail_x", {0, 1, 0})
enableAxisGroup(group)

-- 两根直线导轨：rail_x 目标 0.3 m，rail_y 目标 0.1 m。
moveLineWithAxisGroup(target_pose, 0.5, 0.3, 0, 0, group, {0.3, 0.1})

多自由度导轨摆焊 demo 效果如下，当前仅作为效果展示：

配套脚本：multi_rail_yxz_two_lines.lua。

该脚本配置 3 根直线导轨，轴组顺序为 fake_axis1、fake_axis2、fake_axis3，方向分别对应 Base 坐标系的 Z、Y、X：

axisGroupAddAxis(group, "fake_axis1", group, {0, 0, 1})
axisGroupAddAxis(group, "fake_axis2", "fake_axis1", {0, 1, 0})
axisGroupAddAxis(group, "fake_axis3", "fake_axis2", {1, 0, 0})

示教变量按 Base 坐标系的 X/Y/Z 外部轴位置填写，单位为 mm；脚本内部会转换成轴组顺序 {Z, Y, X}，并统一转为 m 后传入 moveJointWithAxisGroup() 和 moveLineWithAxisGroup()。

高清视频可查看：多自由度导轨摆焊 demo 视频。

后续补齐多直线导轨实机资料时，需要追加：多导轨标定流程、轴组父子关系规范、各轴软限位配置、extq 空表策略、暂停恢复和停止后的回归验证。

8 常见问题

8.1 aubo_control 无法启动

优先检查 ecat_master.conf 中未注释的 nic_number 是否与外部轴 EtherCAT 接线网口一致。若网口名为 enpXs0，则 nic_number = X。

8.2 外部轴方向反了

按顺序检查：

1. 线坐标系第一点和第二点是否反了。
2. axisGroupAddAxis() 的方向向量是否反了。
3. 传动比或方向参数是否填反。

8.3 齿轮齿条“每米跳数”不会算

先统一单位，再按下面公式计算：

S = pi * m * z / i

其中 m 为齿轮模数，z 为齿数，i 为总减速比。若 m 使用 mm，先除以 1000。

8.4 外部轴编码器报警

资料中的处理方式如下，现场需结合驱动器手册确认：

1. H02.31 设置为 1 后重新上电。新款小地轨驱动器可能不需要此步。
2. H02.01 设置为 1，进入绝对值模式，且必须插电池盒，然后重新上电。
3. H0D.20 设置为 1，执行绝对值报警复位，然后重新上电。

若报警闪烁，先按一下 SET 键确认，再按 MOD 键进入参数页面。

9 结论

单直线导轨的关键链路是：控制柜配置外部轴硬件和 EtherCAT 网口编号，ARCS 界面添加导轨并加入轴组，移动页完成低速点动验证，再用 moveJointWithAxisGroup(q, a, v, blend_radius, duration, group_name, extq) 做关节空间过渡，用 moveLineWithAxisGroup(pose, a, v, blend_radius, duration, group_name, extq) 执行机器人与导轨同步直线运动。

真正容易出错的点只有三个：网口编号、导轨正方向、extq 单位和顺序。首次联调时先小速度、小步长、小行程验证，通过后再运行完整 demo。