English

简体中文

English

简体中文

Appearance

Quick Start

About 1122 wordsAbout 4 min

2025-05-29

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 environments.

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 for 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. Execute sudo sysctl -p to apply 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's computer and robot switch to a unified network. It is recommended that new users connect their computer to the robot switch using an Ethernet cable and set the network card communicating with the robot to the 192.168.55.X network segment, preferably 192.168.55.10. Experienced users can configure the network environment themselves.

Assuming the SDK development PC is connected to the robot through network interface eno1, the following configuration is needed for SDK to communicate with the robot's underlying system:

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

Configuration Steps

  1. Connect one end of the Ethernet cable to the robot and the other end to the user's computer. The robot's onboard computer IP address is 192.168.55.200, so the computer IP needs to be set to the same network segment, preferably 192.168.55.10. Network Configuration

  2. To test if the communication connection is normal, you can use ping for testing: Network Diagnostics

  3. After connectivity is established, execute the following commands:

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

Installation and Compilation

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

Install magicdog-sdk

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

The above commands will install magicdog_sdk to the /opt/magic_robotics/magicdog_sdk directory

Example Compilation

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

After running the above commands, if the progress reaches 100% without errors, it means compilation was successful.

Compilation Results

Import magicdog-sdk in User Modules

If users need to import magicdog-sdk in their own modules, they can refer to example/cmake_example/CMakeLists.txt

C++ Example Programs

In the magicdog_sdk/build directory:

  • Audio Examples:
    • audio_example
  • Sensor Examples:
    • sensor_example
  • State Monitoring Examples:
    • monitor_example
  • Low-level Motion Control Examples:
    • low_level_motion_example
  • High-level Motion Control Examples:
    • high_level_motion_example

Enter Debug Mode:

Follow the operation procedures to ensure the robot enters debug mode

Run Examples

Enter the magicdog_sdk/build directory and execute the following commands:

cd /home/magicbot/workspace/magicdog_sdk/build
# Environment configuration
sudo ifconfig eno1 multicast
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev eno1
export LD_LIBRARY_PATH=/opt/magic_robotics/magicdog_sdk/lib:$LD_LIBRARY_PATH

# Audio example
./audio_example

# Sensor 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 magicdog_sdk/example/python directory:

  • Audio Examples:
    • audio_example.py
  • Sensor Examples:
    • sensor_example.py
  • State Monitoring Examples:
    • monitor_example.py
  • Low-level Motion Control Examples:
    • low_level_motion_example.py
  • High-level Motion Control Examples:
    • high_level_motion_example.py

Enter Debug Mode:

Follow the operation procedures to ensure the robot enters debug mode

Run Examples

Enter the magicdog_sdk/example/python directory and execute the following commands:

cd /home/magicbot/workspace/magicdog_sdk/example/python/

# Environment configuration
sudo ifconfig eno1 multicast
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev eno1
export PYTHONPATH=/opt/magic_robotics/magicdog_sdk/lib:$PYTHONPATH
export LD_LIBRARY_PATH=/opt/magic_robotics/magicdog_sdk/lib:$LD_LIBRARY_PATH

# Audio example
python3 audio_example.py

# Sensor 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

Note: Manually executing sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev eno1 only takes effect once. After system restart or network cable disconnection, it needs to be executed again.

Get Python API help information:

cd /home/magicbot/workspace/magicdog_sdk/example/python
# Environment configuration
export PYTHONPATH=/opt/magic_robotics/magicdog_sdk/lib:$PYTHONPATH
export LD_LIBRARY_PATH=/opt/magic_robotics/magicdog_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 Magicdog Python SDK interface
>>> import magicdog_python
# View all interface information             
>>> help(magicdog_python)
# View CameraInfo structure information 
>>> help(magicdog_python.CameraInfo)
# View HighLevelMotionController object information 
>>> help(magicdog_python.HighLevelMotionController)
# View LowLevelMotionController object information 
>>> help(magicdog_python.LowLevelMotionController)
# View SensorController object information 
>>> help(magicdog_python.SensorController)
# View AudioController object information 
>>> help(magicdog_python.AudioController)
# View StateMonitor object information 
>>> help(magicdog_python.StateMonitor)

For example, if you want to view the enumeration values of the trick action 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 magicdog_python
>>> help(magicdog_python.TrickAction)

