From d782ed7e027935a649198a88de2d7ab7fbeeebab Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" Date: Tue, 29 Sep 2026 21:46:34 +0200 Subject: [PATCH 1/4] docs: apply the 5G-MAG README format Problem The root README did not follow the common 5G-MAG README layout (banner, status/version/licence badges, At a glance, template sections), and some of its prose no longer matched the code. [code-derived] Basis No clause governs this; documentation layout from the 5G-MAG repository template (repo-starter, templates/README.md). Raised by Review by the repository owner. Change README.md restructured into the template sections with a banner (.github/banner.svg), badges, a link row and an At a glance table. Prose rewritten and corrected against the code at cef77bc. Every code block is byte-identical to the previous README; no command was added, removed or changed. Corrections are listed in the pull request. Verification T0: checked by a script comparing the old and new README: all 8 code blocks and code-bearing table rows identical, none added or dropped. Nothing built or run. Not in this change Sub-folder READMEs and any code. --- .github/banner.svg | 25 ++++++++ README.md | 142 ++++++++++++++++++++++++++++++++------------- 2 files changed, 127 insertions(+), 40 deletions(-) create mode 100644 .github/banner.svg diff --git a/.github/banner.svg b/.github/banner.svg new file mode 100644 index 0000000..21799bc --- /dev/null +++ b/.github/banner.svg @@ -0,0 +1,25 @@ + + Reference Tools · UE Data Collection, Reporting and Event Exposure: Generic 3GPP Data Collection AF + + + + + + + + + + + + + + + + + + + + + + + diff --git a/README.md b/README.md index ca5f83f..e26cdfb 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,83 @@ -

5G Data Collection Application Function

- Version - Under Development - License + Reference Tools · UE Data Collection, Reporting and Event Exposure: Generic 3GPP Data Collection AF

+

+ 5G Data Collection Service Provider library and Application Function, implementing some of the + data reports and events of 3GPP TS 26.531, TS 26.532 and TS 29.517. +

+ +

+ Status: under development + Version + License: 5G-MAG Public License v1.0 +

+ +

+ Project page  ·  + Issues  ·  + Contributing +

