Motion Controller API

Getting Started

Software Release Version: 0.0.6

To launch the Adeeb Robotics Controller, open a terminal and execute:

adeeb_robotics_controller <path_to_config_file>

The config_files folder contains example configuration files. For example:

adeeb_robotics_controller config_file/delta_config.yml

Next, open a separate terminal and run the desired Python motion script:

python3 <path_to_python_script>

Example motion scripts are available in the python_scripts folder. For instance:

python3 pack_expo_demo.py

Script and Configuration Pairing

• pack_expo_demo.py and autorun.py should be used with delta_config.yml or demo_stand_config.yml
• serial_dh_example.py is intended to be used with kuka_7_axis_config.yml

Configuration files define system settings including the robot type and workspace layout (conveyor and container positions for pick-and-place operations). The Python scripts handle motion control and I/O operations.

System Information

API Route	Method	Description	Payload
/get_sw_release_version	GET	Returns the current software release version	String

Configuration

API Route	Method	Description	Payload
/set_config	POST	Sets the configuration object in JSON format	Config
/get_config	GET	Returns the current configuration in JSON format	N/A

Network and Initialization

Network Control

API Route	Method	Description	Payload
/init_network	POST	Initiates network initialization request	N/A
/init_network	GET	Checks network initialization response	CmdRspRslt

Axis Initialization

API Route	Method	Description	Payload
/init_axes	POST	Initiates axes initialization request	N/A
/init_axes	GET	Checks axes initialization response	CmdRspRslt

Operation Mode Control

API Route	Method	Description	Payload
/req_preop	POST	Initiates pre-operational mode request	N/A
/req_preop	GET	Checks pre-operational mode response	CmdRspRslt
/req_op	POST	Initiates operational mode request	N/A
/req_op	GET	Checks operational mode response	CmdRspRslt

Slave Management

API Route	Method	Description	Payload
/get_number_of_slaves	POST	Initiates slave count request	N/A
/get_number_of_slaves	GET	Checks slave count response	NumSlvsEcatData

Motion Control

All endpoints that have POST/GET pairs follow an asynchronous pattern where the operation is initiated with the POST endpoint and its completion can be checked with the GET endpoint.

Axis Control

API Route	Method	Description	Payload
/axis_servo_on	POST	Initiates servo on request	AxisData
/axis_servo_on	GET	Checks servo on response	AxisData
/axis_servo_off	POST	Initiates servo off request	AxisData
/axis_servo_off	GET	Checks servo off response	AxisData
/axis_move_pos	POST	Initiates absolute position movement request	AxisMovePosData
/axis_move_pos	GET	Checks absolute position movement response	AxisMovePosData
/axis_move_vel	POST	Initiates velocity movement request	AxisMoveVelData
/axis_move_vel	GET	Checks velocity movement response	AxisMoveVelData
/axis_move_rel	POST	Initiates relative position movement request	AxisMoveRelData
/axis_move_rel	GET	Checks relative position movement response	AxisMoveRelData
/axis_move_home	POST	Initiates axis home movement request	AxisData
/axis_move_home	GET	Checks axis home movement response	AxisData
/axis_get_curr_pos	POST	Initiates getting current position request	AxisCurrPosData
/axis_get_curr_pos	GET	Checks getting current position response	AxisCurrPosData
/axis_write_dig_out	POST	Append a digital write command to the axis motion queue	AxisDigData
/axis_write_dig_out	GET	Checks if a digital write command was appended	AxisDigData
/axis_read_dig_in	POST	Initiates an immediate (not queued) digital read request	AxisDigData
/axis_read_dig_in	GET	Checks digital read response	AxisDigData
/axis_motion_done	POST	Initiates axis motion done request	AxisBoolData
/axis_motion_done	GET	Checks axis motion done response	AxisBoolData
/axis_quick_stop	POST	Initiates axis quick stop request	AxisData
/axis_quick_stop	GET	Checks axis quick stop response	AxisData
/axis_clear_alarms	POST	Initiates axis clear alarms request	AxisData
/axis_clear_alarms	GET	Checks axis clear alarms response	AxisData
/axis_get_alarms	POST	Initiates getting axis alarms request	AxisAlarmsData
/axis_get_alarms	GET	Checks getting axis alarms response	AxisAlarmsData
/axis_zero	POST	Initiates axis zero request	AxisData
/axis_zero	GET	Checks axis zero response	AxisData
/axis_sleep	POST	Initiates axis sleep request	AxisSleepData
/axis_sleep	GET	Checks axis sleep response	AxisSleepData
/axis_set_spd_prcn	POST	Initiates setting axis speed request	AxisSpdPrcnData
/axis_set_spd_prcn	GET	Get setting axis speed response	AxisSpdPrcnData
/axis_get_spd_prcn	POST	Initiates getting axis speed request	AxisSpdPrcnData
/axis_get_spd_prcn	GET	Checks getting axis speed response	AxisSpdPrcnData

