docs: configurateur du firmware triphasé

.github/workflows/documentation.yaml

@@ -3,16 +3,14 @@ name: Sphinx
 
 on:
   push:
+    # the 3-phase submodule is not ignored: it brings the configurator (/configurateur/)
     paths-ignore:
-      - '.gitmodules'
       - '1-phase/**'
-      - '3-phase/**'
       - 'hardware/**'
   pull_request:
+    # the 3-phase submodule is not ignored: it brings the configurator (/configurateur/)
     paths-ignore:
-      - '.gitmodules'
       - '1-phase/**'
-      - '3-phase/**'
       - 'hardware/**'
   workflow_dispatch: {}
 

content/common/moniteur-serie.inc.rst

@@ -37,13 +37,13 @@ Si Aucun Message n’Apparaît
 Adresses des Sondes de Température
 """""""""""""""""""""""""""""""""""
 
-Si vous avez activé `TEMP_ENABLED`, le moniteur série affichera les adresses détectées :
+Le routeur ne recherche pas les sondes : il lit celles dont les adresses sont dans `config.h`. Pour relever les adresses, téléverser l’exemple de la bibliothèque *OneWire* (**Fichier → Exemples → OneWire → DS18x20_Temperature**), en changeant au besoin la broche dans `OneWire ds(…)`. Le moniteur série affiche alors l’adresse de chaque sonde branchée :
 
 .. code-block:: text
 
-   Temperature sensor 0 address: 28 AA BB CC DD EE FF 01
-   Temperature sensor 1 address: 28 AA BB CC DD EE FF 02
+   ROM = 28 AA BB CC DD EE FF 1
+   ROM = 28 AA BB CC DD EE FF 2
 
-Copier ces adresses dans `config.h` (section sondes de température).
+Copier ces adresses dans `config.h` (section sondes de température, chaque octet sous la forme `0x28`, `0xAA`…, un octet affiché `1` s’écrit `0x01`), puis téléverser à nouveau le firmware du routeur. Coller une étiquette avec l’adresse sur le câble de chaque sonde.
 
 

content/conf.py

@@ -184,4 +184,31 @@
 #     'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
 #     'printindex': r'\footnotesize\raggedright\printindex',
 # }
-# latex_show_urls = 'footnote'
+# latex_show_urls = 'footnote'
+
+# -- Configurator --------------------------------------------------------------
+# The firmware configurator of the 3-phase router lives with its firmware (3-phase/configurator,
+# tested there against the shipped config files) and is published here, at /configurateur/, from
+# the submodule: the online version always matches the documented firmware.
+import shutil
+
+configurator_dir = os.path.join(os.path.dirname(__file__), '..', '3-phase', 'configurator')
+
+
+def copy_configurator(app, exception):
+    if exception or app.builder.format != 'html':
+        return
+    if not os.path.isfile(os.path.join(configurator_dir, 'index.html')):
+        from sphinx.util import logging
+        logging.getLogger(__name__).warning('configurator not found in %s (submodule too old?)', configurator_dir)
+        return
+    target = os.path.join(app.outdir, 'configurateur')
+    os.makedirs(target, exist_ok=True)
+    for name in os.listdir(configurator_dir):
+        # the page only: the tests, presets and scripts stay in the firmware repository
+        if name.endswith(('.html', '.css', '.js')):
+            shutil.copy2(os.path.join(configurator_dir, name), target)
+
+
+def setup(app):
+    app.connect('build-finished', copy_configurator)

content/firmware/configurateur-triphase.rst

@@ -0,0 +1,82 @@
+.. _configurateur-triphase:
+
+=====================================
+Configurateur du firmware — Triphasé
+=====================================
+
+Le **configurateur** écrit pour vous les fichiers de configuration du firmware triphasé ``Mk2_3phase_RFdatalog_temp``, à partir d’une simple description de votre installation.
+
+👉 **Ouvrir le configurateur :** `https://fredm67.github.io/Mk2PVRouter/configurateur/ <https://fredm67.github.io/Mk2PVRouter/configurateur/>`_
+
+.. note::
+   Le configurateur ne concerne que le firmware **triphasé** (`PVRouter-3-phase <https://github.com/FredM67/PVRouter-3-phase>`_). Il correspond toujours à la version du firmware décrite dans cette documentation.
+
+.. contents:: Sommaire
+    :local:
+    :depth: 1
+
+Ce qu’il fait
+--------------
+
+Vous décrivez votre installation :
+
+- les **charges** (triacs), pilotées par le routeur ou par une unité distante par radio, et leurs priorités ;
+- les **relais** ;
+- les **entrées de commande** : arrêt du routage, arrêt du routeur, marche forcée, rotation des priorités ;
+- le **double tarif**, les **sondes de température** ;
+- le **module mk2Wifi** ;
+- la **radio** (RFM69) et les **unités distantes**, plus rarement utilisées.
+
+Il vérifie la cohérence de vos choix au fur et à mesure (broche utilisée deux fois, broche réservée à la radio, valeur hors limites…), avec les mêmes règles que le compilateur, et en plus ce que le compilateur ne peut pas voir, comme le câblage du module mk2Wifi.
+
+Il produit ensuite :
+
+- ``config.h``, ``config_system.h`` et ``config_rf.h`` pour le routeur ;
+- ``config.h`` et ``config_rf.h`` pour chaque unité distante (firmware ``RemoteLoadReceiver``) ;
+- avec le module mk2Wifi, le fichier **YAML ESPHome** correspondant, ainsi que la liste des ponts de soudure à fermer et la position du cavalier TEMP.
+
+Utilisation
+-----------
+
+#. Ouvrir le configurateur et décrire l’installation, section par section.
+#. Consulter les **Vérifications** à droite : corriger les erreurs (en rouge), sans quoi les fichiers ne sont pas générés ; les avertissements (en orange) sont à vérifier, mais ne bloquent rien.
+#. Avec Chrome ou Edge, cliquer sur **« Enregistrer dans le dossier du firmware… »** et choisir le dossier du firmware décompressé (celui qui contient ``Mk2_3phase_RFdatalog_temp`` et ``RemoteLoadReceiver``). Après confirmation, le configurateur y écrit tous les fichiers, à la place de ceux du même nom ; chaque unité distante reçoit son dossier ``RemoteLoadReceiver-unitN``.
+
+   Avant d’écrire, il sauvegarde ce qu’il remplace dans ``configurator-backup/<date_heure>``. Si vous passez à moins d’unités distantes, les dossiers des unités en trop y sont déplacés.
+
+   Avec un autre navigateur, cliquer sur **« Tout télécharger (ZIP) »**, puis copier les fichiers du routeur dans le dossier ``Mk2_3phase_RFdatalog_temp``, à la place des fichiers du même nom.
+#. **Garder votre** ``calibration.h`` : le configurateur ne le modifie jamais.
+#. Compiler et téléverser comme d’habitude (voir :ref:`logiciel-triphase`).
+
+.. tip::
+   Le bouton **« Annuler le dernier enregistrement… »** (Chrome ou Edge) remet le dossier du firmware dans l’état où il était avant le dernier enregistrement du configurateur : les fichiers remplacés et les dossiers supprimés reviennent, ceux qu’il a créés sont effacés.
+
+.. tip::
+   Le bouton **« Enregistrer les choix »** sauvegarde votre configuration dans un fichier JSON. Après une mise à jour du firmware, rechargez-le avec **« Charger des choix »** pour régénérer des fichiers à jour.
+
+.. tip::
+   Le configurateur fonctionne aussi hors ligne : ouvrir ``configurator/index.html`` depuis une copie du dépôt du firmware.
+
+Étalonnage
+----------
+
+Cochez **« Mode étalonnage »** : le configurateur ne montre plus que ce qui sert à l’étalonnage (les autres réglages sont conservés), et le ``config.h`` généré met le routeur en mode étalonnage, où il mesure sans rien commuter, avec la sortie série lisible (votre choix habituel revient en quittant le mode).
+
+#. Chargez votre ``calibration.h`` avec **« Charger mon calibration.h »**, ou saisissez les valeurs de ``f_powerCal`` (et de ``f_voltageCal``) avec lesquelles tourne le routeur.
+#. Avec une forte charge résistive sur une phase, relevez au même moment la puissance affichée par le routeur (``P1``, ``P2``, ``P3``) et celle d’un appareil de référence pincé sur le même câble, et saisissez-les. La tension (``V1``…) se corrige de la même façon.
+#. Le configurateur calcule la nouvelle valeur (valeur actuelle × appareil / routeur) et la signale si elle est douteuse : sonde à l’envers, charge trop faible, écart trop grand. Copiez les lignes données, ou enregistrez les fichiers : votre ``calibration.h`` est réécrit avec les nouvelles valeurs, le reste du fichier intact.
+#. Téléversez, puis cliquez sur **« Nouvelles valeurs téléversées : nouvelle mesure »** pour vérifier ou affiner.
+#. Une fois étalonné, décochez **« Mode étalonnage »** et téléversez à nouveau.
+
+Module mk2Wifi
+--------------
+
+Avec le module mk2Wifi, le configurateur règle la sortie série du routeur en mode **IoT** et génère un YAML ESPHome complet, cohérent avec le ``config.h`` :
+
+- un capteur pour chaque mesure réellement envoyée par le routeur (puissances, tensions, taux de routage de chaque charge, relais, températures, heures creuses…) ;
+- une commande pour chaque entrée du routeur reliée au module (D5 à D9).
+
+.. important::
+   Les commandes sont **sûres en cas de défaut** : le module ne tire une entrée du routeur à l’état bas que pour l’état non par défaut, et la relâche sinon. Un fil coupé, un pont de soudure ouvert ou un module qui redémarre laissent donc le routeur dans son état normal : routage actif, routeur en marche, pas de marche forcée. À chaque démarrage du module, toutes les commandes reviennent à cet état.
+
+Seuls les ponts de soudure listés par le configurateur doivent être fermés : les autres broches D5 à D9 peuvent être utilisées par le routeur lui-même (charges, relais…).

content/firmware/etalonnage-triphase.rst

@@ -167,6 +167,9 @@ Appareils de mesure possibles
      - :math:`P_{\text{mesuré}}` est la puissance mesurée par l'appareil.
      - :math:`P_{routeur}` est la puissance affichée par le routeur.
 
+   .. tip::
+      Le :ref:`configurateur <configurateur-triphase>` fait ce calcul pour vous : cochez « Mode étalonnage », chargez votre ``calibration.h`` (ou saisissez ses valeurs) et entrez, pour chaque phase, la puissance du routeur et celle de l’appareil. Il donne les nouvelles valeurs et réécrit votre ``calibration.h`` avec elles.
+
 #. **Validation** :
 
    - Téléversez le sketch mis à jour sur le routeur.

content/firmware/firmware-monophase.inc.rst

@@ -32,10 +32,10 @@ Après extraction, vous devriez avoir :
    Mk2_fasterControl_Full/
    ├── Mk2_fasterControl_Full.ino  (fichier principal)
    ├── config.h                     (configuration utilisateur)
+   ├── config_system.h              (fréquence du réseau, seuils d’export)
    ├── calibration.h                (paramètres d’étalonnage)
-   ├── dualtarif.h
+   ├── dualtariff.h
    ├── processing.cpp
-   ├── temperature.cpp
    ├── utils_temp.h
    └── ... (autres fichiers)
 
@@ -115,17 +115,17 @@ Options disponibles :
 Configuration des Sorties Triac
 ###############################
 
-Définir le nombre de sorties et leurs broches :
+Définir le nombre de sorties et la broche de chacune :
 
 .. code-block:: cpp
 
    // Exemple : 2 sorties triac
    inline constexpr uint8_t NO_OF_DUMPLOADS{ 2 };
 
-   inline constexpr IoPinMapping physicalPin_dump_load[NO_OF_DUMPLOADS]{
-     { 5, DivertorConfig(NORMAL) },    // Sortie 1 sur broche D5
-     { 4, DivertorConfig(NORMAL) },    // Sortie 2 sur broche D4
-   };
+   inline constexpr uint8_t physicalLoadPin[NO_OF_DUMPLOADS]{ 4, 3 };  // Sortie 1 sur D4, sortie 2 sur D3
+
+.. note::
+   Par défaut, D3 est la broche de marche forcée (`forcePin`) : pour l’utiliser comme sortie, mettre `forcePin` sur une autre broche libre, ou bien `forcePin` à `0xff` et `OVERRIDE_PIN_PRESENT` à `false`. Avec l’afficheur 7 segments, peu de broches restent libres (voir les commentaires de `config.h`).
 
 Ordre de Démarrage
 ##################
@@ -134,32 +134,29 @@ Définir la priorité des charges :
 
 .. code-block:: cpp
 
-   inline constexpr uint8_t dumpLoad_startup_sequence[NO_OF_DUMPLOADS]{ 0, 1 };
+   inline constexpr uint8_t loadPrioritiesAtStartup[NO_OF_DUMPLOADS]{ 0, 1 };
 
 Signification : Démarrer d’abord la sortie 0, puis la sortie 1.
 
 Sondes de Température (Optionnel)
 #################################
 
-Si vous utilisez des sondes DS18B20, décommenter la ligne :
+Si vous utilisez des sondes DS18B20, activer la mesure :
 
 .. code-block:: cpp
 
-   #define TEMP_ENABLED
+   inline constexpr bool TEMP_SENSOR_PRESENT{ true };
 
-Et configurer les adresses des sondes :
+Puis indiquer la broche du bus *OneWire* (une broche libre, avec une résistance de *pull-up*) et les adresses des sondes :
 
 .. code-block:: cpp
 
-   inline constexpr DeviceAddress sensor_list[3]
-   {
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x01 },  // Sonde 1
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x02 },  // Sonde 2
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x03 },  // Sonde 3
-   };
+   inline constexpr TemperatureSensing temperatureSensing{ 2,
+                                                           { { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x01 },     // Sonde 1
+                                                             { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x02 } } };  // Sonde 2
 
 .. note::
-   Les adresses des sondes seront trouvées lors du premier lancement (voir Moniteur Série).
+   Le firmware ne recherche pas les sondes : relevez leurs adresses avec un programme de scan *OneWire* (exemples de l’Arduino IDE ou sur Internet). Collez une étiquette avec l’adresse sur le câble de chaque sonde.
 
 Configuration dans `calibration.h`
 """"""""""""""""""""""""""""""""""

