JSON protocol:

End Effector Command set (optional)

##Gripper control

The RealMan robotic arm is equipped with the INSPIRE-ROBOTS EG2-4C2 gripper. To facilitate user operation of the gripper, the robotic arm controller provides an open gripper control protocol (the gripper control protocol is mutually exclusive with the end modbus functionality).

###Set the gripper stroke set_gripper_route

Set the gripper stroke, which refers to the maximum and minimum opening values of the gripper. Once set successfully, the values are saved automatically and will not be lost when the gripper is powered off.

• Input parameter

Parameter	Type	Description
set_gripper_route	string	Set the gripper stroke.
min	int	Minimum opening value of the gripper, range: 0−1,000, without a unit of measurement.
max	int	Maximum opening value of the gripper, range: 0−1,000, without a unit of measurement.

• Code demo

Input

{"command":"set_gripper_route","min":70,"max":500}

Output

Setting succeeded:

{
    "command": "set_gripper_route",
    "state": true
}

Setting failed:

{
    "command": "set_gripper_route",
    "state": false
}

###Set the gripper release set_gripper_release

• Input parameter

Parameter	Type	Description
set_gripper_release	string	Set the gripper release.
speed	int	Release speed of the gripper, range: 1−1,000, without a unit of measurement.
block	int	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the gripper release.

{"command":"set_gripper_release","speed":500,"block":true}

Output

Gripper release succeeded:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": true
}

Gripper release failed:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": false
}

This command is used to report the motion to a given position in blocking mode.

{"state":"current_trajectory_state","trajectory_state":true,"device":1,"trajectory_connect": 1}

###Set the force-controlled grasping of the gripper set_gripper_pick

Force-controlled grasping of the gripper: The gripper grasps with the set speed and force. When the gripping force exceeds the preset threshold, the gripper stops grasping.

• Input parameter

Parameter	Type	Description
set_gripper_pick	string	Set the force-controlled grasping of the gripper.
speed	int	Release speed of the gripper, range: 1−1,000, without a unit of measurement.
force	int	Force control threshold, range: 50−1,000, without a unit of measurement.
block	int	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input Set the force-controlled grasping of the gripper.

{"command":"set_gripper_pick","speed":500,"force":200,"block":true}

Output

Gripper release succeeded:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": true
}

Gripper release failed:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 1,
    "trajectory_connect": 1
}

###Set the continuous force-controlled grasping of the gripper set_gripper_pick_on

Continuous force-controlled grasping of the gripper: The gripper grasps with the set speed and force. When the gripping force exceeds the preset threshold, the gripper stops grasping. When the gripping force is less than the preset threshold, the gripper grasps again until the gripping force exceeds the preset threshold.

• Input parameter

Parameter	Type	Description
set_gripper_pick_on	string	Set the continuous force-controlled grasping of the gripper.
speed	int	Release speed of the gripper, range: 1−1,000, without a unit of measurement.
force	int	Force control threshold, range: 50−1,000, without a unit of measurement.
block	int	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the continuous force-controlled grasping of the gripper.

{"command":"set_gripper_pick_on","speed":500,"force":200,"block":true}

Output

Gripper release succeeded:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": false
}

Gripper release failed:
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 1,
    "trajectory_connect": 1
}

###Set the gripper to a given position set_gripper_position

Gripper at a given position: When the current opening is smaller than the given opening, the gripper releases to a given position at the given speed. When the current opening is larger than the given opening, the gripper closes to a given position at the given speed and force. The gripper stops when the gripping force exceeds the preset threshold or when the given position is reached.

• Input parameter

Parameter	Type	Description
set_gripper_position	string	Set the gripper to a given position.
position	int	Opening position of the gripper, range: 1−1,000, without a unit of measurement.
block	int	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the gripper to a given position.

{"command":"set_gripper_position","position":500,"block":true}

Output

Gripper release succeeded.
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": true
}

Gripper release failed.
This command will be returned regardless of whether it is in blocking mode.

{
    "command": "set_gripper",
    "state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 1,
    "trajectory_connect": 1
}

###Get the gripper state get_gripper_state

• Input parameter

Parameter	Type	Description
get_gripper_state	string	Get the gripper state.

• Output parameter