Group Control

API Route	Method	Description	Payload
/group_servo_on	POST	Initiates group servo on request	GroupData
/group_servo_on	GET	Checks group servo on response	GroupData
/group_servo_off	POST	Initiates group servo off request	GroupData
/group_servo_off	GET	Checks group servo off response	GroupData
/group_move_pos	POST	Initiates group absolute position movement request	GroupMovePosData
/group_move_pos	GET	Checks group absolute position movement response	GroupMovePosData
/group_move_rel	POST	Initiates group relative position movement request	GroupMoveRelData
/group_move_rel	GET	Checks group relative position movement response	GroupMoveRelData
/group_move_home	POST	Initiates group home movement request	GroupData
/group_move_home	GET	Checks group home movement response	GroupData
/group_end_eff_engage	POST	Initiates group end effector engagement request	GroupData
/group_end_eff_engage	GET	Checks group end effector engagement response	GroupData
/group_end_eff_eject	POST	Initiates group end effector eject request	GroupData
/group_end_eff_eject	GET	Checks group end effector eject response	GroupData
/group_end_eff_clear	POST	Initiates group end effector clear request	GroupData
/group_end_eff_clear	GET	Checks group end effector clear response	GroupData
/group_get_bgn_pos	POST	Initiates next motion queue begin position request	GroupBgnPosData
/group_get_bgn_pos	GET	Checks next motion queue begin position response	GroupBgnPosData
/group_get_curr_pos	POST	Initiates getting group current position request	GroupCurrPosData
/group_get_curr_pos	GET	Checks getting group current position response	GroupCurrPosData
/group_write_dig_out	POST	Append a digital write command to the group motion queue	GroupDigData
/group_write_dig_out	GET	Checks if a digital write command was appended	GroupDigData
/group_motion_done	POST	Initiates group motion completion request	GroupBoolData
/group_motion_done	GET	Checks group motion completion response	GroupBoolData
/group_quick_stop	POST	Initiates group quick stop request	GroupData
/group_quick_stop	GET	Checks group quick stop response	GroupData
/group_clear_alarms	POST	Initiates group clear alarms request	GroupData
/group_clear_alarms	GET	Checks group clear alarms response	GroupData
/group_get_alarms	POST	Initiates group get alarms request	GroupAlarmsData
/group_get_alarms	GET	Checks group get alarms response	GroupAlarmsData
/group_zero	POST	Initiates group zero request	GroupData
/group_zero	GET	Checks group zero response	GroupData
/group_sleep	POST	Initiates group sleep request	GroupSleepData
/group_sleep	GET	Checks group sleep response	GroupSleepData
/group_set_spd_prcn	POST	Initiates setting group move profile velocity, acceleration, and jerk as % of max	GroupSpdPrcnData
/group_set_spd_prcn	GET	Checks setting group move profile response	GroupSpdPrcnData
/group_get_spd_prcn	POST	Initiates getting group move profile velocity, acceleration, and jerk as % of max	GroupSpdPrcnData
/group_get_spd_prcn	GET	Checks getting group move profile response	GroupSpdPrcnData
/clear_alarms	POST	Initiates clear all alarms request	MotnCmdData
/clear_alarms	GET	Checks clear all alarms response	MotnCmdData
/emergency_stop	POST	Initiates emergency stop request	MotnCmdData
/emergency_stop	GET	Checks emergency stop response	MotnCmdData

