Dobot Magician – Deutsche Python-API-Dokumentation

Praxisorientierte Dokumentation der bisher verwendeten Funktionen aus DobotDllType.py

Grundlage

import DobotDllType as dType

DobotDllType.py kapselt die C/C++-API der DobotDll.dll und stellt deren Funktionen für Python bereit.

Python-Programm ↓ DobotDllType.py ↓ DobotDll.dll ↓ USB / serielle Verbindung ↓ Dobot Magician

Diese Dokumentation konzentriert sich auf die Funktionen, die bereits praktisch verwendet wurden oder unmittelbar für die bisherigen Dobot-Programme wichtig sind.

1. Verbindung

dType.load()

Aufgabe

Lädt die Dobot-Bibliothek DobotDll.dll und liefert ein API-Objekt zurück.

Aufruf

api = dType.load()

Beispiel

import DobotDllType as dType

api = dType.load()

Das Objekt api wird anschließend bei fast allen Dobot-Funktionen als erstes Argument benötigt.

ConnectDobot()

Aufgabe

Stellt die Verbindung zwischen dem Python-Programm und dem Dobot Magician her.

Aufruf

dType.ConnectDobot(api, portName, baudrate)
ParameterBedeutung
apiAPI-Objekt aus dType.load()
portNameCOM-Port, z. B. "COM10"
baudrateÜbertragungsgeschwindigkeit, gewöhnlich 115200

Beispiel

result = dType.ConnectDobot(api, "COM10", 115200)

Typischer Rückgabewert

[0, 'DobotSerial', '0.0.0']
if result[0] == dType.DobotConnect.DobotConnect_NoError:
    print("Dobot verbunden.")

DisconnectDobot()

Aufgabe

Trennt die Verbindung zum Dobot.

dType.DisconnectDobot(api)
try:
    # Dobot-Programm
    pass
finally:
    dType.DisconnectDobot(api)

2. Status und Position

GetPose()

Aufgabe

Liest die aktuelle Position und die Gelenkwinkel des Dobot aus.

pose = dType.GetPose(api)
[x, y, z, r, jointAngle1, jointAngle2, jointAngle3, jointAngle4]
pose = dType.GetPose(api)

print("X =", pose[0])
print("Y =", pose[1])
print("Z =", pose[2])
print("R =", pose[3])
print("J1 =", pose[4])
print("J2 =", pose[5])
print("J3 =", pose[6])
print("J4 =", pose[7])
IndexWert
0X-Koordinate
1Y-Koordinate
2Z-Koordinate
3Rotation R
4Gelenkwinkel J1
5Gelenkwinkel J2
6Gelenkwinkel J3
7Gelenkwinkel J4

3. Befehlswarteschlange

SetQueuedCmdClear()

Aufgabe

Löscht die Befehlswarteschlange des Dobot.

dType.SetQueuedCmdStopExec(api)
dType.SetQueuedCmdClear(api)

SetQueuedCmdStartExec()

Aufgabe

Startet die Ausführung der in der Queue gespeicherten Befehle.

dType.SetQueuedCmdStartExec(api)

SetQueuedCmdStopExec()

Aufgabe

Stoppt die Ausführung der Befehlswarteschlange.

dType.SetQueuedCmdStopExec(api)

GetQueuedCmdCurrentIndex()

Aufgabe

Liest den Index des zuletzt ausgeführten Queue-Befehls.

ziel_index = dType.SetPTPCmd(
    api,
    dType.PTPMode.PTPMOVLXYZMode,
    200, 0, 50, 0,
    isQueued=1
)[0]

dType.SetQueuedCmdStartExec(api)

while dType.GetQueuedCmdCurrentIndex(api)[0] < ziel_index:
    dType.dSleep(100)

dType.SetQueuedCmdStopExec(api)

Hilfsfunktion warten_bis_fertig()

Diese Funktion stammt nicht direkt aus der API, ist aber für eigene Programme nützlich.

def warten_bis_fertig(api, dType, ziel_index):
    dType.SetQueuedCmdStartExec(api)

    while dType.GetQueuedCmdCurrentIndex(api)[0] < ziel_index:
        dType.dSleep(100)

    dType.SetQueuedCmdStopExec(api)

dSleep()

Aufgabe

Wartet eine bestimmte Anzahl Millisekunden.

dType.dSleep(500)

500 ms = 0,5 Sekunden

4. HOME und Alarme

SetHOMEParams()

Aufgabe

Legt eine benutzerdefinierte HOME-Position fest.

dType.SetHOMEParams(api, x, y, z, r, isQueued)
dType.SetHOMEParams(api, 200, 0, 80, 0, isQueued=0)
Achtung: Vor einer HOME-Fahrt prüfen, ob die gewählte Position mit dem montierten Werkzeug kollisionsfrei erreichbar ist.

GetHOMEParams()

home = dType.GetHOMEParams(api)

print("HOME X:", home[0])
print("HOME Y:", home[1])
print("HOME Z:", home[2])
print("HOME R:", home[3])

SetHOMECmd()

Aufgabe

Startet die HOME-Funktion.

home_index = dType.SetHOMECmd(api, 0, 1)[0]
Achtung: HOME ist eine reale Roboterbewegung. Arbeitsbereich freihalten und auf ausreichende Z-Höhe achten.

GetAlarmsState()

Aufgabe

Liest den aktuellen Alarmstatus des Dobot aus.

alarm_result = dType.GetAlarmsState(api)
alarm_bytes = alarm_result[0]

if any(alarm_bytes):
    print("Alarm aktiv.")
else:
    print("Kein Alarm aktiv.")
