GDK Interaction Interface Documentation (Python)¶

Overview¶

The Interaction module provides the G02 robot with voice interaction, display control, audio playback, and other functionality. Through the Python interface, developers can conveniently implement voice control, TTS playback, audio/video playback, and display control for the robot, suitable for voice interaction, multimedia display, human-robot interaction, and many other scenarios.

Notes¶

The interaction interface depends on a cross-network-segment communication module, so if this class of interface is used in an isolated environment (such as a Docker container), you need to ensure the container can modify the host machine's network configuration (add the --privileged parameter when starting the container).

Interface Description¶

Interaction Class¶

This class encapsulates the main functional interfaces of robot interaction.

1. `set_language(language)`¶

Function: Set the voice language
Parameters:

Parameter	Type	Description
`language`	`Language`	Language type; `Language.kLanguageChinese` denotes Chinese, `Language.kLanguageEnglish` denotes English

Return value: None; throws an exception on failure

Language enum values:

Enum value	Description
`Language.kLanguageChinese`	Chinese
`Language.kLanguageEnglish`	English

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

interaction = agibot_gdk.Interaction()
time.sleep(1)  # Wait for initialization to complete

# Set the language to Chinese
try:
    interaction.set_language(agibot_gdk.Language.kLanguageChinese)
    print("Language set successfully")
except Exception as e:
    print(f"Failed to set language: {e}")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
    exit(1)
print("GDK released successfully")

2. `set_call_mode(is_on)`¶

Function: Set the call mode
Parameters:

Parameter	Type	Description
`is_on`	`bool`	`True` enables call mode, `False` disables call mode

Return value: None; throws an exception on failure
Notes:
After enabling call mode, the system automatically enters the wakeup state; after disabling call mode, it automatically exits the wakeup state — no wake word or end word is needed
In call mode, the user's spoken input can be captured, and the corresponding recognized text can be obtained through the interface
In call mode, you can call get_asr_text() or register a callback via register_callback() to obtain the recognized text of the user's spoken input
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Enable call mode
try:
    interaction.set_call_mode(True)
    print("Call mode enabled successfully")
except Exception as e:
    print(f"Failed to enable call mode: {e}")

# Disable call mode
try:
    interaction.set_call_mode(False)
    print("Call mode disabled successfully")
except Exception as e:
    print(f"Failed to disable call mode: {e}")

agibot_gdk.gdk_release()

3. `set_volume(volume)`¶

Function: Set the volume
Parameters:

Parameter	Type	Description
`volume`	`int`	Volume value, typically ranging from 0-100

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Set the volume to 50
try:
    interaction.set_volume(50)
    print("Volume set successfully")
except Exception as e:
    print(f"Failed to set volume: {e}")

agibot_gdk.gdk_release()

4. `set_wakeup_switch(is_on)`¶

Function: Set the wakeup switch
Parameters:

Parameter	Type	Description
`is_on`	`bool`	`True` enables wakeup, `False` disables wakeup

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Enable the wakeup functionality
try:
    interaction.set_wakeup_switch(True)
    print("Wakeup functionality enabled successfully")
except Exception as e:
    print(f"Failed to set wakeup switch: {e}")

agibot_gdk.gdk_release()

5. `set_audio_switch(is_on)`¶

Function: Set the audio switch
Parameters:

Parameter	Type	Description
`is_on`	`bool`	`True` enables audio, `False` disables audio

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Enable the audio functionality
try:
    interaction.set_audio_switch(True)
    print("Audio functionality enabled successfully")
except Exception as e:
    print(f"Failed to set audio switch: {e}")

agibot_gdk.gdk_release()

6. `set_display_switch(is_on)`¶

Function: Set the display switch
Parameters:

Parameter	Type	Description
`is_on`	`bool`	`True` enables the display, `False` disables the display

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Enable the display functionality
try:
    interaction.set_display_switch(True)
    print("Display functionality enabled successfully")
except Exception as e:
    print(f"Failed to set display switch: {e}")

agibot_gdk.gdk_release()

