Provides the main controller for the robot system. Through MagicRobot, you can perform resource initialization, manage communication connections, and access various sub-controllers such as motion controllers, audio controllers, state monitors, and sensor controllers.

⚠️

Module Information

magicdog_python is the Python binding module for the MagicDog SDK, providing comprehensive robot control, sensor data acquisition, audio processing, and other functional interfaces.

Item	Content
Module Name	magicdog_python
Description	MagicDog SDK Python binding module
Dependencies	pybind11, C++ SDK

Interface Definition

MagicRobot is the unified entry class for the robot system.

MagicRobot — Main Robot Class

Item	Content
Class Name	MagicRobot
Function Overview	Main robot control class, integrates all functional modules
Main Functions	System initialization, connection management, controller access
Use Cases	Robot application development, system integration, functional testing

initialize

Item	Content
Method Name	initialize
Method Declaration	bool initialize(const str& local_ip)
Function Overview	Initializes the robot system, including controllers and network modules.
Parameter Description	local_ip: Local communication IP address.
Return Value	true for success, false for failure.
Note	Must be called before first use.

shutdown

Item	Content
Method Name	shutdown
Method Declaration	void shutdown()
Function Overview	Shuts down the robot system and releases resources.
Note	Used together with initialize.

connect

Item	Content
Method Name	connect
Method Declaration	Status connect()
Function Overview	Establishes a communication connection with the robot service.
Return Value	Status::OK indicates success.
Note	Blocking interface, should be called after initialization.

disconnect

Item	Content
Method Name	disconnect
Method Declaration	Status disconnect()
Function Overview	Disconnects from the robot service.
Return Value	Status::OK indicates success.
Note	Blocking interface, used together with connect.

get_sdk_version

Item	Content
Method Name	get_sdk_version
Method Declaration	str get_sdk_version()
Function Overview	Gets the current SDK version.
Return Value	SDK version string (e.g., 0.0.1).
Note	Non-blocking interface, useful for debugging or logging.

set_timeout

Item	Content
Method Name	set_timeout
Method Declaration	void set_timeout(int timeout)
Function Overview	Sets the timeout for interface calls.
Parameter Description	timeout: Timeout in milliseconds.
Note	Non-blocking interface, default is 5000 ms.

get_motion_control_level

Item	Content
Method Name	get_motion_control_level
Method Declaration	ControllerLevel get_motion_control_level()
Function Overview	Gets the current motion control level (high/low).
Return Value	ControllerLevel enum value.
Note	Non-blocking interface, used to determine current control permission.

set_motion_control_level

Item	Content
Method Name	set_motion_control_level
Method Declaration	Status set_motion_control_level(ControllerLevel level)
Function Overview	Sets the current motion control level.
Parameter Description	level: Control permission enum value.
Return Value	Status::OK indicates success, others indicate failure.
Note	Blocking interface, used when switching control modes.

get_high_level_motion_controller

Item	Content
Method Name	get_high_level_motion_controller
Method Declaration	HighLevelMotionController get_high_level_motion_controller()
Function Overview	Gets the high-level motion controller object.
Return Value	High-level motion controller instance, used to call high-level control interfaces.
Note	Non-blocking interface, encapsulates gait, stunt, remote control, and other functions.

get_low_level_motion_controller

Item	Content
Method Name	get_low_level_motion_controller
Method Declaration	LowLevelMotionController get_low_level_motion_controller()
Function Overview	Gets the low-level motion controller object.
Return Value	Low-level motion controller instance, used to control joints or motors.
Note	Non-blocking interface, can directly control joint motors, etc.

get_audio_controller

Item	Content
Method Name	get_audio_controller
Method Declaration	AudioController get_audio_controller()
Function Overview	Gets the audio controller object.
Return Value	Audio controller instance, used for voice control.
Note	Non-blocking interface, can play voice and control volume.

get_sensor_controller

Item	Content
Method Name	get_sensor_controller
Method Declaration	SensorController get_sensor_controller()
Function Overview	Gets the sensor controller object.
Return Value	Sensor controller instance, used to access sensor data.
Note	Non-blocking interface, encapsulates IMU, RGBD, and other sensor data reading.

get_state_monitor

Item	Content
Method Name	get_state_monitor
Method Declaration	StateMonitor get_state_monitor()
Function Overview	Gets the state monitor object.
Return Value	State monitor instance, used to get the current robot state information.
Note	Non-blocking interface, encapsulates BMS, fault, and other state information reading.

Constant Definitions

Constant Name	Type	Description
LEG_JOINT_NUM	int	Number of leg joints
PERIOD_MS	int	Control period (milliseconds)

Data Structure Definitions

Status — Status Return Structure

Field Name	Type	Description
code	ErrorCode	Error code
message	str	Status message

ErrorCode — Error Code Enum

Enum Value	Value	Description
OK	0	Operation successful
SERVICE_NOT_READY	1	Service not ready
TIMEOUT	2	Operation timed out
INTERNAL_ERROR	3	Internal error
SERVICE_ERROR	4	Service error