Drive a 5G cell on an O-RAN radio unit with 2 to 64 simulated UEs along a scripted load ladder, and record the offered load, the RAN's own records, the power draw and the clocks into one checksummed run directory.
ee-capture is the measurement harness behind the COSMOS energy-efficiency (EE) runs. One run brings up a cell with one of the COSMOS 5G stacks on a commercial O-RU, attaches a bank of simulated UEs (Amarisoft lteue on a USRP N310), and steps the offered load through a scenario so that the cell's PRB load goes from nearly idle to saturated. While it runs, it pulls the O-RU's power from the testbed's power monitoring, keeps the RAN's logs and statistics, and records every host's clock and run-start provenance. At the end it writes SHA256SUMS over everything on the shared output storage, so a finished run is a sealed dataset.
A run can also record the cell's downlink control information (DCI) with the DCI decoder add-on (available on restricted capture images). That add-on is optional: by default (eecap_capture: auto) the run captures DCIs when the capture host has the add-on and its decoder, and otherwise skips only the capture and its log processing and runs everything else. Without it, ee-capture is a complete traffic-and-power experiment that needs only two nodes.
After completing this tutorial you will be able to:
run_record.json whether the DCI capture ran, and if not, why;eecap_capture: auto, true or false for what your run must contain.| Difficulty | Advanced |
|---|---|
| Estimated time | the run time of the scenario plus bring-up and teardown; the 64-UE PRB-ladder run below took 1 h 42 min of scenario |
| Domain / sandbox | O-DU in osc, sb1 or rrail; UE host in sb1; run from the console of the O-DU's domain |
| Image | O-DU: the stack's image (ocudu.ndz, duranta.ndz, aerial-26-2-gh200.ndz, Amarisoft); UE host: lte5gue.ndz |
| Transmits? | yes: the O-RU and the UE bank's N310, on the carrier of the chosen O-RU and cell |
| Last verified | 2026-11-17: automatic DCI capture, skip path (two nodes), sealed run on the GH200 O-DU. The run called ee-capture_manual.sh directly from a staged copy whose controller and capture logic are identical to the released cosmos-experiments-ee-capture 0.1.0-11 (its OCUDU-on-GH200 bring-up files were newer); cosmos-tutorial run ee-capture itself not yet run on hardware. The capture path with the add-on taken from the capture host: not measured in a full run |
Background knowledge
ee-capture runs their bring-up, so their pages explain the cell.lteue as a bank of simulated UEs.Account & access
Devices / nodes
| Resource | Role | Qty | Notes |
|---|---|---|---|
| O-DU server | runs the cell (gNB, core) | 1 | a 7.2 fronthaul server in osc, sb1 or rrail, or a GH200 for the Aerial frameworks |
| UE host | lteue with its USRP N310, and the traffic sink |
1 | sb1 |
| O-RU | the radio | 1 | LiteOn, Benetel or Foxconn, per eecap_oru |
| capture host | DCI capture | 0 or 1 | optional; only useful with the restricted capture image |
Disk images
| Image | Load onto | Provides |
|---|---|---|
the stack's image (ocudu.ndz, duranta.ndz, aerial-26-2-gh200.ndz, or the Amarisoft image) |
O-DU | the gNB build that cosmos-tutorial check looks for |
lte5gue.ndz |
UE host | Amarisoft lteue and ltesim_server |
| the restricted capture image (ask the testbed team) | capture host | the DCI decoder add-on at /opt/cosmos-capture/dci; optional |
Software components
| Component | Version | Source |
|---|---|---|
cosmos-experiments-ee-capture |
0.1.0-11 | installed on every console |
cosmos-ue-traffic |
1.3 | installed on every console (the load generator) |
cosmos-orchestration |
0.1.0-481 or later (two-node runs) | installed on every console |
the stack's own tutorial (ocudu-72, duranta-72 or duranta-aerial-72) |
as installed | ee-capture calls its bring-up |
| Domains | osc, sb1, rrail |
| Nodes | 2 or 3, in this order: o-du, ue-host, capture-host (optional), named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh, scp, omf |
cosmos-tutorial check ee-capture verifies, on each node:
o-du)o-du)ue-host)ue-host)ue-host)o-du, ue-host, capture-host)Not in the package - you provide:
The console runs the controller and reaches each role host directly in its own domain or through the other domain's console. The O-DU drives the O-RU over the fronthaul. lteue on the UE host transmits and receives through its N310 as up to 64 UEs; their traffic runs to a sink on the UE host through the core on the O-DU. Every role host writes into the same run directory on the output share (eecap_output), which must be mounted on each of them. With a capture host, its receiver listens to the same cell and writes its records there too.
ssh <username>@console.<o-du domain>.cosmos-lab.org
cosmos-tutorial params ee-capture
OMF_NODES=<o-du>,<ue-host> cosmos-tutorial check ee-capture
This is a long, multi-host run that also decides per framework how the cell comes up; there is no useful command-by-command equivalent. The manual mode runs the controller script ee-capture_manual.sh directly, and the Ansible mode adds node checks around the same script.
export OMF_NODES=<o-du>,<ue-host>[,<capture-host>]
cosmos-tutorial check ee-capture
cosmos-tutorial run ee-capture # ansible
cosmos-tutorial run ee-capture --mode manual # manual
cosmos-tutorial run ee-capture --mode teardown # teardown
For example, a run without a capture host (the DCI capture is skipped):
cosmos-tutorial run ee-capture --mode manual --params my.yml <o-du> <ue-host>
and with one (the DCI capture runs if that host has the add-on):
cosmos-tutorial run ee-capture --mode manual --params my.yml <o-du> <ue-host> <capture-host>
The 2026-11-17 hardware runs called ee-capture_manual.sh directly with the nodes as arguments, from a staged copy with the same controller as the released package; the cosmos-tutorial run wrapper and the Ansible mode have not yet run on hardware.
Change any of these with cosmos-tutorial run ee-capture --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params ee-capture prints the file.
| Key | Default | Meaning |
|---|---|---|
eecap_output |
/mnt/pool/shared/rrail2 |
Where the run directory goes. eecap_output_fs is the mount every role checks before writing: a run refuses to start if the output is not on it (an unmounted share would fill the node's local disk and look like success). |
eecap_output_source |
bucket1.cosmos-lab.org:/mnt/pool/shared |
mounted on a role host that lacks it |
eecap_output_fs |
/mnt/pool/shared |
the NFS MOUNT POINT (bucket1:/mnt/pool/shared); rrail2 is a directory on it |
eecap_framework |
ocudu |
RAN under test. |
eecap_oru |
liteon |
liteon | benetel | foxconn |
eecap_scenario |
ee-ue-sweep-v2.yml |
Offered load (tools/ue-traffic). |
eecap_cell |
ocudu-liteon-3750-100.yml |
|
eecap_ue_count |
16 |
2..64 (owner, 2026-11-11), capped by the cell's ue_max_count |
eecap_ue_tx_gain_offset |
auto |
lteue UL digital backoff, dB: auto = -24 (every framework; lteue's own default -14 clips) |
eecap_attach_min_ratio |
0.95 |
gate: attached / powered-on UEs, held over the run; below it the run FAILS |
eecap_du_watchdog_s |
30 |
mid-run DU watchdog period, s (0 = off): a DU that dies during the load stops it; the run is FAILED, never sealed |
eecap_markers |
True |
one UE 2 s on / 1 s off / 2 s on, at the start and end of the run |
eecap_marker_rate_mbps |
50 |
marker bursts below saturation: at full buffer the gNB queues and only the first |
eecap_warmup_ues |
2 |
attach + detach 2 other UEs before the first markers: a DCI decoder starts UE-specific |
eecap_health_gate |
False |
with the DCI capture add-on: true = do not seal a run whose capture fails its health check |
eecap_capture |
auto |
DCI capture: an optional add-on that comes with the capture image (ask the testbed team); the capture host decides. auto = capture when the capture host has the add-on and its decoder, otherwise skip it (the reason goes into events.jsonl, run_record.json and capture_run.json) and run everything else; true = capture required (the run refuses without it); false = never. |
eecap_dci_addon |
`` | |
eecap_power_devices |
0 items | Power streams pulled after the run (power_export.py dc7c637): each is a device name its exporter knows. |
eecap_ran_params |
0 keys | Framework tutorial keys passed through to the RAN bring-up as they are (e.g. {ocudu_center_freq_mhz: 3750}). |
eecap_ue_radio_node |
sdr1-s1-lg1.sb1.cosmos-lab.org |
lteue: its N310 and the traffic sink. |
eecap_sink_addr |
192.168.100.1 |
the core's UE pool gateway (teaching content, as in ocudu-72's wiki addresses) |
eecap_lteue_port |
9002 |
|
eecap_oru_power_device |
liteon1 |
Power: the O-RU's collector name (the PDU outlet label) and Prometheus (a host name, resolved at run time). |
eecap_prometheus |
http://monitor.rrail.cosmos-lab.org:9090 |
|
eecap_grafana_host |
monitor.rrail.cosmos-lab.org |
Grafana (oran-ee, file provisioning): after finalize the run's dashboard is pushed here; empty = do not push. |
The controller runs one ordered sequence across the hosts:
run_record.json.lteue and the traffic sink, then the seeded scenario, with marker bursts from one UE at the start and end so that every record can be aligned in time.eecap_attach_min_ratio (0.95) of the powered-on UEs stayed attached. A run below it fails and is not sealed.capture_run.json and finally SHA256SUMS, verify the copy on the share, and remove the local staging on the nodes.eecap_capture takes three values:
| Value | Meaning |
|---|---|
auto (default) |
Capture when the capture host has the add-on and its decoder. Otherwise skip the capture and run everything else. |
true |
Capture is required. The run refuses before anything is touched, with !! DCI capture required (eecap_capture: true) but not available: <reason>. |
false |
Never capture. Nothing is probed. |
Where the add-on is looked for. The eecap_dci_addon parameter, then the EECAP_DCI_ADDON environment variable, then /opt/cosmos-capture/dci. An absolute path is a directory on the capture host: the controller runs the add-on's probe there over the run's SSH, and the probe reports whether the add-on and its decoder are present. Only if the probe answers yes does the run capture. The add-on comes with the restricted capture image; a user who cannot load that image has no add-on on the capture host, and the run simply skips the capture.
When the capture is skipped, the run prints
## DCI capture skipped: <reason>
writes a capture-skipped event into events.jsonl, and records dci_capture with state, requested, reason and detail in run_record.json and capture_run.json. The reasons:
| Reason | Meaning |
|---|---|
no-capture-host |
the run was given two nodes (<o-du> <ue-host>) |
no-addon-on-host |
no add-on at the path on the capture host; the detail names the host's image (not the capture image, or one you could not load) |
no-addon-local |
a relative development path that does not exist |
decoder-missing |
the add-on is there but its decoder is not executable |
scanner-missing |
aerial only: no channel scanner for the scan before bring-up |
addon-incomplete |
the add-on directory is incomplete |
probe-failed |
no usable answer from the capture host |
A skipped run then behaves exactly like eecap_capture: false: no channel scans, no decoder, no capture-health gate and no capture role. Everything else runs unchanged: the cell, the load, power, clocks, the RAN records, the attach gate and the seal. The single-cell check uses the O-RU ping census (which O-RUs answer) and the PCI that lteue reports serving it (single_cell.json) instead of decoded DCIs.
From the run of 2026-11-17 (rrail-20261117T094854Z-soe3sa, OCUDU on NVIDIA Aerial with a Foxconn O-RU, two nodes, no capture host):
## run rrail-20261117T094854Z-soe3sa: o-du srv9.rrail.cosmos-lab.org, ue-host srv1-lg1.sb1.cosmos-lab.org, capture-host none -> /mnt/pool/shared/rrail2/rrail-20261117T094854Z-soe3sa
## DCI capture skipped: no capture host given
...
## 4. lteue on srv1-lg1.sb1.cosmos-lab.org: 64 UEs, scenario ee-prb-ladder-v2.yml
...
## attach gate: {"ok": true, "problems_total": 0, "flagged_total": 0}
...
## done: /mnt/pool/shared/rrail2/rrail-20261117T094854Z-soe3sa (82 files checksummed); records in /home/<username>/cosmos-runs/ee-capture/rrail-20261117T094854Z-soe3sa
and in run_record.json:
"capture_host": null,
"dci_capture": {
"state": "skipped",
"requested": "auto",
"reason": "no-capture-host",
"detail": "no capture host given"
},
EXIT 0 and the ## done: line; the attach gate line says "ok": true.run_record.json and capture_run.json carry the same dci_capture block, and events.jsonl has the matching capture-skipped event (or none, when the capture ran).sha256sum -c SHA256SUMS in the run directory passes.Runs that exercised the automatic DCI capture on hardware (cell and UE platforms from the run-start manifests):
| O-DU platform | UE host platform | Framework, O-RU, UEs | DCI capture | Result | Measured |
|---|---|---|---|---|---|
| NVIDIA GH200: Grace, 72 Arm Neoverse V2 cores + Hopper GPU (Aerial L1) | 2× Intel Xeon Gold 6226, 24 cores / 24 threads | ocudu-aerial, Foxconn, up to 64 |
skipped, no-capture-host |
attach gate ok, sealed (82 files); top load step DL/UL 158/115 Mbit/s (1 UE), 176/114 (8 UEs), 229/133 (64 UEs) | 2026-11-17, aerial-26-2-gh200-20261114 / lte5gue-20261115b |
capture with the add-on from the capture host (/opt/cosmos-capture/dci) |
on | not measured in a full run (the probe alone was run on a capture host) |
The run tears down its own units, the gNB and the O-RU when it ends or is stopped. To clean up after an interrupted run:
cosmos-tutorial run ee-capture --mode teardown
Then power the O-RU off if it is still on, and release your reservations.
| Symptom | Likely cause | Fix |
|---|---|---|
## DCI capture skipped: no capture host given |
the run got two nodes | expected; add a third node with the capture image if you need DCIs |
## DCI capture skipped: ... with no-addon-on-host |
the capture host is not on the capture image | expected for public use; with eecap_capture: auto the run continues without DCIs |
!! DCI capture required (eecap_capture: true) but not available |
true demands the add-on |
use auto, or load the capture image on the capture host |
run ee-capture from console.<domain> |
started from another domain's console | log into the console of the O-DU's domain |
cannot create ... (share not mounted on ...) |
the output share is not mounted on a role host | set eecap_output_source and eecap_output_fs, or mount it; for a local run set both to a local path |
| the attach gate fails | fewer than 95 % of the UEs stayed attached | read the RAN log in the run directory; the run is not sealed |
| the run starts but the cell never came up | the bring-up returned without a live gNB | check the O-DU's gNB log before trusting a run; a run on no cell fails the attach gate |
Package cosmos-experiments-ee-capture 0.1.0-12 - on every console it is released to (cosmos-tutorial list shows the installed version). The code is installed on the console in /usr/share/cosmos-experiments/ee-capture/. To change anything, cosmos-tutorial copy ee-capture puts an editable copy in the current directory, and cosmos-tutorial run ee-capture then runs that copy instead of the installed one (cosmos-tutorial which ee-capture shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-ee-capture/usr/share/cosmos-experiments/ee-capture.
Author(s): COSMOS team · Last verified: 2026-11-17 (automatic DCI capture, skip path; capture from the capture host not measured) · Tested image/release: cosmos-experiments-ee-capture 0.1.0-11, aerial-26-2-gh200-20261114, lte5gue-20261115b · Tags: 5g, oran, energy-efficiency, lteue, power, dataset