content/firmware/firmware-triphase.inc.rst

@@ -17,10 +17,11 @@ Après extraction, vous devriez avoir :
    Mk2_3phase_RFdatalog_temp/
    ├── Mk2_3phase_RFdatalog_temp.ino  (fichier principal)
    ├── config.h                     (configuration utilisateur)
+   ├── config_system.h              (fréquence du réseau, période d’envoi des données)
+   ├── config_rf.h                  (liaison radio, si elle est utilisée)
    ├── calibration.h                (paramètres d’étalonnage)
-   ├── dualtarif.h
+   ├── dualtariff.h
    ├── processing.cpp
-   ├── temperature.cpp
    ├── utils_temp.h
    └── ... (autres fichiers)
 
@@ -34,6 +35,9 @@ Après extraction, vous devriez avoir :
 Étape 2 : Configuration du Firmware
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. tip::
+   Le :ref:`configurateur <configurateur-triphase>` écrit ``config.h`` (et, avec le module mk2Wifi, le YAML ESPHome) à partir d’une description de votre installation, en vérifiant vos choix. Il suffit ensuite de remplacer les fichiers et de garder votre ``calibration.h``.
+
 Ouverture du Projet
 """""""""""""""""""
 
@@ -51,21 +55,21 @@ Configuration dans `config.h`
 
 Cliquer sur l’onglet **`config.h`** pour le modifier.
 
