# Lab5 智慧基站控制平台與行動管理實驗
## 目錄
1. 實驗內容
2. 相關知識
3. 相關建制環境/設備規格
4. 實驗架構
5. xApp程式說明
6. 實驗步驟
7. 參考資料
## 1.實驗內容
此次實驗主要是學習架設與部署O-RAN的RIC，以及使用xApp並觀察使用結果
### 1-1問題與討論
1. 截圖6-2最後`watch kubectl get pod -A -o wide`佈署成功的畫面
2. 截圖6-5最後，一、二、三號終端機的成功畫面
3. 解釋A3 Event觸發與停止條件的物理意義
4. 解釋Ping Pong Effect的物理意義
## 2.相關知識
- O-RAN Near-RT RIC 與 E2AP：Near-RT RIC 透過 E2 介面 / E2AP 跟基站（或 Emulator）互動，流程通常包含：
- E2 Setup：E2 Node 與 RIC 建立連線、交換能力資訊
- Subscription：RIC 訂閱你要的量測/事件
- Indication：E2 Node 持續上報量測資料（xApp 依此決策）
- 部署相關
- Kubernetes / Helm：RIC 平台元件與 xApp 都跑在 K8s 上
- AppMgr / DMS CLI：管理 xApp 的 onboard / install / uninstall
- ChartMuseum：xApp Helm chart 的本機 repo
- Docker Registry：讓 K8s 能拉到你 build 的 xApp image
## 3.相關建置環境/設備規格

此次實驗環境使用實體主機與虛擬機皆可，只是需要注意的是ubuntu需要使用**20.04**的版本，與之前的不同，再請同學們注意！

| 電腦選擇 | 實體機、虛擬機皆可 |
| ----------- | ------------------ |
| Ubuntu | 20.04 |
| Near RT-RIC | i-release |
| CPU | 4 Core |
| RAM | 8G |
| Storage | 75 G |