Parameter	Type	Description
enable	int	Gripper enabling state, 0: disable, 1: enable.
status	int	Gripper online state, 0: offline, 1: online.
error	int	Gripper error message. Indicated by the lower 8 bits. Bit5−7: reserved. Bit4: internal communication. Bit3: driver. Bit2: overcurrent. Bit1: over-temperature. Bit0: locked rotor.
mode	int	Current mode, 1: gripper fully open and idle, 2: gripper fully closed and idle, 3: gripper stopped and idle, 4: gripper in closing, 5: gripper in opening, 6: gripper stopped during closing due to force control.
current_force	int	Current force of the gripper, in g.
temperature	int	Current temperature, in °C.
actpos	int	Gripper opening.

• Code demo

Input

{"command":"get_gripper_state"}

Output

{
    "command": "get_gripper_state",
    "enable": 1,
    "status": 1,
    "error": 0,
    "mode": 1,
    "current_force": 100,
    "temperature": 40,
    "actpos": 150
}

Five-fingered dexterous hand

The RealMan robotic arm is equipped with an INSPIRE-ROBOTS five-fingered dexterous hand, which can be configured by the protocol.

###Set the gesture of the dexterous hand set_hand_posture

• Input parameter

Parameter	Type	Description
set_hand_posture	string	Set the gesture of the dexterous hand.
posture_num	int	Gesture sequence number pre-stored in the dexterous hand, range: 1−40.
block	bool	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
set_state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the gesture of the dexterous hand.

{"command":"set_hand_posture","posture_num":1,"block":true}

Output Setting succeeded:

{
    "command": "set_hand_posture",
    "set_state": true
}

Setting failed:

{
    "command": "set_hand_posture",
    "set_state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 2,
    "trajectory_connect": 1
}

###Set the action sequence of the dexterous hand set_hand_seq

• Input parameter

Parameter	Type	Description
set_hand_seq	string	Set the action sequence of the dexterous hand.
seq_num	int	Action sequence number pre-stored in the dexterous hand, range: 1−40.
block	bool	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
set_state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the action sequence of the dexterous hand.

{"command":"set_hand_seq","seq_num":1,"block":true}

Output Setting succeeded:

{
    "command": "set_hand_seq",
    "set_state": true
}

Setting failed:

{
    "command": "set_hand_seq",
    "set_state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 2,
    "trajectory_connect": 1
}

###Set the angles of the dexterous hand set_hand_angle

Set the angles of the dexterous hand, 6 active degrees of freedom (DOF), DOF 1 (thumb flexion), DOF 2 (index finger), DOF 3 (middle finger), DOF 4 (ring finger), DOF 5 (little finger), DOF 6 (thumb rotation).

• Input parameter

Parameter	Type	Description
set_hand_angle	string	Set the finger angles.
hand_angle	int	Array of finger angles, range: 0−1,000. Additionally, -1 indicates that no action will be performed for this degree of freedom, and the current state will be maintained.
block	bool	true: blocking mode, false: non-blocking mode.

• Output parameter

Parameter	Type	Description
set_state	bool	true: setting succeeded, false: setting failed.

You can refer to current_trajectory_state for the output parameters of the motion completion return result.

• Code demo

Input

Set the angles of the dexterous hand.

{"command":"set_hand_angle","hand_angle":[-1,100,200,300,400,500],"block":true}

Output Setting succeeded:

{
    "command": "set_hand_angle",
    "set_state": true
}

Setting failed:

{
    "command": "set_hand_angle",
    "set_state": false
}

This command is used to report the motion to a given position in blocking mode.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 2,
    "trajectory_connect": 1
}

###Set the speed of the dexterous hand set_hand_speed

• Input parameter

Parameter	Type	Description
set_hand_speed	string	Set the finger speed.
hand_speed	int	Finger speed, range: 1−1,000.

• Code demo

Input

{"command":"set_hand_speed","hand_speed":500}

Output Setting succeeded

{
    "command": "set_hand_speed",
    "set_state": true
}```

Setting failed

```json
{
    "command": "set_hand_speed",
    "set_state": false
}

###Set the force threshold of the dexterous hand set_hand_force

• Input parameter

Parameter	Type	Description
set_hand_force	string	Set the finger force threshold.
hand_force	int	Finger force, range: 1−1,000.

• Code demo

Input

{"command":"set_hand_force","hand_force":500}

Output Setting succeeded

{
    "command": "set_hand_force",
    "set_state": true
}

Setting failed

{
    "command": "set_hand_force",
    "set_state": false
}

Set the angle follow control of the dexterous hand hand_follow_angle

