Skip to main content

​
Build

Artifacts:
  • Linux: target/release/libmotor_abi.so, libmotor_abi.a
  • Windows: target/release/motor_abi.dll, motor_abi.lib
  • Header: motor_abi/include/motor_abi.h

​
Unified Surface

The ABI keeps one unified control surface across vendors.

​
ABI Metadata

  • motor_abi_version() returns the loaded ABI library version string.
  • motor_abi_capabilities_json() returns a stable JSON capability document for supported transports, vendors, lifecycle operations, control modes, and vendor-specific features.
  • Python exposes the same information through motorbridge.abi_version() and motorbridge.abi_capabilities().
  • C++ exposes the same information through motorbridge::abi_version() and motorbridge::abi_capabilities_json().
  • Binding parity is tracked in bindings/api_surface.json.
Unified mode IDs (motor_handle_ensure_mode):
  • 1 = MIT
  • 2 = POS_VEL
  • 3 = VEL
  • 4 = FORCE_POS
Unified control units:
  • position: rad
  • velocity: rad/s
  • torque: Nm
Common control/state APIs:
  • motor_handle_enable
  • motor_handle_disable
  • motor_handle_clear_error
  • motor_handle_set_zero_position
  • motor_handle_ensure_mode
  • motor_handle_send_mit
  • motor_handle_send_pos_vel
  • motor_handle_send_vel
  • motor_handle_send_force_pos
  • motor_handle_request_feedback
  • motor_handle_set_can_timeout_ms
  • motor_handle_store_parameters
  • motor_handle_get_state

​
Vendor Entry Points

  • Damiao: motor_controller_add_damiao_motor(...)
  • Hexfellow: motor_controller_add_hexfellow_motor(...) (CAN-FD path via socketcanfd)
  • RobStride: motor_controller_add_robstride_motor(...)
  • MyActuator: motor_controller_add_myactuator_motor(...)
  • HighTorque: motor_controller_add_hightorque_motor(...)

​
ABI Metadata

The ABI exposes metadata entrypoints so tools, gateways, and language bindings can discover the loaded ABI version and supported transports/vendors/features:
  • motor_abi_version() — returns the loaded ABI version string.
  • motor_abi_capabilities_json() — returns a JSON string describing supported transports, vendors, modes, and ops.
These mirror the Python helpers motorbridge.abi_version() / motorbridge.abi_capabilities() and the C++ helpers motorbridge::abi_version() / motorbridge::abi_capabilities_json(). The canonical binding/API surface list is bindings/api_surface.json, used to keep ABI, Python, C++, and documentation aligned.

​
Unified Mode to Native Protocol Mapping

Behavior rule:
  • Unsupported calls return non-zero and a readable message via motor_last_error_message().
  • Signatures stay stable even when a vendor ignores part of a signature.
  • Example: HighTorque accepts send_mit(pos, vel, kp, kd, tau) for interface consistency, but native protocol does not use kp/kd.
  • Hexfellow ABI path supports MIT and POS_VEL, and reports VEL / FORCE_POS as unsupported.
  • RobStride supports MIT / POS_VEL / VEL on unified APIs; torque/current remains parameter-level (robstride_write_param_*), not a unified mode.
  • Damiao set-zero sequence rule: call motor_handle_disable before motor_handle_set_zero_position; otherwise set-zero is rejected by core guard.
  • Damiao set-zero settle rule: core applies an internal fixed settle (~20ms) after successful set_zero_position (no extra ABI parameter).

​
Vendor-Specific Extensions

Damiao register APIs:
  • motor_handle_write_register_f32
  • motor_handle_write_register_u32
  • motor_handle_get_register_f32
  • motor_handle_get_register_u32
RobStride extensions:
  • motor_handle_robstride_ping
  • motor_handle_robstride_set_device_id
  • motor_handle_robstride_write_param_i8/u8/u16/u32/f32
  • motor_handle_robstride_get_param_i8/u8/u16/u32/f32
  • motor_handle_robstride_send_pos_vel_pp (PP sequence)
  • motor_handle_robstride_send_pos_vel_csp (CSP sequence)

​
Typical Call Flow

  1. Transport constructor:
    • motor_controller_new_socketcan(channel) (general path)
    • motor_controller_new_dm_serial(serial_port, baud) (Damiao-only serial bridge; cross-platform, e.g. /dev/ttyACM0 or COM3)
    • motor_controller_new_dm_device(dm_device_type, dm_channel) (Damiao-only, DM_Device SDK: USB2CANFD / USB2CANFD_DUAL / LINKX4C)
  2. motor_controller_add_<vendor>_motor
  3. optional: motor_controller_enable_all
  4. optional: motor_handle_ensure_mode
  5. send control commands / read state / vendor-specific operations
  6. motor_controller_shutdown
  7. motor_handle_free
  8. motor_controller_free

​
Examples

  • C ABI demo: examples/c/c_abi_demo.c
  • C++ ABI demo: examples/cpp/cpp_abi_demo.cpp
  • Python ctypes demo: examples/python/python_ctypes_demo.py