簡介

霸那控制器 (Botnana Control) 是一款工業以太網 EtherCAT 控制器的快速開發以及學習環境。 目標是幫使用者快速開發以工業以太網 EtherCAT 為基礎的自動控制以及工業物聯網應用。

應用領域

霸那控制器軟體適合以下應用

• 資料收集：做為 Remote Control Unit (RTU) 使用。
• 軸控：BN-B3A-10S 可透過 EtherCAT 控制最多 10 軸馬達，整體支援最多 16 個 EtherCAT 從站。目前已支援台達電、Panasonic、Sanyo Denki 以及 Yaskawa 的 EtherCAT 馬達驅動器，以及台達電的脈波產生器，Copley 的 EtherCAT 驅動器。
• 可透過 EtherCAT IO 模組進行類似 PLC 的控制，目前支援台達電及 Beckhoff 的 IO 模組。
• IIoT：透過內建的 Websocket 伺服器，和客戶的雲端服務或 HMI 整合。
• CNC 控制器。

文件網址：

• Botnana Book: https://botnana.github.io/botnana-book/
• Botnana Book PDF 檔案連結: 下載繁體中文 PDF
• rtForth: https://mapacode.github.io/rtforth/
• rtForth PDF 檔案連結: https://drive.google.com/file/d/1DtmB3rDQxERpZAV0gcrQtP_0uRcDQTwc/view?usp=sharing
• API 函式庫: https://github.com/botnana/botnana-apis

硬體規格

Botnana Control 支援以下幾種硬體：

• Botnana BN-B3A

Botnana BN-B3A

霸那 BN-B3A 規格如下：

採購注意事項： 採購時請明確指定 BN-B3A-10S 型號。

產品型號

這些數字是不同限制。執行期最多可掃描 16 個 EtherCAT 從站，但 BN-B3A-10S 提供 10 個運動軸；I/O 模組、閘道及其他非軸類從站可使用其餘支援的從站位置。

硬體規格

EtherCAT 接口為下方標示為 LAN 的接口。

軟體規格

霸那控制器出廠時預裝了 Linux 以及實時作業系統，以及動程科技自行開發的 Botnana Control，針對 EtherCAT 開發的多軸控制軟體。

可控軸數、支援從站數與執行期掃描容量是不同限制。BN-B3A-10S 最多提供 10 個運動軸， 並支援最多 16 個 EtherCAT 從站的拓撲，其中可包含非軸類 I/O 及閘道裝置。執行期同樣 最多掃描 16 個從站；此實作界限不會把產品公布容量提高至 16 個以上。

軸控軟體

所有等級的 Botnana Control 都支援以下規格：

• 支援 1–16 個 EtherCAT 從站；BN-B3A-10S 最多提供 10 個運動軸。
• 支援 Panasonic、Delta、Sanyo Denki 和 Yaskawa 的 EtherCAT 馬達驅動器。基本上有符合 CiA 402 規範的馬達驅動器都有支援。
• 支援 Beckhoff，Delta 的類比及數位輸出入模組。因應客戶需求陸續整合其他廠牌的 EtherCAT 模組。

基本功能

• Real-time extenstion (Xenomai)
• 系統掃描與設定軟體會回報偵測到的 EtherCAT 從站。偵測結果是唯讀證據，不會自動採用已改變的實體拓撲。
• 支援 EtherCAT 馬達驅動器 HM, PP, CSP, PV, CSV 模式。
• 監控軟體。支援 EtherCAT 馬達驅動器與 IO 模組。
• 可進行二與三軸同動及直線圓弧補間。補間支援具 CSP 模式的馬達驅動器。
• 多軸組功能。
• 即時腳本 （rtForth）。

系統架構

Botnana Control 1.14.4 將瀏覽器內容提供、設定與生命週期協調、具權限的軟體更新， 以及即時運動控制分開處理。因此，控制器執行環境故障時，不會自動移除 HMI 或已儲存 的機台設定。

部署概觀

Operator browser                          Customer application
  | HTTP :3000       | WebSocket :3012        | WebSocket :3012
  v                  +--------------------+    |
+----------------------+                  v    v
| hmi-server           |             +------------------------+
| unprivileged HTTP    |             | motion-server          |
+----------+-----------+             | profile + lifecycle    |
           |                         +-----------+------------+
           | fixed local Unix socket             |
           v                           supervised runtime
+----------------------+                         |
| update-agent         |               +---------v------------+
| package inspection  |               | rtForth VM + motion  |
| and staging         |               | engine + EtherCAT HAL|
+----------------------+               +---------+------------+
                                                 |
                                       EtherCAT master / slaves

圖中的 Operator browser 是操作人員瀏覽器，Customer application 是客戶應用程式； profile + lifecycle 表示設定與生命週期協調，supervised runtime 則表示受監督的 執行世代。圖內只使用 ASCII 文字，以確保 HTML 與 PDF 中的框線對齊。

瀏覽器會與控制器建立兩條獨立的網路連線：

• HTTP 連接埠 3000 用於取得封裝在套件內的 HMI，並執行經檢查的軟體更新程序。
• WebSocket 連接埠 3012 傳送控制器狀態、具有版本檢查的設定作業、即時值、命令及 rtForth 求值要求。

客戶應用程式直接連至 Motion WebSocket。Rust hmi-server 不會代理即時流量， motion-server 也不提供瀏覽器檔案。HMI JavaScript 套件會在建立 Debian 套件前 完成編譯；控制器不再需要部署 Node.js HTTP 伺服器。

程序及權限邊界

systemd 以分開的責任啟動已安裝元件。

開機更新會先得到終止決策，才允許 HMI 及 Motion 啟動。安裝失敗可能留下持久的 Motion 封鎖；此時會儘可能啟動 HMI，讓操作人員檢查結果並安排經檢查的復原套件， 而 motion-server 仍維持封鎖。

Motion Server 及可替換的執行世代

motion-server 包含非即時伺服器／控制面，以及可替換的即時控制器世代。

WebSocket connections
        |
        v
+-----------------------------------------------------------+
| Non-real-time motion-server control plane                 |
|                                                           |
| Request admission     Shared MachineProfile               |
| LiveConnectionRegistry RuntimeSupervisor                  |
| Configuration and topology request coordinators          |
+-------------------------------+---------------------------+
                                |
                      generation-bound channels
                                |
+-------------------------------v---------------------------+
| Runtime generation N                                      |
| request/response tasks <-> rtForth VM tasks               |
| controller task -> motion engine -> hardware abstraction  |
+-----------------------------------------------+-----------+
                                                |
                                      EtherCAT master

圖中的 control plane 是非即時控制面，generation-bound channels 是世代專用通道， 而 Runtime generation N 是可替換的第 N 個控制器執行世代。

程序層級的伺服器在控制器世代啟動、替換或故障時仍可使用。因此 HMI 可以繼續顯示 生命週期狀態、保留的拓撲證據及設定復原控制，而不會將無法取得的即時運動值顯示為正常。

主要擁有權邊界如下：

• MachineProfile 管理已儲存設定檔，以及具有版本檢查的記憶體內共用草稿。
• RuntimeSupervisor 管理作用中世代、生命週期、最近一次 Ready 的建置計畫、啟動 來源，以及最新一次完整的實體拓撲觀察。
• LiveConnectionRegistry 管理即時 WebSocket 成員、彙整作用中工作階段的有界限 流量計數器，並在世代變更時分離或重新繫結每個工作階段。
• 每個 WebSocket 工作階段具有對兩個 rtForth 使用者工作之一的世代專用繫結。過期 繫結不能將工作送至替換後的世代。

系統針對每條連線進行請求准入。可替換的最新值輪詢可以合併；未獲准的命令不會在之後 被默默重送。每條連線也具有有界限的輸出工作及佇列，因此緩慢或飽和的用戶端不會阻塞 其他用戶端的 WebSocket 事件迴圈。Botnana Control 仍最多提供兩個即時 rtForth 使用者工作階段。

內建 HMI 從 About 開啟的 Support diagnostics 畫面，可以要求一份不含請求 內容的快照，比較兩個作用中連線。登錄檔會標示提出要求的瀏覽器，只回報連線時間及 有界限的流量／准入計數器，並在連線關閉時移除該欄。系統不會保留流量歷史，也不會 包含對端位址、請求內容、回應或設定值。

另一個同源 HTTP 操作只會向 root 擁有的本機支援能力要求一項固定操作。該能力只讀取 bnc-motion 與 bnc-hmi 目前及前一次開機的記錄，輸出經允許的分類記錄及中繼資料， 並傳回一份不超過 50 MiB 的記憶體內 ZIP。非特權 HMI 不能選擇 journal 服務、開機、 路徑、命令或封存選項。此協作及即時比較都不屬於支援的客戶 JSON API。

控制器啟動及就緒

每個控制器世代都由不可變的 ControllerBuildPlan 建立。計畫包含該次嘗試所選用的 控制板、週期、Motion 設定、軸、軸組、計時器、EtherCAT 從站及啟動腳本。

只有在下列有界限的程序全部成功後，世代才會成為 Ready：

1. 掃描完整的實體 EtherCAT 鏈，但不採用掃描結果。
2. 比較每個預期位置上觀察到的供應商及產品身分。
3. 保留 EtherCAT 主站，並在保留的執行環境再次檢查連線、回應從站數、身分及已穩定 的 PREOP 狀態。
4. 在控制器能力交給 VM 前，完成必要的裝置 mailbox 作業及 PDO 映射設定。
5. 啟用主站並執行即時控制器。
6. 等待必要的啟動 mailbox 作業完成、穩定的 OP 狀態，以及完整的程序資料工作計數器。
7. 發布 Ready，再將即時 WebSocket 工作階段繫結或重新繫結至該確切世代。

主站成功啟用本身不代表已經就緒。如果任何必要步驟失敗，或操作人員停止拓撲重試， 該世代會維持無法使用；伺服器會發布終止生命週期狀態，不會發布錯誤的 Ready。

重新啟動、復原及拓撲來源

不同操作會刻意選用不同的控制器計畫：

一般替換執行環境時，監督器會停止接受舊世代的新工作、排空已接受要求、分離即時工作 階段、關閉舊世代，再以選定來源建立替換世代。系統會先重新繫結正常工作階段，才發布 Ready。如果一個工作階段無法重新繫結，只會關閉該工作階段；其他工作階段及正常 控制器仍可使用。

拓撲核准、持久儲存及啟動由控制器協調。瀏覽器是檢查者及命令來源，不是多重要求所組成 之儲存／啟動交易的擁有者。

設定及執行狀態

HMI 會顯示數個相關狀態，但其擁有者及生命週期不同。

瀏覽器進度及快取資料列只是呈現狀態，不具權威性。重新整理或重新連線時，會以伺服器 管理的設定、拓撲、生命週期及更新狀態取代它們。

即時執行

執行世代使用有界限且由世代管理的請求及回應通道，在 WebSocket 要求與 rtForth VM 之間傳遞資料。VM 具有五個合作式即時工作：

運動引擎管理軸與軸組協調、限制、補間、路徑預視、計時器及程序 I/O。硬體抽象層透過 原生 EtherCAT 主站，將這些責任轉換至支援的 EtherCAT 裝置。設定擁有權會留在週期 工作之外，直到刻意建立新的控制器世代。

軟體更新信任邊界

瀏覽器可以提供 Debian 套件內容，但不會取得 root 或套件管理程式權限。 hmi-server 會限制 HTTP 上傳，並以固定的 Unix socket 通訊協定串流至具權限的 更新代理程式。update-agent 會獨立檢查套件身分、架構、大小、中繼資料及 SHA-256， 再將確認操作綁定至操作人員檢查過的更新狀態版本。

已確認的 Botnana Control 套件會在下次開機重新驗證，並只嘗試安裝一次。更新程式會 在執行 dpkg 前記錄 Motion 封鎖；只有受管理的安裝成功才能清除封鎖。因此 HMI 及 Motion 服務不會將不完整的套件安裝誤認為安全的運動控制執行環境。

此邊界不是使用者驗證。Botnana Control 1.14.4 沒有新增 TLS、應用程式登入或套件 簽章身分。任何可連至控制網路 HMI 的用戶端都能提交套件供檢查，因此部署環境必須依賴 受保護且由現場管理的網路及操作程序。

故障隔離

客戶 API 邊界

已發行的 botnana-apis 函式庫定義支援的客戶 WebSocket API。內建 HMI 的設定版本、 控制器復原、拓撲維護、連線流量診斷及更新通訊協定都是產品內部協作，除非之後的公開 API 版本明確提升其狀態。不能只因內部路由可在網路上看到，就將它們視為客戶 API。

操作程序請參閱 EtherCAT 控制器復原、 檢查並設定 EtherCAT 拓撲及 軟體更新。支援的客戶整合邊界請參閱 JSON API。

Botnana Control 入門

Botnana Control 入門

Botnana BN-B3A 預設於開機時自動啟動動程科技的 Botnana Control P2P 軸控軟體。

開啟 HMI

將上位電腦連接至 BN-B3A 控制網路，然後使用瀏覽器連上 http://192.168.7.2:3000。如果控制器使用其他已設定的 位址，請改用該位址。

請等待 HMI 連線並顯示目前的控制器生命週期。不要因為頁面已開啟，就認為 EtherCAT 控制器已經就緒。下列範例顯示 Controller & Topology 工作區內的 Ready 控制器。

選擇工作區

請使用 HMI 上方的主要導覽列。只切換工作區不會改變已儲存設定或運作中的控制器。

Slave Configuration、Motion 及 Axis Group 是同一份共用設定草稿的不同 檢視。開始另一項獨佔設定或維護操作前，請先儲存或捨棄目前的編輯。

診斷 HMI WebSocket 流量

客戶可以使用內建 HMI，檢查自行開發 HMI 的流量。請讓客戶 HMI 維持連線，開啟 About，選擇 Open support diagnostics，再找到 WebSocket connection traffic。

此已安裝目標截圖顯示內建 HMI 及另一個作用中用戶端。連線 ID、速率及計數器都是 試車範例，不是文件所定義的預設值。

比較表只顯示目前作用中的連線：

• This built-in HMI 是正在顯示此表格的瀏覽器。
• Other client 是另一個作用中的 WebSocket 應用程式；試車時通常是客戶 HMI。
• Active clients 會對照系統最多支援的兩個 rtForth WebSocket 工作階段顯示。
• 每個用戶端都分為 Poll requests 及 Ordered requests，避免可取代輪詢的延遲 掩蓋逐一處理的工作。

破折號表示該結果不適用於該請求類別。No sample 表示目前的准入等待時間範圍內， 該類別沒有已獲准的請求。

用戶端關閉後，其欄位會消失。重新連線會取得新的暫時連線 ID，計數器也會重設；HMI 不會保留流量歷史，也不會顯示對端 IP 位址、請求內容、回應或設定值。關閉 Support diagnostics 或返回 About 後，每秒一次的診斷重新整理會停止。

此功能是內建診斷工具，不是客戶 WebSocket API。自行開發的 HMI 仍應只使用支援的 JSON API。畫面上的請求速率只是流量量測結果，不能證明運動命令已 完成，也不代表控制器每秒可以執行相同數量的任意 rtForth 程式。

下載支援診斷資料

經授權的服務工程師要求控制器證據時，請開啟 About，選擇 Open support diagnostics，再使用 Download diagnostic log。只開啟此畫面不會收集檔案。

瀏覽器會下載帶有時間戳記的 botnana-support-*.zip，其中包含：

• 簡要的人員可讀摘要及資訊清單（manifest）；
• 經允許的控制器版本、服務狀態、運作時間及網路鏈路狀態；
• 目前及前一次開機中，bnc-motion 與 bnc-hmi 的分類結構化記錄；以及
• 來源無法取得或證據遭截短時的明確通知。

完整 ZIP 上限為 50 MiB，但此大小不代表固定的記錄時數。涵蓋時間取決於可回報事件 的發生頻率，以及控制器的 journal 保留狀況。狀態安定的控制器可能涵蓋許多小時， 或涵蓋目前及前一次開機中可取得的部分；若啟動、重試或失敗事件集中發生，則會更快 用完容量。請檢查 summary.txt，以及 manifest 中的 includedFrom、 includedThrough、sourceCaptureTruncated 與 archiveBudgetTruncated 欄位，確認 該下載檔案的確切涵蓋範圍。檔案遠小於 50 MiB 是正常情況。

系統會在兩項服務及兩次開機之間公平保留最新記錄。Botnana Control 不會重新啟動 服務、啟用額外記錄、改變機台、保留新產生的 ZIP，也不會自動上傳。憑證、機台設定、 請求內容、rtForth script、設定值及對端 IP 位址都會排除。

請由操作人員透過現場核准的支援管道傳送 ZIP。若運動控制連線無法使用，但 HTTP HMI 仍可開啟，即時流量會顯示為無法取得，Download diagnostic log 仍可使用。

檢查及編輯從站設定

開啟 Slave Configuration，檢查已儲存的 EtherCAT 從站及其支援的裝置設定。此 工作區顯示已儲存設定，不是新的實體掃描。如果需要變更實體順序、身分或別名，請 使用拓撲檢查程序。

此工作區內各類資料列的作用不同：

**警告：**頁首的 Read-only 及 Editing 描述的是已儲存設定。這些狀態不會 使機台進入安全狀態，也不會將即時控制轉為設定項目。只有在 Controller & Topology 顯示 Ready，且機台處於現場核准的安全狀態時，才能使用即時控制。

若要編輯已儲存的從站設定：

1. 使用一個瀏覽器工作階段作為目前的設定編輯者。先與其他 HMI 使用者協調，並確認 畫面顯示的已儲存從站是預定設定。

2. 選擇 Edit profile。可編輯的設定儲存格會開放使用；即時狀態及即時控制仍有 各自獨立的作用。

3. 變更需要的設定儲存格，然後等待 HMI 顯示新的草稿版本及未儲存變更數量。

4. 選擇 Review changes。逐列檢查設定項目、已儲存值、未儲存值及所屬畫面。

   

5. 選擇一項操作：

   • Save changes：儲存整份共用草稿，供控制器下次啟動時使用；不會取代運作中 控制器的設定。
   • Discard changes：捨棄整份共用草稿，並恢復已儲存設定。

6. 沒有未儲存變更後，選擇 Finish editing 回到唯讀模式。Finish editing 不會 儲存任何資料。

儲存及捨棄會作用於整份共用草稿，不只限於 Slave Configuration 畫面上可見的 資料列。如果 Review changes 列出其他畫面的編輯，請先與該項編輯的負責人協調。 如果編輯或儲存時回報設定已由其他工作階段變更，請檢查重新整理後的值，不要直接 重複操作。

檢查及編輯 Motion 設定

開啟 Motion，比較運作中控制器使用的整體運動控制值與共用設定中的值。

兩個數值欄位具有不同的生命週期：

• Active controller 顯示目前控制器世代啟動時選用的值。儲存設定不會改變此欄。
• Configuration 在唯讀模式顯示已儲存設定，在編輯模式則顯示共用草稿。截圖刻意 顯示與作用中控制器不同的已儲存值；這些是範例值，不是預設值。

Motion 各列的作用如下：

請使用從站設定一節所述的同一套 Edit profile、Review changes、Save changes 及 Discard changes 程序。不要開始第二個編輯工作階段，也不要試圖只 儲存共用草稿的一部分。

**重要：**儲存 Motion 設定只會準備供之後的控制器啟動使用，不會套用至運作中的 控制器。一般 Rescan EtherCAT 會使用上次正常運作設定，不會使用剛儲存的設定 值。任何受控重新啟動都應依現場試車程序規劃；啟動後先確認 Ready 及 Active controller 回讀，再啟用運動控制。

檢查及編輯軸與軸組設定

開啟 Axis Group，比較作用中的軸與軸組值及其設定值。Motion 中設定的容量會 決定此工作區顯示多少個 Group/N 及 Axis/N 區段。

此工作區依責任區分設定：

軸與軸組的編輯使用同一份共用設定程序；儲存前，應逐項檢查待處理變更所顯示的 Screen。如果在同一份草稿同時變更 Motion 容量及 Axis Group 內容，應依設定的 軸數量重新檢查每項映射。

**警告：**錯誤的比例、方向、映射、限制或裝置指派可能造成非預期運動，或使回授 失效。試車時應停用運動控制，並讓機台保持在現場核准的安全狀態。受控啟動控制器 後，請先確認裝置指派、方向、比例及限制，再啟用運動控制。

