Documentation / Widgets / Controller / Joystick

Joystick

A circle within a circle: a knob that a finger drags inside a base. While the finger is held the knob follows it, and its X and Y follow the knob; let go, it springs back to the middle and X and Y go back to 0. Use it to steer, to pan a camera, to move something in a game or to drive a pointer.

Group: Controller · Style parts: Main, Base, Knob · Exports: Arduino, ESP-IDF, MicroPython · Beta: free for everybody to the end of 31 October, then part of Pro

SettingDefaultWhat it does
Dead zone5 %Near the middle X and Y stay 0, so a thumb resting on the knob does not drift. Past it they start from 0 again, with no jump.
MovesAny wayAny way, Left and right only or Up and down only.
Knob size40 %Of the base. The base and the knob are sized to fill the widget’s box between them, so the knob can ride the base’s edge without leaving the box.
Springs back to the middleOnLet go, the knob goes back to the middle and X and Y back to 0. Off, it stays where it was let go, like a throttle.
Return time150 msHow long the way back takes. 0 puts it back at once.

How it moves. Only a press on the knob takes hold of it: a press on the base beside it does nothing. The knob is held where the finger took it, so it does not jump. Its centre can go from the middle to the edge of the base, where X or Y is 1. A finger that goes further leaves the knob on the edge, at the finger’s angle, for as long as it is held. A finger that is held still keeps it there. The widget’s box is square.

What it gives. Bind any of these to a variable, in Data bindings. They go one way, from the Joystick into the variable, as it moves:

A Joystick dropped on the screen brings two variables, JoyX and JoyY, decimals already bound to its X and Y. Its Value changed event comes each time what it gives changes, the last time with X and Y at 0.

Styling. The Base and the Knob are each a part with the whole of Style settings, and each takes Pressed while a finger holds the knob. They start as circles, and a radius of your own makes either a rounded square. Main is the box behind them, which is empty until it is styled.

Exports. Arduino, ESP-IDF and MicroPython. ESPHome has no joystick. Compiled, and driven by a finger in LVGL 9.4.0 and 8.3.11 to match the designer; run on an LCDWIKI ES3C35P steering a sprite (the example below).

Example: reading the stick

  1. Drag a Joystick onto the screen. JoyX and JoyY appear on the Data tab.
  2. Add a Label and bind its Text to JoyX with the format %.2f, and another to JoyY (see Variables and bindings).
  3. Press Preview and drag the knob: the labels follow it, and go back to 0 when you let go.

Example: steering something round a box

  1. Add a Panel for the box, with its Padding at 0, and put the thing to move inside it - an Image of a small sprite, say 40 x 40.
  2. Add two decimal variables for where it is, ShipX and ShipY, and one for how fast, Speed (4 is 200 pixels a second at full stick).
  3. Add an automation, Every interval of 20 ms, with two Set variable actions: ShipX to clamp(ShipX + JoyX * Speed, 0, 256) and ShipY to clamp(ShipY - JoyY * Speed, 0, 226). Y is taken away because the stick counts up as plus and the screen counts down.
  4. Bind the sprite's X position to ShipX and its Y position to ShipY.

The clamp is what keeps it in the box: 256 and 226 are the inside of the box (a 300 x 270 panel less its 2 px border on each side) less the size of the sprite. Let go and the stick gives 0, so the sprite stops where it is. To make it face the way it goes, bind its Rotation to the stick's Angle through a variable. The whole build, with a picture of every step, is a tutorial in Tips and tricks on the forum, and the design is in the gallery.