Skip to content

Contract

The machine-readable contract describes the shape of every message of the protocol: an OpenRPC document whose messages are written in JSON Schema, with x-etm-… extensions for what OpenRPC cannot express — transport, fallback state machine, named validation rules, tolerances, closed lists.

The engine embeds it, and both its own tests and the conformance suite check it on both sides. The tables on the Protocol page are generated from it.

Download the contract

Download etm-powersync-optimizer-protocol.openrpc.json

The site serves the file as is, byte for byte, from the default branch of the engine repository. Its record:

Contract
Title etm-powersync — protocole moteur ↔ optimiseur
Protocol version 1.8
Format OpenRPC 1.3.2, JSON Schema in components.schemas
License GPL-3.0-or-later
File etm-powersync-optimizer-protocol.openrpc.json
Size 109892 bytes
SHA-256 f8b6c501617752e7a67022a68cae6fc3b198be48c49d18ebbd89cd3f525d1d46
Methods Handshake · GetPlan · UpdateLearned
Schemas 54
Semantic rules 19
Extensions (document) x-etm-error-message · x-etm-fallback-machine · x-etm-generated · x-etm-message-errors · x-etm-reason-params · x-etm-semantic-rules · x-etm-tolerances · x-etm-transport
Extensions (methods) x-etm-direction · x-etm-errors-engine · x-etm-notification · x-etm-timeout-s

Your box's contract: NymeaEnergy.GetOptimizerProtocol

The contract published here follows the engine's development; your box may carry an earlier version. To get the contract of the installed engine, ask the box: the JSON-RPC method NymeaEnergy.GetOptimizerProtocol returns the one it embeds. That is the one that is authoritative for an optimizer connected to that box.

It belongs to the optimizer NymeaEnergy.* methods (endpoint, shared secret, status); the box itself returns their exact form through JSONRPC.Introspect. Connecting to the API is described on the JSON-RPC API page.

Validating messages

The engine repository provides a validator, tools/etm-powersync-schema-check (Python, standard library): it checks a single message, a complete recorded session or traces against the contract, and applies the named validation rules on request.