Reference › Language reference › Structure

Reference › Language reference

Structure

The parts of a system, their ports, and the links between them.

On this page: system · component · port · interface · contract · handler · link · icd · canvas

Systems (model files), components, their ports and the links between them, and the contracts the two ends of a link agree on.

system#

A model — one Arche model file. Its children are the root components of the canvas; links connect them.

  • Keywords: system (old spelling: model)
  • Set: the model
  • Where: top level
  • Syntax: system Id "Name" { component … ; part x: Def ; a.p -> b.q }
Property Value Meaning
on-init code What the part runs once it is made, before any part starts: a ```arche block (its variables set from its parameters, a buffer filled…). archec sim runs every part's on-init at 0, in the order of the parts, before their on-start.
on-start code What the part runs when it starts: after every part's on-init, before its state machine enters its first state and its fn main runs.
on-stop code What the part runs when it stops: archec sim runs it at the end of the run (--for), in the order of the parts.
on-release code What the part runs when it is released, after every part's on-stop: what on-init took, given back.
equation any Continuous behaviour, integrated by the simulation between events: equation der(level) = (inflow - out) / AREA (a state: d(level)/dt per second) or equation out = K * sqrt(level) (algebraic, evaluated in order). Names are its variables, its ports (a port's flow: what leaves an out arrives at the in ports it links to, flows into one port add up), constants, parameters, t (seconds) and the functions sqrt, exp, ln, log10, sin, cos, min, max, clamp, abs, pow… In a part with physical ports (a port type with a potential and a flow), an equation has no direction: v = p.v - n.v, c * der(v) = p.i, p.i + n.i = 0, der(x) anywhere in it, a port's variables written port.name; archec physics sorts and solves them.
solver duration The fixed step its equations are integrated at (RK4); 1ms when not said.
fmu string An FMU (FMI 2.0 for co-simulation, an .fmu or its folder) that is its continuous behaviour: copied into the project (fmus/) and stepped by the simulation at the solver step. Its inputs are the flows into its in ports, or its variables, of the same name; its outputs go to its out ports, or its variables (upper.level is upper_level). archec import plant.fmu writes the component.
solver-sample duration How often a solved value is written to the trace (10ms when not said).
budget any A budget: the allowance for a number added up over everything beneath (budget power 150W, budget mass 20kg), or a limit that holds everywhere (budget temperature max 85°C). The same-named numbers of the blocks inside are the draws (power 15W, or a var power). Written as Arche budget variables (rollup: sum | max); an overrun is reported with who draws what. Units are not converted: a draw in another unit is reported.
variants list of variant names The variants it belongs to (variant declarations); one that says nothing belongs to all.
source text Where it is implemented (repeatable): a file, a folder or a glob (src/planner/**, src/*.ts), from the main file's folder. Arche sources. archec recover writes them; archec conform checks the code's imports against the links with them (the most specific source names a file).
ref element name This component is another model's component, shown here: ref tile.tile (Arche ref: {file, component}).
hardware any Its hardware sheet, as a record: the board, the module, their part numbers, dimensions, power… (Arche hardware). os, ram, isa, freq and bitrate are added to it.
implementation any Where its code lives, as a record: language, path, module, type (Arche code; code "x.py" is the Python the simulation runs).
summary text On a component definition (a template): the line its catalog entry shows, apart from the component's own description (templates.yaml, the entry's description).
code text TypeScript or Python files holding this element's behaviour (ctrl.ts, ctrl.py). A fn with no ``` block takes the function of the same name; on-enter name (any code property) takes the function named; on_enter_State, on_exit_State, on_receive_port, on_write_MEM bind by themselves. Bodies are copied into the Arche project, with the top-level constants and helpers each one uses — a copy per function, so a top-level name cannot keep state between calls: keep it on the component (var n, self.n).
handlers typescript | python | arche The language its behaviour is written in, when not the project's: typescript, python or arche (the action language). docs/handlers.md.
pip text The Python packages its Python bodies import, as pip takes them (repeatable, or a list): pip "numpy>=1.26", "sympy". archec sim checks them in the Python it runs and prints the pip command for what is missing; it installs nothing.
simulation-only bool It runs only in simulation (archec sim, Arche's simulator) and in host processes: its bodies are Python the action language cannot say (lists, dicts, big ints, libraries). The embedded generators (c, embassy, go, cpp on a microcontroller) refuse to deploy it to a microcontroller (simulation-only); the Python and TypeScript targets keep it.
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
tags list of tag names Tags from the tag catalog.
color color name A palette color id, or a literal "#rrggbb".
kind kind name Element kind from the kinds catalog (processor, device, bus…).
layer layer name Abstraction layer (operational, system, logical, physical…).
template ident Canvas shape template (box by default).
text-color color name Text color on the canvas.
at point Canvas position x, y (auto-laid-out when absent). On a part, with a name instead: at box.mount places its cad geometry at an anchor of another part's (docs/cad.md).
note-at point Where its note sits on the canvas, from the block: x, y.
size point Canvas size width, height.
image any A picture shown in the box on the canvas: a file path relative to this .arche file — copied into the project's images/ when it is built, so a component folder carries its own pictures — or the name of a file already in images/. , cover fills the box (default contain).
prop prop A free key/value property of the component.
purpose string What the component is FOR, one prose line each (Arche's main functions).
main string Old name of purpose (easy to confuse with fn main): still read, archec fmt --simplify renames it.
clock duration The component clock (period) used by wait clock: clock 10ms. With a name and a frequency (clock clk 100MHz) the component is an FPGA component (the fpga extension, docs/fpga.md): its ports typed with data are signals, its variables registers, its step function and its state machine run on every rising edge, and archec gen --target vhdl writes it as an entity.
reset any An FPGA component's reset (the fpga extension): its name, then active high (default) or active low, and sync (default) or async. At reset every variable takes its first value and the state machine its initial state.
step function name An FPGA component's function called on every rising edge of its clock (the fpga extension), as a thread's step is called every period.
mass any Mass budget contribution (any unit literal).
power any Power budget contribution.
shape any Its body's shape, for a physics engine (archec gen --target mujoco): box x, y, z (full sizes), sphere r, capsule or cylinder r, length (along z), at x, y, z where its centre is in the part's frame, rot how it is turned there (rot y 90deg, or roll, pitch, yaw rot 0, 90deg, 0).
joint any How the part moves relative to the part it is in (the world for a top part): hinge or slide along an axis (x, y, z, or [x, y, z]), ball, free, fixed (the default); at x, y, z where its frame is in its parent's, rot how it is turned there (roll, pitch, yaw about the parent's x, y, z: rot 0, 0, 90deg; or an axis and an angle: rot z 90deg; the axis is in the turned frame), range lo..hi its limits (rad or m), = value where it starts.
cad string Its geometry, as code: a Python file (relative to this file) that defines part, one build123d solid, and optionally anchors = {"mount": Location(...)}, the places other parts sit at. archec cad runs it, writes STEP, STL and GLB to build/cad/, and measures its size, volume, mass, centre of mass and inertia. On a part, it replaces its definition's. What it is made of may follow in a block: cad "cad/box.py" { material PETG }.
material ident What its cad geometry is made of, for its mass: one of PLA, PETG, ABS, ASA, TPU, PA12, PC, POM, PMMA, FR4, aluminium-6061, steel, stainless-304, brass, copper, titanium — or a constant of yours whose value is a density (const RESIN = 1.18g/cm³).
density any The density of its cad geometry, when no material says it (a printed part with 20 % infill is lighter than its plastic): density 0.45g/cm³, density 1270kg/m³.
pcb string Its KiCad board (a .kicad_pcb, relative to this file): its outline is read from the Edge.Cuts layer and its mounting holes from its MountingHole footprints, for fits; archec cad runs KiCad's DRC on it, and its ERC on the .kicad_sch of the same name, when kicad-cli is installed — evidence for the requirements the component satisfies.
outline any A board's size along x and y, when no pcb says it: outline 70mm, 82.5mm. Its frame has its origin at the lower-left corner, seen from the component side.
hole any A mounting hole of a board, when no pcb says them (repeatable): its diameter, and where its centre is from the lower-left corner of the outline — hole 3.2mm at 5mm, 5mm.
cost any Unit cost.
nature hardware | software Whether it is a piece of hardware (a target threads run on) or of software (runs on a thread). Set for you: by cores / core, and by a deployment.
cores number Number of identical cores, named cpu0 … cpuN-1 — makes the component a processor threads can be placed on.
core-type string What the cores are ("Cortex-A78").
os linux | linux-rt | qnx | rtos | freertos | zephyr | autosar-os | bare-metal What runs on the processor. On rtos and bare-metal a binary is one address space: its threads are RTOS tasks (tasks.yaml).
ram any Memory of the processor (16GiB): the budget process memory-limits are checked against.
flash any The program memory of a microcontroller (512KiB): what its firmware must fit in. The boards of the store say it.
isa ident Instruction set (arm64, riscv32…).
hal std | stm32 | rp | nrf | esp32 The Embassy HAL archec gen --target embassy builds against: std (a host process), stm32, rp, nrf, esp32. Default: std on Linux/QNX, else a Cortex-M skeleton that names the HAL to pick.
chip string The exact chip, as the HAL crate names it (stm32f446re, rp2040, nrf52840): the HAL feature archec gen enables.
freq any Core clock (2.2GHz).
bitrate any Bitrate of a kind bus component (2Mbps): the bus routes use, for transfer time and bus load.
ipc-latency duration Latency between two processes on this processor: the simulated latency of a link between them that states none.
runtime containerd | docker | podman | none The container runtime of a Linux processor: what a deployment's containers on it run under. archec gen --target containerd writes their images and compose file.
satisfies list of requirement names Requirements this element satisfies (emitted to traces.yaml).
verifies list of requirement names Requirements this element verifies.
refines list of element names Elements this one refines.
realizes list of element names Elements (one layer up) this one realizes.
allocated-to list of element names Elements this one is allocated to.
deploys list of element names Elements this one deploys.
traces list of element names Generic trace to other elements.
file string The model file it is written to (default: its id, car.yaml).
listed bool listed false: a model file the Models list does not offer (reached from the menu).
clearance any The least distance between two parts placed by their cad geometry (at), measured by archec cad: clearance board, relay >= 2mm. Parts that touch are at 0mm; parts that run into each other fail any clearance. In a system, a clearance not kept is an error of archec cad; in a requirement, it is evidence for it.
fits any A board's mounting holes are over the standoffs of the part that holds it: fits board, box, within 0.2 mm, or fits board, box <= 0.5mm. The holes are those of the board's pcb (a KiCad board), else its hole lines; the standoffs are the mounts = {"board": [(x, y, z), …]} of the box's geometry file, under the anchor the board sits at (at box.board). Checked by archec cad; in a requirement, it is evidence for it.
system Car "Autonomous car" {
  layer physical
  part lidar: Lidar
  part fusion: FusionEcu
  lidar.cloud -> fusion.lidar_in
}

component#

A component. At top level it is a reusable definition (templates.yaml); inside a system or component it is a child — part x: Def instantiates a definition, {…} overrides it. component LidarFront extends Lidar { … } is a definition built on another: it has the base's kind, ports, functions, variables, parameters and state machine, and what it writes adds to them or replaces them (by id); its state machine adds states and transitions to the base's.

  • Keywords: component · part (old spellings: block, subsystem, device, processor)
  • Set: the model
  • Where: top level, inside component, inside system
  • Syntax: component id ["Name"] [extends Base | : Definition] { kind …; port …; fn …; var …; memory …; states { … } }
Property Value Meaning
on-init code What the part runs once it is made, before any part starts: a ```arche block (its variables set from its parameters, a buffer filled…). archec sim runs every part's on-init at 0, in the order of the parts, before their on-start.
on-start code What the part runs when it starts: after every part's on-init, before its state machine enters its first state and its fn main runs.
on-stop code What the part runs when it stops: archec sim runs it at the end of the run (--for), in the order of the parts.
on-release code What the part runs when it is released, after every part's on-stop: what on-init took, given back.
equation any Continuous behaviour, integrated by the simulation between events: equation der(level) = (inflow - out) / AREA (a state: d(level)/dt per second) or equation out = K * sqrt(level) (algebraic, evaluated in order). Names are its variables, its ports (a port's flow: what leaves an out arrives at the in ports it links to, flows into one port add up), constants, parameters, t (seconds) and the functions sqrt, exp, ln, log10, sin, cos, min, max, clamp, abs, pow… In a part with physical ports (a port type with a potential and a flow), an equation has no direction: v = p.v - n.v, c * der(v) = p.i, p.i + n.i = 0, der(x) anywhere in it, a port's variables written port.name; archec physics sorts and solves them.
solver duration The fixed step its equations are integrated at (RK4); 1ms when not said.
fmu string An FMU (FMI 2.0 for co-simulation, an .fmu or its folder) that is its continuous behaviour: copied into the project (fmus/) and stepped by the simulation at the solver step. Its inputs are the flows into its in ports, or its variables, of the same name; its outputs go to its out ports, or its variables (upper.level is upper_level). archec import plant.fmu writes the component.
solver-sample duration How often a solved value is written to the trace (10ms when not said).
budget any A budget: the allowance for a number added up over everything beneath (budget power 150W, budget mass 20kg), or a limit that holds everywhere (budget temperature max 85°C). The same-named numbers of the blocks inside are the draws (power 15W, or a var power). Written as Arche budget variables (rollup: sum | max); an overrun is reported with who draws what. Units are not converted: a draw in another unit is reported.
variants list of variant names The variants it belongs to (variant declarations); one that says nothing belongs to all.
source text Where it is implemented (repeatable): a file, a folder or a glob (src/planner/**, src/*.ts), from the main file's folder. Arche sources. archec recover writes them; archec conform checks the code's imports against the links with them (the most specific source names a file).
ref element name This component is another model's component, shown here: ref tile.tile (Arche ref: {file, component}).
hardware any Its hardware sheet, as a record: the board, the module, their part numbers, dimensions, power… (Arche hardware). os, ram, isa, freq and bitrate are added to it.
implementation any Where its code lives, as a record: language, path, module, type (Arche code; code "x.py" is the Python the simulation runs).
summary text On a component definition (a template): the line its catalog entry shows, apart from the component's own description (templates.yaml, the entry's description).
code text TypeScript or Python files holding this element's behaviour (ctrl.ts, ctrl.py). A fn with no ``` block takes the function of the same name; on-enter name (any code property) takes the function named; on_enter_State, on_exit_State, on_receive_port, on_write_MEM bind by themselves. Bodies are copied into the Arche project, with the top-level constants and helpers each one uses — a copy per function, so a top-level name cannot keep state between calls: keep it on the component (var n, self.n).
handlers typescript | python | arche The language its behaviour is written in, when not the project's: typescript, python or arche (the action language). docs/handlers.md.
pip text The Python packages its Python bodies import, as pip takes them (repeatable, or a list): pip "numpy>=1.26", "sympy". archec sim checks them in the Python it runs and prints the pip command for what is missing; it installs nothing.
simulation-only bool It runs only in simulation (archec sim, Arche's simulator) and in host processes: its bodies are Python the action language cannot say (lists, dicts, big ints, libraries). The embedded generators (c, embassy, go, cpp on a microcontroller) refuse to deploy it to a microcontroller (simulation-only); the Python and TypeScript targets keep it.
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
tags list of tag names Tags from the tag catalog.
color color name A palette color id, or a literal "#rrggbb".
kind kind name Element kind from the kinds catalog (processor, device, bus…).
layer layer name Abstraction layer (operational, system, logical, physical…).
template ident Canvas shape template (box by default).
text-color color name Text color on the canvas.
at point Canvas position x, y (auto-laid-out when absent). On a part, with a name instead: at box.mount places its cad geometry at an anchor of another part's (docs/cad.md).
note-at point Where its note sits on the canvas, from the block: x, y.
size point Canvas size width, height.
image any A picture shown in the box on the canvas: a file path relative to this .arche file — copied into the project's images/ when it is built, so a component folder carries its own pictures — or the name of a file already in images/. , cover fills the box (default contain).
prop prop A free key/value property of the component.
purpose string What the component is FOR, one prose line each (Arche's main functions).
main string Old name of purpose (easy to confuse with fn main): still read, archec fmt --simplify renames it.
clock duration The component clock (period) used by wait clock: clock 10ms. With a name and a frequency (clock clk 100MHz) the component is an FPGA component (the fpga extension, docs/fpga.md): its ports typed with data are signals, its variables registers, its step function and its state machine run on every rising edge, and archec gen --target vhdl writes it as an entity.
reset any An FPGA component's reset (the fpga extension): its name, then active high (default) or active low, and sync (default) or async. At reset every variable takes its first value and the state machine its initial state.
step function name An FPGA component's function called on every rising edge of its clock (the fpga extension), as a thread's step is called every period.
mass any Mass budget contribution (any unit literal).
power any Power budget contribution.
shape any Its body's shape, for a physics engine (archec gen --target mujoco): box x, y, z (full sizes), sphere r, capsule or cylinder r, length (along z), at x, y, z where its centre is in the part's frame, rot how it is turned there (rot y 90deg, or roll, pitch, yaw rot 0, 90deg, 0).
joint any How the part moves relative to the part it is in (the world for a top part): hinge or slide along an axis (x, y, z, or [x, y, z]), ball, free, fixed (the default); at x, y, z where its frame is in its parent's, rot how it is turned there (roll, pitch, yaw about the parent's x, y, z: rot 0, 0, 90deg; or an axis and an angle: rot z 90deg; the axis is in the turned frame), range lo..hi its limits (rad or m), = value where it starts.
cad string Its geometry, as code: a Python file (relative to this file) that defines part, one build123d solid, and optionally anchors = {"mount": Location(...)}, the places other parts sit at. archec cad runs it, writes STEP, STL and GLB to build/cad/, and measures its size, volume, mass, centre of mass and inertia. On a part, it replaces its definition's. What it is made of may follow in a block: cad "cad/box.py" { material PETG }.
material ident What its cad geometry is made of, for its mass: one of PLA, PETG, ABS, ASA, TPU, PA12, PC, POM, PMMA, FR4, aluminium-6061, steel, stainless-304, brass, copper, titanium — or a constant of yours whose value is a density (const RESIN = 1.18g/cm³).
density any The density of its cad geometry, when no material says it (a printed part with 20 % infill is lighter than its plastic): density 0.45g/cm³, density 1270kg/m³.
pcb string Its KiCad board (a .kicad_pcb, relative to this file): its outline is read from the Edge.Cuts layer and its mounting holes from its MountingHole footprints, for fits; archec cad runs KiCad's DRC on it, and its ERC on the .kicad_sch of the same name, when kicad-cli is installed — evidence for the requirements the component satisfies.
outline any A board's size along x and y, when no pcb says it: outline 70mm, 82.5mm. Its frame has its origin at the lower-left corner, seen from the component side.
hole any A mounting hole of a board, when no pcb says them (repeatable): its diameter, and where its centre is from the lower-left corner of the outline — hole 3.2mm at 5mm, 5mm.
cost any Unit cost.
nature hardware | software Whether it is a piece of hardware (a target threads run on) or of software (runs on a thread). Set for you: by cores / core, and by a deployment.
cores number Number of identical cores, named cpu0 … cpuN-1 — makes the component a processor threads can be placed on.
core-type string What the cores are ("Cortex-A78").
os linux | linux-rt | qnx | rtos | freertos | zephyr | autosar-os | bare-metal What runs on the processor. On rtos and bare-metal a binary is one address space: its threads are RTOS tasks (tasks.yaml).
ram any Memory of the processor (16GiB): the budget process memory-limits are checked against.
flash any The program memory of a microcontroller (512KiB): what its firmware must fit in. The boards of the store say it.
isa ident Instruction set (arm64, riscv32…).
hal std | stm32 | rp | nrf | esp32 The Embassy HAL archec gen --target embassy builds against: std (a host process), stm32, rp, nrf, esp32. Default: std on Linux/QNX, else a Cortex-M skeleton that names the HAL to pick.
chip string The exact chip, as the HAL crate names it (stm32f446re, rp2040, nrf52840): the HAL feature archec gen enables.
freq any Core clock (2.2GHz).
bitrate any Bitrate of a kind bus component (2Mbps): the bus routes use, for transfer time and bus load.
ipc-latency duration Latency between two processes on this processor: the simulated latency of a link between them that states none.
runtime containerd | docker | podman | none The container runtime of a Linux processor: what a deployment's containers on it run under. archec gen --target containerd writes their images and compose file.
satisfies list of requirement names Requirements this element satisfies (emitted to traces.yaml).
verifies list of requirement names Requirements this element verifies.
refines list of element names Elements this one refines.
realizes list of element names Elements (one layer up) this one realizes.
allocated-to list of element names Elements this one is allocated to.
deploys list of element names Elements this one deploys.
traces list of element names Generic trace to other elements.
asil any Its ISO 26262 integrity level: QM, A … D — at least that of the requirements it satisfies (asil-allocation).
dal A | B | C | D | E | a | b | c | d | e Its DO-178C design assurance level: A (catastrophic) … E — at least that of the requirements it satisfies.
vendor string Who makes it: product { vendor "Espressif" }. The BOM and the board store read it.
part-number string The maker's part (or order) number: product { part-number "NUCLEO-G474RE" }.
url string Its product page or datasheet: product { url "https://…" }.
driver string Its driver in the hardware store's Go code (lib/arche-hw-store/devices/go, adapted from Gobot): the constructor archec gen --target go calls, with the bus and address its links and port say.
tested-with refs On a kind board: the devices tried on it, which the Store Shelves view offers first.
peripherals any On a kind board: how many of each peripheral it has, by kind — uart, i2c, spi, can as a list of names; adc with each one's channels and bits; dac and pwm with each one's number of channels; usb, ethernet, radio. any-pin [uart, i2c]: those go on any pin (an ESP32's GPIO matrix); shared [[I2C0, SPI0]]: one peripheral under two names. archec warns when a system uses more of one than the board has (board-peripheral).
pinout any On a kind board: what each pin can be besides a GPIO, as its chip names the functions (USART1_TX, I2C1_SDA, TIM1_CH2, ADC1_IN5). A port's pins are checked against it (pin-function), and two ports on one peripheral (board-peripheral). On a Linux board its keys are the header pins' ports (pin3 [GPIO2, I2C1_SDA]).
io-level any On a kind board: the voltage its pins work at (3.3V): the level of each port's pins that says none. A link to a part whose pins work at another level is a warning (pin-level).
rust-driver string What its Rust driver in the hardware store (devices/rust/.rs, for archec gen --target embassy) is built on: a crate of crates.io and its version, or embedded-hal 1.0 when the store's adapter drives the pins itself. docs/drivers.md.
rust-license string The license of the crate rust-driver names (SPDX): rust-license "MIT OR Apache-2.0".
stereotype splitter | joiner | cylinder | macro-algo | do-not-use-sw-caches | pipeline | local-memory-only | disable-thresholds | bypass-config-threading What kind of algorithm it is (kind algorithm): splitter (one input, cut over several outputs), joiner (several inputs, one output), cylinder (its executions spread over several cores), macro-algo, do-not-use-sw-caches, pipeline (it supports pipelining), local-memory-only. On a part: disable-thresholds, bypass-config-threading.
after refs On a part of a composite algorithm: the parts it executes after, with no data between them (a precedence link).
working-memory any On an algorithm: the memory it works in, saved (kept from one execution to the next) or tmp (scratch, for one execution): working-memory saved 4KiB. A deployment place says the allocator.
component Lidar "Lidar" {
  purpose "Scans the scene"
  kind device
  out cloud: ethernet sends POINT_CLOUD
  in pwr: power
  fn scan ```arche
    send cloud POINT_CLOUD { points: 1 }
  ```
}

port#

A port: a link endpoint with a type and direction. sends lists catalog messages; = child.port delegates to a child. port id: T is a port that says no direction.

  • Keywords: port · in · out · inout
  • Set: the model
  • Where: inside component, inside system, inside system-function
  • Syntax: in|out|inout id: [requires|provides] type ["Name"] [sends MSG, …] { handler … } | port id = child.port
Property Value Meaning
provides list of port type names Interfaces this port provides (Arche provides): its component implements their operations. A port that provides its own type says it in the header: out api: provides BrakeApi.
requires list of port type names Interfaces this port requires: the other end of each link must provide them. A port that requires its own type says it in the header: out tx: requires panel-device.
side ident Which side of the box it is drawn on: left, right, top, bottom.
address number The address of the device behind the port on its bus: an I²C address (address 0x77). Two parts with the same address on one bus is an error. A part overrides its definition's (part env2: Bme280 { inout i2c { address 0x76 } }).
pins any The pins of the chip this port is wired to, by role: pins { tx GPIO2; rx GPIO3 } (CAN), pins { sck PIN_18; mosi PIN_19; miso PIN_16; cs PIN_17; int PIN_20 } (an SPI CAN controller), pins { io PA5 } (one line: a LED, a button, a PWM output, an analog input). A board of the store says them; archec gen --target embassy drives the peripheral on them instead of its defaults. level 3.3V in it is the pins' I/O level, not a pin: a link between two levels is a warning (pin-level); archec pins shows each board's pin map.
voltage any On a power port: the voltage an out gives (a board's 3.3 V rail: voltage 3.3V), or what an in takes — one value or a range (voltage 3V..5.5V). A link from a rail to a part that does not take its voltage is a warning (board-supply).
current any On a power port: the most an out gives (a rail's budget), or what an in draws. The parts on one rail must not draw more than it gives (board-current); a part with power and no current draws its power over the rail's voltage.
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
color color name A palette color id, or a literal "#rrggbb".
sends list of message names Messages this port sends (out / inout).
unit string The unit of what flows on it (a port an equation names): both ends of a link must measure the same quantity.
receives list of message names Messages this port accepts (in / inout) — emitted as message handlers.
on-receive code Python run when a message arrives or a wire level changes. A ``` block, or the name of a def in a code .py file.
produces refs On an output: the errors its part makes by itself there — omission, commission, value, early, late. A failure-mode of the part that produces one rates it. archec derives each hazard's fault tree from them (archec safety).
contains refs On an input: the errors that stop there — a watchdog, a range check, a voter. all is every type.
turns any On an input: errors that go on as another type — turns value into omission (a check that drops a bad value makes it silent).
from refs On an output: the inputs whose errors reach it (by default, every input).
from-all refs On an output fed redundantly: an error leaves only when every one of these inputs carries it (an AND in the derived fault tree).
noise any On a sensor's out port (or on a port that provides an interface, as a device of the store: on what its operations read, in archec sim): the standard deviation of the gaussian noise on what it reads, added to each float field of what it sends whose unit is that quantity (noise 0.002rad; noise 0.05m/s², 0.001rad/s for an IMU; a bare number, every float field). Then the field's range saturates it. Drawn from a seed, so a run repeats (archec sim --seed): in the simulator, the MuJoCo bridge, and the C of a sim build (-DARCHE_SIM) — production firmware adds none.
resolution any On a sensor's out port (or a port that provides an interface): the step its reading is rounded to (an ADC's LSB, an encoder's count), by quantity as noise.
gain number On an actuator's in port: its output per unit of command (1 by default). The command is first clamped to its field's range (MuJoCo's ctrlrange).
lag duration On an actuator's in port: the time constant of a first-order lag from its command to its output (a motor's current loop, a valve).
force-range range On an actuator's in port: where its output saturates, lo..hi (a motor's peak torque; MuJoCo's forcerange).
latency duration Added to the latency of its links: on a sensor's out port, how old its reading is when it is sent; on an actuator's in port, its dead time. MuJoCo's sensor and actuator delay.
bitrate any Bitrate in bit/s, e.g. 1Mbps or 1000000.
jitter duration Random jitter added to latency.
pattern fire-and-forget | request-reply | pub-sub | broadcast | service | dataflow Interaction pattern, on the sending side: fire-and-forget (default — the sender never waits), request-reply (a correlated reply, call/reply in Python), pub-sub (1 → N subscribers), broadcast (everyone on the medium), service (a call to whoever serves a service name, wherever it runs: no link), dataflow (a source streams vectors of samples to sinks, which run when enough have come: threshold).
buffer queue | sample | stream What the receiver keeps: queue (every message counts; simulated as link queue), sample (last value wins; simulated as a queue of 1 that drops the oldest), stream (a continuous flow).
depth number Length of a queue buffer (depth alone means buffer queue).
overflow drop-oldest | drop-newest | block When a queue is full: drop-oldest, drop-newest (default), or block (analysis only — the simulator drops the newest).
timeout duration How long a request-reply waits for its reply.
retries number How many times a request-reply is sent again after a timeout.
async bool A request-reply that does not block: the reply arrives at a handler.
deferred bool On a request-reply server: the reply is sent later, not when the handler returns.
deadline duration The latest a message may arrive after it was sent.
stale-after duration A sample older than this is stale.
reliability reliable | best-effort reliable (every message arrives, possibly late) or best-effort (may be lost).
topic string The topic name of a pub-sub port (DDS / ROS 2 / MQTT). Its parts in braces are filled when the message is published, each from the field of that name (topic "/track/{id}"), or of the type written ({sensor: uint8}). A port with a topic is matched by its topic: a subscriber is an in port of the same topic, not a link (topic-wired).
service string The name of the service a port calls (an out) or serves (an in): a call reaches whoever serves that name, wherever it runs — no link. Gives the port pattern service.
vector ident On a dataflow port: the type of one sample of the vectors it streams.
header ident On a dataflow port: the type of the header each vector carries (DataVector[header]).
threshold number On a dataflow sink: how many samples must have come for it to run (the execution threshold).
push-threshold number On a dataflow source: how many samples it gathers before it pushes them to its sinks.
backpressure-threshold number On a dataflow sink: how many samples waiting make it ask its source to slow down (with backpressure on).
history number On a dataflow sink: how many samples of the vector before it each run sees again (a filter's overlap).
max-processing number On a dataflow sink: the most samples one run takes (the maximum processing size).
backpressure on | off On a dataflow port: on when the sink may make its source wait (backpressure-threshold), off (the default) when samples past its capacity are lost. Both ends of a link say the same.
transfer copy | share In buffering { }: copy (each consumer has its own buffer) or share (one buffer, shared).
on-deadline code What the part does instead, with a message it starts on later than the port's deadline after it was sent (a busy part, a slow link): its transitions, on-receive and handlers do not run for it. A ```arche block; simulated, and generated in C and in Rust (Embassy). Without it a late message is handled as any other.
satisfies list of requirement names Requirements this element satisfies (emitted to traces.yaml).
verifies list of requirement names Requirements this element verifies.
refines list of element names Elements this one refines.
realizes list of element names Elements (one layer up) this one realizes.
allocated-to list of element names Elements this one is allocated to.
deploys list of element names Elements this one deploys.
traces list of element names Generic trace to other elements.
max-size any In buffering { }, on a dataflow port: the largest buffer it holds, in bytes.
destroy after-transfer | after-processing In buffering { }: when a buffer is freed — after-transfer (once sent) or after-processing (once the consumer is done). share with after-transfer frees what another still reads: an error.
build any In buffering { }, on an output: allocate a new buffer, or reuse input — the buffer of an input of the same part, written in place.
allocator refs In buffering { }: the allocator its buffers come from (a deployment's allocator).
inout can0: can-fd "CAN" sends BRAKE_CMD receives WHEEL_SPEED

interface#

A contract a port takes part in: the messages that may cross it and the operations a provider implements (an Arche port type with messages and operations, in types.yaml). A port says provides I or requires I; a link whose one end requires what the other does not provide is reported, and so is a provider without a function for each operation. extends adds another interface's messages and operations. In a ```arche body, port.op(…) on a port that requires it calls the operation of the part at the other end of the link (docs/spec.md, Calling another part). As in IDL: an argument is in (the default), out or inout; oneway fn has no result and the caller does not wait; raises E1, E2 names the exceptions it may raise; attribute x: T (readonly attribute) is a value the provider holds.

  • Keywords: interface (old spelling: contract)
  • Set: the model
  • Where: top level
  • Syntax: interface Id "Name" { messages A, B; extends Base; [readonly] attribute x: T; [oneway] fn op([in|out|inout] arg: Type) [-> Type] [raises E, …] }
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
color color name A palette color id, or a literal "#rrggbb".
messages list of message names The messages that may cross a port taking part in it.
extends list of port type names Interfaces whose messages and operations are this one's too.
source text Where it is implemented (repeatable): a file or a folder — a driver class, a trait. Arche sources.
handling http | message What an in port of this type answers: http (method+path) or message.
latency duration Transit latency (simulation timing).
bitrate any Bitrate in bit/s, e.g. 1Mbps or 1000000.
jitter duration Random jitter added to latency.
exception Busy { reason: string }

interface BrakeApi "Brake API" {
  messages BRAKE_CMD, BRAKE_STATUS
  readonly attribute applied: uint16
  fn apply(force: float32) -> bool raises Busy
  fn status(out force: float32)
  oneway fn reset()
}
component BrakeEcu {
  in can: can-fd provides BrakeApi
  fn apply(force: float32) -> bool ```arche
    return true
  ```
}

contract#

What a component (or an interface, or a port type) assumes of what it receives and guarantees of what it sends. A clause is a condition on a port's message fields or on a variable: cmd.force in 0..1000N, status.mode == 2, out.level <= 5V, conditions joined by and; always and eventually may open it, within 20ms [after cmd] may close it. At each link a.p -> b.q, what a guarantees on p must imply what b assumes on q: ranges and equalities on the same field, in the same unit (time units are converted, others are not), and deadlines (a guarantee within 20ms meets an assumption within 50ms). An unmet assumption is contract-unmet; one archec cannot decide is contract-unknown. On an interface or a port type, the clauses name the message (BRAKE_CMD.force) or the field, and hold on every port that takes part in it: guarantees where it sends, assumptions where it receives. Arche has no place for contracts: they stay in the model (and in archec sysml).

  • Keywords: contract
  • Set: the model
  • Where: inside component, inside system, inside interface, inside port-type
  • Syntax: contract { assume <cond> [and <cond>…]; guarantee [always|eventually] <cond> [within 20ms [after port]] } — cond: path in lo..hi | path ==|!=|<|<=|>|>= value | [not] path
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
assume any A condition this side relies on, to the end of the line: cmd.force in 0..1000N.
guarantee any A condition this side ensures, to the end of the line: status.applied within 20ms after cmd.
component BrakeEcu {
  in cmd: can-fd receives BRAKE_CMD
  out status: can-fd sends BRAKE_STATUS
  contract {
    assume cmd.force in 0..1000N
    guarantee status.applied within 20ms after cmd
  }
}

handler#

What an in port answers: an HTTP route (POST "/boot" -> boot) or a message (BRAKE_CMD -> apply).

  • Keywords: handler (old spelling: on)
  • Set: the model
  • Where: inside port
  • Syntax: handler METHOD "/path" -> fn | handler MESSAGE -> fn
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
body code Python body run for this message. A ``` block, or the name of a def in a code .py file.
handler POST "/api/v1/boot" -> boot
handler BRAKE_CMD -> apply_brake

A link between two ports (or components) in this scope. link is optional: a.p -> b.q works on its own line.

  • Keywords: link (old spelling: connect)
  • Set: the model
  • Where: inside component, inside system
  • Syntax: a.port -> b.port ["Name"] [{ latency 2ms }] — type and messages come from the ports; : porttypeandcarries M, … override them
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
color color name A palette color id, or a literal "#rrggbb".
carries list of message names Messages on the wire (ICD).
template ident Link template.
variants list of variant names The variants it belongs to (variant declarations); one that says nothing belongs to all.
prop prop A free key/value property of the component.
latency duration Transit latency (simulation timing).
bitrate any Bitrate in bit/s, e.g. 1Mbps or 1000000.
jitter duration Random jitter added to latency.
pattern fire-and-forget | request-reply | pub-sub | broadcast | service | dataflow Interaction pattern, on the sending side: fire-and-forget (default — the sender never waits), request-reply (a correlated reply, call/reply in Python), pub-sub (1 → N subscribers), broadcast (everyone on the medium), service (a call to whoever serves a service name, wherever it runs: no link), dataflow (a source streams vectors of samples to sinks, which run when enough have come: threshold).
buffer queue | sample | stream What the receiver keeps: queue (every message counts; simulated as link queue), sample (last value wins; simulated as a queue of 1 that drops the oldest), stream (a continuous flow).
depth number Length of a queue buffer (depth alone means buffer queue).
overflow drop-oldest | drop-newest | block When a queue is full: drop-oldest, drop-newest (default), or block (analysis only — the simulator drops the newest).
timeout duration How long a request-reply waits for its reply.
retries number How many times a request-reply is sent again after a timeout.
async bool A request-reply that does not block: the reply arrives at a handler.
deferred bool On a request-reply server: the reply is sent later, not when the handler returns.
deadline duration The latest a message may arrive after it was sent.
stale-after duration A sample older than this is stale.
reliability reliable | best-effort reliable (every message arrives, possibly late) or best-effort (may be lost).
topic string The topic name of a pub-sub port (DDS / ROS 2 / MQTT). Its parts in braces are filled when the message is published, each from the field of that name (topic "/track/{id}"), or of the type written ({sensor: uint8}). A port with a topic is matched by its topic: a subscriber is an in port of the same topic, not a link (topic-wired).
service string The name of the service a port calls (an out) or serves (an in): a call reaches whoever serves that name, wherever it runs — no link. Gives the port pattern service.
vector ident On a dataflow port: the type of one sample of the vectors it streams.
header ident On a dataflow port: the type of the header each vector carries (DataVector[header]).
threshold number On a dataflow sink: how many samples must have come for it to run (the execution threshold).
push-threshold number On a dataflow source: how many samples it gathers before it pushes them to its sinks.
backpressure-threshold number On a dataflow sink: how many samples waiting make it ask its source to slow down (with backpressure on).
history number On a dataflow sink: how many samples of the vector before it each run sees again (a filter's overlap).
max-processing number On a dataflow sink: the most samples one run takes (the maximum processing size).
backpressure on | off On a dataflow port: on when the sink may make its source wait (backpressure-threshold), off (the default) when samples past its capacity are lost. Both ends of a link say the same.
transfer copy | share On a dataflow port: how a vector reaches the sink — copy (the default: the sink gets its own) or share (the same buffer, not copied).
bus ident The bus it takes in the simulation (Arche timing.bus), when no deployment route says so: bus spi_tx0.
lidar.cloud -> fusion.lidar_in "Point cloud" { latency 2ms }
link chassis adcu.can0 -> brakes.can "Brake CAN" { carries BRAKE_CMD }

icd#

A message of the link's interface control document, as the link carries it: its fields (name: Type). Without one, the ICD lists the messages the link carries.

  • Keywords: icd
  • Set: functional analysis & scenarios
  • Where: inside link
  • Syntax: icd id "Name" { field: Type; … }
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
icd m1 "Pointing" { Azimuth: float64; Elevation: float64 }

canvas#

Where the blocks of a system (or a component definition) sit on the canvas, kept apart from its structure: one line per block, path at x, y [size w, h]. Dragging a block in the diagram writes here when the system has one. (Not to be confused with project { layout … }, the Arche app's left pane.) A block placed here takes no at of its own.

  • Keywords: canvas
  • Set: functional analysis & scenarios
  • Where: top level
  • Syntax: canvas System { part at x, y; part.child at x, y size w, h }
canvas Car {
  lidar at 40, 40
  adcu at 420, 200 size 260, 240
}