System Environment

Development is recommended on Ubuntu 22.04 system. Mac/Windows systems are not currently supported for development. The robot's onboard PC runs official services and does not support development;

Development Environment Requirements

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

Third-party Library Dependencies

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

System Configuration

First, to achieve real-time communication under regular users, add the following configuration to the /etc/security/limits.conf file:

*    -   rtprio   98

Second, to increase the receive buffer for each socket connection, add the following configuration to the /etc/sysctl.conf file. Use sudo sysctl -p to take effect immediately or restart to take effect:

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

Network Environment

Connect the user computer and robot switch to a unified network. It is recommended that new users use an Ethernet cable to connect the user computer to the robot switch, and set the network card communicating with the robot to the 192.168.54.X network segment, recommended 192.168.54.111. Experienced users can configure the network environment themselves.

Configuration Steps

1. Connect one end of the Ethernet cable to the robot and the other end to the user computer. The robot's onboard computer IP addresses are 192.168.54.110 (cerebellum computing board) and 192.168.54.119 (brain computing board), so the computer IP needs to be set to the same network segment, recommended 192.168.54.111.

2. To test if the communication connection is normal, you can test with ping:

3. Check the network card name corresponding to the 192.168.54.111 address by using the ifconfig command to view the network card name, as shown in the figure:

Assuming the network port connecting the SDK secondary development PC to the robot is enp0s31f6, the following configuration is needed for SDK to communicate with the robot at the low level:

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

Installation and Compilation

The following steps assume the working directory is /home/magicbot/workspace

Install magicbot-z1_sdk:

Installation steps: Enter the magicbot-z1_sdk directory and execute the following commands step by step to install the SDK to the /opt/magic_robotics/magic_z1_sdk directory for easy find_package retrieval for secondary development program compilation and linking:

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

Example Compilation

Compilation steps: Enter the magicbot-z1_sdk directory and execute the following commands step by step to generate example executable programs in the build directory:

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

Example Programs

In the magicbot-z1_sdk/build directory:

• Audio Example:
  • audio_example
• Sensor Example:
  • sensor_example
• Status Monitoring Example:
  • monitor_example
• Low-Level Motion Control Example:
  • low_level_motion_example
• High-Level Motion Control Example:
  • high_level_motion_example

Notice: Among these, the high-level motion control examples have sequential dependencies (recovery stand -> balance stand -> execute trick actions/remote control)

Enter Debug Mode:

Follow the operation procedures to ensure the robot enters debug mode

Run Examples

Enter the magicbot-z1_sdk/build directory and execute the following commands:

cd /home/magicbot/workspace/magicbot-z1_sdk/build
# Environment configuration
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 control example
./audio_example

# Sensor control example
./sensor_example

# State monitoring example
./monitor_example

# Low-level motion control example
./low_level_motion_example

# High-level motion control example
./high_level_motion_example

Python Example Programs

In the magicbot-z1_sdk/example/python directory:

• Audio Example:
  • audio_example.py
• Sensor Example:
  • sensor_example.py
• Status Monitoring Example:
  • monitor_example.py
• Low-Level Motion Control Example:
  • low_level_motion_example.py
• High-Level Motion Control Example:
  • high_level_motion_example.py

Notice: Among these, the high-level motion control examples have sequential dependencies (recovery stand -> balance stand -> execute trick actions/remote control)

Enter Debug Mode:

Follow the operation procedures to ensure the robot enters debug mode

Run Examples

Enter the magicbot-z1_sdk/example/python directory and execute the following commands:

cd /home/magicbot/workspace/magicbot-z1_sdk/example/python
# Environment configuration
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

# Audio control example
python3 audio_example.py

# Sensor control example
python3 sensor_example.py

# State monitoring example
python3 monitor_example.py

# Low-level motion control example
python3 low_level_motion_example.py

# High-level motion control example
python3 high_level_motion_example.py

Get Python API help information:

# Environment configuration
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.
# Import Magic Z1 python SDK interface
>>> import magicbot_z1_python
# View all interface information             
>>> help(magicbot_z1_python)
# View CameraInfo structure information 
>>> help(magicbot_z1_python.CameraInfo)
# View HighLevelMotionController object information 
>>> help(magicbot_z1_python.HighLevelMotionController)
# View LowLevelMotionController object information 
>>> help(magicbot_z1_python.LowLevelMotionController)
# View SensorController object information 
>>> help(magicbot_z1_python.SensorController)
# View AudioController object information 
>>> help(magicbot_z1_python.AudioController)
# View StateMonitor object information 
>>> help(magicbot_z1_python.StateMonitor)

For example, if you want to view the TrickAction enumeration values:

$ 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_z1_python
>>> help(magicbot_z1_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.

Others

SDK Configuration File

The SDK will generate its default configuration file in the /tmp directory by default during runtime. If the configuration file already exists, it will use the existing configuration:

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

SDK Logs

The SDK's internal logs is generated in the /tmp/logs directory by default during runtime:

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