QTrobot ROS2 API Reference

The QTrobot ROS2 gateway exposes the robot's capabilities as standard ROS2 services and topics, all under the /qtrobot/ namespace, defined in the qtrobot_interfaces package. See Connection for installation instructions.

Two independent gateway nodes are available — launch the ones you need:

Gateway	Module	Connects to	Launch
QTrobot	gateway.qtrobot_ros2	qtrobot-service-hub (robot API)	python -m gateway.qtrobot_ros2 --ros-args -p robot_ip:=<ROBOT_IP> -r __ns:=/qtrobot
RealSense	gateway.realsense_ros2	qtrobot-realsense-driver (camera/IMU, camera)	python -m gateway.realsense_ros2 --ros-args -p realsense_ip:=<ROBOT_IP> -r __ns:=/qtrobot

Parameter	Gateway	Default	Description
robot_ip	QTrobot	127.0.0.1	IP address of the QTrobot service hub.
realsense_ip	RealSense	127.0.0.1	IP address of the RealSense driver host.
rpc_timeout	both	30.0	Service call timeout, in seconds.

Both gateways are remapped onto the same /qtrobot namespace above, so they appear as one consistent API even though they're separate processes — this is why the camera/IMU services and topics below are documented alongside everything else, but require the RealSense gateway specifically to be running.

Not exposed over ROS2

ASR (speech recognition) and kinematics are available in the Python API but are not yet bridged to ROS2 — there are no /qtrobot/asr/... or /qtrobot/kinematics/... interfaces.

Discovering the API

Every service, topic, and message type is fully self-describing in ROS2 — the tables below are a curated map, but the robot's own introspection tools are the source of truth and will never go stale:

# Confirm the gateway(s) are running
ros2 node list

# List everything QTrobot exposes
ros2 service list | grep qtrobot
ros2 topic list | grep qtrobot

# Look up the type of a specific service/topic
ros2 service type /qtrobot/tts/engine/say/text
ros2 topic type /qtrobot/motor/joints/state/stream

# Inspect the exact request/response or message fields
ros2 interface show qtrobot_interfaces/srv/TtsEngineSayText
ros2 interface show qtrobot_interfaces/msg/MotorJointsStateFrame

# Check a topic's live publish rate and subscriber/publisher count
ros2 topic info /qtrobot/motor/joints/state/stream -v

Core concepts

Every service response includes a status field (bool) indicating success, alongside a result field where applicable. A call that times out or fails raises the usual rclpy service-call error for its rpc_timeout window (see the launch parameters above).

Calling a service and subscribing to a topic both follow the standard rclpy patterns:

import rclpy
from rclpy.node import Node
from qtrobot_interfaces.srv import TtsEngineSayText
from qtrobot_interfaces.msg import MotorJointsStateFrame

class Example(Node):
    def __init__(self):
        super().__init__('example')
        # Service client
        self.tts_client = self.create_client(TtsEngineSayText, '/qtrobot/tts/engine/say/text')
        # Topic subscriber
        self.create_subscription(MotorJointsStateFrame, '/qtrobot/motor/joints/state/stream', self.on_state, 10)

    def say(self, text: str):
        req = TtsEngineSayText.Request()
        req.text = text
        future = self.tts_client.call_async(req)
        rclpy.spin_until_future_complete(self, future)
        return future.result()

    def on_state(self, msg: MotorJointsStateFrame):
        for joint in msg.joints:
            self.get_logger().info(f'{joint.name}: {joint.position}')

The same shape applies to every service/topic below — only the request fields, message fields, and topic name change. See Connection for a full service-call walkthrough, and Motor or Microphone for topic-subscription walkthroughs.

On this page: tts · face · gesture · motor · media · speaker · microphone · camera

---

tts

