88 Force-Controlled Assembly Interface Documentation (Including Parameter Descriptions)

Version: V1.0.0
Document status: Official release
Scope: Lua interface description for force-controlled assembly functions
Authoring department: R&D Systems Engineering Department
Release date: 2025-11-20

1. Document Overview

This interface document helps developers understand the force-controlled assembly interface definitions. It covers advanced functions including zeroing, contact detection, hole searching, alignment, in-hole checking, and compliant insertion and defines unified error codes.

2. Data Format Conventions

• Angle unit: ° (degree)
• Distance unit: m (meter)
• Speed unit: m/s
• Force unit: N (newton)
• Force/torque vector format: {Fx,Fy,Fz,Mx,My,Mz} (tool coordinate system or specified coordinate system)

-- Trajectory type
GuideTrajType = {
    NONE = 0, -- No reference trajectory
    LINE1 = 1, -- Straight line speedLine
    LINE2 = 2, -- Straight line moveLine
    SPIRAL = 3, -- Spiral
    WEAVE = 4 -- Weave
}

-- Insertion direction
InsertSelect = {
    x = 1,
    y = 2,
    z = 3
}

-- Hole-search plane
SearchPlane = {
    xy = 1,
    xz = 2,
    yz = 3
}

-- Spiral plane
SpiralPlane = {
    xy = 1,
    yz = 2,
    zx = 3
}

-- Weave direction
WeaveSelect = {
    x = 1,
    y = 2,
    z = 3,
    rx = 4,
    ry = 5,
    rz = 6
}

---

3. Error Code Definitions

