# CarSim 快速上手秘笈 | AVIR Lab | NCTU
CarSim為學術研究、車廠常用的車輛模擬軟體，其提供複雜、貼近現實之車輛數學模型，可以與Simulink連動進行模擬，驗證控制器之效果，在展示結果時可以更具公信力。本篇教學將說明自訂模擬環境的流程。
## 自訂模擬環境
本節將說明如何自訂模擬環境，設定車輛模型之輸入輸出、車輛模型參數、模擬流程和路面資訊等等。
### 1. 建立新的Dataset
這裡新建dataset的方式是從CarSim內建的dataset複製到新的dataset，因為跟直接從空白的dataset開始比較起來更快速、方便。
首先，進入到CarSim主畫面，從上方工具列 Datasets>Simulink 中選取一個Dataset作為複製對象。這邊選取 "Ext. Driver Model: E-Class, Sedan"
接下來，需要複製兩個部分，CarSim中的dataset以及對應到的Simulink檔。首先複製Simulink檔，點選主畫面中間欄 "Run Control with Simulink" 底下的藍色按鈕(Driver Model(CS8))。進去之後右上角"Simulink Model"的文字框內，是這個dataset所連結的Simulink檔之位置，以現在的Dataset為例，在預設安裝設定下他的位置會在:

C:\Users\Public\Documents\CarSim_Data\Extensions\Simulink

**備註**: 文字框下方windows作業系統請選64-bit，否則模擬時會出現錯誤。

在上述路徑找到"Driver_CS8.mdl"後，在現在的位置建立新資料夾(CarSim Demo)，將其複製到新資料夾內並重新命名(CarSim_Demo.mdl)以方便辨識，之後新增跟此dataset有關的檔案都可以放在此資料夾中。
複製好Simulink檔之後，回到CarSim主畫面複製dataset，選擇工具列的File>New Dataset，點選後畫上方畫跳出命名的文字框，左邊種類維持不變，右邊重新命名為 CarSim Demo。


下一步，我們要將這個新的dataset連結到剛剛的Simulink檔案，但是可以看到目前中間欄的藍色按鈕還是顯示"Driver Model(CS8)"，與剛剛的內建dataset名稱相同。在CarSim中，每個藍色的按鈕都可以視為一個子dataset，以現在的情況來說，"Ext. Driver Model: E-Class, Sedan"和"CarSim Demo"兩個dataset現在底下都包含"Driver Model(CS8)"這個子dataset，若是更動，兩邊都會受到影響，因此在建立新環境時，都會把各個子dataset複製，以免互相影響。點選"Driver Model(CS8)"旁的小箭頭>[Copy and Link Dataset]，為此子dataset建立類別以及取新名稱，完成後按"Copy and Link"。


完成後可以在選單中看到剛剛新建立的子dataset。


> **重要**: 要更動設定之前，請確定目前是在自己創的(子)dataset操作，否則可能會動到CarSim內建檔案，或者以後自己創建多個dataset之後互相影響到。養成習慣看到藍色按鈕就點右邊小箭頭>[Copy and Link Dataset]。接下來的示範中，有進入到藍色按鈕之前，也請記得複製到新的子dataset，以下將省略不提。

接著進入剛剛建立的"CarSim Demo"，點選右上角"Simulink Model"最右邊"..."，選擇剛剛複製好的"CarSim_Demo.mdl"，完成後回到主頁(上方按鈕列的"Home"可以直接回到主頁)，按下中間列"Send to Simulink"，跳出剛剛的mdl檔表示建立成功，接下來將設定模型參數、操作、路面等等。

### 2. 設定車輛模型參數

> **重要**: 以下步驟很多都是複製內建dataset後做更改，若是有出現按鈕、文字框呈現淺灰色無法更動的狀態，只要點按鈕列最右邊的"Lock"便可解鎖。但通常複製到自己創建的dataset(完成Copy and Link Dataset)後，程式就會自動解鎖，因此如果發現要更改時是鎖定狀態，請檢查是否忘記複製到自己的dataset。

進到主畫面左欄地個按鈕"E-Class, Sedan w/5 Driver Sensors">"E-Class, Sedan"，這裡主要設定車輛的各種參數，例如在Vehicle Body>Sprung mass: Rigid Sprung Mass中，可以設定車長、軸寬、質量、和慣量等等。


