Guide / Controls / Inputs

Action ring

Turn a ring to pick an action

When to use it. A heading-driven action ring. The device's live heading rotates a needle; you arrange action pucks around the ring; when the needle points at a puck (within tolerance) for dwell seconds, that puck's action fires. Point your phone at a thing to trigger it — no tapping. Pucks can be dragged around the ring to re-bearing them (firing pickup/place/layout), so the same control authors and runs.

Type
compass
Also titled
Compass
Default size
7 rows × 3 columns
Symbol
location.north.circle.fill
Docs
Docs complete
Search for it as
  • heading
  • direction
  • bearing
  • north
  • orientation
  • navigation
Action ring: Point-to-run scenes
Rendered by the app

Fields

11 fields you can set on a compass control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

Buzz when you use the ring

Plays this haptic when a puck is picked up, dropped or fires; the action firing uses medium when not set.

  • noneno haptic
  • lighta small light tap
  • mediuma medium tap and the default for firing
  • heavya strong tap
  • softa rounded cushioned tap
  • rigida sharp firm tap
  • selectiona tiny tick like scrolling a picker
  • successa success pattern
  • warninga warning pattern
  • erroran error pattern
Labellabeltext—

Title above the ring

Shows this text as the title above the ring.

HeightcontrolHeightnumber100–1200step 10420

How tall the ring is

Sets the ring's height in points, which also sets its size since it is square.

TolerancecompassConfig.tolerancenumber1–90step 115

How close the needle must aim

Counts the needle as pointing at a puck when it is within this many degrees of it.

Hold timecompassConfig.dwellnumber0–10step 0.11.2

How long to hold aim

Waits this many seconds of steady aim at a puck before its action fires; 0 fires at once.

LetterscompassConfig.showCardinalson / offtrue (on)

Show the N E S W letters

Draws the N, E, S and W letters around the ring when on.

Letter sizecompassConfig.cardinalSizenumber8–40step 113

Size of the compass letters

Sets the size of the N, E, S and W letters in points.

Letter colorcompassConfig.cardinalColorcolor—

Color of the compass letters

Colors the N, E, S and W letters; they use a neutral grey when not set.

EditablecompassConfig.editableon / offtrue (on)

Let people move the pucks

Lets you drag pucks around the ring to change their direction when on; off locks them all.

eventscompassConfig.eventsobject—

What happens when a puck is moved

Runs these actions when a puck is picked up, dropped or the layout changes.

puckscompassConfig.pucksobject—

The actions around the ring

Places one puck on the ring per entry at its bearing; aiming at it fires its action.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you aim at a puckpucksholdid

the id of the puck you are aiming at

It sends after the needle stays within Tolerance of the puck for the Hold time; with a hold of 0 it sends at once. Each puck carries its own action

Example: Item 1

When you drop a puckplacedropjson

the puck you dropped and its new bearing

Only when Editable is on; a layout event with every puck follows

Example: {"item": "Item 1", "x": 0, "y": 0, "bearing": 90}

Receives

Receives
TakesFromTypeWhat it does
valueshowsensor, hub, mqtt, http, store, defaultnumber

a heading in degrees, 0 for north, turning clockwise

the needle turns to it, and a puck fires when it is aimed at long enough

Example: 90

Sample

The placeholder value the editor shows before real data arrives.

  • 40 then 130

Examples

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

Point-to-run scenes

A three-puck ring where aiming the phone at a puck for a second runs that scene.

JSON 25 lines
{
  "type": "compass",
  "id": "action-ring",
  "position": [0, 0],
  "span": [7, 4],
  "controlHeight": 420,
  "label": "Action Ring",
  "defaultValue": 5,
  "compassConfig": {
    "tolerance": 20,
    "dwell": 1.0,
    "pucks": [
      { "id": "lights", "label": "Lights", "icon": "lightbulb.fill", "tint": "#FF9500", "bearing": 0,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } },
      { "id": "music", "label": "Music", "icon": "music.note", "tint": "#FF2D55", "bearing": 90,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } },
      { "id": "lock", "label": "Lock", "icon": "lock.fill", "tint": "#34C759", "bearing": 180,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } }
    ]
  },
  "sync": [{ "method": "sensor", "sensor": "heading" }]
}