Service	Type	Parameters
/qtrobot/tts/engine/say/text	TtsEngineSayText	text, lang, voice, pitch, rate, volume, style, engine
/qtrobot/tts/engine/say/ssml	TtsEngineSaySsml	ssml, engine
/qtrobot/tts/engine/cancel	TtsEngineCancel	engine (optional)
/qtrobot/tts/engines/list	TtsEnginesList	—
/qtrobot/tts/engine/voices/get	TtsEngineVoicesGet	engine (optional)
/qtrobot/tts/engine/languages/get	TtsEngineLanguagesGet	engine (optional)
/qtrobot/tts/default_engine/get	TtsDefaultEngineGet	—
/qtrobot/tts/default_engine/set	TtsDefaultEngineSet	engine
/qtrobot/tts/engine/configure/get	TtsEngineConfigureGet	engine (optional)
/qtrobot/tts/engine/configure/set	TtsEngineConfigureSet	config (JSON dict), engine (optional)
/qtrobot/tts/engine/supports/ssml	TtsEngineSupportsSsml	engine (optional)

ros2 service call /qtrobot/tts/engine/say/text qtrobot_interfaces/srv/TtsEngineSayText \
    "{text: 'Hello, I am QTrobot.'}"

ros2 service call /qtrobot/tts/engine/cancel qtrobot_interfaces/srv/TtsEngineCancel "{}"

face

Service	Type	Parameters
/qtrobot/face/emotion/list	FaceEmotionList	—
/qtrobot/face/emotion/show	FaceEmotionShow	emotion (string, required), speed (float)
/qtrobot/face/emotion/stop	FaceEmotionStop	—
/qtrobot/face/look	FaceLook	l_eye, r_eye (JSON list), duration (float)

ros2 service call /qtrobot/face/emotion/show qtrobot_interfaces/srv/FaceEmotionShow \
    "{emotion: 'QT/happy'}"

ros2 service call /qtrobot/face/emotion/stop qtrobot_interfaces/srv/FaceEmotionStop "{}"

gesture

Service	Type	Parameters
/qtrobot/gesture/file/list	GestureFileList	—
/qtrobot/gesture/file/play	GestureFilePlay	gesture (required), speed_factor (float)
/qtrobot/gesture/play	GesturePlay	keyframes (JSON dict), rate_hz, speed_factor, resample
/qtrobot/gesture/cancel	GestureCancel	—
/qtrobot/gesture/record/start	GestureRecordStart	motors (JSON list), timeout_ms, release_motors, ...
/qtrobot/gesture/record/stop	GestureRecordStop	—
/qtrobot/gesture/record/store	GestureRecordStore	gesture (required)

ros2 service call /qtrobot/gesture/file/play qtrobot_interfaces/srv/GestureFilePlay \
    "{gesture: 'QT/send_kiss'}"

Stream: progress

Topic	Type	Rate	Description
/qtrobot/gesture/progress/stream	GestureProgressFrame	streaming	Gesture playback progress (0–100%) and elapsed time (µs)

ros2 topic echo /qtrobot/gesture/progress/stream

motor

Service	Type	Parameters
/qtrobot/motor/list	MotorList	—
/qtrobot/motor/on	MotorOn	motor (required)
/qtrobot/motor/on/all	MotorOnAll	—
/qtrobot/motor/off	MotorOff	motor (required)
/qtrobot/motor/off/all	MotorOffAll	—
/qtrobot/motor/move/home	MotorMoveHome	motor (required)
/qtrobot/motor/move/home/all	MotorMoveHomeAll	—
/qtrobot/motor/velocity/set	MotorVelocitySet	motor, velocity (required)

ros2 service call /qtrobot/motor/on/all qtrobot_interfaces/srv/MotorOnAll "{}"
ros2 service call /qtrobot/motor/move/home/all qtrobot_interfaces/srv/MotorMoveHomeAll "{}"
ros2 service call /qtrobot/motor/velocity/set qtrobot_interfaces/srv/MotorVelocitySet \
    "{motor: 'HeadYaw', velocity: 50}"

Stream: joint state, errors, and commands

Topic	Type	Rate	Description
/qtrobot/motor/joints/state/stream	MotorJointsStateFrame	10 Hz	Per-joint position (deg), velocity (deg/s), effort (Nm), voltage (V), temperature (°C)
/qtrobot/motor/joints/error/stream	MotorJointsErrorFrame	on change	Per-joint error flags: overload, voltage, temperature, sensor
/qtrobot/motor/joints/command/stream	MotorJointsCommandFrame	(subscribed)	Send joint position/velocity commands to the robot