以上參數可依照文獻自行更改，接下來針對測試控制器常用到的設定進行說明。首先，實驗室目前的研究中，車輛的輸入通常是四個輪子的馬達扭矩以及方向盤轉角輸入，需對Powertrain的設定做更改，才能直接控制輪胎馬達扭矩。

進到Systems區塊的Powertrain內的"250 KW, 7-spd, 2.65 Ratio"，畫面下半共有六個子dataset，將右欄中間及下面灰色選單的部分，從原本的"Internal front differential"改為"External front differential"。


更改完後，畫面上半部的示意圖將會在四個輪胎都出現綠色的箭頭(EX: IMP_MY_OUT_D1_R)，代表可以作為車輛的控制輸入。


接著回到上層，一樣是在Systems區塊的Brake System，進入後可以看到目前的煞車系統是包含ABS控制的，但在測試自己的控制器時，通常只需要單純的車輛模型不包含額外的控制器。將內建ABS關掉，只需進到"E-Class, Sedan w/ABS"將右上角的"ABS disabled"勾選即可。

其餘區塊(車身、懸吊、轉向系統和輪胎等等)可依照需求自行調整。

### 3. 設定操作情境
此小節將說明CarSim Procedures中的各項設定(速度、轉向命令等等)，但通常控制明令都是來自外部輸入，所以這邊只需做少許的更動。若是要使用CarSim內建的控制器，可自行尋找符合需求的子dataset。

進到主頁第一欄的Procedures後，第一欄Driver Controls中，將對以下區塊進行說明:
**a. Speed**: 灰色選單中，選擇"Initial speed, open-loop throttle"，並在右方文字框輸入模擬時設定的車輛初速。速度控制通常也是控制器設計的一環，所以此處只給定車輛初速，並無加入速度控制。
**b. Braking**: 無須更動，維持"No Braking"。
**c. Shifting control**: 實驗室目前研究沒有針對換檔做設計，因此灰色選單選擇"Control: Shifting(Open Loop)"，底下子dataset選擇"Constant @ 4th Gear"，排除換檔造成的效應。
**d. Steering**: 無須更動，維持"No Steering"。

中間欄的Start and Stop Conditions可以調整模擬時長，即為Simulink中顯示的模擬時間。

### 4. 設定道路及路面資訊
接下來設定模擬中的道路以及路面資訊，勾選主頁"Vehicle & Procedure"欄最下方的"Show more options on this screen"，會出現額外的選單，選擇"Road">"Road: 3D Surface"。下方子dataset選擇"straight">"Flat and Long"。


Geometry區塊可以定義道路的X-Y關係，Friction區塊可設定不同摩擦係數的路面，最左欄Animator Support可以設定路面的動畫。

此範例將維持原有設定不變，設定較複雜的路面可以參考附錄。

### 5. 設定車輛模型之輸入輸出
CarSim提供的複雜車輛模型在simulink中即為一具有輸入輸出之方塊，此節將定義此方塊的輸入輸出。進入到主頁中間欄的藍色按鈕，此時該名稱應已改為自訂的名稱，進入後左下角分別為"Import Channels"與"Output Channels"，分別為定義輸入與輸出的子dataset。

首先進到"Import Channels"，畫面主要分為三個區塊，從左邊開始為分類，選取分類後，該分類底下可以使用的輸入變數便會出現在中間欄位。中間欄位內，對變數長按右鍵可以查看說明，雙擊左鍵可以將該變數加到最右的欄位，代表此變數已加入啟用中的輸入變數。

"Output Channels"也是相同的配置。

**備註**: 有時會發生中間欄位都沒有變數出現的情況發生，此時可以按"Readme file of in(out)puts"文字框旁的"Resfresh"按鈕，就會重新載入。

此範例中，我們將輸入設為向盤轉角與四個輪胎馬的扭矩，並將一些常見的車輛狀態(縱向、側向之位置、速度與加速度、橫擺角速度)設為輸出作為回授訊號，稍後用來設計簡單的控制器展示。


