Apprendre › Tutoriel

Apprendre

Tutoriel : une pompe à eau, du modèle au firmware

Ce tutoriel construit pas à pas un petit système en arche-lang. Ce système est un contrôleur de pompe. Un pupitre opérateur le démarre et l’arrête, et il pilote un moteur.

En chemin, vous allez :

  • vérifier le modèle ;
  • relier une exigence à la part qui la satisfait et au test qui la vérifie ;
  • exécuter ce test dans le simulateur ;
  • placer le contrôleur sur un microcontrôleur ;
  • générer son firmware Rust ;
  • lancer toutes les vérifications en une seule commande de CI.

Créez un dossier vide. Chaque bloc arche ci-dessous s’ajoute, dans l’ordre, à un unique fichier de ce dossier, pump.arche. Le test du tutoriel compile exactement ces blocs : ils reflètent donc le langage tel qu’il est aujourd’hui. Lancez les commandes depuis ce dossier. Si archec n’est pas dans votre PATH, utilisez node <arche-lang>/dist/cli.js à la place.

Chaque déclaration et chaque propriété sont décrites dans la référence du langage. Les commandes sont décrites dans la référence des commandes.

1. Le projet, ses données et ses messages#

project Pump "Water pump" {
  version "0.1"
}

type Flow = float32 unit l/min range 0..120

message START: bool "Start"
message STOP:  bool "Stop"
message FLOW_RATE "Flow rate" { rate: Flow }

const MAX_FLOW = 100 unit l/min

Un message porte un nom en majuscules. Il transporte soit une seule valeur (ici, un booléen : bool), soit des champs. FLOW_RATE a un seul champ, rate, de type Flow. Flow est un nombre doté d’une unité et d’une plage.

Les unités s’écrivent telles quelles : l/min, m/s², °C. archec vérifie que deux valeurs que vous comparez ou additionnez relèvent bien de la même grandeur.

archec check pump.arche
pump.arche:1:1 hint No 'system' declared in pump.arche or its includes — nothing will appear on an Arche canvas [no-system]
pump.arche:7:9 hint message 'START' is never used [unused]
pump.arche:8:9 hint message 'STOP' is never used [unused]
pump.arche:9:9 hint message 'FLOW_RATE' is never used [unused]
✓ no errors

Ces indications ne sont que des conseils. Elles disparaissent à mesure que les étapes suivantes utilisent les messages et ajoutent un système.

2. Les composants et leurs ports#

component Controller "Pump controller" {
  satisfies REQ-START
  in cmd:    can "Commands" receives START, STOP
  out motor: can "Motor" sends FLOW_RATE

  var target: float32 = 0 unit l/min

  fn regulate "Flow loop" {
    wcet 200us
    ```arche
    if state == Running {
      send motor FLOW_RATE { rate: target }
    }
    ```
  }

Ce bloc ne ferme pas encore le composant : l’étape 3 y ajoute sa machine à états. satisfies REQ-START nomme l’exigence qu’il remplit : l’étape 4 l’écrit.

Un port indique trois choses :

  • sa direction : in ou out ;
  • son type : can est un type de port standard ;
  • les messages qu’il reçoit ou émet.

Le corps d’une fonction s’écrit dans le langage d’action, dans un bloc ```arche :

  • state == Running teste l’état de la part ;
  • send motor FLOW_RATE { … } émet un message sur un port ;
  • goto Fault changerait l’état.

archec vérifie le corps : les noms, leurs types, et ce qu’émet chaque port. Puis il traduit le corps en Python pour le simulateur Arche, et en Rust ou en C pour le firmware (étape 7).

wcet est le temps d’exécution dans le pire cas : la durée maximale de la fonction. L’analyse temporelle de l’étape 6 l’utilise.

Un corps peut aussi être écrit en Python, dans un bloc ```python. Utilisez-le pour ce que le langage d’action ne sait pas exprimer, comme un appel de bibliothèque ou une liste.

3. Une machine à états#

  states {
    state Idle "Stopped"
    state Running "Pumping"
    state Fault
    Idle -> Running on START [self.target <= MAX_FLOW]
    Running -> Idle on STOP
    * -> Fault on dry_run / log('dry run')
  }
}

La machine démarre dans son premier état, Idle. Une transition se lit ainsi :

  • on START : la transition est franchie quand le message START arrive ;
  • […] : la garde, une condition qui doit être vraie ;
  • / … : l’action, exécutée quand la transition est franchie ;
  • * -> Fault : une transition depuis n’importe quel état.