Open in CAR-TER

Action ring: Point-to-run scenes
Rendered by the app

Fast ring with strong feedback

A tighter ring that fires the instant you aim, buzzes firmly, and keeps its pucks fixed in place.

JSON 24 lines
{
  "type": "compass",
  "id": "quick-ring",
  "position": [0, 0],
  "span": [7, 4],
  "controlHeight": 360,
  "label": "Quick Ring",
  "haptic": "heavy",
  "defaultValue": 100,
  "compassConfig": {
    "tolerance": 10,
    "dwell": 0,
    "editable": false,
    "pucks": [
      { "id": "door", "label": "Door", "icon": "door.left.hand.closed", "bearing": 90,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } },
      { "id": "garage", "label": "Garage", "icon": "car.fill", "bearing": 270, "locked": true,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } }
    ]
  },
  "sync": [{ "method": "sensor", "sensor": "heading" }]
}

Open in CAR-TER

Custom letters

A plain ring with larger orange compass letters, a longer hold and one puck at north to test aiming.

JSON 22 lines
{
  "type": "compass",
  "id": "letters-ring",
  "position": [0, 0],
  "span": [7, 4],
  "controlHeight": 400,
  "label": "Heading",
  "defaultValue": 0,
  "compassConfig": {
    "dwell": 2.5,
    "tolerance": 25,
    "showCardinals": true,
    "cardinalSize": 20,
    "cardinalColor": "#FF9500",
    "pucks": [
      { "id": "north", "label": "North", "icon": "arrow.up", "bearing": 0,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "home", "type": "scene", "payload": { "name": "{{value}}" } } } }
    ]
  },
  "sync": [{ "method": "sensor", "sensor": "heading" }]
}

Open in CAR-TER

Try it: the bundled compass-demo layout has this ring (seeded to 5° so a needle shows in the simulator).

Try it

These examples need more room than carterkit demo gives one control, so paste one into a layout instead. carterkit prints this page's fields in your terminal.

  1. Install the Python kit.

    pip install carterkit
  2. Read the fields offline.

    carterkit doc compass

carterkit quickstart

The first spatial (Pattern-3) drag control: puck placements ride a bearing coordinate (CARSpatialPlacementState) and the whole ring speaks the Toggle expand convention.

Heading (required)

The needle is driven by the control's own value — bind the compass sensor:

"sync": [{ "method": "sensor", "sensor": "heading" }]

The bound value is the heading in degrees (0 = N, clockwise). No compass hardware (e.g. the simulator)? Set a defaultValue (a number) to render a static needle for testing.

Sizing

Square control. In a mode: "flow" grid set controlHeight (e.g. 420); in a 2-D grid give it a real span. See Grid Dimensions.

Config (compassConfig)

Field Type Description
pucks array The action pucks (below).
tolerance number Half-angle (°) the needle must be within to "point at" a puck (default 15).
dwell number Seconds to hold before firing (default 1.2; 0 = instant on entry).
showCardinals bool N/E/S/W ticks (default true).
editable bool Drag pucks to re-bearing them (default true).
events object pickup / place / layout fired on puck drag.

Puck { id, label?, icon?, tint?, bearing, action?, locked? }

Field Type Description
bearing number Where it sits, degrees (0 = N, clockwise).
action object Fired on point-and-dwell. {{value}} = the puck id.
locked bool Can't be dragged (still activatable).

Events

Puck drag fires place { item, x, y, bearing } and layout { points: { id: {x,y,bearing} }, changed } (see DragEventActions). Puck activation fires that puck's own action.

Accessibility

Under VoiceOver each puck reads its bearing, double-tap fires its action (no pointing needed), and the adjustable action (swipe up/down) rotates it 15° per step.

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