Conveyor Operations

API Route	Method	Description	Payload
/conv_set_spd	POST	Initiates setting conveyor speed request	ConvSpdData
/conv_set_spd	GET	Checks setting conveyor speed response	ConvSpdData
/group_conv_intercept_pickup	POST	Initiates conveyor intercept for pick-up request	GroupConvPickupData
/group_conv_intercept_pickup	GET	Checks conveyor intercept for pick-up response	GroupConvPickupData
/group_conv_intercept_dropoff	POST	Initiates conveyor intercept for drop-off request	GroupConvDropoffData
/group_conv_intercept_dropoff	GET	Checks conveyor intercept for drop-off response	GroupConvDropoffData
/group_conv_descend	POST	Initiates conveyor descend request	GroupConvData
/group_conv_descend	GET	Checks conveyor descend response	GroupConvData
/group_conv_track_pickup	POST	Initiates tracking conveyor pick-up request	GroupConvData
/group_conv_track_pickup	GET	Checks tracking conveyor pick-up response	GroupConvData
/group_conv_track_dropoff	POST	Initiates tracking conveyor drop-off request	GroupConvData
/group_conv_track_dropoff	GET	Checks tracking conveyor drop-off response	GroupConvData
/group_conv_ascend	POST	Initiates conveyor ascend request	GroupConvData
/group_conv_ascend	GET	Checks conveyor ascend response	GroupConvData
/group_conv_pickup	POST	Initiates group conveyor pickup request	GroupConvPickupData
/group_conv_pickup	GET	Checks group conveyor pickup response	GroupConvPickupData
/group_conv_dropoff	POST	Initiates group conveyor drop-off request	GroupConvDropoffData
/group_conv_dropoff	GET	Checks group conveyor drop-off response	GroupConvDropoffData

Container Operations

API Route	Method	Description	Payload
/group_cont_intercept_dropoff	POST	Initiates container intercept at drop-off request	GroupContDropoffData
/group_cont_intercept_dropoff	GET	Checks container intercept at drop-off response	GroupContDropoffData
/group_cont_intercept_pickup	POST	Initiates container intercept at pick-up request	GroupContPickupData
/group_cont_intercept_pickup	GET	Checks container intercept at pick-up response	GroupContPickupData
/group_cont_intercept_pickup_idx	POST	Initiates queuing a group move to position above indexed part in container	GroupContPickupIdxData
/group_cont_intercept_pickup_idx	GET	Checks response of queuing group move above indexed part	GroupContPickupIdxData
/group_cont_descend	POST	Initiates container descend request	GroupContData
/group_cont_descend	GET	Checks container descend response	GroupContData
/group_cont_track_dropoff	POST	Initiates tracking container drop-off request	GroupContData
/group_cont_track_dropoff	GET	Checks tracking container drop-off response	GroupContData
/group_cont_track_pickup	POST	Initiates tracking container pick-up request	GroupContData
/group_cont_track_pickup	GET	Checks tracking container pick-up response	GroupContData
/group_cont_ascend	POST	Initiates container ascend request	GroupContData
/group_cont_ascend	GET	Checks container ascend response	GroupContData
/group_cont_dropoff	POST	Initiates container drop-off request	GroupContDropoffData
/group_cont_dropoff	GET	Checks container drop-off response	GroupContDropoffData
/group_cont_pickup	POST	Initiates container pick-up request	GroupContPickupData
/group_cont_pickup	GET	Checks container pick-up response	GroupContPickupData
/group_cont_pickup_idx	POST	Initiates container part pick-up using auto part indexing	GroupContPickupIdxData
/group_cont_pickup_idx	GET	Checks container part pick-up using auto indexing response	GroupContPickupIdxData
/cont_set_empty	POST	Initiates setting internal container part count to zero	ContData
/cont_set_empty	GET	Checks setting container part count to zero response	ContData
/cont_set_full	POST	Initiates setting internal container part count to full	ContPartData
/cont_set_full	GET	Checks setting container part count to full response	ContPartData
/cont_not_empty	POST	Initiates checking container is not empty	ContBoolData
/cont_not_empty	GET	Checks container is not empty response	ContBoolData
/cont_not_full	POST	Initiates checking container is not full	ContPartBoolData
/cont_not_full	GET	Checks container is not full response	ContPartBoolData

