Basic Usage (Connection, Control & State)
This section walks through the full basic workflow: connect, enable fingers, send motion commands, and read states, with suggested error‑handling patterns.
1. Create an instance and connect
from dexcelbot_apexhand_sdk import (
DexcelBot,
ConnectionType,
ErrorCode,
)
bot = DexcelBot()
# Connect over Ethernet
address = "192.168.0.102" # Replace with your hand's IP or serial address
result = bot.connect(address, ConnectionType.CONNECTION_TYPE_ETHERNET)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError(f"Failed to connect, error code: {result}")
print("Connected:", bot.is_connected())
Supported connection types:
- Ethernet:
ConnectionType.CONNECTION_TYPE_ETHERNET - RS485:
ConnectionType.CONNECTION_TYPE_RS485
2. Enable / disable fingers
from dexcelbot_apexhand_sdk import DexcelBot, FingerId
bot = DexcelBot()
# ... call connect() first ...
# Enable all fingers
bot.set_all_fingers_enabled()
# Enable only index and middle
bot.set_finger_enabled([
FingerId.FINGER_ID_INDEX,
FingerId.FINGER_ID_MIDDLE,
])
# Disable ring and pinky
bot.set_finger_disabled([
FingerId.FINGER_ID_RING,
FingerId.FINGER_ID_PINKY,
])
# Disable all fingers
bot.set_all_fingers_disabled()
If the hand enters a fault state, you can clear it via:
bot.clean_faults()
3. Joint position control with move_joint
move_joint is blocking: the call returns only after the hand reaches the target or an error occurs.
The easiest way to build commands is via create_joint_control_param:
from dexcelbot_apexhand_sdk import (
DexcelBot,
JointId,
create_joint_control_param,
ErrorCode,
)
bot = DexcelBot()
# ... connect + enable fingers ...
# Example: move thumb MCP and index PIP together
cmds = [
create_joint_control_param(
joint_id=JointId.JOINT_ID_THUMB_MCP,
position=0.5, # rad
velocity=0.2, # rad/s
acceleration=0.0,
),
create_joint_control_param(
joint_id=JointId.JOINT_ID_INDEX_PIP,
position=0.8,
velocity=0.3,
acceleration=0.0,
),
]
result = bot.move_joint(cmds)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError(f"move_joint failed: {result}")
4. Follow control with move_j_position_follow
move_j_position_follow is designed for streaming target positions at an irregular rate; the SDK interpolates between consecutive targets internally.
import time
from dexcelbot_apexhand_sdk import (
DexcelBot,
JointId,
create_move_j_position_follow_param,
)
bot = DexcelBot()
# ... connect + enable fingers ...
for i in range(50):
position = 0.2 + 0.3 * (i / 49) # Sweep from 0.2 to 0.5 rad
params = [
create_move_j_position_follow_param(
joint_id=JointId.JOINT_ID_INDEX_MCP_0,
position=position,
)
]
bot.move_j_position_follow(params)
time.sleep(0.02) # Non‑fixed send period
5. Read joint and motor states
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# ... already connected ...
joint_states = bot.get_joint_states()
print("Joint timestamp:", joint_states.timestamp)
for js in joint_states.joint_states:
print(js.joint_id, js.position, js.velocity, js.acceleration)
motor_states = bot.get_motor_states()
print("Motor timestamp:", motor_states.timestamp)
for ms in motor_states.motors:
print(ms.motor_id, ms.temperature, ms.current)
6. Cleanup and disconnect
Always disable and disconnect before your program exits:
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# ... after you finish control ...
bot.set_all_fingers_disabled()
bot.disconnect()
print("Disconnected from ApexHand")
Once you are comfortable with these basics, move on to Motion Control API for safety limits and servo control, and State & Tactile Sensing for continuous feedback and tactile images.