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

版本号：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. 接口总览（快速索引）

5. 详细接口与参数说明

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

5.1 末端力清零（zeroTcpForce）

接口定义

ret = zeroTcpForce(time)

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

参数表

返回值

调用约束

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

5.2 力偏置恢复（restoreTcpForce）

接口定义

ret = restoreTcpForce()

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

参数表

无参数。

返回值

备注

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

5.3 柔顺抓取（fcGraspComp）

接口定义

ret = fcGraspComp(params)

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

参数表

返回值

示例

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）

接口定义

ret = fcWaitGraspCompFinish(timeout)

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

参数表

返回值

5.5 接触（fcContact）

接口定义

ret = fcContact(params)

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

参数表

返回值

示例

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）

接口定义

ret = fcSearchHole(params)

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

参数表

返回值

示例

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）

接口定义

inside = fcCheckInHole(params)

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

参数表

返回值

示例

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）

接口定义

ret = fcInsertComp(params)

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

参数表

返回值

示例

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）

接口定义

ret = fcAlign(params)

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

参数表

返回值

示例

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. 错误码与接口对应关系示例

异常处理建议

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

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

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

8. 安全与前置条件

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

9. 版本变更记录

附录：常用参数建议表