Le linter parcourt la machine. Il signale un état que rien n’atteint, un état sans issue, et un déclencheur qu’aucun port ne reçoit. Ici, dry_run est un tel déclencheur : archec check donne une indication à son sujet.

Le reste du système :

component Motor "Motor driver" {
  in drive: can "Drive" receives FLOW_RATE
}

component Panel "Operator panel" {
  out buttons: can "Buttons" sends START, STOP
}

system Station "Pumping station" {
  part panel: Panel
  part ctrl:  Controller
  part motor: Motor
  panel.buttons -> ctrl.cmd
  ctrl.motor -> motor.drive
}
Diagramme : Pumping station
Ce qu’archec dessine depuis ce code : Pumping station

Un system correspond à un modèle dans Arche, l’éditeur graphique. Ses parts sont des instances des composants. a.p -> b.q relie deux ports. archec vérifie que l’autre extrémité reçoit ce qu’émet la première.

Construisez le projet Arche et ouvrez-le :

archec build pump.arche -o out
arche --project out
✓ 17 files → out (station.yaml, pumphw.yaml, models.yaml, …)
  open with: arche --project …/out

out/ est le projet Arche : les fichiers YAML que lit l’application Arche.

4. Une exigence, et qui la satisfait#

requirement REQ-START "Start on command" {
  text "The pump shall start within 100 ms of a START command."
  priority high
  method test
}

archec passe le texte d’une exigence au crible pour repérer les mots invérifiables, comme « as fast as possible » ou « TBD ». satisfies REQ-START, dans le contrôleur (étape 2), indique qu’il satisfait l’exigence : un lien vers une exigence s’écrit sur ce qui la remplit. Le test de l’étape suivante indique qu’elle est vérifiée, avec verifies.

5. Un test, exécuté dans le simulateur#

test-plan TP-START "Starting" {
  case TC-START-01 "START starts the pump" {
    verifies REQ-START
    at 0ms do ctrl.target = 50.0
    at 10ms do send panel.buttons START(true)
    within 100ms expect ctrl.state == Running
  }
}

Un cas de test est une chronologie. at tel instant, do (faire) quelque chose. within tel délai, expect (attendre) quelque chose. Les lignes s’écrivent comme les corps du contrôleur : send envoie un message depuis le port d’une part, on affecte une variable d’une part, on compare son state à l’un de ses états.

archec test construit le projet, puis exécute ses plans de test dans le simulateur Arche (arche-cli) :

archec test pump.arche -o out --coverage
PASS  TP-START/TC-START-01 START starts the pump

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

Requirements: 1 verified by passing cases, 0 failing

Coverage (station.yaml):
  states           2/3      67 %
      not covered: ctrl: Fault
  transitions      1/4      25 %
      not covered: ctrl: Running -> Idle
      not covered: ctrl: Idle -> Fault
      not covered: ctrl: Running -> Fault
  messages         2/3      67 %
      not covered: STOP: panel.buttons -> ctrl.cmd
  functions        1/1     100 %
  requirements     1/1     100 %

La commande indique quels cas réussissent et quelles exigences ils vérifient. Avec --coverage, elle indique aussi quelle part des machines à états, des messages et des fonctions les tests ont parcourue, et ce qu’ils ont manqué.

6. Où il s’exécute#

component Mcu "Pump MCU" {
  kind processor
  cores 1
  hal stm32
  chip "stm32f446re"
  inout can0: can "CAN"
}

system PumpHw "Pump hardware" {
  part mcu: Mcu
  component bus "CAN bus" {
    kind bus
    bitrate 500kbps
  }
  mcu.can0 -> bus
}

deployment Onboard "On the pump" {
  system Station
  platform PumpHw
  binary pump_fw "pump.elf" on mcu {
    thread ctl "Control" { runs ctrl; period 10ms; step regulate; priority 10 }
  }
}
Diagramme : Pump hardware
Ce qu’archec dessine depuis ce code : Pump hardware

La plateforme est elle aussi un système. Ses parts sont des processeurs et des bus. Un deployment place le système logique sur la plateforme, sans modifier ni l’un ni l’autre. Ici, le contrôleur s’exécute sur un thread du MCU. Toutes les 10 ms, le thread appelle regulate.

archec analyze pump.arche
Deployment Onboard

Threads
  thread            where                    prio      C          T          D          R
  ctl               mcu/cpu0                 10        200us      10ms       10ms       200us    ok

Cores
  mcu/cpu0                   2 %       (RM bound 100 %)  ctl

