From: RahulBanerji Date: Mon, 7 Dec 2020 08:12:19 +0000 (+0530) Subject: Added Docs and Readme.md X-Git-Tag: 1.0.0~3 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=ea6e5c0fa03ccf6b3a000578a10e34e9320f0fbf;hp=ebe8aeaea6de2fbe7719d922cce37a40527481d3;p=ric-app%2Fhw-python.git Added Docs and Readme.md Change-Id: Icd0363fa6b6cc2d96252fb971d02db73e2c6b631 Signed-off-by: Rahul Banerji --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..e38d2af --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# O-RAN-SC Hello World Xapp in Python + +This repository contains open-source code for a prototype python xAPP for near real-time +RAN Intelligent Controller which makes use of python Xapp Framework. + +This xAPP aims to provide basic implementation of : + +1. A1 interfaces interactions + +2. Read-write operations into a persistent storage. + +3. xAPP Configuration management + +4. RMR Health Check + +5. xAPP SDL Check + +6. Raising alarms + +7. Generating metrics (TBD) + +8. E2 Interface intereactions (TBD) + + +Introduction +------------ + +This document provides guidelines on how to install and configure the HW Python xAPP in various environments/operating modes. +The audience of this document is assumed to have good knowledge in RIC Platform. + + +Preface +------- +This xAPP can be run directly as a Linux binary, as a docker image, or in a pod in a Kubernetes environment. The first +two can be used for dev testing. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment. +This covers all three methods. + +1. Docker + +2. Linux Binary + +3. Kubernetes + + + +Software Installation and Deployment +------------------------------------ +The build process assumes a Linux environment with python >= 3.8 and has been tested on Ubuntu. For building docker images, +the Docker environment must be present in the system. + + +##Build Process + +The HW xAPP can be either tested as a Linux binary or as a docker image. + 1. **Linux binary**: + TBD + + 2. **Docker Image**: From the root of the repository, run *docker --no-cache build -t ./* . + + +##Deployment + +**Invoking xAPP docker container directly** (not in RIC Kubernetes env.): + One can include the pod.yaml for including it in k8s build. Replace the image name with one built. + TBD: Adding hw-python to nexus repo + + +Testing +-------- + +Unit tests TBD + + +## License + +``` + + Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +``` diff --git a/container-tag.yaml b/container-tag.yaml new file mode 100644 index 0000000..d2ab322 --- /dev/null +++ b/container-tag.yaml @@ -0,0 +1,4 @@ +# The Jenkins job requires a tag to build the Docker image. +# Global-JJB script assumes this file is in the repo root. +--- +tag: 0.0.1 \ No newline at end of file diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..c3b6ce5 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..07032ac --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,7 @@ +from docs_conf.conf import * + +linkcheck_ignore = [ + 'http://localhost.*', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*' +] diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..067f59b --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: ric-app-hw-py diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..00b0fd0 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..47d7f62 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved.Copyright (C) 2020 + + +Welcome to O-RAN SC HelloWorld xAPP Documentation +======================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview.rst + release-notes.rst + installation-guide.rst + user-guide.rst + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst new file mode 100644 index 0000000..0854d7d --- /dev/null +++ b/docs/installation-guide.rst @@ -0,0 +1,69 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved. + + +Installation Guide +================== + +.. contents:: + :depth: 3 + :local: + +Abstract +-------- + +This document describes how to install the HelloWorld (HW) Python xAPP. + +Version history + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| - |- |Rahul Banerji | - | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Introduction +------------ + +This document provides guidelines on how to install and configure the HW Python xAPP in various environments/operating modes. +The audience of this document is assumed to have good knowledge in RIC Platform. + + +Preface +------- +This xAPP can be run directly as a Linux binary, as a docker image, or in a pod in a Kubernetes environment. The first +two can be used for dev testing. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment. +This document covers all three methods. + + + + +Software Installation and Deployment +------------------------------------ +The build process assumes a Linux environment with python >= 3.8 and has been tested on Ubuntu. For building docker images, +the Docker environment must be present in the system. + + +Build Process +~~~~~~~~~~~~~ +The HW xAPP can be either tested as a Linux binary or as a docker image. + 1. **Linux binary**: + TBD + + 2. **Docker Image**: From the root of the repository, run *docker --no-cache build -t ./* . + + +Deployment +~~~~~~~~~~ +**Invoking xAPP docker container directly** (not in RIC Kubernetes env.): + One can include the pod.yaml for including it in k8s build. Replace the image name with one built. + TBD: Adding hw-python to nexus repo + +Testing +-------- + +Unit tests TBD diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..be50c76 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved.Copyright (C) 2020 + + + + +HelloWorld Python xAPP Overview +================================ + +This repository contains open-source code for a prototype python xAPP for near real-time +RAN Intelligent Controller which makes use of python Xapp Framework. +This xAPP aims to provide basic implementation of : + +-E2, A1 interfaces interactions. + +-Read-write operations into a persistent storage. + +-xAPP Configuration management + +-RMR Health Check + +-xAPP Health Check + +-Raising alarms + +-Generating metrics diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..2525290 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,85 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved.Copyright (C) 2020 + + +Release Notes +============= + + +This document provides the release notes for the Bronze Release of the HelloWorld (HW) xAPP. + +.. contents:: + :depth: 3 + :local: + + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| - | - | Rahul Banerji | - | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + + +Summary +------- + +This release of the Python HW xAPP demonstrates the following: + +-E2, A1 interfaces interactions. + +-Read-write operations into a persistent storage. + +-xAPP Configuration management + +-RMR Health Check + +-xAPP Health Check + +-Raising alarms + +-Generating metrics + + +Release Data +------------ + ++--------------------------------------+--------------------------------------+ +| **Project** | RAN Intelligent Controller | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | TBD | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | TBD | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | TBD | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | open-source Python Hello World xAPP | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Components +---------- + +TBD + + + + +Limitations +----------- +- The HW xAPP doesn't have any usecase in particular to display SDL capabilities. + +- The subscription process assumes, on sending subscription request results in valid subscription response. + +- The HW xAPP doesn't address any RIC usecase in particular. diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..09a0c1c --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,5 @@ +sphinx +sphinx-rtd-theme +sphinxcontrib-httpdomain +recommonmark +lfdocs-conf diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 0000000..19a751d --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,28 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (c) 2020 Samsung Electronics Co., Ltd. All Rights Reserved.Copyright (C) 2020 + +============================================================================================ +HelloWorld xAPP (Python) +============================================================================================ +-------------------------------------------------------------------------------------------- +User's Guide +-------------------------------------------------------------------------------------------- + +Introduction +============================================================================================ + +The RIC platform provides set of functions as part of xAPP Python Framework that the xAPPs can use to accomplish their tasks. +This xAPP is envisioned to provide python xAPP developers, examples of implementing these sets of functions. +Note, HW xAPP does not address/implement any RIC Usecases. + +HelloWorld xAPP Features +============================================================================================ + +RIC Platform provides many Frameworks, APIs and libraries to aid the development of xAPPs. All xAPPs will have some custom +processing functional logic core to the xApp and some additional non-functional platform related processing using +these APIs and libraries. This xAPP attempts to show the usage of such additional platform processing using xapp RIC framework APIs and libraries. + + +The Hello World xApp demonstrates how a python based xApp uses the A1, and E2 interfaces and persistent database read-write operations. +