Low-Level Control

CoE (CANopen over EtherCAT) Operations

API Route	Method	Description	Payload
/coe_wr_u8	POST/GET	U8 write operation	CoeU8Data
/coe_wr_u16	POST/GET	U16 write operation	CoeU16Data
/coe_wr_u32	POST/GET	U32 write operation	CoeU32Data
/coe_rd_u8	POST/GET	U8 read operation	CoeU8Data
/coe_rd_u16	POST/GET	U16 read operation	CoeU16Data
/coe_rd_u32	POST/GET	U32 read operation	CoeU32Data

CiA 402 Operations

API Route	Method	Description	Payload
/set_cia402_op_mode	POST	Initiates CiA 402 operation mode setting request	Cia402OpModeData
/set_cia402_op_mode	GET	Checks CiA 402 operation mode setting response	Cia402OpModeData

Configuration File Reference

Ethernet

Field	Type	Description
interface_name	String	Ethernet interface name
prioritize_usr_space_eth_drv	Boolean	If true, prioritize obtaining slave configuration from ESI file; otherwise use slave EEPROM SSI data

EtherCAT

Field	Type	Description	Unit
esi_file_path	String	ESI file path	N/A
prioritize_esi_config	Boolean	Prioritize ESI file over slave EEPROM SSI data	N/A
cycle_time	u32	EtherCAT cycle time, only multiples of 250μs supported	μs
shift_time	u32	DC master frame send to sync0 offset	% of cycle_time
rx_frame_timeout	u32	Receive frame timeout (Linux and macOS only)	μs

Axes (Single Axis)

Field	Type	Description	Unit
enco_offst	i32	Encoder offset	Encoder ticks
gear_ratio	f64	Gear ratio	N/A
slv_idx	uint	Slave index (zero-indexed position in network)	N/A
min_pos	f64	Minimum angular position of rotational motor	Degrees
max_pos	f64	Maximum angular position of rotational motor	Degrees

Groups

Field	Type	Description	Unit
axs_idx_vec	uint vector (4)	Axes indices	N/A
pos	f64 vector (6)	Robot frame position relative to world frame	mm, mm, mm, deg, deg, deg
world_limits_type	WorldLimitType	World limit enum	N/A
group_type	GroupType	Group type enum	N/A
end_eff	EndEffConfig	End effector digital output configuration	N/A

World Limit: CylindricalZConfig

Field	Type	Unit
z_min	f64	mm
z_max	f64	mm
r_xy_max	f64	mm

Group Type: DeltaConfig

Field	Type	Unit
base_radius	f64	mm
base_offset	f64	mm
upper_arm_length	f64	mm
lower_arm_length	f64	mm
platform_offset	f64	mm
platform_radius	f64	mm
motor_angles	f64 vector (3)	degrees
upper_arm_mass	f64	kg
lower_arm_mass	f64	kg
lower_plate_mass	f64	kg
upper_arm_cm_radius	f64	mm
upper_arm_cm_inertia	f64	kg·mm²

Group Type: SerialDHConfig

Field	Type	Unit
theta	vector (7)	degrees
a	vector (7)	degrees
d	vector (7)	degrees
alpha	vector (7)	degrees
joint_type	vector (7)	N/A

Cameras

Field	Type	Description	Unit
id	String	Camera ID number	N/A
exposure_time	f64	Camera exposure time	μs
pixel_size	f64	Camera pixel size	μm
focal_length	f64	Lens focal length	mm
pos	f64 vector (6)	Camera frame position relative to world frame	mm, mm, mm, deg, deg, deg

Conveyors

Field	Type	Description	Unit
width	f64	Conveyor width	mm
length	f64	Conveyor length	mm
cam_idx_vec	uint vector	Cameras used for tracking objects on this conveyor	N/A
pos	f64 vector (6)	Conveyor frame position relative to world frame	mm, mm, mm, deg, deg, deg
descend_dist	f64	Descend/ascend distance in Z direction during pickup	mm
end_eff_delay	f64	End effector delay to fully engage	s

