协作机械臂力控装配接口文档（含参数说明）

版本号：V1.0.0
文档状态：正式版
适用范围：力控装配功能 Lua 接口说明
编写部门：研发系统工程部
发布日期：2025-11-20

1. 文档概述

本接口文档用于指导开发者了解力控装配接口定义，包括清零、接触、搜孔、对齐、入孔检测、柔性插拔等高级功能，并定义统一的错误码。

2. 数据格式约定

角度单位：°（degree）
距离单位：m（米）
速度单位：m/s
力单位：N（牛顿）
力/力矩向量格式：{Fx,Fy,Fz,Mx,My,Mz}（工具坐标系或指定坐标系）

lua


-- 轨迹类型
GuideTrajType = {
    NONE = 0, -- 无参考轨迹
    LINE1 = 1, -- 直线 speedLine
    LINE2 = 2, -- 直线 moveLine
    SPIRAL = 3, -- 螺旋线
    WEAVE = 4 -- 摆线
}

-- 插入方向
InsertSelect = {
    x = 1,
    y = 2,
    z = 3
}

-- 搜孔平面
SearchPlane = {
    xy = 1,
    xz = 2,
    yz = 3
}

-- 螺旋线平面
SpiralPlane = {
    xy = 1,
    yz = 2,
    zx = 3
}

-- 摆线方向
WeaveSelect = {
    x = 1,
    y = 2,
    z = 3,
    rx = 4,
    ry = 5,
    rz = 6
}

3.错误码定义

lua

FcErrorCode = {
    AUBO_OK = 0,

    -- 通用错误（-1 ~ -99）
    AUBO_BAD_STATE              = -1,
    AUBO_QUEUE_FULL             = -2,
    AUBO_BUSY                   = -3,
    AUBO_TIMEOUT                = -4,
    AUBO_INVL_ARGUMENT          = -5,
    AUBO_NOT_IMPLETEMENT        = -6,
    AUBO_NO_ACCESS              = -7,
    AUBO_CONN_REFUSED           = -8,
    AUBO_CONN_RESET             = -9,
    AUBO_INPROGRESS             = -10,
    AUBO_EIO                    = -11,
    AUBO_NOBUFFS                = -12,
    AUBO_REQUEST_IGNORE         = -13,
    AUBO_ALGORITHM_PLAN_FAILED  = -14,
    AUBO_VERSION_INCOMPAT       = -15,
    AUBO_DIMENSION_ERR          = -16,
    AUBO_SINGULAR_ERR           = -17,
    AUBO_POS_BOUND_ERR          = -18,
    AUBO_INIT_POS_ERR           = -19,
    AUBO_ELP_SETTING_ERR        = -20,


    -- 力控模块错误（-100 ~ -199）
    FORCE_EXCEEDED          = -101,
    FORCE_CONTROL_INIT_FAIL = -102,
    FORCE_CONTROL_RUNTIME_ERR = -103,
    FORCE_ZERO_FAILED       = -104,
    FORCE_RESTORE_FAILED    = -105,

    -- 接触模块错误（-200 ~ -249）
    CONTACT_DISTANCE_EXCEEDED  = -201,

    -- 搜孔模块错误（-250 ~ -299）
    SEARCH_FORCE_EXCEEDED  = -251,
    SEARCH_RANGE_EXCEEDED          = -252,
    ENGAGEMENT_FAILED      = -254,

    -- 入孔检查（-300 ~ -349）
    CHECK_NOT_IN_HOLE      = -301,
    CHECK_RANGE_EXCEEDED   = -302,

    -- 插入模块错误（-350 ~ -399）
    INSERT_FORCE_EXCEEDED  = -351,
    INSERT_DEPTH_EXCEEDED  = -352,

    -- 对齐模块错误（-400 ~ -449）
    ALIGN_ANGLE_EXCEEDED   = -401,
    ALIGN_FORCE_EXCEEDED   = -402,
    
    -- 柔顺抓取模块错误（-450 ~ -499）
    GRASPCOMP_DISTANCE_EXCEEDED  = -451,
}

所有成功返回值统一为：FcErrorCode.AUBO_OK (0)
所有失败返回值将使用上述错误码范围
boolean 返回的接口（如入孔检查）将保持 true/false