FcErrorCode = {
    AUBO_OK = 0,

    -- General errors (-1 to -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,


    -- Force-control module errors (-100 to -199)
    FORCE_EXCEEDED          = -101,
    FORCE_CONTROL_INIT_FAIL = -102,
    FORCE_CONTROL_RUNTIME_ERR = -103,
    FORCE_ZERO_FAILED       = -104,
    FORCE_RESTORE_FAILED    = -105,

    -- Contact module errors (-200 to -249)
    CONTACT_DISTANCE_EXCEEDED  = -201,

    -- Hole-search module errors (-250 to -299)
    SEARCH_FORCE_EXCEEDED  = -251,
    SEARCH_RANGE_EXCEEDED          = -252,
    ENGAGEMENT_FAILED      = -254,

    -- In-hole check errors (-300 to -349)
    CHECK_NOT_IN_HOLE      = -301,
    CHECK_RANGE_EXCEEDED   = -302,

    -- Insertion module errors (-350 to -399)
    INSERT_FORCE_EXCEEDED  = -351,
    INSERT_DEPTH_EXCEEDED  = -352,

    -- Alignment module errors (-400 to -449)
    ALIGN_ANGLE_EXCEEDED   = -401,
    ALIGN_FORCE_EXCEEDED   = -402,
    
    -- Compliant grasping module errors (-450 to -499)
    GRASPCOMP_DISTANCE_EXCEEDED  = -451,
}

• All successful return values are unified as FcErrorCode.AUBO_OK (0).
• All failed return values use the error-code ranges above.
• Interfaces that return a boolean value, such as in-hole checking, continue to return true/false.

---

4. Interface Overview (Quick Index)

Function category	Interface name	Brief description
Force sensor	zeroTcpForce / restoreTcpForce	Zero and restore force bias
Compliant grasping	fcGraspComp / fcWaitGraspCompFinish	Grasp an object at an uncertain position
Contact detection	fcContact	Contact detection based on force thresholds
Alignment	fcAlign	Compliant alignment motion
Hole searching	fcSearchHole	Search for a hole on a plane, including an engagement trajectory
In-hole check	fcCheckInHole	Determine whether the tool has entered a hole
Compliant insertion	fcInsertComp	Insertion with force-control constraints

---

5. Detailed Interface and Parameter Descriptions

Description format: interface definition → function description → parameter table (Required: mandatory/Optional: optional) → return value → notes/example

---

5.1 Zero End-Effector Force (zeroTcpForce)

Interface definition

ret = zeroTcpForce(time)

Function description
Applies mean filtering to the six-dimensional end-effector force sensor over the specified time window and sets the result as the bias to zero the force.

Parameter table

Parameter	Type	Required	Unit	Description	Example
time	number	Yes	s	Sampling duration and averaging window; >= 0.5s is recommended	1.0

Return value

Return value	Meaning
AUBO_OK(0)	Zeroing succeeded
FORCE_ZERO_FAILED(-104)	Zeroing failed (communication error/sensor error/invalid parameter)

Invocation constraints

• Execute while stationary, with no external force on the end effector, to avoid errors caused by zeroing during motion.
• The robot should not contact the external environment during zeroing.

---

5.2 Restore Force Bias (restoreTcpForce)

Interface definition

ret = restoreTcpForce()

Function description
Restores the original bias parameters saved before zeroing.

Parameter table

No parameters.

Return value

Return value	Meaning
AUBO_OK(0)	Restoration succeeded
FORCE_RESTORE_FAILED(-105)	Restoration failed (no data)

Notes

• Usually use this interface together with the end-effector force zeroing interface after a force-control operation ends.

---

5.3 Compliant Grasping (fcGraspComp)

Interface definition

ret = fcGraspComp(params)

Function description
Grasps a workpiece whose position is uncertain and determines whether grasping succeeded based on the force threshold along the compliant axes.

Parameter table

Parameter	Type	Required	Unit	Value/range	Description	Example
feature	table[6]	Optional	—	—	Defines the grasp coordinate system (base/tool/user); format {x,y,z,rx,ry,rz}. Generally, {0,0,0,0,0,0} represents the base coordinate system. Use getTcpPose() to obtain the current pose to represent the tool coordinate system.	{0,0,0,0,0,0}
soft_axis	table[6]	Yes	—	Each item is 0/1	Specifies one or more compliant axes (indices in the feature coordinate system); for example, {1,0,0,0,0,0} specifies X	{1,1,0,0,0,0}
soft_force_threshold	table[6]	Yes	N	>=0	Force threshold on each compliant axis; grasping is considered successful when the force on the axis is below this threshold	{2,2,0,0,0,0}
speed_limit	number	Optional	m/s	>0	Maximum speed of the TCP along the compliant axes	0.1
max_distance_limit	number	Yes	m	>0	Maximum permitted displacement along the compliant axes	0.05
grasp_timeout	number	Optional	s	>0	Operation timeout	5.0

Return value

Return value	Meaning
AUBO_OK(0)	Successfully entered compliant grasping mode
AUBO_INVL_ARGUMENT(-5)	Invalid parameter or initialization failure

Example

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 Wait for Compliant Grasping to Finish (fcWaitGraspCompFinish)

Interface definition

ret = fcWaitGraspCompFinish(timeout)

Function description
Waits for the completion event triggered by fcGraspComp within the specified time. It is generally used together with fcGraspComp.

Parameter table

Parameter	Type	Required	Unit	Description	Example
timeout	number	Yes	s	Maximum waiting time	5

Return value

Return value	Meaning
AUBO_OK(0)	Grasping action completed
AUBO_TIMEOUT(-4)	The action did not complete before the timeout
GRASPCOMP_DISTANCE_EXCEEDED(-451)	Maximum distance limit exceeded

---

5.5 Contact (fcContact)

Interface definition

ret = fcContact(params)

Function description
Performs contact detection along the contact axis and stops immediately when the contact condition is triggered.

Parameter table

Parameter	Type	Required	Unit	Value/range	Description
feature	table[6]	Optional	—	—	Defines the contact coordinate system; format {x,y,z,rx,ry,rz}
compliance	table[6]	Yes	—	Whether each axis participates in force control (0/1)	Force-control direction; for example, {0,0,1,0,0,0} specifies only the Z axis
wrench	table[6]	Yes	N / Nm	Target force/torque threshold	Contact is considered detected when the measured force reaches this threshold; for example, {0,0,10,0,0,0}
env_stiff	table[6]	Optional	—	[0.0~1.0]	Estimated environment stiffness for the force-control algorithm
damp_scale	table[6]	Optional	—	[0.1~1.0]	Damping ratio
stiff_scale	table[6]	Optional	—	[0.0~1.0]	Stiffness ratio
speed_limits	number	Optional	m/s	>0	Speed limit along the contact direction
distance	number	Optional	m	>0	Maximum displacement limit; exceeding it returns an over-distance error
timeout	number	Yes	s	>0	Operation timeout

Return value

Return value	Meaning
AUBO_OK(0)	Contact condition reached successfully
CONTACT_DISTANCE_EXCEEDED(-201)	Maximum permitted displacement (distance) exceeded
AUBO_TIMEOUT(-4)	No contact detected before the timeout (timeout)

Example

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 Hole Searching (fcSearchHole)

Interface definition

ret = fcSearchHole(params)

Function description Performs a search trajectory on the specified plane to locate a shaft hole.

Parameter table

Parameter	Type	Required	Unit	Value/range	Description
search_plane	SearchPlane	Optional	—	xy(1)/xz(2)/yz(3)	Search plane; the default is the xy plane of the TCP coordinate system
search_range	number	Yes	m	>0	Search radius or range
search_time	number	Yes	s	>0	Maximum total search duration
guide_traj_type	GuideTrajType	Optional	—	SPIRAL/MESHING/WEAVE	Active guidance trajectory type
search_max_force	number	Optional	N	>5	Maximum force permitted during searching
search_guide_force	number	Optional	N	—	Guidance force in the search direction
speed_scale	number	Optional	—	[0.1~5]	Global speed ratio
search_damp_scale	table[6]	Optional	—	[0.1~1]	Damping adjustment
search_stiff_scale	table[6]	Optional	—	[0.1~1]	Stiffness adjustment
push_distance	number	Optional	m	>0	Advancing distance

Return value

Return value	Meaning
AUBO_OK(0)	Hole search succeeded
SEARCH_FORCE_EXCEEDED(-251)	Force exceeded the limit; force during searching exceeded search_max_force
AUBO_TIMEOUT(-4)	Hole search timed out (search_time)
SEARCH_RANGE_EXCEEDED(-252)	Search range exceeded

Example

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 In-Hole Check (fcCheckInHole)

Interface definition

inside = fcCheckInHole(params)

Function description Performs compliant detection along the specified detection axis to determine whether the workpiece has entered the hole. The return value is a Boolean indicating the detection result.

Parameter table

Parameter	Type	Required	Unit	Description
check_axis	table[3]	Yes	—	Detection-axis vector in the tool coordinate system, for example {1,0,0}; up to two directions are supported
check_range	number	Yes	m	Detection displacement range
check_force	number	Yes	N	Force threshold along the search axis; exceeding it indicates that the tool is in the hole
check_speed	number	Yes	m/s	Search speed (TCP)

Return value

Return value	Meaning
true	The tool has entered the hole
false	The tool has not entered the hole (range exceeded or force threshold not reached)

Example

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 Compliant Insertion (fcInsertComp)

Interface definition

ret = fcInsertComp(params)

Function description Executes an insertion action with compliant constraints. It supports different guidance trajectories (spiral/weave/straight line) and exits when the target depth is reached or a fault occurs.

Parameter table

Parameter	Type	Required	Unit	Description
insert_select	InsertSelect	Optional	—	Insertion direction relative to the tool coordinate system: x(1)/y(2)/z(3) (z by default)
insert_max_speed	number	Optional	m/s	Insertion speed limit
insert_time	number	Optional	s	Operation timeout
guide_traj_type	GuideTrajType	Optional	—	SPIRAL/WEAVE/LINE
insert_max_force	number	Optional	N	Maximum permitted force during insertion
insert_max_depth	number	Optional	m	Maximum insertion depth
insert_guide_force	number	Optional	N	Guidance force
speed_scale	number	Optional	—	Speed ratio [0.1~5]
insert_damp_scale	table[6]	Optional	—	Damping ratio [0.1~1]
insert_stiff_scale	table[6]	Optional	—	Stiffness ratio [0.0~1]

Return value

Return value	Meaning
AUBO_OK(0)	Insertion succeeded (depth reached or completion determined)
INSERT_FORCE_EXCEEDED(-351)	Force exceeded the limit (insert_max_force)
AUBO_TIMEOUT(-4)	Timed out or condition was not reached

Example

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 Alignment (fcAlign)

Interface definition

ret = fcAlign(params)

Function description Uses compliant motion to adjust the position and orientation so that the object being aligned achieves high-precision alignment with the contact surface.

Parameter table

Parameter	Type	Required	Unit	Description
align_axis	table[6]	Yes	—	Compliant axes. The tool coordinate system can include position and angular-axis flags; for example, {0,0,0,1,1,0} specifies adjustment around RX/RY
contact_axis	table[3]	Yes	—	Contact axis (main axis of the tool coordinate system), for example, {0,0,1}
contact_force	number	Yes	N	Target force on the contact axis for maintaining contact
align_speed	number	Optional	deg/s	Maximum angular speed during alignment
max_limit_force	number	Optional	N	Maximum permitted force during alignment
max_align_angle	number	Optional	deg	Maximum permitted alignment-angle offset
judgment_level	number	Optional	—	Judgment level [0.1~1.0] (a higher level is stricter)

Return value

Return value	Meaning
AUBO_OK(0)	Alignment succeeded
ALIGN_ANGLE_EXCEEDED(-401)	Alignment angle exceeded the maximum range
ALIGN_FORCE_EXCEEDED(-402)	Force exceeded the maximum limit

Example

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. Examples of Error Codes Corresponding to Interfaces

Interface	Possible error codes	Description
zeroTcpForce	FORCE_ZERO_FAILED	Zeroing failed
fcContact	CONTACT_DISTANCE_EXCEEDED / AUBO_TIMEOUT	Over-distance / timeout without contact
fcSearchHole	SEARCH_FORCE_EXCEEDED / AUBO_TIMEOUT	Hole search failed
fcInsertComp	INSERT_FORCE_EXCEEDED / AUBO_TIMEOUT	Insertion failed
fcAlign	ALIGN_ANGLE_EXCEEDED / ALIGN_FORCE_EXCEEDED	Alignment failed

---

Error-handling recommendations

1. Check parameter validity (type and range) before every call.
2. When a force limit is exceeded or an abnormal return value occurs, immediately perform a safe stop/emergency stop or switch to a safe trajectory.
3. For operations that may cause a collision, such as fcContact and fcInsertComp, perform a low-speed trial run first and record logs.

---

7. Usage Example (Typical Flow)

1. Before startup: zeroTcpForce(1.0) (zero while stationary).
2. Perform contact/alignment: call fcContact → fcAlign.
3. Search for and insert into a hole: fcSearchHole → if successful, call fcCheckInHole → fcInsertComp.
4. Grasp: fcGraspComp → fcWaitGraspCompFinish(timeout).
5. End force control: restoreTcpForce.
6. If an exception occurs: perform safety handling (stop or restore) based on the return code.

---

8. Safety and Prerequisites

• Force-control interfaces require the robot's force-control module to be enabled and operating normally.
• Zeroing should be performed with no external contact and while the end effector is stationary.
• Validate parameters through simulation or at low speed before performing insertion, hole searching, or similar operations.

---

9. Version Change History

Version	Date	Changes
V1.0.0	2025-11-20	Initial release (including interface overview)

---

Appendix: Recommended Values for Common Parameters

Parameter	Recommended initial value	Description
soft_force_threshold	1~5 N	Force threshold during grasping; depends on the fixture/workpiece
search_max_force	10~20 N	Permitted peak force during hole searching
contact_force	5~15 N	Target force for contact testing
speed_scale	0.5~1.5	Global speed ratio (avoid impacts caused by excessive speed)

---