[nicburgt]

What this adds

The initial version of flexmeasures-openadr3: a FlexMeasures plugin that acts as an
OpenADR 3.1 VEN (Virtual End Node), polling a VTN (Virtual Top Node) for
demand-response events and storing them as beliefs on FlexMeasures sensors.

It is built on the open-source openadr3-client
library and requires FlexMeasures ≥ v0.33.0 and Python ≥ 3.12.

Scope

Deliberately narrow for a first release:

• UI only — no CLI commands and no REST API endpoints. Everything is configured
  through a new dashboard at /flexmeasures-openadr3/dashboard
  (menu entry "OpenADR 3 Configuration").
• Two payload types — IMPORT_CAPACITY_LIMIT and EXPORT_CAPACITY_LIMIT, mapped to
  import-capacity-limit / export-capacity-limit sensors (kW, 15-minute resolution).
  Other OpenADR payload types are out of scope for now.

How it hangs together

• A VEN client (VTN base URL, OAuth client credentials, scopes) is stored as a
  FlexMeasures generic asset of type OpenADR VEN. Credentials are encrypted at rest in
  the asset attributes, using OPENADR_SECRETS_ENCRYPTION_KEY if set and falling back to
  FlexMeasures' SECRET_KEY.
• Each VEN client holds one or more polling schedules, each with its own OpenADR
  target filter, daily UTC trigger time, and sensor mapping.
• Each schedule enqueues an RQ job on the ingestion queue. The job fetches events
  from the VTN, keeps only the supported payload types, validates that active intervals
  from different events do not overlap, and writes TimedBeliefs under the data source
  OpenADR 3 VTN.
• The resulting sensors are intended to be wired into an asset's flex context — most
  naturally site-consumption-capacity and site-production-capacity on a building.

New plugin settings

Setting	Required	Purpose
OPENADR_SECRETS_ENCRYPTION_KEY	no	Encrypts VTN credentials at rest; falls back to SECRET_KEY
ALLOW_INSECURE_HTTP_VTN	no	Permits plain-HTTP VTN connections (development only)

Testing

• Unit tests for the VEN client repository and the fetch-job scheduler.
• An end-to-end test that runs a real OpenADR 3.1 VTN and a Postgres instance in
  containers (tests/test_container/), seeds events, and asserts the beliefs land on the
  right sensors.
• CI (.github/workflows/lint-and-test.yml) runs lint, mypy and the test suite; actions
  are pinned by SHA.
• examples/capacity-limits-ingestion-walkthrough/ contains a self-contained
  docker-compose walkthrough (VTN + Keycloak + FlexMeasures) for trying it by hand.

Known follow-ups

• Move recurring event fetching to rq.cron.CronScheduler #2 — the daily job re-enqueues itself, so the chain breaks if a worker dies mid-job;
  move to rq.cron.CronScheduler.

Review notes

uv.lock accounts for ~3.8k of the ~10k added lines; the reviewable surface is roughly
flexmeasures_openadr3/ (~2.2k lines) plus tests/ (~1.5k).

[nicburgt]

Migrate to using ingestion redis queue

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	mypy@​2.3.1
	pytest@​9.1.1
	pre-commit@​4.6.2
	flexmeasures@​1.0.0
	testcontainers@​4.15.0
	rq-dashboard@​0.9.0
	openadr3-client@​2.1.0
	pytest-cov@​7.1.0
	fakeredis@​2.37.1
	ruff@​0.16.5
	types-tzlocal@​5.1.0.1
	types-pytz@​2026.3.1.20260727
	types-requests@​2.33.0.20260712
	types-flask@​1.1.6
	types-click@​7.1.8
	types-redis@​4.6.0.20241004
	types-python-dateutil@​2.9.0.20260807
	types-docker@​7.2.0.20260827

View full report

[nhoening]

Just a question

[nhoening]

I'd like some clarification about dependencies. I'm not sure what the uv.lock file is used for?

Maybe it is useful for running only this plugin, and it installs FlexMeasures + dependencies?

How compatible is that with running multiple plugins?

In our practical experience, we have a FlexMeasures docker image, and we might create a dedicated one with some custom plugin with some extra requirements installed. And we might install extra plugins (like this one) even at the deployment step (e.g. with ansible).

[nicburgt]

The uv.lock file locks dependencies to a specific version to ensure a consistent environment.

Running multiple plugins should be relatively straightforward, flexmeasures has also updated to using UV for dependency management.

In the dockerfile in the repository you can see how the plugin can be installed the same way it was done before (just with a uv pip wrapper to ensure we are in a venv).

Furthermore, older plugins that just run on pip can also be installed in this manner

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: pypi pycparser is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: uv.lock → pypi/types-redis@4.6.0.20241004 → pypi/flexmeasures@1.0.0 → pypi/pycparser@3.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pycparser@3.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: pypi pycparser is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: uv.lock → pypi/types-redis@4.6.0.20241004 → pypi/flexmeasures@1.0.0 → pypi/pycparser@3.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pycparser@3.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[nicburgt]

Apologies for the delay, it's been a few hectic weeks in preparation of the residential flexibility event next week.

I'm going to be going over the codebase once more on the 22nd of June to process all feedback, take another look with fresh eyes at the codebase and answer any outstanding questions. I'll be in touch!

[nicburgt]

A few tests seem to have broken in the meantime with the new release, I'll fix this and the pipeline sometime this week when I find a quiet moment again.

Along with that, I'll look into implementing a better cronscheduler while i'm at it.

[nhoening]

Just a heads-up: We will support secret storage and token refreshing strartegies in FlexMeasures v1.0, see the merged PR and the docs here.

That implementation is partly inspired by code in this PR, so maybe we can simplify this PR? we can also do that in a follow-up, of course. We could create a version which is compatible with FM v0.33, then one that works with FM v1.0.

Would love to hear your thoughts.

[nhoening]

We decided that we will only support FlexMeasures >= v1.0, relying on its secrets infrastructure.

(v1.0 will be officially released very soon)

[TeaDrinkingProgrammer]

@nicburgt Don't forget to fix the DCO issues

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[nicburgt]

@TeaDrinkingProgrammer @nhoening @Flix6x

PR is ready to review again now! I will work on a seperate branch which inherits from this branch to create a "demo" example for the LF energy summit, I expect to open that PR sometime tomorrow.

[Flix6x]

Some open comment threads still. Should I just close them? They're not mine.

[nicburgt]

Some open comments are things I didnt yet have the time to implement but are a nice to have / nice improvement. I'll open issues for them on the repository in case someone wants to pick them up before I get to it.

The zizmor warnings (github actions linting) should vanish in a moment, as I just resolved them.