# Dobot API(Dobot Magician)

## Demo
:::spoiler DobotControl.py

import threading
import DobotDllType as dType

# 連線結果字串對照（只是拿來印出可讀狀態）
CON_STR = {
    dType.DobotConnect.DobotConnect_NoError:  "DobotConnect_NoError",
    dType.DobotConnect.DobotConnect_NotFound: "DobotConnect_NotFound",
    dType.DobotConnect.DobotConnect_Occupied: "DobotConnect_Occupied"}

# 將廠商提供的 DLL 載入為 Python 可呼叫的介面（ctypes.CDLL）
api = dType.load()

# 與 Dobot 建立連線：第二個參數是序列埠（空字串=自動搜尋），115200 為鮑率
state = dType.ConnectDobot(api, "", 115200)[0]
print("Connect status:",CON_STR[state])

if (state == dType.DobotConnect.DobotConnect_NoError):
    
    # 清空命令佇列（把之前殘留的指令全部丟掉，乾淨開始）
    dType.SetQueuedCmdClear(api)
    
    # ---（可選）設定 HOME 位置，再執行回零 ---
    # dType.SetHOMEParams(api, 200, 0, 0, 0, isQueued = 1)
    # dType.SetHOMECmd(api, temp = 0, isQueued = 1)
    
    dType.SetQueuedCmdStartDownload(api, totalLoop=1, linePerLoop=1000)

    # ====== 運動參數設定（加入佇列，影響後續 PTP 指令）======

    # 關節空間的速度/加速度上限（°/s 與 °/s²），在使用 PTP 的 ANGLE 系列模式時生效
    dType.SetPTPJointParams(api,100,100,100,100,100,100,100,100,1)

    # 笛卡兒空間的速度/加速度上限（mm/s 與 mm/s²；R 為 °/s 與 °/s²）
    # 在使用 PTP 的 XYZ / MOVL / MOVJ 等笛卡兒模式，以及 JUMP_XYZ 時生效
    dType.SetPTPCoordinateParams(api, xyzVelocity=100, xyzAcceleration=160,rVelocity=60,  rAcceleration=120, isQueued=1)

    # 跳躍（JUMP）參數：拱高 jumpHeight（mm），以及 Z 安全上限 zLimit（mm）
    # 只在 JUMP 類模式下使用
    dType.SetPTPJumpParams(api, jumpHeight=60, zLimit=100, isQueued=1)

    # 全域比例（%）：會把上面設定的上限再乘上這裡的比例後套用
    dType.SetPTPCommonParams(api, 40, 40,1)

    # ====== 動作流程（加入佇列）======

    # 使用 PTP 的 JUMP_XYZ 模式（ptpMode=0），移動到 (232, 116, -18, r=0)
    dType.SetPTPCmd(api, ptpMode=0, x=232, y=116, z=-18, rHead=0, isQueued=1)

    # 夾爪：使能並閉合（enableCtrl=1, on=1）
    dType.SetEndEffectorGripper(api, enableCtrl=1, on=1, isQueued=1)

    # 等待 1000 ms（0.5~1s 常用，讓夾爪穩定）
    dType.SetWAITCmd(api, 1000, 1)

    # 再以 JUMP_XYZ 到 (217, -89, -19, r=0)
    dType.SetPTPCmd(api, ptpMode=0, x=217, y=-89, z=-19, rHead=0, isQueued=1)

    # 夾爪：使能但打開（鬆開物件）（enableCtrl=1, on=0）
    dType.SetEndEffectorGripper(api, enableCtrl=1, on=0, isQueued=1)

    # 等待 1000 ms
    dType.SetWAITCmd(api, 1000, 1)

    # 關閉夾爪輸出（完全關閉控制）
    dType.SetEndEffectorGripper(api, enableCtrl=0, on=0, isQueued=1)

    # 使用 PTP 的 MOVJ_XYZ 模式（ptpMode=1），先抬高到 (217, -89, 30, r=0)
    dType.SetPTPCmd(api, ptpMode=1, x=217, y=-89, z=30, rHead=0, isQueued=1)

    # 再以 MOVJ_XYZ 移動到 (200, 0, 100, r=0)

    dType.SetPTPCmd(api, ptpMode=1, x=200, y=0, z=100, rHead=0, isQueued=1)

    dType.SetQueuedCmdStopDownload(api)

# 中斷連線（釋放資源）
dType.DisconnectDobot(api)

:::
## 使用到的API

### 1. ConnectDobot(api, portName, baudrate)

<font color="#AC19C9">功能</font>：連線 Dobot。

<font color="#AC19C9">參數</font>：
api: load() 的回傳物件

portName: 串列埠名稱（例如 "COM3"、"/dev/ttyUSB0"）。給空字串 "" 代表自動搜尋

baudrate: 鮑率，Magician 預設 115200

<font color="#AC19C9">回傳</font>：一個列表
[result, masterDevType, slaveDevType, fwName, fwVer, masterId, slaveId, runTime]

result: 0=成功、1=未發現、2=被占用

其餘為裝置類型/韌體/ID/運行時間資訊

<font color="#AC19C9">備註</font>：你通常只會拿 [0] 看是否連上。

