Setup guide

Set up a station and a headset

For org admins and station admins. Read this once before the first session. The Operator guide covers using the headset.

1. How it works

An operator wears a Meta Quest 3 and drives a robot arm with the right controller while watching the arm's cameras. The arm can be in the next room or in another city.

• Headset. The KnoxTeleop app on a Quest 3. Shows the camera windows and status badges. The right controller drives the arm.
• Station. The computer next to the arm. Runs the cameras, the arm bridge, a dashboard on port 8081, and the station agent that keeps in touch with the console.
• Console. The website teleop.knoxlabs.com. Admins add people and stations there, assign stations, and link headsets.

Who does what

Role	Works in	Does
Operator	Headset, console	Links their own headset, connects to an assigned station, drives the arm.
Org admin	Console	Invites people, adds stations, assigns stations to people, ends sessions, revokes headsets.
Station admin	Station computer	Starts the station, picks the arm, sets the station PIN, pastes the setup code.
Watcher	Console	Watches a station's cameras in a browser while someone drives. Cannot control anything.

One person can hold several roles. An org admin who wants to drive also needs the station assigned to themselves.

A session

1. Link once. The operator scans a QR code from the console with the headset. The headset now acts as that person.
2. Connect. The operator presses CONNECT on the headset. The console reserves the station for this headset and introduces the two. Video and arm control then flow directly between them.
3. Drive. Holding the grip moves the arm. Releasing it stops the arm.
4. Disconnect. The station is free for the next person. The headset stays linked.

Only one headset can drive a station at a time. If the operator's network drops, the station waits 30 seconds for them before it frees up. Admins can change this per station.

On the same local network, a headset can also connect straight to the station's IP address. That needs no console, account or provisioning. The Operator guide explains it.

2. Provision a station

A station needs to be started once and connected to the console once. After that it reconnects by itself, also after a reboot of the network.

You need

• The station computer with the teleop-server repo and Docker, the arm and cameras plugged in.
• Internet access. Outgoing only: the station needs no open ports.
• An org admin who can add the station in the console.

Start the station

1. Pick the arm. In config/arm_bridge.yaml, set arm_backend to aubo or xarm and fill in its block. The default, mock, is a simulated arm for trying things out.
2. Start it. Run bash scripts/start_all.sh. It starts the cameras, the arm bridge and the station agent. Running it again restarts everything.
3. Set the station PIN. Run python3 tools/set_control_pin.py --config-dir config. The dashboard asks for this PIN before Home, Clear fault and mode changes. STOP never needs it.
4. Open the dashboard at http://<station-ip>:8081. A new station says Not provisioned. It already works for headsets on the same network.

Connect it to the console

1. Add the station · Org admin. In the console, open Stations → Add station. Pick an id such as lab-2 (permanent, lowercase) and a display name. Keep all four services on: video, arm, probe and watch.
2. Copy the setup code · Org admin. The console shows it once. It contains the station's secret, so send it privately. Lost it? Use Manage → Rotate token for a new one.
3. Paste it at the station · Station admin. In the dashboard, click Provision…, paste the code and click Provision. No restart needed: the header switches to the station id and the console shows the station online.
4. Assign people · Org admin. In Stations → Assign, tick everyone who may drive this station.

Move or reset

Once provisioned, the dashboard can't change the station's identity. To move it to another org or give it a new id, run bash scripts/reset_provisioning.sh on the station, delete the old entry in the console, and provision again.

In the console	Effect on the station
Rotate token	The old code stops working at once. Reset the station and paste the new code.
Change services	The agent reconnects with the new set.
Reconnect grace	How long a dropped headset keeps the station, 5–300 s. Default 30.
Max watchers	How many browsers can watch the cameras at once, 1–3. Each one costs the station upload bandwidth.
Delete station	Ends its sessions and removes its assignments.

3. Provision a headset

A headset is linked to one person in one org. Once linked, it can connect to every station assigned to that person.

Install the app

KnoxTeleop is not in the Meta store. Install it over USB once; updates keep the link and settings.

1. Turn on developer mode in the Meta Horizon phone app: headset settings → Developer Mode. Restart the headset.
2. Plug the headset into a computer and accept Allow USB debugging in the headset.
3. Install: adb install -r KnoxTeleop.apk. Meta Quest Developer Hub works too.
4. Open it from Library → Unknown sources. Allow the camera when asked: the headset needs it to scan the link QR code.

Give the operator access

1. Invite them · Org admin. In Members, enter their email and choose Operator. They sign in at teleop.knoxlabs.com with the Google account for that email. No invitation email is sent, so tell them.
2. Assign a station · Org admin. In Stations → Assign, tick their name.

Link the headset

1. Show a link code · Operator. In the console, open Headsets → Link a headset, optionally name it ("Quest 3 – lab bench"), and click Show link code. The code works once, for 5 minutes.
2. Scan it with the headset · Operator. On the headset's station card, press SCAN LINK CODE and look at the QR code. The Operator guide shows this step from the headset side.
3. Done. The console says Linked. The headset shows "Linked as" the person's email and org, and picks their station.

Manage headsets

Action	Who	What happens
Rename	Owner, admin	Only the console label changes.
Disconnect	Owner	Ends the headset's session. The arm holds. The headset stays linked.
End session	Admin	Same, for anyone's headset. Frees the station for someone else.
Revoke	Owner, admin	The headset stops working at once and must be linked again.
Unassign or remove a person	Admin	Their sessions end and their headsets let go of the station.

Handing a headset to someone else: revoke it in the console, then the new person links it from their own account. Pressing UNLINK on the headset only clears it locally.