From 06e1cec55f786a9d302cf2a7ef58e3164c154561 Mon Sep 17 00:00:00 2001 From: Michael Date: Wed, 4 Mar 2026 12:40:32 +0100 Subject: [PATCH] Add GOPACS integration documentation Add user guide covering prerequisites, configuration, asset setup, and testing for GOPACS flex trading. Add developer guide covering source code components, UFTP data flow, inbound endpoint, authentication, and ISP handling. Ref: openremote/extensions#10 --- docs/developer-guide/gopacs-integration.md | 93 +++++++++++++++++++ docs/user-guide/domains/gopacs-integration.md | 50 ++++++++++ 2 files changed, 143 insertions(+) create mode 100644 docs/developer-guide/gopacs-integration.md create mode 100644 docs/user-guide/domains/gopacs-integration.md diff --git a/docs/developer-guide/gopacs-integration.md b/docs/developer-guide/gopacs-integration.md new file mode 100644 index 00000000..20191a8b --- /dev/null +++ b/docs/developer-guide/gopacs-integration.md @@ -0,0 +1,93 @@ +--- +sidebar_position: 18 +--- + +# GOPACS Integration + +This page covers the developer internals of the GOPACS integration. For an overview of what GOPACS is, how to configure it, and how to set up the assets, see the [GOPACS user guide](../user-guide/domains/gopacs-integration.md). + +The integration implements the **UFTP** (Universal Flexibility Trading Protocol) using the [Shapeshifter](https://github.com/shapeshifter) library, with OpenRemote acting as an **AGR (Aggregator)**. + +## Components + +The GOPACS extension lives in the `gopacs/` package within the extensions repository: + +| File | Purpose | +| --- | --- | +| `GOPACSHandler.java` | Core orchestrator — handles all UFTP message processing, signing, OAuth2 auth, and scheduling | +| `GOPACSServerResource.java` | JAX-RS interface for the inbound endpoint (`POST /gopacs/message`) | +| `GOPACSServerResourceImpl.java` | Delegates incoming XML to `GOPACSHandler::processRawMessage` | +| `GOPACSAuthResource.java` | RESTEasy client proxy for OAuth2 token requests | +| `GOPACSAddressBookResource.java` | RESTEasy client proxy for DSO participant lookup | +| `FlexRequestISPTypeHelper.java` | Converts ISP numbers to timestamps (with DST handling) | +| `OAuth2TokenResponse.java` | DTO for OAuth2 token responses | + +Related files outside this package: + +- `agent/EmsGOPACSAsset.java` — JPA entity defining the GOPACS asset type (contracted EAN, power attributes) +- `manager/EmsOptimisationService.java` — Manages `GOPACSHandler` lifecycle (creates/destroys handlers when assets are added/removed) +- `manager/EmsOptimisationSetupService.java` — Setup class that optionally creates GOPACS assets + +## Data flow + +OpenRemote acts as an **AGR (Aggregator)** in the UFTP protocol. The message exchange with the DSO (Distribution System Operator) follows this sequence: + +```mermaid +sequenceDiagram + participant DSO as DSO (Grid Operator) + participant OR as OpenRemote (AGR) + + DSO->>OR: 1. FlexRequest + Note right of OR: DSO requests flexibility for a congestion point
(contains ISPs with max/min power limits) + + OR->>DSO: 2. FlexRequestResponse + Note left of DSO: Auto-response after configurable delay + + OR->>DSO: 3. FlexOffer + Note left of DSO: Sent after flex offer delay
(mirrors request, price EUR 0.00) + + DSO->>OR: 4. FlexOfferResponse + Note right of OR: DSO accepts or rejects the offer + + DSO->>OR: 5. FlexOrder + Note right of OR: DSO orders the accepted flexibility
(updates predicted data points on asset) + + OR->>DSO: 6. FlexOrderResponse + Note left of DSO: Auto-response confirming the order +``` + +### How flex orders feed into optimisation + +1. `FlexOrder` power values are written as predicted data points on the `EmsGOPACSAsset` attributes (`powerLimitMaximumProfileFlexOrder`, `powerLimitMinimumProfileFlexOrder`) +2. `EmsOptimisationService.updatePowerLimitProfileTotalForecasts()` merges these GOPACS constraints with manual power limits from the parent `EmsEnergyOptimisationAsset` +3. The combined limits are used by the optimisation methods to constrain energy scheduling + +## Inbound endpoint + +The handler deploys a JAX-RS web application at `/gopacs`. Incoming signed UFTP XML messages are posted to: + +``` +POST /gopacs/message +Content-Type: application/xml +``` + +Processing steps: + +1. Deserialize the signed XML envelope +2. Verify the cryptographic signature using the sender's public key (from the address book) +3. Deserialize the UFTP payload +4. Process business logic (update asset attributes, schedule data points) +5. After a delay, send the auto-response (this ensures the HTTP response is returned first) + +## Authentication + +- **Inbound messages**: Verified using the DSO's public key, fetched from the GOPACS address book (`GET /v2/participants/DSO?contractedEan=`) and cached in memory +- **Outbound messages**: Signed with the private key from `GOPACS_PRIVATE_KEY_FILE`, delivered with an OAuth2 Bearer token obtained via client credentials flow from the GOPACS Keycloak instance + +## ISP handling + +ISPs (Imbalance Settlement Periods) are 15-minute intervals. `FlexRequestISPTypeHelper` converts ISP numbers to timestamps and includes special handling for European DST transitions (CET/CEST) on the last Sundays of March and October. + +## Testing + +For information on testing with the GOPACS testing environment, see the [GOPACS user guide](../user-guide/domains/gopacs-integration.md#testing). diff --git a/docs/user-guide/domains/gopacs-integration.md b/docs/user-guide/domains/gopacs-integration.md new file mode 100644 index 00000000..4e4bb9f0 --- /dev/null +++ b/docs/user-guide/domains/gopacs-integration.md @@ -0,0 +1,50 @@ +--- +sidebar_position: 3 +--- + +# GOPACS Integration + +[GOPACS](https://www.gopacs.eu/) (Grid Operators Platform for Ancillary Services) is a platform operated by Dutch grid operators (DSOs and TSO) to resolve grid congestion through flexibility trading. When the electricity grid is at risk of overloading, GOPACS sends flexibility requests to market participants (aggregators) who can adjust their energy consumption or production to relieve congestion. + +The communication between GOPACS and market participants uses the **UFTP** (Universal Flexibility Trading Protocol), part of the [USEF](https://www.usef.energy/) framework. For detailed GOPACS documentation, see: [GOPACS documents and manuals](https://www.gopacs.eu/en/documents-and-manuals/) + +## Prerequisites + +To participate in GOPACS flex trading through OpenRemote, you need: + +1. **A GOPACS account** — Register as a Trading Company at [gopacs.eu](https://www.gopacs.eu/) +2. **OAuth2 client credentials** (`client_id` and `client_secret`) — See [OAuth2 Client Credentials for API Clients](https://www.gopacs.eu/wp-content/uploads/2025/12/GOPACS-OAuth2-Client-credentials-for-API-Clients-03-12-2025.pdf) +3. **A signing key pair** — An Ed25519 private key file for signing UFTP messages. The corresponding public key must be registered with GOPACS +4. **A contracted EAN** — The EAN (European Article Number) identifying your grid connection point, as agreed with your DSO + +## Configuration + +The following environment variables must be set on the OpenRemote manager: + +| Variable | Required | Description | +| --- | --- | --- | +| `GOPACS_PRIVATE_KEY_FILE` | Yes | File path to the Ed25519 private key for signing UFTP messages | +| `GOPACS_CLIENT_ID` | Yes | OAuth2 client ID from GOPACS | +| `GOPACS_CLIENT_SECRET` | Yes | OAuth2 client secret from GOPACS | +| `GOPACS_PARTICIPANT_URL` | No | Address book base URL (default: `https://clc-message-broker.gopacs-services.eu`) | +| `GOPACS_OAUTH2_URL` | No | OAuth2 token endpoint (default: `https://auth.gopacs-services.eu/realms/gopacs/protocol/openid-connect/token`) | +| `GOPACS_RESPONSE_DELAY_SECONDS` | No | Delay before auto-responding to messages (default: `10`) | +| `GOPACS_FLEX_OFFER_DELAY_SECONDS` | No | Delay before sending a flex offer (default: `30`) | + +## Asset setup + +In OpenRemote, create an **EMS GOPACS Asset** as a child of an **EMS Energy Optimisation Asset** and set the `contractedEAN` attribute to your grid connection's EAN. This can also be done by enabling the "Include GOPACS" attribute on the **EMS Energy Optimisation Asset**. + +For more on setting up the Energy Management System, see [Energy Management](create-your-energy-management-system.md). + +## Testing + +GOPACS provides a dedicated testing environment. See [Testing UFTP API Flex Messages](https://www.gopacs.eu/wp-content/uploads/2025/12/GOPACS-Testing-receiving-and-sending-flex-messages-by-UFTP-testing-functionality-04-12-2025.pdf) for their guide on sending and receiving flex messages via the UFTP testing functionality. + +For additional context on the protocol and contract types, see [Flex Trading with CSC and ATR (UFTP Messages)](https://www.gopacs.eu/wp-content/uploads/2026/02/GOPACS-Flex-trading-with-Capacity-Limiting-Contracts-using-UFTP-messages-11-02-2026.pdf). + +To configure your Trading Company for testing Capacity Steering Contracts, follow: [Company Settings for CSC Participation](https://www.gopacs.eu/wp-content/uploads/2025/06/GOPACS-Company-settings-for-participating-in-CSC-Capacity-Steering-Contracts.pdf) + +## Developer documentation + +For details on the source code components, inbound endpoint, authentication internals, and ISP handling, see the [GOPACS developer guide](../../developer-guide/gopacs-integration.md).