Guides pratiques › Utiliser des cartes

Guides pratiques

Cartes : le store et vos propres collections

La plupart des projets reposent sur des cartes conçues par d’autres : un devkit ESP32, une Nucleo STM32, un Raspberry Pi, une Jetson. archec fournit un store de cartes connues (arche-hw-store). Vous pouvez aussi ranger vos propres cartes dans des collections de même forme. Le modèle d’une carte dit ce qu’est la carte, quels processeurs elle porte et quels connecteurs elle a, avec les broches auxquelles ils sont reliés.

Utiliser une carte#

archec board list
arche-hw-store 0.1.0  built in
  beaglebone-black  BeagleBone Black — AM3358 (linux, Cortex-A8) · I2C, SPI, GPIO, ANALOG
  esp32-c3-devkitm-1  ESP32-C3-DevKitM-1 — ESP32-C3 (esp32, RISC-V RV32IMC) · CAN, UART, USB, RF
  esp32-devkitc  ESP32-DevKitC — ESP32 (esp32, Xtensa LX6) · CAN, UART, USB, RF
  ...

La commande liste le store, puis vos collections. archec board show donne le détail d’une carte :

archec board show nucleo-g474re
NUCLEO-G474RE  (arche-hw-store 0.1.0, built in)
  STMicroelectronics · NUCLEO-G474RE
  https://www.st.com/en/evaluation-tools/nucleo-g474re.html
  ...
  processors:
    mcu    STM32G474RE  1× Cortex-M4F · 170MHz · 128KiB · hal stm32 · chip "stm32g474re" · os bare-metal
    mcu    Renode: none — Renode 1.17 has no STM32G4 platform (its STM32_FDCAN model serves the STM32L552 only)

  connectors:
    can0   can       FDCAN1, CAN FD (add a transceiver)  [tx PA12, rx PA11]
    uart2  uart      USART2 (ST-LINK virtual COM)  [tx PA2, rx PA3]
    usb    usb       ST-LINK USB
    pwr    power     5 V USB

archec board add ajoute la carte à votre modèle :

archec board add main.arche nucleo-g474re --as ctl
  + uses arche-hw-store "^0.1"
  + include "arche-hw-store/boards/nucleo-g474re/nucleo-g474re.arche"
  + system RoverHw { part ctl: NucleoG474RE }
✓ nucleo-g474re is in the project — main.arche

Elle écrit trois choses. Elle ne les garde que si le projet compile toujours aussi bien qu’avant.

project Rover {
  uses arche-hw-store "^0.1"               // the store, built into archec
}
include "arche-hw-store/boards/nucleo-g474re/nucleo-g474re.arche"

system RoverHw "Hardware" {                // the deployment's platform, or this one
  part ctl: NucleoG474RE
}
Diagramme : Hardware
Ce qu’archec dessine depuis ce code : Hardware
Essayer

Les options :

  • --as nomme la part.
  • --into <System> choisit le système où l’ajouter.
  • --copy copie plutôt le dossier de la carte dans components/, pour que vous puissiez la modifier.

Faire tourner du code sur la carte#

Un binaire placé on la carte tourne sur le processeur de la carte. Certaines cartes ont plusieurs processeurs : la Kria KR260, par exemple, a apu et rpu. archec demande alors lequel.

deployment D {
  system Rover
  platform RoverHw
  binary fw on ctl { thread t { runs controller } }      // ctl.mcu, the STM32G474RE
  route controller.bus -> motor.bus over can_bus { id 0x120 }
}
Diagramme : D
Ce qu’archec dessine depuis ce code : D

La plateforme relie le bus au connecteur de la carte (ctl.can0 -> can_bus). archec gen --target embassy pilote alors le contrôleur CAN sur les broches de la carte, et non sur ses broches par défaut. Ici, c’est FDCAN1 sur PA11/PA12. Sur la nRF52840 DK, ce serait un MCP2515 sur le connecteur Arduino (P1_15, P1_13, P1_14, CS P1_12, INT P1_03).

Ce qu’est une carte#

/// ST NUCLEO-G474RE: an STM32G474RE (Cortex-M4F with FDCAN) on a Nucleo-64.
component NucleoG474RE "NUCLEO-G474RE" {
  kind board
  description "One 170 MHz Cortex-M4F, 128 KB SRAM, three FDCAN controllers…"
  product { vendor "STMicroelectronics"; part-number "NUCLEO-G474RE"; url "https://…" }
  component mcu "STM32G474RE" {
    kind processor
    compute { cores 1; core-type "Cortex-M4F"; hal stm32; chip "stm32g474re"; freq 170MHz; ram 128KiB; os bare-metal }
  }
  inout can0:  can "FDCAN1, CAN FD (add a transceiver)" { pins { tx PA12; rx PA11 } }
  inout uart2: uart "USART2 (ST-LINK virtual COM)" { pins { tx PA2; rx PA3 } }
  in pwr:      power "5 V USB"
}
Diagramme : NUCLEO-G474RE
Ce qu’archec dessine depuis ce code : NUCLEO-G474RE
  • kind board est prédéfini, comme processor et bus.
  • product { vendor; part-number; url } est ce que vous commanderiez.
  • Un processeur dit pour quel code il est compilé :
    • bare metal : hal et chip, qui nomment la cible du crate Embassy ;
    • Linux : os, pour un crate hôte.
  • pins { role pin; … } sur un connecteur nomme les broches de la puce. Elles s’écrivent comme le crate HAL les écrit : GPIO4 (esp32), PA11 (stm32), PIN_16 (rp), P1_15 (nrf). Un rôle dit ce que fait une broche. Les rôles que lit archec sont :
    • tx et rx, pour un contrôleur CAN ;
    • sck, mosi, miso, cs et int, pour un contrôleur sur SPI (le MCP2515) ;
    • sda et scl.

Le dossier d’une carte est un dossier de composant. Il n’utilise que ce qu’il déclare, les types de port prédéfinis et la bibliothèque standard. Il fonctionne donc là où il est, comme en copie.