+ +--- + +## At a glance + +| | | +|---|---| +| **Implements** | Some of the data reports and events defined in [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm), [3GPP TS 26.532](https://www.3gpp.org/DynaReport/26532.htm) and [3GPP TS 29.517](https://www.3gpp.org/DynaReport/29517.htm) | +| **Part of** | [UE Data Collection, Reporting and Event Exposure](https://www.5g-mag.com/reference-tools/data-collection/), alongside [cmcd-toolkit](https://github.com/5G-MAG/cmcd-toolkit) | + ## Introduction -This repository provides a 5G Data Collection Service Provider library and Application Function. The library is designed to be used by this stand alone Application Function or to be used as an embedded service within other Application Functions such as the [5GMS Application Function](https://github.com/5G-MAG/rt-5gms-application-function). The library can provide the interfaces designated as R1-R6 in the [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm) specification (See Clause 4.2). The defautl Application Function implementation here implements some of the data reports and events defined in [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm), [3GPP TS 26.532](https://www.3gpp.org/DynaReport/26532.htm) and [3GPP TS 29.517](https://www.3gpp.org/DynaReport/29517.htm). +This repository holds two things: a 5G Data Collection Service Provider library, and a +standalone Data Collection Application Function (AF) built on it. The library can also be +embedded in other Application Functions, such as the +[5GMS Application Function](https://github.com/5G-MAG/rt-5gms-application-function). -Additional information can be found at: https://5g-mag.github.io/Getting-Started/pages/ue-data-collection-reporting-exposure/ +More information is on the [project page](https://www.5g-mag.com/reference-tools/data-collection/). ### 5G Data Collection Service Provider library -The library is designed to be used by this stand alone Application Function or to be used as an embedded service within other Application Functions such as the [5GMS Application Function](https://github.com/5G-MAG/rt-5gms-application-function). The library can provide the interfaces designated as R1-R6 in the [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm) specification (See Clause 4.2). Individual interfaces can be disabled at application start up by the controlling Application Function if it implements those, or similar, interfaces itself. The Application Function interacts with the Service Provider library via a C function API designed to work with Network Functions written for [Open5GS](https://open5gs.org/). +The library can provide the interfaces designated R1-R6 in [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm) +(see clause 4.2). The Application Function that embeds it can disable individual interfaces at +start-up if it implements those, or similar, interfaces itself. The Application Function uses the +library through a C function API designed for Network Functions written for +[Open5GS](https://open5gs.org/). ### 5G Data Collection Application Function -This Application Function uses the Service Provider library to implement some of the data reports and events defined in [3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm), [3GPP TS 26.532](https://www.3gpp.org/DynaReport/26532.htm) and [3GPP TS 29.517](https://www.3gpp.org/DynaReport/29517.htm). +The default Application Function in this repository uses the Service Provider library to +implement some of the data reports and events defined in +[3GPP TS 26.531](https://www.3gpp.org/DynaReport/26531.htm), +[3GPP TS 26.532](https://www.3gpp.org/DynaReport/26532.htm) and +[3GPP TS 29.517](https://www.3gpp.org/DynaReport/29517.htm). It is a Network Function based on the +[Open5GS](https://open5gs.org/) framework, and is meant to integrate with other 5G application suites +through its HTTP APIs. + +A list of currently supported features will be published on the +[project page](https://www.5g-mag.com/reference-tools/data-collection/). -This is implemented as a Network Function based on the [Open5GS](https://open5gs.org/) framework. The runtime should integrate with other 5G application suites via the HTTP APIs. +## Specification -A list of currently supported features is available [here (actual page TDB)](https://5g-mag.github.io/Getting-Started/pages/ue-data-collection-reporting-exposure/). +Built against 3GPP TS 26.531, TS 26.532 and TS 29.517; this README states no document version. +The OpenAPI bindings are generated at build time from the 5G_APIs repository, by default at tag +`TSG105-Rel18` (Release 18, set by the `fiveg_api_release` and `fiveg_api_approval` options in +`meson_options.txt`). + +Clause-by-clause coverage, and what is still absent, is recorded on the project page rather than +here: ## Install dependencies ### Building with the regression tests -If you wish to run the optional regression tests then you will need to use Ubuntu 24.04 (Noble Numbat) or later as the regression tests rely on command line tools from curl v8.3.0 or later and util-linux v2.39 or later. To install the dependencies, including those for the regression tests, then you can use the following commands on Ubuntu 24.04 or later. +The optional regression tests need Ubuntu 24.04 (Noble Numbat) or later, because they rely on +command-line tools from curl v8.3.0 or later and util-linux v2.39 or later. To install the +dependencies, including those for the regression tests, on Ubuntu 24.04 or later: ```bash sudo apt install git ninja-build build-essential flex bison libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev libnghttp2-dev libmicrohttpd-dev libcurl4-gnutls-dev libtins-dev libtalloc-dev libpcre2-dev curl wget default-jdk cmake jq util-linux-extra python3-h2 @@ -36,7 +86,7 @@ sudo python3 -m pip install --upgrade meson ### Building without the regression tests -If you are not planning on running the regression tests then you can use these commands on Ubuntu to install the build dependencies. +If you do not plan to run the regression tests, install the build dependencies on Ubuntu with: ```bash sudo apt install git ninja-build build-essential flex bison libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev libnghttp2-dev libmicrohttpd-dev libcurl4-gnutls-dev libtins-dev libtalloc-dev libpcre2-dev curl wget default-jdk cmake @@ -47,9 +97,8 @@ sudo python3 -m pip install --upgrade meson Release tar files can be downloaded from . -The source can be obtained by cloning the github repository. - -For example to download the latest release you can use: +The source can be obtained by cloning the GitHub repository. For example, to download the latest +release: ```bash cd ~ @@ -58,7 +107,7 @@ git clone --recurse-submodules https://github.com/5G-MAG/rt-data-collection-appl ## Building -The build process requires a working Internet connection as the API files are retrieved at build time. +The build needs a working Internet connection, because the API files are retrieved at build time. To build the 5G Data Collection Application Function from the source: @@ -68,24 +117,10 @@ meson build ninja -C build ``` -**Note:** Errors during the `meson build` command are often caused by missing dependencies or a network issue while trying to -retrieve the API files and `openapi-generator` JAR file. See the -`~/rt-data-collection-application-function/build/meson-logs/meson-log.txt` log file for the errors in greater detail. Search for -`generator-libspdc` to find the start of the API fetch sequence. - -## Regression tests (optional) - -There are some regression tests that can be run to check that the data collection library and application function are behaving as -expected. Please note the dependencies in the "Install dependencies" section above for running the regression tests. The regression -tests can be executed using: - -```bash -cd ~/rt-data-collection-application-function -meson test -C build regression -``` - -This will build the Data Collection AF (if not already built) and then will start an Open5GS NRF and the Data Collection AF, run -the regression tests and shutdown the Open5GS NRF and Data Collection AF. The results of the testing are displayed. +**Note:** Errors during `meson build` are often caused by missing dependencies, or by a network +issue while retrieving the API files and the `openapi-generator` JAR file. The log +`~/rt-data-collection-application-function/build/meson-logs/meson-log.txt` has the errors in +detail; search for `generator-libspdc` to find the start of the API fetch sequence. ## Installing @@ -98,13 +133,17 @@ sudo meson install --no-rebuild ## Running -The Application Function requires a running 5G Core NRF Network Function to register with. If you do not have a running 5G Core, the [Open5GS](https://open5gs.org/) Network Functions are installed as part of the installation procedure and the Open5GS NRF can be started using: +The Application Function needs a running 5G Core NRF Network Function to register with. If you +do not have a 5G Core running, the [Open5GS](https://open5gs.org/) Network Functions are +installed as part of the installation procedure, and the Open5GS NRF can be started with: ```bash sudo /usr/local/bin/open5gs-nrfd & ``` -Make sure the IP address and port details of the NRF you are running are configured in the `nrf` section of `/usr/local/etc/open5gs/dcaf.conf` and then run the Data Collection Application Function. For example: +Make sure the IP address and port of your NRF are configured in the `nrf` section of +`/usr/local/etc/open5gs/dcaf.conf`, then run the Data Collection Application Function, for +example: ```bash sudo /usr/local/bin/open5gs-dcafd & @@ -112,8 +151,31 @@ sudo /usr/local/bin/open5gs-dcafd & ## Development -This project follows -the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). The -`development` branch of this project serves as an integration branch for new features. Consequently, please make sure to -switch to the `development` branch before starting the implementation of a new feature. +This project follows the +[Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). +The `development` branch is the integration branch for new features, so switch to the +`development` branch before starting work on a new feature. + +### Regression tests (optional) + +Regression tests check that the data collection library and Application Function behave as +expected. They need the extra dependencies listed under +[Install dependencies](#install-dependencies). Run them with: + +```bash +cd ~/rt-data-collection-application-function +meson test -C build regression +``` + +This builds the Data Collection AF if needed, starts an Open5GS NRF and the Data Collection AF, +runs the regression tests, shuts down the NRF and the AF, and displays the results. + +## Contributing + +Contributions are welcome. How to raise an issue, fork the repository and open a pull request, and +the Contributor License Agreement required before code can be merged, are described at +. + +## License +Distributed under the 5G-MAG Public License v1.0. See [LICENSE](LICENSE). From 7e9b16e71f4c3b96dd0cfe4de0a055180b222289 Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" Date: Tue, 29 Sep 2026 22:42:45 +0200 Subject: [PATCH 2/4] docs: name dcaf.yaml as the configuration file in the README Problem README.md, Running, says to configure the NRF in /usr/local/etc/open5gs/dcaf.conf. The build generates dcaf.yaml from dcaf.yaml.in (src/data-collection-af/meson.build:75-77, 92-94), installs it into open5gs_sysconfdir, and compiles open5gs-dcafd with DEFAULT_CONFIG_FILENAME "/dcaf.yaml" (src/data-collection-af/meson.build:83). No dcaf.conf is installed or read. [code-derived] Basis No clause governs this; code-derived from the lines above. open5gs_sysconfdir is join_paths(sysconfdir, 'open5gs') in the open5gs subproject (5G-MAG/open5gs bbc-patches, configs/open5gs/meson.build:18), so with the default prefix the file is /usr/local/etc/open5gs/dcaf.yaml. The `nrf` section the sentence refers to is at dcaf.yaml.in:229. Raised by Review by the repository owner. Change README.md: dcaf.conf -> dcaf.yaml in the Running section. Verification T0: compared with the meson files at this commit and the open5gs subproject revision the wrap pins (bbc-patches). Nothing built or installed. Not in this change Any build file. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e26cdfb..7c9f7ec 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ sudo /usr/local/bin/open5gs-nrfd & ``` Make sure the IP address and port of your NRF are configured in the `nrf` section of -`/usr/local/etc/open5gs/dcaf.conf`, then run the Data Collection Application Function, for +`/usr/local/etc/open5gs/dcaf.yaml`, then run the Data Collection Application Function, for example: ```bash From f4b0bcae68c892799251f53af5d3a0504c6abeed Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" Date: Tue, 29 Sep 2026 23:07:57 +0200 Subject: [PATCH 3/4] docs: describe the README as of #32 merged Problem The open pull request 5G-MAG/rt-data-collection-application-function#32 (feature/integration-test -> development) adds pytest integration tests under tests/integration/, with their own README. It does not change the root README, so after it merges the root README would not mention them. [code-derived] Basis No clause governs this; code-derived. Merged state built by merging #32 (head b5cbcf7) into development (cef77bc), no conflicts. #32 changes only tests/integration/ and adds .gitignore. Raised by Review by the repository owner. Change README.md, Development: a short "Integration tests (optional)" subsection pointing to tests/integration/README.md. What it says is taken from the merged tree: the tests run against a local DCAF from docker/local (tests/integration/README.md; docker/local/ docker-compose.yml:21-23 maps ports 5000, 5100 and 5201, as tests/integration/config.toml expects); the clients create, get and delete R1 provisioning sessions and data reporting configurations, R2 data reporting sessions (plus creating a report) and R6 event subscriptions (tests/integration/clients/*.py); there is no update call. No instruction is copied from the sub-folder README. The rest of the README was checked against the merged tree and is unchanged by #32. Verification T0: code_check.py against the previous README on this branch: 8 of 8 code blocks byte-identical, none added. The tests were not run. Not in this change tests/integration/README.md itself; any code. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 7c9f7ec..f2a3055 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,13 @@ meson test -C build regression This builds the Data Collection AF if needed, starts an Open5GS NRF and the Data Collection AF, runs the regression tests, shuts down the NRF and the AF, and displays the results. +### Integration tests (optional) + +End-to-end tests, run with pytest against a running local Data Collection AF started from +`docker/local`, create, read and delete resources on the R1 (provisioning sessions and data +reporting configurations), R2 (data reporting sessions and reports) and R6 (event subscriptions) +APIs. Requirements and commands are in [tests/integration/README.md](tests/integration/README.md). + ## Contributing Contributions are welcome. How to raise an issue, fork the repository and open a pull request, and From 452b5b61ae970e8f685248a9d25cf6a2f80c60ff Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" <87380947+jordijoangimenez@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:53:12 +0200 Subject: [PATCH 4/4] README: banner alt, Status and Part of follow the website taxonomy --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index f2a3055..fc9bf9b 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,7 @@

- Status: under development + Status Version