Error Handling & Event Callbacks
Use ApexHand error codes, hardware error callbacks and logging for robust applications.
This page focuses on error handling and diagnostics:
- Hardware error checks:
get_hardware_error_code - Hardware error event callback:
register_hardware_error_event_callback - Logging configuration and recommended recovery flow
Hardware error code — get_hardware_error_code
check_hw_error_en.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
# ... connect ...
code = bot.get_hardware_error_code()
if code == ErrorCode.ERROR_CODE_OK:
print("No hardware error")
elif code == ErrorCode.ERROR_CODE_OTHER_ERROR:
print("Hardware error detected, check callbacks or logs for details")
else:
print("get_hardware_error_code failed with:", code)
ERROR_CODE_OK: no hardware error.ERROR_CODE_OTHER_ERROR: some hardware error is present; inspect error callbacks and logs for details.
Hardware error event callback
Register / unregister
hw_error_callback_en.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
HardwareErrorCodes,
ErrorCode,
)
bot = DexcelBot()
# ... connect ...
def on_hardware_error(err: HardwareErrorCodes):
# Structure fields are defined by the native SDK
print("Device error code:", err.device_error)
print("Finger error codes:", err.finger_errors)
result = bot.register_hardware_error_event_callback(on_hardware_error)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError("Failed to register hardware error callback")
# ... run task ...
bot.unregister_hardware_error_event_callback()
When the firmware detects hardware issues (over‑current, sensor faults, etc.), the SDK invokes this callback with a HardwareErrorCodes structure.
To explore the available fields, use
help(HardwareErrorCodes)ordir(HardwareErrorCodes())in a Python REPL.
Combining error and state callbacks
A common pattern is to:
- Use motor state callbacks for “soft” monitoring (temperature, current).
- Use hardware error callbacks for firmware‑level faults.
safe_monitor_en.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
MotorStates,
HardwareErrorCodes,
ErrorCode,
)
bot = DexcelBot()
# ... connect ...
def on_motor_states(states: MotorStates):
for m in states.motors:
if m.temperature > 70.0:
print("[Soft monitor] Motor overheating:", m.motor_id, m.temperature)
def on_hardware_error(err: HardwareErrorCodes):
print("[Firmware error] Device code:", err.device_error)
print("[Firmware error] Finger codes:", err.finger_errors)
bot.register_motor_states_callback(on_motor_states, freq_hz=20)
bot.register_hardware_error_event_callback(on_hardware_error)
# ... run task ...
bot.unregister_motor_states_callback()
bot.unregister_hardware_error_event_callback()
Logging configuration
Log path
log_path_en.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
result = bot.set_log_path("./logs")
if result != ErrorCode.ERROR_CODE_OK:
print("Failed to set log path:", result)
else:
print("SDK logs will be written to ./logs")
Notes:
- The Python wrapper uses a fixed INFO log level internally.
- For debugging hardware issues, always configure a dedicated log directory.
Enable / disable logging
enable_logging_en.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
bot.enable_logging(True) # enable logging
# ... run task ...
bot.enable_logging(False) # disable when no longer needed
Recommended recovery flow
When an error is detected:
- Stop sending new motion commands (
move_joint, servo callbacks, etc.). - Call
get_hardware_error_code()to confirm the error state. - Depending on the error:
- Call
clean_faults()to try clearing the fault. - Optionally lower speed / torque limits and retry cautiously.
- Call
- If the error persists:
- Preserve log files and configuration.
- Share error codes and logs with Dexcel support.
recover_en.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
code = bot.get_hardware_error_code()
if code == ErrorCode.ERROR_CODE_OTHER_ERROR:
print("Hardware error detected, trying to clear...")
clr = bot.clean_faults()
if clr == ErrorCode.ERROR_CODE_OK:
print("Fault cleared. You can re‑apply conservative limits and retry if appropriate.")
else:
print("Failed to clear fault. Stop usage and export logs for analysis.")
With the mechanisms above you can build a robust safety and diagnostics layer around your ApexHand applications.