4. 接口总览（快速索引）

功能分类	接口名称	简要描述
力传感器	`zeroTcpForce` / `restoreTcpForce`	力偏置清零、恢复
柔顺抓取	`fcGraspComp` / `fcWaitGraspCompFinish`	抓取不确定位置物体
接触检测	`fcContact`	基于力阈值的接触探测
对齐	`fcAlign`	柔顺对齐运动
搜孔	`fcSearchHole`	在平面内进行孔位搜索（含啮合轨迹）
入孔检查	`fcCheckInHole`	判断是否进入孔内
柔性插入	`fcInsertComp`	具有力控约束的插入动作

5. 详细接口与参数说明

说明格式：接口定义 → 功能说明 → 参数表（Required: 必填/Optional: 可选） → 返回值 → 备注/示例

5.1 末端力清零（zeroTcpForce）

接口定义

lua

ret = zeroTcpForce(time)

功能说明
对末端六维力传感器在指定时间窗口内进行均值滤波，并将结果设为偏置，实现力清零。

参数表

参数名	类型	Required	单位	说明	示例
`time`	number	Yes	s	采样时长，取平均用时窗口；建议 >= 0.5s	`1.0`

返回值

返回值	含义
`AUBO_OK(0)`	清零成功
`FORCE_ZERO_FAILED(-104)`	清零失败（通信异常/传感器异常/参数非法）

调用约束

在静止（末端无外力扰动）条件下执行，避免运动期间清零导致误差。
在清零期间建议机器人不接触外界。

5.2 力偏置恢复（restoreTcpForce）

接口定义

lua

ret = restoreTcpForce()

功能说明
恢复清零前存储的原始偏置参数。

参数表

无参数。

返回值

返回值	含义
`AUBO_OK(0)`	恢复成功
`FORCE_RESTORE_FAILED(-105)`	恢复失败（无数据）

备注

通常搭配末端力清零接口,在结束力控动作后使用。

5.3 柔顺抓取（fcGraspComp）

接口定义

lua

ret = fcGraspComp(params)

功能说明
用于抓取位置存在不确定性的工件，通过柔顺轴方向的力阈判断抓取成功。

参数表

参数名	类型	Required	单位	取值/范围	说明	示例
`feature`	table[6]	Optional	—	—	抓取坐标系定义（基座/工具/用户）；格式 `{x,y,z,rx,ry,rz}`，一般 `{0,0,0,0,0,0}` 表示基坐标，通过`getTcpPose()`获取当前 pose 表示工具坐标系	`{0,0,0,0,0,0}`
`soft_axis`	table[6]	Yes	—	每项 0/1	指定一个或多个柔顺轴（在 feature 坐标系下的索引）；例如 `{1,0,0,0,0,0}` 表示沿 X	`{1,1,0,0,0,0}`
`soft_force_threshold`	table[6]	Yes	N	>=0	各柔顺轴上的力阈值；当轴上受力小于该阈值时判定抓取成功	`{2,2,0,0,0,0}`
`speed_limit`	number	Optional	m/s	>0	柔顺轴方向最大速度（TCP）	`0.1`
`max_distance_limit`	number	Yes	m	>0	柔顺轴允许最大位移	`0.05`
`grasp_timeout`	number	Optional	s	>0	操作超时	`5.0`

返回值

返回值	含义
`AUBO_OK(0)`	成功进入柔顺抓取模式
`AUBO_INVL_ARGUMENT(-5)`	参数错误或初始化失败

示例

lua

local fc = require('aubo.force_control')
params = {
  feature = {0,0,0,0,0,0},
  soft_axis = {1,0,0,0,0,0},
  soft_force_threshold = {2,2,0,0,0,0},
  speed_limit = 0.05,
  max_distance_limit = 0.02,
  grasp_timeout = 3.0
}
ret = fc.fcGraspComp(params)

5.4 等待柔顺抓取完成（fcWaitGraspCompFinish）

接口定义

lua

ret = fcWaitGraspCompFinish(timeout)

功能说明
在规定时间内等待 fcGraspComp 触发完成事件。通常与 fcGraspComp 成对使用。

