简体中文

English

简体中文

English

外观

快速开始

约 1383 字大约 5 分钟

2025-07-0818:08:40

系统环境

推荐在ubuntu22.04系统下开发，暂不支持Mac/Windows系统下开发，机器人本体PC运行官方服务，不支持开发；

开发环境要求

  • GCC ≥ 11.4 (for Linux)
  • CMake ≥ 3.16
  • Make build system
  • C++20 (minimum)
  • Eigen3
  • python3.10

第三方库依赖

sudo apt update
sudo apt install libgrpc++-dev libgrpc-dev liblcm-dev libyaml-cpp-dev libsystemd-dev -y
sudo apt install cmake python3 python3-dev python3-pip libeigen3-dev build-essential -y

系统配置

首先，为了实现普通用户下通信实时性，需要在/etc/security/limits.conf文件中增加如下配置：

*    -   rtprio   98

其次，为了增加每个socket链接的接收缓存，需要在/etc/sysctl.conf文件中增加如下配置，sudo sysctl -p立即生效或重启生效：

net.core.rmem_max=20971520  
net.core.rmem_default=20971520  
net.core.wmem_max=20971520  
net.core.wmem_default=20971520

网络环境

将用户计算机与机器人交换机接入统一网络。建议新用户使用网线将用户计算机接入机器人交换机，并将与机器人通信的网卡设置在192.168.54.X网段下，推荐使用192.168.54.111。有经验的用户可自行配置网络环境。

配置步骤

  1. 用网线的一端连接机器人，另一端连接用户电脑。机器人机载电脑的IP地址为192.168.54.110（小脑算力板）和192.168.54.119（大脑算力板），所以需要将电脑ip设置为同一网段，建议192.168.54.111. 网络配置

  2. 为了测试通信连接是否正常，可以通过ping进行测试： 网络诊断

  3. 查看192.168.54.111网址对应的网卡名称，通过ifconfig命令查看网卡名字，如图所示： 网卡名称

假设SDK二次开发PC与机器人链接的网口为enp0s31f6，需要进行如下配置以便SDK与机器人的底层通信：

 sudo ifconfig enp0s31f6 multicast
 sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev enp0s31f6

安装与编译

以下步骤假设工作目录为/home/magicbot/workspace

安装 magicbot-z1_sdk:

安装步骤：进入magicbot-z1_sdk目录，并按步骤执行如下命令，将sdk安装至/opt/magic_robotics/magic_z1_sdk目录下，便于二次开发程序find_package检索编译链接：

cd /home/magicbot/workspace/magicbot-z1_sdk/
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/magic_robotics/magic_z1_sdk
sudo make install

例程编译

编译步骤：进入magicbot-z1_sdk目录，并按步骤执行如下命令，在build目录下生成例程可执行程序：

cd /home/magicbot/workspace/magicbot-z1_sdk/
mkdir build
cd build
cmake .. -DBUILD_EXAMPLES=ON
make -j8

例程示例

magicbot-z1_sdk/build目录中：

  • 语音示例:
    • audio_example
  • 传感器示例:
    • sensor_example
  • 状态监控示例:
    • monitor_example
  • 底层运控示例:
    • low_level_motion_example
  • 高层运控示例:
    • high_level_motion_example

Notice: 其中，高层运控示例中几种示例有先后依赖顺序（锁定站立->平衡站立->执行特技/遥控器控制）

进入调试模式：

按照操作流程，确保机器人进入调试模式

运行例程

进入magicbot-z1_sdk/build目录，执行如下命令：

cd /home/magicbot/workspace/magicbot-z1_sdk/build
# 环境配置
sudo ifconfig enp0s31f6 multicast
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev enp0s31f6
export LD_LIBRARY_PATH=/opt/magic_robotics/magic_z1_sdk/lib:$LD_LIBRARY_PATH

# 语音控制示例
./audio_example

# 传感器控制示例
./sensor_example

# 状态监控示例
./monitor_example

# 底层运动控制示例
./low_level_motion_example

# 高层运动控制示例
./high_level_motion_example

Python 例程示例

magicbot-z1_sdk/example/python目录中：

  • 语音示例:
    • audio_example.py
  • 传感器示例:
    • sensor_example.py
  • 状态监控示例:
    • monitor_example.py
  • 底层运控示例:
    • low_level_motion_example.py
  • 高层运控示例:
    • high_level_motion_example.py

Notice: 其中，高层运控示例中几种示例有先后依赖顺序（锁定站立->平衡站立->执行特技/遥控器控制）

进入调试模式：

按照操作流程，确保机器人进入调试模式

运行例程

进入magicbot-z1_sdk/example/python目录，执行如下命令：

cd /home/magicbot/workspace/magicbot-z1_sdk/example/python
# 环境配置
sudo ifconfig enp0s31f6 multicast
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev enp0s31f6
export PYTHONPATH=/opt/magic_robotics/magic_z1_sdk/lib:$PYTHONPATH
export LD_LIBRARY_PATH=/opt/magic_robotics/magic_z1_sdk/lib:$LD_LIBRARY_PATH

# 语音控制示例
python3 audio_example.py

# 传感器控制示例
python3 sensor_example.py

# 状态监控示例
python3 monitor_example.py

# 底层运动控制示例
python3 low_level_motion_example.py

# 高层运动控制示例
python3 high_level_motion_example.py

