EDDIE Architecture

Appearance

AIIDA Communication Protocol

This appendix specifies the wire-level messages exchanged between AIIDA and the EDDIE Framework. It is the protocol-level companion to the AIIDA Runtime View, which describes the same flows from a component perspective:

  • The connection-setup workflow (QR code → handshake → MQTT credentials) corresponds to steps 1–3 of the Control Plane below.
  • The data-streaming workflow is realized by the Data Plane, with optional acknowledgement, termination, and status messages on the Control Plane.

Communication is divided into two planes:

  • Control Plane — handshake and lifecycle messages, exchanged via HTTPS during setup and via dedicated MQTT control topics afterwards.
  • Data Plane — energy-data payloads exchanged on MQTT data topics.

Control Plane ​

1. QR Code ​

Generated by EDDIE and scanned (or pasted) into the AIIDA UI by the customer to bootstrap the handshake.

json
{
  "eddieId": "56faf485-ed0a-4066-8cce-dc227c1350a9",
  "permissionIds": [
    "09520290-ea60-4422-a54c-db8fde93cfd5"
  ],
  "handshakeUrl": "https://framework.eddie.energy/region-connectors/aiida/permission-request/{permissionId}",
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3Nzc5ODE1MjEsImlhdCI6MTc3NzM3NjcyMSwicGVybWlzc2lvbnMiOnsiYWlpZGEiOlsiMDk1MjAyOTAtZWE2MC00NDIyLWE1NGMtZGI4ZmRlOTNjZmQ1Il19fQ.Lo7ttkcQVp-QClKRbyQOCpG_rrB-xpbwHM4T7Mh3FKg"
}

2. AIIDA → EDDIE: Fetch Permission Details ​

Using the handshakeUrl and accessToken from the QR code, AIIDA retrieves the full permission and data-need description so it can decide whether the request is fulfillable.

Request ​

GET {handshakeUrl}
Authorization: Bearer {accessToken}

Response ​

json
{
  "eddie_id": "56faf485-ed0a-4066-8cce-dc227c1350a9",
  "permission_request": {
    "connection_id": "b77f7f5c-3d1b-4597-848f-2001700c228b",
    "data_need_id": "fdeef3a6-aa35-4de2-aec6-9072ccd843b2",
    "permission_id": "09520290-ea60-4422-a54c-db8fde93cfd5",
    "start": "2026-04-28",
    "end": "2026-07-28"
  },
  "data_need": {
    "type": "outbound-aiida",
    "acknowledgementRequired": false,
    "asset": "CONNECTION-AGREEMENT-POINT",
    "createdAt": "2026-01-07T06:57:18.773378Z",
    "dataTags": [],
    "description": "Data sent each 2 secs",
    "duration": {
      "type": "relativeDuration",
      "start": "P0D",
      "end": "P3M"
    },
    "enabled": true,
    "id": "fdeef3a6-aa35-4de2-aec6-9072ccd843b2",
    "isAcknowledgementRequired": false,
    "name": "Outbound CIM AIIDA data with 2 seconds resolution",
    "policyLink": "https://example.com/toc",
    "purpose": "purpose",
    "schemas": [
      "SMART-METER-P1-CIM-V1-04"
    ],
    "transmissionSchedule": "*/2 * * * * *"
  }
}

3. AIIDA → EDDIE: Respond to Permission Request ​

After validating the request, AIIDA replies with one of UNFULFILLABLE, ACCEPT, or REJECT. On ACCEPT, EDDIE provisions a dedicated MQTT user at the EMQX IAM database and returns the credentials and topic names that AIIDA uses for the Data Plane.

Request ​

PATCH {handshakeUrl}
Authorization: Bearer {accessToken}
json
{
  "operation": "ACCEPT",
  "aiidaId": "123e4567-e89b-12d3-a456-426614174000"
}

Response (ACCEPT) ​

json
{
  "serverUri": "tcp://online.eddie.energy:1883",
  "username": "09520290-ea60-4422-a54c-db8fde93cfd5",
  "password": "z=1CfV%O2jHX03ar8]ev&;W`",
  "dataTopic": "aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/data/outbound",
  "statusTopic": "aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/status",
  "terminationTopic": "aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/termination",
  "acknowledgementTopic": null
}

4. Lifecycle Messages During Streaming ​

Once the permission is ACCEPTED and the start time is reached, AIIDA opens the MQTT connection and begins publishing on the Data Plane. The following control messages flow over dedicated MQTT topics for the lifetime of the permission.

4a. EDDIE → AIIDA: Acknowledgement (optional) ​

Sent only when the data need has acknowledgementRequired = true.

MQTT topic: aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/acknowledgement

Payload: ACKNOWLEDGEMENT_CIM_V1_12

4b. EDDIE → AIIDA: Termination (optional) ​

Sent when the EDDIE side terminates the permission before its natural end.

MQTT topic: aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/termination

09520290-ea60-4422-a54c-db8fde93cfd5

5. AIIDA → EDDIE: Status Update ​

AIIDA reports lifecycle transitions on the status topic. The reported status is one of FULFILLED, REVOKED, or TERMINATED (see the state diagram below for the full set of reachable states).

MQTT topic: aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/status

json
{
  "eddie_id": "56faf485-ed0a-4066-8cce-dc227c1350a9",
  "connection_id": "b77f7f5c-3d1b-4597-848f-2001700c228b",
  "data_need_id": "fdeef3a6-aa35-4de2-aec6-9072ccd843b2",
  "permission_id": "09520290-ea60-4422-a54c-db8fde93cfd5",
  "timestamp": "2026-04-28T12:00:00Z",
  "status": "REVOKED"
}

Permission Lifecycle ​

Data Plane ​

The Data Plane carries the actual energy-data payloads on the MQTT topics returned in the ACCEPT response (step 3). In the runtime view this corresponds to the energy-data flow from the Data Source through the AIIDA Application to the AIIDA Region Connector, where it is consumed by the EP Service.

AIIDA → EDDIE: Outbound Data ​

MQTT topic: aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/outbound

Payload can be one of the following:

EDDIE → AIIDA: Inbound Data ​

MQTT topic: aiida/v1/09520290-ea60-4422-a54c-db8fde93cfd5/inbound

Payload can be one of the following: