Guide / Controls / Reference

Value Types

The kinds of value CAR-TER can show or send, and the units a measurement can carry. These are catalog vocabulary, not wire vocabulary: a binding's JSON is unchanged — a gauge bound to heading still receives a plain number. The type and unit tell the designer, carterkit and the MCP what that number

Symbol
number.square
Docs
Docs complete

Fields

2 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
valueTypevalueTypechoiceone of 10—

What kind of value it is

Labels a capability's reading as one of the catalog value kinds so designers can pick sensible controls.

  • booltrue or false
  • integera whole number
  • numberany number, with decimals
  • stringtext
  • datean ISO-8601 string or epoch milliseconds
  • durationa number of seconds
  • measurementa number in the capability's unit
  • locationan object with latitude and longitude
  • jsonany JSON
  • listan array of row objects, from local rows only
unitunittext—

The unit the number is in

Names the unit a reading arrives in so the readout converts to the device's locale, e.g. celsius shows as F in the US.

Examples

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

Temperature in its source unit

Demonstrates unit: "celsius": the value stays in °C on the wire, but the readout shows °F on a US-locale device.

JSON 12 lines
{
  "type": "gauge",
  "id": "outside",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 40,
  "unit": "celsius",
  "label": "Outside"
}

Open in CAR-TER

Speed from a sensor key

Demonstrates unit: "kilometersPerHour" on a speed reading; it shows mph on a US device while min and max stay in km/h.

JSON 18 lines
{
  "type": "gauge",
  "id": "speed",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 120,
  "unit": "kilometersPerHour",
  "label": "Speed",
  "sync": [
    {
      "method": "sensor",
      "sensor": "location.speedKmh"
    }
  ]
}

Open in CAR-TER

A literal unit suffix

Demonstrates a unit that is not in the table: "dBFS" is shown exactly as written after the number.

JSON 18 lines
{
  "type": "gauge",
  "id": "loudness",
  "position": [
    0,
    0
  ],
  "min": -60,
  "max": 0,
  "unit": "dBFS",
  "label": "Loudness",
  "sync": [
    {
      "method": "sensor",
      "sensor": "audio.dbfs"
    }
  ]
}

Open in CAR-TER

is, so they can label it ("Heading, degrees") and pick sensible controls.

Value types

Type On the wire Example
bool true / false true
integer a number with no fraction 42
number a number 21.5
string a string "WNW"
date an ISO-8601 string or epoch milliseconds "2026-09-27T09:30:00Z"
duration a number of seconds 90
measurement a number, in the capability's unit 21.5
location an object with latitude and longitude {"latitude": 45.5, "longitude": -73.6}
json any JSON {"any": [1, 2]}
list an array of row objects — local rows only [{"name": "Basil"}]

The list is closed: a new kind of value is a change to this page first.

Units

A measurement names one real unit. Unit names are Foundation's (UnitTemperature.celsius → celsius), so the app can convert for display: a reading in celsius shows as °F on a US-locale device. A unit string not in this table is shown literally, exactly as written ("°/s", "dBFS").

Unit Dimension Symbol
degrees angle °
kilopascals, hectopascals pressure kPa, hPa
meters, kilometers, miles, feet length m, km, mi, ft
metersPerSecond, kilometersPerHour, milesPerHour speed m/s, km/h, mph
gravity acceleration g
celsius, fahrenheit, kelvin temperature °C, °F, K
seconds, minutes, hours duration s, min, h
percent ratio % (0–100, never converted)

The control unit field

gauge, label and progressRing (and statTile) take one optional unit naming the unit their value arrives in — a name above, its symbol (°C, km/h, mph, kPa, %, …) or the name in any case. The value on the wire and in storage never changes; only the readout converts, to the device locale:

Dimension US UK Metric
temperature (celsius, fahrenheit) °F °C °C
speed mph mph km/h
length, short (meters, feet) ft m m
length, long (kilometers, miles) mi mi km
pressure inHg as written as written

kelvin, angles, durations, gravity and percent never convert. min, max and gauge segments stay in the source unit, so a needle, fill or colour zone sits in the same place on every device. A binding whose sensor key names its unit (location.speedKmh, location.speedMph, location.speed) keeps that unit. Any other string is a literal suffix ("unit": "dBFS" → 12.5 dBFS).

Where types come from

  • Each Sensors key declares its type and unit in the sensors page's front matter; the app's capability catalog is checked against that table.
  • Server-fed values (meshsocket, mqtt, http) are json until the layout says otherwise — the catalog can't know what a server sends.

Setup states

Every capability is in one of these states on a given device:

State Meaning
ready Works now
allowAccess Needs an iOS permission (location, microphone, Motion & Fitness)
configure Needs a setting filled in (an MQTT broker, an HTTP URL)
needsYourServer Needs a server on the mesh to send or answer
unsupported This device or app version can't do it
signIn Reserved — no capability uses it yet

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