EEBus SDK

eebus-sdk is a Python-first SHIP / EEBus / SPINE toolkit for HEMS vendors, lab engineers, and SMGW integrators.

This repository contains three public deliverables:

• eebus_sdk: importable Python package
• eebus: CLI for discovery, identity management, live sessions, and trace replay
• interop_fixtures: sanitized JSONL traces used for regression tests and interoperability debugging

The project is currently alpha. The transport and core SHIP path are implemented and tested, but PPC trust commissioning and broader profile coverage are still being expanded.

Current capabilities

• mDNS / DNS-SD discovery of _ship._tcp.local services
• SHIP identity generation with persistent client certificates
• explicit trust configuration with SKI pinning and optional CA anchors
• asyncio-based TLS + WebSocket + SHIP session handling
• SPINE datagram send/receive helpers
• recorded JSONL tracing and replay summaries
• CLI workflows for:
  • eebus discover
  • eebus identity create
  • eebus trust show
• eebus connect
• eebus trace
• eebus replay
• eebus selftest

PPC status

The SDK has already proven the following on the lab network:

• PPC SHIP endpoint discovery via mDNS
• mutual TLS with a generated client certificate
• WebSocket upgrade to /ship/
• SHIP startup through CMI and hello

The current PPC blocker is still trust enrollment on the PPC / SMGW side. Before the client certificate is trusted, PPC responds with connectionHello phase=pending and closes with 4452 Node rejected by application. The SDK captures and replays that behavior through fixtures and tests.

Verified hardware tests

• SPiNE EnergyLink One installed in the lab: verified mutual TLS, WebSocket upgrade, full SHIP handshake, and reception of a real SPINE discovery datagram.
• PPC CLS / SMGW endpoint installed in the lab: verified mDNS discovery, mutual TLS, WebSocket upgrade, and SHIP startup through hello; full SPINE exchange is still blocked by PPC-side trust enrollment and currently ends with 4452 Node rejected by application.

Quickstart

Create an identity:

python3 -m eebus_sdk.cli identity create --out-dir .state/example-identity --device-id HEMS-EXAMPLE

Discover SHIP peers:

python3 -m eebus_sdk.cli discover --interface-ip 192.0.2.2 --tls-check

Connect to a SHIP peer:

python3 -m eebus_sdk.cli connect \
  --identity .state/example-identity/identity.json \
  --host 192.0.2.10 \
  --port 23292 \
  --path /ship/ \
  --server-name ship-peer.example.local \
  --expected-server-ski 0123456789abcdef0123456789abcdef01234567 \
  --trace-jsonl .state/example-identity/ship-session.jsonl

Summarize a recorded trace:

python3 -m eebus_sdk.cli trace interop_fixtures/ship/spine_discovery_success.jsonl

Validate a fixture in CI:

python3 -m eebus_sdk.cli replay interop_fixtures/ship/ppc_pairing_rejected.jsonl --expect pairing-rejected

Run a full local loopback self-test with both transport and application roles on the same PC:

python3 -m eebus_sdk.cli selftest --verify-tls

Python API

import asyncio

from eebus_sdk import HemsClient, IdentityStore, TrustStore, discover_ship_services


async def main() -> None:
    identity = IdentityStore.load(".state/example-identity/identity.json")
    services = discover_ship_services("192.0.2.2")
    peer = next(service for service in services if service.service_name.endswith("._ship._tcp.local"))
    trust = TrustStore.from_server_ski(peer.ski, verify_tls=False)

    client = await HemsClient.connect(peer, identity, trust, interface_ip="192.0.2.2")
    try:
        discovery = await client.discover_nodes(timeout=5.0)
        print(discovery)
    finally:
        await client.close()


asyncio.run(main())

Development

Run the unit test suite:

python3 -m unittest discover -s tests -v

Key documents:

• interop_fixtures/README.md
• COMPATIBILITY.md

Scope and claims

• This project does not imply BSI or EEBus certification by itself.
• The repository documents behavior in original wording and links to official sources instead of republishing spec text.
• The alpha target is a usable SDK and debugging toolchain for PPC SMGW and at least one non-PPC SHIP/SPINE peer.