Rotary Knob Widget

⚡ Control

The Rotary Knob is a circular drag control that sends values to your device. It operates in two distinct modes: Knob (a bounded dial with a fixed range) and Encoder (an infinite-rotation input that sends a fixed value per tick, like a rotary encoder).

Default size: 2 × 2 grid cells

Preview

Widget appearance may vary slightly from the actual dashboard.

---

Modes

Knob mode

A classic bounded dial. The handle sweeps through a 270° arc from a minimum to a maximum value. Dragging the knob sends the proportional value to the device in real time or on release.

Use for: dimmer controls, volume, servo angle, setpoints, motor speed.

Encoder mode

An infinite-rotation dial with evenly spaced tick marks. Each full revolution consists of a configurable number of steps. Turning clockwise sends one fixed value; turning counter-clockwise sends another.

Use for: incremental control (menu navigation, step-by-step adjustment, stepper motors).

---

Configuration

Knob mode properties

Property	Type	Default	Description
Mode	knob | encoder	knob	Sets the operating mode
Min	number	0	Minimum value sent when handle is at start of arc
Max	number	255	Maximum value sent when handle is at end of arc
Step	number	1	Increment between discrete positions
Unit	string	(none)	Label displayed below the current value
Color	hex color	#3B82F6	Arc and handle accent color
Send on release	boolean	true	true → send once on release; false → send continuously while dragging
Device	device	—	The device to write to
Pin	V0–V255	—	The virtual pin to write to
Label	string	—	Widget label shown above the knob

Encoder mode properties

Property	Type	Default	Description
Mode	encoder	—	Sets the operating mode
Steps per revolution	number	20	Number of tick marks (and steps) per full rotation
CW value	string	1	Value sent when rotated clockwise
CCW value	string	-1	Value sent when rotated counter-clockwise
CW color	hex color	#3B82F6	Trail color for clockwise rotation
CCW color	hex color	#f59e0b	Trail color for counter-clockwise rotation
Device	device	—	The device to write to
Pin	V0–V255	—	The virtual pin to write to
Label	string	—	Widget label shown above the knob

---

Firmware examples

Knob mode — LED brightness

// Receive brightness from Rotary Knob (0–255)
VWIRE_RECEIVE(V0) {
  int brightness = param.asInt();
  analogWrite(LED_PIN, brightness);
  Vwire.virtualSend(V0, brightness); // echo back current value
}

Knob mode — servo angle

#include <Servo.h>
Servo myServo;

// Receive angle from Rotary Knob (0–180)
VWIRE_RECEIVE(V1) {
  int angle = param.asInt();
  myServo.write(angle);
}

void setup() {
  myServo.attach(SERVO_PIN);
  Vwire.config(AUTH_TOKEN);
  Vwire.setDeviceId(DEVICE_ID);
  Vwire.begin(WIFI_SSID, WIFI_PASSWORD);
}

Encoder mode — stepper motor direction

Configure the encoder widget with CW value = "1" and CCW value = "-1".

// Each tick sends "1" (CW) or "-1" (CCW)
VWIRE_RECEIVE(V2) {
  int direction = param.asInt(); // 1 = CW, -1 = CCW
  if (direction == 1) {
    stepMotor(FORWARD, 1);
  } else {
    stepMotor(BACKWARD, 1);
  }
}

Encoder mode — menu navigation

Configure with CW value = "next" and CCW value = "prev".

VWIRE_RECEIVE(V3) {
  String cmd = param.asStr();
  if (cmd == "next") {
    menuNext();
  } else if (cmd == "prev") {
    menuPrev();
  }
}

---

Restoring knob position on reconnect

In Knob mode, the knob position is automatically restored from the last stored pin value after reconnecting. Call Vwire.syncVirtual() in VWIRE_CONNECTED() to trigger the restore:

VWIRE_CONNECTED() {
  Vwire.syncVirtual(V0); // restores knob to last saved position
}

note

Encoder mode is stateless by design — it does not restore position on reconnect, because the encoder value represents a direction command rather than an absolute position.

---

Knob vs Slider — when to use which

	Rotary Knob (Knob)	Slider
Interaction style	Rotary drag	Linear drag
Layout footprint	Square (2×2)	Wide (3×1)
Best for	Compact dashboards, physical dial feel	Linear ranges, 1D control
Encoder/infinite	✅ (encoder mode)	❌