7. `play_tts(text)`¶

Function: Play TTS (text-to-speech)
Parameters:

Parameter	Type	Description
`text`	`str`	The text content to play

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Play TTS
try:
    interaction.play_tts("Hello, I am Genie G2")
    print("TTS playback started successfully")
    time.sleep(3)  # Wait for playback to complete
except Exception as e:
    print(f"Failed to play TTS: {e}")

agibot_gdk.gdk_release()

8. `play_audio(audio_path)`¶

Function: Play an audio file
Parameters:

Parameter	Type	Description
`audio_path`	`str`	Path to the audio file

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Play an audio file
try:
    interaction.play_audio("/path/to/audio.wav")
    print("Audio playback started successfully")
    time.sleep(5)  # Wait for playback to complete
except Exception as e:
    print(f"Failed to play audio: {e}")

agibot_gdk.gdk_release()

9. `play_video(video_path, loop_count)`¶

Function: Play a video file
Parameters:

Parameter	Type	Description
`video_path`	`str`	Path to the video file
`loop_count`	`int`	Number of loop playback repetitions; -1 means infinite loop

Return value: None; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Play a video file, looping once
try:
    interaction.play_video("/path/to/video.mp4", 1)
    print("Video playback started successfully")
    time.sleep(10)  # Wait for playback to complete
except Exception as e:
    print(f"Failed to play video: {e}")

# Play in an infinite loop
try:
    interaction.play_video("/path/to/video.mp4", -1)
    print("Video started looping")
except Exception as e:
    print(f"Failed to play video: {e}")

agibot_gdk.gdk_release()

10. `get_func_status()`¶

Function: Get the voice functionality status
Parameters: None
Return value: A VoiceFuncStatus object, containing the following attributes:

Attribute	Type	Description
`func_status`	`int`	Functionality status
`wakeup_status`	`int`	Wakeup status
`requester`	`str`	Requester
`wakeup_enabled`	`bool`	Whether the wakeup functionality is enabled
`display_enabled`	`bool`	Whether the display functionality is enabled
`audio_enabled`	`bool`	Whether the audio functionality is enabled
`en_settings`	`VoiceSettings`	English voice settings
`cn_settings`	`VoiceSettings`	Chinese voice settings
`timestamp`	`int`	Timestamp (nanoseconds)

VoiceSettings object attributes:

Attribute	Type	Description
`volume`	`int`	Volume
`speech_rate`	`float`	Speech rate
`voice_tone`	`str`	Voice tone
`is_curr_setting`	`bool`	Whether this is the current setting

Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Get the functionality status
try:
    func_status = interaction.get_func_status()
    print("Functionality status information:")
    print(f"  Functionality status: {func_status.func_status}")
    print(f"  Wakeup status: {func_status.wakeup_status}")
    print(f"  Requester: {func_status.requester}")
    print(f"  Wakeup functionality enabled: {func_status.wakeup_enabled}")
    print(f"  Display functionality enabled: {func_status.display_enabled}")
    print(f"  Audio functionality enabled: {func_status.audio_enabled}")
    print(f"  Chinese settings - volume: {func_status.cn_settings.volume}, "
          f"speech rate: {func_status.cn_settings.speech_rate}, "
          f"voice tone: {func_status.cn_settings.voice_tone}")
    print(f"  English settings - volume: {func_status.en_settings.volume}, "
          f"speech rate: {func_status.en_settings.speech_rate}, "
          f"voice tone: {func_status.en_settings.voice_tone}")
    print(f"  Timestamp: {func_status.timestamp}")
except Exception as e:
    print(f"Failed to get functionality status: {e}")

agibot_gdk.gdk_release()

11. `get_asr_text()`¶

Function: Get the ASR (Automatic Speech Recognition) text
Parameters: None
Return value: str, the recognized text content; throws an exception on failure
Example:

import agibot_gdk
import time

if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)

interaction = agibot_gdk.Interaction()
time.sleep(1)

# Get the ASR text
try:
    asr_text = interaction.get_asr_text()
    print(f"Recognized text: {asr_text}")
