# Installing TelAF Simulation

官方網頁：https://docs.qualcomm.com/bundle/publicresource/topics/80-41102-1/use-telaf-simulation.html

:::warning
Qualcomm 有提供 docker container 可以用來模擬 TelAF 跑在 tagert machine 的狀況。這個模擬用的 docker container 有 Ubuntu 18.04 和 Ubuntu 22.04，而他們的 `cgroup` 都必須是 `cgroup1`，不可以是 `cgroup2`。

我一開始是開一個 LXD 的 Ubuntu 18.04 container 安裝 TelAF simulation 所需的 packages，以及安裝它的 docker image。但由於我桌機裝的 Ubuntu 是 24.04，預設是 `cgroup2`，而 LXD container 的 `cgroup` 也會一併受 host 影響而變成 `cgroup2`。

雖然有試過一些方法將桌機 Ubuntu 24.04 改成 `cgroup1`，但 LXD container 頂多變成是 `cgroup1` 和 `cgroup2` 同時存在，無法變成 `cgroup1` only，這樣仍會導致模擬時的一些功能有受限。

最後是改成用 VirtualBox 跑 Ubuntu 18.04 虛擬機來跑 TelAF simulation 才有效。

所以以下是以 VirtualBox 跑 Ubuntu 18.04 虛擬機安裝 TelAF simulation 的步驟。
:::

:::info
檢查是 `cgroup1` 或 `cgroup2` 可以用以下指令：

$ mount | grep cgroup

以下結果是 `cgroup1`：


以下結果是 `cgroup2`：

:::

## 安裝 TelAF simulation

PS. 以下所說的 host 都是指執行在 VirtualBox 的 Ubuntu 18.04 虛擬機。

### 1. 安裝 host 所需的 packages

安裝 Ubuntu 18.04 host 所需的 packages：

sudo apt update && \
sudo apt -y upgrade && \
sudo apt -y install build-essential \
                     ca-certificates \
                     libssl-dev \
                     curl \
                     python3 \
                     ninja-build \
                     python-jinja2 \
                     cmake \
                     python-setuptools \
                     git \
                     fakeroot \
                     file \
                     libcap-dev \
                     python \
                     gcc-multilib \
                     apt-transport-https \
                     software-properties-common

### 2. 在 host 安裝 docker engine

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - && \
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable" && \
sudo apt update && \
sudo apt -y install docker-ce && \
sudo usermod -aG docker ${USER} && \
newgrp docker

## 將目前的使用者加入 docker 群組
sudo usermod -aG docker ${USER}

將使用者加入 docker 群組後，執行 `newgrp docker`，然後重新登入此使用者，此時就可執行 docker 相關指令，如：

## check docker version
docker --version
  
## check details
docker info

### 3. 下載 source code & build docker images

TelAF source code 的 git 頁面：https://git.codelinaro.org/clo/le/platform/TelAF/-/tree/telaf.lnx.1.1

可使用以下指令下載：

~$ git clone -b telaf.lnx.1.1 https://git.codelinaro.org/clo/le/platform/TelAF.git

在 TelAF root directory 內執行以下指令：

## 查看 help page
~/TelAF$ make simula-help

## check current ubuntu distro version
~/TelAF$ make simula-list
 
## change your ubuntu distro version based on your PC host, such as ubuntu18.04
~/TelAF$ make simula-distro-1804


在 TelAF root directory 內執行以下指令以 build docker images：

~/TelAF$ make simula-build-all from=ubuntu:18.04 docker_build_opts="--no-cache"

建立完之後可以用以下指令查看 docker images：

$ docker images


可以看到會安裝兩個 TelAF simulation 的 images，`runtime` 是用來執行模擬的，`develop` 則可以用來開發。

:::info
雖然有 develop 的 container，但我比較習慣在 host（也就是 Ubuntu 18.04 虛擬機）上 build application 🤔
:::

### 4. 下載 simulation 環境所需的相關 source code

讓 `~/TelAF/simulation/setup_simulation.sh` 此腳本有執行的權限：

~/TelAF/simulation$ chmod a+x setup_simulation.sh

執行 `setup_simulation.sh`：

~/TelAF/simulation$ ./setup_simulation.sh