分開看待觀察、設定及運作狀態

HMI 會刻意分開管理下列狀態：

• **偵測拓撲（Detected topology）**是最新一次完整 EtherCAT 實體掃描所得的 唯讀證據。掃描不會儲存或採用該拓撲。
• **共用草稿（Shared draft）**包含目前在設定工作區檢查的設定。尚未儲存的草稿 變更不會持久保存。
• **已儲存設定（Saved profile）**是持久儲存在控制器上的設定。
• **運作中的控制器（Running controller）**使用成功啟動時的設定。儲存設定不會 在未告知的情況下取代目前運作中的設定。

一般 Rescan EtherCAT 會使用 Last working settings 重建控制器，不會使用 尚未儲存的編輯。控制器無法使用時，Start controller 會使用檢查過的已儲存 設定。核准的實體拓撲變更則使用專用檢查及 Approve, save, and start 程序。

使用動作控制或即時 EtherCAT 控制前，請等待 Controller & Topology 顯示 Ready。控制器無法使用、正在啟動或回報故障時，請讓機台保持在現場核准的安全 狀態；HMI 指令是維護控制，不是安全連鎖。

依需求繼續操作

• 如果 Controller & Topology 顯示 Controller unavailable，或需要執行一般 重新掃描，請依照 EtherCAT 控制器復原。
• 如果是核准的實體新增、移除、更換或重新排序，請依照 檢查並設定 EtherCAT 拓撲。
• 如果要安裝套件或回復舊版本，請參閱軟體更新。
• 如果要變更控制器 IP 位址，請參閱 USB 連線 IP 設定。
• 如果設定是在 HMI 外維護，請參閱設定檔。

EtherCAT 控制器復原

當 Botnana Control 必須重新偵測已連接的 EtherCAT 硬體，或 Controller & Topology 顯示 Controller unavailable 時，請使用本程序。如果是核准的新增、 移除、更換或重新排序，請改用 檢查並設定 EtherCAT 拓撲。

**安全注意事項：**重新掃描、啟動或重新啟動控制器之前，請依現場核准的程序讓 機台進入安全停止狀態。這些 HMI 操作是維護控制，不是安全功能。控制器無法使用 或正在啟動時，動作控制、指令稿及即時 EtherCAT 控制都無法使用。

瞭解控制器狀態

HMI 會分開管理下列狀態：

• **共用草稿（shared draft）**是 HMI 目前顯示的編輯內容，由各設定工作區共用， 儲存前不會持久保留。
• **已儲存設定（saved profile）**是持久保存的設定，也是 Start controller 使用的設定。
• Last working settings 是上一次正常運作控制器所保留的設定，一般重新掃描會 使用這份設定。
• **運作中的控制器（running controller）**是目前啟用的 EtherCAT 控制器。儲存 設定不會啟動控制器；啟動控制器也不會自動儲存啟動時偵測到的硬體。

請依目前畫面選擇操作：

重新掃描已就緒的控制器

一般重新掃描會使用 Last working settings 重建運作中的控制器，不會套用尚未 儲存的設定變更。

1. 確認機台已進入現場核准的安全狀態。
2. 開啟 Controller & Topology。
3. 選擇 Rescan EtherCAT。
4. 觀察畫面顯示的啟動階段及拓撲重試倒數。拓撲重試期間，Detected slaves 會在每次完成完整實體掃描後更新，因此可以立即看見新增、移除、更換或重新排序 的從站。
5. 將 Detected slaves 和預定的實體串列逐一比較。顯示變更後的掃描結果不代表 已儲存或採用該拓撲。
6. 如果出現 Stop waiting，而且繼續重試已無助益，請依照 停止拓撲等待處理；否則繼續等待。
7. 控制器顯示 Ready 後，確認所有預期的 EtherCAT 從站都已出現，並在恢復 操作前確認機台狀態。

下列重試已觀察到三個實體從站，但已儲存拓撲仍只有一個從站。此時可以使用 Stop waiting，但 detected 資料列仍只是觀察結果，尚未被採用：

如果命令列顯示 Controller start with last working settings failed，表示控制器目前 無法使用。選擇 Details 會開啟標題為 Controller unavailable 的抽屜；接著請 執行復原無法使用的控制器。

停止拓撲等待

當初始開機或操作員要求的控制器啟動正在重試 EtherCAT 拓撲驗證，而且控制器回報 該嘗試可以停止時，Controller & Topology 命令列會提供 Stop waiting。這是協同式 停止，不是回復、強制停止或緊急停止。先前的控制器已經拆除；停止等待後，控制器 仍然無法使用。

1. 讓機台保持在現場核准的安全狀態。
2. 檢查畫面顯示的控制器世代（generation）及設定來源：開機應顯示 Initial startup settings；一般重新掃描應顯示 Last working settings；復原程序則應 顯示 Saved profile。
3. 選擇 Stop waiting。
4. 在確認畫面再次核對相同的世代及設定來源。替代控制器嘗試會警告無法恢復先前 控制器；初始開機則沒有先前控制器。只有在確定要讓控制器維持無法使用時才確認。
5. 畫面顯示 Stopping controller start… 時，等待正在進行的 EtherCAT 掃描 返回。此要求不會強制終止掃描，也不保證最長完成時間。
6. 等到 HMI 報告啟動已停止並顯示 Controller unavailable 後才能繼續。
7. 修正已連接硬體或已儲存設定。如果實體差異是核准的配置變更，請進入 檢查並設定 EtherCAT 拓撲；否則再次啟動控制器。 確認從站及機台狀態。

停止等待不會儲存或捨棄變更、不會更改已儲存設定或 Last working settings，也不會 採用偵測到的硬體。如果 Stop waiting 消失或要求遭拒，請以重新整理後的狀態為 準；不要自行認定啟動已停止。

復原無法使用的控制器

Start controller 一律使用已儲存設定。

1. 在 Controller & Topology 選擇 Details，確認抽屜標題為 Controller unavailable，並讀取失敗原因及嘗試階段。
2. 檢查已儲存設定的版本，以及它是否和 Last working settings 不同。
3. 如果需要修正，開啟 Edit in 欄位所指示的設定畫面，選擇 Edit profile 並進行修改。
4. 檢查所有未儲存變更，然後選擇一項操作：
   • Save changes：讓草稿成為下次啟動使用的已儲存設定。
   • Discard changes：恢復已儲存設定；此操作不會恢復 Last working settings， 也不會啟動控制器。
5. 返回 Controller & Topology，確認畫面顯示預定使用的已儲存設定版本。
6. 選擇 Start controller。
7. 等待驗證、清理、替代控制器啟動及可能發生的拓撲重試。如果出現 Stop waiting，而且重試已無助益，請依照前述停止程序處理。
8. 控制器顯示 Ready 後，確認預期的 EtherCAT 從站及機台狀態，再恢復操作。

如果 Save changes 失敗，變更仍處於未儲存狀態。請修正畫面回報的問題，然後 選擇 Retry save。HMI 確認儲存成功之前，不可將這些變更視為已持久保存。

另一個瀏覽器工作階段可能在您檢查設定時修改設定。此時 Botnana Control 會拒絕 過期的編輯、儲存、捨棄或啟動要求。再次操作前，請檢查重新整理後的設定及修訂版 號。

復原期間重新連線

瀏覽器中斷連線不會取消重新掃描、停止要求或控制器啟動。重新連線後，請先檢查 恢復顯示的控制器世代、設定來源、階段、停止狀態及結果，再進行其他操作。

如果 HMI 持續停在 Stopping controller start…，請記錄可供支援人員使用的 資訊並升級處理，不要自行認定要求已完成。

清理失敗時

bnc-motion 是在 BN-B3A 上執行的 Botnana Control 運動控制服務。它承載 EtherCAT 控制器執行期；不是 EtherCAT 從站、驅動器或馬達。重新啟動它會中斷 控制器連線，屬於獲授權管理員的處理動作，不是一般操作員控制項。

清理程序會停止故障控制器剩餘的工作，並在建立替代控制器之前釋放其執行期連線。 如果清理失敗，在相同 bnc-motion 程序中再次啟動並不安全。HMI 會停用 Start controller，並指示管理員重新啟動此服務。

1. 不要再送出啟動或重新掃描要求。

2. 記錄控制器世代、失敗原因、嘗試階段及結果。

3. 儲存重新啟動後仍須保留的設定變更，或捨棄不需要的變更。如果無法儲存，請先 記錄必要的未儲存數值，因為重新啟動服務可能使其遺失。

4. 確認機台仍處於現場核准的安全狀態。

5. 請獲授權的管理員執行：

   sudo systemctl restart bnc-motion
   

6. 等待 HMI 重新連線並顯示最新狀態。

7. 再次檢查已儲存設定。如果控制器已就緒，請確認從站及機台狀態；如果控制器無法 使用且 Start controller 已啟用，請重新執行復原程序。

8. 如果清理或服務啟動再次失敗，請停止並聯絡支援人員，不要反覆重新啟動服務。

重新啟動 bnc-motion 不會刪除已儲存設定。未儲存變更不是復原來源，不應預期它們 會在重新啟動後保留。

成功清理後發生的啟動失敗並不相同：此時可能再次出現 Start controller，因為 系統仍能安全釋放失敗的替代控制器。只有在 HMI 啟用此操作時才能重試。如果 HMI 要求重新啟動服務，請改用清理失敗程序。

收集有限拓撲追蹤記錄

Botnana Control 1.14.4 套件修訂版 19 以上會在 bnc-motion journal 寫入精簡的 topology.trace 記錄。重新啟動服務或變更設定前，請由獲授權管理員收集；以下 sudo 命令需要管理員權限：

sudo journalctl -u bnc-motion -n 300 --no-pager

請使用控制器世代（generation）串聯核准、預期的已儲存拓撲、發生變化的實體觀察 結果、最終比較，以及 Ready、failed 或 cancelled 結果。精簡身分使用十六進位 position:vendor_id:product_code 格式。重試期間未變的掃描會遭抑制，因此不會每 500 毫秒寫入一筆相同記錄。追蹤不包含裝置設定、指令稿或其他設定內容。

針對 HMI 回報的確切不符情況，請保留下列記錄：

• event=topology.approval；
• event=controller.start；
• event=topology.observed；
• event=topology.verification；以及
• event=controller.start.completed。

不要只為了收集這項有限追蹤而啟用高流量 EtherCAT frame logging。

提供支援人員的資訊

請記錄：

• 失敗時間；
• 控制器世代；
• 失敗原因、嘗試階段及結果；
• 是否曾要求 Stop waiting，以及 HMI 是否顯示已停止的結果；
• 已儲存設定版本，以及當時是否有未儲存變更；
• 預期及實際觀察到的 EtherCAT 從站；以及
• 經過一次獲授權的 bnc-motion 服務重新啟動後，問題是否再次發生。

請將這些資訊保存在現場事件記錄中。不要將 EtherCAT 寫入指令當成疑難排解捷徑。

檢查並設定 EtherCAT 拓撲

當獲授權的試車技術人員要刻意新增、移除、更換或重新排序 EtherCAT 從站時，請使用 引導式拓撲檢查。如果硬體配置不應改變，請使用一般 Rescan EtherCAT。如果故障不是由 核准的配置變更造成，請使用 EtherCAT 控制器復原。

掃描已連接硬體不會儲存或採用硬體。只有明確使用完整掃描建立提案、檢查影響、 儲存、從該確切已儲存版本啟動，而且控制器到達 Ready 後，變更的配置才會生效。

**安全注意事項：**請遵守現場的上鎖、動作停用、電氣隔離及驗證程序。HMI 確認 只記錄您對機台已安全的聲明，不是安全連鎖。控制器無法使用、正在啟動或回報故障 時，請讓機台保持在核准的安全狀態。

瞭解拓撲狀態

Controller & Topology 會分開管理實體觀察結果、提議的編輯、已儲存設定及運作中 的控制器：

各頁籤的數量可用來交叉檢查。Configured 與 Detected 數量不同本身不會造成任何 變更。檢查期間，先前的偵測資料列會標示 Before configuration 及 Reference only， 直到更新掃描完成後才由目前結果取代。

請在 Slave Configuration 檢查驅動器、I/O、通道及其他從站類型設定。切換 Controller & Topology 頁籤不會取代該編輯器。

準備變更

開始拓撲檢查前：

1. 記錄核准的實體變更、目前從站順序、別名、vendor ID、product code 及回復計畫。 必要時拍攝標籤及配線。
2. 確認步驟 1 的回復計畫確實可行：如果變更後的拓撲無法到達 Ready，可以將 原本的從站、實體排列順序及配線恢復成變更前的狀態。
3. 在 Controller & Topology 比較 Configured slaves 和 Detected slaves。
4. 拓撲檢查會以已儲存設定作為比較及回復基準。請儲存必須保留的現有編輯，或捨棄 不需要的編輯，直到 HMI 不再顯示 Unsaved changes。這可避免將一般設定編輯 和拓撲變更混在同一次檢查程序中。
5. 停止正在使用控制器的指令稿、配方、HMI 工作及其他作業。
6. 讓機台進入現場核准的安全狀態；依規定隔離裝置電源、完成核准的實體變更、檢查 配線及順序，而且只有在允許時才能恢復電源。
7. 只有在可使用 Configure detected topology，且附近沒有顯示未解決原因時才繼續。

控制器可以是 Ready；如果刻意改變的實體配置已經和乾淨的已儲存設定不同， 控制器也可能是 Failed。下列範例在新增兩個核准從站前，乾淨的已儲存基準包含 一個從站：

開始引導式設定

1. 選擇 Configure detected topology。
2. 閱讀確認內容；只有在機台已安全時才確認。
3. 等待 Botnana Control 釋放控制器世代及 EtherCAT master、執行更新掃描，並自動 建立完整提案。不要重複送出要求。
4. 更新掃描尚未完成時，Detected slaves 會保留先前資料列，並標示 Before configuration 及 Reference only。
5. 確認 Proposed topology 自動開啟並顯示確切更新掃描。沒有個別的檢查或重新 掃描操作。

此時控制器無法使用是正常狀態。開始檢查不會改變草稿版本或已儲存版本。一般設定 編輯器仍可看見，但偵測拓撲檢查期間會停用。

下列結果提案包含完整的三從站掃描。頁籤數量會持續分別顯示 configured、detected 及 proposed 來源，而提案只開放編輯 Expected Alias：

如果進入要求遭拒，請讀取畫面原因，不要繞過限制。原因可能是控制器工作尚未完成、 正在轉換狀態、有未儲存設定、已有另一項獨佔拓撲作業，或執行期資源無法安全釋放。

檢查並編輯完整提案

1. 確認提案中的每個位置、vendor ID 及 product code 都是預定項目。不能只採用 部分拓撲。
2. 必要時直接在試算表編輯 Expected Alias，只能輸入 0 至 65535 的整數。這可能 重新定位參照；不會寫入實體從站 EEPROM。
3. 檢查畫面所列的每一項清除、預設、移動、保留及別名影響。
4. 確認畫面只有 Cancel 與 Approve, save, and start 兩個操作按鈕。

如果任何資料列或影響不符合預期，請選擇 Cancel、修正硬體或計畫，再從 Configure detected topology 重新開始。

常見影響如下：

不要只為了讓儲存按鈕可用而接受清除或預設值。如果影響不是預定結果，請取消、 修正硬體或計畫後重新掃描，或取消並捨棄草稿。

移除最後一個從站可以產生零資料列的有效提案。空的已儲存從站清單會被視為尚未 試車的拓撲；不代表系統會強制禁止日後連接任何從站。

核准、儲存並啟動

1. 選擇 Approve, save, and start。
2. 確認確切提案拓撲、預期別名及畫面所列影響。
3. 提案頁籤和兩個決策按鈕會立即關閉。一個確切核准要求會將已接受影響、持久 儲存及控制器啟動交由 Botnana Control 處理。伺服器不需等待後續瀏覽器要求即可 完成此序列，因此要求獲接受後，即使此瀏覽器重新連線或關閉也不會中斷。不會 顯示中間的提案或儲存確認訊息。
4. 只有在控制器顯示 Ready 後才能繼續。
5. 恢復動作許可前，確認從站順序、身分、必要裝置設定及機台狀態。

核准及啟動成功後，configured 頁籤會顯示確切的已儲存三從站拓撲，而且控制器會 顯示 Ready：

啟動已儲存或先前控制器時，只會顯示一般控制器生命週期進度。如果出現 Stop waiting 並加以確認，該次嘗試會取消、內部檢查工作階段會結束，而且 HMI 會返回 一般的控制器無法使用狀態。系統不會自動重新開啟拓撲檢查，也不會顯示重試／恢復操作。請依 目前狀態明確選擇 Configure detected topology、Start controller 或修正設定。

不採用提案而取消

當提案硬體不應啟用時，請選擇 Cancel。確認未核准草稿會遭捨棄，而且會恢復 先前控制器。Configured slaves 必須立即恢復為已儲存設定的資料列；取消後提案 資料列不得繼續顯示於此。取消不會改變已儲存設定，也不會採用提案。必要時先恢復相容的實體 硬體，再等待 Ready 並確認機台。

重新連線及故障處理

內部拓撲檢查工作階段屬於控制器，不屬於單一瀏覽器。重新整理或重新連線後，請等待 Restoring topology configuration state 被目前階段取代。繼續前先確認階段、狀態修訂版、草稿及 已儲存版本、偵測快照、提案和檢查結果。如果另一個工作階段已先執行操作，請檢查 重新整理後的狀態，不要重複舊要求。

• **掃描失敗：**舊快照若標示為非目前狀態，不可使用。選擇 Cancel，修正電源、 連線、纜線或偵測狀態，再從 Configure detected topology 重新開始。
• **儲存前核准失敗：**提案仍未核准。修正問題後再次核准，或選擇取消。
• **儲存後啟動失敗：**拓撲設定會結束，而且不會重新開啟提案。核准設定仍已儲存。 請使用一般控制器無法使用流程，並只在允許復原時選擇 Start controller。
• **顯示 Service recovery is required：**不要再啟動程序內操作。記錄階段、版本、 世代及錯誤，請獲授權管理員依照 EtherCAT 控制器復原 中的 bnc-motion 程序處理。

向支援人員回報時，請記錄安裝的 Botnana Control 版本、核准變更、變更前後的實體 身分及順序、檢查階段、草稿及已儲存版本、偵測快照、已接受的影響、最終控制器 狀態，以及任何中斷連線、重試或重新啟動服務的時間。

設定檔

設定檔

Botnana Control 將持久的機台設定儲存在 /etc/botnana-control/motion.toml。此檔案使用 TOML 格式。

支援的設定變更應優先使用內建 HMI。HMI 編輯具有版本檢查，並會以一份共用設定儲存。 HMI 尚有草稿或正在進行拓撲維護時，請勿編輯檔案。若經授權必須手動編輯，應先依現場 維修程序停止控制器，並備份完整檔案。即使設定檔語法正確，內容錯誤仍可能使控制器 無法啟動或造成非預期運動設定。

儲存設定不會改變運作中的控制器。Active controller 會保留控制器成功啟動時選用 的值，直到之後的受控啟動選用已儲存設定為止。一般 Rescan EtherCAT 會使用上次 正常運作設定，不會使用剛儲存的值。

File 及 Server 區段

若要變更控制器網路位址，請使用 HMI About 程序，不要修改 [server].address。

Motion 區段

[motion] 區段管理控制器整體的運動控制及 EtherCAT 啟動值。

boot_retry_window_ms 不是完整的控制器就緒逾時。取得可接受的 EtherCAT 候選主站 後，設定、啟用及就緒檢查會保留仍較晚的既有期限；若既有期限不足，則取得至少 30 秒 的新就緒時間範圍。

EtherCAT 從站及裝置區段

每個已儲存的 EtherCAT 從站以 [[slaves]] 表示。

在內建 Slave Configuration 編輯器中，供應商 ID 及產品代碼永遠是唯讀。實體 身分、順序或別名若有變更，應使用引導式拓撲維護程序檢查，不可當成一般設定值編輯。

裝置欄位依偵測到的產品而異，可能包括原點復歸方法、原點偏移、原點復歸速度、 加速度、輪廓限制、I/O 選擇、編碼器設定或產品專用程序資料設定。只使用 Slave Configuration 對該裝置顯示的欄位，或遵循適用的產品試車說明；不要複製其他產品 的裝置區塊。

