Guide / Controls / Inputs

Joystick

Steer with your thumb

When to use it. A virtual analog stick or directional pad for continuous 2D input. Fires throttled actions with x and y values ranging from -1 to 1.

Type
joystick
Default size
3 rows × 3 columns
Symbol
dpad.fill
Docs
Docs complete
Search for it as
  • stick
  • pad
  • direction
  • steer
  • drive
  • gamepad
Joystick: Robot drive controller
Rendered by the app

Fields

7 fields you can set on a joystick control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
Labellabeltext—

The name shown under the stick

Shows this text under the stick, above the live x/y readout, in the label font size.

tinttintcolor#667eea

The stick color

Colors the stick, its track ring and the faint center dead-zone disc.

stylestylechoiceone of 2analog

Free stick or 8-way pad

Chooses whether the stick moves freely or snaps to one of 8 directions, with a diagonal counting as full strength.

  • analog defaultthe stick moves freely and sends smooth x and y values
  • dpadsnaps to one of 8 directions, sending x and y of -1, 0 or 1 (diagonals scaled to unit length)
Dead zonedeadzonenumber0–1step 0.050.1

How far to push before it counts

Draws a faint center disc and sends nothing until the stick is pushed past this fraction of its full travel (0-1, default 0.1).

Stickystickyon / offfalse (off)

Stay put when you let go

When on, the stick stays where you released it and sends that position once; when off, it springs back to center and sends x 0, y 0.

Send ratesendRatenumber0.1–10step 0.10.1

How often it sends

Sets the minimum seconds between sends while you hold the stick outside the dead zone (0.1-10, default 0.1).

Label shownhideLabelon / offfalse (off)

Hide the name and readout

When on, hides the label and the x/y readout under the stick.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
cornerRadiustheme.cornerRadiusnumber0–30 ptstep 112

Card outline color

Colors the outline around the card.

borderWidththeme.borderWidthnumber0–5 ptstep 0.51

Label text size

Sets the label text size from 8 to 24 pt (default 12).

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
While you move the stickvaluechangejson

the stick position as x and y, each from -1 to 1 (up is positive y)

Sends at the send rate while the stick is outside the deadzone; on release it sends one last position, which is x 0 and y 0 unless the stick is sticky

Example: {"x": 0.5, "y": -0.25}

Examples

3 examples, each one a control you can paste into a layout.

Robot drive controller

Drive a robot with a free analog stick.

JSON 12 lines
{
  "type": "joystick",
  "id": "drive-stick",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Drive",
  "tint": "#FF2D55",
  "style": "analog",
  "deadzone": 0.15,
  "sendRate": 0.05,
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "robot", "type": "drive", "payload": { "x": "$value.x", "y": "$value.y" } } }
}

Open in CAR-TER

Joystick: Robot drive controller
Rendered by the app

Menu pad

An 8-way pad that snaps to directions and stays where you leave it.

JSON 11 lines
{
  "type": "joystick",
  "id": "menu-pad",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Menu",
  "style": "dpad",
  "sticky": true,
  "deadzone": 0.3,
  "tint": "#667eea"
}

Open in CAR-TER

Quiet camera pan

A slow-sending stick with no label for a clean card.

JSON 11 lines
{
  "type": "joystick",
  "id": "pan-stick",
  "position": [0, 3],
  "span": [3, 3],
  "hideLabel": true,
  "sendRate": 0.5,
  "deadzone": 0.2,
  "tint": "#34C759",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "camera", "type": "pan", "payload": { "x": "$value.x", "y": "$value.y" } } }
}

Open in CAR-TER

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Robot drive controller” on your phone.

    carterkit demo joystick --example 'Robot drive controller'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Generated from ControlDocs/joystick.md. Something unclear or missing? Tell me.