AIMA开放平台文档中心AimDK A3-ultra

7.3 Microphone Management

7.3 Microphone Management

7.3.1 Overview

By default, the robot supports two different microphones as interaction input sources: the external microphone (Shike lavalier microphone) and the built-in microphone (the robot's onboard microphone). In addition, Silent Mode can be enabled to disable interaction. Users can switch microphones and configure Silent Mode through AimMaster, and we also provide RPC interfaces for microphone source switching and Silent Mode configuration.

In addition, we provide raw microphone audio output capabilities, including audio data processed with onboard noise reduction, echo cancellation, and VAD. After disabling AgiBot's own interaction pipeline, users can obtain microphone audio through this interface and integrate it into a custom interaction system.

It should be noted that Silent Mode is an operating state within Normal Mode and supports flexible switching without restarting the agent.

7.3.2 Set Silent Mode RPC Interface

Interface Namepb:/aimdk.protocol.AgentControlService/SetVoiceEnable
Function OverviewSet Silent Mode
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/SetVoiceEnable
Input Parameters
text
{
  "enable_voice": false
}
  • enable_voice: Set to false to enable Silent Mode, set to true for Normal Mode
Output Parameters
text
{
  "header": {
    "code": "0",
    "msg": "SetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "state": "CommonState_UNKNOWN"
}
  • state: No need to pay attention to this field
Example Scriptexamples/agent/SetVoiceEnable.sh
Remarks

7.3.3 Query Silent Mode RPC Interface

Interface Namepb:/aimdk.protocol.AgentControlService/GetVoiceEnable
Function OverviewQuery Silent Mode Status
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/GetVoiceEnable
Input Parameters
text
{}
Output Parameters
text
{
  "header": {
    "code": "0",
    "msg": "GetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "enable_voice": true
}
  • enable_voice: Set to false to enable Silent Mode, set to true for Normal Mode
Example Scriptexamples/agent/GetVoiceEnable.sh
Remarks

7.3.4 Set Interaction Operation Mode RPC Interface

Interface Namepb:/aimdk.protocol.AgentControlService/SetAgentPropertiesRequest
Function OverviewSet Interaction Operation Mode
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/SetAgentPropertiesRequest
Input Parameters
text
{
  "contents": {
    "properties": {
      "2": "only_voice"
    }
  }
}
Modes:
  • only_voice: Only output noise-reduced microphone audio /agent/process_audio_output, subsequent pipeline is completely disconnected
  • normal: Standard operation mode, interaction runs normally
Output Parameters
text
{
  "state": "CommonState_UNKNOWN"
}
Example Scriptexamples/agent/SetAgentPropertiesRequest.sh
Remarks
  • Requires a robot reboot to take effect after calling
  • It is normal for the return value to be CommonState_UNKNOWN after calling. You can call the GetAgentPropertiesRequest interface to check if the interaction mode switch was successful

7.3.5 Get Interaction Operation Mode RPC Interface

Interface Namepb:/aimdk.protocol.AgentControlService/GetAgentPropertiesRequest
Function OverviewQuery Interaction Operation Mode
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/GetAgentPropertiesRequest
Input Parameters
text
{"property_ids": [2]}
Output Parameters
text
{
  "contents": {
    "properties": {
      "2": "only_voice"
    }
  }
}
Modes:
  • only_voice: Only output noise-reduced microphone audio /agent/process_audio_output, subsequent pipeline is completely disconnected
  • normal: Standard operation mode, interaction runs normally
Example Scriptexamples/agent/GetAgentPropertiesRequest.sh
Remarks

7.3.6 Noise-Reduced Microphone Audio Topic Interface

Interface Name/agent/process_audio_output
Function OverviewNoise-Reduced Microphone Audio Interface
Interface Type ROS2 Topic
Output Parameters
text
{
  "stream_id": 2,
  "vad_state": "AUDIO_VAD_STATE_PROCESSING",
  "audio_data": "..."
}
  • stream_id: Microphone identifier, 1 for built-in mic, 2 for external mic
  • vad_state: Voice activity detection status
    • AUDIO_VAD_STATE_NONE = 0
    • AUDIO_VAD_STATE_BEGIN = 1
    • AUDIO_VAD_STATE_PROCESSING = 2
    • AUDIO_VAD_STATE_END = 3
  • audio_data: Audio byte stream data
Example Scriptexamples/agent/get_voice.py
Remarks
  • The ROS2 message type for this message is ros2_plugin_proto/msg/RosMsgWrapper, requires sourcing prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash before use.
  • The built-in microphone does not include audio data in the start and end frames, which are only markers; the external microphone includes audio data.

7.3.7 Wake-Up Result Reporting

Interface Name /agent/wakeup
Function OverviewWake-Up Result Reporting
Interface Type ROS2 Topic
Output Parameters
text
{
    "language":"zh",
    "keyword":"远征远征"，
    "timestamp":"1768812507657",
    "confidence":1.0,
    "wakeup_id":"event_wMXK9pT05JMXeRAOSc706",
    "is_success":true,
    "wakeup_type":"WAKEUP_NORMAL"
}
  • confidence: Speech matching confidence, numerical value between 0-1
  • Keyword: Wake-up word
  • language: Currently only supports Chinese
  • wakeup_type:
    • WAKEUP_UNKNOWN : Wake-up with unknown source or status (placeholder/exception scenario)
    • WAKEUP_NORMAL : Normal voice wake-up, for example user speaks default wake-up word.
    • WAKEUP_CUSTOM_TRIGGERED : Wake-up triggered by custom method, such as custom wake-up word or external event.
Example Scriptexamples/agent/get_wakeup_result.py
Remarks
  • The ROS2 message type for this message is ros2_plugin_proto/msg/RosMsgWrapper, requires sourcing prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash before use.

7.3.8 Built-in and External Microphone Switching RPC Interface

Interface Namepb:/aimdk.protocol.HalAudioService/SetMicSourceRequest
OverviewSwitch the microphone source between the built-in microphone and the external microphone
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.HalAudioService/SetMicSourceRequest
Input
text
{
  "mic_source": 1
}
  • mic_source: 0 indicates the built-in microphone, 1 indicates the external microphone, and all other values are invalid.
Output
text
{
  "header": {
    "code": "0",
    "msg": "SetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "state": "CommonState_UNKNOWN"
}
  • state: This field can be ignored.
Example Scriptexamples/agent/SetMicSource.sh
Remarks

7.3.9 Built-in and External Microphone Status Query RPC Interface

Interface Namepb:/aimdk.protocol.HalAudioService/GetMicSourceRequest
OverviewGet the microphone source currently in use
Interface Type HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.HalAudioService/GetMicSourceRequest
Input
text
{}
Output
text
{
  "header": {
    "code": "0",
    "msg": "Get mic source successfully",
    "trace_id": "",
    "domin": ""
  },
  "mic_source": 0
}
  • mic_source: 0 indicates the built-in microphone, 1 indicates the external microphone, and all other values are invalid.
Example Scriptexamples/agent/GetMicSource.sh
Remarks