Help on class TrickAction in module magicdog_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: magicdog_python.TrickAction, /) -> int
 |  
 |  __init__(...)
 |      __init__(self: magicdog_python.TrickAction, value: typing.SupportsInt) -> None
 |  
 |  __int__(...)
 |      __int__(self: magicdog_python.TrickAction, /) -> int
 |  
 |  __ne__(...)
 |      __ne__(self: object, other: object, /) -> bool
 |  
 |  __repr__(...)
 |      __repr__(self: object, /) -> str
 |  
 |  __setstate__(...)
 |      __setstate__(self: magicdog_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_ACT_CUTE = <TrickAction.ACTION_ACT_CUTE: 46>
 |  
 |  ACTION_BACK_FLIP = <TrickAction.ACTION_BACK_FLIP: 41>
 |  
 |  ACTION_BACK_HOME = <TrickAction.ACTION_BACK_HOME: 110>
 |  
 |  ACTION_BOXING = <TrickAction.ACTION_BOXING: 47>
 |  
 |  ACTION_CHEER_UP = <TrickAction.ACTION_CHEER_UP: 35>
 |  
 |  ACTION_DANCE = <TrickAction.ACTION_DANCE: 115>
 |  
 |  ACTION_DANCE2 = <TrickAction.ACTION_DANCE2: 91>
 |  
 |  ACTION_EMERGENCY_STOP = <TrickAction.ACTION_EMERGENCY_STOP: 101>
 |  
 |  ACTION_FRONT_FLIP = <TrickAction.ACTION_FRONT_FLIP: 42>
 |  
 |  ACTION_HAPPY_NEW_YEAR = <TrickAction.ACTION_HAPPY_NEW_YEAR: 105>
 |  
 |  ACTION_HIGH_FIVES = <TrickAction.ACTION_HIGH_FIVES: 36>
 |  
 |  ACTION_HIGH_JUMP = <TrickAction.ACTION_HIGH_JUMP: 38>
 |  
 |  ACTION_IMITATE = <TrickAction.ACTION_IMITATE: 32>
 |  
 |  ACTION_JUMP_FRONT = <TrickAction.ACTION_JUMP_FRONT: 45>
 |  
 |  ACTION_JUMP_JACK = <TrickAction.ACTION_JUMP_JACK: 30>
 |  
 |  ACTION_LEAP_FROG = <TrickAction.ACTION_LEAP_FROG: 40>
 |  
 |  ACTION_LEAVE_HOME = <TrickAction.ACTION_LEAVE_HOME: 111>
 |  
 |  ACTION_LEFT_SIDE_SOMERSAULT = <TrickAction.ACTION_LEFT_SIDE_SOMERSAULT...
 |  
 |  ACTION_LIE_DOWN = <TrickAction.ACTION_LIE_DOWN: 102>
 |  
 |  ACTION_NONE = <TrickAction.ACTION_NONE: 0>
 |  
 |  ACTION_PUSH_UP = <TrickAction.ACTION_PUSH_UP: 34>
 |  
 |  ACTION_RANDOM_DANCE = <TrickAction.ACTION_RANDOM_DANCE: 49>
 |  
 |  ACTION_RECOVERY_STAND = <TrickAction.ACTION_RECOVERY_STAND: 103>
 |  
 |  ACTION_RIGHT_SIDE_SOMERSAULT = <TrickAction.ACTION_RIGHT_SIDE_SOMERSAU...
 |  
 |  ACTION_ROLL_ABOUT = <TrickAction.ACTION_ROLL_ABOUT: 116>
 |  
 |  ACTION_SCRATCH = <TrickAction.ACTION_SCRATCH: 37>
 |  
 |  ACTION_SHAKE_HEAD = <TrickAction.ACTION_SHAKE_HEAD: 33>
 |  
 |  ACTION_SHAKE_LEFT_HAND = <TrickAction.ACTION_SHAKE_LEFT_HAND: 118>
 |  
 |  ACTION_SHAKE_RIGHT_HAND = <TrickAction.ACTION_SHAKE_RIGHT_HAND: 117>
 |  
 |  ACTION_SIDE_SOMERSAULT = <TrickAction.ACTION_SIDE_SOMERSAULT: 48>
 |  
 |  ACTION_SIT_DOWN = <TrickAction.ACTION_SIT_DOWN: 119>
 |  
 |  ACTION_SLOW_GO_BACK = <TrickAction.ACTION_SLOW_GO_BACK: 109>
 |  
 |  ACTION_SLOW_GO_FRONT = <TrickAction.ACTION_SLOW_GO_FRONT: 108>
 |  
 |  ACTION_SPACE_WALK = <TrickAction.ACTION_SPACE_WALK: 31>
 |  
 |  ACTION_SPIN_JUMP_LEFT = <TrickAction.ACTION_SPIN_JUMP_LEFT: 43>
 |  
 |  ACTION_SPIN_JUMP_RIGHT = <TrickAction.ACTION_SPIN_JUMP_RIGHT: 44>
 |  
 |  ACTION_STOMP = <TrickAction.ACTION_STOMP: 29>
 |  
 |  ACTION_STRETCH = <TrickAction.ACTION_STRETCH: 28>
 |  
 |  ACTION_SWING_BODY = <TrickAction.ACTION_SWING_BODY: 27>
 |  
 |  ACTION_SWING_DANCE = <TrickAction.ACTION_SWING_DANCE: 39>
 |  
 |  ACTION_TURN_AROUND = <TrickAction.ACTION_TURN_AROUND: 112>
 |  
 |  ACTION_WIGGLE_HIP = <TrickAction.ACTION_WIGGLE_HIP: 26>
 |  
 |  ----------------------------------------------------------------------
 |  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 generates its default configuration file in the /tmp directory at runtime. If the configuration file already exists, it will use the existing configuration:

$ ls /tmp/magicdog_mjrrt.yaml
/tmp/magicdog_mjrrt.yaml

SDK Logs

The internal log information of the SDK at runtime is generated by default in the /tmp/logs directory:

$ ls /tmp/logs/magicdog_sdk.log
/tmp/logs/magicdog_sdk.log