Référence › Spécification

Référence

La spécification d’arche-lang

Le cœur du langage, ce que l’édition 1.0 promet de garder, se trouve dans core.md : assez court pour se lire en une soirée. Une section marquée Extension ci-dessous n’est pas encore couverte par cette promesse ; archec check --core nomme ce qu’un modèle utilise de chacune (editions.md).

arche-lang décrit un système en texte simple : de quoi il est fait, ce que fait chaque part, ce qu’il doit faire et comment on le vérifie. Il se compile en un projet Arche. Ce document décrit le langage lui-même : ses éléments lexicaux, sa grammaire et le sens de chaque construction. La référence de chaque déclaration et de chaque propriété se trouve dans patterns.md. Pour bien écrire un modèle, lisez style.md. Pour un premier modèle pas à pas, suivez le tutoriel.

Comme Go, le langage est petit. Il offre une seule façon d’écrire chaque chose et une seule mise en page, que archec fmt écrit pour vous. Chaque exemple ci-dessous compile tel quel (les tests les compilent). Un bloc marqué fragment est un morceau de déclaration.

Notation#

La grammaire est écrite en EBNF :

Production = name "=" Expression "." .
Expression = Term { "|" Term } .
Term       = Factor { Factor } .
Factor     = name | "literal" | "(" Expression ")" | "[" Expression "]" | "{" Expression "}" .

[ … ] est optionnel, { … } signifie zéro ou plusieurs fois, | sépare les alternatives. newline est la fin d’une ligne.

Fichiers sources#

Un modèle tient dans un ou plusieurs fichiers UTF-8 qui se terminent par .arche. L’un d’eux est le fichier principal. Les autres y sont inclus, directement ou non. Un fichier contient des déclarations. Un fichier inclus dans le corps d’un system ou d’un component contient une partie de ce corps.

File        = [ PackageClause ] { Include | Declaration } .
PackageClause = "package" QualifiedName newline .
Include     = ( "include" | "requires" ) string newline .

Éléments lexicaux#

