Joystick 2D
SourcesThe 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 and vertical ), 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 . The normalized deflection vector is clamped radially to the unit circle:
The output signals emitted from the two right-side ports ( and ) are scaled by gain ():
When springReturn = true, releasing the mouse button or touch contact immediately resets the normalized deflection coordinates back to the origin:
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 to the roll attitude controller setpoint and port 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 provides forward linear velocity () with gain = 2.0 (m/s), while port provides angular yaw rate () 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 , preventing diagonal overdrive (e.g. ).
- 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 = falseis 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.