Group 區段

每個 [[group]] 項目定義一個協同運作的軸組。

Axis 區段

每個 [[axis]] 項目定義一軸。Axis Group 會依功能分組顯示這些欄位。

驅動器及編碼器指派會參照已儲存拓撲，但不會改變從站的供應商 ID 或產品代碼。任何 受控啟動後，都應在停用運動控制的狀態下確認裝置指派、方向、比例及限制。

Timer 區段

每個 [[timer]] 項目包含從 1 起算的 position 及 name。1.14.4 的設定工作區不 顯示 Timer 設定；只有適用的整合說明要求時才能變更。

最小語法範例

下列範例只顯示 File、Server 及 Motion 語法，不是完整的機台設定，不可取代已完成 試車的控制器檔案。

[file]
spec_version = "0.0.1"

[server]
address = "0.0.0.0:3012"

[motion]
period_us = 2000
axis_capacity = 10
group_capacity = 2
boot_retry_window_ms = 120000

儲存前，請使用 Slave Configuration、Motion 及 Axis Group 檢查支援的 設定及共用的待處理變更清單。

程式開發界面

Botnana Control 內建伺服器。伺服器提供以下程式開發界面：

• JSON API：程式可以使用 JSON 格式和 Botnana Control 溝通。適用於各種 支援 JSON 及 Websocket 的語言，如 C#、C++、Python 等。

JSON API

Botnana Control 的 JSON API 採用 JSON-RPC 2.0 。

程式可以使用 JSON 格式和 Botnana Control 溝通。此一方法適用於各種支援 JSON 格式且具有 Websocket 函式庫的語言，例如：

• C#
• C++
• Python

公開 API 範圍

本章只涵蓋已發行 botnana-apis 用戶端函式庫所公開的客戶 API。Botnana Control 另有供內建瀏覽器 HMI 與內部服務協調使用的方法；伺服器具有某個方法， 不代表它就是公開 API。方法必須先透過 botnana-apis 發行，本章才能將它記載為 客戶整合合約。

本章採用的相容性基準是 botnana-apis 標籤 customer-release-2025-02-21，其對應來源版本為 commit 1946d8d28759。

回傳資料格式

Botnana Control 若回傳資料，格式一律為

tag1|value1|tag2|value2...

注意回傳格式不是 JSON 格式。

自行開發 HMI 的 WebSocket 建議（1.14.3 版）

Botnana Control 1.14.3 提供兩個 rtForth 使用者工作供 WebSocket 用戶端使用。 伺服器接受 script.evaluate 請求後，不會回傳通用的成功或執行完成訊息。 因此，自行開發的 HMI 不可將 WebSocket 傳送成功或未收到錯誤，視為 script 已經執行的證明。

建議在用戶端採用以下限制，以減少請求累積，並讓運動命令較容易驗證：

• 每個 HMI 應用程式盡可能只維持一條 WebSocket 長連線。連線不用時應正常 關閉，重新連線時應加入有限的等待時間，並避免閒置的瀏覽器分頁或連續重連 占用兩個 rtForth 使用者工作。
• 將連線初始化、heartbeat、讀取及命令全部交由同一個送出額度管理。突發請求 不超過 5 個，持續速率不超過每秒 100 個請求。這是流量建議，不代表系統保證 每秒可執行 100 個長時間運行的 rtForth script。
• 操作命令及運動命令的優先順序應高於輪詢，但仍須使用相同的請求額度。較新的 輪詢可取代或取消尚未送出的舊輪詢；延遲或重新連線後不可補送累積的輪詢。
• 只輪詢目前畫面需要的即時數值。穩定不變的設定資料不應每 50 ms 重複讀取。
• 每個唯讀輪詢 script 應限制在 512 UTF-8 bytes 及 32 個 rtForth 操作以內。 運動命令及設定變更不可和可捨棄的輪詢放在同一批次。
• 必須處理伺服器傳回的每一則訊息，尤其是以 error| 開頭的錯誤。 收到 error|Scripts buffer is fulled.、逾時或斷線時，HMI 必須重新讀取並 核對控制器狀態，不可假設命令已經執行。
• 每條連線同一時間最多只能有一個尚待驗證的狀態變更 script。未收到回應時， 不可自動重送運動命令，因為原命令可能已經執行。

rtForth 使用者工作共用目前所選定的軸組。group! 以及依賴該軸組選擇的命令， 應放在同一個 script.evaluate 請求內。需要確認結果時，請在同一段 script 加入會輸出結果的讀回命令。例如：

{
  "jsonrpc": "2.0",
  "method": "script.evaluate",
  "params": {
    "script": "1 group! 100.0e mm/min vcmd! 1 .group"
  }
}

回傳資料會包含第 1 軸組的 vcmd.1 欄位。這可以確認已儲存的命令值，但不能 單獨證明實際物理速度。vcmd! 對 Sine 軸組不產生作用；Sine 軸組所回報的 vcmd 是其設定的正弦速度振幅。

以上是 1.14.3 版的保守建議，可降低請求壓力造成問題的機會，但不能修復已停滯 的連線，也不提供命令恰好執行一次的保證。

Version API

程式可以使用 Version API 取得 Botnana Control 的版本。

{
  "jsonrpc": "2.0",
  "method": "version.get"
}

會回傳以下字串：

version|1.0.0

Configuration API

已發行的用戶端函式庫提供設定讀取、設定修改與 config.save。Botnana Control 1.14.4-21 與更新版本接受這些已發行的請求格式，不要求用戶端協商內建 HMI 使用 的版本感知設定協定。

同一時間只能使用一個設定編輯器。伺服器處理舊版 setter 請求時，會把修改套用至 當時的設定草稿；不帶參數的 config.save 會儲存當時的草稿。舊版請求無法偵測 另一個瀏覽器或用戶端是否在兩個請求之間修改草稿。請勿同時透過客戶 HMI 與內建 HMI 編輯設定。內建 HMI 的版本感知操作仍會執行過期修改檢查。

參數檔的設定，在重開機或重新讀取參數檔後生效。

修改設定參數

修改設定參數並不會立刻將設定值儲存至參數設定檔，也不會影響到各裝置目前使用的參數。

EtherCAT Position 與 Alias 說明：

EtherCAT Position: 依據 EtherCAT 網路佈局，最靠近主站的 Position 為 1, 依序遞增。

EtherCAT Alias: 每一個 EtherCAT 從站都可以設定一個站號的別名。一般設定此別名的方法有兩種：

1. EtherCAT 從站內的 EEPROM，
2. EtherCAT 從站的硬體旋鈕。

在設定參數時,如果 alias 不為 0，就會以 alias 選擇從站。當 alias 為 0，就以 position 選擇從站。

設定 EtherCAT Slave 參數 config.slave.set

方法：

"method": "config.slave.set" 

必要參數：

"alias": Slave Alis。
"position": Slave Position。
"channel": Device Channel，從 1 開始計數。

每個已發行的 setter 請求只會送出一個數值欄位。已發行欄位如下：

• homing_method、homing_speed_1、homing_speed_2 與 homing_acceleration；
• profile_velocity、profile_acceleration 與 profile_deceleration；以及
• pdo_velocity_offset、pdo_torque_offset、pdo_digital_inputs、 pdo_demand_position、pdo_demand_velocity、pdo_demand_torque、 pdo_real_velocity 與 pdo_real_torque。

Wire 範例：設定位置 1 從站之 channel 1 的回歸原點方法。

{
  "jsonrpc": "2.0",
  "method": "config.slave.set",
  "params": {
    "alias": 0,
    "position": 1,
    "channel": 1,
    "homing_method": 33
  }
}

設定運動控制參數 config.motion.set

方法：

"method": "config.motion.set" 

必要參數：

None

已發行 setter 提供 period_us、group_capacity 與 axis_capacity，每個 請求只送出一個數值。

Wire 範例：

{
  "jsonrpc": "2.0",
  "method": "config.motion.set",
  "params": {
    "period_us": 2000
  }
}

設定軸組參數 config.group.set

方法：

"method": "config.group.set" 

必要參數：

"position": 指定軸組，從 1 開始計數。

已發行 setter 提供 name、必須搭配 mapping 的 gtype、vmax、 amax 與 jmax。除軸組型態與 mapping 必須成對送出外，每個用戶端 helper 只送出一個數值。

Wire 範例：將軸組 1 設為對應軸 1 與軸 2 的 2D 軸組。

{
  "jsonrpc": "2.0",
  "method": "config.group.set",
  "params": {
    "position": 1,
    "gtype": "2D",
    "mapping": [1, 2]
  }
}

設定運動軸參數 config.axis.set

方法：

"method": "config.axis.set" 

必要參數：

"position": 指定運動軸，從 1 開始計數。

每個已發行的 setter 請求只會送出一個數值欄位。已發行欄位如下：

• name、home_offset、encoder_ppu、encoder_length_unit、 encoder_direction、vmax 與 amax；
• ext_encoder_ppu、ext_encoder_direction、closed_loop_filter 與 max_position_deviation；
• drive_alias、drive_slave_position 與 drive_channel；以及
• ext_encoder_alias、ext_encoder_slave_position 與 ext_encoder_channel。

Wire 範例：

{
  "jsonrpc": "2.0",
  "method": "config.axis.set",
  "params": {
    "position": 1,
    "name": "X"
  }
}

取得設定參數

取得 EtherCAT slave 參數 config.slave.get

方法：

"method": "config.slave.get" 

必要參數：

"alias": Slave Alias。
"position": Slave Position。
"channel": Device Channel，從 1 開始計數。

範例：

{
  "jsonrpc": "2.0",
  "method": "config.slave.get",
  "params": {
    "alias": 0,
    "position": 1,
    "channel": 1
  }
}

回傳封包

config_slave_alias.1|0
|config_homing_method.1.1|33
|config_homing_speed_1.1.1|1000
|config_homing_speed_2.1.1|250
|config_homing_acceleration.1.1|500
|config_profile_velocity.1.1|1000000
|config_profile_acceleration.1.1|50000
|config_profile_deceleration.1.1|50000
|config_baud_rate.1.1|6
|config_data_frame.1.1|3
|config_half_duplex.1.1|1
|config_uart_p2p.1.1|0
|config_tx_optimization.1.1|1

取得運動參數 config.motion.get

方法：

"method": "config.motion.get" 

必要參數：

None

範例： 取得 motion 設定

{
  "jsonrpc": "2.0",
  "method": "config.motion.get"
}

回傳封包:

config_period_us|2000
|config_group_capacity|7
|config_axis_capacity|10

取得軸組參數 config.group.get

方法：

"method": "config.group.get"

必要參數：

"position": 指定軸組，從 1 開始計數。

範例： 取得 Group 1 設定

{
  "jsonrpc": "2.0",
  "method": "config.group.get",
  "params": {
    "position": 1
  }
}

回傳封包

config_group_name.1|BotnanaGo
|config_group_type.1|2D
|config_group_mapping.1|2,3
|config_group_vmax.1|0.200
|config_group_amax.1|5.000
|config_group_jmax.1|40.000

取得軸組參數 config.axis.get

方法：

"method": "config.axis.get" 

必要參數：

"position": 指定運動軸，從 1 開始計數。

範例： 取得 Axis 1

{
  "jsonrpc": "2.0",
  "method": "config.axis.get",
  "params": {
    "position": 1
  }
}


回傳封包

config_axis_name.1|Anonymous
|config_axis_home_offset.1|0.0000
|config_encoder_ppu.1|1000000.00000
|config_encoder_length_unit.1|Meter
|config_encoder_direction.1|1
|config_slave_position.1|2
|config_drive_channel.1|2

儲存設定參數

儲存設定參數會立刻將設定值儲存至參數設定檔，但不會影響到各裝置目前使用的參數。

關機再開後系統會使用新的設定。

範例：要求儲存 configuration：

{
  "jsonrpc": "2.0",
  "method": "config.save"
}

Real-time Scripting API

Botnana Control 在其 real-time event loop 提供 Real-time script 來滿足更複雜的程式需求。為此提供兩個 JSON-RPC：

• script.evaluate: 解譯 real-time script。注意不可以使用 script.evaluate 來編譯 real-time script。
• script.deploy: 編譯 real-time script。

Real-time script 的指令集請見 Real-time scripting API

解譯 real-time script script.evaluate

方法：

"method": "script.evaluate" 

必要參數：

"script":real-time script 。

範例：以下 RPC 呼叫設定 Drive channel 1 of Slave 1 回歸原點方法的 JSON 命令。

{
  "jsonrpc": "2.0",
  "method": "script.evaluate",
  "params": {
    "script": "33 1 1 homing-method!"
  }
}

部署 real-time script script.deploy

此一命令將 script 轉交至背景執行的 Task 解譯或編譯，避免影響和使用者互動中的 Task。常用於大型 script 的解譯和執行。

方法：

"method": "script.deploy" 

必要參數：

"script": real-time script 。

範例：以下 RPC 呼叫編譯了一名為 p1 的程式。當 p1 執行時會設定 Drive channel 1 of Slave 1 回歸原點方法。

{
  "jsonrpc": "2.0",
  "method": "script.deploy",
  "params": {
    "script": ": p1  33 1 1 homing-method! ;"
  }
}

Real-time Script API

前言

Botnana Control 在其 real-time event loop 中使用了 Forth VM 以滿足更複雜的程式需求。透過 Forth 執行的命令會立刻影響裝置的行為。

文件網址:

https://botnana.github.io/botnana-book/real-time-script-api.html

指令集

除了標準的 Forth 指令，Botnana Control 增加了以下 Forth 指令集。

• 基本指令集
• EtherCAT 指令集
• EtherCAT Drive 指令集
• EtherCAT IO 指令集
• EtherCAT UART 指令集
• EtherCAT Encoder 指令集
• EtherCAT Gateway 指令集
• 軸組 Axis Group 指令集

Botnana 基本指令集

Host primitives

mtime ( -- n )

Current time in milliseconds

.cpu-timing ( -- )

Print information of CPU timing

0cpu-timing ( -- )

Reset CPU timing

.verbose ( -- )

Print verbose infornatiom

回傳訊息範例 :

version_number|1.3.1|period_us|2000|launch_time|2018-08-09T10:19:21Z

.motion ( -- )

Print information of motion.

只能透過 Json API 進行設定。

命令範例:

.motion

回傳訊息：

period_us|2000
|group_capacity|7
|axis_capacity|10 

本節指令集

定時器指令 （timer）

可以使用的定時器總計有 100 個，編號從 1 ~ 100。

內部使用的計時單位是 Nanosecond，64 bits 的無號長整數計數，整個時間周期可以接近 500 年而不溢位。

定時器的定時時間使用 32 bits 的有號整數設定， 所以可以設定最長的時間是 24.8 天。

使用範例：

   100 1 timer-ms!  \ 設定編號 1 定時器的計時時間為 100 ms。
   1 0timer             \ 定時器編號 1 重新計時。
   1 timer-expired? .   \ 檢視定時器編號 1 是否已經超過計時時間。

.timer ( no -- )

顯示定時器編號 no 的狀態。

命令範例:

1 .timer

回傳訊息：

timer_name.1|None|timer_duration.1|0.0 ms|
timer_expired.1|1|elapsed_time.1|307537.1 ms|
start_time.1|0.0 ms|current_time.1|307537.1 ms

0timer ( no -- )

定時器編號 no 重新計時。

timer-ms! ( ms no -- )

設定定時器編號 no 的計時時間為 ms Millisecond。

timer-expired? ( no -- t )

定時器編號 no 是否已經超過計時時間？

本節指令集

數位正反器 （Flip-flop）

數位正反器可用來偵測數位訊號狀態轉移，可以偵測的型態有：

