Specifications & Documentation
SHIP – secure IP connectivity
SHIP (Smart Home IP) is the IP-based communication protocol used to establish secure connections between EEBUS devices. It defines how devices find each other, build trust and exchange data – from local networks to remote services.
What SHIP is
SHIP defines a secure, standardised approach to machine-to-machine communication over IP. It covers the mechanisms between the network and application layers of the ISO/OSI model and supports both IPv4 and IPv6.
The protocol is designed for different environments and device capabilities: local devices in a home, gateways and remote or web-server-based services. It also accommodates constrained devices that can maintain only a small number of simultaneous connections.
SHIP provides the communication channel, but it does not define the meaning of the application data. In EEBUS communication, that meaning is supplied by SPINE. SHIP can also carry other application protocols and has no dependency on the SPINE data model.
The SHIP protocol stack
SHIP builds on established internet technologies and adds the procedures required for interoperable device communication.
| Layer or function | Technology | Purpose |
|---|---|---|
| Local discovery | mDNS / DNS-SD | Finds SHIP nodes and their services in the local network |
| Network | IPv4 / IPv6 | Provides IP connectivity across different physical networks |
| Transport | TCP | Establishes a reliable connection between two SHIP nodes |
| Security | TLS | Encrypts the connection and authenticates both communication partners |
| Communication channel | WebSocket | Maintains a bidirectional channel for SHIP messages |
| Protocol control | SHIP Message Exchange (SME) | Prepares the connection and carries control and application data |
Application payload
e.g. SPINE messages,
identified by protocolId
Connection states, control
messages, protocol negotiation
Alongside the stack
Discovery
ship service in the local network
Discovery is a separate mechanism – not a layer of the connection stack. For remote services, DNS takes this role.
Figure 1 – Discovery runs alongside the connection stack. Once two SHIP nodes connect, TCP, TLS and WebSocket provide the channel for SHIP Message Exchange.
From discovery to connection
A communicating device or service is called a SHIP node. In a local network, SHIP nodes announce and find the
ship service using multicast Domain Name System (mDNS) and DNS-Based Service Discovery (DNS-SD).
The discovery records provide the information needed to identify and contact a node. This includes a unique SHIP ID, the host and port, the WebSocket path and information used for key verification. Further fields describe the device: the device category is mandatory, while brand, type, model and serial number are optional or recommended.
After discovery, the nodes establish the communication channel in three steps:
- 1Open a TCP connection
- 2Establish a mutually authenticated TLS connection
- 3Open the secure WebSocket channel
The same architecture supports local and remote connections. For a remote service, DNS supplies the address and port instead of local mDNS discovery.
The SHIP Pairing Service
The SHIP Pairing Service establishes trust without any user interaction on the devices themselves. The control unit (devZ, for example the control box of the metering point operator) is configured with three pieces of information about the end device (devA, for example a heat pump, wallbox or energy management system): its SHIP ID, its SHA-256 certificate fingerprint and a device-specific secret. These are typically made available as a QR code on the device. The control unit then sends a cryptographically signed pairing request, which the end device validates before accepting it.
This solves a practical problem in the field: end device and control unit are usually installed by different trades at different times, so the two installers no longer need to be on site at the same moment. Once trust has been established, the end device stops accepting further pairing requests.
Trust, registration and reconnection
Every SHIP node has its own certificate and public key. During the TLS handshake, both sides present a certificate. SHIP then verifies whether the public key belongs to a trusted communication partner.
Trust can be established in several ways, depending on the device and its user interface:
- ✓ User verification – a user compares or confirms the Subject Key Identifier (SKI).
- ✓ Commissioning – a trusted commissioning tool distributes or verifies key material.
- ✓ Manufacturer-specific commissioning – a manufacturer provides its own trusted process.
hello process. The nodes store the relevant credentials for future connections.
When the same nodes connect again, SHIP treats this as a reconnection. If the public key still matches the trusted key from registration, the connection can proceed without repeating the initial trust process. SHIP 1.1 also defines mechanisms for certificate and key changes so that established trust can be maintained securely.How SHIP carries data
hello trust check, protocol negotiation and, where required, PIN verification. SHIP messages distinguish between control information and application data. The application protocol is identified through a
protocolId, so the receiving node knows how to interpret the payload. In EEBUS communication, this payload typically contains SPINE messages. Many SHIP structures use JSON in UTF-8 format. One SHIP message is carried in one WebSocket message. Ping and pong frames check that an open connection is still operational, allowing devices and remote services to remain responsive without constantly rebuilding the channel.
Key distinction
SHIP establishes and protects the communication channel. SPINE defines the energy-related information exchanged through it.
Where to start reading
We recommend this order within the specification:
- 1 Introduction, Scope and Architecture Overview – the purpose, system context and protocol stack.
- 2 Discovery, TCP, TLS and WebSocket – how SHIP nodes find each other and establish the secure channel.
- 3 Key Management – certificates, public-key verification, trust levels, PINs and commissioning.
- 4 SHIP Data Exchange – protocol architecture, connection states, control messages and application payload.
- 5 SHIP XSDs – the machine-readable structures used by the protocol.
