Skip to main content
Version: QTrobot V3

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​

<script src="https://cdn.jsdelivr.net/npm/@luxai-qtrobot/robot-sdk/dist/qtrobot-sdk.umd.js"></script>
npm install @luxai-qtrobot/robot-sdk

List gestures​

const gestures = await robot.gesture.listFiles()
console.log(`Available gestures (${gestures.length}):`)
for (const g of gestures) {
  console.log(`  ${g}`)
}

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

Play and cancel a gesture​

const controller = new AbortController()
const play = robot.gesture.playFile({ gesture: 'QT/bye', signal: controller.signal })

// e.g. on a button click
controller.abort()

try {
  await play
} catch {
  console.log('Gesture cancelled. Homing all motors...')
  await robot.motor.homeAll()
}

playFile() looks up the given name (subfolder + file name, e.g. QT/bye) inside /home/qtrobot/robot/data/gestures on QTRP and plays 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.

const controller = new AbortController()
const recording = robot.gesture.record({
  motors: ['RightShoulderPitch', 'RightShoulderRoll', 'RightElbowRoll'],
  release_motors: true,
  delay_start_ms: 2000,
  timeout_ms: 20000,
  signal: controller.signal,
})

// e.g. when the user clicks "Stop recording"
await robot.gesture.stopRecord()

const keyframes = await recording
console.log(`Recording stopped. ${keyframes.points?.length ?? 0} keyframes recorded.`)

// Play back the recorded gesture
await robot.gesture.play({ keyframes })

// Save it for later playback with playFile()
await robot.gesture.storeRecord({ gesture: 'my_wave' })
  • 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(), 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 abort/stop it.

stopRecord() ends the recording; the recording promise then resolves with 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 storeRecord({ gesture: name }) to save it on QTRP, where it will then show up in listFiles() 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 TypeScript/Node.js API Reference.