⚙ Development Guide > SDK > API

API Overview#

The AirbotClient class is the unified entry point for the AIRBOT Play SDK and implements APIs for robotic arm control and state queries.

Function	Subfunction	Interface	Parameter Description
Initialization	Initialize and connect to the robotic arm server	`init(self, host: str = "localhost", port: int = 50051, arm_dof: int = 6) -> None`	- host: Server IP address - port: Server port - arm_dof: Degrees of freedom of the robotic arm
gRPC control-ownership interfaces	Acquire control-service permission from the server	`acquire_control(lease_ms: int = 15000, renew_period_s: float = 5.0) -> bool`	- Function: Acquires a server control-service handle, allowing the client to control robotic arm motion - lease_ms: Validity period/lease duration of the exclusive control ownership requested from the server - renew_period_s: Interval/frequency at which the client automatically renews the lease in the background - Returns: `True` if the handle is acquired successfully; otherwise `False`
	Release server control-service permission and enter read-only state	`release_control() -> None`	- Function: Releases the server control-service handle so the client can read robotic arm state information but cannot control the arm
	Close the client connection and release client resources	`close() -> None`	- Function: Safely finalizes and cleans up the client, releasing threads, control ownership, and network resources so the client can exit safely
Data-feedback interfaces	Get current robotic arm joint data	`get_arm_joint_state() -> Optional[ArmJointState]`	- Function: Gets the current state of the robotic arm joints - Returns: On success, an `ArmJointState` structure (see Arm State) containing joint position, velocity, and current; on failure, `None`
	Get current robotic arm motor data	`get_arm_motor_state() -> Optional[ArmMotorState]`	- Function: Gets the current state of the robotic arm motors - Returns: On success, an `ArmMotorState` structure (see Arm State) containing motor temperatures, MOSFET temperatures, and error codes; on failure, `None`
	Get current end-effector joint data	`get_eef_joint_state() -> Optional[EEFJointState]`	- Function: Gets the current state of the end-effector joint - Returns: On success, an `EEFJointState` structure (see End-Effector State) containing joint position, velocity, and current; on failure, `None`
	Get current end-effector motor data	`get_eef_motor_state() -> Optional[EEFMotorState]`	- Function: Gets the current state of the end-effector motor - Returns: On success, an `EEFMotorState` structure (see End-Effector State) containing motor temperature, MOSFET temperature, and error code; on failure, `None`
	Get the current Cartesian-space pose of the robotic arm tool end	`get_end_pose() -> Optional[CartesianPose]`	- Function: Gets the current Cartesian-space pose of the robotic arm tool end - Returns: On success, a `CartesianPose` structure (see Tool-End Pose) containing position and orientation; on failure, `None`
	Get the current operating state of the robotic arm server	`get_service_state() -> Optional[ServiceState]`	- Function: Gets the current operating state of the robotic arm server - Returns: On success, a `ServiceState` structure (see Server State) containing the server operating state, server state-machine state, and server controller state; on failure, `None`
	Get current robotic arm firmware information	`get_firmware_info(self) -> Optional[ArmFirmwareInfo]`	- Function: Gets the current robotic arm firmware information - Returns: On success, an `ArmFirmwareInfo` structure (see Firmware Information) containing firmware types, SNs, firmware versions, and other data; on failure, `None`
