Enums & Core Data Structures

The ApexHand Python SDK uses a set of enums and structured types to represent hardware entities and parameters.
Knowing these types makes your code safer and more readable.

All of them are exported from the native _dexcelbot_sdk module and re‑exposed by dexcelbot_apexhand_sdk.py, so you can inspect them directly in Python.

Logging & connection

LogLevel

Logging level enum (documented here for completeness; in the current Python wrapper the level is fixed to INFO internally):

• LOG_LEVEL_DEBUG
• LOG_LEVEL_INFO
• LOG_LEVEL_WARN
• LOG_LEVEL_ERROR
• LOG_LEVEL_FATAL

set_log_path() always uses INFO internally; user code cannot change the log level.

ConnectionType

• CONNECTION_TYPE_RS485: RS485 serial connection
• CONNECTION_TYPE_ETHERNET: Ethernet connection

Used by DexcelBot.connect(address, connection_type).

Error codes

ErrorCode

All SDK functions that can fail return ErrorCode:

• ERROR_CODE_OK: success
• ERROR_CODE_COMM_ERROR: communication error
• ERROR_CODE_TIMEOUT: timeout
• ERROR_CODE_OUT_OF_RANGE: parameter out of allowed range
• ERROR_CODE_OTHER_ERROR: any other error

You should always check the return value for safety‑critical operations:

result = bot.move_joint(cmds)
if result != ErrorCode.ERROR_CODE_OK:
    print("move_joint failed:", result)

Hand structure enums

FingerId

Finger indices:

• FINGER_ID_THUMB
• FINGER_ID_INDEX
• FINGER_ID_MIDDLE
• FINGER_ID_RING
• FINGER_ID_PINKY

Used by:

• set_finger_enabled(fingers: List[FingerId])
• set_finger_disabled(fingers: List[FingerId])
• MaxFingerTorque.finger_id

MotorId

Motor indices (16 total), grouped by finger, e.g.:

• Thumb: MOTOR_ID_THUMB_CMC_0, MOTOR_ID_THUMB_CMC_1, MOTOR_ID_THUMB_CMC_2, MOTOR_ID_THUMB_MCP
• Index: MOTOR_ID_INDEX_MCP_0, MOTOR_ID_INDEX_MCP_1, MOTOR_ID_INDEX_PIP
• Middle: MOTOR_ID_MIDDLE_MCP_0, MOTOR_ID_MIDDLE_MCP_1, MOTOR_ID_MIDDLE_PIP
• Ring: MOTOR_ID_RING_MCP_0, MOTOR_ID_RING_MCP_1, MOTOR_ID_RING_PIP
• Pinky: MOTOR_ID_PINKY_MCP_0, MOTOR_ID_PINKY_MCP_1, MOTOR_ID_PINKY_PIP

Used by MotorState.motor_id.

JointId

Joint indices (21 total), such as:

• Thumb: JOINT_ID_THUMB_CMC_0, JOINT_ID_THUMB_CMC_1, JOINT_ID_THUMB_CMC_2, JOINT_ID_THUMB_MCP, JOINT_ID_THUMB_IP
• Index: JOINT_ID_INDEX_MCP_0, JOINT_ID_INDEX_MCP_1, JOINT_ID_INDEX_PIP, JOINT_ID_INDEX_DIP
• Middle: JOINT_ID_MIDDLE_MCP_0, JOINT_ID_MIDDLE_MCP_1, JOINT_ID_MIDDLE_PIP, JOINT_ID_MIDDLE_DIP
• Ring: JOINT_ID_RING_MCP_0, JOINT_ID_RING_MCP_1, JOINT_ID_RING_PIP, JOINT_ID_RING_DIP
• Pinky: JOINT_ID_PINKY_MCP_0, JOINT_ID_PINKY_MCP_1, JOINT_ID_PINKY_PIP, JOINT_ID_PINKY_DIP

Used by:

• JointState.joint_id
• JointControlParam.joint_id
• MoveJPositionFollowParam.id
• MaxJointSpeed.joint_id
• MaxJointAccel.joint_id

Version & parameter information

VersionInfo

• touch_sensor_version: touch sensor firmware version
• hand_firmware_version: hand firmware version
• sdk_version: SDK library version

Returned by get_version_info():

info = bot.get_version_info()
print(info.touch_sensor_version, info.hand_firmware_version, info.sdk_version)

ParamInfo

• max_speed: List[float]: per‑joint max speed (rad/s)
• max_accel: List[float]: per‑joint max acceleration (rad/s²)
• max_current: List[float]: per‑finger max current/torque (%)

Returned by get_parameters().

Joint state and control structures

JointState & JointStates

JointState:

• joint_id: JointId
• position: float (rad)
• velocity: float (rad/s)
• acceleration: float (rad/s²)

JointStates:

• timestamp
• joint_states: List[JointState]

Used by get_joint_states() and joint state callbacks:

def on_joint_states(states):
    print("timestamp:", states.timestamp)
    for js in states.joint_states:
        print(js.joint_id, js.position)

bot.register_joint_states_callback(on_joint_states, freq_hz=100)

JointControlParam

• joint_id: JointId
• position: float target position (rad)
• velocity: float target velocity (rad/s)
• acceleration: float target acceleration (rad/s²)

Best created with the helper:

from dexcelbot_apexhand_sdk import JointId, create_joint_control_param

cmd = create_joint_control_param(
    joint_id=JointId.JOINT_ID_THUMB_MCP,
    position=0.5,
    velocity=0.2,
    acceleration=0.0,
)

MoveJPositionFollowParam

For follow control:

• id: JointId
• position: float target position (rad)

Used with move_j_position_follow() for smooth trajectories.

Motor state & safety limits

MotorState & MotorStates

MotorState:

• motor_id: MotorId
• temperature: float
• current: float

MotorStates:

• timestamp
• motors: List[MotorState]

Returned by get_motor_states() and used in motor state callbacks.

MaxJointSpeed

• joint_id: JointId
• speed: float max speed (rad/s)

from dexcelbot_apexhand_sdk import MaxJointSpeed, JointId

limits = []
for jid in JointId:
    s = MaxJointSpeed()
    s.joint_id = jid
    s.speed = 1.0
    limits.append(s)

bot.set_max_joint_speed(limits)

MaxJointAccel

• joint_id: JointId
• accel: float max acceleration (rad/s²)

Configured via set_max_joint_accel() in the same pattern as MaxJointSpeed.

MaxFingerTorque

• finger_id: FingerId
• torque: float max torque (0–100%)

from dexcelbot_apexhand_sdk import MaxFingerTorque, FingerId

torques = []
for fid in FingerId:
    t = MaxFingerTorque()
    t.finger_id = fid
    t.torque = 80.0  # limit to 80%
    torques.append(t)

bot.set_max_finger_torque(torques)

With these enums and structures in mind, you will find the motion, sensing and callback APIs in the next sections much easier to read and use.