Hinweis: Die genaue Dekodierung einzelner Alarmbits sollte anhand der zur verwendeten Firmware passenden Alarmtabelle erfolgen.

ClearAllAlarmsState()

Aufgabe

Versucht, gespeicherte Alarmzustände zu löschen.

dType.ClearAllAlarmsState(api)
dType.dSleep(300)

alarm_result = dType.GetAlarmsState(api)

if any(alarm_result[0]):
    print("Es ist weiterhin ein Alarm aktiv.")
Wichtig: Das Löschen des Alarmstatus beseitigt nicht automatisch die physische Ursache des Alarms.

5. Bewegung und Endeffektoren

SetPTPCommonParams()

Aufgabe

Legt den allgemeinen Geschwindigkeits- und Beschleunigungsfaktor für PTP-Bewegungen fest.

dType.SetPTPCommonParams(api, velocityRatio, accelerationRatio, isQueued)
dType.SetPTPCommonParams(api, 20, 20, 0)

Damit werden Geschwindigkeit und Beschleunigung auf 20 % gesetzt.

GetPTPCommonParams()

Aufgabe

Liest die aktuell eingestellten allgemeinen PTP-Faktoren aus.

werte = dType.GetPTPCommonParams(api)
print(werte)

Typische Ausgabe: [100.0, 100.0].

SetPTPJointParams()

Aufgabe

Legt Geschwindigkeit und Beschleunigung der vier Roboterachsen für PTP-Bewegungen fest.

dType.SetPTPJointParams(
    api,
    v1, v2, v3, v4,
    a1, a2, a3, a4,
    isQueued
)
dType.SetPTPJointParams(
    api,
    200, 200, 200, 200,
    200, 200, 200, 200,
    isQueued=0
)
Wichtig: Zuerst kommen vier Geschwindigkeitswerte, danach vier Beschleunigungswerte.

GetPTPJointParams()

werte = dType.GetPTPJointParams(api)
print(werte)
[
    200.0, 200.0, 200.0, 200.0,
    200.0, 200.0, 200.0, 200.0
]

Wert 0 bis 3: Geschwindigkeiten. Wert 4 bis 7: Beschleunigungen.

SetPTPCoordinateParams()

Aufgabe

Legt Geschwindigkeit und Beschleunigung für kartesische PTP-Bewegungen fest.

dType.SetPTPCoordinateParams(
    api,
    xyzVelocity,
    rVelocity,
    xyzAcceleration,
    rAcceleration,
    isQueued
)
dType.SetPTPCoordinateParams(
    api, 200, 100, 200, 100, isQueued=0
)

GetPTPCoordinateParams()

werte = dType.GetPTPCoordinateParams(api)

Typische Ausgabe: [200.0, 100.0, 200.0, 100.0].

Reihenfolge: xyzVelocity, rVelocity, xyzAcceleration, rAcceleration.

SetPTPCmd()

Aufgabe

Führt eine PTP-Bewegung aus beziehungsweise trägt sie in die Befehlswarteschlange ein.

index = dType.SetPTPCmd(
    api,
    ptpMode,
    x,
    y,
    z,
    r,
    isQueued
)[0]

Beispiel: lineare Bewegung

index = dType.SetPTPCmd(
    api,
    dType.PTPMode.PTPMOVLXYZMode,
    200, 0, 50, 0,
    isQueued=1
)[0]

Beispiel: nur Z ändern

pose = dType.GetPose(api)

x = pose[0]
y = pose[1]
r = pose[3]

index = dType.SetPTPCmd(
    api,
    dType.PTPMode.PTPMOVLXYZMode,
    x, y, 50, r,
    isQueued=1
)[0]

Damit bleiben X, Y und R unverändert; nur Z wird verändert.

SetEndEffectorSuctionCup()

Aufgabe

Schaltet den Saugnapf ein oder aus.

Sauger einschalten

dType.SetEndEffectorSuctionCup(
    api,
    True,
    True,
    isQueued=0
)

Sauger ausschalten

dType.SetEndEffectorSuctionCup(
    api,
    True,
    False,
    isQueued=0
)

Typisches vollständiges Grundmuster

import DobotDllType as dType

api = dType.load()

result = dType.ConnectDobot(
    api,
    "COM10",
    115200
)

if result[0] != dType.DobotConnect.DobotConnect_NoError:
    print("Verbindung fehlgeschlagen.")
    raise SystemExit

try:
    dType.SetQueuedCmdStopExec(api)
    dType.SetQueuedCmdClear(api)

    dType.SetPTPCommonParams(
        api,
        20,
        20,
        0
    )

    pose = dType.GetPose(api)

    x = pose[0]
    y = pose[1]
    z = pose[2]
    r = pose[3]

    print(
        f"Position: "
        f"X={x:.1f}, "
        f"Y={y:.1f}, "
        f"Z={z:.1f}, "
        f"R={r:.1f}"
    )

    ziel_index = dType.SetPTPCmd(
        api,
        dType.PTPMode.PTPMOVLXYZMode,
        x,
        y,
        z + 20,
        r,
        isQueued=1
    )[0]

    dType.SetQueuedCmdStartExec(api)

    while dType.GetQueuedCmdCurrentIndex(api)[0] < ziel_index:
        dType.dSleep(100)

finally:
    dType.SetQueuedCmdStopExec(api)
    dType.DisconnectDobot(api)

Gliederung

  1. Verbindung
  2. Status und Position
  3. Befehlswarteschlange
  4. HOME und Alarme
  5. Bewegung und Endeffektoren

Damit besteht bereits ein brauchbarer Kern einer deutschen Dokumentation zu DobotDllType.py, die sich an praktisch verwendeten Python-Befehlen orientiert.