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

Charts

Inputs

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.

DocStatusFields describedValues explainedExamplesStills
Action ringcompassDocs complete11/111/131/3
BlockstreemapDocs complete14/141/132/3
ButtonbuttonDocs complete13/133/31616/16
CardscardListDocs complete——31/3
ChartchartDocs complete35/353/31111/11
ChatchatDocs complete12/12—31/3
ChoicesegmentedControlDocs complete15/153/388/8
ColorcolorPickerDocs complete9/9—31/3
ConnectionschordDocs complete12/121/132/3
Date & timedatePickerDocs complete10/103/355/5
DetailskeyValueDocs complete16/161/188/8
DialgaugeDocs complete18/184/41313/13
DividerdividerDocs complete4/41/131/3
Flip cardflipCardDocs complete9/92/231/3
FlowssankeyDocs complete15/151/132/3
Free canvascanvasDocs complete10/101/132/3
Heat gridheatmapDocs complete25/253/366/6
JoystickjoystickDocs complete9/91/131/3
LoglogConsoleDocs complete10/101/131/3
MapmapDocs complete7/71/166/6
MenupickerDocs complete12/123/366/6
NetworkgraphDocs complete34/34—88/8
PagescarouselDocs complete12/122/255/5
PictureimageDocs complete9/92/255/5
PiepieChartDocs complete25/252/266/6
Pin boardpinboardDocs complete11/111/131/3
Plus / minusstepperDocs complete17/173/377/7
QR codeqrCodeDocs complete6/61/155/5
RadarradarDocs complete19/192/232/3
RingprogressRingDocs complete15/154/4109/10
ScannercameraDocs complete15/154/433/3
SectionsaccordionDocs complete11/111/144/4
SlidersliderDocs complete25/253/377/7
Sort boardsortboardDocs complete11/111/133/3
SpacespacerDocs complete——31/3
SpreadboxPlotDocs complete20/203/332/3
Stat tilestatTileDocs complete21/213/31111/11
Status dotstatusLightDocs complete8/82/266/6
SwitchtoggleDocs complete23/233/377/7
SymbolsymbolDocs complete30/308/81010/10
TablelistDocs complete20/202/285/8
TextlabelDocs complete21/214/41917/19
Text boxtextInputDocs complete16/162/255/5
TimelineganttDocs complete16/161/132/3
Trend linesparklineDocs complete10/101/143/4
Web pagewebViewDocs complete6/6—31/3
ActionsactionsDocs complete25/252/230/3
AnimationsanimationsDocs complete2/2—30/3
AppearanceappearanceDocs complete5/52/230/3
Control Center Controlsglance-controlsDocs complete16/162/230/3
Control Definitioncontrol-defDocs complete37/374/430/3
Data SourcessourcesDocs complete8/81/130/3
DerivederiveDocs complete26/261/130/3
Document Contractdocument-contractDocs complete6/6—30/3
FormformDocs complete5/52/230/3
Glance SurfacesglanceDocs complete13/13—30/3
Glance Widgetsglance-widgetsDocs complete8/8—30/3
Grid Dimensionsgrid-dimensionsDocs complete7/7—40/4
Groupgroup-defDocs complete28/281/330/3
HapticshapticsDocs complete1/1—30/3
Hub Surfaceshub-surfacesDocs complete5/51/130/3
Internalshared-fieldsDocs in progress16/16—0—
Layout Configlayout-configDocs complete32/321/130/3
Live Activity and Dynamic Islandglance-live-activityDocs complete17/175/530/3
Local Storelocal-storeDocs complete16/162/230/3
Lock Screenglance-lock-screenDocs complete3/3—30/3
Long Presslong-pressDocs complete2/2—30/3
PublisherspublishersDocs complete2/2—30/3
PulsepulseDocs complete7/72/230/3
SensorssensorsDocs complete2/2—30/3
Style Rulesstyle-rulesDocs in progress——0—
SyncsyncDocs complete23/23—30/3
ThemingthemingDocs complete114/1144/450/5
Value TypesvaluesDocs complete2/21/130/3
VisibilityvisibilityDocs complete8/8—40/4
WiringprofilesDocs 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

  1. Each device opens a WebSocket to the MeshSocket server
  2. The device sends an identify message with its name, channel, and role
  3. The server routes messages between devices in the same channel
  4. 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

  1. Explore the docs — tap nodes in the graph to learn about each control
  2. Write a layout — create a JSON file following the Layout Config schema
  3. 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
  4. 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.