๐Ÿ•น

Joystick 2D

Sources
Run the live example Free ยท no sign-up ยท runs in your browser

The Joystick2D block provides an interactive on-canvas two-axis thumbstick control that allows simultaneous multi-variable steering during live simulation runs. Dragging the circular knob provides coordinated two-dimensional deflection signals (horizontal XX and vertical YY), making it ideal for commanding drone attitude (roll and pitch), mobile robot velocity and steering angle, camera gimbals, or dual-axis force disturbances. The block features unit-circle radial clamping, configurable output scaling gain, and an optional spring-return mechanism that automatically snaps the knob back to center on release.

Mathematical Model

The user drags the on-canvas knob to raw pixel offset coordinates (dx,dy)(d_x, d_y). The normalized deflection vector is clamped radially to the unit circle:

r=dx2+dy2,(xnorm,ynorm)={(dx,dy),rโ‰ค1(dxr,dyr),r>1r = \sqrt{d_x^2 + d_y^2}, \quad (x_{\text{norm}}, y_{\text{norm}}) = \begin{cases} (d_x, d_y), & r \le 1 \\ \left(\frac{d_x}{r}, \frac{d_y}{r}\right), & r > 1 \end{cases}

The output signals emitted from the two right-side ports (xx and yy) are scaled by gain (KK):

xout(t)=Kโ‹…xnorm(t)yout(t)=Kโ‹…ynorm(t)\begin{aligned} x_{\text{out}}(t) &= K \cdot x_{\text{norm}}(t) \\ y_{\text{out}}(t) &= K \cdot y_{\text{norm}}(t) \end{aligned}

When springReturn = true, releasing the mouse button or touch contact immediately resets the normalized deflection coordinates back to the origin:

(xnorm,ynorm)โ†(0.0,0.0)(x_{\text{norm}}, y_{\text{norm}}) \leftarrow (0.0, 0.0)

When springReturn = false, the knob retains its last dragged deflection position.

Inputs & Outputs

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

Parameters

Parameters Label Type Default Description
valueX X Value number 0 Current X deflection โ€” written by the on-canvas knob. Bounded with Y to the unit circle (|(x,y)| โ‰ค 1).
valueY Y Value number 0 Current Y deflection โ€” written by the on-canvas knob. Bounded with X to the unit circle (|(x,y)| โ‰ค 1).
gain Gain number 1 Output scale: out = deflection ร— gain
springReturn Spring Return boolean true Snap the knob back to (0,0) when released

Usage Examples

Example 1: Drone Quadrotor Roll and Pitch Manual Steering

Steering quadrotor roll and pitch angles interactively. Configuring gain = 30.0 (degrees) and springReturn = true. Connecting port xx to the roll attitude controller setpoint and port yy to the pitch attitude controller setpoint allows pilots to fly the simulated drone interactively; releasing the control immediately re-levels the drone.

Example 2: Mobile Robot Differential Drive Teleoperation

Teleoperating an autonomous ground vehicle. Port yy provides forward linear velocity (vv) with gain = 2.0 (m/s), while port xx provides angular yaw rate (ฯ‰\omega) with gain = 1.5 (rad/s). Releasing the stick halts vehicle motion safely.

Remarks & Best Practices

  • Radial Unit Circle Clamping: Diagonal deflections are bounded to a maximum vector magnitude of x2+y2โ‰ค1\sqrt{x^2 + y^2} \le 1, preventing diagonal overdrive (e.g. โˆฃ(1,1)โˆฃ=2โ‰ˆ1.414|(1, 1)| = \sqrt{2} \approx 1.414).
  • Automatic Real-Time Synchronization: Adding a Joystick2D block automatically locks simulation pacing to real-time wall-clock speed, ensuring responsive human-in-the-loop control.
  • Spring-Return vs. Trim Control: Setting springReturn = false is useful for persistent throttle levers or trim controls where the operator wishes to establish a non-zero operating bias without holding the mouse.
  • Touch and Mouse Compatible: Operates seamlessly across desktop mouse dragging and mobile/tablet touch interfaces.

Related Components

  • Slider: Single-axis interactive linear slider control.
  • KeyboardInput: Steers simulation signals via arrow keys or WASD keyboard controls.
  • XYPlot: Visualizes 2D trajectories and joystick phase portraits.
  • Gain: Scales individual signal channels independently.