Guide / Controls / Reference

Sensors

Bind controls to this device's own hardware — compass, motion, barometer, vitals, sound level, location — with no server and no network. A sync entry with method: "sensor" feeds the control live readings the moment the layout opens.

Symbol
gyroscope
Docs
Docs complete

Fields

2 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
methodmethodtext—

Where the value comes from

Set to sensor on a sync entry so the control reads this phone's own hardware instead of a server.

sensorsensortext—

Which reading to use

Names the hardware pipeline and optional key, e.g. heading or motion.roll, that feeds the control live.

Examples

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

Compass gauge

Demonstrates method: "sensor" with sensor: "heading": a dial that follows the phone's compass.

JSON 17 lines
{
  "type": "gauge",
  "id": "compass",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 360,
  "label": "Heading",
  "sync": [
    {
      "method": "sensor",
      "sensor": "heading"
    }
  ]
}

Open in CAR-TER

Battery level

Demonstrates the dotted key device.battery: a gauge showing the phone's charge as 0 to 100.

JSON 17 lines
{
  "type": "gauge",
  "id": "battery",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 100,
  "label": "Battery",
  "sync": [
    {
      "method": "sensor",
      "sensor": "device.battery"
    }
  ]
}

Open in CAR-TER

Roll angle

Demonstrates sensor: "motion.roll": a gauge that tilts with the phone's roll, in degrees.

JSON 17 lines
{
  "type": "gauge",
  "id": "roll",
  "position": [
    0,
    0
  ],
  "min": -90,
  "max": 90,
  "label": "Roll",
  "sync": [
    {
      "method": "sensor",
      "sensor": "motion.roll"
    }
  ]
}

Open in CAR-TER

Definition

{
  "type": "gauge",
  "id": "compass",
  "min": 0, "max": 360,
  "sync": [{ "method": "sensor", "sensor": "heading" }]
}

The sensor string names a pipeline, optionally dotted with one of its reading keys: "heading" is shorthand for "heading.value", and "motion.roll" picks the roll angle. Any control that can listen — Unit, Border thickness, Title, Unit, Starting status, Particles — can bind.

Pipelines & keys

Pipeline value means Other keys
heading Magnetic heading, 0–360° magnetic, trueHeading, accuracy, cardinal ("WNW")
motion Pitch, degrees pitch, roll, yaw, accel (g), rotation (°/s)
barometer Pressure, kPa pressure, altitude (relative m)
device Battery, 0–100 battery, state, thermal, lowPower, brightness
audio Loudness, 0–100 rel. dB level, dbfs, peak
location Speed, km/h latitude, longitude, speed (m/s), speedKmh, speedMph, course, altitude, accuracy, timestamp_ms

Every key's friendly name, value type and unit is the keys table in this page's front matter (see Value Types); the app's capability catalog is checked against it, so a key added in code without a row here fails the tests.

Permissions & battery

  • heading, motion, and device need no permission.
  • barometer asks for Motion & Fitness; audio for the microphone; location for While-Using access. iOS prompts once, on first use.
  • Hardware runs only while a bound layout is on screen — switching layouts or backgrounding the app stops every pipeline immediately.
  • audio measures loudness only. Samples never leave the audio tap.

Notes

  • On-screen bindings stay on the device. To stream readings to your server or another CAR-TER device, add a Publishers block — that path is consent-gated.
  • The simulator has no compass/barometer and reports battery as unknown; test sensors on hardware.
  • Multiple controls can bind the same pipeline; it runs once.

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