Gamepad, Keyboard & OSC

Five input methods drive markers: gamepad, keyboard, mouse, 3D mouse, and OSC. The keyboard is a full live input, not a fallback.

All five can be active at once. Within a frame, last-write-wins per axis.

Keyboard

Keyboard input uses direct hardware polling, so it stays responsive under heavy pipeline load. Configure in Input → Keyboard.

Movement layouts

Pick the X-Y movement layout that suits your operator. The arrow keys are reserved for navigating the on-display menu, so they’re not available for marker movement.

“Forward” is upstage (+Y), “back” is downstage (−Y).

Layout-aware polling

The poller respects the OS keyboard layout – a QWERTZ operator pressing the physical Z reads as z, not the US-QWERTY y.

Default action keys

All of these are configurable; the defaults match the example config:

Movement keys (WASD/IJKL) can’t double as actions – the form rejects it.

Hotkey-driven OSC

Beyond marker movement, any keyboard combination can fire an OSC message via an OSC Output with a Hotkey trigger. See OSC Transmitters → Hotkey – useful for cue triggers, scene jumps, or operator macros without leaving the keyboard.

Gamepad

Standard USB-wired gamepads are auto-detected. Configure in Input → Gamepad. The reference layout is Xbox-style; the form lets you remap any button when the labels don’t match (e.g. Switch Pro, third-party Xbox-likes).

The controller must be in XInput mode. Pads with a mode switch default to XInput, DirectInput, or a console profile depending on the model – check the controller's manual for how to select XInput.