MotorJointsStateFrame carries a joints array of MotorJointState entries (name, position, velocity, effort, voltage, temperature). MotorJointsCommandFrame carries a joints array of MotorJointCommand entries (name, position, velocity).

ros2 topic echo /qtrobot/motor/joints/state/stream

media

Service	Parameters
/qtrobot/media/audio/fg/file/play	uri (required)
/qtrobot/media/audio/fg/file/pause / resume / cancel	—
/qtrobot/media/audio/fg/volume/get / set	value (0.0–1.0)
/qtrobot/media/audio/fg/stream/pause / resume / cancel	—
/qtrobot/media/audio/bg/*	Background audio — same API as fg
/qtrobot/media/video/fg/file/play	uri (required), speed, with_audio
/qtrobot/media/video/fg/file/pause / resume / cancel	—
/qtrobot/media/video/fg/set_alpha	value (0.0–1.0)
/qtrobot/media/video/fg/stream/pause / resume / cancel	—
/qtrobot/media/video/bg/*	Background video — same API as fg

ros2 service call /qtrobot/media/audio/fg/file/play qtrobot_interfaces/srv/MediaAudioFgFilePlay \
    "{uri: '/data/audio/hello.wav'}"

Streamed audio/video

Topic	Type	Description
/qtrobot/media/audio/fg/stream / bg/stream	AudioFrameRaw	Stream PCM audio to the foreground/background player
/qtrobot/media/video/fg/stream / bg/stream	ImageFrameRaw	Stream image frames to the foreground/background display

speaker

Service	Type	Parameters
/qtrobot/speaker/volume/get	SpeakerVolumeGet	—
/qtrobot/speaker/volume/set	SpeakerVolumeSet	value (0.0–1.0)
/qtrobot/speaker/volume/mute	SpeakerVolumeMute	—
/qtrobot/speaker/volume/unmute	SpeakerVolumeUnmute	—

ros2 service call /qtrobot/speaker/volume/set qtrobot_interfaces/srv/SpeakerVolumeSet "{value: 0.8}"

microphone

Service	Parameters
/qtrobot/microphone/int/tunning/get	—
/qtrobot/microphone/int/tunning/set	name, value

Stream: audio and voice activity

Topic	Type	Description
/qtrobot/mic/int/audio/ch0–ch4/stream	AudioFrameRaw	Internal mic (ch0 beamformed, ch1–4 raw)
/qtrobot/mic/ext/audio/ch0/stream	AudioFrameRaw	External mic
/qtrobot/mic/int/event/stream	MicEventFrame	Voice activity (activity: bool) and direction of arrival (direction: int32, 0–359°)

ros2 topic echo /qtrobot/mic/int/event/stream

camera

The 3D camera and IMU come from a separate gateway process (gateway.realsense_ros2, see the launch table above) — start it alongside the QTrobot gateway to use these services and topics.

Service	Type
/qtrobot/camera/color/intrinsics	CameraColorIntrinsics
/qtrobot/camera/depth/intrinsics	CameraDepthIntrinsics
/qtrobot/camera/depth/scale	CameraDepthScale

ros2 service call /qtrobot/camera/depth/scale qtrobot_interfaces/srv/CameraDepthScale "{}"

Stream: images and IMU

Topic	Type	Rate	Description
/qtrobot/camera/color/image	ImageFrameRaw	15 Hz	RGB color image (default 848×480)
/qtrobot/camera/depth/image	ImageFrameRaw	15 Hz	Raw depth image (Z16, in depth units)
/qtrobot/camera/depth/aligned/image	ImageFrameRaw	15 Hz	Depth aligned to color frame
/qtrobot/camera/depth/color/image	ImageFrameRaw	15 Hz	Colorized depth for visualization
/qtrobot/camera/gyro	ImuFrame	200 Hz	Requires use-gyro on the driver
/qtrobot/camera/acceleration	ImuFrame	63 Hz	Requires use-accel on the driver

ImuFrame carries x, y, z — angular velocity (rad/s) for gyro, linear acceleration (m/s²) for acceleration.

ros2 topic hz /qtrobot/camera/color/image
ros2 topic echo /qtrobot/camera/depth/aligned/image --field encoding

---

See the ROS2 Tutorials for full node examples (service clients, topic subscribers/publishers, and the RealSense gateway).