-Version du PCB
-##############
+Carte-mère
+##########
 
-Selon la version de votre PCB :
+Selon votre carte-mère :
 
 .. code-block:: cpp
 
-   // Ancienne version de PCB (avant 2023)
-   inline constexpr bool OLD_PCB{ true };
+   // Ancienne carte triphasée
+   inline constexpr PcbVersion PCB_VERSION{ PcbVersion::OLD };
 
-   // Nouvelle version de PCB (2023+)
-   inline constexpr bool OLD_PCB{ false };
+   // Carte universelle 3phaseDiverter (rév. 6.0 et suivantes)
+   inline constexpr PcbVersion PCB_VERSION{ PcbVersion::NEW };
 
-.. tip::
-   Si vous avez reçu votre kit après 2 023, mettez `false`.
+.. warning::
+   Les deux cartes ne mesurent pas de la même façon : la carte universelle utilise la référence interne 1,1 V de l’ATmega328P, que le firmware n’active qu’avec `PcbVersion::NEW`. Un mauvais choix donne des mesures fausses. Après un changement, refaire l’étalonnage.
 
 Format de Sortie Série
 ######################
@@ -86,51 +90,51 @@ Options disponibles :
 Configuration des Sorties Triac
 ###############################
 
-Définir le nombre de sorties et leurs broches :
+Définir le nombre de sorties et la broche de chacune :
 
 .. code-block:: cpp
 
    // Exemple : 2 sorties triac
    inline constexpr uint8_t NO_OF_DUMPLOADS{ 2 };
 
