Improve documentation
Issue-ID: NONRTRIC-819
Signed-off-by: elinuxhenrik <henrik.b.andersson@est.tech>
Change-Id: I8e26be0b89c315249d8450c15b21d6c3dd83b489
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9b1eda8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+<!--
+ -
+ ========================LICENSE_START=================================
+ O-RAN-SC
+ %%
+ Copyright (C) 2023: Nordix Foundation
+ %%
+ 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.
+ ========================LICENSE_END===================================
+
+-->
+
+# O-RAN-SC Non-RealTime RIC O-RU Fronthaul Recovery rApp
+
+There are three implementations available for this rApp.
+
+- The Go version that uses Information Coordinator Service (ICS) to create a job that provides info about the Fronthaul state, see [Go version](goversion/README.md).
+- The script version that polls DMaaP Message Router for info about the Fronthaul state, see [script version](scriptversion/README.md).
diff --git a/docs/index.rst b/docs/index.rst
index eb32c18..b1dbe0c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,7 +3,7 @@
.. Copyright (C) 2021 Nordix
Non-RT RIC O-RU Fronthaul Recovery Use Case
-===========================================
+============================================
.. toctree::
:maxdepth: 2
diff --git a/docs/overview.rst b/docs/overview.rst
index 0d861de..3863b9f 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -3,13 +3,13 @@
.. Copyright (C) 2021 Nordix
O-RU Fronthaul Recovery Use Case
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
************
Introduction
************
-This use case is a non-real-world closed-loop use case to demonstrate automated recovery when the front-haul connection between an O-DU and O-RU is reset.
+This use case is a non-real-world closed-loop use case to demonstrate automated recovery when the fronthaul connection between an O-DU and O-RU is reset.
An application in the NONRTRIC senses the fault from the O-RU (O1-FM) and initiates a NETCONF reset operation (O1-CM) using the OAM controller.
More details about the use case can be found on the O-RAN SC wiki: `RSAC <https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=20878423>`_ and `OAM <https://wiki.o-ran-sc.org/display/OAM/Closed+loop+use+case>`_.
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index a084c87..d3132a3 100644
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -7,7 +7,7 @@
=============
-This document provides the release notes for the Non-RT RIC O-RU Front-Haul Recovery Use Case.
+This document provides the release notes for the Non-RT RIC O-RU Fronthaul Recovery Use Case.
Version history
===============
@@ -33,7 +33,7 @@
E Release
---------
+-----------------------------+---------------------------------------------------+
-| **Project** | Non-RT RIC O-RU Front-Haul Recovery |
+| **Project** | Non-RT RIC O-RU Fronthaul Recovery |
| | |
+-----------------------------+---------------------------------------------------+
| **Repo/commit-ID** | nonrtric/b472c167413a55a42fc7bfa08d2138f967a204fb |
@@ -52,7 +52,7 @@
E Maintenance Release
---------------------
+-----------------------------+---------------------------------------------------+
-| **Project** | Non-RT RIC O-RU Front-Haul Recovery |
+| **Project** | Non-RT RIC O-RU Fronthaul Recovery |
| | |
+-----------------------------+---------------------------------------------------+
| **Repo/commit-ID** | nonrtric/4df1f9ca4cd1ebc21e0c5ea57bcb0b7ef096d067 |
@@ -71,7 +71,7 @@
F Release
---------
+-----------------------------+---------------------------------------------------+
-| **Project** | Non-RT RIC O-RU Front-Haul Recovery |
+| **Project** | Non-RT RIC O-RU Fronthaul Recovery |
| | |
+-----------------------------+---------------------------------------------------+
| **Repo/commit-ID** | nonrtric/rapp/orufhrecovery |
diff --git a/goversion/README.md b/goversion/README.md
index 45207cb..0d14f7e 100644
--- a/goversion/README.md
+++ b/goversion/README.md
@@ -1,6 +1,6 @@
-# O-RAN-SC Non-RealTime RIC O-RU O-DU Link Failure Consumer
+# O-RAN-SC Non-RealTime RIC O-RU Fronthaul Recovery Consumer
-This consumer creates a job of type `STD_Fault_Messages` in the Information Coordinator Service (ICS). When it recieves messages, it checks if they are link failure messages. If they are, it checks if the event severity is other than normal. If so, it looks up the O-DU ID mapped to the O-RU where the message originates from and sends a configuration message to the O-DU through SDNC. If the event severity is normal, then it logs, on `Debug` level, that the link failure has been cleared.
+This consumer creates a job of type `STD_Fault_Messages` in the Information Coordinator Service (ICS). When it receives messages, it checks if they are link failure messages. If they are, it checks if the event severity is other than normal. If so, it looks up the O-DU ID mapped to the O-RU where the message originates from and sends a configuration message to the O-DU through SDNC. If the event severity is normal, then it logs, on `Debug` level, that the link failure has been cleared.
## Configuration
@@ -19,7 +19,7 @@
Any of the addresses used by this product can be configured to use https, by specifying it as the scheme of the address URI. The client will not use server certificate verification. The consumer's own callback will only listen to the scheme configured in the scheme of the consumer host address.
-The configured public key and cerificate shall be PEM-encoded. A self signed certificate and key are provided in the `security` folder of the project. These files should be replaced for production. To generate a self signed key and certificate, use the example code below:
+The configured public key and certificate shall be PEM-encoded. A self signed certificate and key are provided in the `security` folder of the project. These files should be replaced for production. To generate a self signed key and certificate, use the example code below:
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650
@@ -33,24 +33,28 @@
If the consumer is shut down with a SIGTERM, it will also delete the job before exiting.
There is also a status call provided in the REST API. This will return the running status of the consumer as JSON.
+
>- /status {"status": "started/stopped"}
## Development
To make it easy to test during development of the consumer, three stubs are provided in the `stub` folder.
-A producer stub, under the `producer` folder, that stubs the producer and pushes an array with one message with `eventSeverity` alternating between `NORMAL` and `CRITICAL`. The stub does not start to send messages until it recieves a create job call from the ICS stub. When a delete job call comes from the ICS stub it stops sending messages. To build and start the stub, do the following:
+A producer stub, under the `producer` folder, that stubs the producer and pushes an array with one message with `eventSeverity` alternating between `NORMAL` and `CRITICAL`. The stub does not start to send messages until it receives a create job call from the ICS stub. When a delete job call comes from the ICS stub it stops sending messages. To build and start the stub, do the following:
+
>1. cd stub/producer
>2. go build
>3. ./producer
An ICS stub, under the `ics` folder, that listens for create and delete job calls from the consumer. When it gets a call it calls the producer stub with the correct create or delete call and the provided job ID. By default, it listens to the port `8083`, but his can be overridden by passing a `-port [PORT]` flag when starting the stub. To build and start the stub, do the following:
+
>1. cd stub/ics
>2. go build
>3. ./ics
An SNDR stub, under the `sdnr` folder, that at startup will listen for REST calls and print the body of them. By default, it listens to the port `3904`, but his can be overridden by passing a `-port [PORT]` flag when starting the stub. To build and start the stub, do the following:
+
>1. cd stub/sdnr
>2. go build
>3. ./sdnr
diff --git a/scriptversion/README.md b/scriptversion/README.md
index 6b59388..6efe080 100644
--- a/scriptversion/README.md
+++ b/scriptversion/README.md
@@ -1,8 +1,8 @@
-# Use case Link Failure
+# Non-RealTime RIC O-RU Fronthaul Recovery
## General
-The Link Failure use case test provides a python script that regularly polls DMaaP Message Router (MR) for "CUS Link Failure"
+The script version of the O-RU Fronthaul Recovery use case provides a python script that regularly polls DMaaP Message Router (MR) for "CUS Link Failure"
messages.
When such a message appears with the "eventSeverity" set to anything but "NORMAL", a configuration change message with the
@@ -11,7 +11,7 @@
When such a message appears with the "eventSeverity" set to "NORMAL" a printout will be made to signal that the
alarm has been cleared, provided that the verbose option has been used when the test was started.
-## Prerequisits
+## Prerequisites
To run this script Python3 needs to be installed. To install the script's dependencies, run the following command from
the `app` folder: `pip install -r requirements.txt`
@@ -58,7 +58,7 @@
## Use docker-compose
-Go to the `docker-compose/` folder and run `bash start.sh`.
+Go to the `docker-compose/` folder and run `bash start.sh`, see [control loop version](docker-compose-controlloop/README.md).
This scripts will start up four components:
dmaap-mr