Ce qu’a une carte#

Chaque carte du store liste aussi tout ce qu’un projet peut y utiliser. C’est écrit à la fin du fichier de la carte, entre deux lignes de repère, par tools/board-resources (voir « D’où viennent les données » plus bas) :

component NucleoG474RE "NUCLEO-G474RE" {
  // … the board as above, with `flash 512KiB` in its compute …
  // the power it gives to what you wire to it
  out v3v3:   power "3.3 V (Arduino power header)" { voltage 3.3V }
  out v5:     power "5 V (Arduino power header)" { voltage 5V }
  // on the board itself
  out led:    gpio "User LD2, green" { pins { io PA5 } }
  in button:  gpio "User button (low when pressed)" { pins { io PC13 } }
  // buses ready to use, on the pins Zephyr's board puts them
  inout i2c1: i2c "I2C1 (Arduino D14, D15)" { pins { sda PB9; scl PB8 } }
  // how many of each peripheral
  peripherals {
    uart [LPUART1, UART4, UART5, USART1, USART2, USART3]
    i2c [I2C1, I2C2, I2C3, I2C4]
    adc { ADC1 { channels 14; bits 12 }; ADC2 { channels 16; bits 12 } }
    pwm { TIM1 4; TIM2 4; TIM15 2 }
  }
  // what each pin can be, besides a GPIO
  pinout {
    PA9 [ADC5_IN2, I2C2_SCL, TIM1_CH2, TIM2_CH3, USART1_TX]
    PB8 [FDCAN1_RX, I2C1_SCL, TIM4_CH3, TIM16_CH1, TIM8_CH2, USART3_RX]
  }
}
Diagramme : NUCLEO-G474RE
Ce qu’archec dessine depuis ce code : NUCLEO-G474RE
  • flash (dans compute) est la mémoire de programme d’un microcontrôleur.
  • Les rails sont des ports out de type power. voltage est ce qu’ils donnent. current est le maximum qu’ils donnent, quand le guide de la carte le dit : le 3V3(OUT) du Pico donne 300 mA.
  • Les éléments de la carte sont aussi des ports : led, button, le rgb_led du C3. pins { io PA5 } est une seule ligne : une LED, un bouton, une sortie PWM, une entrée analogique.
  • Les bus prêts à l’emploi sont les bus UART, I²C et SPI qu’active le devicetree Zephyr de la carte, sur ses broches. Reliez-y un capteur : ctl.i2c1 -> env.i2c. Comme tout connecteur, ce sont des alternatives tant qu’un système ne les relie pas.
  • peripherals compte chaque sorte : uart, i2c, spi, can (leurs noms), adc (les canaux et les bits de chacun), dac et pwm (les canaux de chacun), usb, ethernet, radio.
    • any-pin [uart, i2c] : sur un ESP32 ou un nRF52840, ces périphériques vont sur n’importe quelle broche.
    • shared [[I2C0, SPI0]] : un périphérique sous deux noms (sur le nRF52840, I2C0 et SPI0 sont le même matériel).
  • pinout dit ce que chaque broche peut être, avec les noms que la puce donne à ses fonctions : USART1_TX, I2C1_SDA, SPI1_SCK, FDCAN1_TX, TIM1_CH2 (le canal d’un timer : du PWM), ADC1_IN5, DAC1_OUT1. Sur une carte Linux, les clés sont les ports des broches du connecteur, et les noms sont ceux de Linux : pin3 [GPIO2, I2C1_SDA] (/dev/i2c-1).
  • io-level 3.3V est le niveau des broches de la carte. Un port qui donne son propre pins { level … } le garde.

archec board show <board> affiche tout cela : les périphériques, les rails, et chaque broche avec ce qu’elle peut être et les connecteurs de la carte qui la prennent.

D’où viennent les données#

node tools/board-resources/fetch.mjs      # once: Zephyr's files, at pinned revisions
node tools/board-resources/generate.mjs   # writes the blocks; --check says what would change
  • Cartes à microcontrôleur (les Nucleo, les Pico, le nRF52840 DK, les cartes ESP32) : du devicetree de Zephyr v4.2.0 (Apache-2.0) et de hal_stm32 à la révision que fixe Zephyr. Les fonctions des broches STM32 sont les tables pinctrl de hal_stm32 pour le boîtier exact de la carte. Celles du RP2040 sont l’en-tête pinctrl de Zephyr. Les tailles de flash, les résolutions des ADC, les LED, les boutons, les bus et les noms du connecteur Arduino sont le devicetree de la carte.
  • Ce que le devicetree ne dit pas vient des datasheets des puces et des guides d’utilisation des cartes, dans tools/board-resources/chips.mjs : les broches analogiques de l’ESP32 et du nRF52840 (leurs autres périphériques vont sur n’importe quelle broche), les broches que sort chaque carte, les rails.
  • Cartes Linux : le Raspberry Pi 4 et 5, la Jetson Nano, la BeagleBone Black et la PocketBeagle ont les broches I²C, SPI, UART, PWM et analogiques de leur connecteur, d’après leur documentation. Les autres cartes Linux n’ont que leurs broches PWM (d’après leur pilote Go, adapté de Gobot), leurs rails et leur niveau.
  • Une valeur incertaine est laissée de côté : une broche fausse est pire qu’une broche manquante. Chaque table de chips.mjs dit d’où elle vient.

Les vérifications#

