This example demonstrates how to use the MagicDog SDK to perform basic operations such as initialization, connecting to the robot, and audio control (getting volume, setting volume, TTS playback).

C++

Example file: audio_example.cpp

Reference documentation: C++ API/audio_reference.md

#include "magic_robot.h"

#include <unistd.h>
#include <csignal>

#include <iostream>

using namespace magic::dog;

magic::dog::MagicRobot robot;

void signalHandler(int signum) {
  std::cout << "Interrupt signal (" << signum << ") received.\n";

  robot.Shutdown();
  // Exit process
  exit(signum);
}

int main() {
  // Bind SIGINT (Ctrl+C)
  signal(SIGINT, signalHandler);

  std::string local_ip = "192.168.55.10";
  // Configure local IP address for direct network connection to machine and initialize SDK
  if (!robot.Initialize(local_ip)) {
    std::cerr << "Robot SDK initialization failed." << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Set RPC timeout to 5s
  robot.SetTimeout(5000);

  // Connect to robot
  auto status = robot.Connect();
  if (status.code != ErrorCode::OK) {
    std::cerr << "Connect robot failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Get audio controller
  auto& controller = robot.GetAudioController();

  // Get robot's current volume
  int get_volume = 0;
  status = controller.GetVolume(get_volume);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Get volume failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  std::cout << "Get volume success, volume: " << std::to_string(get_volume) << std::endl;

  // Set robot volume
  status = controller.SetVolume(7);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Set volume failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Verify if the set volume is correct
  status = controller.GetVolume(get_volume);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Get volume failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  std::cout << "Get volume success, volume: " << std::to_string(get_volume) << std::endl;

  // Play voice
  TtsCommand tts;
  tts.id = "100000000001";
  tts.content = "How's the weather today!";
  tts.priority = TtsPriority::HIGH;
  tts.mode = TtsMode::CLEARTOP;
  status = controller.Play(tts);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Play TTS failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Wait 2s
  usleep(5000000);

  // Stop voice playback
  status = controller.Stop();
  if (status.code != ErrorCode::OK) {
    std::cerr << "Stop TTS failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Wait 5s
  usleep(2000000);

  // Get voice configuration
  GetSpeechConfig get_speech_config;
  status = controller.GetVoiceConfig(get_speech_config);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Get voice config failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  std::cout << "Get voice config success, speaker_id: " << get_speech_config.speaker_config.selected.speaker_id
            << ", region: " << get_speech_config.speaker_config.selected.region
            << ", bot_id: " << get_speech_config.bot_config.selected.bot_id
            << ", is_front_doa: " << get_speech_config.dialog_config.is_front_doa
            << ", is_fullduplex_enable: " << get_speech_config.dialog_config.is_fullduplex_enable
            << ", is_enable: " << get_speech_config.dialog_config.is_enable
            << ", is_doa_enable: " << get_speech_config.dialog_config.is_doa_enable
            << ", speaker_speed: " << get_speech_config.speaker_config.speaker_speed
            << ", wakeup_name: " << get_speech_config.wakeup_config.name
            << ", custom_bot: " << get_speech_config.bot_config.custom_data.size() << std::endl;
  for (const auto& [key, value] : get_speech_config.bot_config.custom_data) {
    std::cout << "Custom bot data: " << key << ", " << value.name << std::endl;
  }

  // Set voice configuration
  SetSpeechConfig set_speech_config = ToSetSpeechConfig(get_speech_config);
  set_speech_config.wakeup_name = "Xiaomai";
  set_speech_config.is_doa_enable = false;
  set_speech_config.is_front_doa = false;
  set_speech_config.is_fullduplex_enable = false;
  set_speech_config.is_enable = true;

  status = controller.SetVoiceConfig(set_speech_config);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Set voice config failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  // Subscribe to raw voice data
  controller.SubscribeOriginVoiceData([](const std::shared_ptr<ByteMultiArray> data) {
    std::cout << "Received raw voice data, size: " << data->data.size() << std::endl;
  });
  // Subscribe to BF voice data
  controller.SubscribeBfVoiceData([](const std::shared_ptr<ByteMultiArray> data) {
    std::cout << "Received BF voice data, size: " << data->data.size() << std::endl;
  });

  // Control voice data stream
  status = controller.ControlVoiceStream(true, true);
  if (status.code != ErrorCode::OK) {
    std::cerr << "Control voice stream failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
  }

  // Wait 10s
  usleep(10000000);

  std::cout << "Close voice stream" << std::endl;

  // status = sensor.ControlVoiceStream(false, false);
  // if (status.code != ErrorCode::OK) {
  //   std::cerr << "control voice stream failed"
  //             << ", code: " << status.code
  //             << ", message: " << status.message << std::endl;
  // }

  // usleep(10000000);

  std::cout << "Disconnect robot" << std::endl;

  // Disconnect from robot
  status = robot.Disconnect();
  if (status.code != ErrorCode::OK) {
    std::cerr << "Disconnect robot failed"
              << ", code: " << status.code
              << ", message: " << status.message << std::endl;
    robot.Shutdown();
    return -1;
  }

  robot.Shutdown();

  return 0;
}

Python

Example file: audio_example.py

Reference documentation: Python API/audio_reference.md

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
MagicDog SDK Python Usage Example

This file demonstrates how to use MagicDog SDK Python bindings to control the robot.
"""

import sys
import time
import logging
from typing import Optional

logging.basicConfig(
    level=logging.INFO,  # Minimum log level
    format="%(asctime)s [%(levelname)s] %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)

try:
    import magicdog_python as magicdog
    from magicdog_python import TtsCommand, TtsPriority, TtsMode, GetSpeechConfig
    logging.info("Successfully imported MagicDog Python module!")
    # Print the path of imported magicdog_python
    logging.info(f"Imported magicdog_python path: {sys.path}")
except ImportError as e:
    logging.error(f"Import failed: {e}")
    logging.error("Please run build_python.sh to build Python bindings first")
    sys.exit(1)

def main():
    """Main function"""
    logging.info("MagicDog SDK Audio Python Example Program")
    
    local_ip = "192.168.55.10"
    robot = magicdog.MagicRobot()
    if not robot.initialize(local_ip):
        logging.error("Robot initialization failed")
        return

    robot.set_timeout(5000)
    if not robot.connect():
        logging.error("Robot connection failed")
        robot.shutdown()
        return
    
    logging.info("Robot connected successfully")
    
    audio_controller = robot.get_audio_controller()

    # Get current volume
    volume = audio_controller.get_volume()
    if volume != -1:
        logging.info(f"Current volume: {volume}")
    else:
        logging.error("Failed to get volume")

    # Set volume
    status = audio_controller.set_volume(50)
    if status.code != magicdog.ErrorCode.OK:
        logging.error(f"Failed to set volume: {status.message}")
        robot.shutdown()
        return
    
    # Get volume again to confirm successful setting
    volume = audio_controller.get_volume()
    if volume != -1:
        logging.info(f"Volume set successfully, current volume: {volume}")
    else:
        logging.error("Failed to get volume after setting")
    
    tts_command = TtsCommand()
    tts_command.id = "100000000002"
    tts_command.content = "How's the weather today!"
    tts_command.priority = TtsPriority.HIGH
    tts_command.mode = TtsMode.CLEARTOP
    status = audio_controller.play(tts_command)
    if status.code != magicdog.ErrorCode.OK:
        logging.error(f"Failed to play voice: {status.message}")
        robot.shutdown()
        return
    
    time.sleep(5)
    
    status = audio_controller.stop()
    if status.code != magicdog.ErrorCode.OK:
        logging.error(f"Failed to stop voice playback: {status.message}")
        robot.shutdown()
        return

    # Get voice configuration
    speech_config = audio_controller.get_voice_config()
    if speech_config:
        logging.info("Successfully got voice configuration:")
        logging.info(f"  TTS Type: {speech_config.tts_type}")
        # Print configuration details
        logging.info(f"  Configuration details:")
        
        if speech_config.speaker_config:
            speaker = speech_config.speaker_config
            logging.info(f"    Speaker configuration:")
            logging.info(f"      Data: {speaker.data}")
            logging.info(f"      Selected: {speaker.selected.speaker_id} {speaker.selected.region}")
            logging.info(f"      Speed: {speaker.speaker_speed}")
        
        if speech_config.bot_config:
            bot = speech_config.bot_config
            logging.info(f"    Bot configuration:")
            logging.info(f"      Data: ")
            # bot.data is a dictionary with string keys and values containing [id, name] lists
            for bot_id, bot_info in bot.data.items():
                logging.info(f"        Bot ID: {bot_id}")
                logging.info(f"          Name: {bot_info.name}")
                logging.info(f"          Workflow ID: {bot_info.workflow}")
                
            logging.info(f"      Custom data: {bot.custom_data}")
            logging.info(f"      Selected: {bot.selected.bot_id}")
        
        if speech_config.wakeup_config:
            wakeup = speech_config.wakeup_config
            logging.info(f"    Wakeup configuration:")
            logging.info(f"      Name: {wakeup.name}")
            logging.info(f"      Data: {wakeup.data}")
        
        if speech_config.dialog_config:
            dialog = speech_config.dialog_config
            logging.info(f"    Dialog configuration:")
            logging.info(f"      Front DOA: {dialog.is_front_doa}")
            logging.info(f"      Full duplex enabled: {dialog.is_fullduplex_enable}")
            logging.info(f"      Enabled: {dialog.is_enable}")
            logging.info(f"      DOA enabled: {dialog.is_doa_enable}")
    else:
        logging.error("Failed to get voice configuration")   

    def subscribe_origin_voice_data(data):
        logging.info(f"Received raw voice data: {len(data.data)}")
    def subscribe_bf_voice_data(data):
        logging.info(f"Received BF voice data: {len(data.data)}")

    audio_controller.subscribe_origin_voice_data(subscribe_origin_voice_data)
    audio_controller.subscribe_bf_voice_data(subscribe_bf_voice_data)

    audio_controller.control_voice_stream(True, True)

    time.sleep(10)

    audio_controller.control_voice_stream(False, False)

    # Avoid unprocessed buffered data in lcm
    time.sleep(10)

    robot.disconnect()
    robot.shutdown()
    logging.info("\nExample program execution completed!")

if __name__ == "__main__":
    main()

Running Instructions

1. Environment Setup:

# Set environment variables
export PYTHONPATH=/opt/magic_robotics/magicdog_sdk/lib:$PYTHONPATH
export LD_LIBRARY_PATH=/opt/magic_robotics/magicdog_sdk/lib:$LD_LIBRARY_PATH

2. Run Example:

# C++
./audio_example
# Python
python3 audio_example.py

3. Stop the Program:

• Press Ctrl+C to safely stop the program
• The program will automatically clean up all resources