参数表

参数名	类型	Required	单位	说明	示例
`timeout`	number	Yes	s	最大等待时间	`5`

返回值

返回值	含义
`AUBO_OK(0)`	抓取动作已完成
`AUBO_TIMEOUT(-4)`	超时未完成
`GRASPCOMP_DISTANCE_EXCEEDED(-451)`	超出最大距离限制

5.5 接触（fcContact）

接口定义

lua

ret = fcContact(params)

功能说明
机械臂沿接触轴方向进行接触探测，触发接触条件后立即停止。

参数表

参数名	类型	Required	单位	取值/范围	说明
`feature`	table[6]	Optional	—	—	接触坐标系定义，格式 `{x,y,z,rx,ry,rz}`
`compliance`	table[6]	Yes	—	各轴是否参与力控（0/1）	力控方向，例如 `{0,0,1,0,0,0}` 表示仅 Z 轴
`wrench`	table[6]	Yes	N / Nm	目标力/力矩阈值	当检测力达到该阈值视为接触，例如 `{0,0,10,0,0,0}`
`env_stiff`	table[6]	Optional	—	[0.0~1.0]	环境刚度估计，用于力控制算法
`damp_scale`	table[6]	Optional	—	[0.1~1.0]	阻尼比例
`stiff_scale`	table[6]	Optional	—	[0.0~1.0]	刚度比例
`speed_limits`	number	Optional	m/s	>0	接触方向上的速度限制
`distance`	number	Optional	m	>0	最大位移限制（超过则返回超距）
`timeout`	number	Yes	s	>0	操作超时

返回值

返回值	含义
`AUBO_OK(0)`	成功达到接触条件
`CONTACT_DISTANCE_EXCEEDED(-201)`	超出最大允许位移（distance）
`AUBO_TIMEOUT(-4)`	超时未接触（timeout）

示例

lua

local fc = require('aubo.force_control')
params = {
  feature = {0,0,0,0,0,0},
  compliance = {0,0,1,0,0,0},
  wrench = {0,0,10,0,0,0},
  env_stiff = {0,0,0.8,0,0,0},
  damp_scale = {0.5,0.5,0.5,0.5,0.5,0.5},
  stiff_scale = {0.5,0.5,0.5,0.5,0.5,0.5},
  speed_limits = 0.02,
  distance = 0.1,
  timeout = 8
}
ret = fc.fcContact(params)

5.6 搜孔（fcSearchHole）

接口定义

lua

ret = fcSearchHole(params)

功能说明 在指定平面上执行搜索轨迹进行轴孔探寻。

参数表

参数名	类型	Required	单位	取值/范围	说明
`search_plane`	SpiralPlane	Optional	—	xy(1)/xz(2)/yz(3)	搜索平面，默认 TCP 坐标系 xy 平面
`search_range`	number	Yes	m	>0	搜索半径或范围
`search_time`	number	Yes	s	>0	搜索总时长上限
`guide_traj_type`	GuideTrajType	Optional	—	SPIRA/MESHING/WEAVE	主动引导轨迹类型
`search_max_force`	number	Optional	N	>5	搜索过程允许的最大力
`search_guide_force`	number	Optional	N	—	搜索方向的引导力
`speed_scale`	number	Optional	—	[0.1~5]	全局速度比例
`search_damp_scale`	table[6]	Optional	—	[0.1~1]	阻尼调整
`search_stiff_scale`	table[6]	Optional	—	[0.1~1]	刚度调整
`push_distance`	number	Optional	m	>0	推进距离

返回值

返回值	含义
`AUBO_OK(0)`	搜孔成功
`SEARCH_FORCE_EXCEEDED(-251)`	力超限，搜索中受力超过 `search_max_force`
`AUBO_TIMEOUT(-4)`	搜孔超时（`search_time`）
`SEARCH_RANGE_EXCEEDED(-252)`	超出搜索范围

示例

lua

local fc = require('aubo.force_control')
params = {
  search_plane = SearchPlane.xy,
  search_range = 0.02,
  search_time = 15,
  guide_traj_type = GuideTrajType.WEAVE,
  search_max_force = 50,
  search_guide_force = 10,
  speed_scale = 1.0
}
ret = fc.fcSearchHole(params)

