跳轉到

腳本命令

什麼是腳本命令?

腳本命令 即 HiNC 腳本引擎執行的 C# 敘述。腳本直接引用 SessionShell (API) 的成員與方法 — SessionShell 即全域作用域,無需明確物件參考。

// 以下都是直接以 SessionShell 成員作為全域使用
EnablePhysics = true;
MachiningResolution_mm = 0.125;
PlayNcFile("NC/file1.nc");
Message("Done");

腳本語法基礎

腳本使用 原生 C# 語法:

功能 語法
敘述結尾 ;
行尾註解 // comment
字串插值 $"Value is {variable}"
正無限大 double.PositiveInfinity
負無限大 double.NegativeInfinity
位元 OR(旗標) Fx|Fy|Fz

所有標準 C# 語言特性(變數、迴圈、條件、LINQ 等)皆可使用。


執行模型

工作階段生命週期

  1. 腳本在執行頁的任務分支上依序執行
  2. 由 PacePlayer (API) 控制播放 — PlayNcFile (API) 之類的腳本命令會阻塞至 NC 程式完成
  3. 播放器控制命令(Pace (API)、Pause (API)、Reset (API))與 PacePlayer (API) 互動。任務腳本在播放器執行緒上執行,所以它自己的 Reset() 會以 Reset--Refused 拒絕、什麼都不重置,因為這個重置會在腳本自己的這次執行底下結束工作階段、清除運行時狀態——要在兩支程式之間重置,請改用 ResetRuntime (API)
  4. ResetRuntime (API) 清除運行時狀態——已記錄的步、網格化的工件與訊息。掛在工作階段事件上的處理器不受它影響,要等工作階段結束、也就是播放器「重置」時才會移除。在播放中的程式裡面呼叫它——由程式自己的內嵌腳本呼叫,或由腳本在它自己走訪 RunNcFile (API) 的迴圈裡呼叫——會以 ResetRuntime--Refused 拒絕、什麼都不重置,程式照常播放下去;PowerReset (API) 在那裡也一樣會被拒絕(PowerReset--Refused)。兩者都要在兩支程式之間呼叫

腳本命令編譯不過時,會在工作階段回報 ScriptCommand-Compile--Failed(附上全部診斷),什麼都不執行;執行期丟出例外——包括它自己丟的取消——則回報一則 ScriptCommand-Run--Fault,帶著腳本自己的訊息,不論錯誤出在 await(例如 await Map(…))之前或之後。兩者都不會中斷任務:任務接著執行下一個命令。腳本回傳的動作——例如 RunNcFile (API) 在 return RunNcFile(…) 交回的播放——丟出的例外不算腳本的錯,而是播放的:任務停在那裡,回報 Player-Run--Fault。腳本執行中按下「停止」不算錯誤:腳本會在它下一個會看「停止」的呼叫——播放、動作、NC 優化或它等待的映射——結束,不回報,它下面的列也不再執行(見開始與逐步執行)。「停止」之後才發出的工件呼叫不會結束腳本:它以 MeshedGeomCall--Canceled 警告被跳過,腳本照常往下執行。

讀取或修改工件的呼叫

ExportMeshedGeomToStl (API) 與它的 OBJ、PLY 兩個同類、WriteMeshedGeom (API)、ReadMeshedGeom (API)、Diff (API)、RemoveFlyPiece (API) 與 ScanMeshedGeomInfDefect (API) 會先等已排進的切削做完,執行期間播放停住不動:它們寫出的檔含有呼叫之前播過的每一步,沒有切到一半的步。寫在 PlayNcFile 之後的腳本行沒有東西要等。在程式中途、由它的內嵌腳本呼叫時,會等排在該單節前面的每一步都做完——切削與物理量都算完——所以每隔幾個單節就呼叫一次,播放會變慢。

結束播放結果記錄會從工件寫出加工完成的素材,所以記錄開著時,EndNcResultRecording (API) 也是這樣的呼叫;BeginNcResultRecording (API) 這時也是,因為它會先結束開著的記錄,再開始下一個。下面的規則對兩者都成立,拒絕的訊息會指名這個呼叫:記錄保持開著、什麼都不寫——被拒絕的開始也不會開新的記錄——在任務底下,任務結束時會完成這次記錄。沒有記錄開著時,EndNcResultRecording() 只會說出 NcResult-Record--NotRecording,BeginNcResultRecording 則就在呼叫的地方開始。

