Implementation of the E3 Agent for dApps and E3AP (no service models)

[Thecave3]

These changes introduce an E3 Agent for dApps in the OAI codebase. dApps are real-time microservices designed to operate within the O-RAN ecosystem, enabling sub-10 ms Artificial Intelligence (AI) routines in the Radio Access Network (RAN).
The E3 Agent enables spectrum sensing, frequency-domain signal logging, and dynamic PRB (Physical Resource Block) policies through IPC/ZMQ communication with dApps or xApps.

The dApps are designed for co-location with the CU/DU, where it can interact directly with user-plane data to enable different network management scenarios such as optimizing network slicing, scheduling, and resource management.
A python library for the creation of the dApps is available here.

Additional information about dApps:

• Paper on the dApp architecture
• dApp framework presentation
• Tutorial on dApp deployment on OAI

As agreed in the original MR, this PR includes only the agent lifecycle, configuration parsing, build plumbing, and the nr-softmodem init/destroy hook.
It registers zero service models, so it builds and runs as an idle agent. Concrete service models (e.g. spectrum sensing) and the PHY/MAC hooks that drive them follow in later PRs.

Opt-in and dependencies

• Gated behind the E3_AGENT CMake option (OFF by default) / the --build-e3 build flag.
  The default build is unaffected — e3ap is only compiled and linked into nr-softmodem
  when E3_AGENT=ON.

• When enabled, requires the external libe3 library (vendor-neutral E3AP C++ lib), discovered via pkg_check_modules(CLIBE3 REQUIRED libe3). It is not vendored.

  Install libe3 (Debian/Ubuntu):

  git clone https://github.com/wineslab/libe3 && cd libe3
  ./build_libe3 -I      # installs deps: build-essential cmake pkg-config libzmq3-dev asn1c nlohmann-json3-dev libsctp-dev ...
  ./build_libe3 --install      # release build + installation

Build & test

Tested in RFsim: the gNB initializes the E3 agent, opens its setup socket (/tmp/dapps/setup),
registers zero service models, and runs without crashing.

Configuration

The agent reads an optional E3Configuration section from the gNB config file (parsed only when
E3_AGENT=ON). If absent, it falls back to built-in defaults (posix/ipc).

E3Configuration : {
    link = "zmq";        # posix | zmq
    transport = "ipc";   # tcp | sctp | ipc
};

The same parameters can be overridden on the command line (no config-file edit required):

sudo ./nr-softmodem -O <gnb.conf> ... --E3Configuration.link zmq --E3Configuration.transport ipc

Validated link/transport combinations: (zmq,ipc) (zmq,tcp) (posix,tcp) (posix,sctp)
(posix,ipc).

Notes

• I have added a new log component E3AP specific for the ops performed by the E3 Agent.
• This PR ships no gNB config file; the E3Configuration block / CLI override above is the
  documented way to enable the agent. Example configs follow in the next PRs.

[durantabot]

CI Build: #364 | Failed on the following stages:

• RAN-gNB-N300-Timing-Phytest-LDPC
• RAN-SA-FHI72-CN5G
• RAN-SA-B200-Module-SABOX-Container
• RAN-SA-AERIAL-CN5G
• RAN-RF-Sim-Test-5G
• OAI-CN5G-COTS-UE-Test

[durantabot]

CI Build: #423 | Failed on the following stages:

• RAN-Ubuntu-Image-Builder

[arora-sagar]

@Thecave3 Are you planning to put a document/tutorial on how to use the E3 agent with the dApps framework?

Also, it will be nice if the document covers the definition and explanation of dApps

[arora-sagar]

Also, a CI testing scenario would be good, so we can make sure that the implementation is working consistently.

[Thecave3]

@Thecave3 Are you planning to put a document/tutorial on how to use the E3 agent with the dApps framework?

Also, it will be nice if the document covers the definition and explanation of dApps

Yes sure, I can add a README.md inside the E3AP folder if it helps. There is already a tutorial on deploying and using dApps with OAI at https://openrangym.com/tutorials/dapps-oai that covers the full setup, from installing the dApp library to running a spectrum-sharing example against the gNB. A more focused document specific to the E3 agent configuration (the E3Configuration block, link/transport options, and how to wire a new service model)

Also, a CI testing scenario would be good, so we can make sure that the implementation is working consistently.

The plan is to add a CI stage that installs libe3 (from its repo) before invoking --build-e3, similar to how FlexRIC is handled. I was thinking of deferring this to a later PR that includes also a Service Model so it can be reviewed independently from the agent framework itself. Any advise on what is the best approach and what would you like to check here?

[Thecave3]

I left the TOC to be aligned with other .md files in the repo, but it's not rendered in github.

[durantabot]

CI Build: #432 | Failed on the following stages:
The pipeline may have failed due to CI, validation, or scripting error. See the build for more details.

[Thecave3]

Not sure if this is related with the PR