Élément Forme
Commentaire // to the end of the line, /* … */ ; /// … placé avant une déclaration en est la description
Identifiant lettres, chiffres, _ ; un - à l’intérieur (REQ-BRK-001, kria-parts) : une soustraction s’écrit donc avec des espaces autour de son -
Mot-clé contextuel : un mot n’est un mot-clé que là où une déclaration peut commencer, si bien que state, port ou type restent utilisables comme noms
Nombre 42, 3.14, 1e-3, 0xFF, 0b1010, 1_000_000
Grandeur un nombre et son unité, sans espace : 5ms, 100MHz, 3.3V, 2kg ; ns us µs ms s min h donnent une durée
Chaîne "…" avec \n \t \" \\ ; les autres barres obliques inverses sont conservées ("$\frac{a}{b}$") ; """…""" s’étend sur plusieurs lignes
Traduction après une chaîne, en "…" (ou de, fr…) sur la même ligne ou sur la suivante, plus indentée
Code ```ts … ```, ```python … ```, ```arche … ``` (ou latex, yaml) ; un ``` seul désigne le langage handlers du projet ; quelques propriétés acceptent une simple ligne de Python, et le do et le expect d’un cas de test une ligne du langage d’actions ou de Python (do send p.out M { a: 1 }, do send(p.out, M(a=1)))
Séparateur un saut de ligne termine une propriété ou une déclaration ; dans un bloc sur une ligne, ;
QualifiedName = identifier { "." identifier } .
Path          = identifier [ "[" Index "]" ] { "." identifier [ "[" Index "]" ] } .
Text          = string { language string } .

Un projet indique l’édition du langage dans laquelle il est écrit, comme go.mod nomme une version de Go : edition "1.0". Sans édition, il est lu comme il l’a toujours été. À partir de l’édition 0.12, une ancienne orthographe de mot-clé est une erreur, et non plus un avertissement ; à partir de 0.13, une deuxième façon d’écrire une même chose aussi ; 1.0 se lit comme 0.13 et ouvre la promesse de stabilité (editions.md). archec fmt --edition 1.0 --write écrit les orthographes standard et l’édition. Une édition plus récente que celles qu’archec connaît est une erreur : mettez archec à jour.

Un mot-clé de deux mots s’écrit avec un trait d’union, comme un groupe nominal : port-type, test-plan, use-case, system-function, failure-mode, operating-mode. Les orthographes soudées (porttype, testplan, usecase, statemachine) sont les anciennes. Et un mot n’a qu’un sens : quand l’ancienne orthographe d’une déclaration est le mot standard d’autre chose, l’avertissement indique quoi écrire et à quoi sert le mot : Write `state` (`mode` is for operating modes, `operating-mode`).

Mot Ce qu’il signifie Ce qu’il ne signifie plus : écrivez plutôt
process un processus du système d’exploitation dans un déploiement un workflow : workflow
contract un contrat hypothèse/garantie dans un composant une interface : interface
mode (un mode de fonctionnement s’écrit operating-mode) un état : state
model le système sur lequel tourne un plan de test ou une simulation un système : system
bus le bus lui-même : un composant avec kind bus, le over d’une route, le bus d’un lien un type de port : port-type
view la page qu’ouvre une entrée de menu ou une étape d’histoire un point de vue : viewpoint
goal l’objectif de sûreté ou de sécurité auquel répond un danger ou une menace une mission : mission
function une fonction système (system-function) qu’exécute une étape de chaîne une fonction d’un composant : fn
tests les cas que nomme un bloc verify un plan de test : test-plan
kind une catégorie du catalogue la sorte d’un pseudo-état : pseudo
source l’endroit où se trouve le code (un composant, une fonction) l’origine d’une exigence : origin

Déclarations#

Toutes les déclarations ont la même forme : un mot-clé, un nom, un libellé, ce que le mot-clé accepte dans l’en-tête, puis un corps de propriétés et de déclarations imbriquées.

Declaration = keyword [ identifier ] [ Text ] { Header } [ "as" identifier ] [ Body ] newline .
Body        = "{" { Property | Group | Declaration } "}" .
Property    = key [ Values ] newline .
Group       = groupname "{" Property { ";" Property } "}" .
Values      = Value { "," Value } .
component Pump "Water pump" {
  description "Moves water from the tank to the field."
  kind device
  in power: power
  out flow: can sends FLOW
}

message FLOW: float32 "Flow"

system Field {
  part pump: Pump
}
Diagramme : Field
Ce qu’archec dessine depuis ce code : Field
Essayer
  • Le nom permet au modèle de désigner l’élément. Sa casse dit ce qu’il est, comme en Go : PascalCase pour ce qui est défini (composants, systèmes, types), snake_case pour ce qui est à l’intérieur (parts, ports, fonctions, variables), SCREAMING_CASE pour les messages, les constantes et les littéraux. Les identifiants d’exigences et de tests s’écrivent comme dans leurs documents (REQ-BRK-001).
  • Le libellé est le nom que lisent les gens, avec ses traductions.
  • as id donne à l’élément son identifiant dans Arche quand ce n’est pas son nom (un import conserve ainsi les identifiants d’Arche : component flash_memory "FLASH" as c-1793752253957).
  • Une propriété est une clé et ses valeurs, sur une ligne. Une liste de valeurs continue à la ligne suivante après une ,. Les propriétés qui vont ensemble peuvent s’écrire en groupe, ce qui revient à les écrire une par une :
timing { latency 2ms; jitter 100us; bitrate 1Mbps }

Les groupes sont timing, delivery (la façon dont les messages sont livrés), compute (les cœurs, l’OS, la mémoire, la flash et la puce d’un processeur), physical (masse, puissance, coût), resources (ce qu’a une carte : peripherals, pinout, io-level — docs/boards.md) et errors (le modèle d’erreurs d’une part : errors { produces omission; from a }). Un port d’alimentation dit sa voltage (une valeur, ou une plage 1.71V..3.6V pour ce qu’il accepte) et son current (ce qu’un out fournit au plus, ce qu’un in consomme).

Les déclarations se répartissent en ensembles (patterns.md les liste) : le modèle, avec lequel s’écrit tout modèle, et des ensembles dédiés à un usage : le déploiement, l’analyse fonctionnelle et les scénarios, la sûreté, la sécurité et l’espace de conception, l’application Arche, l’outillage du projet.

L’outillage du projet regroupe ce qui étend archec : un generator (une cible de code), un importer (un fichier d’un autre outil lu en arche-lang : script ou command, extensions, reads) et un exporter (le modèle écrit dans un tel fichier : templates, script ou command, extension), chacun avec ses option typées. On les écrit en général dans un plugin (plugins, générateurs).

importer kv "Key-value files" { script "kv/import.ts"; extensions ".kv" }
exporter kv "Key-value files" { script "kv/export.ts"; extension ".kv" }

Types et valeurs#

Type      = [ "optional" ] [ "*" ] TypeName [ TypeArgs ] [ "[" [ Index ] "]" ] | string .
TypeName  = QualifiedName | "struct" Body .
TypeArgs  = "<" ( Type | number ) { "," ( Type | number ) } ">" .         // no space before "<"
Generic   = "struct" identifier "<" identifier [ ":" "int" ] { "," identifier [ ":" "int" ] } ">" Body .
Value     = number | quantity | Text | Code | "true" | "false" | "nil" | Path
          | "[" [ Values ] "]" | "{" [ Field { "," Field } ] "}" | Value ".." [ Value ] | Expression .

Les types scalaires sont bool, int8…int64, uint8…uint64, float32, float64, char, byte, string, bytes, duration, timestamp. any désigne n’importe lequel d’entre eux. T[4] est un tableau, optional T peut être absent, *T pointe vers un T, et "Vec<u8>" est un type d’un autre langage, conservé tel qu’il est écrit.

const MAX_SPEED = 36 unit m/s

type Speed = float32 unit m/s range 0..70

enum Mode { MANUAL, AUTO }

struct Sample {
  speed: Speed
  mode:  Mode
  stamp: optional uint64
}

union Command {
  stop
  go: Speed
}

Une unité s’écrit telle quelle (unit m/s²). archec vérifie que ce qu’on compare ou qu’on additionne relève d’une même grandeur. Un produit ou un quotient a la grandeur que donnent ses dimensions : V_BUS * I_MAX est une puissance, DIST / T_STOP une vitesse, 1 / 5ms une fréquence. Ainsi, const P = V_BUS * I_MAX { unit W } est valide, et { unit s } donne un unit-mismatch. Il en va de même pour l’expr d’un paramètre face à son unit. Une dimension sans nom usuel s’écrit en toutes lettres (length·time⁻³). Rien n’est converti : kWh et J sont tous deux des énergies, et c’est tout ce qu’archec vérifie.

Une struct peut prendre des types et des nombres : struct Ring<T, N: int>. Chaque utilisation avec ses arguments, Ring<Sample, 64>, est une struct à part entière, Ring_Sample_64, dont les champs ont T et N remplacés. C’est elle que voient Arche, les codecs et le code généré. La struct générique elle-même n’est pas émise.

struct Reading {
  value: float32
}

struct Ring<T, N: int> "Ring buffer" {
  items: T[N]
  head:  uint16
}

message HISTORY {
  last: Ring<Reading, 8>
}

Un type que fournit le code est native : on indique son nom dans chaque langage, ainsi que l’en-tête (C, C++) ou le paquet (Go) qui le déclare. Le code généré l’utilise tel quel. archec ne regarde pas à l’intérieur.

type Iq native "IQ sample" {
  cpp "dsp::Iq" include "dsp/iq.h"
  c "iq_t" include "dsp/iq.h"
  rust "dsp::Iq"
  go "dsp.Iq" import "example.com/dsp"
}

Un type natif qui ne donne son nom dans aucun langage est un native-type.

Formats de trame#

Extension — hors de la promesse de stabilité 1.0 (codegen ; le cœur)

Les octets d’un message sont ses champs dans l’ordre, en little-endian, alignés sur l’octet, sauf s’il précise son format de trame, bit par bit, comme le fait un DBC CAN ou l’ACN d’ASN.1. Il suffit pour cela de l’un de byte-order et size sur le message, ou de at, bits, scale, offset, signed, checksum, counter sur un champ :

enum Gear { P, R, N, D }

message WHEEL_SPEED {
  byte-order big
  size 8
  speed: float32 unit km/h range 0..600 bits 16 scale 0.01
  gear:  Gear
  temp:  float32 range -40..215 bits 8 offset -40
  alive: uint8 bits 4 range 0..15 counter
  crc:   uint8 at 56 checksum crc8
}
  • Un champ commence au bit at de la trame, ou juste après le champ précédent. Il occupe bits bits : 1 pour un bool, le minimum qui contient ses littéraux pour un enum, la taille de son type pour un nombre.
  • Le bit k de la trame se trouve dans l’octet k / 8. En little-endian (byte-order little, le défaut, Intel) : at est le bit de poids faible du champ, et le bit k est le bit k % 8 de son octet. En big-endian (big, Motorola) : at est son bit de poids fort, le bit k est le bit 7 - k % 8, et le champ s’étend vers la fin de la trame. Un champ peut indiquer son propre byte-order.
  • Avec scale ou offset, un nombre circule sous forme d’entier : brut = round((valeur - offset) / scale), saturé à ce que contiennent ses bits ; valeur = brut × scale + offset. Un flottant sans ces propriétés circule sous forme de ses bits IEEE, 32 ou 64.
  • La valeur brute est signée quand le type du champ l’est, ou avec signed.
  • checksum crc8 (SAE J1850) ou checksum xor8 : un octet calculé sur les autres octets de la trame. Une trame dont la somme de contrôle est fausse n’est pas décodée. counter : un compteur cyclique, que le câblage C généré incrémente à chaque envoi.
  • La trame fait size octets, ou autant qu’en atteignent les champs. Les bits qu’aucun champ n’occupe valent zéro.

archec vérifie que deux champs ne partagent aucun bit (wire-overlap), que chacun tient dans la trame (wire-size), que la range d’un champ correspond à ce que ses bits transportent une fois mis à l’échelle (wire-range), et qu’un message qu’une route place sur un bus CAN tient dans sa trame, 8 octets ou 64 en CAN FD (wire-frame). Le DBC, l’ARXML, l’ICD, Renode et archec replay lisent les champs sur leurs bits, et archec gen --target wire écrit leurs codecs en C, en Rust (no_std), en Go et en Python. --target c, embassy et go envoient et reçoivent avec ce même code.

Noms, paquets et chemins#

Extension — hors de la promesse de stabilité 1.0 (catalogs, pour un package ; les noms et les chemins sont du cœur ; le cœur)

Toute déclaration qui porte un nom est connue partout sous ce nom : les noms sont globaux, comme les identifiants d’Arche. Un paquet regroupe des déclarations sous un nom. Écrit en tête d’un fichier, package chassis place le fichier dans ce paquet, et chassis.BRAKE_CMD désigne explicitement l’une de ses déclarations.

package chassis

message BRAKE_CMD: float32 "Brake"

Un élément situé dans un autre se désigne par son chemin : Car.ecu.can0 est le port can0 de la part ecu du système Car. Dans un composant, un chemin part de ce composant (ecu.can0). Une part qui montre le composant d’un autre modèle (ref tile.tile) est parcourue : ce qui se trouve dans ce composant se trouve dans la part.

Structure#

Un system est un modèle d’Arche : les parts qui le composent et la façon dont elles sont reliées. Un component est une définition dont ses parts sont des copies. Un composant écrit dans un autre en est une part.

Port = ( "in" | "out" | "inout" ) identifier [ ":" Type ] [ Text ] [ ( "sends" | "receives" ) Values ] [ Body ] .
Link = [ "link" [ identifier ] ] Path "->" Path [ Text ] [ ":" Type ] [ "as" identifier ] [ Body ] .
message GO: bool "Go"

component Panel "Panel" {
  out button: can sends GO
}

component Motor "Motor" {
  in cmd: can receives GO
}

system Station {
  part panel: Panel
  part motor: Motor
  panel.button -> motor.cmd
}
Diagramme : Station
Ce qu’archec dessine depuis ce code : Station
Essayer

Le type d’un lien et les messages qu’il transporte viennent de ses ports. L’éditeur les affiche, et : type et carries les indiquent sur le lien.

Code#

Extension — hors de la promesse de stabilité 1.0 (exchange ; le cœur)

Une part indique à quels fichiers du code elle correspond avec source, sur son composant : un fichier, un dossier ou un motif glob (* dans un dossier, ** à travers les dossiers, {a,b}), à partir du dossier du fichier principal. Un fichier appartient à la part dont la source le désigne au plus près : un fichier nommé explicitement passe avant un glob, un dossier plus long avant un plus court. La source d’une fonction est celle de son composant.

port-type call "Call" {
  handling message
}

component Planner "Planner" {
  source "src/planner/**"
  in api: call
}

component Shell "Command line" {
  source "src/cli.ts"
  source "src/cli/*.ts"
  out uses: call
}

system App {
  part shell:   Shell
  part planner: Planner
  shell.uses -> planner.api
}
Diagramme : App
Ce qu’archec dessine depuis ce code : App
Essayer

archec recover écrit un tel modèle à partir du code. archec conform vérifie que chaque import entre deux parts correspond à l’un des liens du modèle, et signale les liens qu’aucun import ne justifie. Deux props leur en disent plus. prop weak_links sur un système ou un composant liste des paires de ses parts (["a -> b: 1 import"]) dont les imports sont autorisés sans qu’un lien soit tracé. prop recovered sur un système indique qu’archec recover l’a écrit, si bien qu’archec diagram ne trace que ses liens les plus lourds (le poids d’un lien est le nombre que donne son libellé : "12 imports").

Services, flux de données et topics#

Extension — hors de la promesse de stabilité 1.0 (communication ; le cœur)

La façon dont deux parts communiquent se décrit sur leurs ports (et leurs liens) : pattern, buffer, timeout… (déploiement). Trois autres moyens décrivent comment les composants se rencontrent.

Un service est appelé par son nom, où qu’il s’exécute : service "name" sur un port out l’appelle, sur un port in le fournit. Aucun lien n’est tracé. Un nom qu’aucun port in ne fournit donne un no-service.

message JOB {
  id: uint32
}

component Planner "Planner" {
  out compute: data sends JOB { service "compute" }
}

component Worker "Worker" {
  in compute: data receives JOB { service "compute" }
}
Diagramme : Planner
Ce qu’archec dessine depuis ce code : Planner

Le flux de données (dataflow), c’est le traitement du signal : une source émet en continu des vecteurs d’échantillons, et un puits s’exécute quand il en a reçu assez. Ses propriétés vont dans un groupe dataflow (ou une par une, ce qui revient au même) et donnent au port pattern dataflow.

Propriété Côté Ce qu’elle indique
vector T les deux le type d’un échantillon
header H les deux l’en-tête que porte chaque vecteur
push-threshold n source les échantillons rassemblés avant d’être poussés
transfer copy | share les deux le puits reçoit une copie (par défaut), ou le même tampon
threshold n puits les échantillons qui doivent être arrivés pour qu’il s’exécute
history n puits les échantillons du vecteur précédent que chaque exécution revoit
max-processing n puits le nombre maximal d’échantillons que prend une exécution
backpressure on | off les deux le puits peut faire attendre sa source (off par défaut)
backpressure-threshold n puits les échantillons en attente à partir desquels il le demande
struct FrameHeader {
  seq: uint32
}

component Adc "ADC" {
  out iq: data {
    dataflow { vector float32; header FrameHeader; push-threshold 256 }
  }
}

component Fft "FFT" {
  in iq: data {
    dataflow { vector float32; header FrameHeader; threshold 1024; history 64 }
  }
}

system Receiver {
  part adc: Adc
  part fft: Fft
  adc.iq -> fft.iq
}
Diagramme : Receiver
Ce qu’archec dessine depuis ce code : Receiver
Essayer

Un puits relié à un port qui n’est pas une source, ou à une source d’un autre vector, donne un dataflow-source. Deux extrémités qui n’indiquent pas le même backpressure donnent un dataflow-backpressure. Une propriété de flux de données sur un autre pattern, ou du mauvais côté, donne un comm-property ou un wrong-side.

Un topic nomme ce qu’un port pub-sub publie ou ce à quoi il s’abonne. Ses parties entre accolades sont remplies quand un message est publié, chacune à partir du champ du message qui porte ce nom, ou du type écrit ({sensor: uint8}). Un port qui a un topic est associé par ce topic : un port in du même topic s’y abonne. Le relier en plus donne donc un topic-wired. Une partie qui ne nomme rien de ce que contient le message donne un topic-part. archec sim livre ce qu’un tel port envoie à chaque port in dont le topic lui correspond (* pour un niveau, ** pour un nombre quelconque de niveaux, une partie entre accolades pour n’importe quelle valeur). Une métrique atteint de la même façon les filtres qui correspondent à /<part path>/<metric>.

message TRACK {
  id:    uint32
  range: float32
}

component Radar "Radar" {
  out tracks: data sends TRACK { pattern pub-sub; topic "/tracks/{id}" }
}

component Display "Display" {
  in tracks: data receives TRACK { pattern pub-sub; topic "/tracks/{id}" }
}
Diagramme : Radar
Ce qu’archec dessine depuis ce code : Radar

Le modèle des générateurs donne à chaque port et à chaque lien son pattern (un port qui requiert ou fournit une interface avec des opérations est client-server), son topic et ses topicParts, son service, et dataflow avec les propriétés des deux extrémités.

Comportement#

Le corps d’une fonction est du code, tel qu’Arche l’exécute : TypeScript, Python ou le langage d’actions. Le projet indique lequel (handlers typescript | python | arche). Un composant peut indiquer le sien, et un bloc aussi : ```ts (voir handlers.md). Ce code s’écrit dans le modèle ou dans un fichier .ts ou .py à côté (archec fmt --extract-code). Une variable a un type et une valeur. Une machine à états a des états et des transitions :

Transition = ( Path | "*" ) "->" Path [ "as" identifier ] [ "on" ( identifier | string ) ] [ Guard ] [ "/" Action ] .
Guard      = "[" text "]" | "when" string .
message GO: bool

component Valve "Valve" {
  in cmd:   can receives GO
  var open: bool = false

  fn toggle "Toggle" ```python
    self.open = not self.open
  ```

  states {
    state Closed
    state Open
    Closed -> Open on GO [self.open]
    Open -> Closed on GO
  }
}

system Plant {
  part valve: Valve
}
Diagramme : Plant
Ce qu’archec dessine depuis ce code : Plant
Essayer

Une garde s’écrit entre crochets. when "…" sert pour une garde qui est une phrase que des crochets ne pourraient pas contenir (une apostrophe, un accent). * -> Fault quitte n’importe quel état.

Un corps Python est traduit dans le langage d’actions quand il ne dit que ce que le langage d’actions sait dire (src/pyaction.ts). Les générateurs et le simulateur du navigateur utilisent alors la traduction. Cela couvre self.x = …, if/elif/while, for i in range(a, b, step), for x in buf, for i, x in enumerate(buf), une liste de taille fixe ([0.0] * 8, [1, 2, 3], [i * 0.5 for i in range(4)], xs: list[float] = …), buf[i], len, sum/min/max/any/all d’une liste ou d’un générateur (une boucle avant l’instruction), a // b et a % b (floor_div, floor_mod), x ** y, a if c else b, x in (1, 2), a < b < c, a, b = b, a + b, math.pi/sin/cos/atan2/sqrt/radians, les docstrings, et les lignes qui continuent entre parenthèses ou crochets. Une traduction n’est utilisée que si elle passe la vérification des types. Là où elle calculerait autre chose que Python, elle est refusée : / entre deux entiers (celui de Python donne un float), ** entre deux entiers. Tout le reste n’a pas de traduction, et la raison nomme la construction : "sorted(): it makes a new list", "a slice", "raise: an exception", "np.mean(): numpy is not translated".

Le Python que le langage d’actions ne sait pas dire (un dict, une liste qui grandit, un entier au-delà de 64 bits, numpy) ne tourne qu’en simulation : archec sim l’exécute en Python (sim.md). Un composant (ou une fonction) qui contient un tel code dit simulation-only ; archec gen --target c|cpp|embassy|go refuse un déploiement qui le place sur un microcontrôleur (simulation-only). pip "numpy>=1.26" indique les paquets qu’importe son Python. Un def sans self dans un fichier code se lie à la fn qui a les mêmes paramètres (def gcd(a, b) ↔ fn gcd(a: int64, b: int64)).

Actions#

Un corps peut aussi s’écrire dans le langage d’actions, dans un bloc marqué arche au lieu de python. archec le vérifie (les noms qu’il utilise, leurs types, les ports sur lesquels il envoie et ce qu’ils transportent, les états vers lesquels il va) et le traduit : vers le Python qu’exécute le simulateur d’Arche, vers du Rust avec archec gen --target embassy (sans laisser de TODO dans app.rs), vers du C. Python reste utilisé pour les modèles de l’environnement et le code de test.

Body      = { Statement newline } .
Statement = "var" identifier [ ":" Type [ "[" [ Size ] "]" ] ] [ "=" Expr ]   // var buf: int32[64], var t: int32[] = [1, 2]
          | "var" "(" identifier { "," identifier } ")" "=" Expr              // var (q, r) = divmod(7, 2)
          | Target ( "=" | "+=" | "-=" | "*=" | "/=" ) Expr
          | "(" Target { "," Target } ")" "=" Expr                           // (a, b) = (b, a)
          | "if" Expr Block { "else" "if" Expr Block } [ "else" Block ]
          | "while" Expr Block
          | "for" identifier "in" Expr ".." Expr [ "step" Expr ] Block       // for i in n..0 step -1
          | "for" identifier "in" Expr Block                                 // for x in arr
          | "send" identifier Expr          // a port, and a message: BRAKE_CMD { force: 1.0 }
          | "goto" identifier | "kick" identifier | "wait" Expr | "return" [ Expr ]
          | "log" Expr { "," Expr } | "break" | "continue" | Call .
Call      = identifier "(" [ Expr { "," Expr } ] ")"            // a function of the part, a builtin
          | identifier "." identifier "(" [ Expr { "," Expr } ] ")" .  // port.op(…): over the port's link
Expr      = or and not, == != < <= > >=, | ^ & << >> (on integers), + - * / %, unary - and ~, x.f, a[i],
            f(…), port.op(…), MSG { f: e }, { f: e } where a record is expected, 10ms, 0x1F, 0b101,
            "text", true, false; [e, …] where an array is declared, (e, e, …) where several values go;
            "if" Expr "{" Expr "}" "else" ( "{" Expr "}" | "if" … ), a value chosen.

Les noms que voit un corps sont ses variables locales, les paramètres de la fonction, les variables et fonctions de la part, les constantes et les valeurs d’enum (Mode.On). state == Ready teste l’état de la part. Fonctions intégrées : now() (en ns), abs min max clamp sqrt, sin cos atan2 (en rad), pow(x, y) (des floats), int et float pour convertir, to_s et to_ms, floor_div et floor_mod. Les durées s’écrivent 10ms, 50us, 2s. Un entier sur 64 bits contient un temps en ns et se combine avec elles. Un entier divisé par un entier donne un entier, comme en Rust et en C : / arrondit vers 0 et % a le signe du côté gauche (-7 / 2 vaut -3, -7 % 2 vaut -1). floor_div(a, b) et floor_mod(a, b) sont le // et le % de Python : le quotient arrondi vers le bas, le reste du signe du diviseur (floor_div(-7, 2) vaut -4, floor_mod(-7, 2) vaut 1). Ils prennent des entiers. Un seul endroit diffère : dans les handlers Python d’Arche, % est celui de Python, donc un côté négatif y donne le résultat de floor_mod ; archec sim, C, C++, Rust, Go et TypeScript donnent le signe du côté gauche. Écrivez floor_mod là où un côté peut être négatif et où c’est le résultat de Python que vous voulez.

if c { a } else { b } est une valeur autant qu’une instruction : var s = if x > 0 { 1 } else { -1 }. Il a un else, et seul le côté choisi est calculé. Son type est celui des deux côtés (1 à côté de 2.5 donne un float). C’est le a if c else b de Python, le c ? a : b du C, le if de Rust ; Go reçoit une fonction littérale.

Les opérateurs de bits & | ^ << >> prennent des entiers et ont la même priorité qu’en Python : sous + et -, au-dessus des comparaisons (crc & 0x80 != 0 est (crc & 0x80) != 0). Leur résultat garde la largeur de son type dans toutes les cibles : (crc << 1) d’un uint16 perd le bit qui en sort, en Python et en JavaScript aussi. ~x inverse chaque bit d’un entier, dans la largeur de son type (~0xA5 d’un uint8 vaut 0x5A).

component Crc16 {
  var crc:  uint16 = 0xFFFF
  var last: uint8[4]
  var n:    int32 = 0
  fn add(b: uint8) ```arche
    last[n % len(last)] = b
    n += 1
    crc = crc ^ (int(b) << 8)
    for k in 0..8 {
      if crc & 0x8000 != 0 {
        crc = (crc << 1) ^ 0x1021
      } else {
        crc = crc << 1
      }
    }
  ```
}
Diagramme : Crc16
Ce qu’archec dessine depuis ce code : Crc16
const REACTION_TIME = 150ms
const MU_DRY = 0.7

message BRAKE_CMD { force: float32; emergency: bool }

component Planner "Planner" {
  out can_brake:  can sends BRAKE_CMD
  var speed:      float32 = 0
  var obstacle_m: float32 = 100

  fn plan "Trajectory planning" ```arche
    var d = speed * to_s(REACTION_TIME) + speed * speed / (2 * MU_DRY * 9.81)
    if obstacle_m < d * 1.2 {
      send can_brake BRAKE_CMD { force: 8000.0, emergency: true }
    }
  ```
}

system Car {
  part planner: Planner
}
Diagramme : Car
Ce qu’archec dessine depuis ce code : Car
Essayer

Tableaux#

Un tableau est une variable de la part (var buf: float32[8], ou = [1, 2, 3, 4, 5, 6, 7, 8]), une variable locale d’un corps, ou un paramètre de fonction. buf[i] lit ou affecte un élément, len(buf) donne leur nombre. Un indice est un entier ; un indice littéral hors du tableau est une erreur. Un tableau ne s’affecte pas et ne se copie pas en entier.

  • Un tableau local est sur la pile : var buf: int32[64] commence à zéro, var t: int32[4] = [1, 2, 3, 4] avec ses éléments (int32[] prend sa taille dans ceux-ci). Sa taille est un nombre entier ou une constante. Ses éléments sont des nombres ou des booléens.
  • Une fonction prend un tableau en paramètre : fn sort(a: int32[], n: int32) en prend un de n’importe quelle longueur, fn f(a: int32[8]) un de huit. L’appelant donne un tableau par son nom : une variable de la part, un tableau local, ou son propre paramètre tableau. La fonction travaille sur le tableau même de l’appelant : ce qu’elle affecte, l’appelant le voit. Les éléments sont du même type (sans conversion) ; un paramètre avec une taille prend un tableau de cette taille.
  • for x in arr donne chaque élément à tour de rôle (une copie : affecter x ne change pas le tableau ; arr[i] = …, si).
  • Un tableau ne passe pas par un port (port.op(a)) : seulement vers une fonction de la part. Une struct transporte des valeurs vers une autre part.
Cible fn sort(a: int32[]), sort(buf)
C int32_t a[], int32_t a_len (const quand la fonction ne fait que le lire), sort(self, self->buf, 8) ; a: int32[8] donne int32_t a[8]
C++ std::int32_t *a, std::int32_t a_len, this->buf.data(), …size()
Rust a: &mut [i32] (&[i32] quand il est seulement lu) ; une variable de la part est copiée à l’aller et au retour, une locale est &mut buf
Go a []int32, buf[:]
Python, TypeScript, archec sim la liste ou le tableau lui-même

Plusieurs résultats#

Une fonction donne plusieurs valeurs avec -> (T, U) et return (a, b). On les sépare dans de nouvelles variables locales, var (q, r) = divmod(7, 2) (_ n’en garde aucune), ou dans des variables, (q, r) = divmod(7, 2). (a, b) = (b, a) échange : toutes les valeurs de droite sont calculées d’abord, puis chaque cible est affectée. Plusieurs valeurs ne forment pas une expression : elles sont retournées ou séparées, rien d’autre. Une opération à travers un port donne une seule valeur. C reçoit une struct (arche_tuple_int32_int32_t, champs v0, v1), C++ un std::tuple, Rust un tuple, Go ses résultats multiples.

Compter#

for i in a..b compte à partir de a tant que i < b, de un en un. step dit de combien : for i in 0..n step 2 ; un pas négatif compte à rebours tant que i > b, comme le range(n, 0, -1) de Python est for i in n..0 step -1. Un pas qui est un nombre entier ou une constante (-STRIDE aussi) peut être négatif ; toute autre expression compte en montant, et doit être au-dessus de 0 (for j in i * i..n step i ; le simulateur s’arrête sur un pas qui ne l’est pas). Un pas de 0 est une erreur. Le corps ne change ni le compteur ni les bornes.

Un algorithme, tel que Python l’écrit, dans le langage d’actions :

component Sorter {
  var data: int32[6] = [5, 2, 9, 1, 7, 3]
  var at:   int32 = -1
  var q:    int32 = 0
  var r:    int32 = 0

  fn bubble_sort(a: int32[], n: int32) ```arche
    for i in 0..n {
      for j in 0..n - 1 - i {
        if a[j] > a[j + 1] {
          (a[j], a[j + 1]) = (a[j + 1], a[j])
        }
      }
    }
  ```

  fn divmod(a: int32, b: int32) -> (int32, int32) ```arche
    return (floor_div(a, b), floor_mod(a, b))
  ```

  fn run() ```arche
    bubble_sort(data, len(data))
    for i in len(data) - 1..-1 step -1 {
      if data[i] == 7 {
        at = i
      }
    }
    (q, r) = divmod(-7, 2)
  ```
}
Diagramme : Sorter
Ce qu’archec dessine depuis ce code : Sorter

Appeler une autre part#

port.op(…) appelle une fonction de la part située à l’autre bout du lien du port : une opération d’une interface que le port requires (avec ce qu’elle étend). archec vérifie l’appel par rapport à l’interface : le port, l’opération, le nombre d’arguments qu’elle prend, leurs types et ce qu’elle renvoie. Il vérifie aussi que l’autre bout du lien fournit l’interface (unprovided-interface) avec une fonction de ce nom (missing-operation).

interface BrakeApi "Brake API" {
  fn apply(force: float32) -> bool
  fn release()
}

component Controller "Controller" {
  out brake:   requires BrakeApi
  var applied: uint16 = 0

  fn step "Brake when asked" ```arche
    if brake.apply(2.5) {
      applied += 1
    } else {
      brake.release()
    }
  ```
}

component Brake "Brake" {
  in api:    provides BrakeApi
  var force: float32 = 0

  fn apply(f: float32) -> bool ```arche
    force = f
    return f > 1.0
  ```
  fn release() ```arche
    force = 0.0
  ```
}

system Car {
  part ctl: Controller
  part brk: Brake
  ctl.brake -> brk.api
}
Diagramme : Car
Ce qu’archec dessine depuis ce code : Car
Essayer

La fonction du fournisseur s’exécute chez le fournisseur, sur ses variables et son état, et son résultat revient. L’appelant l’attend. Voici comment chaque cible procède :

Cible brake.apply(2.5)
archec sim la fonction s’exécute aussitôt sur brk (comme un appel de fonction : sans délai ni file d’attente, même si brk est occupée)
Arche (Python, TypeScript) await component("brk").apply(2.5) : la part nommée est celle de l’autre bout du lien
C controller_call_brake_apply(self, 2.5f) : le câblage appelle brake_apply(&part_brk, …) selon la part qui demande, dans le thread de l’appelant ; sans déploiement, dans controller_ports.c, que vous écrivez
C++ this->call_brake_apply(2.5f), une std::function que définit main.cpp (non définie, elle lève une exception)
Rust (Embassy) _out.call_brake_apply(2.5).await : une requête sur un canal vers la tâche de brk, qui exécute la fonction et signale la réponse ; les deux parts doivent donc être sur deux threads (sur un seul, archec le signale et l’appel renvoie la valeur par défaut)
Go self.Call("brake", "apply", float32(2.5)).(bool) : main.go appelle parts.Brk.Apply, dans la goroutine de l’appelant

En C, en C++ et en Go, la fonction du fournisseur s’exécute dans le thread de l’appelant. Ce qui garantit la sûreté, c’est que les deux parts soient sur un même thread, ou que la fonction ne lise et n’écrive que ses propres variables. Une part qu’on atteint par un bus (un autre binaire) n’est pas appelée : archec le signale.

Opérations, comme en IDL#

Extension — hors de la promesse de stabilité 1.0 (components ; le cœur)

Une opération peut en dire plus, comme dans l’IDL de CORBA :

Operation = [ "oneway" ] "fn" identifier "(" [ Arg { "," Arg } ] ")" [ "->" Type ] [ "raises" Path { "," Path } ] .
Arg       = [ "in" | "out" | "inout" ] identifier ":" Type .
Attribute = [ "readonly" ] "attribute" identifier ":" Type .
Exception = "exception" identifier [ Text ] Body .          // a struct
exception NotFound "Not found" {
  id: uint32
}

struct Track {
  id:    uint32
  range: float32
}

interface Tracks "Tracks" {
  readonly attribute count: uint32
  attribute rate:           float32
  fn lookup(id: uint32, out t: Track, inout hint: uint8) -> bool raises NotFound
  oneway fn forget(id: uint32)
}

interface TracksAdmin extends Tracks {
  fn clear()
}
  • Un argument est in par défaut. L’opération écrit un argument out, et lit et écrit un argument inout : à l’appel port.op(…), ce qu’on y passe est une variable (ou un champ), pas une valeur.
  • Une opération oneway n’a pas de résultat, et l’appelant ne l’attend pas : ni -> T, ni argument out (oneway-result).
  • raises nomme des exception : des structs qu’une opération peut lever à la place de son résultat (raises-not-exception pour un autre type).
  • Un attribute est une valeur que détient le fournisseur, et qu’un client lit (et écrit, sauf si elle est readonly).
  • extends (dans l’en-tête ou dans le corps) ajoute les opérations, les attributs et les messages d’une autre interface.

archec sim traite un argument out comme un argument in : sa valeur ne revient pas. Le modèle des générateurs donne chaque opération avec la direction de ses arguments, oneway et raises, pour que le code généré les exprime.

Les périphériques d’un microcontrôleur#

Extension — hors de la promesse de stabilité 1.0 (hardware ; le cœur)

include "std/peripherals" déclare une interface par périphérique : DigitalOut, DigitalIn, Uart, I2cBus, SpiBus, Adc, Pwm, CanBus, Timer. Un port d’un type intégré fournit l’interface de son type (gpio les deux numériques, uart Uart, i2c I2cBus, spi SpiBus, analog Adc, pwm Pwm, can CanBus). Ainsi, inout bus: i2c { requires I2cBus } se relie au port i2c de n’importe quelle carte. Ce qui les pilote sur chaque carte : drivers.md.

Un corps dessiné en séquence#

Extension — hors de la promesse de stabilité 1.0 (scenarios ; le cœur)

Une étape de scénario avec expand dessine, après l’étape, ce que fait le corps

app -> ctl : step
ctl -> brk : apply          the condition, tested before the choice
brk --> ctl : apply         its reply (dashed)
alt [brake.apply(2.5)]
  (applied += 1 calls nothing: not drawn)
else
  ctl -> brk : release      no reply: release gives nothing
end

Une fonction propre appelée (f()) est une étape sur la ligne de vie de la part elle-même, suivie de ce que fait son corps à son tour. port.op(…) est une étape vers la part à l’autre bout du lien, suivie de ce que fait le corps du fournisseur, puis de la réponse (aucune pour une opération oneway ou sans résultat). send port M { … } est un message vers la part à laquelle le port est relié. if / else if / else donne un alt avec une branche par cas, un if seul un opt, while et for un loop, chacun étiqueté avec son propre texte. Un fragment dont aucune branche n’appelle rien est omis. expand 2 s’arrête deux appels plus bas, et une fonction rencontrée de nouveau en descendant est dessinée mais pas suivie. Un corps ne peut pas appeler la fonction d’un enfant : calls child.f est donc dessiné après les étapes du corps. Un corps Python ou TypeScript n’est pas lu : c’est le calls de sa fonction qui est dessiné. Une étape dessinée se trouve à la ligne de son appel : l’éditeur l’ouvre.

Équations physiques#

Extension — hors de la promesse de stabilité 1.0 (physics ; le cœur)

Un type de port avec un potential et un flow est physique : une broche (tension, courant), une bride (vitesse, force), un arbre, un port thermique, un tuyau. Une part qui a de tels ports décrit son comportement par des équations sans direction, avec der(x) n’importe où. Les variables d’un port s’écrivent port.name. Une var que nomme der est un état (sa valeur est la valeur de départ). Une var qui a une valeur et pas de der est un paramètre. Une var sans valeur est une inconnue. Les liens de la part réunissent les ports en nœuds, où les potentiels sont égaux et où la somme des flux entrant dans les parts est nulle.

PortVar  = ( "potential" | "flow" ) identifier [ "unit" unit ] .
Equation = "equation" Expr "=" Expr .     // + - * / ^, der(x), t, functions; no comparison
port-type pin "Electrical pin" {
  potential v unit V
  flow i unit A
}

component Cell(v: float64 = 1.5V) "Cell" {
  inout p: pin
  inout n: pin
  equation p.v - n.v = v
  equation p.i + n.i = 0
}

component Resistor(r: float64 = 100Ω) "Resistor" {
  inout p: pin
  inout n: pin
  var i:   float64 unit A
  equation p.v - n.v = r * i
  equation p.i = i
  equation p.i + n.i = 0
}

component Cap(c: float64 = 1mF) "Capacitor" {
  inout p: pin
  inout n: pin
  var v:   float64 = 0 unit V
  equation v = p.v - n.v
  equation c * der(v) = p.i
  equation p.i + n.i = 0
}

component Ground "Ground" {
  inout p: pin
  equation p.v = 0
}

system Rc {
  part cell: Cell
  part r:    Resistor
  part c:    Cap
  part gnd:  Ground
  cell.p -> r.p
  r.n -> c.p
  c.n -> cell.n
  cell.n -> gnd.p
}
Diagramme : Rc
Ce qu’archec dessine depuis ce code : Rc
Essayer

Une part a autant d’équations que d’inconnues : ses variables sans valeur, ses états, le potentiel de chacun de ses ports (leurs flux viennent des liens). archec vérifie que chaque réseau donne chaque inconnue une seule fois. archec physics le trie et le résout, archec fit trouve ses paramètres à partir de données mesurées, archec fmi en fait une FMU, et le simulateur d’Arche l’exécute comme les équations d’une part physics. Les parts standard se trouvent dans include "std/physics".

archec physics intègre par défaut à pas fixe avec RK4. Un réseau raide (une constante de temps rapide à côté d’une lente) demande --integrator implicit ou trapezoid (chaque pas est résolu par la méthode de Newton), et --tol 1e-6 laisse le pas s’adapter à l’erreur commise. archec physics … --linearize donne les matrices A, B, C et D du réseau en un point de fonctionnement, ses modes (constantes de temps, fréquences et amortissements) et, avec --lqr Q,R, un gain de retour d’état. --batch 100 --vary motor.r=0.8..1.2 l’exécute cent fois sur des threads de travail, en tirant chaque fois un paramètre dans sa plage, puis résume les exécutions (archec sim --batch fait de même pour le comportement).

Corps#

Extension — hors de la promesse de stabilité 1.0 (physics ; le cœur)

Une part peut décrire son corps, pour un moteur physique : sa shape, sa mass, et la joint par laquelle elle bouge dans la part qui la contient (le monde pour une part de premier niveau). Toutes deux vont dans le groupe physical.

Shape = "shape" ( "box" len "," len "," len | "sphere" len | ( "capsule" | "cylinder" ) len "," len ) [ "at" Vec ] [ "rot" Rot ] .
Joint = "joint" [ ( "hinge" | "slide" ) [ Axis ] | "ball" | "free" | "fixed" ] [ "at" Vec ] [ "rot" Rot ] [ "range" Value ".." Value ] [ "=" Value ] .
Axis  = "x" | "y" | "z" | "-x" | "-y" | "-z" | "[" Value "," Value "," Value "]" .
Vec   = len "," len "," len .
Rot   = angle "," angle "," angle | Axis angle .
component Link "Link" {
  physical {
    mass 1kg
    shape capsule 0.04m, 0.5m at 0, 0, -0.25m
  }
}

system Arm {
  part upper: Link {
    joint hinge y at 0, 0, 1.5m range -2..2 = 0.3
    part fore: Link {
      joint hinge y at 0, 0, -0.5m
    }
  }
}
Diagramme : Arm
Ce qu’archec dessine depuis ce code : Arm
Essayer

Les dimensions d’une boîte sont ses dimensions complètes. Celles d’une capsule ou d’un cylindre sont son rayon et sa longueur, selon z. at donne la position du centre de la forme dans le repère de la part, ou la position du repère de la part dans celui de son parent : c’est là que se trouve la liaison. rot fait tourner la forme dans le repère de la part, ou le repère de la part dans celui de son parent : roulis, tangage, lacet (rot 0, 0, 90deg, autour du x du parent, puis de y, puis de z : le rpy d’URDF) ou un axe et un angle (rot z 90deg, rot [1, 1, 0] 45deg). Un angle sans unité est en rad. L’axe de la liaison, la forme, l’emplacement des capteurs et des propulseurs et les parts intérieures sont exprimés dans le repère tourné (joint hinge y at 0, 0, 1m rot z 90deg pivote autour du -x du parent). La range et la position de départ d’une charnière sont en rad, celles d’une glissière en m. L’axe est z quand il n’est pas précisé. archec gen --target mujoco crée un corps pour chaque part qui a une masse ou une forme, imbriqués comme le sont les parts.

archec import robot.urdf et archec import scene.xml (MJCF) écrivent un robot de cette façon : une part par corps, avec sa mass, sa shape et sa joint. Ce que ces formats disent en plus devient des enregistrements prop (prop shoulder = {damping: 0.1, effort: 20}, prop inertial = {…}, les géométries supplémentaires en prop rod = {geom: capsule, size: [0.02, 0.25]} avec les dimensions de MuJoCo). Un actionneur est une part kind actuator dans le corps dont il entraîne la liaison, un capteur une part kind sensor dans le corps qu’il mesure. Leur nature vient de l’unité du message qu’ils reçoivent ou envoient. Le noise et le cutoff d’un capteur deviennent le noise de son port et la range de ses champs. La forcerange et le filtre d’un actionneur deviennent la force-range et le lag de son port. Chaque <key> (le premier donne aussi les positions de départ des liaisons) devient une keyframe du système.

Géométrie#

Extension — hors de la promesse de stabilité 1.0 (cad ; le cœur)

Un composant peut dire sa géométrie : un fichier Python qui définit part, un solide build123d, et en option anchors, les endroits nommés où se placent les autres parts. Ce dont il est fait suit le fichier dans un bloc, ou s’écrit à côté (les trois peuvent aller dans le groupe physical, avec la masse et la forme). Une part d’un système peut avoir sa propre géométrie, et une place : une ancre de la géométrie d’une autre part.

Cad       = "cad" string [ "{" { Material } "}" ] .
Material  = "material" identifier | "density" quantity .
Place     = "at" Path .
Clearance = "clearance" Path "," Path Compare quantity .
CadLimit  = "limit" Path Compare quantity { "," quantity } .
Compare   = "<=" | "<" | ">=" | ">" .
Pcb       = "pcb" string .
Outline   = "outline" quantity "," quantity .
Hole      = "hole" quantity "at" quantity "," quantity .
Fits      = "fits" Path "," Path [ ( "<=" | "<" ) quantity ] .
Sourced   = "sourced" identifier .
requirement REQ-BOX "Fits the bracket" {
  text "The enclosure shall be at most 120 mm × 95 mm × 40 mm, and weigh at most 80 g."
  limit Enclosure.size <= 120mm, 95mm, 40mm
  limit Enclosure.mass <= 80g
}

component Enclosure "Enclosure" {
  cad "cad/enclosure.py" { material PETG }
}

system Assembly {
  part box:   Enclosure
  part relay: GpioRelay { cad "cad/relay.py"; at box.relay }
  clearance box, relay >= 0mm
}

Le chemin d’une limite se termine par ce qui est mesuré : size (la boîte englobante, trois bornes selon x, y et z, ou une seule pour les trois), mass ou volume. Avant vient un composant avec un cad, ou une part d’un système. Un material est un nom de la table de cad.md, ou une constante dont la valeur est une densité. Une borne s’écrit avec son unité et est convertie (mm, cm, m ; g, kg ; mm³, cm³, L) : une borne dans une autre sorte d’unité est une erreur. Un limit sans comparaison est la borne d’une metric, comme avant, et at x, y est une place sur le canevas.

archec cad exécute chaque fichier, écrit du STEP, du STL et du GLB dans build/cad/, mesure la géométrie, place les parts et vérifie les limites et les jeux. Une limite ou un jeu écrit dans une exigence est enregistré comme preuve pour elle. Des parts qui se touchent sont à 0 mm l’une de l’autre ; des parts qui s’interpénètrent échouent à tous les jeux. Le budget de masse (budget mass 150g) compte la masse mesurée d’une part qui a une géométrie et un matériau. cad.md dit tout.

Une part dont la géométrie est construite est un corps pour la physique (archec gen --target mujoco, la vue 3D) : son maillage, et la masse, le centre de masse et l’inertie mesurés, remplacent un shape et un mass écrits. Une valeur écrite qui diffère de la valeur mesurée donne un avertissement qui indique les deux.

Un composant peut aussi dire ce qu’il est en tant que carte : pcb nomme un fichier de carte KiCad, dont on lit le contour (la couche Edge.Cuts) et les trous de fixation (les empreintes MountingHole) ; sans lui, outline donne la taille de la carte selon x et y, et chaque hole le diamètre d’un trou de fixation et son centre depuis le coin inférieur gauche du contour. fits board, box, dans un système ou une exigence, vérifie que chaque entretoise que le boîtier donne à la carte (mounts dans le fichier de sa géométrie) est sous un trou de la carte, à 0,2 mm près ou à la longueur écrite. sourced Assembly, dans une exigence, vérifie que chaque part achetée d’un système a un part-number. archec cad lance l’ERC et le DRC de KiCad sur une carte qui nomme son pcb quand kicad-cli est installé, et les enregistre pour les exigences que le composant satisfait.

requirement REQ-MOUNT "The board screws onto the tray" {
  text "The tray's standoffs shall be under the board's mounting holes."
  fits board, tray
}
requirement REQ-BUY "What is bought can be ordered" {
  text "Every bought part of the unit shall have a part number."
  sourced Unit
}

component Controller "Controller board" {
  pcb "hw/controller.kicad_pcb"
  cad "cad/board.py" { material FR4 }
}
component Shield "A bought board" {
  physical {
    outline 50mm, 40mm
    hole 3.2mm at 3.5mm, 3.5mm
    hole 3.2mm at 46.5mm, 36.5mm
  }
}
component Tray {
  cad "cad/tray.py" { material PETG }
}

system Unit {
  part tray:  Tray
  part board: Controller { at tray.board }
}

Composants FPGA#

Extension — hors de la promesse de stabilité 1.0 (fpga ; le cœur)

Un composant doté d’une horloge est un composant FPGA : du matériel, écrit comme n’importe quel autre composant.

type Adc12 = uint16 { bits 12 }
message WRAP "Wrapped" { turns: uint16 }

component Counter "Counter" {
  clock clk 100MHz
  reset rst_n active low async
  step tick
  in enable: bool
  in sample: Adc12
  out wrap:  data sends WRAP
  var count: uint8 = 0
  var turns: uint16 = 0
  fn tick ```arche
    if enable { count += 1 }
    if count == 0 {
      turns += 1
      send wrap WRAP { turns: turns }
    }
  ```
}
Diagramme : Counter
Ce qu’archec dessine depuis ce code : Counter
  • clock <name> <frequency> (clock clk 100MHz) en fait un composant FPGA. clock 10ms, une seule valeur, reste la période d’un composant qui n’est pas du matériel.
  • reset <name> prend active high (par défaut) ou active low, et sync (par défaut) ou async. Sans reset, c’est rst, actif à l’état haut, synchrone.
  • step <fn> nomme la fonction appelée à chaque cycle.
  • Un port dont le type est un type de donnée est un signal de cette largeur : bool, un type entier, une énumération, ou un type avec bits N. Dans un corps, c’est un nom : un signal in se lit, un signal out s’affecte. Un port qui sends ou receives est une poignée de main valid / ready avec les champs du message.
  • Une var est un registre. Un bloc memory avec une adresse est un registre du banc AXI4-Lite : rw et w sont écrits par le bus et lus par la logique, r est piloté par la logique.

À chaque front montant, dans l’ordre : fn main jusqu’à son prochain wait ; chaque message arrivé (sa transition, le on-receive du port, ses handlers) ; les transitions on "after …", comptées en cycles ; les transitions avec une garde et sans déclencheur, essayées à chaque cycle ; la fonction step. Les sorties sont registrées. Le simulateur exécute ainsi une part FPGA, cycle par cycle.

archec check signale dans un composant FPGA ce qui ne peut pas être synthétisé (fpga-synthesis, fpga-recursion) : flottants, chaînes, tableaux sans taille, boucles while et boucles for dont les bornes ne sont pas des constantes, récursion, appels à une autre part, corps Python et TypeScript, un wait hors de fn main. Une affectation qui perd des bits est un avertissement (fpga-width).

archec gen --target vhdl écrit chaque composant FPGA sous forme d’entité VHDL-2008, les données du modèle sous forme de package, les parts FPGA du système sous forme d’entité top, et un testbench GHDL par cas de test. archec test --target vhdl exécute les cas dans GHDL : chacun est une preuve au lieu ghdl, et laisse une trace que lisent archec why, why-not et timing.

archec synth synthétise les parts FPGA d’un système, puis les place et les route, pour le circuit que nomme sa part kind fpga (chip "iCE40UP5K-SG48", chip "LFE5U-25F-6BG381"). Une exigence borne ce qu’il mesure d’un composant FPGA ou d’un système qui a des parts FPGA : limit Pwm.luts <= 500, et de même pour ffs, bram et dsp ; limit Pwm.fmax >= 100MHz. Une limite sur autre chose, ou avec une borne qui n’est ni un nombre de cellules ni une fréquence, est une erreur (synth-limit). Un chip pour lequel archec ne sait pas synthétiser est un avertissement (synth-device). Ce qui est mesuré est une preuve au lieu synth <device>. fpga.md dit tout.

Capteurs et actionneurs#

Extension — hors de la promesse de stabilité 1.0 (physics, mais le noise et la resolution d’un capteur sont du cœur ; le cœur)

Un capteur lit ce qui est, mais pas exactement. Un actionneur fait ce qu’on lui demande, mais pas tout de suite. Une part kind sensor indique comment elle lit sur son port de sortie, une part kind actuator comment elle agit sur son port d’entrée : c’est le groupe response.

noise      σ of a gaussian noise on each float field of that quantity: 0.002rad, or 0.05m/s², 0.001rad/s
resolution the step a reading is rounded to: 0.0015rad
latency    how old the reading is (on an actuator's in port: its dead time)
gain       output = gain × command (1 when not said)
lag        a first-order lag from the command to the output: 20ms
force-range where the output saturates: -2..2
message ANGLE { angle: float64 unit rad range -3.2..3.2 }
message TORQUE { torque: float64 unit N·m range -1..1 }

component Encoder "Encoder" {
  kind sensor
  out angle: data sends ANGLE {
    noise 0.002rad
    resolution 0.0015rad
    latency 2ms
  }
}

component Motor "Motor" {
  kind actuator
  in cmd: data receives TORQUE {
    response { gain 2; lag 20ms; force-range -1.5..1.5 }
  }
}
Diagramme : Encoder
Ce qu’archec dessine depuis ce code : Encoder

Une lecture est la valeur plus son bruit, saturée par la range du champ (le cutoff de MuJoCo), puis arrondie à la résolution. Un bruit exprimé dans une autre unité de la grandeur du champ est converti (1deg sur un champ en rad). Un nombre sans unité s’applique à tous les champs flottants. Une commande est d’abord bornée par la range de son champ (le ctrlrange de MuJoCo) : c’est ce que voient les handlers de la part. La sortie la suit à travers le retard, multipliée par le gain, saturée par la force-range. La latency d’un port s’ajoute à celle de ses liens.

Le bruit est tiré à partir d’une graine (simulation { seed 7 }, --seed, 1 sinon), avec un même générateur partout : archec sim et sa page, le pont MuJoCo, le C d’un build de simulation (-DARCHE_SIM : le firmware de production n’ajoute aucun bruit ; les bornes et le retard sont toujours là). Ainsi, une exécution se répète, et archec difftest compare les deux côtés avec le bruit actif. Dans un réseau physique, le signal in d’un actionneur prend sa commande à <port>.command et agit à travers la plage de son type, son retard (un état du réseau : archec physics --linearize montre son mode), son gain et sa force-range. Le signal out d’un capteur est affiché tel qu’il le lit. archec avertit d’un bruit là où aucun capteur ne lit ou d’un gain là où aucun actionneur n’agit (realism-port), d’un bruit d’une grandeur qu’aucun champ n’a (unit-mismatch) et d’une plage à l’envers (range-reversed).

Keyframes#

Extension — hors de la promesse de stabilité 1.0 (scenarios ; le cœur)

Une keyframe dans un système est un état de départ nommé, comme celles de MuJoCo. Chaque ligne fixe une variable d’une part, la position de la liaison d’une part (part.joint, en rad ou en m) ou la commande avec laquelle démarre un actionneur (son port d’entrée).

Keyframe = "keyframe" identifier [ Text ] "{" { Path "=" Value } "}" .
message TORQUE { torque: float64 unit N·m range -1..1 }

component Link "Link" {
  physical { mass 1kg; shape capsule 0.04m, 0.5m at 0, 0, -0.25m }
}

component Motor "Motor" {
  kind actuator
  in cmd: data receives TORQUE
}

component Ctrl "Controller" {
  out cmd:    data sends TORQUE
  var target: float64 = 0
}

system Arm {
  part upper: Link {
    joint hinge y at 0, 0, 1.5m
    part motor: Motor
  }
  part ctrl: Ctrl
  ctrl.cmd -> upper.motor.cmd
  keyframe raised "Raised" {
    upper.joint = 1.2
    upper.motor.cmd = 0.3
    ctrl.target = 1.2
  }
}
Diagramme : Arm
Ce qu’archec dessine depuis ce code : Arm
Essayer

archec sim --keyframe raised et archec physics --keyframe raised partent de cet état (et --linearize --at raised y linéarise), archec gen --target mujoco l’écrit sous forme de <key>, et un cas de test avec keyframe raised part de ses variables. Une ligne qui ne désigne rien de modifiable est une erreur (keyframe-name).

La ligne d’une liaison dépend de sa sorte, comme les qpos et qvel de MuJoCo :

Liaison Où elle se trouve À quelle vitesse elle bouge
hinge, slide part.joint = 0.3 (rad, m) part.joint.vel = 1 (rad/s, m/s)
ball part.joint = [0, 0, 30deg] (roulis, tangage, lacet) ou [w, x, y, z] (un quaternion) part.joint.vel = [wx, wy, wz] (rad/s, dans son repère)
free part.joint.at = [x, y, z] et part.joint.rot = [r, p, y] (ou [w, x, y, z]), dans le monde part.joint.vel = [vx, vy, vz] (m/s, dans le monde), part.joint.spin = [wx, wy, wz] (rad/s, dans son repère)

Ce qu’une ligne ne fixe pas reste à la position de départ de la liaison : un corps libre là où ses parts le placent.

Un instant#

Ce qui se passe à un instant donné se passe dans un ordre défini par le modèle, et non par la machine, comme dans Lingua Franca. Le simulateur (archec sim) suit cet ordre, le C qu’écrit archec gen le suit au sein d’un thread, et archec difftest vérifie que les deux concordent.

  • Le temps est logique : un corps ne prend aucun temps, sauf s’il attend (wait 10ms).
  • Ce qui est dû au même instant s’exécute dans l’ordre où cela a été planifié : un message envoyé sur un lien sans latence passe après ce qui était déjà dû à cet instant.
  • Au démarrage : les watchdogs de chaque part sont armés et sa machine entre dans son état initial, les parts dans l’ordre où le système les déclare (les parts d’une part après elle). Ensuite, chaque fn main démarre. Puis viennent les threads périodiques, dans l’ordre où le déploiement les déclare, le premier appel une période plus tard.
  • Une part fait une seule chose à la fois, jusqu’au bout. Ce qui lui arrive pendant ce temps attend dans sa boîte aux lettres, dans l’ordre d’arrivée.
  • Un message vers une part déclenche d’abord la transition unique qu’il provoque : on part de l’état le plus intérieur où se trouve la part et on remonte, dans l’ordre d’écriture à chaque niveau, * -> en dernier (et non prise quand la part est déjà dans son état cible) ; c’est la première dont la garde est vraie. Viennent ensuite le on-receive du port, puis les handlers du port dans l’ordre d’écriture. Une garde et une action voient les champs du message par leur nom.
  • Une transition exécute le on-exit de chaque état qu’elle quitte, le plus intérieur d’abord, puis son action, puis le on-enter de chaque état où elle entre, le plus extérieur d’abord. Elle quitte et réintègre ce qui se trouve dans l’état le plus intérieur qui entoure à la fois sa source et sa cible (pour * -> et goto, la source est l’état où se trouve la part). Ainsi, Up -> Up quitte Up et ses états intérieurs, puis y entre de nouveau.
  • on "after 500ms" compte à partir de l’entrée dans l’état. Y entrer de nouveau relance le décompte. En sortir l’arrête.
  • Un message envoyé là où des liens se séparent les suit dans l’ordre où ils sont écrits.
  • Une variable garde ce que son type peut contenir : un uint8 à 255 plus 1 vaut 0, un entier divisé par un entier donne un entier, un float32 est arrondi en conséquence.
message BEAT { seq: uint16 }

component Monitor "Monitor" {
  in beat: can receives BEAT
  states {
    state Waiting
    state Up
    state Lost
    Waiting -> Up on BEAT
    Up -> Up on BEAT [seq > 0]
    Up -> Lost on "after 30ms"
    Lost -> Up on BEAT
  }
}

system Net {
  part monitor: Monitor
}
Diagramme : Net
Ce qu’archec dessine depuis ce code : Net
Essayer

Chaque battement dont le seq est supérieur à 0 fait entrer de nouveau dans Up : ses 30 ms repartent de zéro.

La vie d’une part#

Extension — hors de la promesse de stabilité 1.0 (components ; le cœur)

Une part peut indiquer ce qu’elle exécute quand elle est créée, démarrée, arrêtée et libérée, comme dans les frameworks à composants : on-init, on-start, on-stop et on-release, chacun étant un corps sur le composant.

component Filter "Filter" {
  var taps:    uint16 = 0
  var running: bool = false

  on-init ```arche
    taps = 64
  ```
  on-start ```arche
    running = true
  ```
  on-stop ```arche
    running = false
  ```
  on-release ```arche
    taps = 0
  ```
}

system Rx {
  part filter: Filter
}
Diagramme : Rx
Ce qu’archec dessine depuis ce code : Rx
Essayer

archec sim exécute le on-init de chaque part, puis le on-start de chaque part, à l’instant 0, dans l’ordre des parts, avant que les machines à états entrent dans leur premier état et que les fn main démarrent. À la fin de l’exécution (--for), il exécute le on-stop de chaque part, puis chaque on-release. Une définition construite sur une autre (extends) reprend ceux de sa base quand elle n’en indique pas. Le modèle des générateurs les donne comme lifecycle de chaque composant, avec leur C, C++, Rust et Go.

Échéances et watchdogs#

Extension — hors de la promesse de stabilité 1.0 (machines, et deployment pour un watchdog ; le cœur)

Un port ou une transition peut indiquer à partir de quand c’est trop tard. Une fois son deadline dépassé (la part commence à traiter le message plus longtemps que cela après son envoi, ou le timer plus longtemps que cela après son expiration), c’est son on-deadline qui s’exécute à la place (sur un port : à la place des transitions, du on-receive et des handlers ; sur une transition : une fois sa garde vraie, à la place de la transition). Un watchdog exécute son on-timeout quand aucun kick ne l’a relancé dans son timeout. Il est armé au démarrage. Une fois expiré, seul un kick le réarme.

message CMD { level: uint8 }

component Actuator "Actuator" {
  in cmd: can receives CMD {
    on-receive ```arche
      kick quiet
    ```
    deadline 5ms
    on-deadline ```arche
      late += 1
    ```
  }
  var late: uint16 = 0

  watchdog quiet "Commands stopped" {
    timeout 50ms
    on-timeout ```arche
      goto Safe
    ```
  }

  states {
    state Idle
    state Active
    state Safe
    Idle -> Active on CMD [level > 50]
    Active -> Idle on CMD [level < 20] {
      deadline 2ms
      on-deadline ```arche
        late += 1
      ```
    }
    Safe -> Idle on CMD [level == 0]
  }
}

system Plant {
  part act: Actuator
}
Diagramme : Plant
Ce qu’archec dessine depuis ce code : Plant
Essayer

Les deux sont simulés, et générés en C et en Rust (Embassy : ce qui arrive à une part qui a une échéance porte l’instant de son envoi, et la tâche de la part attend son prochain watchdog en même temps que ses entrées). Le simulateur d’Arche ne les prend pas encore en charge.

Algorithmes et flux de données#

Extension — hors de la promesse de stabilité 1.0 (communication ; le cœur)

Un algorithme de traitement du signal est un composant avec kind algorithm. Ses ports transportent les données. Son cycle est formé des fonctions qu’il possède parmi initialize, configure, execute_preprocessing, execute, execute_postprocessing et reset (archec sim exécute initialize et configure au démarrage). Ses paramètres d’instanciation sont les paramètres du composant. Une var avec parameter configuration est redéfinie à chaque configuration, une var avec parameter internal lui est propre. working-memory saved 1KiB et working-memory tmp 4KiB indiquent la mémoire dans laquelle il travaille. Le place d’un déploiement indique l’allocateur.

stereotype indique de quelle sorte d’algorithme il s’agit : splitter (une entrée, plusieurs sorties), joiner (plusieurs entrées, une sortie), cylinder, macro-algo, do-not-use-sw-caches, pipeline, local-memory-only. Sur une part, disable-thresholds et bypass-config-threading concernent l’instance.

Un algorithme qui a des parts est un composite : ses parts sont ses rôles, ses liens les connexions entre eux, et ses ports écrits = part.port ses délégations. Il est L1 quand ses parts sont de simples algorithmes, LN quand l’une d’elles est un composite. Le after d’une part l’exécute après une autre part, sans données entre elles.

Une métrique est un message avec kind metric. Un port de sortie qui l’envoie la publie sur /<part path>/<metric> (ou sur son topic). Un port d’entrée la lit, et son topic filtre ce qu’il prend : * pour un niveau, ** pour un nombre quelconque. (Le splitter et le joiner sont écrits en entier dans examples/signal-chain.)

message SNR { kind metric; value: float32 }

component Filter(taps: int32 = 16) {
  kind algorithm
  processing { stereotype pipeline; working-memory tmp 4KiB }
  var gain:   float32 = 1.0 { parameter configuration }
  in input:   data receives FRAME { handler FRAME -> execute }
  out output: data sends FRAME
  out snr:    data sends SNR { pattern pub-sub }
  fn configure ```arche
    gain = clamp(gain, 0.0, 4.0)
  ```
  fn execute(seq: uint32, level: float32) ```arche
    send output FRAME { seq: seq, level: level * gain }
    send snr SNR { value: level * gain }
  ```
}

component Chain {
  kind algorithm
  in input = split.input
  out output = join.output
  part split: Splitter
  part f1:    Filter(taps = 32)
  part f2:    Filter { after f1 }
  part join:  Joiner
  split.left -> f1.input
  split.right -> f2.input
  f1.output -> join.left
  f2.output -> join.right
}

Le linter signale un stéréotype du mauvais côté (celui d’une instance sur une définition), un splitter ou un joiner qui n’a pas les bons ports, une part d’un composite qui n’est pas un algorithme, des parts qui s’exécutent les unes après les autres en cercle, un filtre de métrique sur lequel rien n’est publié, et un lien de flux de données dont les deux extrémités ne décrivent pas la contre-pression de la même façon (backpressure on aux deux extrémités, voir Services, flux de données et topics).

Exigences et traces#

Une exigence est un énoncé, accompagné de ce qui la caractérise (priority, status, method…). Une trace relie deux éléments. Elle s’écrit là où elle part, sous forme de propriété (satisfies, verifies, derives, refines…), chaque valeur avec son identifiant si elle en a un :

TraceProperty = tracekey TraceValue { "," TraceValue } .
TraceValue    = Path [ "as" identifier ] .
TraceDecl     = "trace" tracekey Path "->" TraceValue { "," TraceValue } [ Text ] .
requirement REQ-1 "Start" {
  text "The pump shall start within 100 ms of a START command."
  priority high
}

component Pump "Pump" {
  satisfies REQ-1 as s-1
}

system Field {
  part pump: Pump
}
Diagramme : Field
Ce qu’archec dessine depuis ce code : Field
Essayer

Un lien vers une exigence s’écrit sur ce qui la satisfait (satisfies sur un composant, une part, un port ou une fonction) ou sur ce qui la vérifie (verifies sur un cas de test, un plan de test ou un scénario). Une ligne trace sert aux autres sortes (derives, refines, allocates, realizes, involves, deploys, traces), et à un lien qui porte un commentaire. Les anciennes formes sont lues jusqu’à 0.13 (requirement-link, un avertissement, une erreur avec edition "0.13") : satisfied-by et verified-by sur l’exigence, trace satisfies et trace verifies, et tests dans le bloc verify d’une exigence. La correction rapide et archec fmt en déplacent une quand les deux bouts sont dans le même fichier et que la construction reste la même ; archec refactor move-traces déplace les autres, en vérifiant la construction. À partir de 0.13, le bloc verify d’une exigence liste, pour l’ivv d’Arche, les tests qui disent la vérifier.

Extension — hors de la promesse de stabilité 1.0 (requirements, pour une phrase ears ; formal est du cœur ; le cœur)

Une exigence peut s’écrire en EARS, à propos des parts du modèle, et être prouvée :

ears   "[while <state>,] [when|if <trigger>,] <part> shall <response> [within <time>]"
         <trigger>  = <part> receives <MESSAGE> | <part> enters <State> | <state>
         <response> = be in <State> [or …] | not be in <State> | send <MESSAGE>
formal "never brakes in Fault" | "always …" | "eventually … [within <time>]"
       | "<a> leads to <b> [within <time>]" | "<a> implies <b>"

archec vérifie les parts, les états et les messages que nomme une phrase ears. Cette phrase sert de texte à l’exigence quand elle n’en a pas, et fournit sa propriété formal. archec verify prouve les propriétés formal avec NuSMV (sans le temps : un within est vérifié par les moniteurs, archec replay et archec verify --conflicts). archec gen --target ears-tests écrit un cas de test par exigence EARS. archec verify --conflicts trouve les exigences qu’aucune implémentation ne peut satisfaire ensemble (de façon bornée : le temps est compté en ticks). archec verify --meaning dessine sur une ligne de temps ce que dit chaque propriété.

Vérification#

Un plan de test contient des cas. Un cas est une ligne de temps faite de moments : at 10ms do …, at 10ms expect …, at 20ms fault … et within 100ms expect … (au plus tard 100 ms après le at qui le précède). Un nom après l’heure nomme l’étape dans les rapports : at 0ms "Engage" do …. Un at ne commence pas avant son heure ; il commence plus tard si une attente avant lui a pris du temps. Les lignes d’une même heure s’exécutent dans l’ordre où elles sont écrites. Les stimuli d’une simulation sont les mêmes lignes, avec at … do seulement. Les anciens blocs, le step "…" { do …; wait 10ms; expect … } d’un cas et le stimulus "…" { at 5ms; do … } d’une simulation, sont lus jusqu’à l’édition 0.13 (old-form). archec fmt les réécrit en lignes de temps, à l’identique, ou dit pourquoi il ne le peut pas.

Lignes de test#

Ce qu’un moment fait et attend s’écrit dans le langage d’actions, comme un corps, avec les parts du système pour noms :

at 0ms do send probe.water WATER { temperature: 20.0 }   a message sent from a part's port
at 0ms do ctl.target = 90.0                              a part's variable set
at 5ms do send hmi.bus ENGAGE_REQ(true)                  a message that carries one value
within 100ms expect ctl.state == Idle                    a part's state, by its name
at 1s expect sent(HEAT) >= 1 and not relay.closed        sent(MSG), received(MSG), received(part, MSG), now()
within 50ms expect never: sent(BRAKE_CMD) > 0            within …:, never:, always:, eventually: kept as before

Une part se nomme par son chemin (ctl, arm.ctrl), ou par son seul nom là où une seule part le porte ; puis l’une de ses variables (celle d’un appareil du store aussi : relay.closed), ses ports (dans send) ou son state. Les constantes et les enums du modèle, les fonctions intégrées du langage d’actions, et sent(MSG), received(MSG) (combien depuis le début du cas) sont les autres noms. Une ligne est vérifiée comme un corps : une part, une variable, un port, un message, un champ ou un état inconnu est une erreur (test-line) là où il est écrit, tout comme une instruction de corps (wait, goto) : les heures sont celles des moments.

Dans quel langage une ligne est lue : une ligne qui se lit dans le langage d’actions et passe la vérification est du langage d’actions ; une ligne avec une forme que seul le langage d’actions a (send p M { … }, true, un enregistrement, une durée, x.state == Idle, sent(MSG)) est du langage d’actions, et ses erreurs sont signalées ; tout le reste est du Python, comme avant (send(p, M(a=1)), True, elapsed()). Une ligne qui se lit de la même façon dans les deux (ctl.target = 90.0, not relay.closed, ctl.state == "Idle") veut dire la même chose dans les deux, et s’exécute telle qu’elle est écrite ; une ligne dont le sens différerait (une division de deux entiers) reste du Python. Un bloc ```arche dans un do ou un expect est du langage d’actions, un bloc ```python du Python. La règle est la même dans toutes les éditions.

Les simulateurs exécutent les lignes du langage d’actions traduites : en Python pour celui d’Arche, en TypeScript dans un projet handlers typescript, et le simulateur du navigateur, les tests C et Renode lisent la traduction Python comme ils lisent une ligne Python. archec test donne donc les mêmes verdicts. Une ligne Python relève de l’extension codegen (archec check --core) ; l’indication arche-test-line et archec fix écrivent les plus courantes dans le langage d’actions (send(p.out, M(a=1)) → send p.out M { a: 1 }, True → true, x.state == "S" → x.state == S, sent("M") → sent(M)), et laissent ce qu’ils ne savent pas dire.

Les cas qui ne diffèrent que par leurs valeurs s’écrivent une seule fois, avec un tableau (cases : une extension, testing) :

component Box {
  var speed: float32 = 0
}

system Rig {
  part box: Box
}

test-plan TP "Speeds" {
  cases "Speed {v}" {
    at 0ms do box.speed = {v}
    at 1ms expect box.speed == {v}
    rows {
      id   | v
      TC-1 | 10
      TC-2 | 30
    }
  }
}
Diagramme : Rig
Ce qu’archec dessine depuis ce code : Rig
Essayer

Sûreté#

Extension — hors de la promesse de stabilité 1.0 (safety ; le cœur)

Un danger est évalué (severity, exposure, controllability) et son ASIL en est déduit. Les modes de défaillance et les portes forment son arbre de fautes quand on l’écrit à la main. Une part peut aussi dire quelles erreurs elle produit et ce que deviennent celles qui l’atteignent (son modèle d’erreurs) : archec en déduit alors l’arbre.

ErrorType = "omission" | "commission" | "value" | "early" | "late" .
Produces  = "produces" ErrorType { "," ErrorType } .              // on an output
Contains  = "contains" ( ErrorType | "all" ) { "," ErrorType } .  // on an input
Turns     = "turns" ErrorType { "," ErrorType } "into" ErrorType .  // on an input
From      = ( "from" | "from-all" ) identifier { "," identifier } . // on an output: the inputs behind it
TopEvent  = "error" ErrorType { "," ErrorType } "on" Path .        // on a hazard
message SPEED: float32
message CMD:   float32

component Sensor {
  out speed: can sends SPEED {
    produces omission
  }
}

component Ctrl {
  in a: can receives SPEED {
    turns value into omission
  }
  in b:    can receives SPEED
  out cmd: can sends CMD {
    from-all a, b
  }
}

component Brake {
  in cmd: can receives CMD
}

system Car {
  part s1:     Sensor
  part s2:     Sensor
  part ctrl:   Ctrl
  part brakes: Brake
  s1.speed -> ctrl.a
  s2.speed -> ctrl.b
  ctrl.cmd -> brakes.cmd
}

failure-mode FM-S1 "Sensor 1 dead" {
  of Car.s1
  produces omission
  probability 1e-5
}

hazard HZ-01 "No braking on demand" {
  severity S3
  exposure E4
  controllability C3
  goal SG-01
  error omission on Car.brakes.cmd
}

safety-goal SG-01 "Brake on demand" {
  safe-state "Braking"
}
Diagramme : Car
Ce qu’archec dessine depuis ce code : Car
Essayer

Une erreur se propage le long des liens. À travers une part, elle va de chaque entrée vers chaque sortie (ou vers celles dont le from la nomme), sauf si l’entrée la contient. turns change son type. from-all exige l’erreur sur chaque entrée nommée (un ET). Les événements de base sont les modes de défaillance qui produce une erreur sur leur élément, avec leur probability, ou le produces de la part seul, sans taux. Un danger écrit des deux façons est vérifié : les deux arbres doivent avoir les mêmes coupes minimales.

Une analyse STPA prend l’architecture comme structure de contrôle : une control-action va from une part contrôleur to la part qu’elle contrôle, en passant par les liens. Elle contient ses actions de contrôle dangereuses, une ou plusieurs pour chacun des quatre types (not-provided, provided, timing, duration), ou le type déclaré not-applicable. Chaque uca nomme les dangers qu’elle causes et l’exigence (constraint) qui l’empêche, et contient ses loss-scenario.

Vues#

Extension — hors de la promesse de stabilité 1.0 (design ; le cœur)

Un viewpoint qui dit ce qu’il inclut est un diagramme à part entière : une requête sur un système, et non un dessin. Ses termes sont lus dans l’ordre, chaque exclude retirant ce qu’un include précédent a ajouté. Les blocs qu’il sélectionne, à n’importe quelle profondeur, sont dessinés avec les liens entre eux et placés automatiquement (archec diagram, l’éditeur).

Term     = "*" | Path [ ".*" | ".**" ] | ( "kind" | "tag" | "layer" ) identifier
         | Selector ( "->" | "<->" ) Selector .
Selector = "*" | Path [ ".*" | ".**" ] | ( "kind" | "tag" | "layer" ) identifier .
message GO: bool

component Sensor { out o: can sends GO }
component Ctl { in i: can receives GO; out o: can sends GO }
component Brake { in i: can receives GO }

system Car {
  part lidar:  Sensor
  part adcu:   Ctl
  part brakes: Brake
  lidar.o -> adcu.i
  adcu.o -> brakes.i
}

viewpoint braking "Braking" {
  of Car
  include * -> adcu, adcu -> *
  exclude lidar
}
Diagramme : Car
Ce qu’archec dessine depuis ce code : Car
Essayer

* désigne les parts de premier niveau du système, adcu.* les parts d’adcu, adcu.** tous les blocs qu’il contient. * -> adcu désigne adcu et les blocs qui lui envoient des messages, chacun pris au niveau d’adcu (un lien de cam.isp vers adcu amène cam). depth 2 va jusqu’à deux liens de distance. Un lien entre des blocs qui ne sont pas dessinés est tracé entre les blocs les plus proches de ses extrémités. Un terme qui ne correspond à rien donne un avertissement view-empty. Les noms que donne un terme sont des références : un renommage dans l’éditeur les renomme aussi.

La position des blocs d’un diagramme ne fait pas partie du modèle : l’éditeur garde les positions choisies à la souris dans une vue dans main.layout.json, à côté du fichier principal, par diagramme et par élément ("view:braking": { "Car.adcu": {"at": [420, 200]} }), et un renommage les renomme. Un bloc placé dans la source (at, une ligne canvas) garde cette position. Les autres sont placés automatiquement.

Interface utilisateur#

Extension — hors de la promesse de stabilité 1.0 (ui ; le cœur)

Un bloc ui, dans le composant (ou le système) qui possède un écran, décrit l’interface utilisateur du produit (le guide). À l’intérieur de ce bloc, et seulement là, les mots ci-dessous ouvrent des déclarations. Ailleurs, ce sont des noms comme les autres.

Ui        = "ui" "{" { UiProp | Screen | ElementDef } "}" .
Screen    = ( "screen" | "dialog" | "overlay" ) identifier [ string ] "{" { Prop | Item } "}" .
Item      = Layout | Element | Use | For | If | Fits .
Layout    = ( "row" | "column" | "grid" | "stack" ) [ identifier ] [ "{" { Prop | Item } "}" ] .
Element   = ElementWord [ identifier ] [ string ] [ "{" { Prop | Binding | Event } "}" ] .
ElementDef = "element" identifier "(" [ Param { "," Param } ] ")" "{" { Item } "}" .
Param     = identifier ":" [ "bind" ] Type .
Use       = identifier [ identifier ] "(" [ Arg { "," Arg } ] ")" [ "{" { Prop } "}" ] .
Arg       = [ identifier ":" ] ( string | Expression ) .
For       = "for" identifier "in" Expression "max" integer "{" { Item } "}" .
If        = "if" Expression "{" { Item } "}" { "else" "if" Expression "{" { Item } "}" } [ "else" "{" { Item } "}" ] .
Fits      = "fits" "{" { Layout } "}" .
Binding   = ( "value" | "enabled" | "visible" ) Expression .
Event     = "on" ( "press" | "release" | "long-press" | "change" | "enter" | "exit" ) ( Statements | "{" Statements "}" | CodeBlock )
          | "on" Expression .

ElementWord est l’un de spacer label gauge bar chart telltale image list table button toggle slider select input stepper custom. Un ElementDef s’écrit dans un ui ou en tête de fichier ; son Use, sans espace avant (, est développé en ce qu’il contient (archec ui montre le résultat), un paramètre bind prenant une variable de la part. if/else donnent un visible à ce qu’ils contiennent ; for dessine son unique élément au plus max fois ; fits garde la première disposition qui tient sur l’écran. L’Expression d’une liaison de données et les Statements d’un événement relèvent du langage d’actions (Actions) et sont lus jusqu’à la fin de la ligne (ou du bloc). Les noms qu’on peut y utiliser sont les variables de la part (speed), son state, le dernier message reçu sur un port (bus.STATUS.speed, ou bus.FAULT pour un message qui est une seule valeur), l’état et les variables d’une part voisine (ctrl.state, ctrl.speed) et les constantes. Un événement envoie (send port MSG(args), les arguments dans l’ordre des champs, ou MSG { field: value }), passe d’un écran à l’autre (goto Screen, back), modifie les variables propres de la part, prend des décisions (if), journalise et appelle les fonctions de la part. Un texte affiche des valeurs avec ${expression}.

message STATUS { speed: float32 unit km/h range 0..200 }
message STOP { hard: bool }

component Ctrl {
  in cmd: data receives STOP
  out st: data sends STATUS
  states {
    state Running
    state Stopped
    Running -> Stopped on STOP
  }
}

component Panel {
  in bus:  data receives STATUS
  out cmd: data sends STOP

  ui {
    display 800x480
    screen Main "Main" {
      gauge speed "Speed" { value bus.STATUS.speed }
      label state { text "Now: ${ctrl.state}" }
      button stop "Stop" { style danger; enabled ctrl.state == Running; on press send cmd STOP(true) }
    }
  }
}

system Machine {
  part ctrl:  Ctrl
  part panel: Panel
  ctrl.st -> panel.bus
  panel.cmd -> ctrl.cmd
}
Diagramme : Machine
Ce qu’archec dessine depuis ce code : Machine
Essayer

Le premier screen est celui où démarre l’interface (initial en désigne un autre). Un overlay se superpose à tous les écrans. Ce à quoi chaque élément est lié est vérifié par rapport à ce qu’il affiche, avec son unité et sa plage. Ce qu’envoie un appui doit atteindre une part qui le reçoit. Chaque écran doit être accessible et pouvoir être quitté. Un message lié à la sûreté doit être visible sur chaque écran. Le contenu doit tenir dans l’écran. Le contraste et les libellés suivent WCAG AA (les codes ui-*). archec ui affiche le modèle résolu, UiModel dans src/ui.ts.

Mise en page#

Il n’y a qu’une mise en page, et archec fmt l’écrit. Rien n’y est affaire de choix :

  • deux espaces par niveau ; l’accolade } d’un bloc sur sa propre ligne ;
  • une propriété ou une déclaration par ligne (; seulement dans un bloc écrit sur une ligne) ;
  • les propriétés dans un ordre fixe : ce qu’est l’élément (description, text), comment il est classé (kind, tags, status…), son type, le reste, ses traces (satisfies, verifies…), sa place sur le canevas (at, size) ;
  • trois propriétés ou plus d’un même groupe écrites sous forme de groupe ;
  • l’orthographe standard de chaque mot-clé (une ancienne orthographe donne un avertissement, et disparaît en 0.12).

archec vet signale ce que fmt ne peut pas corriger : des noms qui ne respectent pas leur casse, un long bloc Python dans un fichier de modèle, une déclaration hors de son ensemble.