archec check, archec pins et l’éditeur comparent un système avec ses cartes. Chaque vérification a son archec explain <code> :

  • pin-function : une broche ne peut pas être ce que le port en fait. De l’I²C SDA sur une broche sans SDA, un servo (un port étiqueté "PWM") sur une broche sans timer, un potentiomètre (un port analog) sur une broche sans ADC. Le message liste les broches qui le peuvent.
  • pin-conflict : une broche utilisée deux fois. En plus de deux ports sur une broche : le port d’une broche du connecteur Linux et le bus sur cette broche (pi.pin3 et pi.i2c1), et un port d’une broche relié à deux parts.
  • board-peripheral :
    • deux ports sur un même périphérique : deux ports I²C tous deux sur I2C1, deux servos sur pin12 et pin32 d’un Raspberry Pi 4 (les deux sont PWM0 : ils bougeraient ensemble) ;
    • plus d’une sorte que n’en a la carte : un 2e I²C sur un ESP32-C3, une 3e sortie PWM sur une carte qui en a 2.
  • board-supply : une part alimentée par un rail dont elle ne prend pas la tension. Le port d’alimentation de la part dit ce qu’elle prend : in pwr: power { voltage 1.71V..3.6V }. Le correctif rapide la relie au rail de la carte qui convient.
  • board-current : les parts sur un rail tirent plus qu’il ne donne. Le port d’alimentation de chaque part dit ce qu’elle tire (current 15mA), sinon son power est divisé par la tension du rail.
  • pin-level : l’io-level de la carte est le niveau de ses ports. Un écho en 5 V (pins { level 5V }, celui du HC-SR04) sur une broche en 3,3 V est un avertissement.

Certains appareils du store disent ce qu’ils prennent : le BME280, les BMP180/280, le MPU-6050, l’ADXL345, le HMC5883L, le BH1750, le SHT3x, les ADS1x15, le PCA9685, le MCP3008, le DS18B20 et le HC-SR04. Les valeurs sont celles de la puce, d’après sa datasheet. Un module qui porte un régulateur peut prendre du 5 V : donnez alors à la part votre propre voltage.

Images#

archec board picture nucleo-g474re -o nucleo.svg      # one board
archec board picture main.arche -o hardware.svg       # each system that has boards

archec dessine l’image d’une carte à partir de son modèle. L’image montre :

  • le contour et la couleur de la carte ;
  • son processeur ;
  • ses barrettes de broches et ses connecteurs ;
  • un numéro sur chaque port, avec une légende qui dit ce qu’est le port et quelles broches il utilise.

Sur un Raspberry Pi, les numéros désignent les broches du connecteur où se trouve un bus (I2C1 sur les broches 3 et 5).

Pour un modèle, archec board picture dessine les cartes, les appareils et les bus de chaque système, avec les fils que tracent ses liens : une carte sur un bus CAN, un capteur sur l’I2C du Pi. --system choisit un seul système. Les schémas Hardware du playground sont ces images. Voyez par exemple examples/can-bench : un Raspberry Pi, une Nucleo et un ESP32 sur un même bus CAN, plus un capteur BME280.

Ce sont des dessins, pas des photos. archec sait à quoi ressemble chaque carte du store : sa taille, sa couleur, la place de ses connecteurs. Une carte à vous est dessinée au jugé : une petite carte sombre avec des barrettes, ou un ordinateur monocarte si elle tourne sous Linux.

Plan de brochage#

archec pins main.arche

Pour chaque carte, la commande affiche chaque broche : le port et le rôle qu’elle y tient, l’endroit où le port est relié, et si la part a écrit la broche elle-même. Juste après archec board add, rien n’est encore relié :

RoverHw.ctl — NUCLEO-G474RE · STM32G474RE (stm32)
  PA2   uart2 tx  (not linked)
  PA3   uart2 rx  (not linked)
  PA11  can0 rx   (not linked)
  PA12  can0 tx   (not linked)

Dans un modèle avec des liens, et avec une part qui fixe sa propre broche (part ctl: NucleoG474RE { inout can0 { pins { tx PA2 } } }, à la place de la PA12 de la carte), on obtient ceci :

