腳本命令¶
什麼是腳本命令?¶
腳本命令 即 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 等)皆可使用。
執行模型¶
工作階段生命週期¶
- 腳本在執行頁的任務分支上依序執行
- 由
PacePlayer(API) 控制播放 —PlayNcFile(API) 之類的腳本命令會阻塞至 NC 程式完成 - 播放器控制命令(
Pace(API)、Pause(API)、Reset(API))與PacePlayer(API) 互動。任務腳本在播放器執行緒上執行,所以它自己的Reset()會以Reset--Refused拒絕、什麼都不重置,因為這個重置會在腳本自己的這次執行底下結束工作階段、清除運行時狀態——要在兩支程式之間重置,請改用ResetRuntime(API) 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 上:
在 Fanuc 家族的控制器上,同一段腳本寫在括號內:
單節所帶的腳本會不會照字面執行,由三條規則決定:
- 每個標記各只寫一次,而且腳本寫在最後。 標記會把自己到該則註解結尾的所有文字吃進腳本,所以寫在腳本後面、但仍在同一則註解內的東西會被當成腳本的一部分——同一則註解裡的第二個
@@會被第一段腳本整段吞掉。 - 同一則註解要放兩段時,
@@要寫在@@^之前。 行後腳本會先被取出,所以先寫@@^的註解,它的@@會被行後腳本整段吞掉。 - 一行只寫一則括號註解。 括號註解從該行第一個
(讀到最後一個),所以第二則註解會被當成第一則的一部分。在 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) 提供跨腳本共享資料的鍵值字典:
完整 API 參考¶
完整命令、屬性與事件清單請參閱:
SessionShell(API) — 完整 API 文件- SessionShell — 命令家族,以及各由哪個工作流程使用
延伸閱讀¶
- SessionShell — 這套語法所能觸及的命令家族
- 步 (Step) — 加工步資料模型
- 基礎仿真 — 在仿真流程中使用腳本
- 刀位 (CL) 播放 — 從腳本重播 CL 刀具路徑
- ShellProgress — 執行中的腳本所寫入的訊息串流
- NC 優化原理 — 逐步優化選項的作用,以及求解失敗的步如何被回報