Joystick Widget

⚡ Control

The Joystick widget provides a thumbstick-style XY controller. Dragging the handle sends X and Y coordinates to a virtual pin as a comma-separated pair. Use it to control pan/tilt camera heads, robot drives, or drone gimbal motors.

Default size: 2 × 2 grid cells

---

Configuration

Property	Type	Default	Description
xMin	number	-100	Left extreme value
xMax	number	100	Right extreme value
yMin	number	-100	Bottom extreme value
yMax	number	100	Top extreme value
returnToCenter	boolean	true	Snap to 0,0 on release
color	hex color	#6366F1	Handle accent color
Device	device	—	The device to write to
Pin	V0–V255	—	The virtual pin to write
Label	string	—	Widget label

---

Message format

Values are sent as a comma-separated string: "X,Y"

"-45,72"   → x=-45, y=72
"0,0"      → centered (released)
"100,-100" → full right, full down

---

Firmware example

VWIRE_RECEIVE(V0) {
  String raw = param.asStr();  // e.g. "-45,72"

  int commaIdx = raw.indexOf(',');
  int x = raw.substring(0, commaIdx).toInt();
  int y = raw.substring(commaIdx + 1).toInt();

  // Map to motor speed (-255 to 255 PWM)
  int leftMotor  = constrain(y + x, -255, 255);
  int rightMotor = constrain(y - x, -255, 255);

  setMotor(LEFT,  leftMotor);
  setMotor(RIGHT, rightMotor);
}

---

Pan-tilt control

Servo panServo, tiltServo;

VWIRE_RECEIVE(V1) {
  String raw = param.asStr();
  int commaIdx = raw.indexOf(',');
  int x = raw.substring(0, commaIdx).toInt();   // -100 to 100
  int y = raw.substring(commaIdx + 1).toInt();   // -100 to 100

  int pan  = map(x, -100, 100, 0, 180);
  int tilt = map(y, -100, 100, 0, 180);

  panServo.write(pan);
  tiltServo.write(tilt);
}

---

Tips

returnToCenter

Enable returnToCenter for vehicles and drones — the device should stop when the joystick is released. Disable it for absolute-position controls like camera pan where you want the servo to hold position.