General Concept of the SPINE-IoT API

Summary

The SPINE-IoT API is designed in accordance with the European standard EN 50631 and the international standard IEC 63510. These standards ensure interoperability, security, and scalability in the communication between Energy Smart Appliances (ESA) and Energy Management Systems (EMS).
It enables flexible energy scheduling and control of home appliances through a RESTful architecture. The API supports secure authentication via OAuth2, structured device and use case discovery, and dynamic control through binding and subscription mechanisms. The primary use case covered is Flexible Start for White Goods (FSWG), which allows appliances to adjust their power consumption schedules based on energy availability and user preferences.

---

Overview

The SPINE-IoT API enables seamless communication between EMS and ESA via standardized RESTful interfaces. It is designed to support the EN50631 standard, particularly for the use case Flexible Start for White Goods (FSWG). This concept outlines the architecture, interaction flow, and mandatory implementation requirements for integrating EMS and ESA clouds.

---

Architecture

Key Components

• CCM (Customer Connectivity Manager): EMS cloud responsible for managing energy usage.
• ESA Cloud: Appliance manufacturer's cloud hosting device APIs.
• User: Owner of the ESA account and appliances.

Authentication

• OAuth2 Authorization Code Grant Flow is mandatory.
• CCM must obtain client_id and client_secret from ESA provider.
• All API requests require a JWT in the Authentication header.

---

Interaction Phases

Phase 1: Access Interface

• OAuth2 Flow: CCM authenticates and retrieves access tokens.
• JWT Usage: Required for all subsequent API calls.

Phase 2: Discover and Interact with Devices

Device and Entity Discovery

• GET /devices: Retrieve all or specific devices.
• GET /entities: Retrieve all or specific entities and their features.

Use Case Discovery

• GET /usecases: Identify supported scenarios (e.g., FSWG).
• GET /usecaseInterfaces/flexibleStartForWhiteGoods/v1: Access all relevant feature objects.

Feature Access (Optional)

• GET /features: Retrieve detailed power sequence data.
  • Includes powerSequence, powerTimeSlot, powerSequenceNode, powerSequenceAlternativesRelation.

FSWG Scenarios

• Scenario 1: Announcement of a plan (UCF_Plan_With_Power_Sequences)
• Scenario 2: Shift preferred power sequence (UCF_Shift_Preferred_Power_Sequence)
• Scenario 3: Select alternative power sequence (optional)
• Scenario 4: Configure current power sequence (optional)

---

Phase 3: Binding and Subscription

Binding

• POST /bindings: Create binding for a specific device/entity/use case.
• Only one CCM can control a given appliance at a time.
• PATCH /bindings: Renew binding.
• DELETE /bindings: Remove binding.
• GET /bindings: Retrieve active bindings.

Subscription

• POST /subscriptions: Subscribe to updates for devices, entities, usecases, and usecaseInterfaces.
• POST /receivecallbacks: CCM receives updates from ESA cloud.
• Subscriptions expire after 7 days and must be renewed.

---

Common Workflow

1. Authenticate via OAuth2.
2. Discover devices, entities, and use cases.
3. Subscribe to relevant resources.
4. Access use case interfaces.
5. Bind to use case instances.
6. Control appliances via POST requests.
7. Renew bindings and subscriptions as needed.

---

Mandatory Requirements

• OAuth2 Authorization is required.
• UsecaseInterfaces must be supported for FSWG.
• Binding and Subscription are mandatory for usecaseInterfaces.
• Feature Objects:
  • powerSequenceNode and powerSequenceAlternativesRelation are mandatory.
• Time Format: All timestamps must be in UTC.

---

FAQs

• Accuracy of Power Values: Not strictly defined; use available indicators.
• Single Slot Usage: Allowed but not recommended.
• Manual Device Control: ESA sends updated power sequence.
• JWT Types: Separate JWTs for OAuth and callbacks.
• TLS Requirement: Minimum TLS 1.2.
• Revoking Access: EMS loses access; must re-authenticate.