Parts

Field	Type	Description	Unit
width	f64	Width of the part	mm
length	f64	Length of the part	mm
height	f64	Height of the part	mm
mass	f64	Mass of the part	kg
inertia_zz	f64	Inertia about center of mass in Z direction	kg·mm²
label	String	"", "alphabetic", "alphanumeric", or "text" — used to detect if 180° rotation is needed	N/A
max_linear_error	f64	Percentage of acceptable error in width or length when identifying parts	N/A

Cycles

Field	Type	Description	Unit
grp_idx	uint	Group index	N/A
cnv_idx	uint	Conveyor index	N/A
cnt_idx	uint	Container index	N/A
prt_idx	uint	Part index	N/A
prcn	u8	Speed precision	N/A
cnv_pickup_timeout	f64	How long a conveyor intercept or pickup call keeps attempting to find a part	s
cnv_spd	f64	Conveyor speed	mm/s
cycle_type	Enum	CnvToCnt or CntToCnv	N/A
start_signal	DigSignal	Digital input signal for cycle to start	N/A
done_signal	DigSignal	Digital output signal when cycle is done	N/A

Diagram Quantities

Symbol	Description
φᵢ	Leg angle
θᵢ	Joint angle
rᵦ	Base radius
Oᵦ	Base offset
lᵦ	Base leg length
lₚ	Platform leg length
Oₚ	Platform offset
rₚ	Platform radius

Appendix A: Payload Details

Network Payloads

Payload	Fields	Description	Type
CmdRspRslt	done	Request response	Boolean

Slave Management Payloads

Payload	Fields	Description	Type
NumSlvsEcatData	num_slaves	Number of slaves	uint
	rslt	Error code (see Appendix B)	u16
	done	Request response	Boolean

Axis Payloads

Payload	Key Fields	Description
AxisData	axs_idx, rslt, done	Base axis payload
AxisCurrPosData	axs_idx, curr_pos, rslt, done	Current position (mm or deg)
AxisMovePosData	axs_idx, end_pos, rslt, done	Absolute position target (mm or deg)
AxisMoveVelData	axs_idx, end_vel, rslt, done	Velocity target (mm/s or deg/s)
AxisMoveRelData	axs_idx, rel_pos, rslt, done	Relative position (mm or deg)
AxisDigData	axs_idx, bit_off, val, rslt, done	Digital I/O
AxisBoolData	axs_idx, val, rslt, done	Boolean value
AxisAlarmsData	axs_idx, alarms, rslt, done	Alarm vector
AxisSleepData	axs_idx, t_tot, rslt, done	Sleep duration (s)
AxisSpdPrcnData	axs_idx, prcn, rslt, done	Speed precision

Group Payloads

Payload	Key Fields	Description
GroupData	grp_idx, rslt, done	Base group payload
GroupMovePosData	grp_idx, end_pos, coord_type, rslt, done	Absolute position (Joint or World)
GroupMoveRelData	grp_idx, rel_pos, coord_type, rslt, done	Relative position (Joint or World)
GroupDigData	grp_idx, axs_idx, bit_off, val, rslt, done	Digital I/O
GroupBoolData	grp_idx, val, rslt, done	Boolean value
GroupBgnPosData	grp_idx, coord_type, bgn_pos, rslt, done	Begin position
GroupCurrPosData	grp_idx, joint_pos, world_pos, rslt, done	Current position (joint and world)
GroupAlarmsData	grp_idx, alarms, rslt, done	Alarm vector
GroupSleepData	grp_idx, t_tot, rslt, done	Sleep duration
GroupSpdPrcnData	grp_idx, prcn, rslt, done	Speed precision
MotnCmdData	rslt, done	Motion command response

Conveyor Payloads

Payload	Key Fields	Description
ConvSpdData	cnv_idx, cnv_spd, rslt, done	Conveyor speed (m/s)
GroupConvInterceptData	grp_idx, cnv_idx, prt_idx, label, drop_rz, found, rslt, done	Conveyor intercept
GroupConvData	grp_idx, cnv_idx, coord_type, rslt, done	General conveyor operation
GroupConvPickupData	grp_idx, cnv_idx, prt_idx, label, drop_rz, rslt, done	Conveyor pickup
GroupConvDropoffData	grp_idx, cnv_idx, prt_idx, rslt, done	Conveyor drop-off

Container Payloads

Payload	Key Fields	Description
GroupContDropoffData	grp_idx, cnt_idx, prt_idx, rslt, done	Container drop-off
GroupContPickupData	grp_idx, cnt_idx, prt_idx, drop_rz, rslt, done	Container pickup
GroupContPickupIdxData	grp_idx, cnt_idx, prt_idx, drop_rz, i_idx, j_idx, k_idx, rslt, done	Indexed container pickup
GroupContData	grp_idx, cnt_idx, rslt, done	General container operation
ContData	cnt_idx, rslt, done	Container state
ContPartData	cnt_idx, prt_idx, rslt, done	Container part
ContBoolData	cnt_idx, val, rslt, done	Container boolean check
ContPartBoolData	cnt_idx, prt_idx, val, rslt, done	Container part boolean check

Low-Level Payloads

Payload	Key Fields	Description
CoeU8Data	slv_idx, index, sub_index, val, rslt, done	CoE 8-bit operation
CoeU16Data	slv_idx, index, sub_index, val, rslt, done	CoE 16-bit operation
CoeU32Data	slv_idx, index, sub_index, val, rslt, done	CoE 32-bit operation
Cia402OpModeData	slv_idx, op_mode, rslt, done	CiA 402 operation mode

Appendix B: Motion Result Error Codes

Value	Description
0x0000	Success
0x1001	Initialization axes network error
0x1002	Invalid axis index
0x1003	Invalid group index
0x1004	Invalid conveyor index
0x1005	Invalid container index
0x1006	Invalid part index
0x1007	Invalid digital I/O bit offset
0x1008	Axis index not in group
0x1009	Motion commanded while not servoed on
0x100A	Joint position limits reached
0x100B	Joint velocity limits reached
0x100C	Joint torque limits reached
0x100D	World position limits reached
0x100E	World velocity limits reached
0x100F	World torque limits reached
0x1010	Small or zero length trajectory append dropped
0x1011	Servo off commanded while motion running
0x1012	Axis and group command trajectory attempting to move the same axis
0x1013	Conveyor part not found
0x1014	Conveyor speed not initialized
0x1015	Conveyor speed exceeds group speed — robot cannot catch up with or track the conveyor
0x1016	Conveyor intercept solution did not converge (often due to conveyor running too fast relative to robot)
0x1017	Conveyor vertical trajectory failed — max X vel/acc required during move exceeded
0x1018	Move append while an alarm present
0x1019	Move append while a velocity move is running
0x101A	Move append joint trajectory to a world trajectory on a group with non-unique inverse kinematics is not allowed
0x101B	Quick stop append trajectory failed — quick stop already running
0x101C	Motion command mismatch
0x101D	Forward kinematics unreachable
0x101E	Inverse kinematics non-convergent
0x101F	Inverse kinematics unreachable
0x1020	Inverse kinematics singularity
0x1021	No end effector config available
0x1022	Container was being filled with one part type, then switched to another before full
0x1023	Drop-off with auto fill was made while container is already full
0x1024	Pickup with auto empty was made while container is already empty
0x1025	Container fill index invalid
0x1026	Speed percent cannot be zero
0x1027	Emergency stop pressed
0x1FFF	Unspecified motion error

Appendix C: ECAT Result Error Codes

Value	Description
0x0000	Success
0x0001	Invalid slave index
0x0002	Uninitialized slave index
0x0003	Uninitialized station address
0x0004	Working counter not incremented
0x0005	Frame receive timeout
0x0006	Frame command mismatch
0x0007	ESI file not found
0x0008	SM data cat section not found in SSI
0x0009	Register response mismatch
0x000A	SSI maximum byte length reached
0x000B	Max retries reached while polling CoE SM1 response mbox ready status
0x000C	CoE mbox emergency
0x000D	CoE mbox abort code
0x000E	CiA operational mode maximum retries reached
0x000F	EtherCAT command mismatch