執行完此腳本後，會在執行此腳本的資料夾內產生 `simulation_env` 資料夾，裡面有 5 個 git 專案（細節可參閱官網說明 https://docs.qualcomm.com/bundle/publicresource/topics/80-41102-1/get-the-source-code-from-the-clo-website.html ），開發人員可依據需求選擇特定的 branch，只要修改 `patch_me.json` 此檔案即可。

若有修改 `patch_me.json`，則要在 `simulation_env` 資料夾內執行以下指令：

~/TelAF/simulation/simulation_env$ make update

:::danger
即使沒有要選擇特定的 branch，在第一次執行 `setup_simulation.sh` 腳本後，仍然要在 `simulation_env` 內執行 `make update`，否則後續會一直出錯 😵

我之前不知道，一直不停重新安裝，弄了好久才發現是這個問題 😭😭😭😭😭
:::

### 5. Build TelSDK simulation project

由於 TelAF 是執行在 TelSDK 上面，所以要先建立 TelSDK simulation project，TelSDK 官網：https://docs.qualcomm.com/bundle/publicresource/topics/80-PF458-1/introduction.html

先 `cd` 到 `simulation_env/sdk` 此資料夾內，執行以下兩個指令以設定和建立 TelSDK 基本的開發環境：

## setup the basic env
~/TelAF/simulation/simulation_env/sdk$ ./build_sim.sh setup

## build all gRPC, SDK apps and libs
~/TelAF/simulation/simulation_env/sdk$ ./build_sim.sh rootfs

另外，也可以在 TelAF develop docker container 內建立 TelSDK simulation project：

## 先 cd 到 simulation_env/telaf 資料夾內

## create one script to be used by TelAF simulation develop container
~/TelAF/simulation/simulation_env/telaf$ echo "cd ../sdk && rm -r rootfs && ./build_sim.sh clean && ./build_sim.sh rootfs" > simulation/workstation/.simula.dev.action.sh
~/TelAF/simulation/simulation_env/telaf$ echo "" > simulation/.simulation.build
## PS. 若沒有執行過前面的 build_sim.sh rootf，則 sdk 資料夾底下不會有 rootf 此資料夾，所以記得把其中的 rm -r rootfs 拿掉

## build the SDK simulation project in TelAF container
~/TelAF/simulation/simulation_env/telaf$ make simula-x

當建立完 TelSDK simulation project 後，預設上會在 `sdk` 資料夾底下產生 `rootfs` 此資料夾，先紀錄此資料夾的路徑，後續會用到：

~/TelAF/simulation/simulation_env/sdk$ realpath rootfs
/home/cpt1020/TelAF/simulation/simulation_env/sdk/rootfs

### 6. 在 docker container 內建立 TelAF simulation

`cd` 至 `simulation_env/telaf/simulation` 資料夾內，建立一個名為 `.simulation.build` 的檔案，將以下內容寫入此檔案：

export IMPORT_SDK_SIMULATION = y
export sdk_rootfs=/home/cpt1020/TelAF/simulation/simulation_env/sdk/rootfs
export TELAF_SIMULATION_ENABLE_SMS = y
export TELAF_SIMULATION_ENABLE_DCS = y
export TELAF_SIMULATION_ENABLE_SIM = y
export TELAF_SIMULATION_ENABLE_LOC = y
export TELAF_SIMULATION_ENABLE_MNGD_CONN = y
export TELAF_SIMULATION_ENABLE_SOMEIP_GW = y

:::info
記得要將 `sdk_rootf` 的值改成前面執行 `realpath rootfs` 得到的路徑喔～
:::

在 `simulation_env/telaf/simulation/workstation/` 此資料夾內建立 `.simula.dev.action.sh` 此檔案，並將以下內容寫入此檔案：

make simula-c

在 `simulation_env/telaf` 內執行以下指令：

~/TelAF/simulation/simulation_env/telaf$ make simula-x

### 登入 TelAF simulation docker container

在 `~/TelAF/simulation/simulation_env/telaf` 內執行以下指令即可進入 TelAF simulation 的 docker container：

~/TelAF/simulation/simulation_env/telaf$ make simula-up


進入 container 後，執行 `telaf start` 才會啟動 TelAF，才能用 `app`、`update` 等 target tools（https://docs.qualcomm.com/bundle/publicresource/topics/80-41102-4/Target-Tools.html ）。