### 2. SetQueuedCmdClear(api)

<font color="#AC19C9">功能</font>：清空控制器中的命令佇列。

<font color="#AC19C9">備註</font>：每次開始新的流程前建議先清一次。

### 3. SetQueuedCmdStartDownload(api, totalLoop, linePerLoop)

<font color="#AC19C9">功能</font>：進入「離線腳本下載模式」。之後送入、且 isQueued=1 的指令都會被寫進離線腳本區。
<font color="#AC19C9">參數</font>：

totalLoop: 下載成離線腳本後，控制器預設要重複執行的迴圈數（通常填 1）

linePerLoop: 每個迴圈最多容納的「指令行數」上限（要設足夠大，像 1000）

<font color="#AC19C9">備註</font>：只負責打開離線下載通道，不會讓機器動；必須搭配 SetQueuedCmdStopDownload 關閉才會真正寫入。

### 4. SetPTPJointParams(api, j1Vel, j1Acc, j2Vel, j2Acc, j3Vel, j3Acc, j4Vel, j4Acc, isQueued=0)

<font color="#AC19C9">功能</font>：設定 關節空間（Joint）的 PTP 最大速度與加速度上限（J1~J4）。
單位/範圍（常見值）：

速度（Vel）：度/秒（°/s），建議 0–200 之間

加速度（Acc）：度/秒²（°/s²），建議 0–200 之間

### 5. SetPTPCoordinateParams(api, xyzVelocity, xyzAcceleration, rVelocity, rAcceleration, isQueued=0)

<font color="#AC19C9">功能</font>：設定 笛卡兒空間 PTP 上限：

xyzVelocity / xyzAcceleration: XYZ 平移軸的上限（mm/s、mm/s²）

rVelocity / rAcceleration: 末端旋轉 R 的上限（°/s、°/s²）
常見範圍：

xyzVelocity/Acc：0–200（或依你機台/工況）

rVelocity/Acc：0–200

### 6. SetPTPJumpParams(api, jumpHeight, zLimit, isQueued=0)

<font color="#AC19C9">功能</font>：設定 JUMP 路徑形狀參數

jumpHeight: 拱高（mm）：從起點抬起的高度

zLimit: Z 安全上限（mm）：JUMP 過程 Z 不超過此高度

<font color="#AC19C9">備註</font>：只在 JUMP 模式時生效

### 7. SetPTPCommonParams(api, velocityRatio, accelerationRatio, isQueued=0)

<font color="#AC19C9">功能</font>：設定 全域比例（%）

velocityRatio: 對「已設定的上限」再乘的速度比例（0–100）

accelerationRatio: 對上限再乘的加速度比例（0–100）

<font color="#AC19C9">備註</font>：實際速度/加速度 =（Joint/Coordinate 設定的上限）×（這裡的比例）。常用來全局「降速」測路徑安全。

### 8. SetPTPCmd(api, ptpMode, x, y, z, rHead, isQueued=0)

<font color="#AC19C9">功能</font>：下達一個 PTP 目標點。
<font color="#AC19C9">參數</font>：

**ptpMode**

0: JUMP_XYZ（跳躍，XYZr）

1: MOVJ_XYZ（關節插補到 XYZr）

2: MOVL_XYZ（直線插補到 XYZr）

3: JUMP_ANGLE（跳躍，關節角度）

4: MOVJ_ANGLE（關節插補到關節角）

5: MOVL_ANGLE（直線插補到關節角）

6: MOVJ_ANGLE_INC（關節角增量）

7: MOVL_XYZ_INC（XYZ 增量，直線）

8: MOVJ_XYZ_INC（XYZ 增量，關節）

9: JUMP_MOVL_XYZ（JUMP，平移段用直線 MOVL）

x, y, z（mm）、rHead（°）：目標位姿

### 9. SetEndEffectorGripper(api, enableCtrl, on, isQueued=0)

<font color="#AC19C9">功能</font>：控制氣動夾爪/電動夾爪開關。

<font color="#AC19C9">參數</font>：

enableCtrl: 1=啟用夾爪功能；0=關閉夾爪功能

on: 1=抓取/閉合；0=釋放/打開（僅在 enableCtrl=1 下有效）

### 10. SetWAITCmd(api, waitTime, isQueued=0)

<font color="#AC19C9">功能</font>：在佇列中插入等待。
<font color="#AC19C9">參數</font>：

waitTime: 毫秒（ms）

<font color="#AC19C9">備註</font>：常在夾爪動作後放 1000 ms 讓氣壓/機構穩定。

### 11. SetQueuedCmdStopDownload(api)

<font color="#AC19C9">功能</font>：結束離線下載並將佇列寫入控制器的離線腳本區（很重要！）
<font color="#AC19C9">參數</font>：api

<font color="#AC19C9">備註</font>：少了這步，剛才排進去的 queued 指令不會被存成離線腳本。

### 12. DisconnectDobot(api)

<font color="#AC19C9">功能</font>：斷線、釋放資源（關閉序列阜）。

<font color="#AC19C9">備註</font>：離線下載完成後建議就斷線，測離線執行時避免被 PC 端程式占用。