C、C++:
Five-Finger Dexterous Hand ConfigurationhandControl The RealMan robotic arm is equipped with an INSPIRE-ROBOTS five-fingered dexterous hand at its end-effector, which can be configured through this interface. It includes settings for gesture actions, movement angles, speed, force control range, etc.
Run dexterous hand target gesture sequence number rm_set_hand_posture()
rm_set_hand_posture()- Method prototype:
C
int rm_set_hand_posture(rm_robot_handle * handle,int posture_num,bool block,int timeout)Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
posture_num | Input | Gesture sequence number pre-stored in the dexterous hand, range: 1-40. |
block | Input | true indicates blocking mode, which waits until the dexterous hand motion completes before returning; false indicates non-blocking mode, which returns immediately after the command is sent. |
timeout | Input | Timeout setting in blocking mode, in s. |
- Return value:
| Parameter | Type | Description | Handling Suggestions |
|---|---|---|---|
| 0 | int | Success. | - |
| 1 | int | The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong. | - Validate JSON Command: ① Enable DEBUG logs for the API to capture the raw JSON data. ② Check JSON syntax: Ensure correct formatting of parentheses, quotes, commas, etc. (You can use a JSON validation tool). ③ Verify against the API documentation that parameter names, data types, and value ranges comply with the specifications. ④ After fixing the issues, resend the command and check if the controller returns a normal status code and business data. - Check Robot Arm Status: ① Check for real-time error messages in the robot arm controller or logs (such as hardware failures, over-limit conditions), and reset, calibrate, or troubleshoot hardware issues according to the prompts. ② After fixing the issues, resend the command and check if the controller returns a normal status code and business data. |
| -1 | int | The data transmission fails, indicating that a problem occurs during the communication. | Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. |
| -2 | int | The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout. | - Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. - Verify Version Compatibility: ① Check if the controller firmware version supports the current API functions. For specific version compatibility, refer to the Version Description. ② If the version is too low, upgrade the controller or use an API version that is compatible. |
| -3 | int | The return value parse fails, indicating that the received data format is incorrect or incomplete. | Verify Version Compatibility: ① Check if the controller firmware version supports the current API functions. For specific version compatibility, refer to the Version Description. ② If the version is too low, upgrade the controller or use an API version that is compatible. |
| -4 | int | The current in-position equipment verification fails, indicating the current in-position equipment is not a dexterous hand. | - Detect Concurrent Control by Multiple Devices: Check if other devices are sending motion commands to the robot arm, including the motion of the robot arm, gripper, dexterous hand, and elevator. - Monitor Command Events in Real-Time: Register the callback function rm_get_arm_event_call_back:① Capture device arrival events (such as motion completion, timeout, etc.). ② Determine the specific device type that triggered the event through the device parameter in the callback. |
| -5 | int | Timeout, no response returns. | - Check Timeout Setting: In blocking mode, it supports configuring the timeout for waiting for the device to complete its motion. Ensure that the timeout is set longer than the device's motion time. - Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. |
- Usage demo
C
//Set the dexterous hand to execute gesture 1 in blocking mode, and trigger a timeout if no response is received within 10 seconds
int posture_num = 1;
ret = rm_set_hand_posture(robot_handle,posture_num,true,10);Run dexterous hand action sequence number rm_set_hand_seq()
rm_set_hand_seq()- Method prototype:
C
int rm_set_hand_seq(rm_robot_handle * handle,int seq_num,bool block,int timeout)Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
seq_num | Input | Action sequence number pre-stored in the dexterous hand, range: 1-40. |
block | Input | true indicates blocking mode, where the system waits for the dexterous hand to finish its movement before returning; falseindicates non-blocking mode, where the system returns immediately after sending the command. |
timeout | Input | Timeout setting in blocking mode, in s. |
- Return value:
| Parameter | Type | Description | Handling Suggestions |
|---|---|---|---|
| 0 | int | Success. | - |
| 1 | int | The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong. | - Validate JSON Command: ① Enable DEBUG logs for the API to capture the raw JSON data. ② Check JSON syntax: Ensure correct formatting of parentheses, quotes, commas, etc. (You can use a JSON validation tool). ③ Verify against the API documentation that parameter names, data types, and value ranges comply with the specifications. ④ After fixing the issues, resend the command and check if the controller returns a normal status code and business data. - Check Robot Arm Status: ① Check for real-time error messages in the robot arm controller or logs (such as hardware failures, over-limit conditions), and reset, calibrate, or troubleshoot hardware issues according to the prompts. ② After fixing the issues, resend the command and check if the controller returns a normal status code and business data. |
| -1 | int | The data transmission fails, indicating that a problem occurs during the communication. | Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. |
| -2 | int | The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout. | - Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. - Verify Version Compatibility: ① Check if the controller firmware version supports the current API functions. For specific version compatibility, refer to the Version Description. ② If the version is too low, upgrade the controller or use an API version that is compatible. |
| -3 | int | The return value parse fails, indicating that the received data format is incorrect or incomplete. | Verify Version Compatibility: ① Check if the controller firmware version supports the current API functions. For specific version compatibility, refer to the Version Description. ② If the version is too low, upgrade the controller or use an API version that is compatible. |
| -4 | int | The current in-position equipment verification fails, indicating the current in-position equipment is not a dexterous hand. | - Detect Concurrent Control by Multiple Devices: Check if other devices are sending motion commands to the robot arm, including the motion of the robot arm, gripper, dexterous hand, and elevator. - Monitor Command Events in Real-Time: Register the callback function rm_get_arm_event_call_back:① Capture device arrival events (such as motion completion, timeout, etc.). ② Determine the specific device type that triggered the event through the device parameter in the callback. |
| -5 | int | Timeout, no response returns. | - Check Timeout Setting: In blocking mode, it supports configuring the timeout for waiting for the device to complete its motion. Ensure that the timeout is set longer than the device's motion time. - Check Network Connectivity: Use tools like ping/telnet to check if the communication link with the controller is normal. |
- Usage demo
C
//Set the dexterous hand to execute action sequence 1 in blocking mode, and trigger a timeout if no response is received within 15 seconds
int posture_num = 1;
ret = rm_set_hand_seq(robot_handle,posture_num,true,15);Set the angles of the dexterous hand’s degrees of freedomrm_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).
- Method prototype:
C
int rm_set_hand_angle(rm_robot_handle * handle,const int * hand_angle, bool block, int timeout)Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
hand_angle | Input | Array of predefined 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 | Input | true: Indicates non-blocking mode, returns after sending successfully. false: Indicates blocking mode, returns after receiving the successful setting command. |
timeout | Input | Timeout setting in blocking mode, unit: seconds. |
- Return value:
0 represents success. For other error codes, please refer to the API2 Error Codes.
- Usage demo
C
//Set the actions of each finger of the dexterous hand
int ret;
int hand_angle[6] = {-1,100,200,300,400,500};
bool block = true;
int timeout = 1;
ret = rm_set_hand_angle(handle, hand_angle, block, timeout);Set the speed of the dexterous handrm_set_hand_speed()
- Method prototype:
C
int rm_set_hand_speed(rm_robot_handle * handle,int speed)Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
speed | Input | Finger speed, range: 1-1,000. |
- Return value:
0 represents success. For other error codes, please refer to the API2 Error Codes.
- Usage demo
C
//Set the speed of each finger of the dexterous hand
int speed = 500;
ret = rm_set_hand_speed(robot_handle,speed);Set the force threshold of the dexterous handrm_set_hand_force()
- Method prototype:
C
int rm_set_hand_force(rm_robot_handle * handle,int hand_force)Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
hand_force | Input | Finger force, range: 1-1,000. |
- Return value:
0 represents success. For other error codes, please refer to the API2 Error Codes.
- Usage demo
C
//Set the force threshold of the dexterous hand to 500
int force = 500;
ret = rm_set_hand_force(robot_handle,force);Set the angle follow control of the dexterous handrm_set_hand_follow_angle()
- Set the follow angles of the dexterous hand, which has 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.
- Definition of angles of the dexterous hand (int16):
- OYMotion: angle of joint 1 of the first finger *100.
- INSPIRE-ROBOTS: 0-2,000, obtain the relationship table between the driver stroke and angle by contacting technical support.
- OYMotion: angle of joint 1 of the first finger *100.
WARNING
To use this feature, you need to contact technical support to receive a customized firmware upgrade package for the dexterous hand (OYMotion or INSPIRE-ROBOTS).
- Method prototype:
C
int rm_set_hand_follow_angle(rm_robot_handle *handle, const int *hand_angle, bool block);Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
hand_angle | Input | Set the actions of each finger of the dexterous hand. hand_angle represents the array of finger angles, controlled according to the angles defined by the manufacturer of the dexterous hand. For example: 1. INSPIRE-ROBOTS has an angle range from 0 to +2,000; 2. OYMotion has an angle range from -32,768 to +32,767. |
block | Input | true: Indicates non-blocking mode, returns after sending successfully. false: Indicates blocking mode, returns after receiving the successful setting command. |
- 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° |
- Return value:
0 represents success. For other error codes, please refer to the API2 Error Codes.
- Usage demo
C
// High-speed control of the dexterous hand, non-blocking mode
const int angle[6]= {0,100,200,300,400,500};
bool block = true;
ret = rm_set_hand_follow_angle(robot_handle,angle,block);Set the position follow control of the dexterous handrm_set_hand_follow_pos()
Set the follow positions 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 to receive a customized firmware upgrade package for the dexterous hand (OYMotion or INSPIRE-ROBOTS).
- Method prototype:
C
int rm_set_hand_follow_pos(rm_robot_handle *handle, const int *hand_pos, bool block);Jump to rm_robot_handle for details of the structure.
- Parameter description:
| Parameter | Type | Description |
|---|---|---|
handle | Input | Robotic arm handle. |
hand_pos | Input | Set the actions of each finger of the dexterous hand. hand_angle represents the 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 1,000; 2. OYMotion has a position range from 0 to 65,535. |
block | Input | true: Indicates non-blocking mode, returns after sending successfully. false: Indicates blocking mode, returns after receiving the successful setting command. |
- Return value:
0 represents success. For other error codes, please refer to the API2 Error Codes.
- Usage demo
C
// High-speed control of the dexterous hand, non-blocking mode
const int pos[6]= {0,100,200,300,400,500};
bool block = true;
ret = rm_set_hand_follow_pos(robot_handle,pos,block);