離開 container 時，若是輸入 `exit` 則會將 container 關掉。若要不將 container 關掉的方式離開 container，則必須：
1. 先按 `ctrl` + `p`
2. 再按 `ctrl` + `q`

這樣就會退出 container 而沒有將其關閉，之後若要再回到 container 則可用 `docker attach <container_id>` 回到 container，而 `<container_id>` 則可用 `docker ps` 查看。


### 登入 TelAF develop docker container

在 `~/TelAF` 內執行 `make simula-up-develop` 則可進入 TelAF develop docker container：


## `helloApp` Example

### Build `helloApp` app

在 host 建立以下專案：

cpt1020@Ubuntu1804:~/helloApp$ tree
.
├── helloApp.adef
├── printClientComponent
│   ├── client.c
│   └── Component.cdef
└── printServerComponent
    ├── Component.cdef
    ├── server.c
    └── server.h

2 directories, 6 files

`helloApp.adef`

executables:
{
    helloPrint = ( printClientComponent printServerComponent )
}

processes:
{
    run:
    {
        ( helloPrint )
    }
}

`printClientComponent/client.c`

#include "legato.h"
#include "interfaces.h"
#include "server.h"

COMPONENT_INIT
{
    LE_INFO("Asking server to print 'Hello, world!'");
    printer_Print("Hello, world!");
}

`printClientComponent/Component.cdef`

sources:
{
    client.c
}

cflags:
{
    -I $CURDIR/../printServerComponent
}

`printServerComponent/server.c`

#include "legato.h"
#include "interfaces.h"
#include "server.h"

void printer_Print(const char *message)
{
    LE_INFO("******** Client says: '%s'", message);
}

COMPONENT_INIT
{
}

`printServerComponent/Component.cdef `

sources:
{
    server.c
}

在 build 此 app 之前，先在 `~/TelAF/simulation/simulation_env/telaf` 執行以下兩個指令：

~/TelAF/simulation/simulation_env/telaf$ source set_af_env.sh simulation

~/TelAF/simulation/simulation_env/telaf$ bin/legs


執行完以上兩個指後才可以 build app，指令如下：

mkapp -t <target> -i </path/to/interfaces> <.adef>

例如：

~/helloApp$ mkapp -t simulation -i /home/cpt1020/TelAF/simulation/simulation_env/telaf/interfaces helloApp.adef


執行完之後會多出 `helloApp.simulation.update` 此檔案，要將它傳到 target machine，也就是 TelAF simulation docker container。

### Transfer to TelAF simulation docker container

可以使用 `docker cp` 指令或 `scp` 指令將檔案傳到 TelAF simulation docker container。

#### 使用 `docker cp` 指令

docker cp <file_to_transfer> <container_id>:<path/to/target/directory/>

例如：

~/helloApp$ docker cp helloApp.simulation.update a5e:/root/simulation/


#### 使用 `scp` 指令

scp -P 9022 <file_to_transfer> root@127.0.0.1:</target/directory/path/>

例如：

~/helloApp$ scp -P 9022 helloApp.simulation.update root@127.0.0.1:/root/simulation

使用 `scp` 傳送的話會需要輸入密碼，密碼是 `simula`。


使用 `scp` 時須指定 port number 是 `9022`。使用 `docker ps` 指令時，可以看到 `PORTS` 欄位是 `0.0.0.0:9022->22/tcp, :::9022->22/tcp`：


這個設定會將所有送往 host network interface IP 且 port number 是 9022 的封包都映射到 docker container 裡面。

### Install `helloApp` on TelAF simulation

在 TelAF simulation docker container 裡面執行 `telaf start` 以啟動 TelAF simulation。

執行 `app status` 可以看到有安裝的 App，以及該 App 的狀態：


`cd` 至 `/root/simulation` 資料夾，執行以下指令以安裝 `helloApp`：

~/simulation # update helloApp.simulation.update

這時再執行一次 `app status` 就可看到有安裝了 `helloApp`，且狀態是 `running`：


執行 `logread | grep helloPrint` 可以看到 client 跟 server 的 log 訊息：


### Stop and remove `helloApp`

若要讓 `helloApp` 停止運作，可以執行 `app stop helloApp`：


若要移除 `helloApp`，則可執行 `update -r helloApp`：