Hw.ctl — NUCLEO-G474RE · STM32G474RE (stm32)
  PA2   can0 tx   -> can_bus  (the part's)
  PA2   uart2 tx  -> esp.uart0
  PA3   uart2 rx  -> esp.uart0
  PA11  can0 rx   -> can_bus

Après les broches viennent les avertissements du plan de brochage. archec check et l’éditeur les donnent aussi :

  • pin-conflict : une broche est utilisée par deux ports d’une carte, ou par deux rôles d’un même port.
    • Seuls comptent les ports que le système relie, ou dont une part écrit les broches. D’ici là, les connecteurs d’une carte sont des alternatives : le SPI0 du Pico et son MCP2515 partagent des broches.
    • Un composant qui extends une carte est prévenu quand une broche qu’il écrit appartient à l’un des connecteurs de sa carte.
  • pin-function : la puce ne peut pas utiliser la broche de cette façon.
    • Sur le RP2040 : UART TX uniquement sur les GPIO 0, 4, 8…, et RX sur 1, 5, 9… ; I2C SDA sur les broches paires ; SPI SCK, MOSI et MISO sur leurs propres broches. Les broches d’un port doivent être sur un seul périphérique : TX sur UART1 avec RX sur UART0 est une erreur.
    • Sur l’ESP32 : les GPIO34–39 sont des entrées seulement. Les broches reliées à la flash du module sont prises : GPIO6–11, 12–17 sur le C3, 26–32 sur le S3.
    • Sur chaque carte du store, d’après son pinout (« Ce qu’a une carte »).
  • pin-pair : les deux extrémités d’un lien ne s’accordent pas.
    • tx doit rencontrer le rx de l’autre extrémité. SCK, MOSI, MISO, SDA et SCL rencontrent le même rôle.
    • Un contrôleur CAN sur un bus a besoin de tx et de rx.
  • pin-level : un lien entre des ports dont les niveaux de tension diffèrent. Par exemple, pins { tx PIN_0; rx PIN_1; level 3.3V } d’un côté et level 5V de l’autre. level n’est pas une broche. L’io-level d’une carte est le niveau de ses ports. Les cartes Nucleo n’en donnent pas : la plupart des broches STM32 prennent du 5 V (broches FT), et archec ne sait pas lesquelles.

Devicetree Zephyr#

archec gen main.arche --target devicetree -o generated

Cette commande écrit un overlay devicetree pour chaque binaire du déploiement qui tourne sur le microcontrôleur d’une carte. L’overlay porte le nom que west (l’outil de build de Zephyr) donne à la carte, par exemple generated/devicetree/steer_fw/boards/nucleo_g474re.overlay. Copiez son dossier boards/ dans l’application Zephyr.

L’overlay a un nœud pour chaque connecteur CAN, UART, I2C et SPI de la carte que la plateforme relie (steer_mcu.can0 -> chassis_can) :

/ {
	aliases {
		arche-chassis-can = &fdcan1;
	};
	chosen {
		zephyr,canbus = &fdcan1;
	};
};

/* steer_mcu.can0 — FDCAN1, CAN FD (add a transceiver): tx PA12, rx PA11 */
&fdcan1 {
	status = "okay";
	pinctrl-0 = <&fdcan1_tx_pa12 &fdcan1_rx_pa11>;
	pinctrl-names = "default";
	bitrate = <500000>;
};
  • Broches. Ce sont les broches du port : les pins propres à une part l’emportent sur celles de la carte. Chacune est nommée comme son HAL la nomme : nœuds pinctrl de hal_stm32, groupes NRF_PSEL(…), macros pinmux du RP2040 et de l’ESP32.
  • Périphérique. C’est celui que donne le nom du connecteur (USART2, FDCAN1, TWAI0). Sur le RP2040, c’est celui auquel appartiennent ses broches.
  • Vitesse. C’est le bitrate du lien, sinon celui du bus :
    • bitrate pour le CAN (1 Mbit/s au plus ; un bus CAN FD ajoute bitrate-data) ;
    • current-speed pour un UART ;
    • clock-frequency pour l’I2C.
  • CAN sur SPI. Le MCP2515 de la nRF52840 DK et du Pico est un nœud mcp2515 sous le SPI, avec ses CS et INT en GPIO.
  • Appareils I2C. Un appareil relié à la carte est un nœud à son address. C’est à vous d’ajouter son compatible.
  • Alias. Chaque bus a un alias, arche-<bus>. Sous Zephyr (__ZEPHYR__), le drivers.c de archec gen --target c envoie les trames d’un bus CAN ou UART sur DEVICE_DT_GET(DT_ALIAS(arche_<bus>)). Son main.c rend la main et laisse tourner les threads. La couche plateforme du C est arche_rt_posix.c, sur l’API POSIX de Zephyr (CONFIG_POSIX_API). Ce réglage se trouve dans le prj.conf, écrit une seule fois à côté de l’overlay.

Netlist KiCad#

archec kicad main.arche [CarHw] -o car.net

Cette commande écrit le câblage d’un système sous forme de netlist KiCad. Le système est celui que vous nommez, sinon la plateforme du déploiement. pcbnew lit la netlist (File → Import → Netlist), et eeschema peut la comparer à un schéma.

  • Symboles. Chaque part dont les ports portent des signaux est un symbole sans empreinte. Une carte est A1, A2… ; tout le reste est U1…. Ce qui se trouve sur une carte appartient au symbole de la carte.

  • Broches d’un symbole. Ce sont les signaux de ses ports, pris dans la première de ces sources qui existe :

    • les broches de la carte, par rôle (uart2.TX/PA2) ;
    • les wire du type de port (wire canh "CAN_H") ;
    • les signaux habituels d’un type prédéfini : CAN_H/CAN_L, TX/RX, SDA/SCL, SCK/MOSI/MISO/CS, V+/GND.

    Une part qui fixe ses propres broches (part pico: RaspberryPiPico { inout i2c0 { pins { … } } }) reçoit son propre symbole.

  • Nets. Un lien donne un net par signal.

    • TX et RX se croisent. Le net porte le nom de l’extrémité TX (pico_uart0_TX).
    • SDA va sur SDA.
    • Tout ce qui est relié à un composant kind bus partage ses nets (chassis_can_CAN_H). Deux extrémités TX/RX sur un même bus se croisent.
    • Toutes les masses GND forment un seul net.
  • CAN. Un connecteur CAN avec des broches de contrôleur (tx/rx, ou le SPI d’un MCP2515) place CAN_H/CAN_L côté bus. Une note indique que le transceiver se met entre les deux.

Votre propre collection#

archec board new carrier-v2 --in ~/arche-boards --from nucleo-g474re --name "Carrier v2"
archec board check ~/arche-boards
archec board extract main.arche RoverHw.ctl --in ~/arche-boards   # a board the model defines

Une collection est une bibliothèque : un dossier avec un library.arche (créé par board new) et des boards/<id>/<id>.arche. Les images vont dans boards/<id>/assets/.

  • Un projet voit une collection grâce à libraries "<folder>". board add écrit cette ligne.
  • Tous les projets de la machine voient les collections listées dans ARCHE_BOARDS (une liste de chemins). Le réglage VS Code arche.boardCollections la définit pour l’éditeur et son serveur de langage.
  • arche.lock enregistre la version et l’empreinte de la collection, comme pour toute bibliothèque.

board check compile chaque carte seule et vérifie trois choses :

  • ses processeurs indiquent hal et chip, ou os ;
  • ses broches sont bien des broches de sa puce ;
  • son image est présente.

Dans VS Code#

La vue Store Shelves de la barre latérale Arche (anciennement la vue Boards) liste les cartes qu’utilise le modèle (cliquez sur l’une d’elles pour aller à la part), puis les six étagères. Son étagère Boards contient le store et vos collections, et son étagère Sensors and actuators les appareils, rangés par ce qu’ils font.

  • Sur une carte : Add to Model… (depuis la collection ou en copie, et dans quel système), Show Board Details (sa fiche, processeurs, connecteurs, broches), Open Definition, Duplicate to My Collection….
  • Sur une collection : New Board…, Check Board Collection (résultats dans la vue Problems), Reveal Collection Folder.
  • Sur un appareil : Add Device to Model… (son nom, et sur quel bus des cartes du modèle il va), Show Card.
  • Dans la barre de titre : ajouter, filtrer toutes les étagères (par nom, ce que fait la pièce, fabricant, puce, HAL, cœur), rafraîchir, New Board…, Add Board Collection….
  • Sur un composant de la vue Model : Save as Board in My Collection….
  • Glissez une carte depuis la vue dans un éditeur .arche. archec écrit part esp32_c3_devkitm_1: Esp32C3DevKitM1 là où vous la déposez, avec le nom de la part sélectionné pour que vous puissiez le changer.
    • Déposée hors de tout bloc, la part va dans un nouveau system <Project>Hw "Hardware".
    • L’include de la carte et le uses du projet sont écrits comme les écrit board add.
    • Déposée dans un autre type d’éditeur, elle donne la ligne part en texte.

L’éditeur connaît aussi les cartes.

  • Complétion.

    • Après part x: (et extends), il propose les cartes du store et de vos collections, avec le fabricant et la référence. Si vous en choisissez une que le modèle n’inclut pas encore, il écrit aussi son include. Dans le fichier qui contient le bloc project, il écrit uses arche-hw-store "^0.1", ou libraries et uses pour une de vos collections.
    • Dans pins { … } sur un port, il propose d’abord les rôles. Chacun vient avec la broche que la carte lui donne sur un port de ce type (tx PA12).
    • Après un rôle, il propose les broches de la carte avec ce qui y est relié (PA11 — can0 rx, FDCAN1). La broche de même rôle et de même type de port vient en premier.
    • Dans une part d’une carte (part ctl: NucleoG474RE { … }, ou un composant qui en extends une), il propose les connecteurs de la carte avec leur type, leur nom et leurs broches. En choisir un l’écrit avec ses broches, que vous pouvez ensuite modifier : inout uart2 { pins { tx PA2; rx PA3 } }.
  • Survol.

    • Sur le nom d’une carte, ou sur une part de carte : son fabricant, sa référence et son URL ; ses processeurs (cœur, horloge, RAM, hal et chip) ; ses connecteurs avec leurs broches ; et la collection d’où elle vient.
    • Sur une broche dans pins { … } : la puce qui la porte, et ce que la carte y relie (PA11 — can0 rx, FDCAN1).
    • Sur un rôle : à quoi il sert.
  • Avertissements (board-pin, aussi dans archec check). Un nom de broche que la puce de la carte n’utilise pas déclenche un avertissement. Cela vaut sur une carte, sur une part de carte et sur un composant qui en étend une. Le correctif rapide propose la broche la plus proche, et les broches qu’utilisent les connecteurs de la carte :

    NUCLEO-G474RE has no pin 'PB99': its STM32G474RE (stm32) names them like PA11. Did you mean 'PB9'?

    Un rôle qu’archec ne lit pas (tz) déclenche lui aussi un avertissement.

Le store#

Carte Processeur Compile pour CAN
ESP32-C3-DevKitM-1 ESP32-C3, RISC-V hal esp32, esp32c3 TWAI sur GPIO2/GPIO3
ESP32-S3-DevKitC-1 ESP32-S3, 2× Xtensa LX7 hal esp32, esp32s3 TWAI sur GPIO4/GPIO5
ESP32-DevKitC ESP32, 2× Xtensa LX6 hal esp32, esp32 TWAI sur GPIO21/GPIO22
NUCLEO-G474RE STM32G474RE, Cortex-M4F hal stm32, stm32g474re FDCAN1 sur PA12/PA11
NUCLEO-F446RE STM32F446RE, Cortex-M4F hal stm32, stm32f446re CAN1 sur PA12/PA11
NUCLEO-H743ZI2 STM32H743ZI, Cortex-M7 hal stm32, stm32h743zi FDCAN1 sur PD1/PD0
Raspberry Pi Pico, Pico W RP2040, 2× Cortex-M0+ hal rp, rp2040 MCP2515 sur SPI0
nRF52840 DK nRF52840, Cortex-M4F hal nrf, nrf52840 MCP2515 sur le connecteur Arduino
Raspberry Pi 4, Pi 5 BCM2711 / BCM2712 Linux (std) un HAT MCP2515, SocketCAN
Jetson Orin Nano Developer Kit 6× Cortex-A78AE Linux (std) —
Kria KR260 K26 : 4× Cortex-A53, 2× Cortex-R5F, PL Linux (apu), FreeRTOS (rpu) —
Raspberry Pi 4 et 5 (pilote Go) BCM2711 / BCM2712 Linux (Go : raspi.NewAdaptor) —
Jetson Nano Developer Kit Tegra X1, 4× Cortex-A57 Linux (Go : jetson.NewAdaptor) —
BeagleBone Black, PocketBeagle AM3358, Cortex-A8 Linux (Go : beaglebone, pocketbeagle) —
ASUS Tinker Board, Tinker Board 2 RK3288 / RK3399 Linux (Go) —
FriendlyELEC NanoPi NEO, NanoPC-T6 Allwinner H3 / RK3588 Linux (Go) —
Orange Pi 5 Pro RK3588S Linux (Go) —
PINE64 ROCK64, Radxa ROCK Pi 4, Radxa Zero RK3328 / RK3399 / S905Y2 Linux (Go) —

Aucune de ces cartes n’a de transceiver CAN. Câblez-en un entre les broches et le bus.

Dans Renode#

Renode (1.17) est un émulateur de microcontrôleurs. archec gen main.arche --target renode --deployment D y fait tourner les microcontrôleurs d’un déploiement, sans les cartes. La commande crée :

  • une machine pour chaque processeur qui a un binaire, avec la description que Renode donne de sa puce, et l’ELF du binaire chargé ;
  • un CANHub pour chaque bus CAN de la plateforme ;
  • un UARTHub pour chaque lien UART de la plateforme ;
  • les appareils de la carte que Renode modélise, là où le firmware les pilote : un BME280 à son adresse I²C, un relais ou une LED sur sa broche ;
  • l’UART vers l’ordinateur (le port COM virtuel du ST-LINK) enregistré dans <binary>.trace, que lisent archec timing et archec replay.

archec board show indique, pour chaque processeur, sous quelle forme Renode l’exécute (Renode: …).

Puce (cartes) Plateforme Renode CAN Remarques
stm32h743zi (NUCLEO-H743ZI2) platforms/cpus/stm32h743.repl FDCAN1 (MCAN) le RCC de Renode ne garde pas FDCANSEL : le .resc lui fait relire PLL1_Q, l’horloge que choisit le main.rs généré
stm32f446re (NUCLEO-F446RE) platforms/cpus/stm32f4.repl CAN1 (bxCAN) un STM32F407 : plus de flash et de RAM, le même CAN et les mêmes USART aux mêmes adresses. Ses timers sont réglés à 16 MHz, l’horloge que garde le firmware généré
nrf52840 (nRF52840 DK) platforms/cpus/nrf52840.repl — Renode n’a pas de MCP2515 : le CAN de la carte n’est pas sur le bus
stm32g474re (NUCLEO-G474RE) — pas de STM32G4 dans Renode
rp2040 (Pico, Pico W) — pas de RP2040 dans Renode
esp32, esp32c3, esp32s3 — aucune puce Espressif dans Renode
Processeurs Linux (Pi, Jetson, APU de la Kria…) — non émulés : leur binaire tourne sur un hôte ; le .resc contient pour lui un pont SocketCAN, en commentaire (hôtes Linux)

Le port CAN ou UART d’une carte est le périphérique Renode que nomme son texte ("FDCAN1, CAN FD…", "USART2 (ST-LINK virtual COM)"). Un port CAN qui n’en nomme aucun est le premier contrôleur, celui que pilote le firmware généré. Pour un UART qui n’en nomme aucun, archec le signale et ne devine pas.

archec gen main.arche --target embassy --deployment Bench -o out
archec gen main.arche --target renode --deployment Bench -o out
(cd out/embassy/brake_fw && cargo build --release)
renode out/renode/Bench/Bench.resc              # the machines, running
renode-test out/renode/Bench/Bench.robot        # the checks

Les chemins des ELF sont des variables en tête de machines.resc ($brake_fw). Changez-les pour un firmware compilé ailleurs, ou écrit en C.

La suite Robot (Bench.robot) vérifie ceci :

  • chaque binaire qui communique sur un bus a démarré son contrôleur CAN ;
  • pour chaque cas de test, ce que Renode peut voir :
    • un send venant d’une part que Renode n’exécute pas est mis sur le bus, encodé selon la disposition du message dans le codec. Le firmware doit le lire.
    • un expect sent("MSG") compte les trames envoyées par les machines avec l’identifiant CAN de ce message ;
    • do sensor.temperature = 31 règle la mesure de l’appareil dans Renode, et expect relay.closed lit la broche du relais.

examples/car-bench est le firmware des actionneurs de la voiture, exécuté de cette façon. examples/greenhouse fait tourner une NUCLEO-F446RE avec un BME280 et un relais : ./board.sh --renode le compile, l’exécute dans Renode et le mesure (voir le tutoriel de la carte).

Appareils et pilotes#

Le store contient aussi des appareils : capteurs, écrans (plus bas), moteurs, LED, convertisseurs analogique-numérique… Il y en a 87, chacun dans son dossier sous devices/. Les cartes Linux ci-dessus ont aussi leur pilote en Go, sous boards/<board>/drivers/go/.

Les deux viennent de Gobot v2.6.0 (Apache-2.0, voir LICENSE-gobot et NOTICE). Ils sont adaptés pour n’importer rien de Gobot.

include "arche-hw-store/sensors.arche"

/// BME280 temperature, pressure and humidity sensor.
component Bme280 "BME280" {
  kind device
  product { vendor "Bosch Sensortec"; part-number "BME280"; driver "i2c.NewBME280Driver" }
  inout i2c:             i2c "I²C" { address 0x77 }
  in pwr:                power "supply (1.71V to 3.6V)" { voltage 1.71V..3.6V }
  in temperature_sensor: provides TemperatureSensor "Temperature" { noise 1°C; resolution 0.01°C }
  in humidity_sensor:    provides HumiditySensor "Humidity" { noise 3%RH; resolution 0.008%RH }
  fn temperature -> Temperature "Temperature (°C)"
  fn humidity -> Humidity "Humidity (%RH)"
}
Diagramme : BME280
Ce qu’archec dessine depuis ce code : BME280

La plupart des appareils disent aussi ce qu’ils font : un port qui provides une interface de sensors.arche (voir Capteurs par ce qu’ils font), avec leur précision et leur alimentation.

  • driver nomme le constructeur Go de l’appareil dans devices/go/<family>/. Les familles sont i2c, spi, gpio, aio et onewire. Sur une carte, driver nomme son adaptateur.
  • address est l’adresse I²C de l’appareil. Deux appareils à la même adresse sur un même bus sont une erreur (bus-address). Une part peut en déplacer un : part env2: Bme280 { inout i2c { address 0x76 } }.
  • Une carte Linux a un port pour chaque broche de connecteur que connaît son pilote (pin11, ou p8_07 sur une BeagleBone). Vous reliez donc la broche d’un appareil à la broche de la carte :
system Bench {
  part pi:  RaspberryPi4
  part env: Bme280
  part led: GpioLed
  pi.i2c1 -> env.i2c
  pi.pin11 -> led.pin
}
Diagramme : Bench
Ce qu’archec dessine depuis ce code : Bench

Le code Go tient dans un seul module, archehw (lib/arche-hw-store/go.mod) :

  • le runtime, dans runtime/go/ : les interfaces de Gobot sous le nom archert, et l’accès Linux à l’I²C, au SPI, aux GPIO, au PWM, à l’analogique et au 1-Wire ;
  • les pilotes des appareils, dans devices/go/ ;
  • les pilotes des cartes, à côté de chaque carte.

Il ne dépend de rien en dehors de Go. Les tests de Gobot sont fournis avec : lancez go test ./... dans lib/arche-hw-store (npm test les lance aussi).

Deux outils le gardent aligné sur Gobot :

go run ./tools/gobot-port <gobot checkout> lib/arche-hw-store "v2.6.0 (798be8c)"   # the Go code
go run ./tools/gobot-catalog lib/arche-hw-store                                     # devices/ and the boards' .arche

Le code de Gobot ne contient ni les fabricants, ni les références, ni les unités, ni les processeurs des cartes. Ils se trouvent dans tools/gobot-catalog/known.go et known_boards.go. Ce que fait chaque appareil, sa précision et son alimentation se trouvent dans tools/gobot-catalog/sensors.go.

Capteurs par ce qu’ils font#

Un modèle dit ce dont il a besoin, un capteur de température, et seulement ensuite quelle part le fournit. lib/arche-hw-store/sensors.arche a une interface pour chaque chose que fait un capteur ou un actionneur. Ses opérations sont typées avec les grandeurs d’arche-types :

Mesure Interface Donne
Température TemperatureSensor temperature() -> Temperature (°C)
Humidité HumiditySensor humidity() -> Humidity (%RH)
Pression de l’air PressureSensor pressure() -> Pressure (Pa)
Accélération, rotation Accelerometer, Gyroscope, Imu (les deux) acceleration() -> Vec3 (m/s²), angular_velocity() -> Vec3 (rad/s)
Cap Magnetometer heading() -> Angle (rad)
Distance DistanceSensor distance() -> Distance (m)
Lumière LightSensor illuminance() -> Illuminance (lx)
Qualité de l’air AirQualitySensor eco2() -> Co2 (ppm), tvoc() -> Tvoc (ppb)
Courant et tension CurrentSensor current() -> Current, voltage() -> Voltage
Position GpsReceiver fix() -> GpsFix
Angle de rotation Encoder angle() -> Angle
Un appui, un mouvement Button, MotionSensor pressed() -> bool, motion() -> bool
Fait Interface Prend
De la lumière Led, RgbLed on(), off(), toggle(), state() ; set_rgb(r, g, b)
Du son Buzzer on(), off(), tone(frequency, duration)
Commuter une charge Relay on(), off(), toggle(), state()
Bouger Servo, DcMotor, Stepper move(angle) ; forward(speed), backward(speed), off() ; move(steps)
Afficher du texte Display clear(), write(text)

Un appareil en fournit une par un port qui porte son nom : le BME280 a temperature_sensor, humidity_sensor et pressure_sensor. Le contrôleur dit ce dont il a besoin avec requires, et l’appelle dans son corps :

project Greenhouse {
  uses arche-hw-store "^0.1"
}
include "arche-hw-store/devices/bme280/bme280.arche"
include "arche-hw-store/devices/relay/relay.arche"

component Thermostat "Thermostat" {
  out air: requires TemperatureSensor
  out fan: requires Relay
  fn main ```arche
    while true {
      if air.temperature() > 28.0 {
        fan.on()
      } else {
        fan.off()
      }
      wait 1s
    }
  ```
}

system Greenhouse {
  part air: Bme280
  part fan: GpioRelay
  part ctl: Thermostat
  ctl.air -> air.temperature_sensor
  ctl.fan -> fan.relay
}
Diagramme : Greenhouse
Ce qu’archec dessine depuis ce code : Greenhouse
Essayer

Pour utiliser plutôt un DS18B20, changez part air: Bme280 en part air: Ds18b20, et son include. Le lien, le corps, la simulation et les tests restent tels quels.

55 des 87 appareils sont rangés sous ces interfaces. Les autres restent rangés par leur bus :

  • les ADC (ADS1x15, MCP3xxx, PCF8591, YL-40) et les extensions de ports (MCP23017, PCA9501, PCA953x) ;
  • les HAT PWM et moteurs (PCA9685, Adafruit 2327 et 2348) ;
  • les lecteurs RFID (MFRC522), les pilotes de matrices de LED (MAX7219, AiP1640) et le ruban APA102 ;
  • le pilote haptique (DRV2605L), l’horloge (PCF8583), le Nunchuck de la Wii et le GrovePi ;
  • les pilotes génériques et analogiques, et les capteurs de son et de vibration.

Les pilotes génériques de Gobot portaient les noms des interfaces. Ils s’appellent maintenant GpioLed, GpioButton, GpioRelay, GpioBuzzer, GpioRgbLed, HobbyServo, GpioStepper et Thermistor. Leurs dossiers (led, button…) n’ont pas changé.

Précision et alimentation#

Le port d’un appareil dit comment il mesure : noise (la précision de la datasheet, tirée comme le σ d’une gaussienne dans le simulateur) et resolution (le pas auquel une mesure est arrondie). Son port pwr dit son alimentation (voltage 1.71V..3.6V, et le maximum qu’il tire quand la datasheet le dit). Pour un capteur de distance, son enregistrement hardware donne sa plage (hardware {range: {min: 0.02m, max: 4m}}). Ces valeurs viennent des datasheets, seulement là où nous en sommes sûrs. Le reste est laissé de côté.

Une fn que le pilote Go donne sous une autre forme garde une ligne au-dessus d’elle : // Go: Distance() gives cm. Dans archec gen --target go, lisez le pilote dans user.go et réglez les variables de la part. Les opérations sont celles du modèle.

Dans le simulateur#

Un appareil sans code propre fait ce que fait son interface, dans archec sim, sur sa page et dans le playground (src/sensorsim.ts, écrit une fois par interface) :

Interface Dans le simulateur
TemperatureSensor ±0,5 °C autour de temperature (21 °C), sur 10 minutes, plus le bruit de l’appareil
HumiditySensor, PressureSensor, LightSensor, AirQualitySensor, CurrentSensor, Magnetometer de même, autour de 45 %RH, 101325 Pa, 300 lx, 600 ppm et 50 ppb, 0,25 A sous 5 V, 0,5 rad
DistanceSensor quelque chose qui va et vient de ±0,4 m autour de distance (1 m) toutes les 20 s, dans la plage de l’appareil
Accelerometer, Gyroscope la gravité sur z, immobile, avec le bruit sur chaque axe
GpsReceiver une position 3D autour de latitude et longitude, avec 2,5 m de bruit
Button, MotionSensor, Encoder pressed, motion, angle, tels que les règle un scénario
Led, Relay, Buzzer, RgbLed, Display leur état (lit, closed, text…), chaque changement dit dans la trace
Servo angle tourne vers target à 60° en 0,1 s, dans 0..π
DcMotor speed suit sa commande avec un retard de 0,2 s
Stepper step avance vers target à rpm (60), 200 pas par tour

Les noms entre accents graves sont des variables que la part reçoit dans le simulateur. Un cas de test change le monde à travers elles, sans plant :

test-plan TP "The greenhouse" {
  case TC-WARM "The air warms: the fan runs" {
    at 2s do air.temperature = 30
    at 3.5s expect fan.closed
  }
  case TC-DOOR "The door button" {
    at 2s do door.pressed = True
    at 3s expect ctl.held
  }
}
archec sim main.arche --test

lib/arche-hw-store/tests/greenhouse.arche est un tel modèle. Ses cas comptent dans les fiches des appareils (archec shelf sensors bme280 : "2 tests in the simulator").

15 des appareils ont aussi un pilote Rust, pour les cartes à microcontrôleur (archec gen --target embassy) : rust-driver dans leur product nomme le crate sur lequel il repose. Voir drivers.md.

Écrans#

Chaque écran du store dit ce qu’une ui affichée dessus peut utiliser. Son enregistrement hardware {display: {…}} donne la taille en pixels, la densité, l’entrée et le contrôleur.

Appareil Écran Entrée Bus
ili9341 2,8" 320×240, 143 dpi, RGB565 tactile (XPT2046) SPI, DC, reset, rétroéclairage, IRQ tactile
st7789 2,0" 240×320, 200 dpi touches SPI, DC, reset, rétroéclairage
st7789-240x240 1,3" 240×240, 261 dpi touches SPI, DC, reset, rétroéclairage
ssd1306, spi-ssd1306 0,96" 128×64 mono, 149 dpi touches I²C 0x3C, SPI (pilotes de Gobot)
hdmi-display 1920×1080, 92 dpi pointeur HDMI, USB
archec device list --displays
archec device add main.arche ili9341 --into RoverHw

Un composant qui a une ui { } sans display à lui prend la part écran qui se trouve à côté de lui. archec la cherche d’abord dans un système dont le composant est une part, puis dans la plateforme d’un déploiement de ce système. archec ui indique alors « from the hardware ». L’input propre à l’ui l’emporte sur celui de l’écran.

Un écran à vous est un composant avec le même enregistrement :

component MyPanel "7\" panel" {
  kind device
  hardware {display: {width: 1024, height: 600, dpi: 170, input: "touch"}}
  in hdmi: hdmi
}
Diagramme : 7" panel
Ce qu’archec dessine depuis ce code : 7" panel

archec gen --target ui-lvgl et ui-slint écrivent l’ui pour cet écran (voir ui). L’enregistrement du SSD1306 se trouve dans tools/gobot-catalog/known.go : l’outil de catalogue le réécrit donc.

Limites#

  • Aucune carte du store n’a de transceiver CAN. Câblez-en un entre les broches et le bus.
  • pin-function connaît ce que dit le pinout des cartes du store. Sur les cartes Linux autres que les Raspberry Pi, la Jetson Nano et les BeagleBone, il ne connaît que les broches PWM.
  • board-current compte les parts reliées directement à un rail, et seulement les rails dont le current est connu : le 3V3(OUT) des Pico et le 3,3 V de la BeagleBone Black. Les rails des Nucleo, des ESP32, des nRF et de la plupart des cartes Linux ne le disent pas encore.
  • Aucune carte du store n’a de centrale inertielle ou de capteur intégré qu’archec liste : aucune des 24 n’en a un relié à une broche.
  • Les broches STM32 qui prennent du 5 V (FT) ne sont pas signalées : les Nucleo n’ont pas d’io-level.
  • La vérification board-pin sait comment chaque HAL nomme ses broches, mais pas le brochage de chaque puce. PK15 passe sur une puce qui n’a pas de port K.
  • Une carte à vous est dessinée au jugé, pas d’après son aspect réel.
  • Les overlays devicetree sont vérifiés avec dtc dans les tests, face à des substituts des nœuds propres à la carte. Ils n’ont pas été compilés avec west dans un arbre Zephyr.
  • archec kicad vérifie sa sortie en la relisant dans les tests : les broches de chaque net existent, et aucune broche n’est sur deux nets. KiCad lui-même (kicad-cli) n’a pas été lancé dessus.
  • Renode n’a ni STM32G4, ni RP2040, ni puce Espressif, ni MCP2515. Les processeurs Linux ne sont pas émulés.
  • Dans Renode, l’état d’une part à l’intérieur du firmware n’est pas vérifié.
  • L’adaptateur Go du Raspberry Pi a été écrit avant le Pi 5 et n’a pas été essayé dessus.
  • Aucun appareil du store n’a tourné sur du vrai matériel. Ses interfaces et sa version simulée disent ce qu’il fait, pas que son pilote le fait.
  • Un appel à un appareil à travers une interface (air.temperature()) tourne dans le simulateur. Le code généré (Go, Rust, C) ne le relie pas encore au pilote de l’appareil : lisez vous-même le pilote (user.go) et donnez la valeur à la part.
  • L’INA3221 ne lit que son canal 1 à travers CurrentSensor. Un récepteur GPS, un moniteur d’alimentation et un codeur rotatif ont leurs interfaces, mais le store n’a pas encore de tel appareil (le capteur d’angle rotatif Grove est un potentiomètre).
  • L’état simulé d’un appareil bouge quand on l’interroge : l’angle d’un servo est calculé à chaque appel, pas entre deux.

Les cartes du store#

Chaque carte livrée avec archec, dessinée depuis son modèle par archec board picture : son processeur, ses connecteurs et un numéro sur chaque port, avec ce qu’il est et ses broches.