Client parameter-setting interface	Set maximum robotic arm joint velocity	`set_arm_speed(self, arm_speed: list[float]) -> bool`	- Function: Sets the maximum operating velocity of the robotic arm motors - arm_speed: Maximum motor operating velocity (0 to 2.0 * pi) - Returns: Whether the setting succeeded
Robotic arm control interfaces	Set the robotic arm controller (requires control ownership)	`switch_controller(controller: Controller, timeout_ms: int = 1000) -> bool`	- Function: Sets the robotic arm controller type - controller: Controller name of type `Controller` (see Controller) - timeout_ms: Timeout in ms - Returns: `True` if set successfully; otherwise `False`
	Enter gravity-compensation mode (requires control ownership)	`enter_gravity_compensation_mode(timeout_ms: int = 1000) -> bool`	- Function: Enters gravity-compensation mode. Call `switch_controller` to switch to another controller and exit this mode. - timeout_ms: Timeout in ms - Returns: `True` if set successfully; otherwise `False`
	Control the robotic arm in joint space (requires control ownership)	`move_joint(pos: list[float], options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Controls the robotic arm in joint space - pos: Target joint-space positions of the robotic arm motors (for joint-position limits, see Joint-Limit Values) - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Control the end effector in joint space (requires control ownership)	`move_eef(pos: float, options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Controls the end effector in joint space (for joint-position limits, see Joint-Limit Values) - pos: Target joint-space position of the end effector - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Control the robotic arm in Cartesian space (requires control ownership)	`move_end_pose(pos: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Controls the robotic arm in Cartesian space - pos: Target robotic arm tool-end pose represented by `CartesianPose` (see Tool-End Pose) - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Plan and control a Cartesian-space linear trajectory (requires control ownership)	`move_end_pose_linear(start: CartesianPose, target: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Plans and controls a Cartesian-space linear trajectory for the robotic arm - start: Starting robotic arm tool-end pose represented by `CartesianPose` (see Tool-End Pose) - target: Target robotic arm tool-end pose represented by `CartesianPose` (see Tool-End Pose) - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Plan and control a Cartesian-space circular trajectory (requires control ownership)	`move_end_pose_circle(start: CartesianPose, path: CartesianPose, target: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Plans and controls a Cartesian-space circular trajectory for the robotic arm - start: Starting robotic arm tool-end pose represented by `CartesianPose` (see Tool-End Pose) - path: Tool-end pose of the robotic arm path point represented by `CartesianPose` (see Tool-End Pose) - target: Target robotic arm tool-end pose represented by `CartesianPose` (see Tool-End Pose) - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Plan and control multiple joint-space waypoints (requires control ownership)	`move_joint_waypoints(waypoints: list[list[float]], options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Plans and controls multiple robotic arm joint-space waypoints - waypoints: Set of robotic arm joint-space positions; for joint-position limits, see Joint-Limit Values - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
	Plan and control multiple Cartesian-space waypoints (requires control ownership)	`move_end_pose_waypoints(waypoints: list[CartesianPose], options: ArmControlOptions, timeout_ms: int = 1000) -> bool`	- Function: Plans and controls multiple robotic arm Cartesian-space waypoints - waypoints: Set of robotic arm Cartesian-space positions represented by `CartesianPose` - options: Control parameters of type `ArmControlOptions` (see Control Options); see Control Modes for the parameters required by each mode - timeout_ms: Timeout in ms - Returns: `True` if the control command is sent successfully; otherwise `False`
Robotic arm reset functions	Return the robotic arm to zero (requires control ownership)	`return_zero() -> bool`	- Function: Returns all robotic arm joints to zero - Returns: `True` if the control command is sent successfully; otherwise `False`
	Emergency-stop and recover the robotic arm (emergency stop requires control ownership; recovery does not)	`set_arm_emergency_stop(mode: bool) -> bool`	- Function: Emergency-stops or recovers the robotic arm - mode: Selects emergency stop or recovery: `True` is emergency-stop mode and `False` is recovery after emergency stop - Returns: `True` if the control command is sent successfully; otherwise `False`
	Clear robotic arm motor error codes (requires control ownership)	`clear_arm_motor_err() -> bool`	- Function: Clears robotic arm motor error codes - Returns: `True` if the control command is sent successfully; otherwise `False`
	Clear end-effector motor error codes (requires control ownership)	`clear_eef_motor_err() -> bool`	- Function: Clears end-effector motor error codes - Returns: `True` if the control command is sent successfully; otherwise `False`
Utility function	Located in the `utilities` submodule and primarily used to map travel between different end effectors	`def map_pendant_to_gripper(pos: float, *, from_pendant: str, to_gripper: str, clamp: bool = True) -> float`	- Function: Maps a teaching-device return value to the end effector's actual control quantity - pos: Teaching-device input value - from_pendant: Teaching-device type - to_gripper: Gripper type - Returns: Actual gripper control quantity - See the appendix for all currently supported teaching-device and gripper models

Trajectory-Planning Velocity

Trajectory-planning velocity is not affected by the maximum velocity limit. The maximum trajectory-planning velocity is 4π.

End-Effector Control Precautions

The control method used by the end effector differs between controller operating conditions. Observe the following precautions:

① Before calling the set_arm_speed and set_eef_speed interfaces to set maximum execution velocity, the default maximum operating velocity of the robotic arm and end effector is π / 3 rad/s.

② When options.blocking = False (that is, when an end-effector motion-control interface is called in non-blocking mode), an end-effector command in progress may be interrupted by a controller switch.
For example, if an end-effector motion command is sent under the direct_control controller and the controller is then switched to planning_control, the previously issued command will be interrupted.
Therefore, select blocking or non-blocking execution as appropriate for the task.

③ During Cartesian-space or joint-space control under the servo_control controller, end-effector motion is affected by the options.eef_pos parameter. When options.blocking = False, meaning non-blocking operation, and both move_end_pose (or move_joint) and move_eef are called, the later command interrupts execution of the earlier task. By contrast, end-effector control under direct_control accepts commands only from move_end_pose.
Be sure to distinguish between the usage of the servo_control and direct_control control modes to avoid control conflicts.