Multiple gamepads can be connected to one station. Each pad is pinned to a marker by plug order against the controlled-marker list – the first-plugged pad drives the first marker in the list, the second pad the second, etc. With two or more pads connected, D-Pad next/prev is suppressed (each operator's pad stays on its assigned marker), and Left Bumper / Right Bumper on a pad adjusts the speed of its marker only. Pads with no marker route appear under Unbound controllers in the on-screen Settings info card; their Left Bumper / Right Bumper are a no-op.

Sticks

• Move stick (default: left stick) – X/Y motion. The deadzone and response curve below apply to whichever stick you pick.
• Axis Deadzone – fraction of stick travel treated as zero. Default 0.15; raise it if the marker creeps when the stick is released, lower it for tighter response on a well-centred stick.
• Response Curve – how deflection maps to velocity: Linear (proportional), Logarithmic (default – fine control near centre, faster toward the edges; usually best for followspot work), Quadratic (a steeper ramp than Logarithmic), or S-Law (slow at both ends, fast through the middle).
• Invert Y/Z Mapping – flip the forward/back sense for operators who prefer flight-sim style (push up to move downstage).

Stick deflection translates to velocity in m/s, scaled by the current speed (modified by the Speed −/+ buttons).

Default button mapping

Buttons can also be bound as triggers for OSC outputs (see OSC Transmitters → Controller button) – fire a cue from the gamepad without the operator letting go of the sticks. Stick axes additionally drive the per-marker marker faders for continuous OSC values.

Speed ramp

The Speed − / Speed + controls (Left Bumper / Right Bumper on a gamepad, R / T on the keyboard) step the active marker's tracking speed through the configured Min–Max range. Tapping repeatedly accelerates the step: a streak of presses ramps the increment up through 1×, 3×, then 8×, so a burst crosses the range fast while a single tap nudges finely. Each controller's ramp is independent – on a multi-operator station, one pad accelerating its marker doesn't carry into another pad.

Button detection wizard

When a pad's physical layout doesn't match the Xbox reference, auto-detect it instead of remapping by hand: Input → Gamepad → Button Detection Map → Start Button Detection Wizard. The wizard runs on the app display as a full-screen overlay – press each button as prompted (Step X of Y) and OpenFollow learns the raw index behind every label. Results fill the detection map and the controller name shows as Mapped with ….

The wizard takes exclusive input on the app display while running. Cancel it with Esc on the device, or Cancel wizard in the web UI – the web cancel exists so a keyboardless operator isn't stranded once the wizard has grabbed input.

The wizard stores the captured pad's GUID alongside the name. If a later session connects a pad whose GUID doesn't match – a different physical unit, or the same pad in a different mode (most often: not in XInput) – the journal logs a one-shot warning per GUID and the Gamepad controllers (E9) section of the diagnostics bundle reports calibration MISMATCH. Re-run the wizard on the actual unit to clear it.

Mouse

A standard input on both the Raspberry Pi and macOS. Off by default; enable it under Input → Mouse. Left-click a marker's ground circle to take control, move the pointer to steer it, and right-click to release. Double right-click resets the marker to its default position. Useful for static positioning during programming, and as a quick stand-in when no gamepad is to hand.

3D mouse

A 3Dconnexion SpaceMouse or SpaceNavigator¹ is a spring-centred six-axis (6DOF) puck you push, pull, lift, and twist to steer a marker. Off by default; turn it on with the Enabled checkbox under Input → 3D Mouse. Changes apply live, with no restart. Plug it in and it's picked up automatically; with none connected the section still saves but nothing moves.

A 3D mouse counts as a controller in its own right, numbered alongside gamepads (3D mice first, then gamepads), so its marker carries a controller indicator (C1, C2, …) on the Operator Screen. On its own it drives the currently selected marker, like the keyboard and mouse – use its marker-cycle buttons to change which. Alongside other controllers it's pinned to its own marker by plug order, the way two gamepads each keep their own, so operators don't fight over one selection; the marker-cycle buttons go quiet in that mode.

Axis mapping

Each of the six motions maps on its own to a target. Defaults:

Re-point any motion at any Target: X / Y / Z (move the marker along that stage axis), Speed (ramp the marker's move-speed while held), Fader (drive the controlled marker's fader 0–1 while held), or None. Each axis also carries its own:

• Sensitivity (0–10) – a multiplier on that axis. 1 moves at the marker's configured speed; 2 doubles it; below 1 is finer. Set height gentler than lateral movement, for instance.
• Deadzone (0–1) – a dead band near centre, so the marker doesn't creep when your hand rests on the puck. Raise it on a twitchy axis.
• Invert – flip that axis's direction.

A shared Response curve shapes deflection-to-speed for all axes: Linear, Logarithmic (fine near centre, fast at the edges), Quadratic (finer still near centre), or S-Law (eased at both ends).

Buttons

Bind device buttons to Reset marker, Next / Previous marker (when the 3D mouse is the only controller), Speed up / Speed down, Toggle help, and Toggle zones. Click Detect next to a binding and press the button on the device to fill it in; leave a binding blank to unbind it. Button counts vary by model. The Settings menu has no 3D-mouse binding – opening and navigating it needs a keyboard or gamepad.

OSC input

OSC input lets external systems drive markers directly. Configured in Input → OSC Input.

The same receiver also accepts Operator Messages – text cards pushed onto the Operator Screen over OSC.

Every inbound OSC address in one place: the OSC Dictionary.

Settings

• Enabled – master toggle.
• UDP Port – default 8765.
• Multicast group – an IPv4 multicast address (224.0.0.0–239.255.255.255) the receiver joins, so one sender reaches every station at once. Defaults to 239.20.20.20; clear it to disable. Unicast and subnet broadcast are received regardless.
• Allowed sender IPs – comma-separated allowlist. Leave this empty only on bench networks. Without it, any device on the LAN can hijack marker positions.

Address scheme

Two forms are accepted, both absolute writes in PSN coordinates (X = stage left, Y = upstage, Z = up):

/marker/<id>     x  y  z       # full triple
/marker/<id>/x   v             # set X only
/marker/<id>/y   v             # set Y only
/marker/<id>/z   v             # set Z only

Within a single frame, last-write-wins per axis. Per-axis writes after a triple override only that axis; a triple after per-axis writes resets all three.

Example: TouchOSC

A simple TouchOSC layout with three faders (X, Y, Z) targeting marker 1 would send:

/marker/1/x   <float>
/marker/1/y   <float>
/marker/1/z   <float>

Set OpenFollow’s OSC Input port to match TouchOSC’s send port and add the iPad’s IP to the allowlist.

Example: console-driven cue presets

Hard-code positions from your lighting console’s OSC export to position markers ahead of a scene:

/marker/1   3.0  5.0  1.65
/marker/2   -2.5 4.0  1.65

Combine with the operator’s gamepad: the cue jumps the marker to a starting position; the operator takes over from there.

Example: grandMA3

Add OpenFollow as an OSC destination under Menu → In & Out → OSC (set its IP and the OSC Input port). Fire writes from a macro or cue with SendOSC, which carries the type tags and values in the message string. Group the tags, then the values – three floats in one message hit the full-triple address:

SendOSC 1 "/marker/1,fff,3.0,5.0,1.65"

The per-axis form works too, one float per message:

SendOSC 1 "/marker/1/x,f,3.0"
SendOSC 1 "/marker/1/y,f,5.0"
SendOSC 1 "/marker/1/z,f,1.65"

To track a live value, embed an attribute or variable in the macro line so each execution sends the current position. Add the MA3 console’s IP to the allowlist.

Combining inputs

OpenFollow doesn’t lock a marker to a single input. A typical multi-input setup:

• Operator drives marker 1 with a gamepad.
• Pre-show cues hard-position marker 1 via OSC before the operator picks up.
• Action keys (Reset, Toggle Help, Speed) on the keyboard remain live throughout – useful when the gamepad is unplugged briefly or replaced.

Last-write-wins applies per axis within a frame – an OSC message landing on the same frame as a stick deflection overwrites that axis.

1. SpaceMouse and SpaceNavigator are registered trademarks of 3Dconnexion GmbH.