Python SDK

2025-12-052025-12-08

1.Introduction

This SDK provides convenient Python interfaces for the secondary development of the Aoyi Smart Hand. It allows developers to manage device connection, data acquisition, and gesture control, thereby accelerating the development of applications utilizing the Smart Hand.

2.Supported Operating Systems and Software Versions

Operating System

Windows (64-bit & 32-bit): Support for both 64-bit and 32-bit versions on the Windows operating system, facilitating development for Windows users. Linux (x86 & ARM): Support for both x86 and ARM architectures on the Linux operating system, meeting the requirements of diverse hardware environments.

Software Version

Python 3.12 and above: This development kit is targeted for Python 3.12 and later，ensuring compatibility with the latest Python versions.

3.Installation and Usage

Installation

Download the SDK Locally：

Method 1: Click this link to download
Method 2: Visit ohand_serial_sdk_python Github page to get the latest Python SDK

Method 3: Obtain via clone:

git clone https://github.com/oymotion/ohand_serial_sdk_python

Usage

Upon successful installation, users can import the SDK into their Python scripts and leverage the API for Smart Hand development. The following code snippet demonstrates the primary code for connecting to the Smart Hand (available in the simple_control.py file):

def main():
    interface_instance = None
    ohand_instance = None
    if PORT_TYPE == PORT_UART:
        interface_instance = Serial_Init(port_name=find_comport("CH340") or find_comport("Serial"), baudrate=115200)
    else:
        interface_instance = CAN_Init(port_name="1", baudrate=1000000)

    if interface_instance is None:
        print("Port init failed\n")
        return

    ohand_instance = OHandSerialAPI(interface_instance, HAND_PROTOCOL_UART, ADDRESS_MASTER,
                                           send_data_impl, recv_data_impl)

    ohand_instance.HAND_SetTimerFunction(get_milli_seconds_impl, delay_milli_seconds_impl)
    ohand_instance.HAND_SetCommandTimeOut(255)
    print(ohand_instance.get_private_data(), "\n")

The output is shown below:

初始化.png

4.API Reference

init()

Method Signature：

def __init__(self, private_data, protocol, address_master, send_data_impl, recv_data_impl=None):

Parameters:

Parameter	Description
`self.address_master = address_master`	Device Address
`self.protocol = protocol`	Communication Protocol
`self.private_data = private_data`	Internal private data storage for the class.
`self.recv_data_impl = recv_data_impl`	Receiver Function
`self.send_data_impl = send_data_impl`	Send Function

Return Value： Status: None on success
Failure: Return the corresponding error code

HAND_SendCmd()

Method Signature：

def HAND_SendCmd(self, addr, cmd, data, nb_data):

Parameters：

Parameter	Description
`cmd`	Command ID
`data`	Command Data
`nb_data`	Data Length

Return Value： Status: None on success
Failure: Return the corresponding error code

HAND_GetResponse()

Method Signature：

def HAND_GetResponse(self, addr, cmd, time_out, resp_bytes, remote_err):

Parameters：

Parameter	Description
`addr`	Device Address
`cmd`	命Command ID令ID
`time_out`	Timeout Period
`resp_bytes`	Response Data Buffer
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code

HAND_OnData()

Method Signature：

HAND_OnData(data)

Parameters：

Parameter Description

date Date
Return Value： Status: None on success
Failure: Return the corresponding error code

HAND_HAND_SetTimerFunctionOnData()

Method Signature：

def HAND_SetTimerFunction(self, get_milli_seconds_impl, delay_milli_seconds_impl):

Parameters：

Parameter Description

get_milli_seconds_impl Gets the current time

delay_milli_seconds_impl Delay Function
Return Value： Status: None on success
Failure: Return the corresponding error code

HAND_GetProtocolVersion()

Method Signature：

