AR_Fuelsys 範例腳本說明
腳本結構 · 執行管線 · 關鍵 API 引用
解析 SystemDesk 2024-B Demos\AR_Fuelsys\SD\Scripts 內的 25 支 Python 腳本:如何以「Options 變體 + Main 管線 + Utilities 函式庫」自動建立 AR_Fuelsys 專案、產生程式碼、匯出 .vecu 與 .fmu,並詳列其 COM API 引用。
來源路徑:C:\Users\DS-PVE\Documents\dSPACE\SystemDesk\2024-B\Demos\AR_Fuelsys\SD\Scripts。本頁所有程式碼片段皆直接摘自這些腳本的實際內容(dSPACE 原廠 demo),用以說明其 API 引用方式。AR_Fuelsys 為「容錯燃油噴射系統」示範,展示 SystemDesk 較複雜功能與 SystemDesk↔TargetLink 互通。
目錄
01. 資料夾總覽與三層架構
整個 Scripts 資料夾採「薄變體 + 厚核心」設計。25 支腳本可分三層:
① 變體腳本(薄)
~21 支 2–4 KB 小檔。只設定 Options 再呼叫 AR_Fuelsys_Main.Main()。每支 = 一種拓樸/輸出組合。
② 執行管線(核心)
AR_Fuelsys_Main.py(≈344 KB)。依 Options 建立整個 AR_Fuelsys 模型、產碼、匯出 V-ECU、建置、匯出 FMU。
③ 工具函式庫
Utilities.py(≈150 KB)。約 180 個可重用函式,把 SystemDesk COM API 包成好用的 helper。
02. 變體腳本的運作模式與 Options
每支變體腳本結構一致:import + reload → 在 Main() 內設 Utilities.Options.* → 呼叫 AR_Fuelsys_Main.Main()。以最簡單的 AR_Fuelsys_1Ecu.py 為例:
import importlib, Utilities, AR_Fuelsys_Main importlib.reload(Utilities); importlib.reload(AR_Fuelsys_Main) def Main(): Options = Utilities.Options # 共用的全域設定物件 Options.ProjectName = "AR_Fuelsys_1Ecu" Options.EngineModelRealization = {"SWC"} # 引擎模型當作 SWC 放在 Controller Options.CombiRealization = {"SWC"} Options.UseDiagnosis = False # 不啟用 Dem/Dcm 診斷 Options.BuildForVeos = True # 建置 VEOS 離線模擬應用 (OSA) AR_Fuelsys_Main.Main() # 交給核心管線 if __name__ == "__main__": Main()
變體之間的差異全在 Options。主要選項:
| Option | 意義 / 取值 |
|---|---|
| ProjectName | 產生的 SystemDesk 專案名(.sdp) |
| EngineModelRealization | 引擎模型實現方式:ECU/MDL/SWC + CAN/IOHWAB + FD |
| CombiRealization | 儀表(combi)實現:ECU/SWC + CAN/LIN + FD |
| UseDiagnosis | 是否納入診斷(Dem / Dcm) |
| BuildForVeos | 是否建置 VEOS 離線模擬應用(OSA) |
| ExportAsFMU / FMUVersion | 是否匯出 FMU;FmiVersion.FMI2 / FMI3 / NONE |
| MemMapTarget | 記憶體映射/編譯目標(如 "GCC") |
| GenerateCode / ExportSystemExtract / SaveProject / OpenExistingProject | 管線各階段開關(見 §04) |
03. 腳本清單(依拓樸分類)
| 腳本 | 說明 |
|---|---|
| 核心 | |
| AR_Fuelsys_Main.py | 整個 demo 的建構管線(模型 → 產碼 → 匯出 → 建置) |
| Utilities.py | ≈180 個 COM API 包裝 helper 與 Options/FmiVersion 定義 |
| 單 ECU(無網路) | |
| AR_Fuelsys_1Ecu.py | 最簡變體:全部元件在 Controller,閉迴路模擬 |
| AR_Fuelsys_1Ecu_FMI2.py / _FMI3.py | 同上,額外匯出 FMI 2.0 / 3.0 FMU |
| 雙 / 三 ECU(含匯流排) | |
| AR_Fuelsys_2Ecus_Can.py / _IoHwAb.py | 兩顆 ECU,經 CAN 通訊 / 經 IoHwAb I/O |
| AR_Fuelsys_2Ecus_1Mdl_Can_IoHwAb.py / _CanFd_ / _Lin_ | 兩 ECU 共用一模型,CAN / CAN FD / LIN + IoHwAb 變體 |
| AR_Fuelsys_3Ecus_2Can.py | 三顆 ECU、兩條 CAN 匯流排 |
| AR_Fuelsys_3Ecus_Can_IoHwAb / _Lin_Can / _Lin_CanFd / _Lin_IoHwAb | 三 ECU 的各種匯流排/IO 組合 |
| AR_Fuelsys_3Ecus_2Can_MemMapGcc.py | 三 ECU + 兩 CAN,並設 MemMapTarget="GCC" |
| *_Can_FMI2/FMI3 · *_2Can_FMI2/FMI3 | 上述拓樸的 FMU 匯出版本 |
| 重建與匯出 | |
| Rebuild_AR_Fuelsys_3Ecus_2Can.py Rebuild_..._2Ecus_1Mdl_Can_IoHwAb.py | 開既有 .sdp(OpenExistingProject=True)重新產碼並重建 OSA |
| ExportToTargetLink.py | 把目前專案的 SWC 匯出成 ARXML 給 TargetLink |
04. Main() 執行管線
AR_Fuelsys_Main.Main() 依 Options 逐階段執行;建模階段以 GetElementByPath 檢查「是否已存在」來決定是否重建(支援 Rebuild 重用既有專案):
OpenProject() 或 CreateProject()(依 OpenExistingProject)/AUTOSAR_Platform → 建 SwComponentTypes → EcuInstances → Communication → Systems → ECU 設定GenerateCodeForAllEcus() — 產生 BSW 模組與 RTE 程式碼(Options.GenerateCode)ExportSystemExtract() — 匯出 System Extract(供 ControlDesk 匯流排監控)ExportVEcuImplementations() — 對每顆 V-ECU 匯出 .vecu 或 .fmuBuildForVeos() — 建置 OSA(Options.BuildForVeos)Utilities.SaveProject()(Options.SaveProject)05. Utilities.py 函式庫分類
Utilities.py 的約 180 個函式,把 SystemDesk COM API 依 AUTOSAR 建模概念包裝,命名遵循 Create* / Add* / Get* / GetOrCreate* / Set* / Find* / Import* / Build* 慣例:
| 類別 | 代表函式 |
|---|---|
| 連線 / 專案 | ConnectToSystemDesk、ConnectToVeosPlayer、CreateProject、OpenProject、SaveProject |
| 元素存取 | GetElementByPath、DeleteElementByPath、FindAncestor、GetOrCreatePackage |
| SWC / 行為建模 | CreateDataSendPoint、CreateDataReadAccess、CreateModeSwitchPoint、SetNonqueuedSenderComSpec |
| 資料型別 / 校正 | GetOrCreateApplicationPrimitiveDataType、GetOrCreateCompuMethod、CreateConstantSpecification |
| 通訊(CAN/LIN) | CreateFrame、CreateFrameTriggering、CreateISignal、AddISignalToPduMapping、AddLinScheduleTableEntry |
| ECU 設定 / 排程 | AddModuleConfiguration、AddRteEventMapping、TriggerOsTask、StartBswGeneration |
| 匯入 / 匯出 / 建置 | ImportAutosarFiles、ImportA2lFile、BuildForVeos、BuildModelContainerForVeos |
06. 關鍵 API 引用(重點)
以下摘自腳本實際程式碼,是理解「如何以 COM 驅動 SystemDesk」最關鍵的片段。
6.1 連線與環境設定(ConnectToSystemDesk)
SdApplication = win32com.client.Dispatch("SystemDesk.Application.2024-B") applicationRootDir = SdApplication.ApplicationRootDir # BSW 模組自動化組件目錄(%ProgramData%\dSPACE\...\Automation) bswAutomationDir = os.path.join(SdApplication.ApplicationProgramDataDir, "Automation") sys.path.insert(0, bswAutomationDir) # SystemDesk 的 Scripting 目錄(列舉定義) sys.path.insert(0, os.path.join(applicationRootDir, r"Tools\Scripting")) import SystemDeskEnums # SdEnums = 列舉(如 BuildStatusEnum)
VEOS Player 亦以 COM 連線(用於以 VEOS Player 建置模型容器):win32com.client.Dispatch("VeosPlayer.Application.2024-B") → import VeosEnums。
6.2 專案與元素存取(物件模型)
# 建立 / 關閉 / 取得作用中專案 SdProject = SdApplication.CreateProject(projectFile) # .sdp SdApplication.ActiveProject.Close(saveOldProject) # 以 AUTOSAR 路徑取得元素(GetElementByPath 的核心) arRoot = SdApplication.ActiveProject.RootAutosar firstPackage = arRoot.ArPackages.Elements[0] elements = firstPackage.GetElementsByARPath("/SwComponentTypes/FuelsysController/...") # Collection 慣用法:AddNew / AddNewRange / Item / Count / Elements / Names package = rootPackage.ArPackages.AddNew() packages = rootPackage.ArPackages.AddNewRange(shortNames) # 批次,效能較佳
6.3 ECU 設定與模組(含 FMI 定義檔)
AddModuleConfiguration 依 Options.ExportAsFMU/FMUVersion 選用不同的參數定義檔與定義套件——這正對應 ViVa / FMI2 / FMI3 三種目標:
if fmi and FMUVersion == FmiVersion.FMI2: defFile = SdApplication.EcuConfigurationManager.DefaultFmi2DefinitionFilename # 定義套件:/dSPACE_FMI2、/dSPACE_Sim、/dSPACE … elif fmi and FMUVersion == FmiVersion.FMI3: defFile = SdApplication.EcuConfigurationManager.DefaultFmi3DefinitionFilename # CAN/Fr 走 /dSPACE_FMI3_LS_Bus(fmi-ls-bus) else: defFile = SdApplication.EcuConfigurationManager.DefaultDefinitionFilename # ViVa
FMU 情境會額外加入 FmiAd(FMI adapter)與 Xcp 模組;FMI 2.0 另加 Dap、Sfc——與 dSPACE MCAL 獨有模組一致。
6.4 匯出 V-ECU 容器(.vecu)與 FMU(.fmu)★
這是本主題最關鍵的 API。ExportVEcuImplementations() 遍歷 project.ClassicVEcus,依 vEcu.IsFmu 決定呼叫哪個匯出方法:
SdApplication.BatchMode = True # 抑制對話框(自動化必備) for vEcu in project.ClassicVEcus.Elements: path = GetVEcuExportPath(vEcu) # .vecu 或 .fmu if vEcu.IsFmu == False: vEcu.ExportContainer(path) # ← 匯出 .vecu(VEOS/CFD) else: settings = vEcu.GetNewExportFmuSettings() settings.TargetPath = path settings.BuildAndExportBinaries = True settings.ExportSourceCode = False settings.ExportConfigurations.Clear() if FMUVersion == FmiVersion.FMI2: settings.ExportConfigurations.Add("Generic FMI 2.0 - Windows (x86_64)") else: settings.ExportConfigurations.Add("dSPACE VEOS - Windows (x86_64)") vEcu.ExportFmu(settings) # ← 匯出 .fmu(FMI 相容) vEcu.EnableAutoConfigureAndGenerate = True
| API | 用途 |
|---|---|
| vEcu.ExportContainer(path) | 匯出 .vecu 實作容器 |
| vEcu.GetNewExportFmuSettings() | 取得 FMU 匯出設定物件 |
| settings.TargetPath / BuildAndExportBinaries / ExportSourceCode | 輸出路徑、是否建置二進位、是否含原始碼 |
| settings.ExportConfigurations.Add(...) | 匯出組態(FMI2:Generic FMI 2.0 - Windows (x86_64);FMI3:dSPACE VEOS - Windows (x86_64)) |
| vEcu.ExportFmu(settings) | 依設定匯出 .fmu |
| vEcu.IsFmu | 此 V-ECU 是否為 FMU 型態 |
6.5 建置(Build → BuildStatus)
SdApplication.BatchMode = True if vEcuName is None: buildResult = simSystem.Build() # 建整個 simulation system else: vEcu = simSystem.ClassicVEcus.Item(vEcuName) buildResult = vEcu.Build() # 建單顆 V-ECU buildStatus = SdEnums.BuildStatusEnum(buildResult.BuildStatus)
6.6 Serializer 匯出 ARXML(ExportToTargetLink)
settings = swc.Serializer.GetNewExportSettings() settings.SetElements([swc, implementation]) settings.FilePath = "ForTargetlink\\" + swc.ShortName + ".arxml" settings.ExportReferencedElements = True swc.Serializer.Export(settings) # 專案層級亦有:sdProject.Serializer.WriteAutosarProjectFiles(...)
SdApplication.BatchMode = True 包夾,避免對話框阻斷腳本(結束時還原)。② 移除物件參考須用 pythoncom.Nothing(腳本中 vEcu.BuildScript.Value = Nothing 即此意),設 None 會出錯。07. FMU vs V-ECU 匯出差異(腳本層面)
| 面向 | V-ECU(.vecu) | FMU(.fmu) |
|---|---|---|
| 變體腳本設定 | 預設(不設 ExportAsFMU) | ExportAsFMU=True + FMUVersion=FMI2/FMI3 |
| 參數定義檔 | DefaultDefinitionFilename(ViVa) | DefaultFmi2/Fmi3DefinitionFilename |
| 額外模組 | Sab / Dap 等標準模擬模組 | 加 FmiAd、Xcp;FMI2 加 Dap、Sfc |
| 匯出呼叫 | vEcu.ExportContainer(path) | vEcu.ExportFmu(settings) |
08. 如何執行這些腳本
這些腳本是在外部 Python 直譯器中執行、透過 COM 驅動 SystemDesk 的自動化腳本——不是在 SystemDesk 內部執行。以下為官方建議流程(PythonWin)與命令列替代方式。
8.1 前置需求
| 項目 | 說明 |
|---|---|
| SystemDesk 2024-B | 已安裝且 COM 已註冊(腳本以 SystemDesk.Application.2024-B 連線,未啟動會自動啟動) |
| demo 已解壓到使用者資料夾 | 須從安裝目錄 .\Demos 複製 ZIP 到 Documents 解壓(本機已在 …\Documents\dSPACE\SystemDesk\2024-B\Demos\AR_Fuelsys) |
| Python + pywin32 | 需 win32com(pywin32)。PythonWin(dSPACE/Python 隨附)已內建;若用其他 Python 需先裝 pywin32 |
| VEOS 2024-B(選用) | 當 Options.BuildForVeos = True 需要,用於建置 OSA(部分函式另會連 VEOS Player) |
8.2 方法一:PythonWin(官方建議)
啟動 PythonWin
由開始功能表的 dSPACE / Python 群組開啟 PythonWin。
File – Run
選單 File – Run(或工具列 Run 圖示)開啟 Run Script 對話框。
Browse 選腳本
選變體腳本(如 AR_Fuelsys_1Ecu.py)。
OK 執行
於 PythonWin 狀態列 / Interactive Window 觀察標準與錯誤輸出。
import Utilities / import AR_Fuelsys_Main 能正確解析;腳本內的 importlib.reload() 也確保修改後不必重開直譯器即生效。8.3 方法二:命令列(適合批次 / CI)
用具備 pywin32 的 Python 直接執行。務必讓腳本所在的 Scripts 目錄可被匯入(Python 會自動把被執行腳本的目錄加入 sys.path,故從該目錄執行或用完整路徑皆可):
:: 若使用 C:\Python313,先安裝 pywin32(僅裝在此 Python 路徑下) C:\Python313\Scripts\pip install pywin32 :: 切到 Scripts 目錄後執行變體腳本 cd /d "C:\Users\DS-PVE\Documents\dSPACE\SystemDesk\2024-B\Demos\AR_Fuelsys\SD\Scripts" C:\Python313\python.exe AR_Fuelsys_1Ecu.py :: 也可用完整路徑執行(cwd 不限) C:\Python313\python.exe "C:\...\AR_Fuelsys\SD\Scripts\AR_Fuelsys_2Ecus_Can.py"
Dispatch("SystemDesk.Application.2024-B") 找不到而失敗。此字串位於 Utilities.py 的 ConnectToSystemDesk(),需改成對應版本(例如你另有 2025-B 目錄)。8.4 產出位置
依 GetNewProjectRootDir():因腳本位於名為 Scripts 的資料夾,SystemDesk 會把產生的專案存到其上層資料夾(即 …\AR_Fuelsys\SD\)。官方提醒:「執行時 SystemDesk 將建立的專案存到腳本的上層資料夾;既有專案檔會被覆寫。」
SD\ ├─ AR_Fuelsys_1Ecu.sdp # 產生的 SystemDesk 專案 ├─ AR_Fuelsys_1Ecu\ # 產出資料夾 │ ├─ <VEcu>.vecu / <VEcu>.fmu # V-ECU 容器 / FMU(依 Options) │ └─ ...osa / Build.log # BuildForVeos=True 時的 OSA 與建置紀錄 └─ Scripts\ # 原腳本
8.5 執行前設定與建立自訂變體
設定既有變體
官方流程:啟動 PythonWin → 閱讀腳本標頭說明(如「options in line 54++」)→ 編輯 Options.* → File – Run。
建立新變體
複製一支變體 → 改 Options.ProjectName 與拓樸/輸出(EngineModelRealization、CombiRealization、ExportAsFMU…)→ 放回 Scripts\ 執行。無需改 Main/Utilities。
若要對既有專案重新產碼並重建(不重建模型),用 Rebuild_*.py(其設 Options.OpenExistingProject = True,會開啟對應 .sdp 而非重新建立)。
8.6 疑難排解
| 現象 | 原因 / 解法 |
|---|---|
ModuleNotFoundError: Utilities | 未從 Scripts 目錄執行、或直接執行路徑未被加入 sys.path。改用完整路徑執行,或先 cd 到 Scripts。 |
No module named 'win32com' | Python 缺 pywin32。用 PythonWin,或 C:\Python313\Scripts\pip install pywin32。 |
Dispatch 失敗 / com_error | SystemDesk 未安裝/未註冊或版本不符。確認 2024-B 已安裝,或改 ConnectToSystemDesk() 內的版本字串。 |
| 執行中途卡住等待對話框 | 腳本已於建置/匯出時設 BatchMode=True;若在其他階段被訊息擋住,確認 SystemDesk 未跳出待確認視窗。 |
| VEOS 建置失敗 / 找不到 VEOS Player | BuildForVeos=True 需 VEOS 安裝;ConnectToVeosPlayer() 會試 2025-A 再退回 2024-B。無 VEOS 時可設 BuildForVeos=False 只匯出容器。 |
| 既有專案被覆寫 | 設計如此(同名 .sdp 會覆寫)。要保留請先改 Options.ProjectName 或另存。 |
AR_Fuelsys_1Ecu.py)理解 Options 模式 → 再讀 Utilities.py 的 ConnectToSystemDesk / BuildForVeos / 匯出函式掌握 API 慣例 → 最後對照 AR_Fuelsys_Main.py 的 Main() 看整體管線。ExportToTargetLink.py 則是最短、最易懂的 API 入門範例。來源檔案
本頁所有 API 片段摘自下列實際腳本(dSPACE 原廠 AR_Fuelsys demo,2024-B):
| 檔案 | 引用內容 |
|---|---|
| AR_Fuelsys_Main.py | Main() 管線、ExportVEcuImplementations(ExportContainer / ExportFmu)、AddModuleConfiguration 呼叫 |
| Utilities.py | ConnectToSystemDesk、CreateProject、GetElementByPath、AddModuleConfiguration、BuildForVeos |
| AR_Fuelsys_1Ecu.py(及各變體) | Options 設定模式 |
| ExportToTargetLink.py | Serializer 匯出 ARXML |
路徑:C:\Users\DS-PVE\Documents\dSPACE\SystemDesk\2024-B\Demos\AR_Fuelsys\SD\Scripts · 方法完整簽章請參閱 SystemDesk API Reference(dSPACE Help)。