Set the following angles of the dexterous hand, 6 active degrees of freedom (DOF), DOF 1 (thumb flexion), DOF 2 (index finger), DOF 3 (middle finger), DOF 4 (ring finger), DOF 5 (little finger), DOF 6 (thumb rotation). The control frequency is up to 50 Hz.

WARNING

To use this feature, you need to contact technical support for a customized firmware upgrade package for the dexterous hand (OYMotion or INSPIRE-ROBOTS).

• Input parameter

Parameter	Type	Description
hand_follow_angle	string	Set the finger angles.

• The angle definitions and motion ranges for each degree of freedom of INSPIRE-ROBOTS are as follows.

Angle	Legend	Range
Little finger Ring finger Middle finger Index finger		19°−176.7°
Thumb bending angle		-130−53.6°
Thumb rotation angle		90°−165°

• The angle definitions and motion ranges for each degree of freedom of OYMotion are as follows.

Angle	Legend	Range
Index finger Middle finger Ring finger Little finger		100.22°−178.37° 97.81°−176.06° 101.38°−176.54° 98.84°−174.86°
Thumb bending angle		2.26°−36.76°
Thumb rotation angle		0°−90°

• Code demo

Input

Execution: Set the finger actions of the dexterous hand. hand_angle: array of finger angles, controlled according to the angles defined by the manufacturer of the dexterous hand. For example:

1. OYMotion has an angle range from -32,768 to +32,767;
2. INSPIRE-ROBOTS has an angle range from 0 to +1,000.

Definition of angles of the dexterous hand (int16):

1. OYMotion: angle of joint 1 of the first finger × 100;
2. INSPIRE-ROBOTS: 0−1,000. Please contact technical support for the relationship table between the driver stroke and angle.

{"command":"hand_follow_angle","hand_angle":[100,100,200,300,400,500]}

Output Setting succeeded

{
    "command": "hand_follow_angle",
    "set_state": true
}

Setting failed

{
    "command": "hand_follow_angle",
    "set_state": false
}

Set the position follow control of the dexterous hand hand_follow_pos

Set the following angles of the dexterous hand, 6 active degrees of freedom (DOF), DOF 1 (thumb flexion), DOF 2 (index finger), DOF 3 (middle finger), DOF 4 (ring finger), DOF 5 (little finger), DOF 6 (thumb rotation). The control frequency is up to 50 Hz.

WARNING

To use this feature, you need to contact technical support for a customized firmware upgrade package for the dexterous hand (OYMotion or INSPIRE-ROBOTS).

• Input parameter

Parameter	Type	Description
hand_follow_pos	string	Set the finger angles.

• Code demo

Input

Execution: Set the finger actions of the dexterous hand. hand_pos: array of finger positions, controlled according to the angles defined by the manufacturer of the dexterous hand. For example:

1. INSPIRE-ROBOTS has a position range from 0 to 2,000;
2. OYMotion has a position range from 0 to 65,535.

{"command":"hand_follow_pos","hand_pos":[100,100,200,300,400,500]}

Output Setting succeeded

{
    "command": "hand_follow_pos",
    "set_state": true
}

Setting failed

{
    "command": "hand_follow_pos",
    "set_state": false
}

End tool action list

RealMan robotic arm’s functions related to the end effector action list enable comprehensive management and control of end effector actions.

Get the end tool action listget_tool_action_list

• Input parameter

Parameter	Type	Description
get_tool_action_list	string	Query the action list.
page_num	int	Page number (Do not pass this parameter when querying all).
page_size	int	Page size (Do not pass this parameter when querying all).
vague_search	string	Fuzzy search (Pass this parameter to perform fuzzy query).

• Output parameter

Parameter	Type	Description
get_tool_action_list	string	Query the action list.
total_size	int	Total number of actions.
list	object	Detailed action information.

• Code demo

Input

{"command":"get_tool_action_list"}

Output

