Connection

Every program starts the same way: create a Robot client. Unlike the Python SDK, there's no direct ZMQ transport here — only MQTT and WebRTC — because both Node.js and the browser need a transport that works over a normal network socket or WebSocket.

• MQTT is the default, recommended choice — the MQTT gateway already runs on QTPC out of the box, so there's nothing extra to install. Use it from Node.js or the browser.
• WebRTC is for when you need the lowest latency, or live audio/video (see Audio and Video). It needs qtrobot-service-hub-gateway-webrtc installed on QTPC first — it isn't there by default.

Node.js vs. browser

This is the one thing that genuinely differs between the two environments: Node.js can open a raw TCP socket, a browser can't. That changes which broker URL scheme you use:

Environment	MQTT broker URL	Why
Node.js	mqtt://<robot-ip>:1883 (or mqtts:// for TLS)	Full TCP socket access
Browser	ws://<robot-ip>:9001 (or wss:// over the internet)	Browsers only expose WebSocket, not raw TCP

Everything else — the SDK API, the namespaces, the examples in the rest of this tutorial section — is identical in both environments.

Setup

Browser — no build step, drop the UMD bundle in from a CDN:

<script src="https://cdn.jsdelivr.net/npm/@luxai-qtrobot/robot-sdk/dist/qtrobot-sdk.umd.js"></script>
<script>
  const { Robot } = QTRobotSDK
</script>

Node.js — or any bundler-based project (React, etc.):

mkdir ~/example && cd ~/example
npm init -y
npm install @luxai-qtrobot/robot-sdk

import { Robot } from '@luxai-qtrobot/robot-sdk'

Connect over MQTT

Basic — plain TCP (Node.js) or WebSocket (browser), no TLS, no authentication:

// Node.js
const robot = await Robot.connectMqtt('mqtt://10.231.0.1:1883', 'QTRD000123')
console.log(`connected to ${robot.robotId} (${robot.robotType})`)
robot.close()

<!-- Browser -->
<script>
  const robot = await Robot.connectMqtt('ws://10.231.0.1:9001', 'QTRD000123')
  console.log(`connected to ${robot.robotId} (${robot.robotType})`)
</script>

note

The robot's default MQTT broker has no authentication or TLS configured — connect as shown above. Username/password or TLS only apply if qtrobot-service-hub-gateway-mqtt has been set up to use a different, external broker that requires them.

With custom timeouts:

const robot = await Robot.connectMqtt('mqtt://10.231.0.1:1883', 'QTRD000123', {
  connectTimeoutSec: 15,
  defaultRpcTimeoutSec: 30,
})

Manual transport — power-user style, construct MqttConnection/MqttTransport yourself when you need direct control over the connection lifecycle:

import { Robot, MqttTransport } from '@luxai-qtrobot/robot-sdk'
import { MqttConnection } from '@luxai-qtrobot/magpie'

const conn = new MqttConnection('mqtt://10.231.0.1:1883', { clientId: 'qtrobot-sdk-QTRD000123' })
await conn.connect(10_000)

const transport = new MqttTransport(conn, 'QTRD000123')
const robot = await Robot.connect(transport)

Automatic cleanup — await using calls robot.close() for you when the block exits (TC39 explicit resource management):

await using robot = await Robot.connectMqtt('mqtt://10.231.0.1:1883', 'QTRD000123')
console.log(`connected to ${robot.robotId} (${robot.robotType})`)
// robot.close() is called automatically here

Connect over WebRTC

A peer-to-peer connection — after a short handshake ("signaling") over MQTT, RPC and stream traffic flows directly between your code and the robot. This is what Audio and Video use to send your own camera/microphone to the robot and receive its live feeds.

Install the gateway on QTPC first:

sudo apt install qtrobot-service-hub-gateway-webrtc

const robot = await Robot.connectWebrtcMqtt('mqtt://10.231.0.1:1883', 'QTRD000123')
console.log(`connected to ${robot.robotId} (${robot.robotType})`)

<!-- Browser — same wss:// rule as MQTT applies to the signaling broker -->
<script>
  const robot = await Robot.connectWebrtcMqtt('wss://<robot-ip>:8084', 'QTRD000123')
</script>

Advanced: connecting over the internet

For real internet use, the signaling broker needs to be a remote/public MQTT broker (wss://), and you'll usually need STUN/TURN servers for NAT traversal:

const robot = await Robot.connectWebrtcMqtt('wss://broker.example.com:8084', 'QTRD000123', {
  webrtcOptions: {
    stunServers: ['stun:stun.l.google.com:19302'],
    turnServers: [{ url: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' }],
  },
})

Next steps

Continue with the TTS tutorial, or see the full connection API in the TypeScript/Node.js API Reference.