這三個匯出都另有一個三個引數的形式,最後一個引數 balanceNeighbourLevels 要求的是均勻網格,也就是任務命令上的均勻網格:ExportMeshedGeomToStl("Output/part.stl", 0, true);。這時會先在大格子緊鄰著小得多的格子的地方把匯出的網格細分,讓相鄰格子的大小最多相差一倍、三角形的大小逐漸變化——替分析建立網格的軟體或 CAD 的匯入功能可能偏好這樣的網格。檔案裡的三角形會多一些,描述的仍是同一個表面;OBJ 與 PLY 的匯出保留每個格子的顏色;工件不會改變:播放照常繼續,和沒有這個選項時一樣。它不會把模型封閉起來。兩個引數的呼叫不變,等於 false。什麼時候該要求它、它讓哪些地方維持原樣,見在兩次執行之間保留工件。

  • await 之後——例如 await Map(…)——任務腳本改在另一條執行緒上繼續,由正在等腳本的播放器執行緒替它執行這個呼叫。自己啟動的工作請用 await 等,不要用 .Wait() 或 .Result 同步等:腳本同步等著的工作在另一條執行緒上發出的呼叫——在那件工作裡的 await 之後,或在腳本第一個 await 之前的 Task.Run(() => EndNcResultRecording()).Wait() 裡——要等被腳本佔住的播放器執行緒,30 秒後以 MeshedGeomCall--BusyPacePointTimeout 拒絕;請用 await 等那件工作,或直接在腳本主體裡呼叫。在腳本自己走訪 RunNcFile (API) 的迴圈裡不要 await:那裡 await 之後的呼叫也一樣會被拒絕。
  • 直接播放的程式裡——主機的 PlayNcFile(經 HTTP 或由主機自己的程式碼呼叫),而不是任務——請在內嵌腳本的第一個 await 之前呼叫;await 之後的呼叫會以 MeshedGeomCall--BusyAnotherThread 拒絕。
  • 在 SessionStepBuilt (API) 的處理器裡,呼叫會以 MeshedGeomCall--OnPump 拒絕。任務播放時,處理器若把呼叫交給另一條執行緒、自己再同步等它——Task.Run(…).Wait()——就佔住了呼叫要等的管線:播放器已接下這個呼叫時,播放停住不動,直到按下「停止」,呼叫才以 MeshedGeomCall--Canceled 回應;播放器還沒接下它時,呼叫在 30 秒後被撤回,以 MeshedGeomCall--BusyPacePointTimeout 回應,處理器的等待隨之返回,播放繼續。直接播放的程式裡——主機的 PlayNcFile,而不是任務——呼叫會立刻以 MeshedGeomCall--BusyAnotherThread 拒絕,播放照常繼續。請改在腳本主體裡呼叫。

被拒絕的呼叫什麼都不做,在工作階段以一則 MeshedGeomCall--* 訊息說明原因,腳本照常往下執行;ScanMeshedGeomInfDefect 回傳 null。呼叫開始之前、或它還在等排在前面的步時按下「停止」,會取消它(MeshedGeomCall--Canceled),工作階段正在拆除時會拒絕它(MeshedGeomCall--BusyReset),而呼叫等待期間工件被換掉——被「重置」或另一個 ReadMeshedGeom 換掉——它就什麼都不寫(MeshedGeomCall--TreeDiscarded)。沒有工件幾何時,匯出、WriteMeshedGeom 或 RemoveFlyPiece 什麼都不寫,發出警告 MeshedGeomCall--NoGeom,腳本照常往下執行。WriteMeshedGeom 寫到無法寫入的檔——所在資料夾不能寫入,或在 Windows 上檔案是唯讀的、或被不允許刪除它的程式開著——會丟出 IOException,檔案本身維持原樣。寫入先寫到檔案旁邊的 <檔名>.writing,再搬到位;寫入失敗時會刪掉自己的 <檔名>.writing,除非在 Windows 上有程式開著它、又不允許它被刪除。搬到位是用新檔取代原檔,而不是寫進原檔:即使檔案本身可寫,資料夾也必須可寫;在 Linux 上,唯讀的檔一樣會被取代,權限變成新建檔案的預設,那個名字若是符號連結,會被換成一般檔案,不會寫進它指向的檔,而指向原檔的另一個硬連結保留原來的內容。在 Windows 上,開著這個檔的程式若每一個都允許它在開著時被刪除,檔案照樣被取代:那些程式在關掉它之前讀寫的仍是舊檔,這段期間寫的不會進到新檔(在 Windows 11、本機的 NTFS 磁碟上,以及經同一台機器的網路共用、開著它的程式也經那個共用開檔時查證過,後者開著的檔一律被拒絕;其他 Windows 版本、其他檔案系統、對映的磁碟機與別台機器的共用沒有查證)。從檔案總管下載單一檔案時,就是這樣開著檔案。先前一次寫入留下的 <檔名>.writing 會先刪掉;刪不掉的同樣丟出 IOException,它留在原處,檔案本身維持原樣。所在資料夾不能寫入時,把資料夾改成可寫,下一次寫入會自己刪掉它;在 Windows 上,請清掉它的唯讀屬性或刪掉它,或關掉佔住它的程式,再寫一次。