## 4.實驗架構
### 4-1 實驗環境模擬圖
此次實驗是模擬Near-RT RIC中的Handover xApp在接收E2 Termination的即時訊號後，持續的對當前環境做決策並最終交給E2 Termination做判斷，判斷的場域如下圖，在8000m x 6000m的環境中，有18個基站，並分成辦公區與居住區，UE在兩個區域中移動時xApp會判斷該UE是否需要換手，並給予換手的決策。
### 4-2 Rear-RT RIC架構
- Emulator：負責模擬基站和 UE 的相關資料
- Handover xApp：透過算法分析並決策是否要進行換手
> 以上資料是參考O-RAN SC
> [官方規格書 (Specifications) 相關網站](https://specifications.o-ran.org/specifications)

### 4-3 Emulator
Emulator 模擬的是科學園區的上下班情況
#### 環境大小
- 長8000m、寬6000m
- 基站數量：18
- 基站半徑：1000m

#### UE 設定
1. 移動限制在矩形區域內
2. 模擬時間： 24 小時
3. 分佈情形：

| 班表 | 上班時間 | 整體UE占比 |
| -------- | ------------- |:---------- |
| 大夜班 | 00:00 ~ 09:00 | 20% |
| 小夜班 | 16:00 ~ 01:00 | 20% |
| 正常日班 | 08:00 ~ 17:00 | 60% |


## 5. xApp式碼說明

## 6. 實驗流程

### 6-0 Software Updater
登入ubuntu後，一樣需要更新與安裝必要的工具，依序完成以下指令即可

sudo apt update
sudo apt upgrade
sudo apt install ubuntu-desktop
sudo -i
sudo apt install unrar
sudo apt-get install -y git vim curl net-tools openssh-server python3-pip nfs-common libsctp1
sudo apt-get update

### 6-1 下載實驗所需的O-RAN Near RT RIC Source Code
將壓縮檔解壓縮並移動至桌面
### 6-2安裝O-RAN Near RT RIC
1. 安裝O-RAN SC I-Release

sudo -i
git clone https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep -b i-release
ls ~/ric-dep/bin  #確認ric-dep/bin有安裝成功


2. 將教材提供的 install_k8s_and_helm.sh , install_kong.sh , install_RIC.sh 覆蓋掉原本的檔案 (假設你已經放在桌面)

cd /home/*你設的username*/Desktop 
cp install_RIC.sh ~/ric-dep/bin/
cp install_k8s_and_-_helm.sh ~/ric-dep/bin/
cp install_kong.sh ~/ric-dep/bin/

3. 依序給予這三個 Shell Scripts 權限

chmod 777 install_k8s_and_helm.sh 
chmod 777 install_kong.sh
chmod 777 install_RIC.sh

提權成功後會看到權限列表長這樣

4. 執行三個shell scripts來安裝與部署需要的pods
:warning: 請先檢查`./install_k8s_and_helm.sh`中的IP使否與你現在電腦的IP相同，若不相同請自行修改！不然會安裝失敗！
>可以透過`ip a`的指令查看本機的IP

:warning:執行以下指令會花費很多時間，請奈心等待！如果虛擬機效能太差會安裝更久！安裝時會出現重複的訊息是正常的，請放心

./install_k8s_and_helm.sh 
./install_kong.sh
./install_RIC.sh

- 完成畫面

執行完成後須透過以下指令查看pods的部署情況

watch kubectl get pod -A -o wide


若`watch kubectl get pod -A -o wide`結果一切正常就請略過第五步

5. ~~安裝O-RAN Near RT RIC失敗~~
如果在執行第四步時安裝失敗，會需要解除安O-RAN Near RT RIC指令並重新部署O-RAN Near RT RIC指令（希望大家不會執行到這步）
- 解除 O-RAN Near RT RIC 指令

./uninstall

- 重新部署 O-RAN Near RT RIC 指令

cd ~/ric\-dep/bin
./install -f ../RECIPE_EXAMPLE/example_recipe_oran_i_release.yaml -c "jaegeradapter influxdb"

### 6-3xApp 佈署工具 DMS CLI 安裝指令
O-RAN SC有提供一個部署的工具『**DMS CLI**』，接下來就只要透過以下的指令就可以順利部署xApp了

docker run --rm -u 0 -it -d -p 8090:8080 -e DEBUG=1 -e STORAGE=local -e STORAGE_LOCAL_ROOTDIR=/charts -v $(pwd)/charts:/charts chartmuseum/chartmuseum:latest
export CHART_REPO_URL=http://0.0.0.0:8090

git clone https://gerrit.o-ran-sc.org/r/ric-plt/appmgr -b h-release
cd appmgr/xapp_orchestrater/dev/xapp_onboarder

apt-get install python3-pip
pip3 uninstall xapp_onboarder
pip3 install ./

chmod 755 /usr/local/bin/dms_cli
ls -la /usr/local/lib/python3.8

chmod -R 755 /usr/local/lib/python3.8

輸入完畢後，需要透過以下指令確認所有的確認xApp部署（DMS/xapp_onboarder）這套工具鏈本身能不能正常運作，如果有可以就會顯示`Ture`

dms_cli health


### 6-4 xApp檔案修改
因為每個人在部署RIC時，不同的pod都會分配不同到IP，所以需要找到一下ric-app-A3handover中的dockerfile，並修改檔案中`ENV SUBMGR`的IP成自己的，而如何找到自己的submgr，則可以透過先前的`watch kubectl get pod -A -o wide`來查看
>
>

### 6-5 RIC、Emulator和xApp連線
0. 在這個步驟中，會需要先開三個terminal，並透過以下指令進入路徑（記住！是三個terminal都需要）

sudo -i
cd /home/<your username>/Desktop

1. 先在第三個terminal執行以下指令
:warning: 請注意最後一個curl的指令，在`http://<appmgr IP>:8080/ric/v1/register`的*appmgr*中，也需要透過`watch kubectl get pod -A -o wide`來查看自己的IP。
例：`http://10.244.0.11:8080/ric/v1/register`

cd ric-app-A3handover
docker run -d -p 5000:5000 --restart=always --name registry registry:2
export CHART_REPO_URL=http://0.0.0.0:8090
dms_cli onboard ./init/config-file.json ./init/schema.json
docker build -t 127.0.0.1:5000/hw-python:1.0.2 .
docker tag 127.0.0.1:5000/hw-python:1.0.2 127.0.0.1:5000/hw-python:1.0.2
docker push 127.0.0.1:5000/hw-python:1.0.2

curl -v -X POST 'http://<appmgr IP>:8080/ric/v1/register' -H 'accept:application/json' -H 'Content-Type:application/json' -d '@hwpython-register.json'

> 成功畫面

2. 依序給予 Shell Scripts 檔案權限

chmod 777 Emulator_TCP
chmod 777 emulator_connect_run.sh
chmod 777 emulator_run.sh

3. 建立kuberbet所需的設置

mkdir -p ~/.kube
sudo cp -i /etc/kubernetes/admin.conf ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

4. 在三個terminal **依序**執行以下指令

//第一個 terminal 執行，等第一個terminal出現wait for connect...再執行第二個指令
./emulator_run.sh 

//第二個 terminal 執行 
./emulator_connect_run.sh

//第三個 terminal 執行 
dms_cli install hw-python 1.0.1 ricxapp

如果看到以下畫面就是有判斷成功！
:warning: 成功時請務必要截圖！
- 一號終端機會顯示適合當下的情境與是否要做handover
- 透過二號終端機紅色框框的E2 Setup的狀態來判斷Emulator是否有正常運作，黃色框框的RIC Subscription的狀態來判斷xApp是否有正常運作
- 三號終端機會顯示OK

5. 清除ricxapp
- 若有發現連不上或以上兩個procedure沒有順利完成，請中斷一號和二號terminal並透過以下指令解除xApp佈署

dms_cli uninstall hw-python ricxapp

## 參考資料
- [教育部 5G技術聯盟 模組13](https://drive.google.com/drive/folders/1xWStVcOl4KDpCvO0nRylCXAnWFBBBY3g)