Guide / Reference
Controls.
The 46 controls you can put on a layout: what each one shows or changes, every field it takes, and examples you can paste.
Readouts
Cards
cardListA stack of cardsDocs complete Chat
chatMessages back and forthDocs complete Details
keyValueLabeled readings from one objectDocs complete Dial
gaugeA number on a dial, from low to highDocs complete Log
logConsoleLines of messages as they arriveDocs complete QR code
qrCodeA code a phone camera can scanDocs complete Ring
progressRingHow far along something isDocs complete Stat tile
statTileA big number, its change, and a faint trendDocs complete Status dot
statusLightA colored dot: OK, busy, or offDocs complete Symbol
symbolAn icon that can animateDocs complete Table
listRows of informationDocs complete Text
labelA line of text, or a value with a captionDocs complete
Charts
Blocks
treemapSizes compared as blocksDocs complete Chart
chartLines or bars over timeDocs complete Connections
chordHow things connect to each otherDocs complete Flows
sankeyWhere amounts flow from and toDocs complete Heat grid
heatmapColored squares that show how muchDocs complete Network
graphDots joined by linesDocs complete Pie
pieChartParts of a wholeDocs complete Radar
radarSeveral scores on one shapeDocs complete Spread
boxPlotHow a set of numbers spreads outDocs complete Timeline
ganttTasks laid out over timeDocs complete Trend line
sparklineA little line that shows how a number changesDocs complete
Inputs
Action ring
compassTurn a ring to pick an actionDocs complete Choice
segmentedControlPick one of a few optionsDocs complete Color
colorPickerPick a colorDocs complete Date & time
datePickerPick a day or a timeDocs complete Free canvas
canvasPlace things anywhere on a surfaceDocs complete Joystick
joystickSteer with your thumbDocs complete Menu
pickerPick one from a listDocs complete Pin board
pinboardPin things onto a pictureDocs complete Plus / minus
stepperCount up or down one step at a timeDocs complete Slider
sliderSlide to pick a numberDocs complete Sort board
sortboardDrag cards between columnsDocs complete Switch
toggleTurns something on or offDocs complete Text box
textInputType something inDocs complete
Buttons
Media
Layout
Building blocks
The parts every layout shares: data, actions, themes, and the surfaces outside the app.
Docs coverage
73 of 76 docs are complete. 1103 of 1103 fields say what they do, 120 of 122 choice fields explain every value, and 230 of 351 examples have a picture rendered by the app.
| Doc | Status | Fields described | Values explained | Examples | Stills |
|---|---|---|---|---|---|
Action ringcompass | Docs complete | 11/11 | 1/1 | 3 | 1/3 |
Blockstreemap | Docs complete | 14/14 | 1/1 | 3 | 2/3 |
Buttonbutton | Docs complete | 13/13 | 3/3 | 16 | 16/16 |
CardscardList | Docs complete | — | — | 3 | 1/3 |
Chartchart | Docs complete | 35/35 | 3/3 | 11 | 11/11 |
Chatchat | Docs complete | 12/12 | — | 3 | 1/3 |
ChoicesegmentedControl | Docs complete | 15/15 | 3/3 | 8 | 8/8 |
ColorcolorPicker | Docs complete | 9/9 | — | 3 | 1/3 |
Connectionschord | Docs complete | 12/12 | 1/1 | 3 | 2/3 |
Date & timedatePicker | Docs complete | 10/10 | 3/3 | 5 | 5/5 |
DetailskeyValue | Docs complete | 16/16 | 1/1 | 8 | 8/8 |
Dialgauge | Docs complete | 18/18 | 4/4 | 13 | 13/13 |
Dividerdivider | Docs complete | 4/4 | 1/1 | 3 | 1/3 |
Flip cardflipCard | Docs complete | 9/9 | 2/2 | 3 | 1/3 |
Flowssankey | Docs complete | 15/15 | 1/1 | 3 | 2/3 |
Free canvascanvas | Docs complete | 10/10 | 1/1 | 3 | 2/3 |
Heat gridheatmap | Docs complete | 25/25 | 3/3 | 6 | 6/6 |
Joystickjoystick | Docs complete | 9/9 | 1/1 | 3 | 1/3 |
LoglogConsole | Docs complete | 10/10 | 1/1 | 3 | 1/3 |
Mapmap | Docs complete | 7/7 | 1/1 | 6 | 6/6 |
Menupicker | Docs complete | 12/12 | 3/3 | 6 | 6/6 |
Networkgraph | Docs complete | 34/34 | — | 8 | 8/8 |
Pagescarousel | Docs complete | 12/12 | 2/2 | 5 | 5/5 |
Pictureimage | Docs complete | 9/9 | 2/2 | 5 | 5/5 |
PiepieChart | Docs complete | 25/25 | 2/2 | 6 | 6/6 |
Pin boardpinboard | Docs complete | 11/11 | 1/1 | 3 | 1/3 |
Plus / minusstepper | Docs complete | 17/17 | 3/3 | 7 | 7/7 |
QR codeqrCode | Docs complete | 6/6 | 1/1 | 5 | 5/5 |
Radarradar | Docs complete | 19/19 | 2/2 | 3 | 2/3 |
RingprogressRing | Docs complete | 15/15 | 4/4 | 10 | 9/10 |
Scannercamera | Docs complete | 15/15 | 4/4 | 3 | 3/3 |
Sectionsaccordion | Docs complete | 11/11 | 1/1 | 4 | 4/4 |
Sliderslider | Docs complete | 25/25 | 3/3 | 7 | 7/7 |
Sort boardsortboard | Docs complete | 11/11 | 1/1 | 3 | 3/3 |
Spacespacer | Docs complete | — | — | 3 | 1/3 |
SpreadboxPlot | Docs complete | 20/20 | 3/3 | 3 | 2/3 |
Stat tilestatTile | Docs complete | 21/21 | 3/3 | 11 | 11/11 |
Status dotstatusLight | Docs complete | 8/8 | 2/2 | 6 | 6/6 |
Switchtoggle | Docs complete | 23/23 | 3/3 | 7 | 7/7 |
Symbolsymbol | Docs complete | 30/30 | 8/8 | 10 | 10/10 |
Tablelist | Docs complete | 20/20 | 2/2 | 8 | 5/8 |
Textlabel | Docs complete | 21/21 | 4/4 | 19 | 17/19 |
Text boxtextInput | Docs complete | 16/16 | 2/2 | 5 | 5/5 |
Timelinegantt | Docs complete | 16/16 | 1/1 | 3 | 2/3 |
Trend linesparkline | Docs complete | 10/10 | 1/1 | 4 | 3/4 |
Web pagewebView | Docs complete | 6/6 | — | 3 | 1/3 |
Actionsactions | Docs complete | 25/25 | 2/2 | 3 | 0/3 |
Animationsanimations | Docs complete | 2/2 | — | 3 | 0/3 |
Appearanceappearance | Docs complete | 5/5 | 2/2 | 3 | 0/3 |
Control Center Controlsglance-controls | Docs complete | 16/16 | 2/2 | 3 | 0/3 |
Control Definitioncontrol-def | Docs complete | 37/37 | 4/4 | 3 | 0/3 |
Data Sourcessources | Docs complete | 8/8 | 1/1 | 3 | 0/3 |
Derivederive | Docs complete | 26/26 | 1/1 | 3 | 0/3 |
Document Contractdocument-contract | Docs complete | 6/6 | — | 3 | 0/3 |
Formform | Docs complete | 5/5 | 2/2 | 3 | 0/3 |
Glance Surfacesglance | Docs complete | 13/13 | — | 3 | 0/3 |
Glance Widgetsglance-widgets | Docs complete | 8/8 | — | 3 | 0/3 |
Grid Dimensionsgrid-dimensions | Docs complete | 7/7 | — | 4 | 0/4 |
Groupgroup-def | Docs complete | 28/28 | 1/3 | 3 | 0/3 |
Hapticshaptics | Docs complete | 1/1 | — | 3 | 0/3 |
Hub Surfaceshub-surfaces | Docs complete | 5/5 | 1/1 | 3 | 0/3 |
Internalshared-fields | Docs in progress | 16/16 | — | 0 | — |
Layout Configlayout-config | Docs complete | 32/32 | 1/1 | 3 | 0/3 |
Live Activity and Dynamic Islandglance-live-activity | Docs complete | 17/17 | 5/5 | 3 | 0/3 |
Local Storelocal-store | Docs complete | 16/16 | 2/2 | 3 | 0/3 |
Lock Screenglance-lock-screen | Docs complete | 3/3 | — | 3 | 0/3 |
Long Presslong-press | Docs complete | 2/2 | — | 3 | 0/3 |
Publisherspublishers | Docs complete | 2/2 | — | 3 | 0/3 |
Pulsepulse | Docs complete | 7/7 | 2/2 | 3 | 0/3 |
Sensorssensors | Docs complete | 2/2 | — | 3 | 0/3 |
Style Rulesstyle-rules | Docs in progress | — | — | 0 | — |
Syncsync | Docs complete | 23/23 | — | 3 | 0/3 |
Themingtheming | Docs complete | 114/114 | 4/4 | 5 | 0/5 |
Value Typesvalues | Docs complete | 2/2 | 1/1 | 3 | 0/3 |
Visibilityvisibility | Docs complete | 8/8 | — | 4 | 0/4 |
Wiringprofiles | Docs in progress | — | — | 0 | — |
About the control docs
How It Works
CAR-TER renders layouts — JSON files that describe a grid of interactive controls. Each control can send commands and receive live data over a persistent WebSocket mesh.
A layout defines tabs, each containing a grid of controls. Controls range from simple buttons and toggles to live gauges, sparklines, maps, and graphs. Everything is driven by data — what you see on screen is exactly what the JSON describes.
The Control System
Every control in CAR-TER is declared as a JSON object with a type, id, and grid position. The system supports 46 control types across three categories:
Input Controls
Buttons, toggles, sliders, steppers, pickers, date pickers, text inputs, color pickers, and segmented controls. These send user actions to your server. The camera control scans QR codes, barcodes, and text live — detections are on the mesh the moment they're seen. Container controls — carousels, flip cards, and accordions — arrange sets of groups into swipeable pages, flippable faces, and collapsible sections.
The drag pack makes arrangement itself the input: sortboards drag items between bound zones (kanban, seating, triage), pinboards place markers anywhere on a freeform surface (floor plans, maps, photos), and the compass ring mixes drag with the device's heading sensor — point the needle at a puck to fire its action. The Max zoom goes structural: a pan/zoom freeform surface hosting whole working controls at any position and size, rearrangeable in place. Every drop emits pickup/place/layout events, and the whole arrangement round-trips as synced state a server can seed or rearrange.
Display Controls
Gauges, progress rings, sparklines, labels, images, maps, and graphs. These visualize incoming telemetry data in real time. The stat tile is a whole KPI in one card — the number, its change against a reference, a threshold tint, and a faint trend. The Effect control is the glyph itself — SF Symbols with native rendering modes, variable layers, and looping effects, plus custom rain, snow, and sparkles, animated on the phone with no server frames.
The chart pack blurs the line: charts (bar/line/area/scatter/histogram/waterfall) with tappable datums, pie charts that double as spin-to-select wheels and radial menus, heatmaps you can paint like an LED matrix or weekly scheduler, and radar profiles whose vertices drag like a multi-parameter tuner. The statistical wing goes further: box/violin plots that compute quartiles and densities on-device, gantt timelines whose bars drag like progress sliders, sankey flows and chord matrices that spotlight on tap, and treemaps with Files-style drill-down. Every one displays live data and talks back.
The key–value table closes the last shape gap: a feed that returns an object rather than an array renders as labeled rows, chips, or cards without unrolling it into one label per key.
Data Flow
Every control can sync with a backend. Input controls fire actions; display controls listen for incoming data and update automatically. The connection block is standardized: the same filter/valuePath/{{value}} vocabulary works over a MeshSocket server, an MQTT broker, a polled HTTP API (Data Sources), or the on-device Local Store — method just picks the wire, so you know exactly what a control accepts and emits no matter the backend. A layout can also Derive values on the phone (watts = volts × amps) from what its controls show, with no server code.
MeshSocket Protocol
CAR-TER communicates through MeshSocket — a lightweight WebSocket mesh networking protocol. Devices connect to a central server and join channels with assigned roles.
How Devices Connect
- Each device opens a WebSocket to the MeshSocket server
- The device sends an
identifymessage with its name, channel, and role - The server routes messages between devices in the same channel
- Controls fire events that flow through the mesh to all listeners
Message Types
- emit — fire-and-forget broadcast to the channel
- request — send a message and await a response
- broadcast — server pushes data to all channel members
- identify — authenticate and join a channel
Sync Configuration
Controls declare their data bindings in a sync array:
{
"type": "gauge",
"id": "cpu-gauge",
"sync": [{
"method": "meshsocket",
"type": "listen",
"event": "broadcast",
"filter": { "msg_type": "telemetry" },
"valuePath": "cpu"
}]
}
When the server broadcasts {"msg_type": "telemetry", "cpu": 73} (a broadcast_request, which the relay delivers to every channel member as a broadcast frame), the gauge updates to 73 automatically. The filter keeps frames with other msg_types from touching it.
Chat
CAR-TER includes a built-in chat control powered by MeshSocket. Messages flow through the mesh in real time and are persisted locally with SwiftData.
Chat uses the same channel and identity system as all other controls — your display name comes from the connection config, and messages are routed through the mesh to all channel members.
Layout Structure
A layout JSON file has this shape:
{
"name": "My Layout",
"headerTitle": "Dashboard",
"accentColor": "#667eea",
"tabs": [
{
"title": "Controls",
"icon": "slider.horizontal.3",
"grid": { "columns": 4, "rows": 6 },
"children": [ ... ]
}
],
"connection": {
"url": "ws://192.168.1.100:4444",
"identity": {
"name": "My Phone",
"channel": "home",
"role": "controller"
}
}
}
Each tab lays its children out on a 2-D grid — a control's position and span
place it in a row × col rectangle, so a tall control can sit beside two stacked
shorter ones. Set a grid's mode to "flow" for the simpler row-banded layout
(full-page content, plain forms). See Grid Dimensions.
Tap any node in the graph to explore the full documentation for each control type, system feature, and data model.
Get Started
- Explore the docs — tap nodes in the graph to learn about each control
- Write a layout — create a JSON file following the Layout Config schema
- Bind your data — point controls at an MQTT broker or HTTP API you already
run (Data Sources, zero server code), or run a server: drive your layout from
Python with
pip install carterkit, or speak the MeshSocket protocol directly from any language - Connect — load your layout and watch it come alive
Full developer docs — building servers, the wire protocol, and the carterkit
library — live at carterbeaudoin.net/CAR-TER.
Control doc schema: depth keys
Each field in a control doc's frontmatter may carry these authored keys:
summary— plain-language subtitle shown in Simple mode.does— one sentence: what visibly changes on the phone when the field is set (e.g. "Rounds the card behind the text; 0 is square"). Hold and scrub rows show it as their help text. (effect:is taken: it is the look/behavior category.)valueHelp— enum fields only; one-line JSON mapping each value to one line of help, e.g.valueHelp: {"half": "a 180-degree arc", "full": "a closed ring"}. The editor shows it under the options.
A doc may declare depth: complete at the top level of its frontmatter. The depth
lint (ControlDocDepthTests) then requires summary and does on every field, a
valueHelp line for every value of every enum field, at least three ### examples
under ## Examples, and no summary/does that just repeats the field title.