事件驅動執行

SessionStepBuilt (API) 等事件於仿真期間觸發,可作步級邏輯:

SessionStepBuilt += (preStep, curStep) => {
    if (curStep != null)
        Message($"Step: ToolId={curStep.ToolId}");
};
PlayNcFile("NC/file1.nc");

這樣加上的處理器屬於工作階段:ResetRuntime (API) 不會移除它,它要等工作階段結束、也就是播放器「重置」時才會移除。


NC 碼中的腳本命令

腳本命令可嵌入 NC 程式自己的註解,讓腳本在程式裡寫著它的那個位置執行。這需要兩層語法配合:控制器的註解語法先把註解從單節取出,而註解符號取決於控制器本身:

控制器 用什麼開啟註解
Fanuc、Mazak、Syntec 只有括號 ( )
Siemens ; 到行尾
Heidenhain //、; 或 ( )

腳本語法接著用兩個標記把腳本從註解文字取出:@@ 是在該單節運動之前執行的腳本,@@^ 是在之後執行的(下文稱行前/行後標記,指的就是該單節之前/之後)。兩個標記是該語法的設定、不是固定字元:它們來自專案所指名的控制器定義,而自帶解析器設定的專案則沿用自己那一份。在以 ; 開啟註解的 Siemens 上:

T01 M06 ;@@MachiningResolution_mm=0.03125;
S1270 M03
G43 Z10. H01

在 Fanuc 家族的控制器上,同一段腳本寫在括號內:

T01 M06 (@@MachiningResolution_mm=0.03125;)
S1270 M03
G43 Z10. H01

單節所帶的腳本會不會照字面執行,由三條規則決定:

  • 每個標記各只寫一次,而且腳本寫在最後。 標記會把自己到該則註解結尾的所有文字吃進腳本,所以寫在腳本後面、但仍在同一則註解內的東西會被當成腳本的一部分——同一則註解裡的第二個 @@ 會被第一段腳本整段吞掉。
  • 同一則註解要放兩段時,@@ 要寫在 @@^ 之前。 行後腳本會先被取出,所以先寫 @@^ 的註解,它的 @@ 會被行後腳本整段吞掉。
  • 一行只寫一則括號註解。 括號註解從該行第一個 ( 讀到最後一個 ),所以第二則註解會被當成第一則的一部分。在 Heidenhain 上,括號註解會比 ; 註解先被取出,所以寫在 ; 之後的呼叫會把參數輸給它——;@@LineSelection("a", …); 執行時只剩 LineSelection;,編譯不過。在 Heidenhain 上,有呼叫任何東西的腳本請寫在 ( ) 內或 // 之後。

內嵌腳本與腳本命令編譯時用同一組參考與命名空間引用 (using),而且和腳本命令一樣,本身不需要任何授權功能。腳本編譯不過會在它所屬的步回報 Script-Compile--Error,執行期丟例外則是 Script-Run--Exception,兩者都不會中斷播放。內嵌腳本執行時按下「停止」,會在腳本播放下一段程式或下一個動作時生效,腳本就在那裡結束,不會回報;「停止」落在某個單節進行途中時,該單節的腳本不會執行。內嵌腳本不能重置它所在的這次執行:@@ResetRuntime(); 與 @@PowerReset(); 會以 ResetRuntime--Refused 與 PowerReset--Refused 拒絕、什麼都不重置,程式照常播放下去。這類重置請放在兩支程式之間——放進一個腳本命令,或寫成兩次播放之間的一行腳本。

Note

3.2.7 到 3.2.31 的套件只在有 NcComposition 授權功能時才執行內嵌腳本。沒有這個授權功能時,只會對第一個內嵌腳本回報一次 Script--NotLicensed,其後不論同一次播放或之後的播放全部靜默跳過。程式裡的內嵌腳本若在換到這幾版之後不再生效,換到更新的套件就會恢復執行,程式本身不必修改。

