State Reading & Tactile Images

Learn how to read joint and motor states and access tactile images in ApexHand.

This page covers the sensing side of the SDK:

Joint states: get_joint_states and callbacks
Motor states: get_motor_states and callbacks
Tactile images: get_hand_sensor_image and callbacks
The HandSensorImage hierarchy

Joint states — `JointStates`

Single read

read_joint_states_en.py

from dexcelbot_apexhand_sdk import DexcelBot

bot = DexcelBot()
# ... connect ...

states = bot.get_joint_states()
print("timestamp:", states.timestamp)

for js in states.joint_states:
    print(js.joint_id, js.position, js.velocity, js.acceleration)

JointStates contains:

timestamp
joint_states: List[JointState]

Continuous callback

joint_states_callback_en.py

from dexcelbot_apexhand_sdk import DexcelBot, JointStates, ErrorCode

bot = DexcelBot()
# ... connect ...

def on_joint_states(states: JointStates):
    subset = states.joint_states[:3]
    for js in subset:
        print("[Joint]", js.joint_id, "pos =", js.position)

result = bot.register_joint_states_callback(on_joint_states, freq_hz=100)
if result != ErrorCode.ERROR_CODE_OK:
    raise RuntimeError("Failed to register joint states callback")

# ... later ...
bot.unregister_joint_states_callback()

Motor states — `MotorStates`

Single read

read_motor_states_en.py

from dexcelbot_apexhand_sdk import DexcelBot

bot = DexcelBot()
# ... connect ...

motors = bot.get_motor_states()
print("timestamp:", motors.timestamp)

for ms in motors.motors:
    print("[Motor]", ms.motor_id, "T =", ms.temperature, "I =", ms.current)

Continuous callback

motor_states_callback_en.py

from dexcelbot_apexhand_sdk import DexcelBot, MotorStates, ErrorCode

bot = DexcelBot()
# ... connect ...

def on_motor_states(states: MotorStates):
    overheat = [m for m in states.motors if m.temperature > 60.0]
    if overheat:
        print("Warning: overheating motors:", [m.motor_id for m in overheat])

result = bot.register_motor_states_callback(on_motor_states, freq_hz=50)
if result != ErrorCode.ERROR_CODE_OK:
    raise RuntimeError("Failed to register motor states callback")

# ... later ...
bot.unregister_motor_states_callback()

Motor state callbacks are useful for simple thermal / current monitoring and protective actions (e.g. slow down or stop).

Tactile images — `HandSensorImage`

The tactile subsystem exposes a hierarchy of structures:

TactileImage:
- width, height
- gray_image: List[int]
- tangential_forces: TangentialForce
CommonFingerSensorImage / ThumbFingerSensorImage:
- multiple TactileImage surfaces such as pip_image, dip_image, tip_image
HandSensorImage:
- timestamp
- index_image, middle_image, ring_image, pinky_image
- thumb_image
- palm_image

Single read

read_tactile_en.py

from dexcelbot_apexhand_sdk import DexcelBot

bot = DexcelBot()
# ... connect ...

img = bot.get_hand_sensor_image()

print("timestamp:", img.timestamp)
print("Index PIP size:", img.index_image.pip_image.width, "x", img.index_image.pip_image.height)
print("Palm size:", img.palm_image.width, "x", img.palm_image.height)

You can convert gray_image to a NumPy array and visualize or process it using Matplotlib or OpenCV.

Continuous callback

tactile_callback_en.py

from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode

bot = DexcelBot()
# ... connect ...

def on_hand_image(img):
    tip = img.thumb_image.tip_image
    if tip.width * tip.height == 0:
        return
    avg_gray = sum(tip.gray_image) / (tip.width * tip.height)
    print("Thumb tip avg gray:", avg_gray)

result = bot.register_hand_sensor_image_callback(on_hand_image, freq_hz=30)
if result != ErrorCode.ERROR_CODE_OK:
    raise RuntimeError("Failed to register tactile callback")

# ... later ...
bot.unregister_hand_sensor_image_callback()

Typical monitoring setup

In practice you can combine callbacks to build a simple monitoring layer:

monitor_all_en.py

from dexcelbot_apexhand_sdk import (
    DexcelBot,
    JointStates,
    MotorStates,
    ErrorCode,
)

bot = DexcelBot()
# ... connect ...

def on_joint_states(states: JointStates):
    if states.joint_states:
        js = states.joint_states[0]
        print("[Joint]", js.joint_id, "pos =", js.position)

def on_motor_states(states: MotorStates):
    for m in states.motors:
        if m.temperature > 65.0:
            print("!!! Motor overheat:", m.motor_id, m.temperature)

def on_hand_image(img):
    palm = img.palm_image
    if palm.width * palm.height == 0:
        return
    avg_gray = sum(palm.gray_image) / (palm.width * palm.height)
    if avg_gray > 10:
        print("Palm contact detected, avg gray =", avg_gray)

bot.register_joint_states_callback(on_joint_states, freq_hz=100)
bot.register_motor_states_callback(on_motor_states, freq_hz=20)
bot.register_hand_sensor_image_callback(on_hand_image, freq_hz=15)

# ... run your task ...

bot.unregister_joint_states_callback()
bot.unregister_motor_states_callback()
bot.unregister_hand_sensor_image_callback()

With this in place you have full access to kinematic and tactile feedback, which you can then feed into higher‑level control or learning algorithms.

Motion Control APIs in Detail

A deeper look at ApexHand motion control, follow control and safety limits.

Error Handling & Event Callbacks

Use ApexHand error codes, hardware error callbacks and logging for robust applications.