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 :
inouout; - son type :
canest 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 == Runningteste l’état de la part ;send motor FLOW_RATE { … }émet un message sur un port ;goto Faultchangerait 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 messageSTARTarrive ;[…]: 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
}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 }
}
}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.rsest 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.rsest écrit une seule fois ; ensuite, il vous appartient. Il contient :- la struct de la part,
Ctrl, avectargetà sa valeur initiale, et sa machine ; - la garde à implémenter,
guard_target_le_max_flow; - chaque fonction.
regulateest déjà en Rust, traduite depuis son corps```arche. Un corps Python serait laissé en commentaire, à vous de le porter.
- la struct de la part,
src/main.rs,Cargo.tomlet.cargo/config.tomlsont 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).