def HAND_GetProtocolVersion(self, hand_id, major, minor, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`major`	Outputs the major version numberParameter
`minor`	次版本号输出Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

major, minor = [0], [0]
err, major_get, minor_get = serial_api_instance.HAND_GetProtocolVersion(hand_id, major, minor, [])
assert err == HAND_RESP_SUCCESS, f"获取协议版本失败: {err}"
logger.info(f"成功获取协议版本: V{major_get}.{minor_get}")

HAND_GetFirmwareVersion()

Method Signature：

def HAND_GetFirmwareVersion(self, hand_id, major, minor, revision, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`major`	Outputs the major version number parameter
`minor`	Outputs the minor version number parameter
`revision`	Outputs the revision number parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

major, minor, revision = [0], [0], [0]
err, major_get, minor_get, revision_get = serial_api_instance.HAND_GetFirmwareVersion(hand_id, major, minor, revision, [])
assert err == HAND_RESP_SUCCESS, f"获取固件版本失败: {err}"
logger.info(f"成功获取固件版本: V{major_get}.{minor_get}.{revision_get}")

HAND_GetHardwareVersion()

Method Signature：

def HAND_GetHardwareVersion(hand_id, hw_type, hw_ver, boot_version, remote_err)

Parameters：

Parameter	功能
`hand_id`	Device Address
`hw_type`	Hardware Type Output Parameter
`hw_ver`	Hardware Version Output Parameter
`boot_version`	Bootloader Version Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

hw_type, hw_ver, boot_version = [0], [0], [0]
err, hw_type_get, hw_ver_get, boot_version_get = serial_api_instance.HAND_GetHardwareVersion(hand_id, hw_type, hw_ver, boot_version, [])
assert err == HAND_RESP_SUCCESS, f"获取硬件版本失败: {err}"
logger.info(f"成功获取硬件版本: V{hw_type_get}.{hw_ver_get}.{boot_version_get}")

HAND_GetCaliData()

Method Signature：

def HAND_GetCaliData(self, hand_id, end_pos, start_pos, motor_cnt, thumb_root_pos, thumb_root_pos_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`end_pos`	End Position Array
`start_pos`	Start Position Array
`motor_cnt`	Motor Quantity
`thumb_root_pos`	Thumb Base Position Array
`thumb_root_pos_cnt`	Thumb Base Position Gear
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

end_pos = [0] * MAX_MOTOR_CNT
start_pos = [0] * MAX_MOTOR_CNT
motor_cnt = [MAX_MOTOR_CNT]
thumb_root_pos = [0] * MAX_THUMB_ROOT_POS
thumb_root_pos_cnt = [3]  # 初始请求3个拇指根位置Date
err, end_pos_get, start_pos_get, thumb_root_pos_get = serial_api_instance.HAND_GetCaliData(hand_id, end_pos, start_pos, motor_cnt, thumb_root_pos, thumb_root_pos_cnt, [])
assert err == HAND_RESP_SUCCESS, f"获取矫正Date失败: {err}"
logger.info(f"成功获取矫正Date, end_pos: {end_pos_get}, start_pos: {start_pos_get}, thumb_root_pos: {thumb_root_pos_get}, ")

HAND_GetFingerPID()

Method Signature：

def HAND_GetFingerPID(self, hand_id, finger_id, p, i, d, g, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`p`	比例ParameterP
`i`	积分ParameterI
`d`	微分ParameterD
`g`	重力补偿ParameterG
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

p, i, d, g = [0], [0], [0], [0]
for j in range(MAX_MOTOR_CNT):
  err, p_get, i_get, d_get, g_get = serial_api_instance.HAND_GetFingerPID(hand_id, j, p, i, d, g, None)
  assert err == HAND_RESP_SUCCESS, f"获取pidDate失败: {err}"
  logger.info(f"成功获取手指: {j} pidDate: p: {p_get} i: {i_get} d: {d_get} g: {g_get}")

HAND_GetFingerCurrentLimit()

Method Signature：

def HAND_GetFingerCurrentLimit(self, hand_id, finger_id, current_limit, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`current_limit`	电流限制值（单位： mA或其他硬件相关单位）
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

current_limit = [0]
for i in range(MAX_MOTOR_CNT):
  err, current_limit_get = serial_api_instance.HAND_GetFingerCurrentLimit(hand_id, i, current_limit, None)
  assert err == HAND_RESP_SUCCESS, f"获取电流最大值失败: {err}"
  logger.info(f"成功获取手指: {i} 电流最大值: {current_limit_get}")

HAND_GetFingerCurrent()

Method Signature：

def HAND_GetFingerCurrent(self, hand_id, finger_id, current, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`current`	实时电流值
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

current = [0]
for i in range(MAX_MOTOR_CNT):
  err, current_get = serial_api_instance.HAND_GetFingerCurrent(hand_id, i, current, [])
  assert err == HAND_RESP_SUCCESS, f"获取电流最大值失败: {err}"
  logger.info(f"成功获取手指: {i} 电流值: {current_get}")

HAND_GetFingerForceTarget()

Method Signature：

def HAND_GetFingerForceTarget(self, hand_id, finger_id, force_target, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`force_target`	Target Force Value
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

force_target = [0]
for i in range(MAX_MOTOR_CNT):
  err, force_target_get = serial_api_instance.HAND_GetFingerForceTarget(hand_id, i, force_target, [])
  assert err == HAND_RESP_SUCCESS, f"手指力值目标失败: {err}"
  logger.info(f"成功获取手指: {i} 力值目标: {force_target_get}")

HAND_GetFingerForce()

Method Signature：

def HAND_GetFingerForce(self, hand_id, finger_id, force_entry_cnt, force, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`force_entry_cnt`	Number of Actual Force Data Entries
`force`	Force Data Array
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

force = [0] * MAX_FORCE_ENTRIES
force_entry_cnt = [0]
for i in range(MAX_MOTOR_CNT):
  err, force_get = serial_api_instance.HAND_GetFingerForce(hand_id, i, force_entry_cnt, force, [])
  assert err == HAND_RESP_SUCCESS, f"手指每点力值失败: {err}"
  logger.info(f"成功获取手指: {i} 力值每点: {force_get}")

HAND_GeHAND_GetFingerPosLimittFingerForce()

Method Signature：

def HAND_GetFingerPosLimit(self, hand_id, finger_id, low_limit, high_limit, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`low_limit`	Lower Position Limit (Minimum Position)
`high_limit`	Upper Position Limit (Maximum Position)
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

low_limit, high_limit = [0], [0]
for i in range(MAX_MOTOR_CNT):
  err, low_limit_get,high_limit_get  = serial_api_instance.HAND_GetFingerPosLimit(hand_id, i, low_limit, high_limit, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指限位值失败: {err}"
  logger.info(f"成功获取手指: {i} 限位值low: {low_limit_get}, 限位值high: {high_limit_get}")

HAND_GetFingerPosAbs()

Method Signature：

def HAND_GetFingerPosAbs(self, hand_id, finger_id, target_pos, current_pos, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`target_pos`	Target Absolute Position (Raw Encoder Value)
`current_pos`	Current Absolute Position (Raw Encoder Value)
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

target_pos, current_pos = [0], [0]
for i in range(MAX_MOTOR_CNT):
  err, target_pos_get, current_pos_get = serial_api_instance.HAND_GetFingerPosAbs(hand_id, i, target_pos, current_pos, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指绝对位置失败: {err}"
  logger.info(f"成功获取手指: {i} 目标绝对位置: {target_pos_get}, 当前绝对位置: {current_pos_get}")

HAND_GetFingerPos()

Method Signature：

def HAND_GetFingerPos(self, hand_id, finger_id, target_pos, current_pos, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`target_pos`	Target Logical Position (Calibrated Mapping Value)）
`current_pos`	Current Logical Position (Calibrated Mapping Value)
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

target_pos, current_pos = [0], [0]
for i in range(MAX_MOTOR_CNT):
  err, target_pos_get, current_pos_get = serial_api_instance.HAND_GetFingerPos(hand_id, i, target_pos, current_pos, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指位置失败: {err}"
  logger.info(f"成功获取手指: {i} 目标位置: {target_pos_get}, 当前位置: {current_pos_get}")

HAND_GetFingerAngle()

Method Signature：

def HAND_GetFingerAngle(self, hand_id, finger_id, target_angle, current_angle, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`target_angle`	Target Angle Output Parameter
`current_angle`	Current Angle Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

target_angle, current_angle = [0], [0]
for i in range(MAX_MOTOR_CNT):
  err, target_angle_get, current_angle_get = serial_api_instance.HAND_GetFingerAngle(hand_id, i, target_angle, current_angle, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指角度失败: {err}"
  logger.info(f"成功获取手指: {i} 目标角度: {target_angle_get}, 当前角度: {current_angle_get}")

HAND_GetThumbRootPos()

Method Signature：

def HAND_GetThumbRootPos(self, hand_id, raw_encoder, pos, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`raw_encoder`	Raw Encoder Value Output Parameter
`pos`	Calibrated Position Value Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

raw_encoder, pos = [0], [0]
err, raw_encoder_get, pos_get = serial_api_instance.HAND_GetThumbRootPos(hand_id, raw_encoder, pos, [])
assert err == HAND_RESP_SUCCESS, f"获取大拇指位置失败: {err}"
logger.info(f"成功获取大拇指: 原始值: {raw_encoder_get}, 位置: {pos_get}")

HAND_GetFingerPosAbsAll()

Method Signature：

def HAND_GetFingerPosAbsAll(self, hand_id, target_pos, current_pos, motor_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`target_pos`	目Absolute Position Array Output Parameter (Raw Encoder Values)
`current_pos`	Current Absolute Position Array Output Parameter (Raw Encoder Values)
`motor_cnt`	Input/Output Parameter: Motor Count
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

target_pos, current_pos = [0] * MAX_MOTOR_CNT, [0] * MAX_MOTOR_CNT
motor_cnt = [MAX_MOTOR_CNT]
err, target_pos, current_pos = serial_api_instance.HAND_GetFingerPosAbsAll(hand_id, target_pos, current_pos, motor_cnt, [])
assert err == HAND_RESP_SUCCESS, f"获取手指全部绝对位置失败: {err}"
logger.info(f"成功获取全部绝对位置: 当前位置: {current_pos}, 目标位置:{target_pos}")

HAND_GetFingerAngleAll()

Method Signature：

def HAND_GetFingerAngleAll(self, hand_id, target_angle, current_angle, motor_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`target_angle`	Target Angle Array Output Parameter
`current_angle`	Current Angle Array Output Paramete
`motor_cnt`	Joint Count Parameter (Input/Output)
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

target_angle, current_angle = [0] * MAX_MOTOR_CNT, [0] * MAX_MOTOR_CNT
motor_cnt = [MAX_MOTOR_CNT]
err, target_angle, current_angle = serial_api_instance.HAND_GetFingerAngleAll(hand_id, target_angle, current_angle, motor_cnt, [])
assert err == HAND_RESP_SUCCESS, f"获取手指全部角度失败: {err}"
logger.info(f"成功获取全部角度: 当前角度: {target_angle}, 目标角度:{current_angle}")

HAND_GetFingerStopParams()

Method Signature：

def HAND_GetFingerStopParams(self, hand_id, finger_id, speed, stop_current, stop_after_period, retry_interval, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`speed`	Stop Speed Output Parameter
`stop_current`	Stop Current Threshold Output Parameter
`stop_after_period`	Stop Wait Time Output Parameter
`retry_interval`	Retry Interval Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

speed, stop_current, stop_after_period, retry_interval = [0], [0], [0], [0]
for i in range(MAX_MOTOR_CNT):
  err, speed_get, stop_current_get, stop_after_period_get, retry_interval_get = serial_api_instance.HAND_GetFingerStopParams(hand_id, i, speed, stop_current, stop_after_period, retry_interval, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指停止Parameter失败: {err}"
  logger.info(f"成功获取手指停止Parameter: 速度: {speed_get}, 暂停电流:{stop_current_get}, 暂停间隔:{stop_after_period_get}, 重试间隔:{retry_interval_get}")

HAND_GetFingerForcePID()

Method Signature：

def HAND_GetFingerForcePID(self, hand_id, finger_id, p, i, d, g, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`p`	Proportional Parameter
`i`	Integral Parameter
`d`	Derivative Parameter
`g`	Gravity Compensation Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

p, i, d, g = [0], [0], [0], [0]
for j in range(MAX_MOTOR_CNT - 1):
  err, p_get, i_get, d_get, g_get = serial_api_instance.HAND_GetFingerForcePID(hand_id, j, p, i, d, g, [])
  assert err == HAND_RESP_SUCCESS, f"获取手指力pid失败: {err}"
  logger.info(f"成功获取手指力pid: 手指: {j} p: {p_get}, i:{i_get}, d:{d_get}, g:{g_get}")

HAND_GetSelfTestLevel()

Method Signature：

def HAND_GetSelfTestLevel(self, hand_id, self_test_level, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`self_test_level`	Self-Test Level Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code

self_test_level = [0]
err, self_test_level_get = serial_api_instance.HAND_GetSelfTestLevel(hand_id, self_test_level, [])
assert err == HAND_RESP_SUCCESS, f"获取自检等级失败: {err}"
logger.info(f"成功自检等级: {self_test_level_get}")

HAND_GetBeepSwitch()

Method Signature：

def HAND_GetBeepSwitch(self, hand_id, beep_switch, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`beep_switch`	Buzzer Switch Status Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

beep_switch = [0]
err, beep_switch_get = serial_api_instance.HAND_GetBeepSwitch(hand_id, beep_switch, [])
assert err == HAND_RESP_SUCCESS, f"获取蜂鸣器开关失败: {err}"
logger.info(f"成功获取蜂鸣器开关: {beep_switch_get}")

HAND_GetButtonPressedCnt()

Method Signature：

def HAND_GetButtonPressedCnt(self, hand_id, pressed_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`pressed_cnt`	Button Press Count Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

button_pressed_cnt = [0]
err, button_pressed_cnt_get = serial_api_instance.HAND_GetButtonPressedCnt(hand_id, button_pressed_cnt, [])
assert err == HAND_RESP_SUCCESS, f"获取手按下的数量: {err}"
logger.info(f"获取手按下的数量: {button_pressed_cnt_get}")

Note: This feature is only available for the bionic hand. It is not available on the dexterous hand.

HAND_GetUID()

Method Signature：

def HAND_GetUID(self, hand_id, uid_w0, uid_w1, uid_w2, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`uid_w0`	UID Part 1 Output Parameter
`uid_w1`	UID Part 2 Output Parameter
`uid_w2`	UID Part 3 Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

uid_w0, uid_w1, uid_w2 = [0], [0], [0]
err, uid_w0_get, uid_w1_get, uid_w2_get = serial_api_instance.HAND_GetUID(hand_id, uid_w0, uid_w1, uid_w2, [])
assert err == HAND_RESP_SUCCESS, f"获取uid: {err}\n"
logger.info(f"获取uid: uid_w0: {uid_w0_get}, uid_w1: {uid_w1_get}, uid_w2: {uid_w2_get}")

HAND_GetBatteryVoltage()

Method Signature：

def HAND_GetBatteryVoltage(self, hand_id, voltage, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`voltage`	Battery Voltage Value Output Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Note: This feature is only available for the bionic hand. It is not available on the dexterous hand.

HAND_GetUsageStat()

Method Signature：

def HAND_GetUsageStat(self, hand_id, total_use_time, total_open_times, motor_cnt, remote_err):

Purpose：

Retrieves usage statistics, reading the hand's total operating time and the individual power-on count for each motor.

Parameters：

Parameter	Description
`hand_id`	Device Address
`total_use_time`	Total Usage Time Output Parameter
`total_open_times`	Motor Total Power-On Count Array Output Parameter
`motor_cnt`	Motor Count Input Parameter
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Note: This feature is only available for the bionic hand. It is not available on the dexterous hand.

HAND_GetManufactureData()

Method Signature：

def HAND_GetManufactureData(self, hand_id, sub_model, hw_revision, serial_number, customer_tag, remote_err):

Purpose：

Retrieves manufacturing data, reading the hand's model, hardware version, serial number, customer tag, and other manufacturing information.
Parameters：

Parameter	Description
`hand_id`	Device Address
`sub_model`	Model Output Parameter
`hw_revision`	Hardware Version Output Parameter
`serial_number`	Serial Number Output Parameter
`customer_tag`	Customer Tag Output Paramet
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

sub_model, hw_revision, serial_number, customer_tag = [0], [0], [0], [0]

err, sub_model_get, hw_revision_get, serial_number_get, customer_tag_get = serial_api_instance.HAND_GetManufactureData(hand_id, sub_model, hw_revision, serial_number, customer_tag, [])

assert err == HAND_RESP_SUCCESS, f"manufacture_data_get: {err}\n"
logger.info(f"sub_model: {sub_model_get}, hw_revision: {hw_revision_get}, serial_number: {serial_number_get}, customer_tag: {customer_tag_get}")

HAND_Reset()

Method Signature：

def HAND_Reset(self, hand_id, mode, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`mode`	Reset Mode
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

mode = 0
err = serial_api_instance.HAND_Reset(hand_id, mode, [])
assert err == HAND_RESP_SUCCESS, f"HAND_Reset: {err}\n"
delay_milli_seconds_impl(25000)

HAND_PowerOff()

Method Signature：

def HAND_PowerOff(self, hand_id, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

err = api.HAND_PowerOff(hand_id, [])
assert err == HAND_RESP_SUCCESS, f"power_off_set: {err}\n"

Note: This feature is only available for the bionic hand. It is not available on the dexterous hand.

HAND_SetID()

Method Signature：

def HAND_SetID(self, hand_id, new_id, remote_err):

Parameters：

Parameter	Description
`hand_id`	Current Device Address
`new_id`	New Device Address
`remote_err`	Remote Error Code Storage

Return Value： Status: None on success
Failure: Return the corresponding error code
Usage Example:

new_id = 0x03
err = serial_api_instance.HAND_SetID(hand_id, new_id, [])
assert err == HAND_RESP_SUCCESS, f"id_set: {err}\n"
serial_api_instance.HAND_SetID(new_id, hand_id, [])

HAND_Calibrate()

Method Signature：

def HAND_Calibrate(self, hand_id, key, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`key`	Calibration Key
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Note: This feature is currently not publicly available. Please contact technical support if you need to use this function.

HAND_SetCaliData()

Method Signature：

def HAND_SetCaliData(self, hand_id, end_pos, start_pos, motor_cnt, thumb_root_pos, thumb_root_pos_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`end_pos`	End Position Array Input
`start_pos`	Start Position Array Input
`motor_cnt`	Motor Count
`thumb_root_pos`	Thumb Base Position Array Input
`thumb_root_pos_cnt`	Thumb Base Position Array Input
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Note: This feature is currently not publicly available. Please contact technical support if you need to use this function.

HAND_SetFingerPID()

Method Signature：

def HAND_SetFingerPID(self, hand_id, finger_id, p, i, d, g, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`p`	Proportional Parameter
`i`	Integral Parameter
`d`	Derivative Parameter
`g`	Gravity Compensation Parameter
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

for j in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  err = serial_api_instance.HAND_SetFingerPID(hand_id, j, pid_gains[j][0], pid_gains[j][1], pid_gains[j][2], pid_gains[j][3], remote_err)
  print(f"remote_err: {remote_err}")
  assert err == HAND_RESP_SUCCESS, f"finger: {j}, finger_pid_set: {err}\n"

HAND_SetFingerCurrentLimit()

Method Signature：

def HAND_SetFingerCurrentLimit(self, hand_id, finger_id, current_limit, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`current_limit`	Current Limit Value
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Note: This feature is currently not publicly available. Please contact technical support if you need to use this function.

HAND_SetFingerCurrentLimit()

Method Signature：

def HAND_SetFingerCurrentLimit(self, hand_id, finger_id, current_limit, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`pos_limit_low`	Position Lower Limit
`pos_limit_high`	Position Upper Limit
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

current_limit_set = 200
current_limit_get = [0]
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  err = serial_api_instance.HAND_SetFingerCurrentLimit(hand_id, i, current_limit_set, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, finger_current_limit_set: {err}\n"

HAND_FingerStart()

Method Signature：

def HAND_FingerStart(self, hand_id, finger_id, pos_limit_low, pos_limit_high, remote_err):

Purpose：

This function initiates motion for a specified single finger on the target robotic hand device and configures the positional movement limits.
Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`pos_limit_low`	Position Lower Limit
`pos_limit_high`	Position Upper Limit
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

finger_ids = [1, 2, 4, 6, 8, 10]
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  finger_id = finger_ids[i]
  err = serial_api_instance.HAND_FingerStart(hand_id, finger_id, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, test_finger_start_set: {err}\n"

HAND_FingerStop()

Method Signature：

def HAND_FingerStop(self, hand_id, finger_id_bits, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id_bits`	Finger Position Mask
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

finger_ids = [1, 2, 4, 6, 8, 10]
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  finger_id = finger_ids[i]
  err = serial_api_instance.HAND_FingerStop(hand_id, finger_id, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, test_finger_stop_set: {err}\n"

HAND_SetFingerPosAbs()

Method Signature：

def HAND_SetFingerPosAbs(self, hand_id, finger_id, raw_pos, speed, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`raw_pos`	Absolute Position Value
`speed`	Motion Velocity
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

pos_abs_set = 13000
speed = 100
target_pos, current_pos = [0], [0]
delay_milli_seconds_impl(set_delay_time)
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  err = serial_api_instance.HAND_SetFingerPosAbs(hand_id, i, pos_abs_set, speed, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, test_finger_pos_abs_set: {err}\n"

HAND_SetFingerPos()

Method Signature：

def HAND_SetFingerPos(self, hand_id, finger_id, pos, speed, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (range: 0-5)
`pos`	Target Position Value
`speed`	Motion Speed
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

pos_set = 32000
speed = 100
target_pos_get, current_pos_get = [0], [0]
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(finger_set_delay_time)
  err = serial_api_instance.HAND_SetFingerPos(hand_id, i, pos_set, speed, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, test_finger_pos_set: {err}\n"

HAND_SetFingerAngle()

Method Signature：

def HAND_SetFingerAngle(self, hand_id, finger_id, angle, speed, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (0-5)
`angle`	Target Position Value
`speed`	Motion Speed
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

four_finger_angle_set = 12000
thumb_angle_set = 3600
thumb_root_angle_set = 6000
target_angle, current_angle = [0], [0]
speed = 100
for i in range(MAX_MOTOR_CNT):
  delay_milli_seconds_impl(200)
  if(i >= 1 and i <= 4):
      err = serial_api_instance.HAND_SetFingerAngle(hand_id, i, four_finger_angle_set, speed, [])
  elif (i == 0):
      err = serial_api_instance.HAND_SetFingerAngle(hand_id, i, thumb_angle_set, speed, [])
  else:
      err = serial_api_instance.HAND_SetFingerAngle(hand_id, i, thumb_root_angle_set, speed, [])
  assert err == HAND_RESP_SUCCESS, f"finger: {i}, test_finger_angle_set: {err}\n"

HAND_SetThumbRootPos()

Method Signature：

def HAND_SetThumbRootPos(self, hand_id, pos, speed, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`pos`	Thumb Base Position Value
`speed`	Motion Speed
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

pos_set = 1
pos = [0]
speed = 100
raw_encoder = [0]
err = serial_api_instance.HAND_SetThumbRootPos(hand_id, pos_set, speed, [])
assert err == HAND_RESP_SUCCESS, f"test_thumb_root_pos_set: {err}\n"

HAND_SetFingerPosAbsAll()

Method Signature：

def HAND_SetFingerPosAbsAll(self, hand_id, raw_pos, speed, motor_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`raw_pos`	Position Value Array
`speed`	Velocity Value Array
`motor_cnt`	Motor Quantity
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

raw_pos_abs = [13000, 13000, 13000, 13000, 13000, 5000]
raw_speed = [100,100, 100, 100, 100, 100]
motor_cnt = MAX_MOTOR_CNT
raw_target_pos_abs, raw_current_pos_abs = [0] * MAX_MOTOR_CNT, [0] * MAX_MOTOR_CNT

err = serial_api_instance.HAND_SetFingerPosAbsAll(hand_id, raw_pos_abs, raw_speed, motor_cnt, [])
assert err == HAND_RESP_SUCCESS, f"test_finger_pos_abs_all_set: {err}\n"

HAND_SetFingerPosAll()

Method Signature：

def HAND_SetFingerPosAll(self, hand_id, pos, speed, motor_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`pos`	Position Value Array
`speed`	Velocity Value Array
`motor_cnt`	Motor Quantity
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

raw_pos = [18000, 33000, 33000, 33000, 33000, 38000]
raw_speed = [100, 100, 100, 100, 100, 100]
motor_cnt = MAX_MOTOR_CNT
raw_target_pos, raw_current_pos = [0] * MAX_MOTOR_CNT, [0] * MAX_MOTOR_CNT

err = serial_api_instance.HAND_SetFingerPosAll(hand_id, raw_pos, raw_speed, motor_cnt, [])
assert err == HAND_RESP_SUCCESS, f"test_finger_pos_all_set: {err}\n"

HAND_SetFingerAngleAll()

Method Signature：

def HAND_SetFingerAngleAll(self, hand_id, angle, speed, motor_cnt, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`angle`	Angle Value Array
`speed`	Velocity Value Array
`motor_cnt`	Motor Quantity
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

raw_angle = [2000,12000,12000,12000,12000,5000]
raw_speed = [100, 100, 100, 100, 100, 100]
motor_cnt = MAX_MOTOR_CNT
raw_target_angle, raw_current_angle = [0] * MAX_MOTOR_CNT, [0] * MAX_MOTOR_CNT

err = serial_api_instance.HAND_SetFingerAngleAll(hand_id, raw_angle, raw_speed, motor_cnt, [])
assert err == HAND_RESP_SUCCESS, f"test_finger_angle_all_set: {err}\n"

HAND_SetFingerStopParams()

Method Signature：

def HAND_SetFingerStopParams(self, hand_id, finger_id, speed, stop_current, stop_after_period, retry_interval, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (0-5)
`speed`	Motion Speed
`stop_current`	Stop Current Threshold
`stop_after_period`	Stop Detection Time Period
`retry_interval`	Retry Interval Time
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

speed = 16
stop_current = 200
stop_after_period = 300
retry_interval = 500
speed_get, stop_current_get, stop_after_period_get, retry_interval_get = [0], [0], [0], [0]

for i in range(MAX_MOTOR_CNT):
  err = serial_api_instance.HAND_SetFingerStopParams(hand_id, i, speed, stop_current, stop_after_period, retry_interval, [])
  assert err == HAND_RESP_SUCCESS, f"test_finger_stop_params_set: {err}\n"

HAND_SetFingerForcePID()

Method Signature：

def HAND_SetFingerForcePID(self, hand_id, finger_id, p, i, d, g, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`finger_id`	Finger ID (0-5)
`p`	Proportional Parameter
`i`	Integral Parameter
`d`	Derivative Parameter
`g`	Gravity Compensation Parameter
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

p, i, d, g = [0], [0], [0], [0]

for j in range(MAX_MOTOR_CNT - 1):
  delay_milli_seconds_impl(finger_set_delay_time)
  err = serial_api_instance.HAND_SetFingerForcePID(hand_id, j, force_pid[j][0], force_pid[j][1], force_pid[j][2], force_pid[j][3], [])
  assert err == HAND_RESP_SUCCESS, f"test_finger_force_pid_set: {err}\n"

HAND_ResetForce()

Method Signature：

def HAND_ResetForce(self, hand_id, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

err = serial_api_instance.HAND_ResetForce(hand_id, [])
assert err == HAND_RESP_SUCCESS, f"test_force_reset: {err}\n"

HAND_ResetForce()

Method Signature：

def HAND_ResetForce(self, hand_id, remote_err):

Purpose：

This function is used to send custom commands to the robotic hand device, supporting bidirectional data transmission. It provides a generic and extensible interface that enables users to transmit specific data and receive device responses, facilitating the implementation of non-standard or extended functionalities.

Parameters：

Parameter	Description
`hand_id`	Device Address
`data`	Data Buffer
`send_data_size`	Sent Data Size
`recv_data_size`	Received Data Size
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

err = serial_api_instance.HAND_ResetForce(hand_id, [])
assert err == HAND_RESP_SUCCESS, f"test_force_reset: {err}\n"

HAND_SetSelfTestLevel()

Method Signature：

def HAND_SetSelfTestLevel(self, hand_id, self_test_level, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`self_test_level`	Self-Test Level
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

self_test_level_set = 2
self_test_level = [0]

err = serial_api_instance.HAND_SetSelfTestLevel(hand_id, self_test_level_set, [])
assert err == HAND_RESP_SUCCESS, f"test_self_test_level: {err}\n"

HAND_SetBeepSwitch()

Method Signature：

    def HAND_SetBeepSwitch(self, hand_id, beep_on, remote_err):

Parameters：

Parameter	Description
`hand_id`	Device Address
`beep_on`	Buzzer Switch Status
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

beep_switch_set = 1
beep_switch = [0]

err = serial_api_instance.HAND_SetBeepSwitch(hand_id, beep_switch_set, [])
assert err == HAND_RESP_SUCCESS, f"test_beep_switch_set: {err}\n"

HAND_Beep()

Method Signature：

def HAND_Beep(self, hand_id, duration, remote_err):

Parameters：

Parameter Description

hand_id Device Address

duration Buzzer Duration

remote_err Remote Error Code Storage
Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

duration = 200
err = serial_api_instance.HAND_Beep(hand_id, duration, [])
assert err == HAND_RESP_SUCCESS, f"test_beep: {err}\n"

HAND_SetButtonPressedCnt()

Method Signature：

def HAND_SetButtonPressedCnt(self, hand_id, pressed_cnt, remote_err):

Purpose：

This function configures the button press counting mechanism of the robotic hand, allowing the user to set a trigger threshold for the number of button presses or reset the current count. It is commonly used to define how many button presses are required to activate a specific function or to reset the counter to its initial state.

Parameters：

Parameter Description

hand_id Device Address

pressed_cnt 按钮按下计数

remote_err Remote Error Code Storage
Return Value:
Status: None on success
Failure: Return the corresponding error code
Note: This feature is currently not publicly available. Please contact technical support if you need to use this function.

HAND_StartInit()

Method Signature：

def HAND_StartInit(self, hand_id, remote_err):

Parameters：

Parameter Description

hand_id Device Address

remote_err Remote Error Code Storage
Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

serial_api_instance.HAND_SetSelfTestLevel(hand_id, 0, [])
err = serial_api_instance.HAND_StartInit(hand_id, [])
assert err == HAND_RESP_SUCCESS, f"test_start_init: {err}\n"

HAND_SetManufactureData()

Method Signature：

def HAND_SetManufactureData(self, hand_id, key, sub_model, hw_revision, serial_number, customer_tag, remote_err):

Purpose：

This function configures the manufacturing data of the robotic hand, including critical information such as the product key, sub-model, hardware version, serial number, and customer tag. This data is typically used for device identification, authorization verification, and production traceability.

Parameters：

Parameter	Description
`hand_id`	Device Address
`key`	Product Key
`sub_model`	Submodel
`hw_revision`	Hardware Version
`serial_number`	Serial Number
`customer_tag`	Customer Tag
`remote_err`	Remote Error Code Storage

Return Value:
Status: None on success
Failure: Return the corresponding error code
Usage Example:

key = [0x88, 0x77]
sub_model = 1
hw_revision = 10
serial_number = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10]
customer_tag = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]

err = serial_api_instance.HAND_SetManufactureData(hand_id, key, sub_model, hw_revision, serial_number, customer_tag, [])
assert err == HAND_RESP_SUCCESS, f"manufacture_data_set : {err}\n"

Note: This feature is currently not publicly available. Please contact technical support if you need to use this function.

Parameter	Description
`get_milli_seconds_impl`	Gets the current time
`delay_milli_seconds_impl`	Delay Function

Parameter	Description
`hand_id`	Device Address
`duration`	Buzzer Duration
`remote_err`	Remote Error Code Storage