except Exception as e:
    print(f"Failed to get ASR text: {e}")

agibot_gdk.gdk_release()

12. `register_callback(type, callback)`¶

Function: Register a callback function
Parameters:

Parameter	Type	Description
`type`	`str`	Callback type
`callback`	`function`	Callback function

Return value: None; throws an exception on failure
Currently supported callback types:
get_asr_text: The callback function's parameter type is str; in the wakeup state, when new speech input is recognized, the callback function is invoked and passed the recognized text content
Other functionality callbacks are not yet supported

13. `unregister_callback(type)`¶

Function: Unregister a callback function
Parameters:

Parameter	Type	Description
`type`	`str`	Callback type

Return value: None; throws an exception on failure
Currently supported callback types:
get_asr_text: Unregisters the callback function; after unregistering, the callback function will not be invoked when new speech input is recognized in the wakeup state
Other functionality callbacks are not yet supported
Example:

  import agibot_gdk
  import time

  class ASRHandler:
      def __init__(self, interaction):
          self.interaction = interaction

      def callback(self, text):
          print(f"callback text: {text}")

  if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
      print("GDK initialization failed")
      exit(1)

  interaction = agibot_gdk.Interaction()
  time.sleep(1)

  # Enable call mode
  try:
      interaction.set_call_mode(True)
      print("Call mode enabled successfully")
  except Exception as e:
      print(f"Failed to enable call mode: {e}")

  asr_handler = ASRHandler(interaction)

  # Register the callback function
  try:
      interaction.register_callback("get_asr_text", asr_handler.callback)
      print("Callback function registered successfully")
  except Exception as e:
      print(f"Failed to register callback function: {e}")

  try:
      while True:
          time.sleep(1)
  except KeyboardInterrupt:
      interaction.set_call_mode(False)
      interaction.unregister_callback("get_asr_text")
      agibot_gdk.gdk_release()

Usage Notes¶

GDK initialization: You must call agibot_gdk.gdk_init() to initialize the GDK system before using the Interaction functionality
GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
Initialization wait: After creating an Interaction object, it is recommended to wait 1 second to ensure the DDS connection is established
Exception handling: All interfaces throw an exception on failure, so use try-except for exception handling
File paths: When playing audio and video, make sure the file path is correct and the file exists
Language setting: Setting the language affects the language used by TTS, so set it according to actual needs
Volume range: Pay attention to a reasonable range when setting the volume, avoiding values too high or too low
Loop playback: When looping video playback, use -1 to indicate an infinite loop, and remember to stop it in time
Status querying: Periodically query the functionality status to ensure each function is working properly
ASR text: When getting ASR text, make sure the speech recognition functionality is enabled
Call mode: In call mode, the user's spoken input can be captured, and the corresponding recognized text can be obtained through the interface
Registering callback functions: In call mode, you can call get_asr_text() or register a callback via register_callback() to obtain the recognized text of the user's spoken input

Application Scenarios¶

Voice interaction: Implementing the robot's speech recognition and speech synthesis functionality
Multimedia display: Playing audio and video content for information display
Human-robot interaction: Interacting with humans through voice and display
Status monitoring: Monitoring the voice functionality status to ensure the system is running normally
Multilingual support: Supporting switching between Chinese and English to adapt to different scenario needs
Volume control: Dynamically adjusting the volume to adapt to different environments
Functionality switches: Flexibly controlling functionality switches such as wakeup, audio, and display

GDK Interaction Interface Documentation (Python)¶

Overview¶

Notes¶

Interface Description¶

Interaction Class¶

1. set_language(language)¶

2. set_call_mode(is_on)¶

3. set_volume(volume)¶

4. set_wakeup_switch(is_on)¶

5. set_audio_switch(is_on)¶

6. set_display_switch(is_on)¶

7. play_tts(text)¶

8. play_audio(audio_path)¶

9. play_video(video_path, loop_count)¶

10. get_func_status()¶

11. get_asr_text()¶

12. register_callback(type, callback)¶

13. unregister_callback(type)¶