以上即完成CarSim端的設定，儲存後回到主頁按下"Send to Simulink"。

>**重要**: 每次CarSim端有更動時，皆需按下"Send to Simulink"，Simulink端才會更新。

### 6. Simulink端設定
在Simulink端，方才所有在CarSim端的設定都包含在紅色車輛的方塊圖內。剩下我們只需注意其輸入輸出，便可開始控制演算法的實現。CarSim原始輸出的變數單位跟大部分文獻中常用的單位不太一樣，因此需要再做轉換(原先mdl檔內的其他方塊可以刪除)。方向盤轉角與實際輪胎轉角也存在一倍數關係(steering ratio)，可以在CarSim>Steering System中左邊Note欄位查看。將輸出接到"To workspace"方塊，方便在Matlab繪製結果。


使用"Signal builder"方塊來設計加速度命令與轉向角命令。利用下列控制法計算出跟隨期望速度所需的輪胎扭矩(此處將兩個後輪視為驅動輪，兩個前輪的扭矩為0):

$T_{m3}=T_{m4}=\frac{1}{2}mR\cdot (-rV_y+a_{x, cmd}-K\cdot(Vx-V_{x, cmd}))$

m: 車體質量，R: 輪胎半徑，K: 控制增益。

使用"Matlab function"實現此控制法，程式碼如下:

function Tm = Torque_controller(yawrate, Vx, Vy, Vxd, axd)

R = 0.306;        % radius of tire
K = 50;           % gain (positive)  
m = 1880;         % mass of vehicle

Tm = 0.5*m*R*(-yawrate*Vy+axd-K*(Vx-Vxd));

最後的Simulink如下:

模擬結束後，數據已記錄在Matalb的workspace中，可將結果繪製出來查看。

figure()

subplot(1, 3, 1)
plot(vehicle_out.Data(:, 1), vehicle_out.Data(:, 2), 'r', 'LineWidth', 2)
hold on; grid on;
title('Position')
xlabel('X (m)')
ylabel('Y (m)')

subplot(1, 3, 2)
plot(desired.Time, desired.Data(:, 1), 'k:', 'LineWidth', 2)
hold on; grid on;
plot(vehicle_out.Time, vehicle_out.Data(:, 3), 'r', 'LineWidth', 2)
title('Longitudinal velocity')
xlabel('time (s)')
ylabel('V_x (m/s)')

subplot(1, 3, 3)
plot(desired.Time, desired.Data(:, 2), 'k:', 'LineWidth', 2)
hold on; grid on;
plot(vehicle_out.Time, vehicle_out.Data(:, 5), 'r', 'LineWidth', 2)
title('Longitudinal acceleration')
xlabel('time (s)')
ylabel('a_x (m/s^2)')


## 常見問題
1. 啟動CarSim時可能會出現server error的訊息，但還是可透過選擇local的license file正常啟動。
2. CarSim的Dongle頗貴，若有在家用個人電腦跑模擬的需求，建議將Dongle插在實驗室電腦主機，在遠端連回來操作。使用windows內建遠端桌面連線程式啟動CarSim會無法正常啟動，可以預先在實驗室開好或者使用chrome remote desktop即可解決。

## 附錄

### 設定路徑
設定DLC路徑時，若只用端點來表示路徑，CarSim在處理路徑做interpolation時可能會出問題，建議先自行處理過，增加路徑點的數量，並用MATLAB函數pchip做平滑化，簡易程式碼如下:

xd = [0 55 185 235 355 400]; % Desired path
yd = [0 0 3.4 3.4 0 0];
step = 5;                    % Distance between points
xq = xd(1):step:xd(end);
yq = pchip(xd, yd, xq);

figure()
plot(xd, yd)
hold on; grid on;
plot(xq, yq, '--')

fp = fopen('CarSim_path.txt','w'); % Write to .txt file
for i=1:length(xq)
    fprintf(fp, '%.2f, %.2f\n', xq(i), yq(i));
end
fclose(fp);

### 動畫：比較控制器
CarSim可以將模擬結果的動畫進行疊圖比較，勾選主畫面右下角的 "Overaly animation and plots with the other runs"，在從選單中選擇要比較的dataset，即可在Animate中檢視結果。