Learn › Concepts

Learn

Concepts: the model before the syntax

arche-lang describes a system with five ideas. Each one is small. Learn these five, and the rest of the language is detail.

Each section below has a picture and a model that compiles. The test test/teach.test.js checks every one. To try a model, save it as room.arche and check it:

archec check room.arche
✓ no errors

The one-page syntax is in the cheat sheet. The full language is in the specification and the language reference.

1. Definition and instance: component and part#

A component is a definition: a kind of thing, written once. A part is an instance of it, placed in a system. Two parts of one component are two things, each with its own state and variables.

flowchart LR
  Lamp["component Lamp<br/>(the definition)"]
  subgraph Room["system Room"]
    desk["part desk: Lamp"]
    ceiling["part ceiling: Lamp"]
  end
  Lamp -. instance of .-> desk
  Lamp -. instance of .-> ceiling
component Lamp "Lamp" {
  var level: uint8 = 0
}

system Room "Room" {
  part desk:    Lamp
  part ceiling: Lamp
}
Diagram: Room
What archec draws from this code: Room
Try it

A system is what Arche (the graphical editor) shows on its canvas. It is also what the simulator runs. A system is a definition too, so a part can be a system. This is how a model nests.

A part talks to another part through its ports. A port has three things:

  • a direction: in, out or inout;
  • a type, which is the medium: can, ethernet, gpio…;
  • the messages it sends or receives.

A message is the data that travels. A link a.p -> b.q joins two ports of two parts. archec checks that the other end receives what one end sends.

flowchart LR
  button["button: Button"] -- "click → cmd<br/>PRESS { count }" --> lamp["lamp: Lamp"]
message PRESS "Press" { count: uint8 }

component Button "Button" {
  out click: can sends PRESS
}

component Lamp "Lamp" {
  in cmd: can receives PRESS
}

system Room "Room" {
  part button: Button
  part lamp:   Lamp
  button.click -> lamp.cmd
}
Diagram: Room
What archec draws from this code: Room
Try it

The ports belong to the component. The link belongs to the system. So the same Lamp can be wired one way in one system, and another way in another.

3. State machines and triggers#

A component can have one state machine. It starts in its first state. A transition A -> B on TRIGGER [guard] is taken when the trigger comes and the guard holds. A trigger is a message that arrives on a port, or a named event. A guard is a condition in brackets; it is optional.

A function's body can also change the state, with goto. It can test the state, with state == On.

stateDiagram-v2
  [*] --> Off
  Off --> On: PRESS
  On --> Off: PRESS
  On --> Off: main, after 10 s (goto Off)
message PRESS "Press" { count: uint8 }

component Button "Button" {
  out click: can sends PRESS
}

component Lamp "Lamp" {
  in cmd: can receives PRESS
  states {
    state Off
    state On
    Off -> On on PRESS
    On -> Off on PRESS
  }
  fn main "Night mode" ```arche
    wait 10s
    if state == On {
      goto Off
    }
  ```
}

system Room "Room" {
  part button: Button
  part lamp:   Lamp
  button.click -> lamp.cmd
}
Diagram: Room
What archec draws from this code: Room
Try it

The body is written in the action language, in a ```arche block. archec checks the names, types, states and ports the body uses. It translates the body to Python for the simulator, and to C, Rust and Go. The function main is special: it runs from the start, as the part's own thread.

4. Requirement, satisfies, verifies, test plan#

A requirement says what must hold. Two words link it to the rest, each written on the other end of the link:

  • a component satisfies it: that is where the requirement is met;
  • a case of a test plan verifies it: that test shows it holds.

(satisfied-by and verified-by, written on the requirement, are the old forms: read until 0.13, and archec fmt moves them.)

archec reports a requirement that nothing satisfies or nothing verifies.

flowchart LR
  req["requirement REQ-ON"]
  lamp["component Lamp"] -- satisfies --> req
  tp["test-plan TP-ON<br/>case TC-ON-01"] -- verifies --> req
message PRESS "Press" { count: uint8 }

requirement REQ-ON "Turn on" {
  text "The lamp shall turn on within 50 ms of a press."
}

component Button "Button" {
  out click: can sends PRESS
}

component Lamp "Lamp" {
  satisfies REQ-ON
  in cmd: can receives PRESS
  states {
    state Off
    state On
    Off -> On on PRESS
    On -> Off on PRESS
  }
}

system Room "Room" {
  part button: Button
  part lamp:   Lamp
  button.click -> lamp.cmd
}

test-plan TP-ON "Turning on" {
  case TC-ON-01 "A press turns it on" {
    verifies REQ-ON
    at 0ms do send(button.click, PRESS(count=1))
    within 50ms expect lamp.state == "On"
  }
}
Diagram: Room
What archec draws from this code: Room
Try it

archec test runs the case in the simulator. A test step is Python, as the simulator runs it. do acts, and expect checks. The command first writes the project the simulator runs (arche-out/), then runs the cases:

archec test room.arche
✓ 12 files → arche-out (room.yaml, models.yaml, templates.yaml, …)
  open with: arche --project …/arche-out
PASS  TP-ON/TC-ON-01 A press turns it on

1/1 passed, 0 failing, 0 known failure(s)

Requirements: 1 verified by passing cases, 0 failing

5. System, deployment, generated code#

The logical system says what the parts do. A second system, the platform, says what they run on: processors and buses. A deployment places each part of the first system on the second. It names a binary on a processor, and a thread in that binary that runs the part. Neither system changes.

The generators read the deployment and write the code, one program per binary.

flowchart LR
  logical["system Room<br/>(what it does)"] --> dep["deployment Board"]
  hw["system RoomHw<br/>(what it runs on)"] --> dep
  dep --> gen["archec gen --target c<br/>embassy · go · ros2 …"]
  gen --> code["lamp_fw: C, Rust, Go…"]
message PRESS "Press" { count: uint8 }

component Button "Button" {
  out click: can sends PRESS
}

component Lamp "Lamp" {
  in cmd:    can receives PRESS
  var level: uint8 = 0
  fn dim "Dim" {
    ```arche
    if level > 0 {
      level -= 1
    }
    ```
    wcet 50us
  }
}

system Room "Room" {
  part button: Button
  part lamp:   Lamp
  button.click -> lamp.cmd
}

component Mcu "Lamp MCU" {
  kind processor
  cores 1
  inout can0: can "CAN"
}

system RoomHw "Room hardware" {
  part mcu: Mcu
}

deployment Board "On the board" {
  system Room
  platform RoomHw
  binary lamp_fw "lamp.elf" on mcu {
    thread ctl "Control" { runs lamp; period 10ms; step dim }
  }
}
Diagram: Room
What archec draws from this code: Room
Try it
archec gen room.arche --target c -o generated

This writes generated/c/:

  • lamp.c, the part. Its dim is translated from the ```arche body: if (self->level > 0) { self->level -= 1; }.
  • arche_types.h and arche_types.c, the types of the messages.
  • lamp_fw/, the program of the binary: its main.c, the thread that calls dim every 10 ms, and a Makefile.

See code generation for every target.

Where next#