Skip to main content
Version: V2.0.5.1

🆕 8.9 Voice (Lyre Voice Package)

8.9.1 Packages and Installation Locations​

The Lyre voice solution consists of three packages: lyre_ros2, lyre_msgs, and lyre_examples.

  • lyre_ros2: Functional package for voice capabilities, installed on the Orin controller.
  • lyre_msgs: Interface definition package. It is installed both under the ros2ws directory on x86 and under the lyre_ros2 directory.
  • lyre_examples: Example programs demonstrating how to call the voice interfaces, installed under the ros2ws directory on x86.

Directory structure:

├── ros2ws/                # x86
│ ├── install
│ │ ├── lyre_msgs          # Interface definitions
│ │ │ ├── README.md        # SDK development documentation
│ │ ├── lyre_examples      # Interface usage examples
│
├── lyre_ros2/             # Orin
│ ├── install
│ │ ├── lyre_msgs          # Interface definitions
│ │ │ ├── README.md        # SDK development documentation
│ │ ├── lyre               # Functional package
│ ├── scripts
│ │ ├── setup_network.sh   # Network configuration script
│ │ ├── setup_systemd.sh   # Auto‑start service deployment script
│ │ ├── reset_systemd.sh   # Auto‑start service removal script
│ ├── README.md            # User manual
│ ├── QAs.md               # FAQ

In summary:

  • The solution includes the lyre package, the lyre_msgs package, and the lyre_examples package.
  • On Orin, the lyre_ros2 directory contains the lyre and lyre_msgs packages.
  • On x86, the ros2ws directory contains the lyre_msgs and lyre_examples packages.

8.9.2 Voice Interaction Function​

The robot supports voice interaction. After the device is powered on, the voice interaction function is disabled by default. It can be enabled via the remote controller.

8.9.2.1 Remote Controller Switch​

  • Place the E, G, H keys in the middle position; move the F key upward.
  • Long‑press the A button to enable or disable the voice interaction function.

8.9.2.2 Voice Dialogue Method​

Stand approximately 1.5 meters in front of the robot, facing the camera above the microphone on the robot’s chest, and converse with the robot.

8.9.3 Starting the Voice Package​

The ROS package name for the voice system is lyre, and the corresponding systemd service name is also lyre.

8.9.3.1 Manually Starting the Voice Dialogue ROS Node​

In the lyre_ros2 package, use the following commands to start the voice dialogue ROS node:

cd lyre_ros2
source install/setup.bash
ros2 launch lyre chat.launch.py

Note: By default, the robot will automatically start the lyre node at boot. Only one lyre process is allowed to run at a time. Use the following command to check whether another lyre process is already running:

ps -ef | grep "ros2 launch lyre" | grep -v grep

If any output is shown, a lyre process is running. Use the following command to stop it:

pkill -INT -f "ros2 launch lyre"

Note: If systemd auto‑start has been configured for lyre, you must disable the auto‑start service before stopping the process; otherwise, the process you stop manually will be restarted automatically. See later sections for details.

8.9.3.2 Boot‑Time Auto‑Start Service​

By default, the lyre systemd service is configured to auto‑start at boot.

  • Check whether the lyre service auto‑starts at boot:

    systemctl is-enabled lyre

    If the output is enabled, the lyre service is configured to auto‑start.

  • Enable auto‑start for the lyre service:

    sudo systemctl enable lyre

  • Disable auto‑start for the lyre service:

    sudo systemctl disable lyre

8.9.4 Run Modes​

The Lyre voice package provides four run modes: play, asr, audio, and chat. Integrators can choose one according to their needs.

Note: Run modes are mutually exclusive. At any given time, only one of the four modes can be active.

  • play: Only audio playback–related functions are available.
  • asr: Only speech recognition–related functions are available.
  • audio: Both speech recognition and audio playback, including text‑to‑speech playback, are available.
  • chat: Speech recognition, audio playback, and full voice dialogue functions are available.

The unified command to start a given mode is:

ros2 launch lyre <mode>.launch.py

For example, to start the audio mode:

ros2 launch lyre audio.launch.py

To deploy a specific mode as a boot‑time auto‑start service:

The lyre_ros2 package provides the script setup_systemd.sh under lyre_ros2/scripts to configure auto‑start:

bash setup_systemd.sh <mode>  # [default: chat]

For example, to deploy the play mode as an auto‑start service:

bash setup_systemd.sh play

8.9.5 Interface Example Programs​

The lyre_examples package provides several C++ interface usage examples. Its directory structure is:

lyre_examples/
├── bin/              # Compiled executables for interface examples
│ ├── lyre_example_play_file_srv
├── cli/              # Shell scripts for interface example invocation
│ ├── call_play_file_srv.sh
│ ├── sub_play_progress_msg.sh
├── src/              # C++ source code for interface examples
│ ├── play_file_srv.cpp
├── res/              # Static resources
│ ├── test.mp3
├── CMakeLists.txt    # Example CMakeLists.txt
├── package.xml       # Example ROS package.xml

For each exposed voice interface, lyre_examples provides:

  • C++ example code
  • Corresponding compiled executable
  • Shell scripts to invoke the interface

These are placed respectively under src, bin, and cli.

To avoid confusion:

  • Executable names for demos are prefixed with lyre_example_.
  • Scripts subscribing to Topics are prefixed with sub_.
  • Scripts publishing Topics are prefixed with pub_.
  • Scripts calling Services are prefixed with call_.

For secondary development of C++ ROS 2 projects, you can:

  1. Import the lyre_msgs interfaces as shown in lyre_examples.
  2. Refer to the example code to complete your own feature implementations.

8.9.5.1 ROS Package Configuration​

<package format="3">
  <depend>lyre_msgs</depend>
</package>

8.9.5.2 CMake Configuration​

find_package(lyre_msgs REQUIRED)

ament_target_dependencies(
  <your_target>
  lyre_msgs
)

8.9.5.3 Build‑Time and Run‑Time Dependencies​

The lyre_msgs package is provided under both the ros2ws workspace on x86 and the lyre_ros2 workspace on Orin.
Before building or running your own ROS program, source lyre_msgs from these workspaces:

# x86
source ros2ws/install/setup.bash

# Orin
source lyre_ros2/install/setup.bash

8.9.6 Audio Playback Interfaces​

8.9.6.1 Play Local File (Service)​

If you know that a given audio file already exists on the controller running lyre_ros2, you can use the following ROS Service to play it:

# lyre_msgs/srv/PlayFile.srv
# Play an audio clip from a local file.
string SERVICE_NAME = /audio_play/play_file
string sid      # Stream identifier (unique per audio stream).
uint32 seq      # Sequence number (incremental per packet).
bool   last     # Last flag (true if this is the final packet).
bool   force    # Force playback (stop all running tasks and play immediately).
string path     # Absolute path to the audio file in the local file system.
---
int8 CODE_OK = 0
int8 CODE_INVALID_PARAMS = 1
int8 CODE_FAILED = -1
string sid      # Playback stream ID (generated internally if absent).
int8 code       # Status code.
string message  # Human‑readable status message.

For a C++ usage example, refer to play_file_srv in the lyre_examples package.

8.9.6.2 Play Remote File (Service)​

You can play an audio file hosted on the network using the following ROS Service:

# lyre_msgs/srv/PlayUrl.srv
# Play an audio clip from a file URL.
string SERVICE_NAME = /audio_play/play_url
string sid        # Stream identifier (unique per audio stream).
uint32 seq        # Sequence number (incremental per packet).
bool   last       # Last flag (true if this is the final packet).
bool   force      # Force playback (stop all running tasks and play immediately).
string url        # URL to the audio file in the network.
---
int8 CODE_OK = 0
int8 CODE_INVALID_PARAMS = 1
int8 CODE_FAILED = -1
string sid        # Playback stream ID (generated internally if absent).
int8   code       # Status code.
string message    # Human‑readable status message.

For a C++ usage example, refer to play_url_srv in the lyre_examples package.

8.9.6.3 Play Text (Service)​

If you need to access the audio playback service from another controller, you can use the following ROS Service to play a text string:

# lyre_msgs/srv/PlayText.srv
# Play an audio clip synthesized from text.
string SERVICE_NAME = /audio_play/play_text
string sid       # Stream identifier (unique per audio stream).
uint32 seq       # Sequence number (incremental per packet).
bool   last      # Last flag (true if this is the final packet).
bool   force     # Force playback (stop all running tasks and play immediately).
string text      # Text to be synthesized into speech.
string token     # System API (unavailable for applications).
string output    # System API (unavailable for applications).
---
int8 CODE_OK = 0
int8 CODE_INVALID_PARAMS = 1
int8 CODE_FAILED = -1
string sid       # Playback stream ID (generated internally if absent).
int8 code        # Status code.
string message   # Human‑readable status message.

For a C++ usage example, refer to play_text_srv in the lyre_examples package.

Note: This function is only available in the audio and chat run modes.

8.9.6.4 Listen for Playback Events (Topic)​

During audio playback, playback events are published on the following Topic:

# lyre_msgs/msg/PlayEvent.msg
# Events related to audio playback.
string TOPIC_NAME = /audio_play/event
int8 EVENT_STARTED = 0
int8 EVENT_COMPLETED = 1
int8 EVENT_STOPPED = 2
int8 EVENT_CANCELLED = 3
int8 EVENT_FAILED = 4
string sid
uint32 seq
int8 event
string message

For a C++ usage example, refer to play_event_msg in the lyre_examples package.

8.9.6.5 Listen for Playback Progress (Topic)​

During audio playback, playback progress and total duration (in seconds) are published on the following Topic:

# lyre_msgs/msg/PlayProgress.msg
# Audio playback progress.
string TOPIC_NAME = /audio_play/progress
string sid
uint32 seq
float64 position
float64 duration

For a C++ usage example, refer to play_progress_msg in the lyre_examples package.

8.9.6.6 Stop Audio Playback (Service)​

Use the following ROS Service to stop the current audio playback (non‑recoverable):

# lyre_msgs/srv/PlayStop.srv
# Stop the current audio playback task (cannot be resumed).
string SERVICE_NAME = /audio_play/stop
---

For a C++ usage example, refer to play_stop_srv in the lyre_examples package.

8.9.6.7 Pause Audio Playback (Service)​

Use the following ROS Service to pause the current audio playback (can be resumed later using the Resume service):

# lyre_msgs/srv/PlayPause.srv
# Pause the current audio playback task.
string SERVICE_NAME = /audio_play/pause
---

For a C++ usage example, refer to play_pause_srv in the lyre_examples package.

8.9.6.8 Resume Audio Playback (Service)​

Use the following ROS Service to resume playback of a paused audio stream:

# lyre_msgs/srv/PlayResume.srv
# Resume a paused audio playback task.
string SERVICE_NAME = /audio_play/resume
---

For a C++ usage example, refer to play_resume_srv in the lyre_examples package.

8.9.7 Speech Recognition Interfaces​

The device integrates a speech recognition module and provides ASR (Automatic Speech Recognition) capabilities.

8.9.7.1 Listen for Wake‑Up Events (Topic)​

When the wake‑up keyword is spoken near the device, a wake‑up event is triggered. The specific wake‑up keyword depends on the device model and is described in the user manual.

In code, you can listen for wake‑up messages via the following ROS Topic:

# lyre_msgs/msg/AsrKeyword.msg
# ASR wake‑up keyword.
string TOPIC_NAME = /audio_asr/keyword
string keyword
int32 angle

For a C++ usage example, refer to asr_keyword_msg in the lyre_examples package.

8.9.7.2 Listen for Speech Recognition Results (Topic)​

The device can convert surrounding sounds into text. You can obtain the recognized text via the following ROS Topic:

# lyre_msgs/msg/AsrIat.msg
# ASR recognition result.
string TOPIC_NAME = /audio_asr/iat
string id
string text

For a C++ usage example, refer to asr_iat_msg in the lyre_examples package.

8.9.7.3 Listen for Other Events (Topic)​

The device also publishes other ASR‑related events. Event types are defined in the following ROS Topic:

# lyre_msgs/msg/AsrEvent.msg
# ASR‑related events from the device.
string TOPIC_NAME = /audio_asr/event
int8 EVENT_ERROR = 2            # Error event; arg1 is the error code.
int8 EVENT_STATE = 3            # Service state event.
int8 EVENT_WAKEUP = 4           # Wake‑up event.
int8 EVENT_SLEEP = 5            # Sleep event.
int8 EVENT_PRE_SLEEP = 10       # Pre‑sleep event.
int8 EVENT_CONNECTED_TO_SERVER = 13 # Connected to server.
int8 EVENT_SERVER_DISCONNECTED = 14 # Disconnected from server.
int8 event
int8 arg1

For a C++ usage example, refer to asr_event_msg in the lyre_examples package.

8.9.7.4 aiui_msg Event​

The SDK remains compatible with the legacy Topic /xunfei/aiui_msg, which has been marked as deprecated and may be removed in the future.

string TOPIC_NAME = /xunfei/aiui_msg

The Topic type is std_msgs::msg::String. You can obtain its content using:

ros2 topic echo -f /xunfei/aiui_msg

8.9.8 Voice Dialogue Interfaces​

8.9.8.1 Voice Interaction Switch​

The lyre node subscribes to a ROS Topic to control whether voice interaction is enabled:

string TOPIC_NAME = /audio_chat/enable

The Topic type is std_msgs::msg::Bool.

  • Enable dialogue:

    ros2 topic pub -1 /audio_chat/enable std_msgs/msg/Bool "data: true"

  • Disable dialogue:

    ros2 topic pub -1 /audio_chat/enable std_msgs/msg/Bool "data: false"