Joystick Card
A virtual joystick that streams X/Y coordinates and direction to the device, optionally locked to one axis.
ESP-DASH Pro feature. This functionality is available only in the commercial edition of ESP-DASH.The joystick card provides a virtual joystick and streams its position and direction to the device while the user drags it. The joystick can be locked to the X or Y axis. Use it to drive robots, pan-tilt mounts or any control that needs continuous directional input.
Constructor
dash::JoystickCard(ESPDash& dashboard, const char* name, dash::JoystickLock lock = dash::JoystickLock::NONE);Prop
Type
dash::JoystickCard joystick(dashboard, "Joystick");
dash::JoystickCard joystickX(dashboard, "Joystick X", dash::JoystickLock::X);
dash::JoystickCard joystickY(dashboard, "Joystick Y", dash::JoystickLock::Y);An overload without the dashboard argument creates the card without attaching it to a dashboard; attach it later with dashboard.add(card).
Callback
void onChange(std::function<void(const dash::Joystick& joystick)> callback);While the user holds the joystick, the dashboard sends its position every 50 ms and the callback fires for each update. When the user releases the joystick, the callback fires once more with x and y set to 0 and the direction set to "idle". No dashboard update is required inside the callback.
The dash::Joystick object provides:
Prop
Type
Coordinate range
x and y are the offset of the thumb from the joystick center in CSS pixels. The thumb is clamped to a circle with a radius of 45, so each axis ranges from -45 to 45 and the combined offset never exceeds 45 (x² + y² ≤ 45²). Full deflection on a diagonal therefore yields roughly ±32 on each axis.
| Movement | x | y |
|---|---|---|
| Right | negative, down to -45 | 0 |
| Left | positive, up to 45 | 0 |
| Up | 0 | positive, up to 45 |
| Down | 0 | negative, down to -45 |
With dash::JoystickLock::X, y is always 0. With dash::JoystickLock::Y, x is always 0.
The X axis is inverted relative to the usual screen convention. Negate x() if your application expects positive values to the right.
joystick.onChange([](const dash::Joystick& joy) {
Serial.printf("x=%d y=%d dir=%s\n", joy.x(), joy.y(), joy.direction().c_str());
});Methods
setLock()
bool setLock(dash::JoystickLock lock);Locks the joystick to the X or Y axis, or unlocks it with dash::JoystickLock::NONE. Returns true if the lock changed.
joystick.setLock(dash::JoystickLock::X); // Horizontal movement only
joystick.setLock(dash::JoystickLock::Y); // Vertical movement only
joystick.setLock(dash::JoystickLock::NONE); // Free movementlock()
dash::JoystickLock lock() const;Returns the current axis lock.
Example
#include <Arduino.h>
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <ESPDashPro.h>
AsyncWebServer server(80);
ESPDash dashboard(server);
dash::JoystickCard joystick(dashboard, "Drive");
void setup() {
Serial.begin(115200);
// ... connect to WiFi
joystick.onChange([](const dash::Joystick& joy) {
Serial.printf("Joystick: %s\n", joy.to_string().c_str());
// ... map joy.x() and joy.y() to motor speeds
});
server.begin();
}
void loop() {
// ...
}