Found unhandled hudson.remoting.ProxyException exception:
org.kohsuke.github.HttpException: {
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest",
  "status": "401"
}
	PluginClassLoader for github-api//org.kohsuke.github.GitHubConnectorResponseErrorHandler$1.onError(GitHubConnectorResponseErrorHandler.java:88)
	PluginClassLoader for github-api//org.kohsuke.github.GitHubClient.detectKnownErrors(GitHubClient.java:504)
	PluginClassLoader for github-api//org.kohsuke.github.GitHubClient.sendRequest(GitHubClient.java:464)
	PluginClassLoader for github-api//org.kohsuke.github.GitHubClient.sendRequest(GitHubClient.java:427)
	PluginClassLoader for github-api//org.kohsuke.github.Requester.fetch(Requester.java:85)
	PluginClassLoader for github-api//org.kohsuke.github.GHRepository.read(GHRepository.java:147)
	PluginClassLoader for github-api//org.kohsuke.github.GHPerson.getRepository(GHPerson.java:162)
	PluginClassLoader for pipeline-githubnotify-step//org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep.getRepoIfValid(GitHubStatusNotificationStep.java:270)
	PluginClassLoader for pipeline-githubnotify-step//org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep.access$100(GitHubStatusNotificationStep.java:80)
	PluginClassLoader for pipeline-githubnotify-step//org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep$Execution.run(GitHubStatusNotificationStep.java:383)
	PluginClassLoader for pipeline-githubnotify-step//org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep$Execution.run(GitHubStatusNotificationStep.java:365)
	PluginClassLoader for workflow-step-api//org.jenkinsci.plugins.workflow.steps.AbstractSynchronousNonBlockingStepExecution$1$1.call(AbstractSynchronousNonBlockingStepExecution.java:47)
	hudson.security.ACL.impersonate2(ACL.java:446)
	PluginClassLoader for workflow-step-api//org.jenkinsci.plugins.workflow.steps.AbstractSynchronousNonBlockingStepExecution$1.run(AbstractSynchronousNonBlockingStepExecution.java:44)
	java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:572)
	java.base/java.util.concurrent.FutureTask.run(FutureTask.java:317)
	java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	java.base/java.lang.Thread.run(Thread.java:1583)

[rorsc]

Not sure if this is related with the PR

[...]

I don't think so, it was on notifying Github. The actual build was/is fine. you can ignore that

[rorsc]

I left the TOC to be aligned with other .md files in the repo, but it's not rendered in github.

Good, thanks. I left them in case people have links to Gitlab (which is now a mirror), so the TOC would show there. On Github, it automatically renders a TOC which you access by clicking on a button at the top right.

[durantabot]

CI Build: #460 | Failed on the following stages:

• OAI-CN5G-COTS-UE-Test
• RAN-NSA-B200-Module-LTEBOX-Container
• RAN-SA-B200-Module-SABOX-Container
• RAN-gNB-N300-Timing-Phytest-LDPC
• RAN-SA-FHI72-MPLANE-CN5G
• RAN-SA-OAIUE-CN5G
• RAN-SA-AW2S-CN5G
• RAN-RF-Sim-Test-5G
• RAN-SA-AERIAL-OAIUE-CN5G

[durantabot]

CI Build: #475 | Failed on the following stages:

• RAN-Ubuntu-Jetson-Image-Builder
• RAN-Ubuntu-ARM-Image-Builder
• RAN-Ubuntu-Image-Builder

[durantabot]

CI Build: #507 | Failed on the following stages:

• OAI-CN5G-COTS-UE-Test
• RAN-NSA-B200-Module-LTEBOX-Container
• RAN-SA-Multi-Antenna-CN5G
• RAN-gNB-N300-Timing-Phytest-LDPC
• RAN-SA-FHI72-MPLANE-CN5G
• RAN-SA-OAIUE-CN5G
• RAN-SA-B200-Module-SABOX-Container
• RAN-RF-Sim-Test-5G
• RAN-SA-AERIAL-CN5G

[durantabot]

CI Build: #504 | Failed on the following stages:

• OAI-CN5G-COTS-UE-Test
• RAN-gNB-N300-Timing-Phytest-LDPC
• RAN-SA-FHI72-MPLANE-CN5G
• RAN-SA-B200-Module-SABOX-Container
• RAN-NSA-B200-Module-LTEBOX-Container
• RAN-SA-OAIUE-CN5G
• RAN-RF-Sim-Test-5G
• RAN-SA-AERIAL-CN5G

[rorsc]

please make so that all commits compile, I think it's a small change and would be potentially useful if we need to verify stuff later, or for bisecting

[arora-sagar]

@Thecave3 Are you planning to put a document/tutorial on how to use the E3 agent with the dApps framework?
Also, it will be nice if the document covers the definition and explanation of dApps

Yes sure, I can add a README.md inside the E3AP folder if it helps. There is already a tutorial on deploying and using dApps with OAI at https://openrangym.com/tutorials/dapps-oai that covers the full setup, from installing the dApp library to running a spectrum-sharing example against the gNB. A more focused document specific to the E3 agent configuration (the E3Configuration block, link/transport options, and how to wire a new service model)

Thanks for the documentation.

Also, a CI testing scenario would be good, so we can make sure that the implementation is working consistently.

The plan is to add a CI stage that installs libe3 (from its repo) before invoking --build-e3, similar to how FlexRIC is handled. I was thinking of deferring this to a later PR that includes also a Service Model so it can be reviewed independently from the agent framework itself. Any advise on what is the best approach and what would you like to check here?

Yes, it is fine to do it in another PR.

[durantabot]

CI Build: #627 | Failed on the following stages:

• OAI-CN5G-COTS-UE-Test
• RAN-SA-FHI72-CN5G
• OAI-FLEXRIC-RAN-Integration-Test
• RAN-SA-AW2S-CN5G
• RAN-SA-Multi-Antenna-CN5G
• RAN-gNB-N300-Timing-Phytest-LDPC
• RAN-SA-AERIAL-OAIUE-CN5G
• RAN-SA-AERIAL-CN5G
• RAN-RF-Sim-Test-5G