• 高準位觸發(High Level Trigger）
• 低準位觸發(Low Level Trigger）
• 上緣觸發 (Rising Edge Trigger）
• 下緣觸發 (Falling Edge Trigger）

高準位觸發條件

 True              +--------------
                   |
 False ------------+

                   |-----------|
                     Hold Time

   只要滿足 Hold Time 的時間，數位正反器就會切換為真（True）的狀態，
   反之則為假（False）。

   當條件滿足，數位正反器可以一直持續輸出為 True，直到原始訊號轉態為 False。

低準位觸發條件

 True  ------------+
                   |
 False             +--------------

                   |-----------|
                     Hold Time

   只要滿足 Hold Time 的時間，數位正反器就會切換為真（True）的狀態，
   反之則為假（False）。

   當條件滿足，數位正反器可以一直持續輸出為 True，直到原始訊號轉態為 True。

上緣觸發條件

 True              +---------
                   |
 False ------------+

         |---------|------|
           Set-up    Hold
           Time      Time

   要同時滿足 Set-up time 與 Hold Time 的時間，數位正反器才會切換為真（True）的狀態，
   反之則為假（False）。

   因為是邊緣觸發，所以數位正反器只有一個周期的輸出為 True。

下緣觸發條件

 True  ------------+
                   |
 False             +---------

         |---------|------|
           Set-up    Hold
           Time      Time

   要同時滿足 Set-up time 與 Hold Time 的時間，數位正反器才會切換為真（True）的狀態，
   反之則為假（False）。

   因為是邊緣觸發，所以數位正反器只有一個周期的輸出為 True。

可以使用的數位正反器總計有 100 個，編號從 1 ~ 100。因為數位正反器為效率上的考量， 所以名稱是 _uc 結尾的指令沒有檢查編號是否在正確的範圍，所以使用上要特別留意。

使用範例：

   3 1 ff-type!           \ 設定數位正反器編號 1 為上緣觸發。
   2000 1 ff-setup!       \ 設定數位正反器編號 1 的建立時間。
   2000 1 ff-hold!        \ 設定數位正反器編號 1 的保持時間。
   true 1 ff-forth-uc     \ 設定數位正反器編號 1 的原始狀態，應該每個周期執行。
   ...
   1 ff-triggered-uc? .   \ 檢視數位正反器編號 1 是否已經觸發？

.ff ( no -- )

顯示數位正反器編號 no 的狀態。

命令範例:

1 .ff

回傳訊息：

ff_type.1|High Level|setup_time.1|2000|hold_time.1|2000|
setup_count.1|0|hold_count.1|0|last.1|0|triggered.1|0

ff-forth-uc ( t no -- )

每個周期設定給數位正反器編號 no 的狀態 t。

此命令沒有檢查堆疊個數與 no 範圍，使用上要特別注意。

ff-hold! ( us no -- )

設定數位正反器編號 no 的 Hold Time us Microsecond。

ff-last-uc@ ( no -- t )

數位正反器編號 no 最後/新的原始狀態？

此命令沒有檢查堆疊個數與 no 範圍，使用上要特別注意。

ff-setup! ( us no -- )

設定數位正反器編號 no 的 Setup Time us Microsecond。

ff-triggered-uc? ( no -- t )

數位正反器編號 no 是否滿足觸發條件？

此命令沒有檢查堆疊個數與 no 範圍，使用上要特別注意。

ff-type! ( type no -- )

設定數位正反器編號 no 的觸發型態 type。

觸發型態 type 設定值如下：

• 1: 高準位觸發
• 2: 低準位觸發
• 3: 上緣觸發
• 4: 下緣觸發

has-ff? ( no -- t )

是否有編號 no 的數位正反器？

reset-ff ( no -- )

重置數位正反器編號 no。不修改條件，只清除內部狀態。

本節指令集

EtherCAT 指令集

EtherCAT 指令集

.ec-dc ( -- )

顯示 EtherCAT 通訊時間同步的狀況。

命令範例:

.dc-dc

回傳訊息:

dc_adjust_ns|65|dc_diff_ns|-865935|reference_time_diff_ns|2003080
|application_time_diff_ns|2052185

其中的：

dc_adjust_ns:               EtherCAT 主站周期的調整量。
dc_diff_ns:                 EtherCAT 主從站之間的時間相位差。
reference_time_diff_ns:     EtherCAT 從站的周期。
application_time_diff_ns:   EtherCAT 主站的周期。

.ec-emcy ( n -- )

顯示 EtherCAT Slave Position n 的emergemcy message 訊息。目前 Botnana-Control 會依據 status word 中的 fault bit 自動送出 ?ec-emcy 的命令。

命令範例:

1 .ec-emcy  \ 取得 EtherCAT 第 1 個從站的 emergemcy message

回傳訊息:

error_code.1|0x5441
|error_register.1|0x20
|error_data.1.1|0
|error_data.2.1|19
|error_data.3.1|0
|error_data.4.1|0
|error_data.5.1|0
|error_message_cout|1

其中的：

error code:                     等同於 Object 0x603F:00
error register:                 等同於 Object 0x1001: 00
error_data.1 ~ error_data.5:    為驅動器廠家定義的異警訊息。
                                此範例為台達電 A2-E 驅動器所回傳的訊息,
                                error_data.2.1 = 19 表示異警碼 0x13 (緊急停止)

.ec-links ( -- )

顯示 EtherCAT 通訊的連線狀態

命令範例:

.ec-links

回傳訊息:

slaves_responding|3|al_states|8|link_up|1
|input_wc|3|output_wc|3|input_wc_state|1|output_wc_state|1
|input_wc_error|8187|output_wc_error|8233
|waiting_sdos_len|0|ec_ready|1

其中的：

slaves_responding:  EtherCAT 從站的連線數
al_states:          所有 EtherCAT 從站的狀態。8 代表所有從站都在操作模式。
input_wc:           Input Data Working Count。有處理 Input Data 的從站數。
output_wc:          Output Data Working Count。有處理 Output Data 的從站數。
input_wc_state:     Input Data Working Count 正常與否，1 表示正常。
output_wc_state:    Output Data Working Count 正常與否，1 表示正常。
input_wc_error:     計數 input_wc_state = 0 的周期數。
                    通常在開機時因為時間還不能同步，所以在開機初期會增加。
output_wc_error:    計數 output_wc_state = 0 的周期數。
                    通常在開機時因為時間還不能同步，所以在開機初期會增加。
waiting_sdos_len:   等待處理的 SDO 命令數。
ec_ready:           1 表示 EtherCAT 通訊正常。

.ec-wdt-proc-data ( n -- )

顯示 EtherCAT Slave Position n 的 ESC Watchdog Time Process Data 的暫存器設定值。

命令範例:

1 .ec-wdt-proc-data

回傳訊息:

ec_wdt_proc_data.1|1000|ec_wdt_proc_data_busy.1|0|ec_wdt_proc_data_error.1|0

其中的：

ec_wdt_proc_data:       ESC Watchdog Time Process Data 的暫存器設定值
ec_wdt_proc_data_busy:  要求設定或是讀取的指令是否還在執行中?
ec_wdt_proc_data_error: 要求設定或是讀取的指令是否執行失敗?

.sdo ( n -- )

顯示 EtherCAT Slave Position n 的 SDO 指令執行結果。

命令範例:

2 .sdo

回傳訊息：

sdo_index.2|0x6041
|sdo_subindex.2|0x00
|sdo_error.2|false
|sdo_busy.2|false
|sdo_data.2|24
|sdo_data_hex.2|0x0018

其中的：

以 sdo_index.2 為例, .2 表示第 2 個 slave。
sdo_index   : EtherCAT object index。
sdo_subindex: EtherCAT object subindex。
sdo_error   : 此 sdo request 是否有問題,
              可能原因有 index 錯誤, 資料型態錯誤 ... 等等。
sdo_busy    : 此 SDO request 是否還在處理中。
sdo_data    : Object 的值。
sdo_data_hex: 以 16 進位表示 Object 的值。

.slave ( n -- )

顯示 EtherCAT Slave Position n 的資訊。

命令範例:

2 .slave

以第 2 個 slave 為士林電機 SDP 驅動器為例，

回傳訊息：

vendor.2|0x000005BC
|product.2|0x00000001
|description.2|SDP-E CoE Drive
|alias.2|0
|device_type.2|0x00020192
|profile_deceleration.1.2|50000
|profile_acceleration.1.2|50000
|profile_velocity.1.2|1000000
|operation_mode.1.2|6
|home_offset.1.2|0
|homing_method.1.2|33
|homing_speed_1.1.2|1000
|homing_speed_2.1.2|250
|homing_acceleration.1.2|500
|supported_drive_mode.1.2|0x000003ED
|control_word.1.2|0x0000
|target_position.1.2|2641624
|target_velocity.1.2|0
|status_word.1.2|0x0050
|real_position.1.2|2641624
|digital_inputs.1.2|0x00000000
|pds_state.1.2|Switch On Disabled
|pds_goal.1.2|Switch On Disabled

其中的

vendor.2 表示第 2 個 slave 的 vendor id
product.2 表示第 2 個 slave 的 product code
description.2 表示第 2 個 slave 的 description
device_type.2 表示第 2 個 slave 的 device type, 其值為 0x00020192
profile_deceleration.1.2 表示第 2 個 slave 上第 1 個 drive 的 profile deceleration [pulse/s^2], 
profile_acceleration.1.2 表示第 2 個 slave 上第 1 個 drive 的 profile acceleration [pulse/s^2],
profile_velocity.1.2 表示第 2 個 slave 上第 1 個 drive 的 profile velocity [pulse/s],
operation_mode.1.2 表示第 2 個 slave 上第 1 個 drive 的 operation mode, 目前有支援的模式如下：
    1: profile position mode
    3: profile velocity mode
    6: homing mode
    8: cycle sync. position mode
homing_method.1.2 表示第 2 個 slave 上第 1 個 drive 的 homing method, 常用的模式有：
    1 : homing on negative limit and index pulse
    2 : homing on positive limit and index pulse
    3, 4 : homing on positive home switch and index pulse
    5, 6 : homing on negative home switch and index pulse
    33: homing on negative index pulse
    34: homing on positive index pulse
    35: homing on the current position
    其他: 參考驅動器 0x6098::0x00 的說明
homing_speed_1.1.2 表示第 2 個 slave 上第 1 個 drive 的 speed for search switch [pulse/s]        
homing_speed_2.1.2 表示第 2 個 slave 上第 1 個 drive 的 speed for search zero [pulse/s]
homing_acceleration 表示第 2 個 slave 上第 1 個 drive 的 homing acceleration [pulse/s^2]    
supported_drive_mode.1.2 表示第 2 個 slave 上第 1 個 drive 的 supported drive mode, 定義如下：
    Bit 0 : profile posiiton mode
    Bit 2 : profile velocity mode
    Bit 5 : homing  mode
    Bit 7 : cycle sync. position mode
    其他: 參考驅動器 0x6502::0x00 的說明    
control_word.1.2 表示第 2 個 slave 上第 1 個 drive 的 control word, 定義如下：
    Bit 0 : switch on
    Bit 1 : enable voltage
    Bit 2 : quick stop
    Bit 3 : enable operation
    Bit 4~6 : operation mode specification
    Bit 7 : fault Reset
    Bit 8 : halt
    其他: 參考驅動器 0x6040::0x00 的說明       
target_position.1.2 表示第 2 個 slave 上第 1 個 drive 的 target position [pulse]
target_velocity.1.2 表示第 2 個 slave 上第 1 個 drive 的 target velocity [pulse/s]
status_word.1.2  表示第 2 個 slave 上第 1 個 drive 的 status word, 定義如下：
    Bit 0 : ready to switch on
    Bit 1 : switch on
    Bit 2 : operation enabled (servo on)
    Bit 3 : fault
    Bit 4 : voltage enabled
    Bit 5 : quick stop
    Bit 6 : switch on disabled
    Bit 7 : warning
    Bit 10 : target reached
    其他: 參考驅動器 0x6041::0x00 的說明      
real_position.1.2  表示第 2 個 slave 上第 1 個 drive 的 real position [pulse]
digital_inputs.1.2 表示第 2 個 slave 上第 1 個 drive 的 digital inputs, 定義如下：
    Bit 0 : negative limit
    Bit 1 : positive limit
    Bit 2 : home switch
    其他: 參考驅動器 0x60FD::0x00 的說明 

Note: 單位會因驅動器而有不同

數位輸出回傳資料範例，以台達電 EC7062 為例：

vendor.3|Delta|product.3|EC7062|dout.1.3|0|dout.2.3|0|dout.3.3|0|
dout.4.3|0|dout.5.3|0|dout.6.3|0|dout.7.3|0|dout.8.3|0|dout.9.3|0|
dout.10.3|0|dout.11.3|0|dout.12.3|0|dout.13.3|0|dout.14.3|0|
dout.15.3|0|dout.16.3|0

其中的 dout.11.3 代表是第 3 個 Slave 的第 11 個數位輸出。

數位輸入回傳資料範例，以台達電 EC6022 為例：

vendor.7|Delta|product.7|EC6022|din.1.7|0|din.2.7|0|din.3.7|0|
din.4.7|0|din.5.7|0|din.6.7|0|din.7.7|0|din.8.7|0|din.9.7|0|
din.10.7|0|din.11.7|0|din.12.7|0|din.13.7|0|din.14.7|0|din.15.7|0|
din.16.7|0

其中的 din.15.7 代表是第 7 個 Slave 的第 15 個數位輸入。

類比輸出回傳資料範例，以台達電 EC9144 為例：

vendor.5|Delta|product.5|EC9144|aout.1.5|0|aout.2.5|0|
aout.3.5|0|aout.4.5|0

類比輸入回傳資料範例，以台達電 EC8124 為例：

vendor.4|Delta|product.4|EC8124|ain.1.4|0|ain.2.4|0|
ain.3.4|0|ain.4.4|0

.slave-diff ( n -- )

顯示 EtherCAT Slave Position n 的資訊。 只回傳與上次要求不同的資訊。

使用者可以使用 .slave 取得所有參數。使用 .slave-diff 取得自上次執行 .slave 或是 .slave-diff 後被改變的狀態。 如果上次執行 .slave 或 .slave-diff 後狀態都沒有改變， 回傳資料為空字串。

命令範例:

2 .slave-diff

?ec-emcy ( n -- )

當驅動器發生異警時，可以使用此命令讓驅動器將異警訊息（emergency message）傳送回來。

@ec-wdt-proc-data ( n -- )

從 EtherCAT 從站 n 讀回 ESC Watchdog Time Process data 暫存器的值。此命令是要求 EtherCAT 從站將暫存器值傳送回來，不會馬上取得結果。 可以透過 ec-wdt-proc-data-busy? 的結果得知是否已經回傳。

ec-a>n ( alias -- n )

利用 EtherCAT slaves alias alias 找到對應的 Slave position n

Note:

1. alias 不可以為零
2. 假如 alias 不存在，則會回傳錯誤訊息

ec-ain? ( ch n -- t )

EtherCAT slave position n Channel channel 是否為類比輸入？

ec-alias! ( alias n -- )

設定 EtherCAT slave position n 的 alias 為 alias。

Note:

1. alias 除了 0 以外，不可重複。
2. 此設定命令是修改 SII EEPROM 對應的暫存器。如果是由硬體旋鈕控制的，就不需要由此命令設定。
3. 不可以有重複的 alias。
4. 此命令會造成 Real Time Cycle Overrun。要在所有驅動器 Servo OFF 情況執行。

ec-alias? ( alias -- t )

EtherCAT slave alias alias 是否存在？

ec-aout? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為類比輸出？

ec-din? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為數位輸入？

ec-dout? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為數位輸出？

ec-drive? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為馬達驅動器？

ec-emcy-busy? ( n -- t )

EtherCAT slave position n 的 ?ec-emcy 是否等待執行中？

ec-encoder? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為編碼器輸入模組？

ec-gateway? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為閘道器 (Gateway) 模組？

ec-load ( n -- )

將 EtherCAT slave position n 的設定值回復到原廠預設值。相當設定 Object 0x1011:1 為 0x64616F6C (ASCII: l:0x6C, o:0x6F, a:61, d:64)。

如果 EtherCAT slave 有提供回復到原廠預設值功能，大部份會使用此方式。

ec-ready? ( -- t )

EtherCAT 通訊是否備妥或是正常？

ec-save ( n -- )

將 EtherCAT slave position n 目前的設定值存到 EEPROM。相當設定 Object 0x1010:1 為 0x65766173 (ASCII: s:0x73, a:0x61, v:76, e:65)。

如果 EtherCAT slave 有提供設定參數到 EEPROM 的功能，大部份會使用此方式。

ec-uart? ( ch n -- t )

EtherCAT slave position n Channel ch 是否為 UART 模組？

ec-wdt-proc-data@ ( n -- interval )

將 EtherCAT 從站 n 的 Watchdog time interval 放到整數堆疊上。

ec-wdt-proc-data! ( interval n -- )

設定 EtherCAT 從站 n 的 Watchdog time 設定為 interval。其 interval 的時間必須參考從站的 Watchdog 設定。

如果要將 Watchdog 關閉就將 interval 設定為 0 。

ec-wdt-proc-data-busy? ( n -- t )

是否正在執行 @ec-wdt-proc-data 中？

ec-wdt-proc-data-error? ( n -- t )

執行 @ec-wdt-proc-data 的結果是否有錯誤？

list-slaves ( -- )

顯示所以 EtherCAT 從站的 vendor id 與 product code。

測試範例： 第 1 個從站為台達電 A2-E 驅動器 , 第 2 個從站為士林電機驅動器。

回傳訊息：

slaves|477,271601776,1468,1

台達電 A2-E:  vendor_id = 477 (0x1DD)
             product_code =  271601776 (0x10305070)
士林電機 SDP: vendor_id = 1468 (0x5BC)
             product_code =  1 (0x1)

sdo-busy? ( n -- t )

EtherCAT slave position n 的 SDO 命令是否等待執行？

命令範例 1:

2 sdo-busy?

命令範例 2: 讀取 Slave 2 0x6064:0x00 位址的值，等待該命令完成後輸出訊息。

: test-sdo 0 $6064 2 sdo-upload-i32 
           begin 2 sdo-busy? while pause repeat
           2 .sdo ;
 deploy test-sdo ;deploy
 
 Note: 
 1. pause: 表示當下的命令暫停, 等待下一個real time cycle 執行時，再從命令暫停的地方開始執行。
 2. deploy test-sdo ;deploy : 將 test-sdo 指令放到背景執行。
        因為 test-sdo 所定義的命令中有含有等待的指令, 如在當前的 Task 執行，
        就無法再處理後續由 client 端送進來的指令。

sdo-data@ ( n -- data )

取得 EtherCAT slave position n 的 SDO 命令的資料 data。

sdo-error? ( n -- t )

EtherCAT slave position n 的 SDO 命令的執行結果是否有問題？

sdo-download-i16 ( data subindex index n -- )

將設定值 data 以 16 bits 有號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-download-i32 ( data subindex index n -- )

將設定值 data 以 32 bits 有號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

命令範例：

100 0 $60FF 2 sdo-download-i32 \ 將 `100` 寫到 slave position `2` Object `0x60ff`:`0`

sdo-download-i8 ( data subindex index n -- )

將設定值 data 以 8 bits 有號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-download-u16 ( data subindex index n -- )

將設定值 data 以 16 bits 無號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-download-u32 ( data subindex index n -- )

將設定值 data 以 32 bits 無號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-download-u8 ( data subindex index n -- )

將設定值 data 以 8 bits 無號整數的型式透過 SDO 寫到 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-upload-i16 ( subindex index n -- )

以 16 bits 有號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-upload-i32 ( subindex index n -- )

以 32 bits 有號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

命令範例:

0 $6064 2 sdo-upload-i32 \ 讀取 slave position `2` Object `0x6064`:`0`

sdo-upload-i8 ( subindex index n -- )

以 8 bits 有號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-upload-u16 ( subindex index n -- )

以 16 bits 無號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-upload-u32 ( subindex index n -- )

以 32 bits 無號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

sdo-upload-u8 ( subindex index n -- )

以 8 bits 無號整數的型式透過 SDO 讀取 EtherCAT slave n 的 Object Index index: subindex subindex。

until-no-requests ( -- )

等待所有的 SDO Requests 完成。

相當於

: until-no-requests ( -- )
    ." log|until-no-requests" cr
    begin
        waiting-requests?
    while
        pause
    repeat ;

waiting-requests? ( -- t )

是否所有的 SDO 命令都已經執行完畢 ？

本節指令集

EtherCAT Drive 指令集

EtherCAT Drive 指令集

EtherCAT 驅動器通常都會符合 CiA 402 規範，此規範定義了驅動器的操作模式與介面。實際上驅動器並不會實現所有 CiA 402 規範提到的所有功能，在選用驅動器時還是要留意。

目前 Botnana Control 支援以下幾種驅動器的運動模式：

• 位置控制模式 PP (Profile Position Mode）
• 速度控制模式 PV (Profile Velocity Mode）
• 原點復歸模式 HM (Homing mode)
• 扭力控制模式 TQ (Profile Torque Mode)
• 週期同步位置模式 CSP (Cyclic Sync Position Mode)
• 週期同步速度模式 CSV (Cyclic Sync Velocity Mode)
• 週期同步扭力模式 CST (Cyclic Sync Torque Mode)

就應用面來看週期同步模式適合用來做多軸同動或是特殊的軌跡規劃。

位置模式方塊圖：

               +--------+
               | +----> |----------------------- +
               | |CSP   |                        |
               | |      |      +-------------+   v    +-----------+
Target   ----->|-+----> |----->| Position    |-->o--->|  Position |----> Control
Position       |  PP    |      | Trajectory  |        |  Control  |      Effect
               |        |      | Generation  |        |           |
               +--------+      +-------------+        +-----------+
              Mode Seletor

速度模式方塊圖：

               +--------+
               | +----> |----------------------- +
               | |CSV   |                        |
               | |      |      +-------------+   v    +-----------+
Target   ----->|-+----> |----->| Velocity    |-->o--->|  Velocity |----> Control
Velocity       |  PV    |      | Trajectory  |        |  Control  |      Effect
               |        |      | Generation  |        |           |
               +--------+      +-------------+        +-----------+
              Mode Seletor

扭力模式方塊圖：

               +--------+
               | +----> |----------------------- +
               | |CST   |                        |
               | |      |      +-------------+   v    +-----------+
Target   ----->|-+----> |----->| Torque      |-->o--->|  Torque   |----> Control
Torque         |  TQ    |      | Trajectory  |        |  Control  |      Effect
               |        |      | Generation  |        |           |
               +--------+      +-------------+        +-----------+
              Mode Selector

原點復歸方法

在原點復歸模式（HM）中，驅動器會執行 CiA 402 物件 0x6098 所選的方法。驅動器 可能只實作標準方法的一部分，因此仍應以製造商手冊及試車結果為準。

復歸方法會尋找一個參考事件。系統在找到該事件後才套用已設定的原點偏移；原點 偏移不會改變感測器搜尋順序。驅動器通常以 Homing Speed 1 搜尋原點或極限開關， 再以 Homing Speed 2 搜尋最後的編碼器索引脈波。

下列表格使用的詞彙如下：

• 負向及正向是設定後的運動軸方向；
• 有效及無效是設定輸入極性後的邏輯開關狀態；
• 索引脈波是編碼器週期出現的參考脈波；
• 另一側邊緣是原點開關有效區域的另一個邊界；
• → 表示「接著發生」，不表示實際運動方向。

選用指南

CiA 402 及各製造商可能另有其他方法。選用前，必須由驅動器手冊確認支援狀態、輸入 指派、極性及實際行為。

代表性流程

上圖分別以方法 1、3、7 及 37 的一種代表性起始狀態說明流程。下列表格才是各方法 變體的定義。圖中的 S 是起始位置，星號是最後建立的參考事件。

極限開關及索引脈波精化：方法 1–2

原點開關及索引脈波精化：方法 3–6

初始運動取決於目前的原點開關狀態。所選方法會決定使用哪一個開關轉態，以及哪一側 相鄰的索引脈波作為參考。

原點開關及極限反轉保護：方法 7–14

方法 7–10 會先正向搜尋；如果在找到指定的原點開關事件前先遇到正極限，便會反轉。 方法 11–14 會先負向搜尋，並在先遇到負極限時反轉。因此即使起始位置已越過預期的 開關進入方向，仍可回頭尋找參考。

不使用索引脈波的開關參考：方法 17–22

這些方法直接在指定的開關轉態建立參考，不會執行最後的編碼器索引脈波搜尋。

僅使用索引脈波及目前位置的方法

試車任何會移動的復歸方法前，應先確認方向定義、開關極性、感測器排列、可用行程、 搜尋速度、加速度及停止行為，並將馬達與機構分離，或以其他方式確保機台安全。

驅動器運行狀態

               +-------+
-------------->| FSA   +-------------->
Control Word   |       |   Status Word
(0x6040)       +-------+   (0x6041)

FSA (Finite States Automaton) of PDS (Power Drive System)

             Start
               |
               |
               V 0
        +-------------------+
        | Not Ready to      |
        | switch on         |
        | (Not initialized) |
        +-------------------+
               |
               |
               V 1
 +------------------------------+       +-----------+
 |         Switch on            | 15    |   Fault   |
 |         Disabled             |<------|           |
 |  (Initialization completed)  |       |  (Alarm)  |
 +------------------------------+       +-----------+
  ^ 9        |   ^ 7   ^ 10   ^ 12            ^ 14
  |          |   |     |      |               |
  |          v 2 |     |      |               |
  |  +---------------+ |      |               |
  |  |  Ready to     | |      |               |
  |  |  Switch on    | |      |               |
  |  | (Main circuit | |      |               |
  |  |  power off )  | |      |               |
  |  +---------------+ |      |               |
  |    ^ 8   |   ^ 6   |      |               |
  |    |     |   |     |      |               |
  |    |     V 3 |     |      |               |
  |    | +-------------+----+ |        +------+-----------+
  |    | |   Switched on    | |        |  Fault reaction  |
  |    | |                  | |        |     active       |
  |    | |  (Servo ready)   | |        | (Deceleration    |
  |    | +------------------+ |        |  processing)     |
  |    |     |   ^ 5          |        +------------------+
  |    |     |   |            |               ^
  |    |     v 4 |            |               | 13
+-------------------+   11 +---------------+  |
|     Operation     |----->|Quick stop     |  |
|     Enabled       |<-----|active         |  |
|                   | 16   | (Deceleration |  |
|     (Servo on)    |      |  processing)  |  |
+-------------------+      +---------------+  |
                                              Error Occurs 

FSA Transition

Control Word (0x6040:0x0)：

+-----------------------------------------------------------+
+-----------------------------------------------------------+
Bit 15                                                  Bit 0

• Bit 0: Switch On
• Bit 1: Enable Voltage
• Bit 2: Quick Stop
• Bit 3: Enable Operation
• Bit 4: Operation Mode Specification
• Bit 5: Operation Mode Specification
• Bit 6: Operation Mode Specification
• Bit 7: Fault Reset
• Bit 8: Halt
• Bit 9: Operation Mode Specification
• Bit 10: Reserved
• Bit 11: Reserved
• Bit 12: Reserved
• Bit 13: Reserved
• Bit 14: Reserved
• Bit 15: Reserved

Operation Mode Specification:

Status Word (0x6041:0x0)：

+-----------------------------------------------------------+
+-----------------------------------------------------------+
Bit 15                                                  Bit 0

• Bit 0: Ready to Switch On
• Bit 1: Switched On
• Bit 2: Operation Enabled
• Bit 3: Fault
• Bit 4: Voltage Enabled
• Bit 5: Quick Stop
• Bit 6: Switch On Disabled
• Bit 7: Warning
• Bit 8: Reserved
• Bit 9: Remote
• Bit 10: Operation Mode Specification
• Bit 11: Internal Limit Active
• Bit 12: Operation Mode Specification
• Bit 13: Operation Mode Specification
• Bit 14: Reserved
• Bit 15: Reserved

Operation Mode Specification:

FSA State:

+drive-halt ( ch n -- )

命令 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器功能暫停。

此時馬達會依據 0x605D (Halt option code) 設定，暫時性的減速與停止。

+drive-homed ( ch n -- )

標記 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器已經完成回歸機械原點。

此狀態為主站所提供的狀態紀錄。

+pp-cosp ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 9 （Change on set-point） 為 1。

當 Control Word Bit 9 為 1 （Change on set-point）與 Bit 5 （change set immediately） 為 0 時，同方向運動不減速到 0 通過中繼點。

細部功能請參考選用驅動器的 PP 模式描述。

+pp-imt ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 5 （change set immediately）為 1。

當 Control Word 的 Bit 5 （change set immediately） 為 1 時，表示要馬達驅動器只朝向最後所接受的目標位置運動。

細部功能請參考選用驅動器的 PP 模式描述。

+pp-rel ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 6 （absolute/relative）為 1。

細部功能請參考選用驅動器的 PP 模式描述。當 Control Word 的 Bit 6 （absolute/relative）為 1，馬達驅動器以相對位置來處理目標位置。

-drive-halt ( ch n -- )

命令 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器功能繼續。

參考命令 +drive-halt

-drive-homed ( ch n -- )

標記 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器未完成回歸機械原點。

此狀態為主站所提供的狀態紀錄。

-pp-cosp ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 9 （Change on set-point）為 0。

當 Control Word Bit 9 為 0 （Change on set-point）與 Bit 5 （change set immediately） 為 0 時，同方向運動減速到 0 通過中繼點。

細部功能請參考選用驅動器的 PP 模式描述。

-pp-imt ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 5 （change set immediately）為 0。

當 Control Word 的 Bit 5 （change set immediately） 為 0 時，表示要通過每一個馬達驅動器所接受的目標位置。

細部功能請參考選用驅動器的 PP 模式描述。

-pp-rel ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道的馬達驅動器處於 PP 模式時，設定 Control Word 的 Bit 6 （absolute/relative）為 0。

細部功能請參考選用驅動器的 PP 模式描述。當 Control Word 的 Bit 6 （absolute/relative）為 1，馬達驅動器以絕對位置來處理目標位置。

drive-cw! ( cw ch n -- )

直接設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 control word 為 cw。(由 PDO 設定)。

demand-p@ ( ch n -- pos )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 demand position pos。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 demand position (object 0x6062) 映射到 PDO Mapping 上。

demand-tq@ ( ch n -- tq )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 demand torque tq。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 demand torque (object 0x6074) 映射到 PDO Mapping 上。

demand-v@ ( ch n -- vel )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 demand velocity vel。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 demand velocity (object 0x606B) 映射到 PDO Mapping 上。

drive-dins@ ( ch n -- dins )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的數位輸入狀態 dins。(由 PDO 取得資料)。

對應到 object 0x60FD。定義如下：

+-----------------------------------------------------------+
+-----------------------------------------------------------+
Bit 31                                                  Bit 0

• Bit 0: Negative Limit
• Bit 1: Positive Limit
• Bit 2: Home Switch
• Bit 3 ~ 31: 依馬達驅動器廠商定義。

drive-douts! ( douts ch n -- )

使用 SDO 命令，設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的數位輸出為 douts。

對應到 object 0x60FE:0x01。定義如下：

+-----------------------------------------------------------+
+-----------------------------------------------------------+
Bit 31                                                  Bit 0

• Bit 0: Brake。
• Bit 1 ~ 31: 依馬達驅動器廠商定義。

一般而言，驅動器的數位輸出是由馬達驅動器直接控制，如果需要由主站直接控制輸出，就要搭配 drive-douts-mask! 一起使用。

drive-douts-mask! ( mask ch n -- )

使用 SDO 命令，設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的數位輸出遮罩為 mask。

與 drive-douts! 一起使用。

drive-fault? ( ch n -- flag )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 status word Bit 3 (fault) 的狀態 flag。

drive-homed? ( ch n -- flag )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器是否已經回歸機械原點 flag。

drive-nl? ( ch n -- nl )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的負向極限開關是否被觸發 nl。

其狀態來源與 drive-dins@ 相同。

drive-nsl! ( nsl ch n -- )

使用 SDO 命令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的負向軟體極限為 nsl。

對應的 Object 0x607D:0x01。

drive-nsl@ ( ch n -- nsl )

將 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的負向軟體極限放到堆疊上。

此設定值會在開機時從馬達驅動器讀回到主站。在開機後設定負向軟體極限請使用 drive-nsl!，這樣 SDO 命令回應的記憶體位置才會正確。

drive-off (ch n -- )

將 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State 切換到 Switch On Disabled。

drive-on (ch n -- )

將 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State 切換到 Operation Enabled。

drive-on? ( ch n -- flag )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State 是否在 Operation Enabled flag。

drive-org? ( ch n -- org )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 home switch 是否被觸發 org。

其狀態來源與 drive-dins@ 相同。

drive-pl? ( ch n -- pl )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的正向極限開關是否被觸發 nl。

其狀態來源與 drive-dins@ 相同。

drive-psl! ( psl ch n -- )

使用 SDO 命令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的正向軟體極限為 psl。

對應的 Object 0x607D:0x02。

drive-psl@ ( ch n -- psl )

將 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的正向軟體極限放到堆疊上。

此設定值會在開機時從馬達驅動器讀回到主站。在開機後設定正向軟體極限請使用 drive-psl!，這樣 SDO 命令回應的記憶體位置才會正確。

drive-polarity! ( polarity ch n -- )

使用 SDO 命令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的方向定義 polarity。

對應的 Object 0x607E。

drive-rpdo1@ ( ch n -- r1 )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第一個 Rx PDO 資料 （slave -> master）r1。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

drive-rpdo2@ ( ch n -- r2 )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第二個 Rx PDO 資料 （slave -> master）r2。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

drive-stop ( ch n -- )

將 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State 切換到 Quick stop actived。

drive-sw@ ( ch n -- sw )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Status Word sw。(由 PDO 取得資料)。

drive-vmax! ( vmax ch n -- )

使用 SDO 命令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的最高速度 vmax。

對應的 Object 0x6080:0x01。

drive-wpdo1! ( w1 ch n -- )

設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第一個 Tx PDO 資料 （master -> slave）w1。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

drive-wpdo1@ ( ch n -- w1 )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第一個 Tx PDO 資料 （master -> slave）w1。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

drive-wpdo2! ( w2 ch n -- )

設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第二個 Tx PDO 資料 （master -> slave）w2。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

drive-wpdo2@ ( ch n -- w2 )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器使用者規劃的第二個 Tx PDO 資料 （master -> slave）w2。

需要設定主站參數檔，而且該管道的馬達驅動器可以將對應的 object 映射到 PDO Mapping 上。

go ( ch n -- )

設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器 Control Word 的 Bit 4 為 1。

該管道馬達驅動器在 PP 模式時為 new set-point，在 HM 模式時為 start homing。當主站接受到該管道的回應訊息時，會自動將 Control Word 的 Bit 4 設定為 0。

homing-a! ( acceleration ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 homing acceleration acceleration。

對應的 Object 為 0x609A。要留意馬達驅動器的設定單位。

homing-method! ( method ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 homing method method。

對應的 Object 為 0x6098。

homing-v1! ( v1 ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 homing speed for switch v1。

對應的 Object 為 0x6099:0x01。要留意馬達驅動器的設定單位。

homing-v2! ( v2 ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 homing speed for zero v2。

對應的 Object 為 0x6099:0x02。要留意馬達驅動器的設定單位。

op-mode! ( mode ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的操作模式 mode。

對應的 Object 為 0x6060。

目前有支援的 mode 如下：

1: PP
3: PV
4: TQ
6: HM
8: CSP
9: CSV
10: CST

也有已經定義好的模式代號命令：

: pp ( -- mode ) 1 ;
: pv ( -- mode ) 3 ;
: tq ( -- mode ) 4 ;
: hm ( -- mode ) 6 ;
: csp ( -- mode ) 8 ;
: csv ( -- mode ) 9 ;
: cst ( -- mode ) 10 ;

命令範例:

1  1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 PP 模式
pp 1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 PP 模式
3  1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 PV 模式
pv 1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 PV 模式
4  1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 TQ 模式
tq 1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 TQ 模式
6  1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 HM 模式
hm 1 1 op-mode!  \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 HM 模式
8   1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CSP 模式
csp 1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CSP 模式
9   1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CSV 模式
csv 1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CSV 模式
10  1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CST 模式
cst 1 1 op-mode! \ 將 EtherCAT 從站編號 1 第 1 管道馬達驅動器切換為 CST 模式

pds-goal! ( goal ch n -- )

切換 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State goal。主站會依據 FSA State 自動設定 Control Word。

可以切換的 FSA state of PDS 如下：

: switch-on-disabled ( -- goal ) 1 ;
: ready-to-switch-on ( -- goal ) 2 ;
: switched-on        ( -- goal ) 3 ;
: operation-enabled  ( -- goal ) 4 ;
: quick-stop-active  ( -- goal ) 5 ;

drive-on, drive-on 與 drive-stop 命令就是以 pds-goal 命令組合而成：

: drive-on ( ch n -- )
    operation-enabled -rot pds-goal! ;

: drive-off ( ch n -- )
    switch-on-disabled -rot pds-goal! ;

: drive-stop ( ch n -- )
    quick-stop-active -rot pds-goal! ;

profile-a1! ( a1 ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 profile acceleration a1。

對應的 Object 為 0x6083。在 PP 與 PV 模式時會使用到此加速度進行位置或是速度規劃，要留意馬達驅動器的設定單位。

profile-a2! ( a2 ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 profile deceleration a2。

對應的 Object 為 0x6084。在 PP 與 PV 模式時會使用到此減速進行位置或是速度規劃，要留意馬達驅動器的設定單位。

profile-v! ( vel ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 profile velocity vel。

對應的 Object 為 0x6081。在 PP 模式時會使用速度進行位置與速度規劃，要留意馬達驅動器的設定單位。

real-p@ ( ch n -- pos )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的真實位置 pos。(由 PDO 取得資料)。

對應的 Object 為 0x6064。通常單位是脈波數。

real-tq@ ( ch n -- tq )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的實際扭力 tq（由 PDO 取得資料）。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 torque actual value (object 0x6077) 映射到 PDO Mapping 上。通常單位是額定扭力的 0.1%。

real-v@ ( ch n -- vel )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的真實速度 vel。(由 PDO 取得資料)。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 real velocity (object 0x606C) 映射到 PDO Mapping 上。單位有可能是 pulse/s 或是 0.1 rpm。

reset-fault ( ch n -- )

當 EtherCAT 從站編號 n 第 ch 管道馬達驅動器處於 Fault of FAS State 時，將該管道馬達驅動器切換到 Switch on Disabled 的狀態。主站會自動設定對應的 Control Word。

target-p! ( pos ch n -- )

設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的目標位置 pos。(由 PDO 設定位置)。

對應的 Object 為 0x607A。通常單位是脈波數。

target-p@ ( ch n -- pos )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的目標位置 pos。

target-reached? ( ch n -- flag )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Status Word Bit 10 (target reached) 是否為 1 。

其狀態來源與 drive-sw@ 相同。

target-tq! ( tq ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的目標扭力 tq。

對應的 Object 為 0x6071。通常單位是額定扭力的 0.1%。

此命令適合在 TQ 模式下使用。若要在 CST 模式下週期性設定目標扭力，需將 Object 0x6071 設定為使用者 PDO，再使用 drive-wpdo1! 或 drive-wpdo2! 寫入。

target-v! ( vel ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的目標速度 v。

對應的 Object 為 0x60FF。單位有可能是 pulse/s 或是 0.1 rpm。

此命令只適合在 PV 模式下使用，如果是 CSV 模式要設定目標速度則是要使用 drive-wpdo1! 或是 drive-wpdo2!。

tq-ofs! ( ofs ch n -- )

透過 PDO 設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Torque Offset ofs。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 Torque Offset (object 0x60B2) 映射到 PDO Mapping 上。此命令通常用於 CSP、CSV 或 CST 模式，可在馬達驅動器的扭力控制迴路中額外調整扭力目標值。通常單位是額定扭力的 0.1%。

tq-ofs@ ( ch n -- ofs )

透過 PDO 取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Torque Offset ofs。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 Torque Offset (object 0x60B2) 映射到 PDO Mapping 上。

tq-slope! ( slope ch n -- )

使用 SDO 指令設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的扭力輸出變化率 slope。

對應的 Object 為 0x6087。通常單位是額定扭力的 0.1%/s。

在 TQ 模式下，驅動器使用此設定值規劃扭力輸出的變化。通常會搭配 drive-vmax! 使用，避免馬達扭力輸出尚未到達目標時運動速度過快。

until-drive-on ( ch n -- )

等待 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 FSA State 到達 Operation Enabled。

因此命令內含有 pause，所以只適合用於 Background Task。

此命令相當於:

: until-drive-on ( ch n -- )
    begin
        over over drive-on? not
    while
        pause
    repeat
    drop drop ;

until-no-fault ( ch n -- )

等待 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Status Word Bit 3 (Fault) 為 0。

因此命令內含有 pause，所以只適合用於 Background Task。

相當於

: until-no-fault ( channel slave -- )     
    pause pause pause pause pause pause \ 確保收到驅動器最新的 status word
    begin
        over over drive-fault?
    while
        pause
    repeat
    drop drop ; 

until-target-reached ( ch n -- )

等待 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Status Word Bit 10 (target reached) 為 1。

因此命令內含有 pause，所以只適合用於 Background Task。

此命令相當於:

: until-target-reached ( channel slave -- )
    pause pause pause pause pause pause \ 確保收到驅動器最新的 status word
    begin
        over over target-reached? not
    while
        pause
    repeat
    drop drop
;

v-ofs! ( ofs ch n -- )

設定 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Velocity Offset ofs。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 Velocity Offset (object 0x60B1) 映射到 PDO Mapping 上。

此一命令通常用於 CSP 或是 CSV 模式下，可以在馬達驅動器內的速度控制迴路額外調整速度目標值。單位通常是 pulse/s 或是 0.1 rpm。

v-ofs@ ( ch n -- ofs )

取得 EtherCAT 從站編號 n 第 ch 管道馬達驅動器的 Velocity Offset ofs。

需要設定主站參數檔，而且該管道的馬達驅動器可以將 Velocity Offset (object 0x60B1) 映射到 PDO Mapping 上。

PP-TEST 範例

使用 EtherCAT 從站編號 1 第 1 管道的馬達驅動器。

: pp-test
    pp 1 1 op-mode!          \ 切換到 PP Mode
    until-no-requests        \ 等待 op-mode! 命令實際設定到驅動器
    1 1 reset-fault          \ 解除驅動器異警
    1 1 until-no-fault       \ 等待解除驅動器異警完成
    1 1 drive-on             \ Drive On
    1 1 until-drive-on       \ 等待 Drive on 程序完成
    1000 1 1 target-p!       \ Set target position to 1000
    1 1 go                   \ New set-point
    1 1 until-target-reached \ 等待到達目標點
;

deploy pp-test ;deploy       \ 在 Background Task 執行 pp-test

本節指令集

EtherCAT IO 指令集

EtherCAT IO 指令集

EtherCAT IO 包含以下部份：

1. EtherCAT DIN/DOUT/AIN/AOUT 模組。單一種或是綜合的訊號模組。
2. EtherCAT PWM 模組。目前只有支援 BECKHOFF EL2502 模組。因為該模組可以使用同步命令（PDO）控制 PWM Period 與 Duty Cycle。如果是非同步命令 （SDO）的控制方式，使用 SDO upload/download 命令即可。

+ec-ain ( ch n -- )

開啟 EtherCAT 從站編號 n，第 ch 管道的類比輸入。

如選用的類比輸入從站，需要開啟類比輸入管道才能讀到量測值，就可以使用此以指令。

命令範例:

1 6 +ec-ain  \ 開啟 EtherCAT 從站編號 6，第 1 管道的類比輸入。

+ec-aout ( ch n -- )

開啟 EtherCAT 從站編號 n，第 ch 管道的類比輸出。

如選用的類比輸出從站，需要開啟類比輸出管道才能輸出訊號，就可以使用此以指令。

命令範例:

1 2 +ec-aout  \ 開啟 EtherCAT 從站編號 2，第 1 管道的類比輸出。

+pwm-user-scale ( ch n -- )

開啟 EtherCAT 從站編號 n，第 ch 管道的 PWM 自定義 Duty Cycle 命令功能。

-ec-ain ( ch n -- )

關閉 EtherCAT 從站編號 n，第 ch 管道的類比輸入。

命令範例:

1 6 -ec-ain  \ 關閉 EtherCAT 從站編號 6，第 1 管道的類比輸入。

-ec-aout ( ch n -- )

關閉 EtherCAT 從站編號 n，第 ch 管道的類比輸出。

命令範例:

1 2 -ec-aout  \ 關閉 EtherCAT 從站編號 2，第 1 管道的類比輸出。

-pwm-user-scale ( ch n -- )

關閉 EtherCAT 從站編號 n，第 ch 管道的 PWM 自定義 Duty Cycle 命令功能。

ec-ain@ ( ch n -- value )

取得 EtherCAT 從站編號 n，第 ch 管道的類比輸入。

命令範例:

1 6 ec-ain@  \ 取得 EtherCAT 從站編號 6，第 1 管道的類比輸入

ec-ain-error ( ch n -- error )

取得 EtherCAT 從站編號 n，第 ch 管道的類比輸入是否有錯誤。

BECKHOFF AI 模組有提供此一狀態，其錯誤的狀況有以下兩種：

• Over range
• Under range

ec-ain-validity ( ch n -- validity )

取得 EtherCAT 從站編號 n，第 ch 管道的類比輸入是否有效。

BECKHOFF AI 模組有提供此一狀態，表示該管道資料有正確地被主站使用 EtherCAT PDO 讀取。 原始資料 0 = valid, 1 = invalid，為避免字義上混淆，主站在取得資料時就進行反向的操作。

ec-aout! ( value ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道的類比輸出為 value。

命令範例:

100 1 2 ec-aout!  \ 設定 EtherCAT 從站編號 2，第 1 管道的類比輸出為 100

ec-aout@ ( ch n -- value )

取得 EtherCAT 從站編號 n，第 ch 管道的類比輸出 value。

1 2 ec-aout@  \ 取得 EtherCAT 從站編號 2，第 1 管道的類比輸出

ec-din@ ( ch n -- t )

取得 EtherCAT 從站編號 n，第 ch 管道的數位輸入訊號 t。

命令範例:

3 5 ec-din@  \ 取得 EtherCAT 從站編號 5 的第 3 管道的數位輸入訊號

ec-dout! ( t channel n -- )

設定 EtherCAT 從站編號 n，第 ch 管道的數位輸出訊號為 t。

命令範例:

1 2 3 ec-dout!  \ 設定 EtherCAT 從站編號 3，第 2 管道的數位輸出訊號為 1

ec-dout@ ( ch n -- t )

取得 EtherCAT 從站編號 n，第 ch 管道的數位輸出訊號 t。

命令範例:

2 3 ec-dout@  \ 取得 EtherCAT 從站編號 3 的第 2 管道的數位輸出訊號

ec-wdout! ( value index n -- )

以 32 bits 命令資料 value 與編號 index 設定 EtherCAT 從站編號 n 的數位輸出訊號。

命令範例:

$11 1 2 ec-wdout!  \ 設定 EtherCAT 從站編號 2，第 1 與 5 管道的數位輸出。
1   2 2 ec-wdout!  \ 設定 EtherCAT 從站編號 2，第 33 管道的數位輸出。

max-pwm-period@ ( n -- period )

取得 EtherCAT 從站編號 n， PWM 模組支援的最大周期時間 period [us]。

min-pwm-period@ ( n -- period )

取得 EtherCAT 從站編號 n， PWM 模組支援的最小周期時間 period [us]。

pwm-def-out! ( output ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號， 在通訊錯誤時的 Duty Cycle 預設值 output。

pwm-def-out-ramp! ( ramp ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號， 在通訊錯誤時的 Duty Cycle 斜降率 ramp。

pwm-duty! ( duty ch n -- period )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號的 Duty Cycle duty。 Duty Cycle 物理值可以參考 pwm-presentation!指令。

pwm-duty@ ( ch n -- duty )

取得 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號的 Duty Cycle duty。

pwm-period! ( period ch n -- period )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號 Period period [us]。

pwm-period@ ( ch n -- period )

取得 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號 Period period [us]。。

pwm-presentation! ( presentation ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號 Duty Cycle 解析度 presentation。

BECKHOFF EL2502 可以設定的模式有：

pwm-wdt! ( wdt ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號，當通訊錯誤時，訊號輸出模式 wdt。

BECKHOFF EL2502 可以設定的模式有：

• 0: Default watchdog value
• 1: Watchdog ramp active
• 2: Last output value active

pwm-user-gain! ( gain ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號自定義 Duty Cycle 命令增益 gain。

參考 BECKHOFF EL2502 文件中針對 Object 0x8000:0x01 的說明。

pwm-user-offset! ( offset ch n -- )

設定 EtherCAT 從站編號 n，第 ch 管道 PWM 訊號自定義 Duty Cycle 命令偏移量 offset。

本節指令集

EtherCAT UART 指令集

EtherCAT UART primitives

本節指令集

EtherCAT Encoder 指令集

EtherCAT Encoder primitives

本節指令集

EtherCAT Gateway 指令集

EtherCAT Gateway 指令集

閘道器 Gateway 的資料操作是以 Byte 為單位。以類似記憶體存取的方式進行讀取/寫入。

目前支援的硬體是： Anybus X-Gateway

注意事項：

1. 讀取/寫入資料長度限制 1 ~ 4 byte
2. 起始位置必須從 0 開始

0gateway ( ch n -- )

重置 EtherCAT 從站編號 n，第 ch 管道的閘道器。

gateway-in-be@ ( len start ch n -- data )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸入資料，由起始位置 start，資料長度 len bytes， 以 Big-Endian 的位元組順序讀出，放到整數堆疊上 data。

gateway-in-le@ ( len start ch n -- data )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸入資料，由起始位置 start，資料長度 len bytes， 以 Little-Endian 的位元組順序讀出，放到整數堆疊上 data。

gateway-in-len@ ( ch n -- len )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸入暫存器大小 len bytes 放到整數堆疊上。

gateway-out-be! ( cmd len start ch n -- )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸出資料，起始位置 start，資料長度 len bytes， 以 Big-Endian 的位元組順序寫入 cmd。

gateway-out-be@ ( len start ch n -- data )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸出資料，由起始位置 start，資料長度 len bytes， 以 Big-Endian 的位元組順序讀出，放到整數堆疊上 data。

gateway-out-le! ( cmd len start ch n -- )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸出資料，起始位置 start，資料長度 len bytes， 以 Little-Endian 的位元組順序寫入 cmd。

gateway-out-le@ ( len start ch n -- data )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸出資料，由起始位置 start，資料長度 len bytes， 以 Little-Endian 的位元組順序讀出，放到整數堆疊上 data。

gateway-out-len@ ( ch n -- len )

將 EtherCAT 從站編號 n，第 ch 管道的閘道器的輸出暫存器大小 len bytes 放到整數堆疊上。

gateway-ready? ( ch n -- t )

EtherCAT 從站編號 n，第 ch 管道的閘道器是否備妥 ？

本節指令集

軸組 Axis Group 指令集

Job Operation

針對軸組運動使用。Job 指的是所有軸組合作完成的工作。

座標系解釋

• ACS ：Axes Coordinate System (運動軸座標系)
• MCS ：Machine Coordinate System (機械座標系或是大地座標系)
• PCS ：Product Coordinate System/Program Coordinate System (工件座標系)

軸組概念說明

        +--------------+
        |  Coordinator |
        |              |
        +-------+------+
                |
    +-------------------------+
    |           |             |
+---+---+    +--+----+    +---+---+
| Group |    | Group |    | Group |
| (1D)  |    |  (2D) |    |  (3D) |
+---+---+    +--+----+    +--+----+
    |           |            |
    |           +----------+ +----------+------------+
    |           |          | |          |            |
+---+---+   +---+---+   +--+-+--+   +---+---+   +----+--+
|  Axis |   |  Axis |   |  Axis |   |  Axis |   |  Axis |
|       |   |       |   |       |   |       |   |       |
+---+---+   +---+---+   +---+---+   +---+---+   +-------+
    |           |           |           |
    |           |           |           |
    |           |           |           |
+---+---+   +---+---+   +---+---+   +---+---+
| Drive |   | Drive |   | Drive |   | Drive |
|       |   |       |   |       |   |       |
+-------+   +-------+   +-------+   +-------+

Coordinator (同動控制功能):

多軸同動控制。EtherCAT 通訊具有時間同步的特性，所以適合用來實現多軸同動的功能。

此多軸同動控制所選用的 EtherCAT 馬達驅動裝置必須支援周期時間同步位置模式 （Cyclic Synchronous Position Mode），一般而言 EtherCAT 馬達驅動裝置都有支援。

Group （軸組）:

軸組運動功能如下：

1. S 型加減速曲線。
2. 直線與圓弧路徑規劃。
3. 路徑運動速度限制。
4. 路徑預視。
5. 可以多個軸組同時運行（受限於運動軸是否被其他運動功能控制）。

目前有提供以下幾種類型：

1. 單軸 （1D）。
2. 2軸正交 (2D)。
3. 3 軸正交 (3D)。
4. 單軸弦波運動 （Sine wave）。

Axis（運動軸）:

受控於軸組，運行點對點的運動或是進行追隨運動。如果沒有對應的驅動裝置即為虛擬軸。當運動軸為虛擬軸時，其實際位置是由命令位置推算所得。

執行點對點運動時的注意事項：

1. S 型加減速曲線。
2. 運動速度只能在靜止改變。加速曲線會依據運動軸的最大加速度與最大速度進行規劃。
3. 運動中可以隨時改變目標位置。

Drive（驅動裝置）：

實際的馬達驅動裝置。可以是不同廠牌/型態的馬達驅動器。

運動單位

Botnana Control 的長度單位默認為公尺 [m]，時間單位為秒 [s]。 所以速度單位為 m/s, 加速度單位m/s^2，加加速度單位m/s^3。

假設有一個 1D 的直線運動系統，馬達編碼器的解析度設定為 1000000 pulse = 1 m。

以長度單位為公尺的設定範例：

• Group vmax = 0.01 [m/s]
• Group amax = 5.0 [m/s^2]
• Group jmax = 40.0 [m/s^3]
• Group ignorable distance = 0.0000005 [m]
• Axis encoder_ppu = 1000000
• Axis encoder_length_unit = Meter
• Axis vmax = 0.01 [m/s]
• Axis amax = 5.0 [m/s^2]
• Axis ignorable distance = 0.0000005 [m]

以長度單位為脈衝數 (Pulse) 的設定範例：

• Group vmax = 10000.0 [pulse/s]
• Group amax = 5000000.0 [pulse/s^2]
• Group jmax = 40000000.0 [pulse/s^3]
• Group ignorable distance = 0.5 [pulse]
• Axis encoder_ppu = 1
• Axis encoder_length_unit = Pulse
• Axis vmax = 10000.0 [pulse/s]
• Axis amax = 5000000.0 [pulse/s^2]
• Axis ignorable distance = 0.5 [pulse]

假設有一個 1D 的旋轉運動系統，馬達編碼器的解析度設定為 3600000 pulse = 1 rev，以旋轉半徑 100 mm 的切線速度來比擬線性速度。 Botnana Control 是以徑度 (radian) 計算，所以轉換時需要留意。

以長度單位為徑度的設定範例：

• Group vmax = 0.1 [rad/s]
• Group amax = 50.0 [rad/s^2]
• Group jmax = 400.0 [rad/s^3]
• Group ignorable distance = 0.0000005 [rad]
• Axis encoder_ppu = 3600000
• Axis encoder_length_unit = Revolution
• Axis vmax = 0.1 [rad/s]
• Axis amax = 50.0 [rad/s^2]
• Axis ignorable distance = 0.0000005 [rad]

命令位置：

當同動控制功能（+coordinator）開啟後，Botnana Control 會依據運動軸的設定，將運動軸的命令轉換到馬達驅動器的命令位置。 所以當同動控制功能 （+coordinator）開啟後，如果該控制器被運動軸所控制，就無法直接設定馬達驅動器的命令位置。

如果軸組啟動中，且依據路徑規劃開始運動，或是運動中暫停，Botnana Control 會依據軸組的設定將運動命令分配給對應的運動軸， 此時運動軸的命令就會受到軸組控制。如果軸組間有共用運動軸，切換時就必須要留意是否會造成運動軸命令位置不連續。

落後誤差過大處置方式

當實體軸運動時，如果命令位置與實際位置相差過大，通常表示有軸控的問題發生，當停止運動且排除故障後，消除落後誤差過大的方法如下：

• 當同動控制功能沒有開啟或是該馬達驅動器不受運動軸控制時，直接以馬達驅動器的實際位置設定命令位置。例如：

    1 1 real-p@ 1 1 target-p!

• 當同動控制功能開啟，且運動軸不受軸組控制，例如：

    1 0axis-ferr    \ 清除第 1 個運動軸的落後誤差

• 當同動控制功能開啟，且運動軸受軸組控制，例如：

    1 group! 0path     \ 假設是第 1 個軸組，切換軸組為 1，清除路徑
    1 0axis-ferr       \ 假設第 1 個運動軸受控於第 1 個軸組，清除第 1 個運動軸的落後誤差
    2 0axis-ferr       \ 假設第 2 個運動軸受控於第 1 個軸組，清除第 2 個運動軸的落後誤差

Coordinator

.coordinator ( -- )

輸出軸組狀態。

輸出訊息如下：

    coordinator_enabled|0

    coordinator_enabled: 1 表示同動功能開啟，0 表示同動功能關閉。

+coordinator ( -- )

啟動同動控制功能。

由 Botnana Control 進行軸運動控制，Botnana Control會依軸組路徑或是運動軸目標位置進行加減速規劃與位置補間。

在此模式之下，驅動器必須要切換到 CSP Mode。

-coordinator ( -- )

關閉同動控制功能。

#groups ( -- len )

取得軸組數量 len。

#axes ( -- len )

取得運動軸數量 len 。

coordinator? ( -- t )

軸組是否開啟？

empty? ( -- t )

所有軸組的路徑是否已經清空？

ems-job ( -- )

執行同動功能緊急停止。所有軸組與運動軸的點對點運動都會立即停止。軸組的路徑資訊都會被清除。

end? ( -- t )

所以軸組與運動軸點對點運動是否到達路徑終點？

reset-job ( -- )

清除所有軸組的路經資訊。

start-job ( -- )

命令所有軸組開始運動。

stop? ( -- t )

所以軸組與運動軸點對點運動是否已經停止？

stop-job ( -- )

命令所有軸組與運動軸點對點運動減速停止。

本節指令集

Axis Group

.group ( g -- )

輸出 group g 資訊

命令範例:

1 .group  \ 輸出第 1 個軸組的資訊

回傳訊息 :

group_enabled.1|0
|group_stopping.1|1
|move_count.1|0
|path_event_count.1|0
|path_id.1|0
|path_mode.1|0
|focus.1|0
|source.1|0
|pva.1|0.0000000,0.00000,0.00000
|move_length.1|0.0000000
|total_length.1|0.0000000
|feedrate.1|0.00000
|vcmd.1|0.00000
|max_look_ahead_count.1|0
|ACS.1|0.0000000,0.0000000,0.0000000
|MCS.1|0.0000000,0.0000000,0.0000000
|PCS.1|0.0000000,0.0000000,0.0000000

.grpcfg ( g -- )

輸出 group g 的設定參數

命令範例：

1 .grpcfg  \ 輸出第 1 個軸組的設定參數

回傳訊息:

group_name.1|Anonymous
|group_type.1|3D
|group_mapping.1|1,2,3
|group_vmax.1|0.10000
|group_amax.1|5.00000
|group_jmax.1|80.00000
|group_ignorable_distance.1|0.0000005

+group

啟動目前選用的軸組。

命令範例:

1 group!   \ 切換到第 1 個軸組
+group     \ 啟動目前選用的軸組

-group

關閉目前選用的軸組。

0path

清除目前軸組的路經資訊。

命令範例:

1 group!  \ 切換到第 1 個軸組
0ptah     \ 清除目前軸組的路經資訊

acs-p@ ( n -- ) ( F: -- pos )

取得目前軸組，ACS 座標系第 n 軸的座標位置。

命令範例:

1 acs-p@ f. \ 取得第 1 軸得座標位置，然後輸出位置資訊

回傳訊息:

0.0000000

feedrate! ( F: v -- )

設定後續安插路徑的最大運動速度 v。v 必須大於 0。

命令範例:

100.0e mm/min feedrate!  \ 設定當下 group feedrate 為 100.0 mm/min

feedrate@ ( F: -- v )

取得後續安插路徑的最大運動速度 v。

命令範例:

feedrate@ f. \ 取得 group feedrate，並輸出訊息

回傳訊息:

0.1000000

gamax! ( g -- ) ( F: a -- )

設定 group g 的最大加速度為 a。

命令範例：

2.0e 1 gamax! \ 設定 Group 1 的最大加速度為 2.0

gend? ( -- flag )

所選定的軸組是否到達路徑終點？

gignore-dist! ( g -- ) ( F: dist --)

設定指定軸組 g 可忽略的長度計算誤差 dist。

通常在 pulse 的系統下，設定為 0.5 或是 0.1 [pulse]。其它設定為 0.5e-6 或是 0.1e-6 [m] or [rad]

gjmax! ( g -- ) ( F: j -- )

設定 group g 的最大加加速度為 j。

命令範例：

40.0e 1 gjmax! \ 設定 Group 1 的最大加加速度為 40.0

gmap! ( j1 j2 j3 ... g -- )

設定軸組 g 所控制的運動軸 j1 j2 j3 ...。需要注意軸組型態與運動軸數量。

注意事項：

1. 軸組 g 不可以處在啟動狀態。
2. 運動軸 j 不可受控於其他啟動中的軸組或是在點對點運動模式。
3. 軸組型態與運動軸數量要匹配正確。

命令範例：

              \ 假設軸組 1 是 3D 軸組
2 3 4 1 gmap! \ 設定 Group 1 對應的運動軸編號分別是 2, 3, 4
2 1 gmap!     \ 設定 Group 1 對應的運動軸編號分別是 2，則是會回報錯誤 （Stack underflow）

gmap@ ( g -- j1 j2 j3 ... )

取得軸組所控制的運動軸，需要注意軸組型態與運動軸數量。

group! ( g -- )

設定目前選用的軸組 g, g 編號從 1 開始。

group@ ( -- g )

取得目前所選定的軸組 g命令範例:

group@                  \ 取出目前軸組編號
1 group! 0.1e feedrate! \ 選用軸組 1，設定 feedrate
group!                  \ 切換回原來的軸組

group? ( -- t )

目前所選定的軸組是否啟動 ?

grp1d? ( g -- flag )

指定軸組 g 是否為 1D 軸組 ?

grp2d? ( g -- flag )

指定軸組 g 是否為 2D 軸組 ?

grp3d? ( g -- flag )

指定軸組 g 是否為 3D 軸組 ?

grp-sine? ( g -- flag )

指定軸組 g 是否為 Sine Wave 軸組 ?

gstart ( -- )

命令所選定的軸組開始運動。

命令範例:

1 group! gstart  \ 切換到軸組 1, 命令軸組 1 開始運動。

gstop ( -- )

命令所選定的軸組停止運動。

命令範例:

1 group! gstop  \ 切換到軸組 1, 命令軸組 1 停止運動。

gstop? ( -- flag )

所選定的軸組是否已經停止運動 ？

gvmax! ( g -- ) ( F: v -- )

設定 group g 的最大速度為 v。

命令範例：

1000.0e mm/min 2 gvmax! \ 設定 Group 1 的最高速度為 1000.0 mm/min

map-len@ ( g -- len )

取得軸組 g 的運動軸數量 len。

map-sine ( j1 g -- )

設定軸組 g 的對應運動軸為 j1。

注意事項：

1. 軸組 g 必須為 Sine Wave 軸組。
2. 軸組 g 不可以處在啟動狀態。
3. 運動軸 j1 不可受控於其他啟動中的軸組或是在點對點運動模式。

命令範例：

3 1 map-sine  \ 設定 Group 1 的運動軸為 Axis 3

map1d ( j1 g -- )

設定軸組 g 的對應運動軸為 j1。

注意事項：

1. 軸組 g 必須為 1D 軸組。
2. 軸組 g 不可以處在啟動狀態。
3. 運動軸 j1 不可受控於其他啟動中的軸組或是在點對點運動模式。

命令範例：

3 1 map1d  \ 設定 Group 1 的運動軸為 Axis 3

map2d ( j1 j2 g -- )

設定軸組 g 的對應運動軸為 j1, j2。

注意事項：

1. 軸組 g 必須為 2D 軸組。
2. 軸組 g 不可以處在啟動狀態。
3. 運動軸 j1 j2 不可受控於其他啟動中的軸組或是在點對點運動模式。

命令範例：

3 5 2 map2d \ 設定 Group 2 的運動軸為 Axis 3, 5

map3d ( j1 j2 j3 g -- )

設定軸組 g 的對應運動軸為 j1, j2, j3。

注意事項：

1. 軸組 g 必須為 3D 軸組。
2. 軸組 g 不可以處在啟動狀態。
3. 運動軸 j1 j2 j3 不可受控於其他啟動中的軸組或是在點對點運動模式。

命令範例：

3 5 6 2 map3d 設定 Group 2 的運動軸為 Axis 3, 5, 6

mcs ( -- )

宣告所選定軸組以目前 MCS 座標位置為路徑起始點（將 PCS 與 MCS 座標系重疊）。

mcs-p@ ( n -- ) ( F: -- pos )

取得所選定軸組 MCS 座標系中指定軸 n 的座標位置 pos。

命令範例：

1 mcs-p@  \ 取得第 1 軸的 MCS 座標系位置。

move-source# ( -- n )

取得所選定軸組目前是處在哪個路徑事件 n。

next-a@ ( F: -- a )

取得所選定軸組路徑切線方向加速度 a。

next-path-id@ ( -- id )

取得所選定軸組，目前路徑的編號 id。

next-path-mode@ ( -- mode )

取得所選定軸組，目前路徑的模式 mode。

next-path-p@ ( -- ) ( F: -- pos )

取得所選定軸組，從運動起始點算起，沿路路徑方向的位置 pos。

next-v@ ( F: -- v )

取得所選定軸組路徑切線方向速度 v。

path-events-capacity@ ( -- n )

取得所選定軸組可容納的路徑數量 n。

path-events-len@ ( -- n )

取得所選定軸組目前的路徑數量 n。

path-id! ( id -- )

設定後續安插路徑的編號 id。

應用範例：

1. 儲存對應 NC 程式的行號，當執行軸組運動時可以得知目前位置是由哪一行 NC 程式解譯而來。

path-id@ ( -- id )

取得後續安插路徑的編號 id。

path-mode! ( mode -- )

設定後續安插路徑的模式 mode。

path-mode@ ( -- mode )

取得後續安插路徑的模式 mode。

應用範例：

1. 用來區分該路徑是加工或是非加工路徑。

pcs-p@ ( n -- ) ( F: -- pos )

取得所選定軸組 PCS 座標系的指定軸 n 的座標位置 pos。

vcmd! ( F: v -- )

設定路徑上運行的速度 v。

• 當 v > 0 時，會沿著路徑前進，直到路徑終點。
• 當 v = 0 時，速度會減速到 0。
• 當 v < 0 時，會沿著路徑後退，直到路徑起始點。

運動速度限制如下：

1. vcmd! 所指定的速度。
2. 該軸組所限制的最大運動速度 (gvmax!)。
3. 當下路徑的進給速度 （feedrate!）。
4. 預視路徑總長與當下位置。

命令範例:

100.0e mm/min vcmd! \ 設定運動速度為 100.0 mm/min

本節指令集

1D 路徑規劃

注意事項：

1. 目前選用的軸組必須為 1D 型態。
2. 路徑的起始點為前一個路徑的目標點。
3. 必須要宣告路徑起始點（ move1d, mcs, psc1d）

line1d ( F: x -- )

增加目標點為 (x) 的直線路徑。

move1d ( F: x -- )

宣告目前位置為 PCS 座標 (x)，並且為路徑起始點。類似工件程式 GM 碼的 G92。

pcs1d ( F: x0 -- )

宣告 PCS 座標零點(x0)，並以當下位置做為路徑起始點。類似工件程式 GM 碼的 G54。

範例 test-1d

假設 Group 1 為 1D group, 以 100.0 mm.min 速度運動通過相對起點為 -0.5, 1.0，終點為 0.0 的座標位置。

: test-1d                      \ 定義 test-1d 指令
    +coordinator               \ 啟動軸運動控制模式
    start-job                  \ 啟動加減速機制
    1 group! +group            \ 切換選用軸組，啟動 Group 1
    0path                      \ 清除 Group 1 路徑
    0.0e move1d                \ 宣告目前位置為起始運動位置，座標為 0.0
    -0.5e line1d               \ 插入目標點為 -0.5 的 1D 直線路徑
    1.0e line1d                \ 插入目標點為 1.0 的 1D 直線路徑
    0.0e line1d                \ 插入目標點為 0.0 的 1D 直線路徑
    100.0e mm/min vcmd!        \ 設定運動速度為 100.0 mm/min
    begin                      \ 等待到達終點位置
        1 group! gend? not     \ 檢查是否到終點, 此處 1 group! 避免在等待過程中被其他指令修改了
    while
        pause                  \ 若是未到終點就等待下一個周期再進行檢查
    repeat 
    1 group! -group            \ 關閉 Group 1
;

deploy test-1d ;deploy         \ 在背景執行 test-1d

本節指令集

2D 路徑規劃

注意事項：

1. 目前選用的軸組必須為 2D 型態。
2. 路徑的起始點為前一個路徑的目標點。
3. 必須要宣告路徑起始點（ move2d, mcs, psc2d）

arc2d ( n -- )( F: cx cy x y -- )

增加 2D 圓弧路徑，其圓心為 (cx,cy)，目標位置是 (x, y)。 n 表示從起始點運動第 n 圈到達目標點。

• n > 0 表示逆時針運動，
• n < 0 表示順時針運動，
• n 不可以為 0。

line2d ( F: x y -- )

增加目標點為 (x,y) 的直線路徑。

move2d ( F: x y -- )

宣告目前位置為 PCS 座標 (x, y)，並且為路徑起始點。類似工件程式 GM 碼的 G92。

pcs2d ( F: x0 y0 -- )

宣告 PCS 座標零點(x0, y0)，並以當下位置做為路徑起始點。類似工件程式 GM 碼的 G54。

範例 test-2d

假設 Group 1 為 2D group

: test-2d                          \ 定義 test-2d 指令
    +coordinator                   \ 啟動軸運動控制模式
    start-job                      \ 啟動加減速機制
    1 group! +group                \ 啟動 Group 1
    0path                          \ 清除路徑
    0.0e  0.0e  move2d             \ 宣告目前位置為起始運動位置，座標為 (0.0, 0.0)
    0.1e  0.0e  line2d             \ 插入目標點為 (0.1, 0.0) 的 2D 直線路徑
    0.1e  0.1e  line2d             \ 插入目標點為 (0.1, 0.1) 的 2D 直線路徑
    0.0e  0.1e  line2d             \ 插入目標點為 (0.0, 0.1) 的 2D 直線路徑
    0.0e  0.05e 0.0e 0.0e 1 arc2d  \ 以圓心位置 （0.0, 0.05）逆時針走到目標點 （0.0, 0.0）
    100.0e mm/min vcmd!            \ 設定運動速度為 100.0 mm/min
    begin                          \ 等待到達終點位置
        1 group! gend? not         \ 檢查是否到終點, 此處 1 group! 避免在等待過程中被其他指令修改了
    while
        pause                      \ 若是未到終點就等待下一個周期再進行檢查
    repeat
    1 group! -group                \ 關閉 Group 1
;

deploy test-2d ;deploy         \ 在背景執行 test-2d

本節指令集

3D 路徑規劃

注意事項：

1. 目前選用的軸組必須為 3D 型態。
2. 路徑的起始點為前一個路徑的目標點。
3. 必須要宣告路徑起始點（ move3d, mcs, psc3d）。

helix3d ( n -- )( F: cx cy x y z -- )

增加 3D 螺旋路徑，其圓心為 (cx,cy)，目標位置是 (x, y, z)。 n 表示從起啟點運動第 n 圈到達目標點。

• n > 0 表示逆時針運動，
• n < 0 表示順時針運動，
• n 不可以為 0。

如果 z 與起始點相同，此螺旋路徑即為 XY 平面上的圓弧路徑。

line3d ( F: x y z-- )

增加目標點為 (x,y, z) 的直線路徑。

move3d ( F: x y z -- )

宣告目前位置為 PCS 座標 (x, y, z)，並且為路徑起始點。類似工件程式 GM 碼的 G92。

pcs3d ( F: x0 y0 z0 -- )

宣告 PCS 座標零點(x0, y0, z0)，並以當下位置做為路徑起始點。類似工件程式 GM 碼的 G54。

範例 test-3d

假設 Group 1 為 3D group

: test-3d                          \ 定義 test-3d 指令
    +coordinator                   \ 啟動軸運動控制模式
    start-job                      \ 啟動加減速機制
    1 group! +group                \ 啟動 Group 1
    0path                          \ 清除 Group 1 路徑
    0.0e  0.0e  0.0e   move3d      \ 宣告目前位置為起始運動位置，座標為 (0.0, 0.0, 0.0)
    0.0e  0.1e  0.0e  line3d       \ 插入目標點為 (0.0, 0.1, 0.0) 的 3D 直線路徑
    -0.1e  0.1e -0.2e 0.1e 0.1e  1 helix3d
                                   \ 以圓心位置 （-0.1, 0.1）逆時針走到目標點 （-0.2, 0.1, 0.1 ）的螺旋路徑
    100.0e mm/min vcmd!            \ 設定運動速度為 100.0 mm/min
    begin                          \ 等待到達終點位置
        1 group! gend? not         \ 檢查是否到終點, 此處 1 group! 避免在等待過程中被其他指令修改
    while
        pause                      \ 若是未到終點就等待下一個周期再進行檢查
    repeat
    1 group! -group                \ 關閉 Group 1
;

deploy test-3d ;deploy         \ 在背景執行 test-3d

本節指令集

Sine Wave Planner

注意事項：

1. 目前選用的軸組必須為 Sine Wave 型態。
2. 必須要宣告路徑起始點（ move3d, mcs, psc3d），此起始點就是相位 0 的位置。

move-sine ( F: x -- )

宣告目前位置為 PCS 座標 (x)，並且為路徑起始點。

sine-amp! (F: amp -- )

設定弦波振幅。可以運動中修改，經過起始點後才開始改變振幅。

sine-f! ( F: f -- )

設定弦波頻率。可以運動中修改，在相位 270 deg 的地方改變頻率。

pcs-sine ( F: x0 -- )

宣告 PCS 座標零點(x0） ，並以當下位置做為路徑起始點。

範例 test-sine

假設 Group 1 為 SINE Wave Group

+coordinator          \ 啟動軸運動控制模式
start-job             \ 啟動加減速機制
1 group! +group       \ 啟動 Group 1
0path                 \ 清除 Group 1 路徑
0.0e   move-sine      \ 宣告目前位置為起始運動位置，座標為 (0.0)
1.0e   sine-f!        \ 設定sine wave 頻率為 1.0 Hz
0.01e  sine-amp!      \ 設定sine wave 振幅為 0.01
...
stop-job              \ 停止加減速機制

本節指令集

Axis

名詞說明：

• command_position: 運動軸的目標位置。

• demand_position: 運動過程中的命令位置。如果受到軸組控制時， demand_position 會與 command_position 相等。如果是運動軸的點對點運動，在過程中 demand_position 會朝著目標位置運動，只有在到達目標點時 demand_position 會與 command_position 相等。

• feedback_position: 由馬達編碼器或是雙位置回授所得到的實際位置。

• position_correction: 位置修正量。可以是 Pitch Corrector 所算出來的補正量，或是其他策略所推算出來的補正值。

• corrected_position: 修正後的實際位置。

  corrected_position = feedback_position - position_correction + home_offset

• following_error: 落後誤差。

  following_error = demand_position - corrected_position

.axis ( j -- )

顯示運動軸 j 狀態。

命令範例:

1 .axis

回傳訊息 :

axis_command_position.1|0.0000000
|axis_demand_position.1|0.0000000
|axis_corrected_position.1|0.0000000
|encoder_position.1|0.0000000
|external_encoder_position.1|0.0000000
|feedback_position.1|0.0000000
|position_correction.1|0.0000000
|following_error.1|0.0000000
|axis_interpolator_enabled.1|0
|axis_homed.1|0

.axiscfg ( j -- )

顯示運動軸 j 設定

命令範例：

1 .axiscfg

回傳訊息：

axis_name.1|A2
|axis_home_offset.1|0.0000000
|encoder_length_unit.1|Meter
|encoder_ppu.1|1000000.00000
|encoder_direction.1|1
|ext_encoder_ppu.1|60000.00000
|ext_encoder_direction.1|-1
|closed_loop_filter.1|15.0
|max_position_deviation.1|0.001000
|drive_alias.1|0
|drive_slave_position.1|1
|drive_channel.1|1
|ext_encoder_alias.1|0
|ext_encoder_slave_position.1|0
|ext_encoder_channel.1|0
|axis_amax.1|5.00000
|axis_vmax.1|0.10000
|axis_ignorable_distance.1|0.0000005

+homed ( j -- )

設定運動軸 j 已回歸機械原點。

-homed ( j -- )

設定運動軸 j 未回歸機械原點。

0axis-ferr ( j -- )

清除運動軸 j 落後誤差。使用運動軸實際位置修正命令位置，如果是虛擬軸則不受影響。

axis-amax! ( j -- ) ( F: amax -- )

設定運動軸 j 的最大加速度 amax。

命令範例：

2.0e 1 axis-amax!  \ 設定 Axis 1 amax 為 2.0

axis-amax@ ( j -- ) ( F: -- amax )

取得運動軸 j 的最大加速度 amax。

命令範例：

1 axis-amax@  \ 取得 Axis 1 amax

axis-clerr ( j -- ) ( F: clerr -- )

取得運動軸 j 雙位置回授誤差 clerr。

通常外部編碼器安裝在靠近軌道或是工作台的位置，如果和馬達編碼器的位置相差過大代表機械傳動系的運作出現問題，此時可以優先檢查皮帶輪或是聯軸器。

axis-cmd-p! ( j -- )( F: pos -- )

設定運動軸 j 的目標位置 pos。

axis-cmd-p@ ( j -- )( F: -- pos )

取得運動軸 j 的目標位置 pos。

axis-demand-p@ ( j -- )( F: -- pos )

取得運動軸 j 的命令位置 pos。

axis-drive@ ( j -- channel slave )

取得運動軸 j 配置的馬達驅動器的 EtherCAT 站號 slave 與驅動軸編號 channel。

slave 指的是 slave position，最靠近主站的從站編號為 1，依序遞增。

如果是以 slave alias 指定馬達驅動器的方式，則是主站在初始化或是設定時就依指定 slave alias 取得 slave position。

當是虛擬軸時，axis-drive@ 回傳的 channel = 0, slave = 0。

axis-ext-enc@ ( j -- channel slave )

取得運動軸 j 配置的外部編碼器的 EtherCAT 站號 slave 與輸入編號 channel。

當沒有配置外部編碼器時會使得 axis-ext-enc@ 回傳 channel = 0, slave = 0。

axis-ferr@ ( j -- ) ( F: ferr -- )

取得運動軸 j 取得落後誤差 ferr。

axis-ignore-dist! ( j -- ) ( F: dist -- )

設定指定運動軸 j 可忽略的長度計算誤差 dist。

通常在 pulse 的系統下，設定為 0.5 或是 0.1 [pulse]。其它設定為 0.5e-6 或是 0.1e-6 [m] or [rad]

axis-len ( -- len )

取得 Botnana Control 所規劃的運動軸總數 len。

axis-real-p@ ( j -- )(F: -- pos )

取得運動軸 j的實際位置 pos 。

axis-rest? ( j -- flag )

運動軸 j 命令是否靜止？

可以利用此狀態作為不同落後誤差或是雙位置回授誤差的監控條件切換。

axis-ts! ( j -- ) ( F: ts -- )

設定用來判定運動軸 j 命令是否靜止的安定時間 ts sec。

axis-vmax! ( j -- ) ( F: vmax -- )

設定運動軸 j 的最大速度 vmax。

命令範例：

0.5e 1 axis-vmax!  \ 設定 Axis 1 vmax 為 0.5

axis-vmax@ ( j -- ) ( F: -- vmax )

取得運動軸 j 的最大速度 vmax。

axis>pulse ( j -- pulse ) ( F: pos -- )

轉換運動軸 j 的命令位置 pos 為編碼器脈波位置 pulse。

cl-cutoff! ( j -- ) ( F: freq -- )

設定運動軸 j 雙位置回授誤差濾波器的截止頻率 freq。

此截止頻率影響雙位置回授誤差的計算，如果調高，運動響應會比較貼近外部編碼器的回授位置，但是系統會比較不穩定。

drv-alias! ( drive-alias j -- )

使用 EtherCAT Station Alias drive-alias 指定運動軸 j 馬達驅動器。

當 drive-alias = 0 表示使用 slave position 指定馬達驅動器。 當 drive-alias 不存在時，此運動軸就會以虛擬軸處理。

drv-channel! ( drive-channel j -- )

使用 drive-channel 指定運動軸 j 馬達驅動器的控制軸。

因應單一 EtherCAT 從站多軸驅動器的模組型態，所以必須要使用此一參數。一般驅動器則是固定設定為 1。

命令範例：

1 3 drv-channel! \ 設定 Axis 3 對應的馬達驅動器的控制軸為 1

drv-slave! ( drive-slave j -- )

使用 EtherCAT Slave Position drive-slave 指定運動軸 j 馬達驅動器站號。

命令範例：

2 1 drv-slave!  \ 設定 Axis 1 對應的馬達驅動器站號為 2

enc-dir! ( dir j -- )

設定運動軸 j 馬達運動/編碼器方向 dir。

當機器的軸向與馬達的運轉方向定義相反時可以藉由此參數來轉換。

dir 可以設定的值為：

• 1: 同方向
• -1: 反方向

命令範例：

1 3 enc-dir!  \ 設定 Axis 3 編碼器方向

enc-ppu! ( j --) ( F: ppu -- )

設定運動軸 j 距離單位對應馬達編碼器的脈波數 ppu

命令範例可以參考 enc-u!

enc-u! ( u j -- )

設定運動軸 j 馬達編碼器的脈波數對應的距離單位 u。

可以設定的單位有：

• u = 0 as Meter,
• u = 1 as Revolution
• u = 2 as Pulse

命令範例：

1000000.0e 3 enc-ppu! \ 設定 Axis 3 的編碼器單位距離的脈波數為 1000000.0
0 3 enc-u!            \ 設定 Axis 3 的編碼器單位距離為 1 m
                      \ 表示 1 m 有 1000000 個 pulse (編碼器脈波數), 1 pulse 為 1 um

ext-enc-alias! ( enc-alias j -- )

使用 EtherCAT Station Alias 指定外部編碼器。參考 drive-alias!。

ext-enc-channel! ( enc-channel j -- )

指定外部編碼器的量測管道。參考 drive-channel!。

ext-enc-dir! ( dir j -- )

指定外部編碼器的方向。參考 enc-dir!。

ext-enc-ofs! ( j -- )( F: ofs -- )

指定運動軸 j 外部編碼器的位置偏移量 ofs。

如果外部編碼器是絕對式型態，可以使用此命令調整外部編碼器由脈波數換算到物理位置的區間。

以海德漢長度 80 mm 絕對式光學尺為例，可以使用的區間範圍是 20 ~ 100 mm。 如果安裝方向與運動方向相反就會變成 -100 mm ~ -20 mm。 為了將換算出來的調整為 20 ~ 100 mm，就可以使用此命令來進行調整。

ext-enc-ppu! ( j -- )( F: ppu -- )

設定運動單位距離對應外部編碼器的脈波數。參考 enc-ppu!。單位距離則是依 enc-u!設定。

ext-enc-slave! ( enc-slave j -- )

使用 EtherCAT Slave Position 指定外部編碼器。參考 drive-slave!。

hmofs! ( j -- ) ( F: ofs -- )

設定運動軸 j 機械零點的座標偏移量。

命令範例：

0.5e 3 hmofs! \ 設定 Axis 3 home offset

homed? ( j -- flag )

取得運動軸 j 是否回歸機械原點的狀態?

max-pos-dev! ( j -- ) ( F: max-dev -- )

設定運動軸 j 雙位置回授的最大命令修正量 max-dev。避免當傳動系出現問題或是參數配置錯誤時，修正量無法收斂到固定值的狀況發生。

virtual-axis? ( j -- flag )

運動軸 j 是否為虛擬軸？

運動軸追隨範例

以 Axis 2 追隨 Axis 1 的命令位置運動

...
begin
    ... \某個條件成立執行
while
    ........
    2 axis-demand-p@ 1 axis-cmd-p!
    pause
repeat
...

本節指令集

單軸運動

命令針對單一運動軸，可以同時讓多個運動軸同時運行。如果該運動軸受到軸組控制則不可執行單軸運動。

+interpolator ( j -- )

啟動 Axis j 單軸運動。

-interpolator ( j -- )

關閉 Axis j 單軸運動。如果單軸運動中，會以當下的速度開始減速到 0。

interpolator-v! ( j -- )（ F: v -- ）

設定 Axis j 單軸運動的最大速度。

單軸運動範例

以 Axis 1 為例：

+coordinator                       \ 啟動軸組功能
1  +interpolator                   \ 啟動 Axis 1 單軸運動
100.0e  mm/min  1  interpolator-v! \ 設定 Axis 1 單軸運動速度為 100.0 mm/min
0.3e  1  axis-cmd-p!               \ 設定 Axis 1 的目標位置為座標位置 0.3 m 
1 axis-demand-p@                   \ 取得 Axis 1 目前的命令位置
1 axis-real-p@                     \ 取得 Axis 1 目前的實際位置

本節指令集

Pitch Corrector

+pcorr ( channel slave -- )

開啟指定驅動器的 Pitch Corrector

-pcorr ( channel slave -- )

關閉指定驅動器的 Pitch Corrector

>pcorr ( channel slave -- )

讀取指定驅動器的 Pitch Corrector，此命令會造成 real time cycle overrun, 要在安全的情況下使用，例如 Servo off 的情況下。

.pcorr ( channel slave -- )

輸出目前 Pitch Corrector 的查表結果

命令範例:

1 1 .pcorr

回傳訊息 :

pcorr_name.1.1|P0001-01.sdx
|pcorr_len.1.1|10
|pcorr_position.1.1|0.0000000
|pcorr_forward.1.1|0.0000000
|pcorr_backward.1.1|0.0000000
|pcorr_corrected_position.1.1|0.0000000
|pcorr_backlash.1.1|0.0000000
|pcorr_direction.1.1|1
|pcorr_factor.1.1|0.0020000
|pcorr_enabled.1.1|0

本節指令集

已知可支援的硬體清單

WiFi Adapters

• D-Link DWA-171
• D-Link DWA-172

EtherCAT Slave 清單

目前 Botnana Control 支援以下 EtherCAT Slaves：

CiA DSP 401 Compatible

• Digital Input Module
• Digital Output Module
• Analogue Input Module
• Analogue Output Module

CiA DSP 402 Compatible

• Servo drive
• Stepper motor
• Multiple drive module

(研華) Advantech

• AMAX_4830, DIO

Beckhoff

• EK1100, EtherCAT Bus Coupler
• EL1088, 8-channel digital input terminal 24 V DC, negative switching
• EL1809, 16-channel digital input 24 V DC
• EL2088, 8-channel digital output terminal 24 V DC, negative switching
• EL2502, 2-channel pulse width output terminal
• EL2088, 8-channel digital output terminal
• EL2809, 16-channel digital output 24 V DC
• EL3058, 8-channel analog input terminal 4…20 mA, single-ended, 12 bit
• EL3062, analog input
• EL4002, analog output
• EL5032, 2-channel EnDat 2.2 interface
• EL6021, Serial terminal
• EL6022, Serial terminal

Copley Controls

• Xenus XEL-230-36, EtherCAT Servo Drive

台達電 (Delta)

• ASDA-A2-E, EtherCAT(CoE) Drive
• R1-EC5500, EtherCAT to E-BUS power module
• R1-EC6022, 16 digital inputs, sink/source type
• R1-EC7062, 16 digital outputs, sink type
• R1-EC9144, 4 channels 16-bit D/A control module
• R1-EC8124, 4 channels 16-bit single-ended A/D control module
• R1-EC5621, Single-axis pulse output motion control module

ELMO

• GOLD_BASSOON Servo Drive

FASTECH

• Ezi-SERVOⅡ EtherCAT Series

ICPDAS

• ECAT-2512, EtherCAT junction

MITSUBISHI

• MR-J4-10TM Servo Drive

OMRON

• GX-MD1611 REMOTE TERMINAL (8 Ch. Digital Input， 8 Ch. Digital Output)
• NX-ECC203, ID5342, OD5121 (IO 模組，測試中)

Oriental Motor

• AZ Series DC power input Multi-Axis Driver

Panasonic

• EtherCAT communication driver MINAS A5B Series
• MCDLT35BF (A6B)

SANYO DENKI

• SANMOTION R ADVANCED MODEL

士林電機 （Shihlin）

• SDP, EtherCAT Servo Driver

TPM

• TPM_207_D240_NX, 32 Ch. Digital Input
• TPM_207_D204_XN, 32 Ch. Digital Output
• TPM_207_A220FD, 8 Ch. Analog Input, 8 Ch. Digital Output
• TPM_207_A204F，8 Ch. Anaglo Output

Yaskawa

• SGDV-2R8AE1A
• SGD7S-7R6AA0A (測試中)

版本說明

1.14.4 版

1.14.4 版新增控制器復原與 EtherCAT 拓撲維護流程，強化設定及軟體更新處理， 並限制 HMI 的 WebSocket 流量。

EtherCAT 控制器生命週期與復原

• 控制器處於就緒狀態時，可以重新掃描 EtherCAT 硬體，不必重新啟動 bnc-motion 服務。現有的 WebSocket 工作階段會重新繫結到替換後的執行世代。
• 控制器啟動時會核對已連接的 EtherCAT 拓撲與預期設定檔，並顯示目前階段與 重試倒數。
• 如果啟動程序仍在等待預期拓撲，操作人員可以停止等待。這會結束本次嘗試， 不會還原先前的控制器世代。
• 控制器無法使用時，可以在 HMI 檢查已儲存的機台設定檔，視需要修正，並以 該確切儲存版本啟動替換控制器。
• HMI 重新連線後，會還原復原來源、階段、結果及操作可用狀態。
• 如果無法確認舊控制器已安全清除，Botnana Control 會阻止在同一程序內再次 啟動。此時必須由授權管理員重新啟動 bnc-motion 服務後才能重試。

EtherCAT 拓撲維護

• 新的拓撲維護流程支援有計畫地新增、移除、替換或調整從站順序。
• HMI 會分開呈現已設定從站、偵測到的從站、建議拓撲、已儲存設定檔及 執行中的控制器。
• 掃描是唯讀操作，不會自動採用已連接的硬體。操作人員必須明確選用完整的 偵測拓撲、檢查其影響、在未啟用狀態下儲存，最後套用該確切儲存版本。
• 因從站移除、替換、移動或身分不明確而受影響的裝置設定及映射，必須先完成 檢查才能儲存。
• 維護狀態由控制器管理；重新載入瀏覽器或改用另一個 HMI 工作階段後仍可還原。

機台設定檔編輯與 HMI

• HMI 現在透過共用的主要導覽列，提供獨立的 Controller & Topology、 Slave Configuration、Motion 及 Axis Group 工作區。
• 除了拓撲維護正在占用設定檔時以外，即使控制器無法使用、正在重新啟動或 啟動中，仍可編輯設定檔。
• 草稿與已儲存設定檔的修訂版號，可防止另一個瀏覽器工作階段以過期內容進行 編輯、儲存、捨棄或啟動控制器。
• 設定檔變更會先驗證並以不可分割方式套用。儲存失敗時會保留未儲存草稿， 以便修正或重試。
• Motion 及 Axis Group 會分開顯示作用中控制器使用的值與已儲存或草稿 設定。儲存只會準備供之後的控制器啟動使用，不會套用至運作中的控制器。
• 一般 Slave Configuration 編輯中的 EtherCAT 供應商 ID 及產品代碼維持 唯讀；預期身分若有變更，應使用引導式拓撲程序。
• 伺服器 IP 位址變更會先驗證、以不可分割方式儲存，並由 HMI 回報結果；新 位址會在重新開機後生效。
• 試算表版面、設定檔狀態、操作可用性及復原控制已重新設計，在較小顯示器上 也能更清楚操作。

軟體更新與 HMI 執行環境

• 舊有的 Node.js HMI 伺服器已由具有限制機制的 Rust HTTP 伺服器取代。
• Debian 套件在暫存前會先檢查。About 頁面會顯示確切的套件身分、版本、 架構、分類及 SHA-256，供操作人員確認。
• 經確認的 Botnana Control 套件會安排在下一次開機時嘗試安裝一次。安裝開始 前，可以取消待安裝套件。
• 重新開機後，About 頁面會顯示具權威性的安裝結果。
• 安裝失敗、逾時、中斷或安裝結果未完整記錄時，系統可以阻止運動功能，直到 經確認的復原套件成功安裝為止。
• 如果系統保留了上一個成功版本的確切套件，可以先檢查該套件，再安排有計畫 的版本回復。
• Botnana Control 會區分由自身管理的套件與應由外部更新程式管理的套件。

有界限的 WebSocket 流量

• 內建 HMI 的啟動、心跳、可見數值輪詢及操作請求共用同一個傳送額度。最多 可累積五個立即請求額度，並以每秒 100 個請求的速率補充。

• 隱藏的工作區不再持續進行高頻率即時輪詢。已過時的輪詢會被較新的輪詢取代， 不會累積成延遲後的追趕突發流量。

• 操作人員及運動命令具有較高優先權，但仍受同一請求額度限制。

• 運動伺服器會另外針對每一條連線執行准入控制。系統可以合併已辨識的最新值 輪詢，但不會默默捨棄或重複執行變更狀態及未知用途的工作。

• 請求未獲准時，在一秒的過載期間內，伺服器最多回報一次以下過載訊息：

  error|WebSocket request limit exceeded. Non-admitted requests during the next 1 second have no effect; retry later.
  

• 系統不會只因請求速率過高而關閉連線。一條過載連線不會消耗另一條連線的 准入額度。

• 內建 HMI 從 About 開啟的 Support diagnostics 畫面，會比較兩個作用中 WebSocket 用戶端各自的 Poll requests 及 Ordered requests 速率、准入總數、 從收到訊框到准入的 第 95 百分位等待時間、各類別結果及輸出狀態。連線關閉後會移除該用戶端，不會 保留其計數器。准入等待時間不是回應時間或命令完成時間。

• Download diagnostic log 會傳回由操作人員啟動的 ZIP，其中包含摘要、經允許的 執行環境中繼資料，以及 bnc-motion 與 bnc-hmi 目前／前一次開機的分類記錄。 ZIP 上限為 50 MiB，會回報遺漏及截短，不會保留，也不會自動上傳。此限制是檔案 大小上限，不保證固定的記錄時數。

• 在桌面瀏覽器的內容高度捲動後，診斷下載操作仍會完整顯示在對話框操作按鈕上方。

• WebSocket 輸出不再阻塞事件迴圈；連線關閉時會釋放通訊端、輸出工作程序及 配發的 rtForth 使用者工作。

相容性注意事項

• 內建 HMI 與運動伺服器必須一起升級。內建 HMI 的設定修改使用設定通訊協定 第 2 版，並會拒絕過期的草稿修訂版號。
• 1.14.4-21 與更新版本也接受已發行客戶函式庫送出的既有設定 setter，以及不帶 參數的 config.save。這些舊版請求無法偵測同時發生的草稿修改，因此同一時間 只能使用一個設定編輯器。
• 系統仍使用既有的 JSON-RPC-over-WebSocket 方法及以管線符號分隔的 rtForth 回應格式；但超出 1.14.4 准入界限的用戶端，現在可能收到上述明確過載結果。
• Botnana Control 仍提供兩個 rtForth 使用者工作供 WebSocket 用戶端使用。
• Support diagnostics 的流量比較及診斷下載是內建 HMI 的內部功能，不是支援的 客戶 JSON API 新增項目。
• 接受 script.evaluate 請求後，仍沒有通用的成功或完成確認。WebSocket 傳送 成功或沒有收到錯誤，不能證明變更狀態的程式已經執行。
• 自行開發的 HMI 應將軸組選擇、依賴該選擇的命令及讀回動作放在同一個 script.evaluate 請求中。發生過載、逾時或斷線後，必須先核對控制器狀態， 再決定是否能安全重試。

內建流量比較請參閱 Botnana Control 入門。 自行開發 HMI 的流量與命令驗證建議，請參閱 JSON API；套件更新程序 請參閱軟體更新。

1.14.3 版

從 1.14.1 版以來的變更

• WebSocket 看門狗逾時時間由 4 秒延長為 10 秒，提高系統對短暫通訊延遲的 容忍度。
• 文件新增保守的自行開發 HMI 連線、輪詢及命令驗證建議；該版本的伺服器尚未 強制執行每條連線的有界限准入控制。

軟體更新

請依控制器目前顯示的 ABOUT 頁面選擇程序。Botnana Control 1.14.3 與更早版本使用舊版上傳頁面；1.14.4 與更新版本則使用經審查的 Debian 套件更新區域。

更新前準備

• 請向動程公司或其他可信任來源取得套件。不要安裝來源不明、未經確認的套件。
• 只可從可信任的控制網路執行更新。
• 依現場安全程序讓機台進入安全停止狀態。軟體更新與重新開機不是安全功能。
• 安裝套件期間請保持電源供應。
• 記錄目前的軟體版本及控制器 IP 位址。

BN-B3A 的套件檔名格式如下：

botnana-control_<Debian-version>_arm64.deb

由舊版轉換至 1.14.4 時，請使用已修正的套件：

botnana-control_1.14.4-2_arm64.deb

Debian 套件版本是 1.14.4-2；Botnana Control 畫面顯示的產品版本是 1.14.4。

從 1.14.3 或更早版本升級

這是從舊版更新程式轉換至 1.14.4 新套件更新程式的一次性程序。

1. 準備一部已設定好 Botnana Control 網路連線的電腦，建議使用 Google Chrome。

2. 開啟控制器 HMI；一般網址為 http://192.168.7.2:3000，然後選擇 ABOUT。

3. 確認舊版 ABOUT 頁面顯示 1.14.3 或更早版本，且有 UPLOAD MANUALLY 按鈕。

   

4. 選擇 UPLOAD MANUALLY，再選取 botnana-control_1.14.4-2_arm64.deb。等待上傳完成；上傳期間不要關閉頁面或切斷電源。

5. 出現 Upload successful, please reboot Botnana Control 後，選擇 REBOOT。

   

6. BN-B3A 重新開機及安裝套件約需三分鐘。在此期間不要切斷電源。

7. 重新連線 HMI，開啟 ABOUT，確認畫面顯示 Version 1.14.4。

   

8. 重新載入瀏覽器頁面後，才讓機台恢復運轉。

完成這次舊版升級後，畫面可能顯示 No managed installation result is recorded 及 No retained prior version。這是正常現象：安裝是由舊版更新程式執行，當時 1.14.4 的套件管理程式尚未啟用。這些訊息不表示安裝失敗。

更新 1.14.4 或更新版本

1.14.4 與更新版本使用 ABOUT 頁面的 Debian package update 區域。以下範例使用 Debian 套件 botnana-control_1.14.5-1_arm64.deb 更新產品版本 1.14.4。

1. 讓機台進入安全停止狀態，然後開啟 ABOUT。

2. 選擇 Select Debian package，再選取供應的 .deb 檔案。

3. 確認後續畫面顯示的所有資料：

   • 原始檔名；
   • 套件識別名稱（botnana-control）；
   • Debian 版本；
   • 架構（BN-B3A 應為 arm64）；
   • upgrade、reinstall 或 downgrade 等分類；
   • SHA-256 檢查碼。

   

4. 所有資料都符合預定版本時，才選擇 Stage package。暫存成功後，控制器會在下次開機時對已審查的確切套件執行一次安裝。

5. 確認畫面顯示 Staged; reboot to apply，然後選擇 REBOOT。不要以關機代替此次安裝所需的重新開機。

   

6. 等待控制器重新啟動，重新連線並開啟 ABOUT。

7. 同時確認畫面上的產品版本及 Last result。

   

安裝開始前可以取消 pending 套件。開機安裝一旦開始，就只會嘗試一次，不能取消，也不會自動重試。

保留套件與降版

頁面可能提供 Review retained version。這是先前由新套件管理程式成功安裝後所保留的完整套件，不一定是目前版本之前實際安裝的軟體；例如，曾透過舊版更新程式或 Linux 指令變更套件時，兩者可能不同。

若有保留套件，請選擇 Review retained version，確認其資訊及檢查碼，再暫存並重新開機。

如果畫面顯示 No retained prior version，請向動程公司取得所需且確認正常的套件；控制器無法從已安裝的檔案重建遺失的 .deb。以下範例在 1.14.5 運行時選取 botnana-control_1.14.4-2_arm64.deb。暫存前必須確認分類是 downgrade。

完成審查後，暫存該套件並重新開機。

重新啟動後，確認產品版本為 1.14.4，且結果顯示成功安裝 1.14.4-2。因為 1.14.5 是由新套件管理程式安裝，其完整套件現在可透過 Review retained version 1.14.5-1 使用。

畫面版本不符合預期時

保持機台停止。重新載入 ABOUT，並比較產品版本與 Last result。若完成一次性舊版升級後沒有安裝結果，請確認產品版本是否已變更為預定版本。若更新結果顯示失敗或版本仍是舊版，請暫存已審查且確認正常的套件後再重新開機；不要在沒有 pending 復原套件時反覆重新開機。

常見問題

• 登入 Linux 系統
• 網路設定
• USB連線IP設定

登入 Linux 系統

登入

使用 Type-C 傳輸線連結 BN-B3A 的 Type-C (OTG) 接口到電腦的 USB port，再以 ssh 登入，

ssh debian@192.168.7.2

密碼為 temppwd

下列命令會取得不受限制的 root shell，必須由獲授權管理員執行。程序若提供明確的 sudo <命令>，應優先只執行該命令；只有核准的維修工作才可使用 root shell，完成後 應立即退出：

sudo su

USB 連線 IP 設定

USB 連線 IP 設定

新購買的 BN-B3A 的 IP 為 192.168.7.2。因此，建議上位控制器的 IP 設為 192.168.7.1。網路遮罩設為 255.255.255.0 ，如下所示。

1. 開啟設定／網路和網際網路, 選擇進階網路設定中的變更界面卡選項。

   

2. 選擇型別為 Remote NDS 或是 RNDIS 的無法辨識的乙太網路。

   

3. 選擇此一網路的內容。

   

4. 選擇網際網路通訊協定。

   

5. 設定 IP 地址和遮罩。

   

6. 連線測試，使用命令提示字元或是 Power shell，

   

7. 執行 ssh debian@192.168.7.2，debian 為登入帳號。當詢問是否繼續時，回答 yes。

   

8. 詢問密碼時，回答 temppwd。

   

9. 以下為登入內建的 Linux 系統的畫面。

   

10. 也可以使用瀏覽器連上 http://192.168.7.2:3000 來進行確認。目前 BN-B3A 尚未支援 HTTPS，因此以下網頁會出現紅色不安全警告，可以忽略此警告。

    

修改控制器 IP 位址

1. 讓機台進入安全停止狀態，然後選擇 ABOUT。

2. 等待 Current IP address 顯示已儲存的控制器位址。繼續之前，請同時記錄舊位址及預定的新位址。

   

3. 在 Network prefix 輸入新網路的前三個數字。控制器位址固定以 .2 結尾。例如，輸入 192.168.6 會儲存 192.168.6.2。

4. 確認預覽顯示的位址完全符合預期。

   

5. 選擇 Set IP，並等待畫面顯示 IP address saved. It will change after reboot.

   

6. 如果無法使用 Set IP，請等待系統選定設定通訊協定第 2 版並載入已儲存設定。再次嘗試前，必須儲存或捨棄尚未儲存的機台設定變更。

7. 選擇 REBOOT。重新開機前，已儲存的新位址不會生效。

8. 將上位電腦改設至新網路，例如 192.168.6.1，再使用新位址重新連線控制器，例如 http://192.168.6.2:3000。

同一電腦連接多塊 BN-B3A

修改方式如 修改 IP ，但每塊 BN-B3A 要設為不同的 IP 區段。

例如︰ 第一塊設為 address 192.168.6.2，第二塊設為 address 192.168.7.2。

如果忘記了修改了的 IP ，該怎麼辦？

BN-B3A 有 HDMI 及 USB，接上螢幕及鍵盤，開機後可使用使用者名稱 debian 登入，密碼為 temppwd，登入後，執行 ip a。參考下圖，usb0 的 IP 就是設定的 IP，在圖中顯示的 IP 是 192.168.7.2 。