-   inline constexpr IoPinMapping physicalPin_dump_load[NO_OF_DUMPLOADS]{
-     { 5, DivertorConfig(NORMAL) },    // Sortie 1 sur broche D5
-     { 4, DivertorConfig(NORMAL) },    // Sortie 2 sur broche D4
+   inline constexpr uint8_t physicalLoadPin[NO_OF_DUMPLOADS]{
+     Load::local(5),  // Sortie 1 sur la broche D5
+     Load::local(6)   // Sortie 2 sur la broche D6
    };
 
+.. note::
+   Une charge pilotée par radio par une unité distante s’écrit `Load::remote(1)` (unité 1, de 1 à 3) au lieu de `Load::local(…)`.
+
 Ordre de Démarrage
 ##################
 
 Définir la priorité des charges :
 
 .. code-block:: cpp
 
-   inline constexpr uint8_t dumpLoad_startup_sequence[NO_OF_DUMPLOADS]{ 0, 1 };
+   inline constexpr uint8_t loadPrioritiesAtStartup[NO_OF_DUMPLOADS]{ 0, 1 };
 
 Signification : Démarrer d’abord la sortie 0, puis la sortie 1.
 
 Sondes de Température (Optionnel)
 #################################
 
-Si vous utilisez des sondes DS18B20, décommenter la ligne :
+Si vous utilisez des sondes DS18B20, activer la mesure :
 
 .. code-block:: cpp
 
-   #define TEMP_ENABLED
+   inline constexpr bool TEMP_SENSOR_PRESENT{ true };
 
-Et configurer les adresses des sondes :
+Puis indiquer la broche du bus *OneWire* (D3 par défaut, qui a déjà sa résistance de *pull-up*) et les adresses des sondes :
 
 .. code-block:: cpp
 
-   inline constexpr DeviceAddress sensor_list[3]
-   {
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x01 },  // Sonde 1
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x02 },  // Sonde 2
-     { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x03 },  // Sonde 3
-   };
+   inline constexpr TemperatureSensing temperatureSensing{ 3,
+                                                           { { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x01 },     // Sonde 1
+                                                             { 0x28, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x02 } } };  // Sonde 2
 
 .. note::