5.7 入孔检查（fcCheckInHole）

接口定义

lua

inside = fcCheckInHole(params)

功能说明 沿指定检测轴进行柔顺探测，判断工件是否进入孔内；返回布尔值表示检测结果。

参数表

参数名	类型	Required	单位	说明
`check_axis`	table[3]	Yes	—	检测轴向量（工具坐标系），例如 `{1,0,0}`；最多支持两个方向
`check_range`	number	Yes	m	检测位移范围
`check_force`	number	Yes	N	搜索轴方向上的受力阈值，超过视为在孔内
`check_speed`	number	Yes	m/s	搜索速度（TCP）

返回值

返回值	含义
`true`	已进入孔内
`false`	未进入孔（超出范围或未达到力阈）

示例

lua

local fc = require('aubo.force_control')
params = {
  check_axis = {1,0,0},
  check_range = 0.02,
  check_force = 5.0,
  check_speed = 0.01
}
inside = fc.fcCheckInHole(params)

5.8 柔性插拔（fcInsertComp）

接口定义

lua

ret = fcInsertComp(params)

功能说明 机器人按照柔性约束方式执行插入动作，支持不同引导轨迹（螺旋/摆动/直线），并在到达深度或遇到故障时退出。

参数表

参数名	类型	Required	单位	说明
`insert_select`	InsertSelect	Optional	—	插入方向，相对于工具坐标系： x(1)/y(2)/z(3)（默认 z）
`insert_max_speed`	number	Optional	m/s	插入速度上限
`insert_time`	number	Optional	s	操作超时
`guide_traj_type`	GuideTrajType	Optional	—	SPIRAL/WEAVE/LINE
`insert_max_force`	number	Optional	N	插入过程最大允许力
`insert_max_depth`	number	Optional	m	插入最大深度
`insert_guide_force`	number	Optional	N	引导力大小
`speed_scale`	number	Optional	—	速度比例 [0.1~5]
`insert_damp_scale`	table[6]	Optional	—	阻尼比例 [0.1~1]
`insert_stiff_scale`	table[6]	Optional	—	刚度比例 [0.0~1]

返回值

返回值	含义
`AUBO_OK(0)`	插入成功（达到深度或判定完成）
`INSERT_FORCE_EXCEEDED(-351)`	受力超限（`insert_max_force`）
`AUBO_TIMEOUT(-4)`	超时或未达到条件

示例

lua

local fc = require('aubo.force_control')
params = {
  insert_select = InsertSelect.z,
  insert_max_speed = 0.02,
  insert_time = 12,
  guide_traj_type = GuideTrajType.SPIRAL,
  insert_max_force = 20,
  insert_max_depth = 0.05,
  insert_guide_force = 2.0,
  speed_scale = 1.0
}
ret = fc.fcInsertComp(params)

5.9 对齐（fcAlign）

接口定义

lua

ret = fcAlign(params)

功能说明 通过柔顺运动调整位置与姿态，使被对齐物体与接触面实现高精度对齐。

参数表

参数名	类型	Required	单位	说明
`align_axis`	table[6]	Yes	—	柔顺轴，工具坐标系可包含位置与角度轴标志，例如 `{0,0,0,1,1,0}` 表示绕 RX/RY 调整
`contact_axis`	table[3]	Yes	—	接触轴（工具坐标系主轴），例如 `{0,0,1}`
`contact_force`	number	Yes	N	接触轴的目标力，用于维持接触
`align_speed`	number	Optional	deg/s	对齐过程中最大角速度
`max_limit_force`	number	Optional	N	对齐过程中最大允许受力
`max_align_angle`	number	Optional	deg	最大允许对齐角度偏移
`judgment_level`	number	Optional	—	判定等级 [0.1~1.0]（高等级更严格）

返回值

返回值	含义
`AUBO_OK(0)`	对齐成功
`ALIGN_ANGLE_EXCEEDED(-401)`	对齐角度超出最大范围
`ALIGN_FORCE_EXCEEDED(-402)`	力超出最大限制

示例

lua

