Typed actions example

RAM writes, an application mailbox and a register-field action.

Download example JSON · GitHub source · Authoring examples

Authoring example · Descriptor com.example.device-controls · version 1.0.0 · domain API 1.

Purpose and prerequisites

An authoring sample for adapting to your own firmware or instrument. Implement matching firmware/mailbox/SVD; actions require explicit debugger Send. It is not a tested board-support domain.

Engineering interpretation

The fields and thresholds below are the exact example contract. Replace placeholder sources and document the actual producer, units, safe-access conditions and acceptable states before enabling this on a target. Parsing success establishes format validity, not hardware compatibility.

Acquisition and validity

The descriptor declares 3 inputs and 0 derived channels, with a requested default of 20 Hz per input. Unsupported/unsafe rows remain unavailable. The achieved poll rate depends on the probe and selected inputs.

Inputs are sampled separately while firmware runs. DWARF paths require the exact Debug ELF; unresolved or null pointers produce unavailable values. A readable object is not proof that it has finished initialization. Firmware can update or reuse it between reads. Missing observations propagate to dependent fields and checks.

Cards with a capacity reference show value / capacity, not a percentage. Both readings must be available, capacity must be positive, and the value must lie between zero and capacity. Otherwise the card is unavailable. Individual fields retain their raw values in traces. Saved observations describe their acquisition time, not fresh target state.

Cards and tables

Controls

CARD OR ROW	READING AND SIGNIFICANCE	UNIT
Sample limit · `settings.limit`	u16 sample_limit readback. The allowed draft range is 0–500; a readback proves stored value, not application use. Explicit action: `set_limit`; see Actions below.	Raw value / decoded state
Device enabled · `device.enabled`	u8 device_enabled observation. The mailbox must invoke real application logic; a mirror write alone is not application control. Explicit action: `set_enabled`; see Actions below.	Raw value / decoded state
Flags · `device.flags`	Placeholder PORT.STATUS register. The action addresses its READY field; actual SVD access semantics must allow the declared write. Explicit action: `clear_ready`; see Actions below.	Raw value / decoded state

Every sampled input

All paths below come from the downloadable definition. Integer types specify width and signedness. No scaling is applied to a raw read. A field without a declared unit is a code, count, address or raw register; its engineering meaning is explained above or below.

INPUT	SOURCE / ADDRESS PATH	TYPE	INTERPRETATION / ACCESS
`settings.limit`	`sample_limit`	u16	See its card/table above.
`device.enabled`	`device_enabled`	u8	See its card/table above.
`device.flags`	`PORT.STATUS`	u32	See its card/table above.

Findings

This domain declares no automatic findings. Use the fields and the interpretation above; absence of a finding does not establish healthy operation.

Actions

These are templates requiring matching firmware and SVD support. set_limit writes RAM and confirms readback; set_enabled uses operation 1 in a firmware mailbox and waits up to 3000 ms for application completion; clear_ready uses the register-field transport path. Transport completion proves the write was delivered, not that application state changed. Only explicit Send in a supported live debugger executes actions; desktop/history views are read-only.

Set sample limit

set_limit; completion: readback.

{
  "input": {
    "ty": "u16",
    "min": 0,
    "max": 500
  },
  "target": {
    "kind": "ram",
    "source": {
      "symbol": "sample_limit",
      "steps": []
    },
    "execution": "running_scalar"
  }
}

Enable device

set_enabled; completion: application.

{
  "input": {
    "ty": "u8",
    "choices": [
      {
        "value": "0",
        "label": "Off"
      },
      {
        "value": "1",
        "label": "On"
      }
    ]
  },
  "target": {
    "kind": "mailbox",
    "symbol": "domain_command",
    "operation": 1,
    "timeout_ms": 3000
  }
}

Clear ready flag

clear_ready; completion: transport.

{
  "input": {
    "ty": "u32",
    "choices": [
      {
        "value": "1",
        "label": "Clear"
      }
    ]
  },
  "target": {
    "kind": "register",
    "peripheral": "PORT",
    "register": "STATUS",
    "field": "READY",
    "execution": "running_scalar"
  }
}

Definition and contribution

Verified against the complete authoring descriptor and the native validation, structured-source, derived-field, finding and action contracts. No real producer is supplied for this sample.

View or propose changes to the canonical JSON. Contribution guide.

Download SHA-256: 500afb9763a2c9e0f45bac43d799ce346a7e1263a9469443708e9c8f3f4202aa.

TRACE DOMAINS OVERVIEW ALL GUIDES EMAIL SUPPORT