-   Les adresses des sondes seront trouvées lors du premier lancement (voir Moniteur Série).
+   Le firmware ne recherche pas les sondes : relevez leurs adresses avec un programme de scan *OneWire* (exemples de l’Arduino IDE ou sur Internet). Collez une étiquette avec l’adresse sur le câble de chaque sonde.
 
 Configuration dans `calibration.h`
 """"""""""""""""""""""""""""""""""

content/index.rst

@@ -134,6 +134,7 @@ Bienvenue dans la documentation du Mk2PVRouter !
 
    firmware/logiciel-etalonnage-monophase
    firmware/logiciel-etalonnage-triphase
+   firmware/configurateur-triphase
 
 .. toctree::
    :caption: 🏠 Installation Finale

content/mk2wifi/installation-mk2wifi.rst

@@ -60,6 +60,9 @@ Le premier chargement du firmware se fait obligatoirement via le connecteur USB-
 
    Débranchez le module de la carte principale avant de connecter le câble USB-C.
 
+.. tip::
+   Pour le routeur triphasé, le :ref:`configurateur <configurateur-triphase>` génère le YAML ESPHome du module, cohérent avec le ``config.h`` du routeur, et indique les ponts de soudure à fermer.
+
 Procédure
 ~~~~~~~~~
 

content/principe-fonctionnement.rst

@@ -121,4 +121,4 @@ Le Mk2PVRouter offre également des fonctionnalités avancées :
   - Il est également possible de piloter certaines fonctions du routeur via Home Assistant, comme la **marche forcée**.
 
   .. note::
-     Pour plus de détails sur l’intégration avec Home Assistant et pour accéder à un fichier YAML prêt à l’emploi pour ESPHome, consultez ce `Gist <https://gist.github.com/FredM67/986e1cb0fc020fa6324ccc151006af99>`_.
+     Pour le routeur triphasé, le :ref:`configurateur <configurateur-triphase>` génère un fichier YAML ESPHome prêt à l’emploi, cohérent avec la configuration du routeur. Pour plus de détails sur l’intégration avec Home Assistant, consultez aussi ce `Gist <https://gist.github.com/FredM67/986e1cb0fc020fa6324ccc151006af99>`_.