powersync-docs/docs/optimiseur/index.en.md

Optimizer

IN PROGRESS

The protocol between the engine and an optimizer is published (version 1.1). Connecting an optimizer is being tested on our test installation; the box does not need one to work.

What an optimizer is for

The engine's rules decide on the present: this minute's surplus, shared according to your priorities. An optimizer looks further ahead. From the forecasts the engine hands it — PV production, base consumption, entered tariff — it proposes a plan in time slots over several hours: shift the water heater to the expected production peak, keep headroom for evening charging, and so on.

The optimizer advises, the engine decides

• The engine only executes the current slot of the plan. The rest is shown as a forecast, and requested again on the next cycle.
• Every setpoint is capped by the load's bounds (floor, ceiling, anti-flapping locks) and by the real-time safety loop, which stays with the engine and overrides everything. An optimizer cannot bypass a lock.
• Every action must carry its reason. An action without one is rejected.
• A malformed plan, or one that targets an unknown load, is rejected as a whole.

At worst, a faulty optimizer can therefore only propose a poor allocation — bounded by the engine.

The box works without an optimizer

Optimizer missing, silent, abstaining, plan expired or rejected: the engine returns to its rules (rules) for that cycle, with no interruption of control. The app shows at all times which strategy is in charge. The Community edition works entirely this way.

Its data come from the engine only

• The engine connects to the optimizer, never the other way round: the box opens no port.
• The optimizer runs on the box (local socket) or on a machine in your local network (TCP). On the local network, a shared secret (token) is recommended.
• It receives only the context the engine sends, forecasts included: it calls neither a weather service nor a tariff provider, and opens no connection to the outside.
• What it learns stays on site.

Who can write an optimizer

Anyone. The protocol is open and described by a machine-readable contract published under GPL-3.0. A free reference optimizer and a conformance suite let you write your own and check it against the real engine — see Writing an optimizer.

The ETM optimizer

ETM-Schurig offers its own proprietary optimizer, included in the Pro edition. It connects through this same protocol, within the same limits: it advises, the engine decides. At handshake it announces itself as etm-optimizer; the reference optimizer announces itself as powersync-optimizer.

In this section

• Protocol — transport, handshake, context, plan, fallback, validation rules.
• Contract — the OpenRPC file that is authoritative on the shape of messages.
• Writing an optimizer — reference optimizer and conformance suite.