Apprendre › Démarrer un projet

Apprendre

Démarrer un projet : archec new

archec new crée un nouveau projet qui fonctionne déjà. Son modèle passe archec check, son test tourne dans le simulateur, et il peut générer un firmware. Vous commencez donc par changer des noms, pas devant un fichier vide.

Un premier projet#

archec new my-rover --template blank --yes
  + project MyRover "My rover"
  + handlers typescript
✓ my-rover: 3 file(s)
✓ archec check: no errors

Next:
  archec check my-rover/main.arche
  archec test my-rover/main.arche
  code my-rover      (the VS Code extension draws it)

La commande écrit trois fichiers :

  • main.arche, le modèle ;
  • README.md, avec les commandes à lancer ensuite ;
  • .gitignore.

Vérifiez ensuite le modèle et lancez son test :

cd my-rover
archec check main.arche
archec test main.arche
✓ no errors
...
PASS  TP-BLINK/TC-BLINK-01 It turns on, then off

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

code . ouvre le dossier dans VS Code, et l’extension dessine le modèle.

Les questions#

Sans --yes, et dans un terminal, archec new my-rover pose cinq questions. Avec les genres, il y en a six : le genre de projet vient en premier.

  1. Que construisez-vous ? Choisissez un modèle de projet : blank, rover-esp32, can-sensor-node ou drone-fc (voir les modèles de projet). Vous pouvez aussi donner owner/name, un modèle de projet de l’Arche Store.
  2. Quelle carte ? La carte du modèle de projet, aucune carte, ou une carte du store de cartes. archec board list les liste.
  3. Que fera-t-il ? Facultatif : des numéros ou des mots, séparés par des virgules, ou rien. Chaque réponse ajoute les pièces du store qui le font et qui vont sur la carte (voir ce qu’il fait).
  4. Les parts principales, et qui parle à qui. Écrivez un a -> b par ligne, par exemple lidar -> planner et planner -> motors. Un nom seul est une part sans lien pour l’instant. Pour une part qui n’existe pas, archec crée un composant, une part, un port à chaque extrémité et un message entre les deux. Une part que le modèle de projet contient déjà reçoit un nouveau port.
  5. Du code généré ? none, c, embassy (Rust) ou go. Si vous avez choisi une carte et que le modèle n’a pas encore de déploiement, archec en écrit un : un firmware sur la carte, avec un thread qui exécute les parts.

archec vérifie chaque étape comme le fait archec check. Une étape qui ajouterait une erreur est écartée, et la sortie le signale dans une note. Par exemple : une carte dont les ports ne correspondent pas aux liens du modèle de projet.

Sans questions#

Les options répondent aux questions. --yes prend la réponse par défaut pour les autres. archec prend aussi les réponses par défaut quand l’entrée n’est pas un terminal.

