Gesture

robot.gesture plays predefined keyframe gestures, and can record new ones directly from the robot's own arms. These examples assume you already have a connected robot — see Connection if you haven't set one up yet.

Setup

mkdir ~/example
cd ~/example
python -m venv .venv
# or: uv venv .venv

source .venv/bin/activate

pip install luxai-robot
# or: uv pip install luxai-robot

Connect

from luxai.robot.core import Robot

robot = Robot.connect_zmq(robot_id="QTRD000123")
print(f"connected to {robot.robot_id} ({robot.robot_type})")

See Connection for MQTT, WebRTC, and other connection options.

List gestures

# List available gestures
gestures = robot.gesture.list_files()
Logger.info(f"Available gestures: {gestures}")

list_files() lists the gesture files available on QTRP, under /home/qtrobot/robot/data/gestures. Gestures can be organized in subfolders — list_files() returns paths like QT/bye, relative to that folder.

Play and cancel a gesture

# Play a gesture; press <Enter> to cancel
Logger.info("Playing gesture 'bye' — press <Enter> to cancel...")
h = robot.gesture.play_file_async("QT/bye")
input()
h.cancel()

# Put the robot back to a resting pose
robot.motor.home_all()

play_file()/play_file_async() look up the given name (subfolder + file name, e.g. QT/bye) inside /home/qtrobot/robot/data/gestures on QTRP and play it.

Record a gesture

Instead of hand-writing keyframes, you can record a gesture by physically moving the robot's arm and letting the SDK capture the motion. This example: starts recording on a delay, lets you move the arm by hand while torque is released, stops recording on your signal, plays the result back, and optionally saves it.

# Move the robot's right arm to record a gesture — recording starts in 2
# seconds and lasts for a maximum of 20 seconds.
h = robot.gesture.record_async(
    motors=["RightShoulderPitch", "RightShoulderRoll", "RightElbowRoll"],
    release_motors=True,
    delay_start_ms=2000,
    timeout_ms=20000,
)
Logger.info("Recording... (press <Enter> to stop recording)")
input()
robot.gesture.stop_record()
keyframes = h.result()
Logger.info(f"Recording stopped. {len(keyframes['points'])} keyframes recorded.")

# Play back the recorded gesture
robot.gesture.play(keyframes)

# Save it for later playback with play_file()
if input("Save this gesture? (y/n) ").lower() == "y":
    name = input("Enter gesture name: ")
    robot.gesture.store_record(name)
    Logger.info(f"Gesture '{name}' stored.")

• motors — the list of motors to record; only their movement is captured.
• release_motors=True — turns torque off on those motors for the duration of the recording, so you can move them freely by hand. This is almost always what you want when recording by hand.
• delay_start_ms=2000 — recording starts 2 seconds after calling record_async(), giving you time to get into position before it starts capturing.
• timeout_ms=20000 — a safety cap: recording stops automatically after 20 seconds even if you forget to call stop_record().

stop_record() ends the recording; h.result() then returns the raw recorded keyframes. You can save these yourself (e.g. to your own file/database) and play them back later with robot.gesture.play(keyframes) — or call robot.gesture.store_record(name) to save it on QTRP, where it will then show up in list_files() like any other gesture. There's no SDK method to delete a stored gesture — to remove one, delete its file under /home/qtrobot/robot/data/gestures directly from a terminal on QTRP.

Next steps

Continue with the Speaker tutorial, or see the full robot.gesture namespace in the Python API Reference.