BlockWerk Documentation
ENNLDEFRESZH
Launch App
🕹ī¸

Phone Controller

Connectivity

PhoneController is a source block that turns any smartphone into a wireless joystick plus an independent yaw dial. When the block is placed on the canvas it shows a pairing QR code; scanning it opens a controller page on the phone with a large on-screen touch joystick and a horizontal yaw strip below it. The phone streams normalized X/Y/Yaw control values (−1â€Ļ+1) into the simulation at ~30 Hz over the same WebRTC peer-to-peer channel used by the RemoteSensor block — no cables, no app install.

Two control modes are available for the joystick pad on the phone (the yaw strip works the same in both):

  • Touch (default): thumb on the on-screen joystick pad. Release springs back to center.
  • Tilt: uses the phone's orientation sensors (DeviceOrientation). Tilt left/right maps to X, tilt forward/back maps to Y. The neutral pose is calibrated when the mode is enabled; tap the pad to re-center at any time.

The yaw strip is a separate horizontal drag control below the pad — drag left/right, release to spring back to 0. It's always active regardless of touch/tilt mode.

Use this block for interactive demos where a mouse feels clumsy: flying a simulated drone, steering a vehicle model, or driving a setpoint through a control loop by hand. Its X/Y output ports are named identically to Joystick2D's, so it's a drop-in wireless replacement anywhere an on-canvas joystick is wired up — including the Fly the Quadcopter (Phone) template, which also wires the Yaw port to the drone's yaw axis.

Simulate in BlockWerk

Interactive sandbox directly in your browser — zero installation, WASM-powered.

Simulate in BlockWerk →

Inputs & Outputs

Direction ID Label Type Status
← Out x X number Output
← Out y Y number Output
← Out yaw Yaw number Output

Parameters

Parameters Label Type Default Description
playoutDelay Playout Delay (ms) number 80 Network jitter buffer. Lower = more responsive control, higher = smoother signal on flaky connections.
interpolation Interpolation select linear How to reconstruct the control signal between received joystick packets.
outputLabels Output Labels vector x,y,yaw

Usage Examples

Phone Joystick — Attitude Demo

Load the bundled Phone Joystick — Attitude Demo (block examples menu). Your thumb commands the attitude of a simulated quadcopter: X becomes a roll setpoint, Y a pitch setpoint, each shaped by second-order attitude dynamics and rendered on a 3D gimbal:

PhoneController ──â–ē [X] ──â–ē Gain(30) ──â–ē 2nd Order System ──â–ē Gimbal3D [roll]
                ──â–ē [Y] ──â–ē Gain(30) ──â–ē 2nd Order System ──â–ē Gimbal3D [pitch]

Scan the QR code, press Grab Control, start the simulation — the drone follows your thumb.

Fly the full quadcopter template wirelessly

The Fly the Quadcopter (Phone) template (Examples menu → Control Systems) wires all three ports — x/y to the roll/pitch PID loops (through a Gain, same as Joystick2D's built-in gain) and yaw straight to the yaw PID loop — driving the full three-axis PID + motor mixer + 3D gimbal. No on-canvas slider needed: the phone's yaw strip covers it.

Manual setpoint for a PID loop

PhoneController ──â–ē [Y] ──â–ē Gain ──â–ē (setpoint) Subtraction ──â–ē PIDController → plant

Remarks & Best Practices

  • Source block: All three channels are output ports (right side). X is positive to the right, Y is positive forward/up (pushing the joystick up gives +1), Yaw is positive to the right of the strip.
  • Fixed 30 Hz stream: The phone transmits continuously — also when centered — to keep the playout buffer warm and the latency estimate stable.
  • Dead zone: A small dead zone (Âą0.02) is applied on the phone so a resting thumb/handle yields exactly 0.
  • Simulation waits for pairing: Like all live-hardware blocks, the simulation start is gated until the phone is connected and the first packets have arrived.
  • WebRTC required: Phone and desktop both need internet access for the PeerJS signalling handshake. Self-hosted PeerJS servers are supported via the same localStorage keys as RemoteSensor (blockwerk_peer_host / blockwerk_peer_port / blockwerk_peer_path / blockwerk_peer_secure).
  • One controller per diagram: The X/Y/Yaw channels are global (remote:joy.x / remote:joy.y / remote:joy.z); two PhoneController blocks would receive the same data.
  • Output values when disconnected: All three ports hold 0 until the phone connects and begins transmitting.

Related Components

  • RemoteSensor: Stream the phone's accelerometer, gyroscope, magnetometer, barometer, and GPS instead of a joystick.
  • ExternalInput: Lightweight source for manually injected or scripted numeric values.
  • Gimbal3D: 3D attitude visualization — the natural sink for this block's demo.