获取python api帮助信息：

# 环境配置
export PYTHONPATH=/opt/magic_robotics/magic_z1_sdk/lib:$PYTHONPATH
export LD_LIBRARY_PATH=/opt/magic_robotics/magic_z1_sdk/lib:$LD_LIBRARY_PATH

$ python3
Python 3.10.12 (main, Aug 15 2025, 14:32:43) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
# 导入Magic z1 python SDK接口
>>> import magicbot_z1_python
# 查看所有接口信息             
>>> help(magicbot_z1_python)
# 查看CameraInfo结构信息 
>>> help(magicbot_z1_python.CameraInfo)
# 查看HighLevelMotionController对象信息 
>>> help(magicbot_z1_python.HighLevelMotionController)
# 查看LowLevelMotionController对象信息 
>>> help(magicbot_z1_python.LowLevelMotionController)
# 查看SensorController对象信息 
>>> help(magicbot_z1_python.SensorController)
# 查看AudioController对象信息 
>>> help(magicbot_z1_python.AudioController)
# 查看StateMonitor对象信息 
>>> help(magicbot_z1_python.StateMonitor)

比如，如果想查看特技动作TrickAction的枚举值：

$ python3
Python 3.10.12 (main, Aug 15 2025, 14:32:43) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import magicbot_gen1_python
>>> help(magicbot_gen1_python.TrickAction)
Help on class TrickAction in module magicbot_z1_python:

class TrickAction(pybind11_builtins.pybind11_object)
 |  Method resolution order:
 |      TrickAction
 |      pybind11_builtins.pybind11_object
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  __eq__(...)
 |      __eq__(self: object, other: object, /) -> bool
 |  
 |  __getstate__(...)
 |      __getstate__(self: object, /) -> int
 |  
 |  __hash__(...)
 |      __hash__(self: object, /) -> int
 |  
 |  __index__(...)
 |      __index__(self: magicbot_z1_python.TrickAction, /) -> int
 |  
 |  __init__(...)
 |      __init__(self: magicbot_z1_python.TrickAction, value: typing.SupportsInt) -> None
 |  
 |  __int__(...)
 |      __int__(self: magicbot_z1_python.TrickAction, /) -> int
 |  
 |  __ne__(...)
 |      __ne__(self: object, other: object, /) -> bool
 |  
 |  __repr__(...)
 |      __repr__(self: object, /) -> str
 |  
 |  __setstate__(...)
 |      __setstate__(self: magicbot_z1_python.TrickAction, state: typing.SupportsInt, /) -> None
 |  
 |  __str__(...)
 |      __str__(self: object, /) -> str
 |  
 |  ----------------------------------------------------------------------
 |  Readonly properties defined here:
 |  
 |  __members__
 |  
 |  name
 |      name(self: object, /) -> str
 |  
 |  value
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  ACTION_LEFT_GREETING = <TrickAction.ACTION_LEFT_GREETING: 300>
 |  
 |  ACTION_NONE = <TrickAction.ACTION_NONE: 0>
 |  
 |  ACTION_RIGHT_GREETING = <TrickAction.ACTION_RIGHT_GREETING: 301>
 |  
 |  ACTION_SHAKE_HEAD = <TrickAction.ACTION_SHAKE_HEAD: 220>
 |  
 |  ACTION_SHAKE_LEFT_HAND_REACHOUT = <TrickAction.ACTION_SHAKE_LEFT_HAND_...
 |  
 |  ACTION_SHAKE_LEFT_HAND_WITHDRAW = <TrickAction.ACTION_SHAKE_LEFT_HAND_...
 |  
 |  ACTION_SHAKE_RIGHT_HAND_REACHOUT = <TrickAction.ACTION_SHAKE_RIGHT_HAN...
 |  
 |  ACTION_SHAKE_RIGHT_HAND_WITHDRAW = <TrickAction.ACTION_SHAKE_RIGHT_HAN...
 |  
 |  ACTION_TRUN_LEFT_INTRODUCE_HIGH = <TrickAction.ACTION_TRUN_LEFT_INTROD...
 |  
 |  ACTION_TRUN_LEFT_INTRODUCE_LOW = <TrickAction.ACTION_TRUN_LEFT_INTRODU...
 |  
 |  ACTION_TRUN_RIGHT_INTRODUCE_HIGH = <TrickAction.ACTION_TRUN_RIGHT_INTR...
 |  
 |  ACTION_TRUN_RIGHT_INTRODUCE_LOW = <TrickAction.ACTION_TRUN_RIGHT_INTRO...
 |  
 |  ACTION_WELCOME = <TrickAction.ACTION_WELCOME: 340>
 |  
 |  ----------------------------------------------------------------------
 |  Static methods inherited from pybind11_builtins.pybind11_object:
 |  
 |  __new__(*args, **kwargs) from pybind11_builtins.pybind11_type
 |      Create and return a new object.  See help(type) for accurate signature.

其他

SDK配置文件

SDK运行时默认会在/tmp目录下生成其默认配置文件，如果配置文件已存在则使用已有配置：

$ ls /tmp/magicbot_z1_mjrrt.yaml
/tmp/magicbot_z1_mjrrt.yaml

SDK日志

SDK运行时内部的日志信息默认生成在/tmp/logs目录下：

$ ls /tmp/logs/magicbot_z1_sdk.log 
/tmp/logs/magicbot_z1_sdk.log