local fc = require('aubo.force_control')
params = {
  align_axis = {0,0,0,1,1,0},
  contact_axis = {0,0,1},
  contact_force = 10,
  align_speed = 0.02,
  max_limit_force = 30,
  max_align_angle = 10,
  judgment_level = 0.8
}
ret = fc.fcAlign(params)

6. 错误码与接口对应关系示例

接口	可能返回错误码	说明
zeroTcpForce	FORCE_ZERO_FAILED / SENSOR_ERROR	清零失败
fcContact	CONTACT_NOT_DETECTED / CONTACT_DISTANCE_EXCEEDED	未接触 / 超距
fcSearchHole	SEARCH_FORCE_EXCEEDED / AUBO_TIMEOUT / SEARCH_FAILED	搜孔失败
fcInsertComp	INSERT_FORCE_EXCEEDED / AUBO_TIMEOUT / INSERT_FAILED	插入失败
fcAlign	ALIGN_ANGLE_EXCEEDED / ALIGN_FORCE_EXCEEDED	对齐失败

异常处理建议

所有调用前检查参数有效性（类型、范围）。
在出现力超限或异常返回时立即调用安全停机/急停或切换至安全轨迹。
对可能导致碰撞的操作（如 fcContact、fcInsertComp）先做低速试运行并记录日志。

7. 使用示例（典型流程）

启动前：zeroTcpForce(1.0)（静止情况下清零）
进行接触/对齐：调用 fcContact → fcAlign
搜孔并插入：fcSearchHole → 若成功调用 fcCheckInHole → fcInsertComp
抓取：fcGraspComp → fcWaitGraspCompFinish(timeout)
力控结束：restoreTcpForce
出现异常：根据返回码执行安全处理（停止或恢复）

8. 安全与前置条件

力控类接口要求机器人力控模块已启用且状态正常。
清零建议在无外界接触、末端静止的环境下进行。
插入/搜孔等操作建议先进行仿真或在低速下验证参数。

9. 版本变更记录

版本号	日期	修改内容
V1.0.0	2025-11-20	首版（含接口概述）

附录：常用参数建议表

参数	建议初始值	说明
`soft_force_threshold`	1~5 N	抓取时的力阈，视夹具/工件而定
`search_max_force`	10~20 N	搜孔时允许的峰值力
`contact_force`	5~15 N	接触测试时使用的目标力
`speed_scale`	0.5~1.5	全局速度比例（避免过快造成冲击）

协作机械臂力控装配接口文档（含参数说明） ​

1. 文档概述 ​

2. 数据格式约定 ​

3.错误码定义 ​

4. 接口总览（快速索引） ​

5. 详细接口与参数说明 ​

5.1 末端力清零（zeroTcpForce） ​

5.2 力偏置恢复（restoreTcpForce） ​

5.3 柔顺抓取（fcGraspComp） ​

5.4 等待柔顺抓取完成（fcWaitGraspCompFinish） ​

5.5 接触（fcContact） ​

5.6 搜孔（fcSearchHole） ​

5.7 入孔检查（fcCheckInHole） ​

5.8 柔性插拔（fcInsertComp） ​

5.9 对齐（fcAlign） ​

6. 错误码与接口对应关系示例 ​

7. 使用示例（典型流程） ​

8. 安全与前置条件 ​

9. 版本变更记录 ​

附录：常用参数建议表 ​

协作机械臂力控装配接口文档（含参数说明）

1. 文档概述

2. 数据格式约定

3.错误码定义

4. 接口总览（快速索引）

5. 详细接口与参数说明

5.1 末端力清零（zeroTcpForce）

5.2 力偏置恢复（restoreTcpForce）

5.3 柔顺抓取（fcGraspComp）

5.4 等待柔顺抓取完成（fcWaitGraspCompFinish）

5.5 接触（fcContact）

5.6 搜孔（fcSearchHole）

5.7 入孔检查（fcCheckInHole）

5.8 柔性插拔（fcInsertComp）

5.9 对齐（fcAlign）

6. 错误码与接口对应关系示例

7. 使用示例（典型流程）

8. 安全与前置条件

9. 版本变更记录

附录：常用参数建议表