Specifications & Documentation
SPINE – our data model
SPINE (Smart Premises Interoperable Neutral-message Exchange) is the data model of the EEBUS standard. It defines what energy-relevant devices can say about themselves and how they exchange that information – independently of the transport technology underneath.
SPINE specifications
Introduction, Protocol Specification, Resource Specification and the data model XSDs.
What SPINE is
SPINE defines messages and procedures on the application level (ISO/OSI layer 7). It says nothing about how the bits travel, so any technology that supports the bi-directional exchange of arbitrary data can carry SPINE messages. For SHIP, the IP-based protocol also developed by EEBus, the mapping is minimal; other technologies are integrated through their own mapping components.
It covers the control and monitoring of energy-relevant devices: heat pumps and HVAC systems, EV chargers, battery storage, PV systems and home appliances.
Device, entity, feature
Every device is described on three levels. The same three levels form the SPINE address: the device is a string with a vendor-unique part, the entity is a sequence of numbers that can also address sub-entities, and the feature is a single number.
| Level | What it describes | Example |
|---|---|---|
| Device | The physical device | Fridge-freezer combination |
| Entity | A logical (sub-)device – one device may hold several | Fridge, freezer |
| Feature | A functionality, described by exactly one class | Temperature measurement, superfreeze switch |
Device: Fridge-freezer
Entity: Fridge
Feature: Temperature measurement
Feature: On/off control
Entity: Freezer
Feature: Temperature measurement
Feature: Superfreeze control
- Device
- Entity
- Feature
Address levels
Figure 1 – Address levels of a fridge-freezer: one device, two entities, four features – and one address per feature.
Classes, functions, elements
How devices exchange information
A SPINE message consists of a header, holding addresses and the classifier, and a payload carrying the data.
- ✓ Classifiers — read and reply for requests, write for changes, notify for updates to subscribers, call for remote procedures, result for acknowledgements and errors.
- ✓ Roles — every feature acts as server or client. The server owns the data; the client requests or changes it.
- ✓ Discovery — after a connection is established, a device learns which entities, features and functions its partner offers. Use Case discovery complements this where detailed discovery is not sufficient.
- ✓ Binding and subscription — binding restricts which partner may interact with a feature; subscription delivers updates without polling.
- ✓ Partial data — only the relevant parts of a function are read, written or notified, instead of the whole function.
From data model to Use Cases
The data model describes what a device can say about itself. What a device must say in a given situation is defined by the EEBUS Use Cases – for example limiting power consumption at the grid connection point, or reporting current consumption data. Each Use Case specifies which entities, features and functions the participating devices use, and in which role. This is why two devices from different manufacturers can work together without prior coordination.
Key distinction
SPINE defines the energy-related information. SHIP establishes and protects the communication channel through which it is exchanged.
Where to start reading
We recommend this order within the specification:
- 1 SPINE Technical Report – Introduction — the guided overview this page is based on.
- 2 SPINE Protocol Specification — datagram, classifiers, functional commissioning.
- 3 SPINE Resource Specification — the complete resource model, standard and complex classes.
- 4 Data model XSDs — the machine-readable definition.
