工作流程:透過 Web API 建構專案¶
基礎加工仿真說明專案裡有什麼。本頁說明如何把專案建到真正完成——避免返工的順序、任務該怎麼安排,以及那道驗收測試:它告訴你專案已經完成,而不只是填滿了。
本頁寫給依客戶交付物組出 .hincproj 的人——不論是操作瀏覽器介面的人,還是透過 HTTP API 執行同樣操作的代理程式 (agent)。某一步有 API 形式時,路由就寫在那一步旁邊。透過 API 重播並驗收建好的專案,見透過 HTTP API 進行重播驗收。
flowchart TD
New["1 · 新專案<br>(自足的根目錄)"]
Assets["2 · 放入資產<br>NC、STL、資源檔"]
Equip["3 · 設備<br>機構鏈、主軸"]
Job["4 · 工作<br>毛胚、目標幾何、材料"]
Ctrl["5 · 控制器<br>品牌 + 它自己的表"]
Tools["6 · 刀具庫"]
Mission["7 · 任務<br>分組、各組各自的解析度"]
Replay["8 · 重播並讀<br>每一則訊息"]
Cross["9 · 數值交叉核對"]
Assume["10 · 記錄每一個假設"]
New --> Assets --> Equip --> Job --> Ctrl --> Tools --> Mission --> Replay --> Cross --> Assume
Replay -->|任何警告| Ctrl
透過 API 建構,而不是編輯 XML¶
透過服務的 HTTP API 建立與修改專案。它與介面走的是同一條程式路徑,所以這樣建出來的專案,走的是受支援的建立/載入/儲存路線。手寫 .hincproj XML 只是 API 還碰不到的欄位的退路——而碰到這種欄位時,更好的解法是把那個端點補上。
下面各步所依賴的登入、回應封套、檔案根目錄、專案生命週期與以鍵編輯物件的模式,都在透過 HTTP 驅動網頁服務(英文,未鏡像),那一頁也列出框架自己的 OpenAPI 文件寫錯的請求本體。其中有三條規則,決定了一次腳本化的建置能不能信任:每一個回應都要檢查 success,而不只看 HTTP 狀態;透過鍵在幾何或變換器內部編輯之後,下一次執行之前要重新裝入那個欄位;不要操作別人正在使用的執行個體(這一條寫在〈One Service, One Project〉頁,英文,未鏡像)。
執行讀的是哪些端點¶
專案帶著兩個控制器模型:仿真播放所用的執行器,以及存在它旁邊的一個 legacy 模型。兩者有好幾條路由長得很像,而寫進 legacy 模型的值會被接受、儲存、讀回,一聲不吭,執行卻從來看不到它。機台資料要經由下面這些路由寫入:
| 資料項 | 執行讀取的路由 | 執行會忽略的相似路由 |
|---|---|---|
| 機構鏈 | POST /api/mech/machine-tool/load——見下文 |
— |
| 主軸能力 | POST /api/mech/spindle-capability/load-file {rootName, relFile} |
— |
| 控制器品牌 | POST /api/mech/soft-nc-runner/brand {Brand, CopyWorkCoordinates} |
PUT /api/Controller/cnc-brand |
| X、Y、Z 行程 | PUT /api/Controller/stroke-limit-xyz,本體恰好是六個數 [minX, maxX, minY, maxY, minZ, maxZ],單位 mm,會同時寫入兩個模型——個數不對就回應 400,什麼也不寫;或 PUT /api/mech/soft-nc-runner/machine-limits/{axis} {Positive, Negative} |
— |
| 行程極限檢查 | PUT /api/Controller/stroke-limit-check,本體為 true 或 false——專案層級的開關,不屬於兩個模型中的任何一個,隨專案儲存,預設打開。關掉時,播放每一步的檢查(Stroke-Limit--Over)與工作階段開始時的 StrokeLimit--Unconfigured 警告都會停止;每個 NC 單節結束時的位置仍會與已設定的極限比對(StrokeLimit--Positive、StrokeLimit--Negative),但在單節途中超出行程的移動(例如鑽孔循環的下刀、圓弧)這時就不會回報 |
— |
| 切屑截斷 | PUT /api/Controller/chip-stock-truncation,本體為 true 或 false——專案層級的開關,不屬於兩個模型中的任何一個,隨專案儲存,預設關閉;回饋模式的一半。任務的物理模擬命令執行時會把兩半都設好,所以寫在這裡的值只留到執行走到那個命令為止:要用回饋模式播放,就改設命令的欄位(PUT /api/Mission/commands/{path}/fields/feedbackMode,在透過 HTTP 建構任務的表裡),或在命令執行之後才寫這裡 |
— |
| 撓曲變換 | PUT /api/Controller/deflection-transformation,本體為 true 或 false——回饋模式的另一半,專案層級的開關,隨專案儲存,預設關閉,物理模擬命令以同樣的方式設定它 |
— |
| 快速進給率 | PUT /api/mech/soft-nc-runner/rapid-feedrates/{axis} {Value},mm/min(旋轉軸為 deg/min) |
PUT /api/Controller/rapid-feedrate |
| 原點/G28 參考點 | PUT /api/mech/soft-nc-runner/home-positions/{axis} {Value} |
— |
| 換刀位置 | PUT /api/mech/soft-nc-runner/tool-change/{axis} {Value},或以 {Stay: true} 讓該軸停在原處 |
— |
| 換刀時間 | PUT /api/mech/soft-nc-runner/tool-change/tooling-time {Value},單位秒 |
PUT /api/Controller/tooling-time |
| 最高主軸轉速 | PUT /api/mech/soft-nc-runner/controller-params/max-spindle-speed {Value},rpm——只記錄、不讀取(§4) |
— |
| 副程式資料夾 | PUT /api/mech/soft-nc-runner/subprogram-folders {InternalFolder, ExternalFolder},相對於專案資料夾 |
— |
stroke-limit-xyz 因個數不對而回應的 400,會寫明它預期的形狀與實際收到的個數——送了五個數時,訊息是 Expected 6 values [minX, maxX, minY, maxY, minZ, maxZ] in mm; got 5.。沒有本體、或本體為 JSON null 的請求,在這條路由執行之前就被拒絕:框架自己的驗證會回應一個 400,本體是 problem details 格式的 JSON 物件,而不是那則訊息。
machine-limits/{axis}、rapid-feedrates/{axis}、home-positions/{axis} 與 tool-change/{axis} 這四條逐軸路由,{axis} 只接受它們各自的 GET 所列出的軸名之一,不分大小寫,並以列出的寫法寫入,所以 machine-limits/x 設定的是 X。列出的軸名,是品牌預設組預先放入的 X、Y、Z,再加上工具機機構鏈所增加的軸(載入工具機之後核對軸組);這些路由本身不會增加任何軸。其他任何名稱都會被拒絕:回應仍是 HTTP 200,帶著 "success": false、放在 axes 裡的已列出軸名,以及一則點名該名稱的 message——No axis 'Q' on this machine; its axes are X, Y, Z, B, C.,一個軸名都沒列出時則是 No axis 'Q' on this machine; it has no axes yet.——什麼也不寫。只在忽略大小寫時才同時符合多個已列出軸名的名稱,也同樣被拒絕,而不是挑一個來猜:No axis 'ax' on this machine: several axes (AX, Ax) match it only ignoring letter case, so none is taken; its axes are …。
程式資料表也有同樣的分裂:執行所解析的工件偏移與刀具補正,是執行器的那一份,位於 /api/mech/soft-nc-runner/ 之下(§4)。每一個值都要在儲存並重新載入之後,用同一條路由的 GET 讀回來。
載入機構鏈¶
從檔案載入時,機構鏈經由 POST /api/mech/machine-tool/load 載入,本體為 {"RootName": "ProjectDirectory", "RelFile": "MachineTool/<name>.mt"}。RootName 是 ProjectDirectory 或 ResourceDir,其他任何根目錄都會以 400 拒絕。因此,在別處建好的機構鏈要先放進專案資料夾——經由檔案路由上傳——再從 ProjectDirectory 載入。在 ResourceDir 底下挑中的機構鏈,會連同附屬檔案以相同的相對路徑寫進專案,並在那裡被參照。(POST /api/mech/machine-tool/update 安裝的是已經在物件存放區裡的機構鏈,…/create 則安裝一個空白的刀位 (cutter-location) 裝置;兩者都不讀檔案。)
不論載入成功與否,這條路由都回應 HTTP 200:檔案不存在,或載入器拒收的機構鏈,會以 "success": false 回來,原因寫在 message 裡。成功時,本體會寫出機構鏈的 typeName 與專案所記錄的 relFile,之後 GET /api/mech/machine-tool 也回報同樣的內容。載入的回應不帶載入器的訊息:機台缺少的端錨點、或大小寫寫錯的端錨點,會回報到服務日誌(GET /api/Project/logs),並在專案儲存之後,出現在下一次 POST /api/Project/reload 的 messages 裡。兩個端錨點缺了任何一個的機台都無法執行。資源庫裡沒有的機台,可以不帶任何形狀建出來——見沒有模型的機台。
1. 單一自足的根目錄¶
.hincproj 與它參照的每一項資產都放在同一個資料夾底下——專案自己的目錄——而每一個參照都相對於它,不帶 ../。
<project>/
├── <name>.hincproj
├── NC/ 任務播放的程式
├── Delivered/ 客戶的檔案,與收到時完全一樣
├── Geom/ 工件/夾具 STL
├── MachineTool/ 運動學機構鏈
├── SpindleCapability/
├── WorkpieceMaterial/
├── CuttingParameter/
├── CutterMaterial/
└── README.md 假設了什麼,以及為什麼
有兩樣東西不會自己搬過來,所以在接上任何東西之前,先手動把它們帶進來:
- NC 檔案。 程式檔案命令只存一個單純的相對路徑,沒有任何東西會替你複製檔案。
- 工具機的附屬檔案。 把機構外置的機構鏈,以不帶路徑的檔名參照附屬檔案與它的 STL 實體,相對於
.mt自己所在的資料夾——整個資料夾要放在一起。
資源檔(機構鏈、主軸、切削參數、工件材料、刀具材料)是事先備好、以參照載入的資料。從根目錄資源目錄載入其中一個,會在相同的子路徑——例如 WorkpieceMaterial/<name>——寫出專案自己的副本,並記錄那個相對於專案的路徑,所以儲存後的專案從不指向共用資源庫;已經在專案裡的檔案,就在原處被參照。先把檔案上傳進專案、再從根目錄專案資料夾載入,結果相同,而且在每個版本上都行得通:每次從資源庫挑選之後,都要確認副本已經落在專案資料夾裡,沒有的話就自己上傳(檔案與具名根目錄(英文,未鏡像))。
程式:保留交付原件,播放副本¶
每一支程式都照客戶交付時的原樣保留在 Delivered/ 底下,播放的是 NC/ 裡的副本。只做三種修改,而且只改副本:
- 呼叫查找所需的檔名。 以編號呼叫的副程式或巨集,只會在副程式資料夾裡的一組固定檔名下被找到——
P25呼叫找的是O0025.NC或O25.NC等等;見通用 NC 碼支援。以O25.dat交付的被呼叫程式,就以其中一個檔名複製一份,內容一字不動。找不到的被呼叫程式會回報為錯誤,該次呼叫被跳過,執行仍會跑完——而所有切削都在被呼叫程式裡時,就什麼也沒切到。 - 會改變結果的寫法。 當一次重播顯示,有某種結果所依賴的寫法,讀取器沒有照它的意思處理——由變數選定的
G碼(G[#120])、以變數寫成的巨集引數(G65 P25 A#120)、軸字語排在同一單節另一個G碼之後的參考點返回(G91 G28 G0 Z0)——就把副本裡的那一行改寫成機台實際執行的字面形式(G[#120]的值為 55 時寫G55;G65 P25 A55;該單節是讓 Z 回原點時寫G91 G28 Z0),其餘每一行都維持交付時的樣子。 - 操作員手動做的事。 為操作員手動換刀的機台寫的程式不帶
T… M06,而除了換刀指令或手動裝刀項目之外,沒有任何東西會裝上刀具,所以副本若單獨播放,主軸就是空的、建不出任何加工步(Step-Tool--NotEquipped)。副本保持不加換刀,改在任務裡、該程式的程式檔案上方放一筆指名那把刀的手動裝刀項目:它像操作員那樣裝上刀,不建步、也不佔檔案編號(裝上操作員手動裝的刀;它的路由在透過 HTTP 建構任務的表裡)。刀長仍然是程式的事:程式不做長度補正時,在副本的第一個往下的移動之前加上G43 H1,除非改照現場的做法,把刀長併進工件偏移的 Z(§4)。
每一份改寫過的副本,開頭都加一行註解說明改了什麼,並在專案的 README 裡列出同樣的修改與各自的理由,好讓副本能與交付原件逐行比對。等某個版本能原生讀取那種寫法時,就撤掉改寫,改播放交付的那一行。
只會引發一則已知訊息、不改變運動的寫法——具名的程式標頭、平滑化或前瞻 (look-ahead) 碼、讀取循環時間計時器——可以維持交付時的樣子。把它們以預期訊息列在 README 裡,寫明 id 與每次播放出現的次數,這樣下一次重播就拿這份清單來核對,而不必再調查一次。
2. 安排建置順序以避免返工¶
後面的步驟會讀前面的結果,所以各部分依一個順序放進去:建在最終路徑上的專案、工具機與主軸、工件與它的材料、控制器——先定品牌,再填它自己的表——逐把放進刀具庫的刀具、程式原點、任務,最後儲存、載回來再檢查一次。安排專案建置順序以避免返工列出每一步與它的路由、一把刀具的十個步驟,以及載入工具機之後的軸組核對。
3. 依製程而不是依檔案清單安排任務¶
新專案一建立,裡面就已經有任務,其中的佔位項目要編輯或刪除。把程式分組,每一類工序一個清單命令,依製程執行的順序排列,每個群組帶著自己的加工解析度,以及一筆之後的執行能從它接續的階段末記錄;專案帶著目標幾何時,打開幾何差異偵測。依製程安排任務列出這個配置、它的理由,以及透過 HTTP 建構它的路由。
4. 填好控制器自己的表¶
刀具庫描述的是實體刀具。控制器對同一把刀具有它自己的記錄,而 NC 程式讀的是控制器那一份。兩者都必須存在。
以 Siemens 式的控制器而言,那是兩張表:
| 表 | 存放 | 若是空的 |
|---|---|---|
| 刀具名稱 → 刀號 | T="…" 呼叫所用的名稱 |
刀具永遠不會裝上,程式完全不產生任何加工步 |
| 刀刃補正 | 每個 (tool, edge)(刀具、切削刃):沿刀軸的長度、半徑 |
每一次刀刃呼叫都退回通用補正表,並記錄一則警告 |
數值取自刀具庫,並且寫入之前先斷言兩者相符。警告消失、切削位置卻完全沒動,就證明各列帶的數字是對的——幾何若有偏移,就是兩張表之一錯了。
Note
並不是每一個控制器參數都有讀取它的一方。有些——例如最高主軸轉速——是記錄下來的機台資料,目前處理流程裡沒有任何東西會讀它。把它們填上是好習慣,但不要把這件事回報成修好了一個缺陷;也要記得,把一個猜測的值(例如假設的主軸)複製到第二個地方,就表示真實資料送到時兩處都要改。
透過 API 設定工件偏移¶
服務公開了兩張工件偏移表,而它們不會保持同步:
| 表 | 路由 | 讀取者 |
|---|---|---|
執行器自己的表——在 Fanuc 與 Mazak 上是參數表(#5221+、#7001+) |
GET /api/mech/soft-nc-runner/work-coordinates、PUT …/work-coordinates/{id} {X, Y, Z} |
執行,以及設備頁面的工件座標系 (G54…) 葉節點 |
| legacy ISO 座標表 | GET /api/Controller/iso-coordinate-table、PUT …/iso-coordinate-table/{index} {Index, X, Y, Z} |
下面的對齊呼叫、執行頁的座標標記,以及指名它的腳本 |
程式選用的每一列都要寫進執行器的表,然後在儲存並重新載入之後讀回來。只填 legacy 表的建置,會繞著機械零點播放整支程式:什麼都沒切到,唯一的徵兆是一則 Play-Touch--None 警告,因為停留在零的 G54–G59 列會被當成一種編寫慣例,不發出任何訊息。使用對齊呼叫時,也要把同一列寫進 legacy 表。它的 PUT 只能編輯表裡原本就有的列(G54–G59 與 G59.1–G59.9),其他任何 id 都回應 400。
一列是每根軸都在機械零點時,主軸的刀具安裝點與程式原點相遇的那個機械位置。刀具長度不在其中:G43 H 所選的長度補正會加上刀把長度與伸出量。在程式不做長度補正的情況下、拿刀具對刀記錄下來的偏移,已經包含了那把刀的長度,輸入之前必須先換算。程式仍然不加任何長度,所以執行需要從別處取得它,否則刀尖會在每一個程式 Z 之下整整一支刀長處運行:在程式的副本裡加上 G43 H(§1),或者在零件擺好之後,把刀長加回執行器那一列的 Z 裡,每把刀一列,一如現場的做法。
透過 API 把零件擺到記錄的偏移上¶
重現的方向——保留記錄的偏移,把零件移到它上面——只要一個呼叫:POST /api/Controller/iso-coordinate-table/{index}/align-workpiece-program-zero。它從 legacy 表讀取 {index} 列,把夾具那條從幾何錨點通到床台安裝點的連接上的變換器,改寫成一個靜態平移,使程式原點錨點在每根軸都位於機械零點時落在那個偏移上。回應帶著這個平移,以及變換器改寫前後的 XML;把「改寫前」的 XML POST 到 …/iso-coordinate-table/revert-align-workpiece-program-zero 就能復原。任務腳本裡的同一項操作是 AlignWorkpieceProgramZeroToIso("G54")。
- 它需要專案上有夾具,以及一條帶線性軸(旋轉軸可有可無)的機構鏈。缺了任一樣,它都回應 400,什麼也不改;純粹的刀位裝置不算這樣的機構鏈。
- 它寫入的是從夾具的幾何錨點直通床台安裝點的那條連接——預設形狀的夾具都有這條連接。夾具沒有這條連接、這條連接帶的是動態變換器,或從工作臺到程式原點的路徑不是只經過這條連接時,它會回應 400 並附上原因,什麼也不改。
- 它會以純平移取代那條連接原本的內容,旋轉也包括在內。
- 它只讀一次工件幾何座標系,以及工件通往夾具安裝點與程式原點錨點那兩條連接的現況。先把這些設好,改動其中任何一個之後都要重新對齊。
用探測來證明擺放,而不是信任這個呼叫。在第一次播放之前、或按下重置之後——在重置之前,播放過的工作階段會一直沿用它開始時的擺放——在一個程式從不使用的列上按 P0:POST /api/Controller/iso-coordinate-table/G59/set-to-program-zero 會回應它寫入的 X、Y、Z,這些值必須在捨入誤差內等於記錄的那一列。儲存之前,用 …/G59/set-to-machine-zero 把探測列恢復成機械零點。執行器的 POST /api/mech/soft-nc-runner/work-coordinates/{id}/set-to-program-zero 只回應 success;它的值要用 GET /api/mech/soft-nc-runner/work-coordinates 讀取。
對齊之後,記錄偏移裡的錯誤就不再改變切出什麼,但它會讓整套設置在機械座標裡整體位移,而行程檢查與機台碰撞都看得到這個位移。同一張工作臺上有好幾件零件、每件一個偏移時,P0 只能填帶著程式原點錨點那件零件的那一列——見幾件零件、幾個偏移。
5. 終點是一次乾淨的重播,而不是填滿的表單¶
重播整個任務,並依 id 盤點訊息。 每一則警告都是待辦清單上的一項。不要把任何一則寫成可接受的退路:退路被觸發,就表示專案從沒提供那個退路本來要補上的資料。
讀取訊息時把嚴重性門檻設低,才不會漏掉任何一則。嚴重性有 Message、Success、Progress、Warning、Error——注意沒有 Info,而無法辨識的名稱是在回應本體裡被拒絕,而不是以 HTTP 錯誤拒絕,讀起來跟「沒有訊息」一模一樣。
只剩下已宣告的資訊性訊息——那些陳述一項已知、刻意之限制的訊息——再加上維持交付原樣之寫法的預期訊息(§1),而且每一則都以 id 及它為何不改變結果的理由列在 README 裡時,才停下來。典型會留下來的訊息:
- 每個 NC 檔一則,回報行數;
- 執行器認得並消化、但不建模的機台 M 碼(OEM 輔助功能,例如冷卻液閥),它們會被宣告出來,而不是悄悄忽略。
其他任何訊息都是待做的工作。
乾淨的訊息清單還不等於通過。 沒有先重置就開始的執行,會疊在上一次執行之上播放,而上一次碰到工件的步會讓 Play-Touch--None 無從觸發;在已經切過的毛胚上重播,留下的反而是每把什麼都沒切到的刀各一則 Tool-Touch--None,讀起來像是刀長或偏移出錯,而不是漏了重置。另外兩種失敗各只留下一則警告:從未裝上刀具的執行完全不產生步,仍以 Finished 結束,留下的是 step 清單裡的 Step-Tool--NotEquipped,而不是播放結束的警告(在程式上方放一筆手動裝刀項目就能裝上刀);上面沒有任何程式的執行後作業什麼也不寫,回報的是 StepFile-Write--NoFile/ShotFile-Write--NoFile。這三者,連同抓出它們的檢查,都在透過 HTTP API 進行重播驗收裡。通過這些檢查的重播,仍然必須達到案例自己的標準:那些標準在第一次播放之前寫下,並照原文判定(案例自己的通過標準)。
6. 兩項數值交叉核對——以及它們證明不了什麼¶
訊息抓到的是執行器注意到的東西。這兩項抓的則是完全不產生訊息的基準錯誤。
切削深度對照程式的層深。 在一趟能從 NC 讀出每層下刀量的粗加工上,切削深度的峰值必須等於它。這就釘住了 Z 基準:程式原點若錯了,刀具切下的量就不同,峰值也不會落在程式的數字上。精加工程式沒有層深可讀;改拿它留下的表面來核對它的基準(由參照網格建立工件)。
循環時間對照後處理器自己的估計。 許多後處理器會把每道工序的加工時間以註解寫進程式。把它們加總,與仿真時間比較。
Warning
誠實界定循環時間核對的範圍。它確認的是進給率與路徑長度被正確地採用。它不是與真實機台的比較,因為兩邊忽略的是同樣的東西:沒有加速度模型(時間是路徑長度除以進給率,沒有加減速——這在由數千段短線段構成的精加工上代價最大)、換刀時間預設為零,而且在控制器的原點/G28 參考點與換刀位置表依機台資料填好之前,原點與換刀位置都預設為機械零點(換刀時 Z 移到 0,X 與 Y 不動)。
基於同樣的理由,客戶的「總加工時間」遠高於各工序註解的總和,通常並不矛盾——註解是切削時間,總時間則是包含換刀與工序間移動的實際時間。這是兩個不同的量。
7. 記錄每一個假設¶
真實的交付物都不完整。用合理的數值建置,並把每一個都寫進 .hincproj 旁邊的 README.md——假設了什麼、依據什麼推斷,以及真實數值送到時會改變什麼。常見的項目有:工件偏移、毛胚尺寸與材料、刀具的螺旋角與前角、塗層、伸出量、刀把尺寸、智慧刀把的感測器高度、主軸的功率–扭矩曲線、夾具幾何、對程式副本所做的改寫,以及上面的循環時間輸入。同一份 README 也放著案例的通過標準,在第一次播放之前寫下(案例自己的通過標準)。
對照:專案資料盤點清單是建置之前交給客戶的清單;本節則是建置之後交回去的東西。
延伸閱讀¶
- 安排專案建置順序以避免返工 — 第 2 節的完整內容:建置的每一步與它的路由
- 依製程安排任務 — 第 3 節的完整內容:任務的配置,以及建構它的路由