提供机器人系统主控制器，通过 MagicRobot 可以进行资源初始化、管理通信连接、访问各子控制器如运动控制器、音频控制器、状态监控以及传感器控制器等。

⚠️

模块信息

magicdog_python 是 MagicDog SDK 的 Python 绑定模块，提供了完整的机器人控制、传感器数据获取、音频处理等功能接口。

项目	内容
模块名	magicdog_python
描述	MagicDog SDK Python 绑定模块
依赖	pybind11, C++ SDK

接口定义

MagicRobot 是机器人系统的统一入口类。

MagicRobot — 主机器人类

项目	内容
类名	MagicRobot
功能概述	机器人主控制类，整合所有功能模块
主要功能	系统初始化、连接管理、控制器获取
使用场景	机器人应用开发、系统集成、功能测试

initialize

项目	内容
方法名	initialize
方法声明	bool initialize(const str& local_ip)
功能概述	初始化机器人系统，包括控制器与网络模块。
参数说明	local_ip：本地通信 IP 地址。
返回值	true 表示成功，false 表示失败。
备注	首次使用前必须调用。

shutdown

项目	内容
方法名	shutdown
方法声明	void shutdown()
功能概述	关闭机器人系统，释放资源。
备注	配合 initialize 使用。

connect

项目	内容
方法名	connect
方法声明	Status connect()
功能概述	与机器人服务建立通信连接。
返回值	Status::OK 表示成功。
备注	阻塞接口，需初始化后调用。

disconnect

项目	内容
方法名	disconnect
方法声明	Status disconnect()
功能概述	断开与机器人服务的连接。
返回值	Status::OK 表示成功。
备注	阻塞接口，与 connect 配对使用。

get_sdk_version

项目	内容
方法名	get_sdk_version
方法声明	str get_sdk_version()
功能概述	获取当前 SDK 的版本号。
返回值	SDK 版本字符串（如 0.0.1）。
备注	非阻塞接口，便于调试或日志标记。

set_timeout

项目	内容
方法名	set_timeout
方法声明	void set_timeout(int timeout)
功能概述	设置接口调用的超时时间。
参数说明	timeout：单位为毫秒。
备注	非阻塞接口，默认值为 5000 毫秒。

get_motion_control_level

项目	内容
方法名	get_motion_control_level
方法声明	ControllerLevel get_motion_control_level()
功能概述	获取当前运动控制级别（高层/低层）。
返回值	ControllerLevel 枚举值。
备注	非阻塞接口，用于判断当前控制权限。

set_motion_control_level

项目	内容
方法名	set_motion_control_level
方法声明	Status set_motion_control_level(ControllerLevel level)
功能概述	设置当前运动控制级别。
参数说明	level：控制权限枚举值。
返回值	Status::OK 表示设置成功，其他代表设置失败。
备注	阻塞接口，控制模式切换时使用。

get_high_level_motion_controller

项目	内容
方法名	get_high_level_motion_controller
方法声明	HighLevelMotionController get_high_level_motion_controller()
功能概述	获取高层运动控制器对象。
返回值	高层运动控制器实例，用于调用高层控制接口。
备注	非阻塞接口，封装了步态、特技、遥控等控制功能。

get_low_level_motion_controller

项目	内容
方法名	get_low_level_motion_controller
方法声明	LowLevelMotionController get_low_level_motion_controller()
功能概述	获取低层运动控制器对象。
返回值	低层运动控制器实例，用于控制关节或电机。
备注	非阻塞接口，可直接控制关节电机等。

get_audio_controller

项目	内容
方法名	get_audio_controller
方法声明	AudioController get_audio_controller()
功能概述	获取音频控制器对象。
返回值	音频控制器实例，用于语音控制。
备注	非阻塞接口，可播放语音和控制音量。

get_sensor_controller

项目	内容
方法名	get_sensor_controller
方法声明	SensorController get_sensor_controller()
功能概述	获取传感器控制器对象。
返回值	传感器控制器实例，用于访问传感器数据。
备注	非阻塞接口，封装了 IMU、RGBD 等传感器数据读取。

get_state_monitor

项目	内容
方法名	get_state_monitor
方法声明	StateMonitor get_state_monitor()
功能概述	获取状态监控器对象。
返回值	状态监控器实例，用于获取机器人当前状态信息。
备注	非阻塞接口，封装了 BMS、故障等状态信息的读取。

常量定义

常量名	类型	描述
LEG_JOINT_NUM	int	腿部关节数量
PERIOD_MS	int	控制周期（毫秒）