powersync-docs/docs/fonctionnalites/moteur.md

# Comment le moteur décide

<span class="badge community">COMMUNITY</span>

Le moteur d'énergie de la box pilote seul vos charges : bornes de recharge, chauffe-eau,
pompe à chaleur SG-Ready, relais. Il est libre (GPL-3.0) et c'est lui qui décide dans la
version **Community**. Cette page décrit sa logique pour l'installateur et l'intégrateur ;
les pages suivantes détaillent chaque fonction.

## Vue d'ensemble

```mermaid
flowchart TB
    CPT["Compteur de tête<br/>courant par phase, injection, soutirage"]
    BAT["Batterie<br/>état de charge"]
    APP["Application<br/>demandes ponctuelles"]
    CFG["Réglages de l'installateur<br/>rangs, bornes, obligations"]

    subgraph M["Moteur d'énergie, sur la box"]
        PROT["Protection contre la surcharge<br/>à chaque mesure, prioritaire"]
        subgraph C["Cycle de répartition, chaque minute"]
            C1["1. Mesure et marge de soutirage"] --> C2["2. Recharges à échéance"]
            C2 --> C3["3. Réserve batterie"]
            C3 --> C4["4. Passe éco<br/>demandes ponctuelles, obligations"]
            C4 --> C5["5. Passe confort<br/>surplus en cascade, par rang"]
            C5 --> C6["6. Une commande par charge"]
        end
        AD["Adaptateurs<br/>bornes et verrous de chaque charge"]
    end

    OPT["Optimiseur, en option<br/>propose la répartition"]

    VE["Bornes de recharge"]
    ECS["Chauffe-eau<br/>à relais ou modulable"]
    PAC["Pompe à chaleur SG-Ready"]
    REL["Relais"]

    CPT --> PROT
    CPT --> C1
    BAT --> C3
    APP --> C4
    CFG --> C
    OPT -. "plan" .-> C6
    C6 --> AD
    PROT --> AD
    AD --> VE & ECS & PAC & REL
```

La protection contre la surcharge et les adaptateurs restent au moteur dans tous les cas :
un [optimiseur](../optimiseur/index.md), s'il est branché, ne propose que la répartition.

## Deux boucles, deux priorités

Le moteur sépare la sécurité de la répartition. Ce sont deux boucles distinctes, qui ne
tournent pas au même rythme et n'ont pas la même priorité.

- **La protection contre la surcharge, à chaque mesure.** Dès que le bilan mesuré change,
  le moteur lit le courant de chaque phase au compteur de tête. Si une phase dépasse la
  limite configurée, il réduit **immédiatement** le courant des bornes de recharge, puis
  le relâche quand la marge revient. Les autres charges (chauffe-eau, pompe à chaleur,
  relais) sont délestées au début du cycle suivant ([délestage](delestage.md)). Cette
  protection prime sur toute décision de répartition.
- **Le cycle de répartition, chaque minute.** Il répartit la puissance disponible entre
  les charges, sur la mesure d'une minute du bilan électrique, et repart aussitôt quand
  vous changez un réglage. C'est le seul endroit où une stratégie intervient : les règles
  intégrées, ou un [optimiseur](../optimiseur/index.md) s'il est branché.

**Si le compteur de tête se tait** (plus de 90 s sans mesure), le moteur suspend la
répartition et met les charges en position sûre : charges réglables à 0 W, relais
ouverts, pompe à chaleur en fonctionnement normal, bornes déjà en charge ramenées au
courant minimum, aucune nouvelle charge démarrée. La protection contre la surcharge reste
active. La répartition reprend au cycle qui suit le retour du compteur.

## Les règles, dans l'ordre

À chaque cycle, le moteur applique les mêmes étapes, dans le même ordre.

1. **Mesurer.** Le point de départ est ce que mesure le compteur de tête (injection et
   soutirage). Le moteur en tire aussi la **marge de soutirage** : ce que l'installation
   peut encore prendre au réseau sans dépasser la limite de phase. Aucun achat au réseau,
   quelle qu'en soit la raison, ne la dépasse.
2. **Servir les recharges à échéance.** Un véhicule qui doit être chargé pour une heure
   donnée est servi sur le réseau, hors du partage du surplus.
3. **Protéger la batterie.** Si une batterie domestique est sous son seuil de réserve, le
   surplus lui revient d'abord : les charges pilotées n'en reçoivent pas. Au-dessus du
   seuil, ce qu'elle absorbe compte comme surplus disponible. Sa décharge n'est jamais
   comptée comme du surplus.
4. **Les besoins garantis (passe « éco »).** D'abord les **demandes ponctuelles** faites
   depuis l'application (« chauffer maintenant ») : la charge reçoit sa pleine puissance,
   quel que soit son rang. Ensuite les **obligations quotidiennes**, par exemple une
   énergie minimale pour le chauffe-eau avant une heure donnée : le moteur achète au
   réseau ce qui manque, réparti régulièrement jusqu'à l'échéance, et passe à pleine
   puissance quand il ne reste plus que le temps juste nécessaire. Ces achats restent dans
   la marge de soutirage.
