Fields
7 fields you can set on a joystick control. Every control also takes the shared fields (id, position, span, sync, action).
Fields| Field | Type | Default | What it does |
|---|
Labellabel | text | — | The name shown under the stick Shows this text under the stick, above the live x/y readout, in the label font size. |
|---|
tinttint | color | #667eea | The stick color Colors the stick, its track ring and the faint center dead-zone disc. |
|---|
stylestyle | choiceone of 2 | analog | 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 zonedeadzone | number0–1step 0.05 | 0.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). |
|---|
Stickysticky | on / off | false (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 ratesendRate | number0.1–10step 0.1 | 0.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 shownhideLabel | on / off | false (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| Field | Type | Default | What it does |
|---|
cornerRadiustheme.cornerRadius | number0–30 ptstep 1 | 12 | Card outline color Colors the outline around the card. |
|---|
borderWidththeme.borderWidth | number0–5 ptstep 0.5 | 1 | 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| Sends | When | Type | What it sends |
|---|
While you move the stickvalue | change | json | 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.
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 ↗
Rendered by the appAn 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 ↗
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.
Install the Python kit.
pip install carterkit
Show “Robot drive controller” on your phone.
carterkit demo joystick --example 'Robot drive controller'
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.