powersync-docs/docs/fonctionnalites/moteur.en.md

How the engine decides

COMMUNITY

The box's energy engine drives your loads on its own: EV chargers, water heater, SG-Ready heat pump, relays. It is free software (GPL-3.0) and it is what decides in the Community edition. This page describes its logic for installers and integrators; the following pages detail each feature.

Two loops, two priorities

The engine keeps safety apart from allocation. They are two separate loops, running at different rates and with different priorities.

• The safety loop, in real time. On every change in the measured balance, it reads the current of each phase at the grid meter. If a phase exceeds the configured limit, it cuts loads back immediately (load shedding), then releases them once there is headroom again. It does not wait for the cycle and overrides everything else.
• The allocation cycle, about once a minute. It shares the available power between the loads. This is the only place a strategy acts: the built-in rules, or an optimizer if one is connected.

If the grid meter stops answering, the engine suspends allocation and falls back to safety mode: no measurement, no decision.

The rules, in order

On every cycle, the engine runs the same steps, in the same order.

1. Measure. The starting point is what the grid meter measures. The engine adds back what the loads it drives are already drawing: a running load is not counted against itself.
2. Account for what is locked. A load under a lock (minimum on or off time, delay between two current changes) keeps the power it has committed, and that power is taken out of the budget. An unavailable load receives no setpoint, but what it draws is still counted.
3. Serve needs with a deadline. A daily obligation (for example a minimum energy for the water heater before a given time) or a one-off request made from the app may, as the deadline nears and the surplus has not been enough, take the remainder from the grid — if the installer has allowed it.
4. Cascade the surplus. Loads are served in the priority order you set (1 = served first). Each receives what is left of the budget, within its bounds, and the budget is reduced accordingly. There is one budget: without it, three managers would each see "2 kW of surplus" and draw 6 between them.
5. Stop what cannot start. Below its minimum power, a load stays off rather than running at half.

The bounds of each load

Each load carries bounds entered by the installer, which every decision respects, whatever the strategy:

• a power floor and ceiling (or current, for an EV charger);
• anti-flapping locks: minimum on and off time, delay between two changes;
• for an SG-Ready heat pump: the state is chosen from the estimated power of each state, with a minimum hold time.

The reason for every decision

The engine takes no decision without stating why. Every decision carries a non-empty reason (decisionReason): a stable code and its parameters, which the app displays in your language — "surplus insufficient", "below minimum power", "charging deadline"… The list of codes is published with the optimizer protocol.

The measurement, never the result of control

Surplus is computed from the raw measurement: production and meter, as measured. Never from the net balance after control: the engine would be reading itself, and oscillate.

Without internet

All of the above runs on the box. Without internet, the engine keeps driving the loads, enforces safety and answers the app on your local network. Only the PV forecast stops — and it is not used for decisions in the Community edition, any more than the entered tariff: both are displayed and recorded, never used by the rules.

What about an optimizer?

An optimizer can propose a plan over several hours, based on the forecasts. It replaces the allocation step, never the safety loop or the bounds. See the Optimizer section.