Rehabilitation & Physiotherapy
Massage
Primitive Description and Usage
Description: This primitive uses hybrid motion/force control to move the robot TCP linearly between waypoints in motion control directions and to exert force in force control directions. Safety mechanisms such as maximum contact force and maximum velocity along force control directions can be configured to protect the human body from injury when the robot comes into contact with it.
Example Usage: Use this primitive to control the robot to perform a massage on the human body.
Primitive Input Parameters
Input Parameter |
Description |
Type |
Unit |
Default Value & Range |
|---|---|---|---|---|
target* |
Target TCP pose |
COORD |
m-deg |
[traj_start* world*] |
targetWrench* |
Force and torque applied on target TCP pose |
VEC_6d |
N |
0.0 0.0 -5.0 0.0 0.0 0.0 |
waypoint |
Waypoint pose |
ARRAY_COORD |
m-deg |
[traj_start* traj_goal* traj_prev* world*] |
wrench |
Force and torque applied on the waypoint in the force control coordinate system |
ARRAY_VEC_6d |
N |
|
vel |
TCP linear velocity |
DOUBLE |
m/s |
0.25 ∈ [0.001 … 2.2] |
acc |
TCP linear acceleration |
DOUBLE |
m/s^2 |
1.5 ∈ [0.1 … 3.0] |
zoneRadius |
Blending zone radius while TCP approximates the waypoints |
TYPE |
mm |
Z50 ∈ [ZFine Z1 Z5 Z10 Z15 Z20 Z30 Z40 Z50 Z60 Z80 Z100 Z150 Z200 ZSpline] |
targetTolerLevel |
Tolerance level to determine if the robot has reached the target. 1 means to check with the smallest tolerance, 0 means no tolerance check. |
INT |
none |
0 ∈ [0 … 10] |
forceCoord |
Reference coordinate system for force control direction |
COORD |
m-deg |
0 0 0 0 0 0 TCP ONLINE ∈ [world* tcp_start* tcp*] |
forceAxis* |
Activated axes of force control coordinate to apply force or torque |
VEC_6i |
none |
0 0 1 0 0 0 ∈ [0 0 0 0 0 0 … 1 1 1 1 1 1] |
jerk |
TCP linear jerk |
DOUBLE |
m/s^3 |
200.0 ∈ [50.0 … 500.0] |
angVel |
TCP angular velocity |
DOUBLE |
deg/s |
150.0 ∈ [10.0 … 500.0] |
enableFixRefJntPos |
Flag to indicate if fixed reference joint position is enabled. If this parameter is set to TRUE, the primitive will use the value of parameter [refJntPos] as the fixed joint reference position instead of the reference joint position of each waypoint during execution. |
BOOL |
none |
0 ∈ [0 / 1] |
refJntPos |
Reference target joint positions. When the robot moves in Cartesian space, each joint will move as close as possible toward the reference position. |
JPOS |
deg |
0.0 -40.0 0.0 90.0 0.0 40.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 |
configOptObj |
Weights of three configuration optimization objectives during robot motion, which respectively are to make the robot easier to translate in Cartesian space, easier to rotate in Cartesian space, and closer to the reference joint position. |
VEC_3d |
none |
0.0 0.0 0.5 ∈ [0.0 0.0 0.1 … 1.0 1.0 1.0] |
stiffScale |
Robot stiffness scale during motion. The lower the stiffness scale, the more compliant the motion. |
VEC_6d |
none |
1.0 1.0 1.0 1.0 1.0 1.0 ∈ [0.01 0.01 0.01 0.01 0.01 0.01 … 1.0 1.0 1.0 1.0 1.0 1.0] |
enableMaxWrench |
Flag to indicate if maximum contact wrench is enabled in each Cartesian direction: X, Y, Z, Rx, Ry, Rz |
VEC_6i |
none |
0 0 0 0 0 0 ∈ [0 0 0 0 0 0 … 1 1 1 1 1 1] |
maxContactWrench |
Maximum contact wrench allowed for static collision along Fx, Fy, Fz, Mx, My, Mz |
VEC_6d |
N |
150.0 150.0 150.0 40.0 40.0 40.0 ∈ [5.0 5.0 5.0 1.0 1.0 1.0 … 150.0 150.0 150.0 40.0 40.0 40.0] |
enableEntryPoint |
Use the first waypoint as the entry point. The robot moves from free space to the first waypoint along the force control axis, then executes the hybrid position/force controlling motion. |
BOOL |
none |
0 ∈ [0 / 1] |
maxWrenchPause |
The robot pauses when it reaches the maximum contact wrench and resumes executing subsequent trajectories after the maximum contact wrench is removed. |
BOOL |
none |
0 ∈ [0 / 1] |
motionForceDecouple |
Flag to indicate if motion control and force control are decoupled. When the tool is long and the friction is large, it is recommended to enable this parameter so that the tool can make more stable contact with the human body. |
BOOL |
none |
0 ∈ [0 / 1] |
maxVelForceDir |
Maximum movement velocity along force control direction |
VEC_3d |
m/s |
2.0 2.0 2.0 ∈ [0.005 0.005 0.005 … 2.0 2.0 2.0] |
wrenchFilterCutoff |
Cutoff frequency of command wrench filter. The lower this frequency, the smoother the change in command wrench. |
DOUBLE |
Hz |
1.0 ∈ [0.1 … 10.0] |
lineSpace |
Wavelength of the overlaid sine wave or helix wave trajectory |
DOUBLE |
m |
0.005 ∈ [0.005 … 1.0] |
amplitude |
Amplitude of the overlaid sine wave or helix wave trajectory |
DOUBLE |
m |
0.0 ∈ [-1.0 … 1.0] |
pitch |
Pitch of the helix wave trajectory |
DOUBLE |
m |
0.0 ∈ [-1.0 … 1.0] |
*Parameters marked with an asterisk must be assigned a value prior to executing the primitive.
*Coordinate System Definition
Coordinate |
Definition |
Value Format |
|---|---|---|
world |
WORLD coordinate system, which is a fixed Cartesian coordinate system located at the center of the robot base |
X Y Z Rx Ry Rz WORLD WORLD_ORIGIN |
work |
WORK coordinate system, which defines the position of the workpiece relative to the WORLD coordinate system |
X Y Z Rx Ry Rz WORK WorkCoordName |
tcp |
TCP coordinate system, which is located at the Tool Center Point relative to the center of robot flange |
X Y Z Rx Ry Rz TCP ONLINE |
tcp_start |
The fixed coordinate system which is located at the initial TCP pose of the primitive |
X Y Z Rx Ry Rz TCP START |
traj_start |
The offset of a waypoint relative to the initial TCP pose in the TCP coordinate system |
X Y Z Rx Ry Rz TRAJ START |
traj_goal |
The offset of a waypoint relative to the target TCP pose in the TCP coordinate system |
X Y Z Rx Ry Rz TRAJ GOAL |
traj_prev |
The offset of a waypoint relative to the previous waypoint in the TCP coordinate system |
X Y Z Rx Ry Rz TRAJ PREVIOUSWAYPOINT |
You can use the simplified value format above to describe a waypoint, while the complete description of a Cartesian waypoint is: X Y Z Rx Ry Rz ReferenceCoordinate A1 A2 A3 A4 A5 A6 A7 E1 E2 E3 E4 E5 E6. A1 to A7 are the preferred joint positions of the robot; X1 to X6 are the target positions of external axes. The additional data can be added if necessary.
Add “:” to separate the waypoints. For example: 0.2 0 0.3 0 180 0 WORLD WORLD_ORIGIN : 0.2 0.1 0.3 0 180 0 WORLD WORLD_ORIGIN.
*Robot Joint Position Description
The complete description of a joint waypoint (JPOS) is: A1 A2 A3 A4 A5 A6 A7 E1 E2 E3 E4 E5 E6. A1 to A7 are the joint positions of the robot; X1 to X6 are the positions of external axes. You can only set the robot joint positions if external axes do not exist. For example: {jnt_def_1}.
Add “:” to separate the waypoints. For example: {jnt_def_2}.
Primitive State Parameters
State Parameter |
Description |
Type |
Unit |
|---|---|---|---|
terminated |
The termination flag of the primitive. It is set to true if the primitive is terminated. |
BOOL |
none |
timePeriod |
The time spent on running the current primitive. |
DOUBLE |
s |
reachedTarget |
Flag to indicate if the robot has reached the target |
BOOL |
none |
waypointIndex |
Index of the current waypoint the robot just passed. 0 means the initial pose. |
INT |
none |
Primitive Output Parameters
Output Parameter |
Description |
Type |
Unit |
|---|---|---|---|
tcpPoseOut |
The TCP pose when the primitive is terminated. It is represented in the world coordinate system. |
COORD |
m-deg |
Default Transition Condition
State Parameter |
Condition |
Value |
|---|---|---|
reachedTarget |
= |
1 |