Warning

;@ 是前一代執行器 (runner) 的標記,;# 是它的行後標記。在今天播放 NC 的執行器上,這兩個只是普通註解文字,命令不會執行。對 ;@,建置會對每個 NC 檔發出一次 CsScript-Marker--Legacy 警告,指出檔名與第一個 ;@ 後面接著呼叫或指派的行;;# 的命令則不會有任何訊息。在 Fanuc 家族上裸寫時,; 根本不開啟註解,那段文字連註解都不是——建置另外會發出 UnparsedText--Remaining 警告。


檔案路徑樣板

輸出檔的命令支援 [NcName] 標記,會替換為各 NC 檔名稱:

PlayNcFile("NC/file1.nc");
PlayNcFile("NC/file2.nc");
WriteShotFiles("Output/[NcName].shot.csv", 1);
// 產生:Output/file1.nc.shot.csv、Output/file2.nc.shot.csv

所有檔案路徑除非指定為絕對路徑,否則皆以 專案目錄 為基準。


重要警告

下列操作可能損壞仿真狀態或產生錯誤結果:

  • 仿真期間請勿儲存專案。 系統內部配置(如訓練專屬的解析度覆寫)可能覆寫你的設定。
  • 訓練銑削係數期間請勿重置播放器。 請改以關閉專案取代按下重置按鈕,以避免意外錯誤。
  • 訓練期間請勿修改解析度、刀具或控制器設定。 在訓練中途改變這些設定會使結果無效。
  • 請勿在 SessionStepBuilt (API) 的處理器裡播放、重置或結束工作階段。 處理器在每一步完成時執行,這時播放還在產生後面的步。從處理器呼叫 PlayAct (API)、PlayToolingTeleport (API)、PlayClTeleport (API)、ResetRuntime (API)、EndSession (API) 或播放器的 Reset (API) 都會丟出例外:例外以 Step--Exception 回報在那一步,那一步也不留結果。讀取或修改工件的呼叫——包括 EndNcResultRecording(),以及記錄開著時的 BeginNcResultRecording——在那裡不會丟出例外:它們以 MeshedGeomCall--OnPump 拒絕、什麼都不做,記錄保持開著。PlayNcFile 與其他播放程式的命令在播放進行中會被當成第二個播放而拒絕(任務播放中為 Play--Busy;播放在另一條執行緒上時——例如主機或網頁請求自己的執行緒——為 Play--BusyAnotherThread),播放器的重置正在結束工作階段時則以 Play--BusyReset 拒絕;被拒絕的播放回傳 false。停止之後、被停下的播放最後幾步還在收尾時,處理器裡的播放程式命令會被放行,並在開始時等待執行這個處理器的管線而丟出例外:例外以 Step--Exception 回報在那一步。關閉專案不會被拒絕,但會停止播放並等它結束,而播放本身可能正在等這個處理器:兩邊可能互相等候。這類工作請放到播放結束之後:腳本裡寫在 PlayNcFile 之後的那一行,要等每一步的處理器都執行完才會執行。
  • 執行進行中,請勿從另一條執行緒播放動作。 從主機自己的執行緒或網頁請求呼叫的 PlayAct (API)、PlayToolingTeleport (API) 或 PlayClTeleport (API),以及主機呼叫的 LocalProjectService 的 Act (API),在播放器執行中或暫停時——任務,或步物理重算之類的工作——什麼都不播放,並回報 Play--BusyAct;任務腳本自己在播放器執行緒上的呼叫,以及 NC 內嵌腳本的呼叫,則會放行。另一條執行緒正在本工作階段播放 NC 時,來自其他任何執行緒的動作一律不播放,並回報 Play--BusyActAnotherThread。它們被拒絕時都回傳 false,被放行時回傳 true,呼叫者可以據此檢查。這類呼叫請寫在任務腳本裡,或放到執行結束之後。
  • 請勿將 SessionStepBuilt (API) 事件中的 UpdateNcOptOption 與 NC 內嵌優化命令併用。 並行計算可能造成未定義行為。
  • 請勿把 NaN 寫進逐步的 NcOptOption。 求解該步時會拒絕 NaN 的每刃進給邊界:該步保留仿真進給率,並以一則指名選項值的錯誤回報,其餘各步照常優化。見當某一步解不出來時。

全域變數

Global (API) 提供跨腳本共享資料的鍵值字典:

Global["material"] = "Steel";
var material = Global["material"];

完整 API 參考

完整命令、屬性與事件清單請參閱:

延伸閱讀