La commande donne le temps de réponse de chaque thread (R) au regard de son échéance (D), et la charge de chaque cœur. Ici, le thread a besoin de 200 µs toutes les 10 ms : le cœur est donc occupé à 2 %.

7. Le firmware#

archec gen pump.arche --target embassy -o generated
  generated/embassy/pump_fw/src/arche.rs
  generated/embassy/pump_fw/src/app.rs
  generated/embassy/pump_fw/src/main.rs
  generated/embassy/pump_fw/Cargo.toml
  generated/embassy/pump_fw/.cargo/config.toml

La commande écrit une crate Rust par binaire, pour le runtime asynchrone Embassy. Ici il n’y a qu’un binaire, donc une seule crate : generated/embassy/pump_fw/.

  • src/arche.rs est réécrit à chaque exécution. Il contient :

    • les messages et leur codec CAN ;
    • un canal par lien ;
    • la machine à états de la part ctrl : CtrlState, CtrlEvent, CtrlMachine::next ;
    • son trait de comportement, CtrlBehaviour ;
    • la tâche du thread ctl. À l’arrivée d’un START, la tâche fait avancer la machine avant d’appeler la part.

    Les noms viennent de la part, et non de son composant. Deux parts d’un même composant donnent deux structs.

  • src/app.rs est écrit une seule fois ; ensuite, il vous appartient. Il contient :

    • la struct de la part, Ctrl, avec target à sa valeur initiale, et sa machine ;
    • la garde à implémenter, guard_target_le_max_flow ;
    • chaque fonction. regulate est déjà en Rust, traduite depuis son corps ```arche. Un corps Python serait laissé en commentaire, à vous de le porter.
  • src/main.rs, Cargo.toml et .cargo/config.toml sont configurés pour la puce STM32F446RE.

Compilez-la avec les outils de Rust :

cd generated/embassy/pump_fw && cargo build --release

8. En CI#

archec ci pump.arche -o out --coverage-min 50 --junit report.xml

exécute en une seule commande ce que vérifie un pipeline : lint, format, timing, TARA (l’analyse de sécurité), build, les tests et leur couverture. Elle affiche les résultats des tests, puis une ligne par étape de contrôle :

archec ci pump.arche
  ✓ lint      0 error(s), 0 warning(s)
  ✓ format    1 file(s) formatted
  ✓ vet       2 style finding(s) (--strict fails on them)
  – ui        no ui
  ✓ timing    1 deployment(s) hold
  – conform   no `source` names a file of the code (--src <dir>)
  – tara      no threats
  – verify    no requirement with a formal property
  ✓ build     17 file(s) → out
  ✓ test      1 case(s) pass
  ✓ coverage  58.3% (7/12) ≥ 50%
✓ ci: every gate passed
  JUnit report: report.xml

Un – marque une étape qui n’a rien à vérifier. report.xml est le rapport JUnit destiné au serveur de CI. La commande renvoie le code 1 si une étape échoue.

9. Partager des composants : les bibliothèques#

Un composant que plusieurs projets utilisent se range dans une bibliothèque. Une bibliothèque est un dossier qui contient un fichier library.arche. Ce fichier nomme la bibliothèque et en donne la version.

library pump-parts "Pump parts" {
  version "1.2.0"
}

Les versions cohabitent côte à côte, sous la forme shared/pump-parts@1.2.0/ et shared/pump-parts@2.0.0/. Un projet indique trois choses : où se trouvent les bibliothèques, quelles versions il accepte, et quel fichier de la bibliothèque il inclut :

project Pump "Water pump" {
  libraries "../shared"
  uses pump-parts "^1.2"
}

include "pump-parts/motor.arche"

^1.2 désigne la version 1.2 ou ultérieure, mais avant la 2.0. archec prend la version la plus récente disponible, sauf si le fichier arche.lock en décide autrement :

archec lib pump.arche          # each library, the version used, the others there are
archec lib pump.arche lock     # arche.lock: the versions and a fingerprint of their files

Une fois verrouillée, la version est conservée jusqu’à ce que vous verrouilliez de nouveau. Si les fichiers d’une bibliothèque changent mais pas sa version, archec le signale.

Pour aller plus loin#

  • patterns.md — chaque déclaration, avec ses propriétés et un exemple.
  • commands.md — chaque commande.
  • Les exemples : examples/physics (des équations, 30 lignes), examples/autonomous-car (une pile complète : exigences, déploiement, plans de test, génération de code).