Document GOPACS Redispatch attributes, state machine, and runtime behavior#35
Open
Miggets7 wants to merge 4 commits into
Open
Document GOPACS Redispatch attributes, state machine, and runtime behavior#35Miggets7 wants to merge 4 commits into
Miggets7 wants to merge 4 commits into
Conversation
…ion rules Fills the gaps between the redispatch implementation and ems/README.md: - Adds a Mermaid sequence diagram mirroring the UFTP one - Adds a 'Selection rules' note (MANDATORY preferred over VOLUNTARY) - Adds an 'Asset attributes' table covering all 19 redispatch attributes - Enumerates redispatchBidStatus values (NONE, PENDING_CONFIRMATION, CONFIRMED) - Adds a 'Resilience and polling' subsection covering the polling floor, fetch-failure semantics, mandatory API key, and handler-restart triggers - Clarifies that announcement history records every polled announcement (audit trail) and notes the 10k LRU bound - Cross-links the prerequisites back to the UFTP Getting Started section
- Clarify that redispatchAnnouncementHistory records announcements twice for selections (first-sight without effectivity, then a richer entry when selected) so the audit trail does not look duplicated to operators. - Note that the >=5 min poll floor clamps the configured interval, not a runtime backoff. - Spell out that persistent non-200 responses (e.g. 401 from a bad API key) keep stale announcements visible indefinitely; point to the log strings to grep for. - Add an example category for redispatchEanEffectivity and tighten the redispatchLastPoll description to "completed poll where the API responded". - Note that the diagram's selection-side actions only fire on a new selection, not every iteration.
Member
|
Adding this to the internal sprint board |
There was a problem hiding this comment.
Pull request overview
Documentation update to the EMS GOPACS README to fully describe the Redispatch (intraday congestion management) feature, aligning its detail level with the existing UFTP documentation and making runtime behavior and asset attributes explicit for operators and developers.
Changes:
- Added Redispatch prerequisites cross-linking back to UFTP “Getting Started” and documented the required Redispatch API key/env vars.
- Added a Redispatch sequence diagram plus explicit selection rules and bid-status state machine descriptions.
- Documented all Redispatch-related
EmsGOPACSAssetattributes (grouped table) and clarified resilience/polling and history semantics.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+219
to
+221
| - The polling interval is clamped to a minimum of 5 minutes because GOPACS recommends spacing requests at least that far apart. | ||
| - HTTP errors and exceptions on the announcements endpoint **skip the poll and preserve current attributes**, so transient API hiccups do not flap the bid status. Only a confirmed-empty response (HTTP 200 with no announcements) clears the active announcement and resets `redispatchBidStatus` to `NONE`. | ||
| - A *persistent* non-200 (e.g. an invalid API key returning 401, or a sustained outage) keeps the previously selected announcement on screen indefinitely. If `redispatchLastPoll` falls behind the configured interval, check the manager logs for `Failed to fetch announcements: HTTP …` (warning) or `Error fetching announcements` (severe). |
Contributor
Author
There was a problem hiding this comment.
Fixed in 803c773. The resilience note now states that any HTTP-200 poll yielding no selected announcement clears state, and enumerates the three cases — empty response, no open CONGESTIONMANAGEMENT announcements, and contracted EAN absent from the effectivity categories — matching the three clearAnnouncementAttributes() call sites in the handler. Only a failed fetch preserves prior state.
| Announcement and bid history are stored as time-series data points on `redispatchAnnouncementHistory` and `redispatchBidHistory` attributes, retained for 90 days. These are viewable in the OpenRemote history panel. | ||
| Announcement and bid history are stored as time-series data points on `redispatchAnnouncementHistory` and `redispatchBidHistory`, retained for 90 days and viewable in the OpenRemote history panel. | ||
|
|
||
| `redispatchAnnouncementHistory` records **every** polled announcement on first sight (including ones that the EAN-effectivity check later rejects), so the audit trail captures everything GOPACS returned during the handler's lifetime — not just the announcements that became active. When an announcement is then *selected* on a poll, a second, richer history entry is recorded with the matched effectivity details, so an active announcement will appear twice in the timeline (once at first sight, once on selection). To keep memory bounded for long-running handlers, the running set of already-recorded announcement IDs is capped at 10 000 entries (LRU-evicted). |
Contributor
Author
There was a problem hiding this comment.
Fixed in 803c773 by correcting the wording rather than the implementation. The set is add-only for dedup and IDs are never re-queried, so access-order LRU would behave identically to insertion order here — FIFO is the intended behavior. Updated both the README and the recordedAnnouncementIds code comment to say insertion-order/FIFO (the LinkedHashMap uses accessOrder=false).
Comment on lines
+146
to
+148
| loop every poll interval (≥ 5 min) | ||
| OR->>API: GET /machineannouncements (CONGESTIONMANAGEMENT, OPEN) | ||
| API-->>OR: announcements |
Contributor
Author
There was a problem hiding this comment.
Fixed in 803c773. The diagram label now reads ANNOUNCEMENT_OPEN, matching the ANNOUNCEMENT_STATE_OPEN constant and the surrounding prose.
Address Copilot review feedback on the redispatch documentation: - Resilience note now describes all three HTTP-200 conditions that clear the active announcement (empty response, no open CONGESTIONMANAGEMENT announcements, or contracted EAN absent from effectivity categories), instead of only the empty-response case. Clarifies that only a failed fetch preserves prior state. - Replace inaccurate "LRU-evicted" wording with insertion-order/FIFO in both the README and the recordedAnnouncementIds code comment; the set uses a LinkedHashMap with accessOrder=false. - Align the sequence diagram announcement state label with the actual ANNOUNCEMENT_OPEN constant used by the handler and prose.
Member
|
@igorrutka to approve |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documentation-only changes to
ems/README.mdfilling gaps in the Redispatch (Intraday Congestion Management) section. Before this PR, 14 of the 19 redispatch attributes onEmsGOPACSAssetwere undocumented and several non-obvious runtime behaviors (state machine, MANDATORY-vs-VOLUNTARY selection, transient-failure handling, mandatory API key, polling floor) were not surfaced. The Redispatch section now matches the level of detail already established by the UFTP section above it.What was added
CONGESTIONMANAGEMENT/ANNOUNCEMENT_OPENannouncements where the contracted EAN appears in some EAN-effectivity category, then prefersMANDATORYoverVOLUNTARY.EmsGOPACSAsset, its type, whether it is read-only, and a one-line purpose.redispatchSuggestedPowerandredispatchSuggestedVolumeare explicitly marked as not yet populated (pending bid pricing strategy follow-up).redispatchBidStatusvalues:NONE,PENDING_CONFIRMATION,CONFIRMED.GOPACS_REDISPATCH_API_KEY(logsSEVERE), togglingredispatchEnabledor changingcontractedEANrestarts the handler. Persistent non-200s (e.g. 401 from a bad API key) keep stale announcements visible — operator log strings are documented.Verification
Documentation only — no executable verification. Each claim was cross-checked against:
ems/src/main/java/org/openremote/extension/ems/agent/EmsGOPACSAsset.java(attribute definitions)ems/src/main/java/org/openremote/extension/ems/manager/gopacs/GOPACSRedispatchHandler.java(state machine constants, selection logic, failure handling, polling floor, API-key gate, history recording)ems/src/main/java/org/openremote/extension/ems/manager/EmsOptimisationService.java(lifecycle behaviors triggered by attribute changes)Checklist