archec new my-node --template can-sensor-node --yes
archec new my-robot --board raspberry-pi-4 --parts "lidar -> planner, planner -> motors" --target go --yes
archec new my-drone --template drone-fc --board nucleo-f446re --name "Racer" --dry-run
  • --does temperature,motor répond à « Que fera-t-il ? » (ce qu’il fait).
  • --name donne son nom au projet. Par défaut, le nom vient du dossier : my-drone donne project MyDrone "My drone".
  • --dry-run affiche les fichiers et n’écrit rien. La dernière ligne ci-dessus affiche :
  + project Racer "Racer"
  + handlers typescript
  + derived-from "arche/drone-fc@0.1.0"
  + board nucleo-f446re (in place of the template's nucleo-h743zi2)

── .gitignore ──
...

Ce qu’il fait#

La troisième question, ou --does, prend des choix simples. Chacun ajoute des parts venues des étagères : un appareil du store qui le fait, et les algorithmes qui vont avec.

Choix Aussi compris Ajoute
temperature humidity, pressure, weather un BME280 (I²C), sinon un SHT3x, un DS18B20 (1-Wire sur une broche GPIO), une thermistance (une broche analogique)
motion imu, tilt, acceleration un MPU6050 (I²C), sinon un ADXL345 ; l’algorithme ComplementaryFilter
distance range, ultrasonic, obstacle un HC-SR04 (broches GPIO), sinon un LIDAR-Lite (I²C)
light lux, brightness un BH1750 (I²C), sinon un TSL2561, un capteur de lumière Grove (une broche analogique)
compass heading, magnetometer un HMC5883L (I²C)
presence pir un détecteur de mouvement PIR (une broche GPIO)
button switch, press un bouton (une broche GPIO) ; l’algorithme Debounce
led lamp une LED (une broche GPIO)
relay fan, pump un relais (une broche GPIO)
motor dc-motor, wheel un moteur à courant continu (une broche GPIO) ; l’algorithme Ramp
servo un servo de modélisme (une broche PWM)
display screen, lcd, oled un OLED SSD1306 (I²C), sinon un HD44780 (broches GPIO)
setpoint pid, control l’algorithme Pid
thermostat heating, cooling un capteur de température, un relais et l’algorithme Thermostat
filter smooth, low-pass, noise l’algorithme LowPass
archec new greenhouse --board nucleo-g474re --does thermostat,display --yes
  + board nucleo-g474re: uses arche-hw-store "^0.1", include …, system GreenhouseHw { part nucleo_g474re: NucleoG474RE }
  + thermostat: part air: Bme280 — BME280 (on nucleo_g474re.i2c1)
  + thermostat: part relay: GpioRelay — Relay (on a GPIO pin)
  + thermostat: part thermostat: Thermostat — arche-algorithms (in Main)
  + display: part display: Ssd1306 — SSD1306 (on nucleo_g474re.i2c1)
  • Un appareil doit aller sur la carte : un appareil I²C seulement si la carte a de l’I²C, un appareil analogique seulement si elle a une broche analogique ou un ADC. archec prend le premier appareil de la liste qui convient, puis tout autre appareil du store qui fait la même chose. Si aucun ne convient, une note le dit et nomme l’étagère où chercher.
  • Avec une carte, un appareil va dans le système matériel, à côté de la carte, comme le place archec device add. Un appareil I²C ou SPI est relié au bus de la carte (nucleo_g474re.i2c1 -> air.i2c). Les broches, c’est à vous de les relier. Sans carte, les appareils vont dans le système logique.
  • Un algorithme est une part du système logique, avec le uses et l’include qu’écrit archec shelf add.
  • Les parts ne sont pas encore reliées à votre logique. Un composant dit ce dont il a besoin (out air: requires TemperatureSensor) et le système le relie (ctl.air -> air.temperature_sensor), comme dans boards.md.

Chaque part est une étape, vérifiée comme les autres : une part qui ajouterait une erreur est écartée, avec une note. Dans VS Code, New Project pose la même question, sous forme d’une liste où vous cochez les choix.

Les modèles de projet#

Modèle de projet Ce que c’est Carte
blank Un composant qui clignote, une exigence et son test. Le plus petit projet qui fait quelque chose. aucune (--board en ajoute une)
rover-esp32 Un rover à roues : une télécommande, un capteur de distance, deux moteurs et un contrôleur de conduite. Sa machine à états s’arrête avant un obstacle. ESP32-DevKitC
can-sensor-node Une température envoyée sur CAN toutes les 100 ms. Une mauvaise mesure le fait passer dans un état de défaut. Une passerelle sur le bus le réinitialise. NUCLEO-G474RE (STM32G4, FDCAN)
drone-fc Un contrôleur de vol de quadricoptère : récepteur RC, centrale inertielle, armement et failsafe, une boucle de vitesse à 1 kHz, quatre ESC. NUCLEO-H743ZI2
ros2-rover Un rover sous forme de nœuds ROS 2 : pilote du lidar, planificateur, pilote des moteurs. Un monde simulé ferme la boucle, et le rover s’arrête avant le mur. aucune (un ordinateur Linux)
robot-draw, robot-cap, robot-cube Un petit bras dans MuJoCo dessine un carré, dévisse un bouchon de bouteille, tourne une face d’un cube ; des exigences, des cas de test face au bras, des constantes à régler (prototypage de robot). aucune (--kind robot met le planificateur sur un Pico)

Les modèles de projet se trouvent dans lib/templates/, à côté d’archec. Chacun est une bibliothèque avec kind template. archec store seed les publie, si bien qu’un store les propose sous arche/<id>. Pour créer votre propre modèle de projet, créez un dossier de bibliothèque avec kind template et un main.arche, et publiez-le comme n’importe quel paquet.

Genres#

--kind dit ce qu’est le projet : un firmware, un service, un robot… Avec un genre, archec new ne se contente pas d’écrire un modèle qui passe les vérifications. Il aboutit à un dépôt qui compile et s’exécute déjà.

archec new my-node --kind firmware
First run (firmware):
  ✓ archec check
  ✓ archec test — 3/3 pass
  ✓ archec gen --target c
  ✓ archec gen --target c-tests
  ✓ make (rover_fw)
  ✓ the test plans on the C (make test) — 1/1 pass
  ✓ rover_fw runs 0.5 s on this computer
✓ first run: simulated 500 ms, built (make), 4/4 tests pass, rover_fw runs 0.5 s on this computer

Dans un terminal, sans --kind, la première question est Quel genre de projet ? Vous répondez par l’un des genres ci-dessous, ou par un modèle de projet ou un paquet du store comme avant. Avec --describe, archec choisit le genre d’après les mots de votre phrase (firmware, esp32, stm32…). --kind a la priorité.

Chaque genre reçoit ce qui suit :

  • Un modèle de projet, un langage de code et un déploiement. Chaque genre part de son propre modèle de projet ; --template en choisit un autre. Chaque genre fixe le langage du comportement ; --handlers en choisit un autre. Si le projet n’a pas de déploiement, archec écrit celui dont son code a besoin. Comme pour toute étape, une étape qui ajouterait une erreur est écartée, avec une note.

  • src/ et generated/. src/ contient le code que vous complétez. Il est généré, et vous le versionnez. Écrivez votre code entre les marqueurs USER CODE BEGIN et USER CODE END : chaque archec gen le conserve (voir la régénération). Le reste du code généré va dans generated/, avec ce qu’écrit la compilation. .gitignore exclut generated/.

  • Un test pour chaque part. Une part qu’aucun plan de test ne nomme reçoit un premier cas de test dans tests.arche. archec test l’exécute dans le simulateur. Le cas vérifie l’un de ces points :

    • un message qu’un lien apporte à la part fait avancer sa machine à états, ou lui parvient ;
    • ce que la part envoie parvient à la part à l’autre extrémité ;
    • la part démarre dans son premier état.

    Modifiez ces cas pour dire ce que la part doit faire.

  • La CI. .github/workflows/archec.yml et .gitlab-ci.yml à la racine. Le premier job vérifie le modèle (archec gen --target ci : archec check, archec ci). Un job code génère ensuite le code, le compile et lance ses tests, avec les outils nécessaires installés.

  • VS Code. .vscode/extensions.json recommande arche-lang et les extensions utiles pour le code. .vscode/tasks.json contient trois tâches : build (générer, puis compiler), test (le simulateur, puis les tests du code) et archec: live. À l’ouverture du dossier, l’extension propose de lancer archec live.

  • La première exécution. Une fois les fichiers écrits, archec lance archec check, archec test (les plans de test dans le simulateur), archec gen pour chaque cible, puis la compilation du genre et ses tests. Il affiche une ligne par étape, puis une ligne de synthèse.

    • Si un outil manque sur cet ordinateur, son étape est sautée, avec une note. De même pour un démon qui ne tourne pas (podman, Docker).
    • Une étape qui échoue affiche la fin de sa sortie, et archec new se termine avec le code 1. Sur un projet qu’archec vient de créer, c’est un bogue d’archec.
    • --no-run saute la première exécution. archec new --first-run [dir] la relance plus tard. Le genre est enregistré dans .archec/kind.json.
Genre Ce que vous obtenez Code Compilé et testé avec
firmware Du code pour une carte à microcontrôleur : les parts du modèle placées sur la carte, son firmware généré. Modèle de projet rover-esp32 ; --board pour une autre carte, --target c (par défaut), embassy ou go. src/c/ (ou src/embassy/, src/go/), un dossier par binaire ; generated/c-tests/ C : make (le runtime POSIX, sur cet ordinateur), le binaire exécuté une demi-seconde, les plans de test sous forme de tests unitaires C (make test). Go : go build, go vet. Rust : cargo check quand la cible de la carte est installée (rustup target list --installed) ; la cible Xtensa d’un ESP32 demande la chaîne d’outils d’Espressif, elle est donc sautée.
service Un service backend en Go sur un hôte Linux ou macOS, sans carte. Modèle de projet web-service : api -> orders -> store, des routes HTTP, une machine à états de stockage. src/go/<project>/ (avec http.go, les routes) ; generated/openapi/ go build, go vet, go test (chaque route répond) ; le programme sert du HTTP.
containers Plusieurs programmes, chacun dans son conteneur, qui communiquent par le réseau. Modèle de projet container-pipeline : ingest -> processor -> dashboard. src/go/<program>/ par conteneur ; generated/containerd/, generated/k8s/ go build pour le Linux du conteneur, go vet, go test ; le fichier compose et les manifestes Kubernetes lus hors ligne ; podman build de chaque image quand podman (ou Docker) tourne.
ros2 Un robot sous forme de nœuds ROS 2, avec un monde simulé qui ferme la boucle. Modèle de projet ros2-rover : lidar, planificateur, moteurs. src/ros2*/ (paquets, nœuds, launch) ; generated/c-tests/, generated/gazebo/ make test (les tests C), une vérification statique des paquets ; avec ROS 2 : colcon build, puis les nœuds lancés face au monde. La CI l’exécute dans ros:jazzy-ros-base.
desktop Un programme sur PC : des parts sur des threads, un écran d’opérateur. Modèle de projet desktop-app : une source, un moniteur de seuil, une console. src/c/, src/ui-qml/<Ui>/ ; generated/cmake/, generated/c-tests/, generated/ui-web/ CMake, les tests C, le programme exécuté une seconde ; l’écran Qt compilé et lancé hors écran quand Qt 6 est présent.
library Des composants que d’autres incluent : un paquet du store et une bibliothèque C. Modèle de projet component-library : un seuil, un verrou, un système d’exemple. src/c/ ; CMakeLists.txt (le vôtre) ; generated/c-tests/ CMake, ctest (un test par cas), et archec store publish . --dry-run : le paquet tel que publié compile.
robot Un petit bras et une tâche dans MuJoCo : dessiner une forme, dévisser un bouchon, tourner une face d’un cube. Modèle de projet robot-draw, ou la scène que nomme --describe. src/c/arm_fw/ (le planificateur, pour un Raspberry Pi Pico) ; generated/mujoco/ make (le runtime POSIX), le binaire exécuté une demi-seconde ; avec le Python de MuJoCo, le plan de test face au bras (archec sim --plant … --test), sauté avec une note sans lui. archec test autorise les cas qui ont besoin du bras (tests/mujoco.allow).

Un service web (--kind service)#

archec new my-shop --kind service
archec new my-shop --kind service --parts "api -> orders, orders -> store, store -> billing"

Ce genre crée un service backend en Go : un seul processus sur un hôte Linux ou macOS, sans carte. Il part du modèle de projet web-service, avec trois modules comme parts : api -> orders -> store.

  • api répond en HTTP : POST /orders, GET /orders/count, DELETE /orders.
  • orders vérifie chaque commande.
  • store conserve les commandes acceptées.

Le modèle comporte quatre exigences, et un plan de test qui passe dans le simulateur. Le comportement est écrit dans le langage d’action (handlers arche). Le simulateur d’Arche l’exécute, et archec le traduit en Go.

Ce que archec new ajoute et produit :

  • Le déploiement. Un processeur Host (compute { os linux }) dans une plateforme Machine, et deployment OnHost. Il a un seul binaire, en language go, avec un thread qui exécute les parts. Les parts traitent donc leurs messages et leurs appels HTTP un par un.

  • src/go/<project>/, le programme Go (archec gen --target go -o src, versionné). Tous ces fichiers sont régénérés :

    • parts.go : chaque part, avec ses variables, ses fonctions et sa machine à états ;
    • main.go : les parts câblées comme le modèle les relie, avec une goroutine par thread ;
    • http.go : une route pour chaque handler GET "/path" -> fn du modèle ;
    • http_test.go : un test de chaque route.

    Votre code va à deux endroits, et archec gen conserve les deux. Le premier, ce sont les régions USER CODE : <Part>.init, et le corps de chaque fonction à laquelle le modèle ne donne pas de corps. Le second, c’est user.go, écrit une seule fois.

  • generated/openapi/<Component>.json (--target openapi) : la même API en OpenAPI 3.1, pour les clients et la documentation.

  • La première exécution : go build (le binaire va dans generated/bin/), go vet et go test. Sans Go dans le PATH, ces étapes sont sautées avec une note.

Lancez-le :

cd src/go/my_shop
go run .                                   # listens on :8080; ADDR=:9000 for another
curl -X POST -d '{"item":7,"qty":3}' localhost:8080/orders
curl localhost:8080/orders/count

Comment fonctionne une route :

  • Elle prend les paramètres de sa fonction dans le chemin (/items/{id}). Sinon, elle les prend dans la query (GET, DELETE, HEAD) ou dans un corps JSON (POST, PUT, PATCH).
  • Elle répond avec la valeur de retour de la fonction en JSON : une struct, avec les noms de champs du modèle. Quand la fonction ne renvoie rien, elle répond 204.
  • Un paramètre qui ne s’analyse pas donne une erreur 400.
  • L’appel s’exécute sur le thread de sa part, comme un message. Une part n’exécute donc jamais deux choses à la fois.
  • Le port vient de l’attr url de la part (dans le modèle de projet : http://localhost:8080). ADDR en fixe un autre.

Pour ajouter une route, ajoutez un handler à un port d’une part, et ajoutez sa fonction :

in http: ethernet "HTTP" {
  handler GET "/orders/{item}" -> stock_of
}
fn stock_of "Stock of an item" (item: uint32) -> uint32 {
  ```arche
  return stock
  ```
}

Lancez ensuite archec gen main.arche --target go -o src et archec gen main.arche --target openapi -o generated.

Limites :

  • Le simulateur n’exécute pas le HTTP. Le plan de test envoie à la place les messages auxquels mènent les routes : send(api.orders, PLACE(…)).
  • Le test des routes vérifie que chaque route répond avec son statut. Il ne vérifie pas le contenu de la réponse : pour cela, écrivez votre propre *_test.go à côté.
  • Une fonction que le modèle déclare sans corps est une région USER CODE en Go. Mais le simulateur d’Arche s’arrête quand il appelle cette fonction. Donnez un corps à la fonction dans le modèle quand un test l’appelle.

Des processus dans des conteneurs (--kind containers)#

Ce genre crée plusieurs processus, chacun dans son conteneur, qui communiquent par le réseau. Le modèle de projet, container-pipeline, est une chaîne de trois parts :

  • ingest prend une mesure chaque seconde ;
  • processor la résume ;
  • dashboard affiche le résumé, et passe en Alarm quand une mesure dépasse LIMIT.
archec new my-pipes --kind containers

Ce que vous obtenez :

  • Un modèle qui se simule. Trois composants, leurs messages, trois exigences et un plan de test. Le déploiement place chaque part dans un conteneur, sous forme de programme Go, sur un serveur Linux (runtime containerd). archec test exécute les cas de test du modèle de projet, plus un pour le déploiement : une mesure chaque seconde.

  • Le code, dans src/go/<part>, à compléter (--target go). Chaque part est un programme Go, avec :

    • ses variables, ses corps ```arche traduits en Go, et sa machine à états ;
    • une région USER CODE dans chaque constructeur, et dans chaque fonction qui n’a pas de corps dans le modèle ;
    • user.go, écrit une seule fois.

    Un lien entre deux parts passe en JSON sur HTTP (net.go). Chaque programme écoute sur son propre port, à partir de 9001 dans l’ordre du déploiement. Il joint les autres sur 127.0.0.1. Deux variables d’environnement changent cela : ARCHE_LISTEN (par exemple :8080) et ARCHE_PEER_<PART> (par exemple http://processor:8080). net_test.go teste les deux extrémités de chaque lien.

  • Les images et les manifestes, dans generated/. Ils sont régénérés, et pas versionnés.

    • generated/containerd contient un Containerfile par conteneur, qui prend le programme dans bin/<part>, et containers/server/compose.yaml.
    • generated/k8s/k8s contient un Deployment Kubernetes par conteneur, pour kubectl apply -k.

    Les conteneurs utilisent le réseau de l’hôte. Les mêmes ports fonctionnent donc sur une seule machine, sous compose, et sur un nœud d’un cluster.

La première exécution fait ce qui suit :

  1. Elle compile chaque programme pour le Linux du serveur, dans generated/containerd/bin.
  2. Elle lance go vet et go test sur chaque programme.
  3. Elle vérifie le fichier compose (docker-compose config) et les manifestes (kubectl kustomize), sans démon ni cluster.
  4. Elle construit les images avec podman, si la machine podman tourne. Sinon, elle indique podman machine start et continue.

Lancez-le sur votre machine, avec un terminal par part (cd src/go/ingest && go run .), ou dans des conteneurs :

podman compose -f generated/containerd/containers/server/compose.yaml up

L’isa (jeu d’instructions) du serveur est celui de la machine qui a créé le projet, par exemple arm64 sur un Mac ARM. Les images tournent donc sur cette machine. Pour un serveur x86, écrivez isa x86_64. Les programmes et les images sont alors compilés pour linux/amd64. Ils ne tournent pas sous podman sur un Mac ARM, car le runtime de Go plante sous émulation. Compilez-les dans la CI ou sur le serveur.

Plus de détails sur les parts :

  • Une part que vous ajoutez (--parts "processor -> archive") reçoit son propre conteneur et son propre programme.
  • Une part sans port in exécute sa première fonction, sans paramètres, chaque seconde. Les autres parts s’exécutent quand elles reçoivent un message.
  • Une part sans comportement pour l’instant n’est dans aucun programme. Un lien vers elle est écarté tant qu’elle ne fait rien.

Robot ROS 2 (--kind ros2)#

archec new my-robot --kind ros2

Ce genre crée un robot sous forme de nœuds ROS 2. Il part du modèle de projet ros2-rover, avec trois parts :

  • un pilote de lidar ;
  • un planificateur qui roule vers un mur, ralentit en s’en approchant, et s’arrête 0,3 m avant ;
  • un pilote de moteurs qui convertit la vitesse en vitesses de roues.

Le monde est un procédé (kind plant) : une part qui représente le monde physique. Il déplace le rover selon ses vitesses de roues, et donne au lidar la distance restante. Le simulateur exécute le procédé avec le reste, si bien que le plan de test tourne sans rien installer. Le procédé n’est pas un nœud. Sur le robot, dans Gazebo ou dans un script de test, c’est autre chose qui joue le monde.

Ce que vous obtenez :

Déploiement <Project>Ros2, avec packaging ros2 : un binaire, <project>_nodes, sur un ordinateur Linux. Il a un processus pour chaque part qui a un comportement et n’est pas du matériel (le procédé est écarté).
src/ (le vôtre, versionné) Produit par archec gen --target ros2 : le paquet de messages <project>_msgs (src/ros2) ; le paquet de nœuds src/ros2_nodes/<project>_nodes, avec un exécutable rclcpp par processus autour du module C de la part ; et <project>_ros2_bringup, avec le fichier launch.
generated/ (ignoré) c-tests (les plans de test sous forme de tests unitaires C des mêmes modules C), gazebo (le monde pour gz sim : SDF, bridge, adaptateur), colcon (la compilation, l’installation et les logs de colcon).
Tests Le plan de test dans le simulateur (archec test). make test dans generated/c-tests. tests/ros2_check.py --static : chaque package.xml s’analyse, le Python compile, chaque fichier launch a generate_launch_description, les modules C compilent. tests/ros2_check.py avec ROS 2 : il lance les nœuds et joue le monde, et le rover doit s’arrêter entre 0,25 et 0,35 m.
Compilation colcon build --base-paths src, dans generated/colcon.
CI Les étapes de compilation et de test, dans l’image ros:jazzy-ros-base (ciContainer).

Votre code dans les nœuds va dans leurs régions USER CODE, et archec gen le conserve. Les régions sont :

  • dans chaque src/<exe>.cpp : les includes ; la fin du constructeur de chaque nœud (<part>.node, par exemple un abonnement au topic d’un vrai pilote) ; les membres du nœud (<part>.members) ; et main, avant le démarrage des threads ;
  • dans CMakeLists.txt : une région pour d’autres paquets et sources ;
  • dans chaque module C : les includes, et la fin de son init.

Le comportement lui-même est dans le modèle.

Sans ROS 2 sur la machine (sur macOS, par exemple), colcon build et l’exécution réelle sont sautés avec une note. Le simulateur, les tests unitaires C et les vérifications des paquets tournent quand même. Pour compiler malgré tout, utilisez le conteneur ROS 2 :

podman run --rm -v "$PWD:/ws" -w /ws ros:jazzy-ros-base bash -c \
  '. /opt/ros/jazzy/setup.sh && colcon --log-base generated/colcon/log build --base-paths src --build-base generated/colcon/build --install-base generated/colcon/install && . generated/colcon/install/setup.sh && python3 tests/ros2_check.py'

Programme de bureau (--kind desktop)#

Ce genre crée un programme sur PC, sous Linux, macOS ou Windows. Par exemple : un outil de pilotage, un banc de test, l’interface d’un simulateur. Les parts sont des modules C sur quelques threads d’un même programme. La part qui a un ui { } est l’écran du programme.

archec new my-bench --kind desktop

Il part du modèle de projet desktop-app, qui contient :

  • une source de signal qui envoie un échantillon toutes les 10 ms ;
  • un moniteur qui passe en High au-dessus d’un seuil, et journalise chaque alarme ;
  • une console d’opérateur, avec une jauge et des boutons Start/Stop ;
  • trois exigences, et le plan de test qui les vérifie.

Son déploiement place un programme, app, sur le PC. La source tourne sur un thread à 10 ms. Le moniteur et la console tournent sur un autre thread. Un projet qui arrive sans déploiement reçoit un programme, avec un thread par part.

Ce que vous obtenez :

Où Quoi Versionné
src/c/ Le C des parts (--target c). Votre code va entre les marqueurs USER CODE BEGIN et END (Monitor.init, Monitor.includes, app.start dans app/wiring.c, …), et archec gen le conserve. oui
src/ui-qml/Console/ L’écran sous forme d’application Qt Quick (--target ui-qml). main.cpp et CMakeLists.txt sont à vous ; le QML vient du modèle. oui
generated/cmake/ Le projet CMake du programme (--target cmake). non
generated/c-tests/ Le plan de test sous forme de tests unitaires C (--target c-tests). non
generated/ui-web/ L’écran sous forme de page web, avec le modèle simulé dedans. Ouvrez index.html. non

La première exécution le compile et le lance, avec ces commandes :

archec test main.arche                                      # the test plan, simulated
cmake -S generated/cmake -B build -DARCHE_GEN=src           # the C is in src/c
cmake --build build
make -C generated/c-tests test                              # 3 passed, 0 failed
./build/app/app 1000                                        # runs for a second, then exits
cmake -S src/ui-qml/Console -B build/ui-Console && cmake --build build/ui-Console
QT_QPA_PLATFORM=offscreen ARCHE_UI_QUIT_AFTER=1000 ./build/ui-Console/console_ui

Remarques sur ces commandes :

  • -DARCHE_GEN=src est donné sans type, si bien que CMake en fait un chemin absolu à partir du dossier où vous le lancez.
  • ./build/app/app sans nombre tourne jusqu’à Ctrl-C.
  • Les étapes Qt demandent Qt 6 : qmake6 dans le PATH, et sa configuration CMake. Sans lui, elles sont sautées avec une note.

Limites :

  • make test exécute le C que --target c-tests écrit à partir du modèle. Il n’exécute pas votre code dans src/c/. Le programme compile et exécute ce que vous écrivez dans une région, mais aucun test unitaire ne le couvre.
  • L’écran et le programme ne sont pas encore reliés. L’écran Qt lit ses valeurs par un WebSocket (ARCHE_UI_WS, voir ui), et le programme C n’en sert pas. La page web simule le modèle toute seule.
  • Sous Windows, avec un générateur multi-configuration (Visual Studio), le programme est dans build/app/Debug/app.exe. La première exécution ne le cherche pas là.

Bibliothèque de composants (--kind library)#

archec new my-sensors --kind library

Ce genre crée une bibliothèque de composants que d’autres projets incluent. Elle a deux formes : un paquet de l’Arche Store (le modèle) et une bibliothèque C compilée avec CMake (le code). Il part du modèle de projet component-library :

Fichier Ce que c’est
components.arche La bibliothèque : ses messages, ses exigences et ses composants (un seuil avec hystérésis, un verrou).
main.arche Le projet, et un petit système qui utilise les composants (Example), avec le plan de test.
library.arche La fiche du store : kind library, son nom (my-sensors), sa version, son propriétaire, sa licence, le contrôle à l’export.
CMakeLists.txt La bibliothèque CMake my_sensors, ses ports my_sensors_ports, et un test ctest par cas. Il est à vous, écrit une seule fois.
src/c/ Le C de chaque composant (archec gen --target c -o src). Votre code entre les marqueurs USER CODE est conservé.
generated/c-tests/ Le plan de test en C (--target c-tests), que ctest exécute sur src/c.

La première exécution fait ce qui suit :

  1. Elle vérifie le modèle.
  2. Elle exécute le plan de test dans le simulateur.
  3. Elle écrit le C, le compile avec CMake et lance ctest.
  4. Elle empaquette le dossier comme le ferait le store, et le compile comme le fait le validateur du store (archec store publish . --dry-run). Rien n’est envoyé.

Une bibliothèque n’a pas de déploiement, car elle ne tourne nulle part toute seule. --target c écrit les composants sans déploiement. Ce que chaque composant envoie passe par une fonction dans src/c/<component>_ports.c. Le projet qui utilise la bibliothèque écrit ces fonctions. Le fichier est un point de départ : il encode le message, et vous laisse l’envoi. Les tests C transportent eux-mêmes les messages entre les parts de l’exemple.

Pour utiliser le C dans un autre projet CMake :

add_subdirectory(path/to/my-sensors)
target_link_libraries(app PRIVATE my_sensors)   # and my_sensors_ports, or your own send functions

Pour publier la bibliothèque :

  1. Renseignez owner, license et export-control dans library.arche. Le modèle de projet écrit owner your-name, Apache-2.0 et none. Ce sont vos déclarations en tant qu’éditeur.
  2. Lancez archec store check ., puis archec store publish ..

Un projet prend la bibliothèque avec archec add main.arche your-name/my-sensors, et inclut my-sensors/components.arche. Ce que construit archec (generated/, arche-out/) ne fait pas partie du paquet.

Limites :

  • Le C part avec le paquet tel que vous l’avez écrit. Mais un projet qui inclut les composants et lance lui-même archec gen réécrit leur C, sans le code de vos régions. Pour le code, utilisez la cible CMake de la bibliothèque.

Bras robotisé (--kind robot)#

archec new my-arm --kind robot --describe "unscrew a bottle cap"

Ce genre part d’une des scènes de robot : robot-draw, robot-cap ou robot-cube (prototypage de robot). Avec --describe, la phrase choisit la scène :

  • Hors ligne (par défaut), ce sont ses mots : draw, pen, square choisissent robot-draw ; cap, bottle, unscrew robot-cap ; cube, puzzle robot-cube. Pour robot-draw, triangle ou star et une taille (9 cm) donnent la forme à dessiner.
  • Avec une IA autorisée (archec config ai local-ai ou online), le modèle lit la phrase et répond la même chose : une scène, une forme, une taille. Une réponse qui n’en fait pas partie se rabat sur les mots. Le modèle n’écrit rien d’autre.
# scene: robot-draw, a triangle 90 mm across (the words "draw", "triangle")

Le déploiement met le planificateur sur un Raspberry Pi Pico. Le bras, l’objet et le vérificateur (le traceur, le banc) appartiennent à la simulation : ils ne sont pas placés. Le C se compile pour cet ordinateur. Les pilotes des servos et des doigts, c’est à vous de les écrire dans ses régions USER CODE.

Remixer un paquet du store#

N’importe quel paquet du store peut servir de point de départ à un projet : une architecture entière, un modèle de projet, une carte.

archec new my-car --from arche/autonomous-car
archec new my-node --from acme/can-node@^1.2 --store https://store.example.com

Le projet est une copie, pas une dépendance. Les fichiers sont à vous, et rien ne les met à jour dans votre dos. (archec add sert pour une bibliothèque que vous utilisez.) archec vérifie le paquet comme le fait archec add : son hash, la signature de son éditeur et l’empreinte des fichiers. Ce que le paquet utilise du store vient aussi.

Le projet enregistre son origine :

project MyCar "My car" {
  version "0.1.0"
  derived-from "arche/autonomous-car@0.3.0"
}

Quand vous publiez le projet, sa bibliothèque garde cette ligne. La page du paquet dans le store montre la famille : de quoi le paquet est dérivé, et ce qui en est dérivé.

Dans VS Code, un paquet de la vue Store propose Use as Starting Point. La commande demande un dossier, puis ouvre le nouveau main.arche. Arche: New Project… dans la palette de commandes pose les cinq questions ci-dessus.

À partir d’une description#

archec new my-robot --describe "a robot with 2 motors, a lidar and a Raspberry Pi"

Claude écrit le premier modèle. Il reçoit une courte référence du langage, les cartes du store de cartes, et un modèle de projet comme exemple. archec vérifie ce qui revient, et renvoie les erreurs à Claude, qui les corrige. Cela se répète jusqu’à quatre tours (--rounds le change). Le résultat est un premier jet : relisez-le avant de vous y fier.

Quand la description comporte un affichage (un écran, un tableau de bord, une IHM, une dalle tactile, un OLED), Claude reçoit aussi la référence de ui { }, et on lui demande les écrans. Le composant qui possède l’affichage reçoit une ui liée à ce que le modèle lui envoie. archec la vérifie comme le reste.

Ce qui est envoyé, et quand :

  • archec envoie votre description, et les messages d’archec check sur ce qu’a écrit Claude, à l’API d’Anthropic (le modèle claude-opus-5-5).
  • Il ne les envoie que quand vous lancez la commande.
  • --dry-run affiche tout le prompt et n’envoie rien.
  • Il faut ANTHROPIC_API_KEY.

Limites#

  • Les cas de test qu’un genre écrit pour chaque part sont des premiers cas, pas une spécification. Modifiez-les pour dire ce que la part doit faire.
  • Une étape qui ajouterait une erreur (une carte, un lien, un déploiement) est écartée avec une note, pas imposée.
  • Un modèle écrit avec --describe est un premier jet produit par un modèle de langage. Relisez-le avant de vous y fier.
  • Chaque genre a ses propres limites, listées dans sa section ci-dessus.

Pour aller plus loin#

  • Le tutoriel : ce que veut dire chaque ligne d’un modèle, d’une pompe à eau jusqu’à son firmware.
  • Cartes : archec board add et archec device add, pour ajouter une carte ou un capteur plus tard.
  • archec explain <code> : ce que veut dire un message d’archec check.