5. **Partager le surplus en cascade (passe « confort »).** Les charges sont servies dans
   l'ordre de **priorité** que vous avez fixé (1 = servie en premier). Chacune reçoit ce
   qui reste du budget, dans ses bornes, et le budget est décrémenté d'autant. Le budget
   est **unique** : sans lui, trois gestionnaires verraient chacun « 2 kW de surplus » et
   en tireraient 6. À son tour, pour chaque charge :
    - ce qu'elle consomme déjà lui est rendu : une charge en marche n'est pas comptée
      contre elle-même ;
    - sous sa puissance minimale, elle reste arrêtée plutôt que de fonctionner à moitié,
      et le budget passe à la suivante. Une borne de recharge peut toutefois démarrer avec
      un petit complément pris au réseau, dans la tolérance réglée ;
    - une charge sous **verrou** (durée minimale de marche ou d'arrêt, délai entre deux
      changements) garde sa puissance du moment ;
    - une charge **indisponible** garde sa puissance actuelle, sans nouvelle consigne ; ce
      qu'elle consomme reste compté.
6. **Une seule commande par charge.** Le besoin garanti et la part de surplus d'une même
   charge sont fusionnés : chaque charge reçoit une seule consigne, avec son motif.

### Les rangs et les domaines

Le moteur ne connaît **qu'une seule liste** : chaque charge a un rang, toutes catégories
confondues, et la cascade suit ce rang. Le **domaine** d'une charge (véhicule électrique,
eau chaude sanitaire, climatisation, chauffage, batterie) est une étiquette choisie par
l'installateur : le moteur ne la lit pas pour décider.

L'application s'en sert pour présenter l'ordre de service **par domaines** : on règle
l'ordre des domaines entre eux, puis l'ordre des charges dans chaque domaine. À la mise en
service, elle propose : véhicule électrique, eau chaude sanitaire, climatisation,
chauffage. Comme tout repose sur la liste unique, rien n'oblige les charges d'un domaine à
se suivre : un chauffe-eau d'appoint peut être servi **en tout dernier**, après le
chauffage, et une borne peut passer avant le chauffe-eau tandis qu'une autre passe après.

```mermaid
flowchart LR
    subgraph AV["Ordre proposé"]
        direction TB
        a1["1 · VE garage"] --> a2["2 · VE visiteur"] --> a3["3 · Chauffe-eau principal"] --> a4["4 · Chauffe-eau d'appoint"] --> a5["5 · PAC"]
    end
    subgraph AP["Après réglage"]
        direction TB
        b1["1 · VE garage"] --> b2["2 · Chauffe-eau principal"] --> b3["3 · VE visiteur"] --> b4["4 · PAC"] --> b5["5 · Chauffe-eau d'appoint"]
    end
    AV ==>|"on ne change que des rangs"| AP

    classDef ev stroke:#3b82f6,stroke-width:3px
    classDef ecs stroke:#ef4444,stroke-width:3px
    classDef chauf stroke:#f59e0b,stroke-width:3px
    class a1,a2,b1,b3 ev
    class a3,a4,b2,b5 ecs
    class a5,b4 chauf
```

Bordure bleue : véhicule électrique · rouge : eau chaude sanitaire · orange : chauffage.

!!! tip "Poser les rangs à la mise en service"
    Une borne détectée est ajoutée d'office **en fin de liste**, quel que soit son domaine.
    Deux charges au même rang sont départagées par leur identifiant, ce qui n'est le choix
    de personne. Réglez l'ordre dans l'application à la mise en service.

### Les bornes de chaque charge

Chaque charge porte des bornes saisies par l'installateur, que **toute** décision
respecte, quelle que soit la stratégie :

- un **plancher** et un **plafond** de puissance. Pour une borne de recharge, ils sont en
  courant (multiplié par le nombre de phases), et le plafond est en plus limité par la
  limite de phase ;
- des **verrous anti-battement** : durée minimale de marche et d'arrêt, délai entre deux
  changements. Une borne de recharge a les siens (délai entre marche et arrêt, délai entre
  deux changements de courant) ;
- pour une PAC SG-Ready : l'état choisi selon la puissance estimée de chaque état, avec
  une hystérésis et une durée minimale de maintien. L'état de blocage n'est jamais
  commandé par le surplus.

## Le motif de chaque décision

Le moteur ne prend aucune décision sans en dire la raison. Chaque décision porte un
**motif** (`decisionReason`) non vide : un code stable et ses paramètres, que
l'application affiche dans votre langue — « surplus insuffisant », « sous la puissance
minimale », « échéance de recharge »… La liste des codes est publiée avec le
[protocole optimiseur](../optimiseur/protocole.md#reponse).

## La mesure, jamais le résultat du pilotage

Le surplus est calculé sur la **mesure brute** du compteur de tête, telle qu'elle est
mesurée. Jamais sur un bilan recalculé après pilotage : le moteur se lirait lui-même et
oscillerait.

## Sans internet

Tout ce qui précède tourne sur la box. Sans internet, le moteur pilote, applique la
sécurité et répond à l'application sur votre réseau local. Seule la
[prévision PV](prevision-pv.md) s'interrompt. Dans la version Community, ni la prévision
ni le [tarif saisi](../tarifs.md) n'entrent dans les décisions des règles : tous deux
sont affichés et enregistrés, jamais utilisés pour décider.

## Et un optimiseur ?

Un optimiseur peut proposer un plan sur plusieurs heures, à partir des prévisions. Il
remplace l'étape de répartition, **jamais** la protection contre la surcharge ni les
bornes. Voir la section [Optimiseur](../optimiseur/index.md).