{
    "action_list": [
    {
      "hand_pos": [0, 0, 0, 0, 0, 0],
      "name": "Realman"
    },
    {
      "hand_pos": [0, 0, 0, 0, 0, 0],
      "name": "111111111111111"
    },
    {
      "hand_pos": [0, 0, 0, 0, 0, 0],
      "name": "QN-Tactile"
    },
    {
      "hand_pos": [14, 19, 18, 9, 6, 4],
      "name": "QN-Gripper Closure"
    },
    {
      "hand_pos": [14, 19, 18, 9, 6, 4],
      "name": "QN-Gripper Closure-1-1-1-1"
    },
    {
      "hand_pos": [14, 19, 18, 9, 6, 4],
      "name": "Qiangnao-Target Position"
    },
    {
      "hand_pos": [12],
      "name": "Open-1-1-1-1"
    },
    {
      "hand_pos": [12000],
      "name": "Gripper Closure-1-1-1-1"
    },
    {
      "hand_pos": [12],
      "name": "Open-1-1-1"
    },
    {
      "hand_pos": [12000],
      "name": "Gripper Closure-1-1-1"
    },
    {
      "hand_pos": [12],
      "name": "Open-1-1"
    },
    {
      "hand_pos": [12000],
      "name": "Gripper Closure-1-1"
    },
    {
      "hand_pos": [12],
      "name": "Open-1"
    },
    {
      "hand_pos": [12000],
      "name": "Gripper Closure-1"
    },
    {
      "hand_pos": [12000],
      "name": "Gripper Closure"
    },
    {
      "hand_pos": [12],
      "name": "Open"
    }
  ],
  "command": "get_tool_action_list",
  "total_size": 16
}

Run the specified end effector actionrun_tool_action

• Input parameter

Parameter	Type	Description
run_tool_action	string	Start running the numbered trajectory.
name	string	Run the action with the specified name; it can run as long as the action exists.

• Output parameter

Parameter	Type	Description
run_state	bool	true: Start running. false: Run failed.
run_tool_action	string	The trajectory file runs in place.

• Code demo

Input

Start running the action "123".

{
    "command": "run_tool_action",
    "name": "123"
}

Output

Start running succeeded.

{
    "command": "run_tool_action",
    "run_state": true
}

Start running failed.

{
    "command": "run_tool_action",
    "run_state": false
}

After the end action is completed, the operation end command is returned.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 5,
    "trajectory_connect": 0
}

Delete the specified end effector actiondelete_tool_action

• Input parameter

Parameter	Type	Description
delete_tool_action	string	Delete the action with the specified name.
name	string	The name of the action to be deleted.

• Output parameter

Parameter	Type	Description
delete_state	bool	true: Succeeded. false: Failed.

• Code demo

Input

Delete trajectory 2.

{
    "command": "delete_tool_action",
    "name": "pick"
}

Output

Deletion succeeded.

{
    "command": "delete_tool_action",
    "delete_state": true
}

Deletion failed.

{
    "command": "delete_tool_action",
    "delete_state": false
}

Save the end tool actionsave_tool_action

• Input parameter

Parameter	Type	Description
save_tool_action	string	Save the action.
name	string	The name of the action to be saved.
hand_pos	array	Position.
hand_angle	array	Angle.

• Output parameter

Parameter	Type	Description
save_state	bool	true: Succeeded. false: Failed.

• Code demo

Input

{
    "command": "save_tool_action",
    "name": "pick",
    "hand_pos": [0, 0, 0, 0, 0, 0]
}

{
    "command": "save_tool_action",
    "name": "pick",
    "hand_angle": [0, 0, 0, 0, 0, 0]
}

Output

Saving succeeded.

{
    "command": "save_tool_action",
    "save_state": true
}

Saving failed.

{
    "command": "save_tool_action",
    "save_state": false
}

Update the end tool actionupdate_tool_action

• Input parameter

Parameter	Type	Description
update_tool_action	string	Update the action.
name	string	The name of the action to be updated.
new_name	string	New action name.
hand_pos	array	Position.
hand_angle	array	Angle.

• Output parameter

Parameter	Type	Description
update_state	bool	true: Succeeded. false: Failed.

• Code demo

Input

{
    "command": "update_tool_action",
    "name": "pick",
    "new_name": "1",
    "hand_pos": [0, 0, 0, 0, 0, 0]
}

{
    "command": "update_tool_action",
    "name": "pick",
    "new_name": "1",
    "hand_angle": [0, 0, 0, 0, 0, 0]
}

Output

Update succeeded.

{
    "command": "update_tool_action",
    "update_state": true
}

Update failed.

{
    "command": "update_tool_action",
    "update_state": false,
}

Trajectory end return flagcurrent_trajectory_state

The trajectory is the current trajectory.

• Input parameter

Parameter	Type	Description
current_trajectory_state	string	Return flag when the current trajectory ends.
device	int	0: Joint, 1: Gripper, 2: Dexterous Hand, 3: Lifting Mechanism, 4: Extended Joint, 5: End Tool Action, Others: Reserved.

• Code demo

Implementation: The current trajectory reaches the target.

{
    "state": "current_trajectory_state",
    "trajectory_state": true,
    "device": 0
}