API Description

Dobot Magician API

Description

Issue: V1.2.3

Date: 2019-07-19

Shenzhen Yuejiang Technology Co., Ltd

 Dobot Magician API Description

Copyright © ShenZhen Yuejiang Technology Co., Ltd 2018. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means
without prior written consent of Yuejiang Technology Co., Ltd

Disclaimer
To the maximum extent permitted by applicable law, the products described (including its
hardware, software and firmware, etc.) in this document are provided AS IS, which may have flaws,
errors or faults. Yuejiang makes no warranties of any kind, express or implied, including but not
limited to, merchantability, satisfaction of quality, fitness for a particular purpose and non-
infringement of third party rights. In no event will Yuejiang be liable for any special, incidental,
consequential or indirect damages resulting from the use of our products and documents.
Before using our product, please thoroughly read and understand the contents of this document
and related technical documents that are published online, to ensure that the robotic arm is used on
the premise of fully understanding the robotic arm and related knowledge. Please use this document
with technical guidance from professionals. Even if follow this document or any other related
instructions, Damages or losses will be happen in the using process, Dobot shall not be considered
as a guarantee regarding to all security information contained in this document.
The user has the responsibility to make sure following the relevant practical laws and
regulations of the country, in order that there is no significant danger in the use of the robotic arm.

Shenzhen Yuejiang Technology Co., Ltd

Address: 3F, Building NO.3, Tongfuyu Industrial Town, Nanshan District, Shenzhen, China
Website: www.dobot.cc

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
i
 Dobot Magician API Description Preface

Preface
Purpose
The document is aiming to have a detailed description of Dobot API and general process of
Dobot API development program.
Intended Audience
This document is intended for:
 Customer Engineer
 Installation and Commissioning Engineer
 Technical Support Engineer
Change History

Date Change Description

2019/07/19  Add a note for API return result

 Add the description of the relationship between the speed and speed rate

 Adjust the content structure

2019/05/05 Add a note for API SetJOGCmd

2018/11/06 Modify some mistakes of API function

2018/03/26 The first release

Symbol Conventions
The symbols that may be founded in this document are defined as follows.

Symbol Description

Indicates a hazard with a high level of risk which, if not

DANGER avoided, could result in death or serious injury

Indicates a hazard with a medium level or low level of

WARNING risk which, if not avoided, could result in minor or
moderate injury, robotic arm damage

Indicates a potentially hazardous situation which, if not

NOTICE avoided, can result in robotic arm damage, data loss, or
unanticipated result

NOTE Provides additional information to emphasize or

supplement important points in the main text

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
ii
 Dobot Magician API Description Contents

Contents
Dobot Commands..................................................................................................... 1
Command Timeout .................................................................................................. 2
Setting Command Timeout ............................................................................................... 2
Connect/Disconnect.................................................................................................. 3
Searching for the Dobot .................................................................................................... 3
Connecting to the Dobot ................................................................................................... 3
Disconnecting the Dobot................................................................................................... 4
Demo: Connection Example ............................................................................................. 4
Command queue controlling ................................................................................... 6
Starting Command in Command queue ............................................................................ 6
Stopping Command in Command queue .......................................................................... 6
Stopping Command in Command queue Forcedly ........................................................... 6
Demo: Processing PTP Command and Control Queue Synchronously ............................ 7
Demo: Processing PTP Command and Controlling Queue Asynchronously .................... 8
Downloading Commands.................................................................................................. 9
Stopping Downloading Commands. ................................................................................. 9
Demo: Downloading PTP Command................................................................................ 9
Clearing Command queue............................................................................................... 10
Getting Command Index ................................................................................................. 10
Demo: Checking Whether the Commands Have Been Executed ................................... 11
Device Information ................................................................................................ 13
Setting the Device Serial Number ................................................................................... 13
Getting the Device Serial Number .................................................................................. 13
Setting the Device Name ................................................................................................ 13
Getting the Device Name ................................................................................................ 13
Getting the Device Version ............................................................................................. 14
Setting the Sliding Rail Status ........................................................................................ 14
Getting the Sliding Rail Status ........................................................................................ 15
Getting the Device Clock ................................................................................................ 15
Real-time pose ........................................................................................................ 16
Getting the Real-time Pose of the Dobot ........................................................................ 16
Getting the Real-time Pose of the Sliding Rail ............................................................... 16
Resetting the Reference Value of the Real-time Pose ..................................................... 17
ALARM .................................................................................................................. 18
Getting the Alarm Status ................................................................................................. 18
Clearing the Statuses of All Alarms ................................................................................ 18
Homing Function ................................................................................................... 19
Setting the Homing Position ........................................................................................... 19
Getting the Homing Position .......................................................................................... 19
Executing the Homing Function ..................................................................................... 20
Executing the Automatic Leveling Function................................................................... 20
Getting the Automatic Leveling Results ......................................................................... 21
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
iii
 Dobot Magician API Description Contents

HHT Function ........................................................................................................ 22

Setting the Hand-Hold Teaching Trigger Mode .............................................................. 22
Getting the Hand-Hold Teaching Trigger Mode ............................................................. 22
Setting the Status of the Hand-Hold Teaching Function ................................................. 23
Getting the Status of the Hand-Hold Teaching Function ................................................ 23
Getting the Hand-Hold Teaching Trigger Single ............................................................ 23
Demo: Hand-Hold Teaching ........................................................................................... 23
End-effector .......................................................................................................... 25
Setting the Offset of the End-effector ............................................................................. 25
Getting the Offset of the End-effector ............................................................................ 25
Setting the Status of the Laser......................................................................................... 26
Getting the Status of the Laser ........................................................................................ 26
Setting the Status of the Air Pump .................................................................................. 26
Getting the Status of the Air Pump ................................................................................. 27
Setting the Status of the Gripper ..................................................................................... 27
Getting the Status of the Gripper .................................................................................... 28
JOG ....................................................................................................................... 29
Setting the Velocity and Acceleration of the Joint Coordinate Axis when Jogging ........ 29
Getting the Velocity and Acceleration of the Joint Coordinate Axis when Jogging ....... 29
Setting the velocity and acceleration of the Cartesian Coordinate Axis when Jogging .. 30
Getting the velocity and acceleration of the Cartesian Coordinate Axis when Jogging . 30
Setting the velocity and acceleration of the Sliding Rail when Jogging ......................... 31
Getting the velocity and acceleration of the Sliding Rail when Jogging ........................ 31
Setting the Velocity Ratio and Acceleration Ratio when Jogging ................................... 32
Getting the Velocity Ratio and Acceleration Ratio when Jogging .................................. 33
Executing the Jogging Command ................................................................................... 33
PTP ........................................................................................................................ 35
Setting the Velocity and Acceleration of the Joint Coordinate Axis in PTP Mode ......... 36
Getting the Velocity and Acceleration of the Joint Coordinate Axis in PTP Mode ......... 36
Setting the Velocity and Acceleration of the Cartesian Coordinate Axis in PTP Mode .. 37
Getting the Velocity and Acceleration of the Cartesian Coordinate Axis in PTP Mode . 37
Setting the Lifting Height and the Maximum Lifting Height in JUMP mode ................ 38
Getting the Lifting Height and the Maximum Lifting Height in JUMP mode ................ 38
Setting the Extended Parameters in JUMP mode............................................................ 39
Getting the Extended Parameters in JUMP mode ........................................................... 39
Setting the Velocity and Acceleration of the Sliding Rail in PTP Mode ......................... 40
Getting the Velocity and Acceleration of the Sliding rail in PTP Mode .................. 40
Setting the Velocity Ratio and Acceleration Ratio in PTP Mode ............................ 41
Getting the Velocity Ratio and Acceleration Ratio in PTP Mode............................ 41
Executing a PTP Command .................................................................................... 42
Executing a PTP Command with the I/O Control ................................................... 43
Executing a PTP Command with the Sliding Rail .................................................. 45
Executing a PTP Command with the Sliding Rail and I/O Control ........................ 46
CP .......................................................................................................................... 49
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
iv
 Dobot Magician API Description Contents

Setting the Velocity and Acceleration in CP Mode ......................................................... 49

Getting the Velocity and Acceleration in CP Mode ........................................................ 49
Executing the CP Command ........................................................................................... 50
Executing the CP Command with the Laser Engraving .................................................. 51
ARC ....................................................................................................................... 53
Setting the Velocity and Acceleration in ARC Mode ...................................................... 53
Getting the Velocity and Acceleration in ARC Mode ..................................................... 53
Executing the ARC Command ........................................................................................ 54
Executing the CIRCLE Command .................................................................................. 55
Losing-Step Detection .......................................................................................... 57
Setting the losing-step threshold ..................................................................................... 57
Executing the Losing-Step Command ............................................................................ 57
Demo: Executing the Losing-Step Command................................................................. 57
WAITING ............................................................................................................. 59
Executing the Waiting Command ................................................................................... 59
TRIGGERING ..................................................................................................... 60
Executing the Triggering Command ............................................................................... 60
EIO ........................................................................................................................ 61
Setting the I/O Multiplexing ........................................................................................... 61
Getting the I/O multiplexing ........................................................................................... 62
Setting the I/O Output ..................................................................................................... 62
Getting the I/O Output .................................................................................................... 63
Setting the PWM Output ................................................................................................. 63
Getting the PWM Output ................................................................................................ 64
Getting the I/O Input ....................................................................................................... 64
Getting the A/D Input...................................................................................................... 65
Setting the Velocity of the Extended Motor .................................................................... 65
Setting the Velocity of the Extended Motor and the Movement Distance .............. 66
Enabling the Photoelectric Sensor........................................................................... 66
Getting the Photoelectric Sensor Value ................................................................... 67
Enabling the Color Sensor....................................................................................... 67
Getting the Color Sensor Value ............................................................................... 68
CAL ....................................................................................................................... 69
Setting the Angle Sensor Static Error ............................................................................. 69
Getting the Angle Sensor Static Error ............................................................................. 69
Setting the Linearization Parameter of the Angle Sensor ............................................... 69
Getting the Linearization Parameter of the Angle Sensor ............................................... 70
Setting the Static Error of the Base Encoder................................................................... 70
Getting the Static Error of the Base Encoder .................................................................. 70
WIFI ...................................................................................................................... 72
Enabling WIFI ................................................................................................................ 72
Getting the WIFI Status .................................................................................................. 72
Setting the SSID.............................................................................................................. 72
Getting the SSID ............................................................................................................. 73
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
v
 Dobot Magician API Description Contents

Setting the Network Password ........................................................................................ 73

Getting the Network Password ....................................................................................... 73
Setting the IP Address ..................................................................................................... 73
Getting the IP Address .................................................................................................... 74
Setting the Sub Netmask ................................................................................................. 74
Getting the Sub Netmask......................................................................................... 74
Setting the Gateway ................................................................................................ 75
Getting the Gateway ................................................................................................ 76
Setting the DNS....................................................................................................... 76
Getting the DNS ...................................................................................................... 77
Getting the WIFI Connection Status ....................................................................... 77
Other functions..................................................................................................... 78
Event Loop ...................................................................................................................... 78

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
vi
 Dobot Magician API Description 1 Dobot Commands

Dobot Commands
Dobot controller supports two kind of commands: Immidiate command and queue command:
 Immidiate command: Dobot controller will process the command once received
regardless of whether there is the rest commands processing or not in the current
controller;
 Queue command: When Dobot controller receives a command, this command will be
pressed into the controller internal command queue. Dobot controller will execute
commands in the order in which the commands were pressed into the queue.
For more detailed information about Dobot commands, please refer to Dobot protocol.

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
1
 Dobot Magician API Description 2 Command Timeout

Command Timeout

Setting Command Timeout

As described in 1 Dobot Commands, all commands sent to Dobot controller have returns. When
a command error occurs due to a communication link interference or any other factors, this
command cannot be recognized by the controller and will have no return. Therefore, each command
issued to the controller has a timeout period. The timeout period can be set by the following API.

Table 2.1 Set timeout

Prototype void SetCmdTimeout( unsigned int cmdTimeout)

Description Set command timeout. If a command is required to return data within a given
time after issuing it, please call this API to set timeout to check whether the
return of this command is overtime

Parameter cmdTimeout: Command timeout. Unit: ms

Return DobotCommunicate_NoError:There is no error

NOTE
API returns result as an enumerate type. You can view them in the DobotType.h file.

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
2
 Dobot Magician API Description 3 Connect/Disconnect

Connect/Disconnect

Searching for the Dobot

Table 3.1 Search for the Dobot

Prototype int SearchDobot(char *dobotNameList, uint32_t maxLen)

Description Search for Dobot, DLL will store the information of Dobot that has been
searched for and use ConnectDobot to connect the searched Dobot

Parameter dobotNameList: String pointer, DLL will write serial port/UDP searched into
dobotNameList. For example, a specific dobotNameList is "COM1 COM3
COM6 192.168.0.5", different serial port or IP address should be separated
by the space
maxLen: Maximum String length, to avoid memory overflow

Return The number of Dobot

Connecting to the Dobot

Table 3.2 Connect to the Dobot

Prototype int ConnectDobot(const char *portName, uint32_t baudrate, char *fwType,

char *version float *time)

Description Connecing to the Dobot. In this process, portName can be obtained from
dobotList in the SearchDobot(char *dobotList, uint32_t maxLen) API.
If portName is empty, and ConnectDobot is called directly, DLL will
connect the random searched Dobot automatically

Parameter portName: Dobot port. As for the serial port, portName is COM3; While for
UDP, portName is 192.168.0.5
baudrate: Baud rates. Value: 115200
fwType: Firmware type. Dobot or Marlin
version: Version
time: Timeout

Return DobotConnect_NoError： The connection is successful

DobotConnect_NotFound：Dobot interface was not found
DobotConnect_Occupied：Dobot interface is occupied or unavailable

NOTICE

In order to make the API recognize the Dobot controller interface, please install the
required driver in advance. For more details, please refer to Dobot User Guide.

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
3
 Dobot Magician API Description 3 Connect/Disconnect

Disconnecting the Dobot

Table 3.3 Disconnect the Dobot

Prototype void DisconnectDobot(void)

Description Disconnect the Dobot

Parameter None

Return DobotConnect_NoError :There is no error

Demo: Connection Example

Program 3.1 Connection Example

#include "DobotDll.h"

int split(char **dst, char* str, const char* spl)

{
int n = 0;
char *result = NULL;
result = strtok(str, spl);
while( result != NULL )
{
strcpy(dst[n++], result);
result = strtok(NULL, spl);
}
return n;
}

int main(void)
{
int maxDevCount = 100;
int maxDevLen = 20;

char *devsChr = new char[maxDevCount * maxDevLen]();

char **devsList = new char*[maxDevCount]();
for(int i=0; i<maxDevCount; i++)
devsList[i] = new char[maxDevLen]();

SearchDobot(devsChr, 1024);
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
4
 Dobot Magician API Description 3 Connect/Disconnect

split(devsList, devsChr, " ");

ConnectDobot(devsList[0], 115200, NULL, NULL, NULL);

// Control Dobot

DisconnectDobot();

delete[] devsChr;
for(int i=0; i<maxDevCount; i++)
delete[] devsList[i];
delete[] devsList;
}

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
5
 Dobot Magician API Description 4 Command queue controlling

Command queue controlling

There is a queue in Dobot controller to store and execute commands in order. You can also start
and stop a command in the command queue to realize asynchronous operations.

NOTICE

Only the API where the isQueued parameter is set to 1 can be added to the command
queue.

Starting Command in Command queue

Table 4.1 Start command in command queue

Prototype int SetQueuedCmdStartExec(void)

Description The Dobot controller starts to query command queue periodically. If there
are commands in queue, Dobot controller will take them out and execute the
commands in order, indicating that Dobot executes commands one after
another

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Stopping Command in Command queue

Table 4.2 Stop command in command queue

Prototype int SetQueuedCmdStopExec(void)

Description The Dobot controller stops to query command queue and execute command.
However, if one command is being executed when this API is called, this
command will continue to be executed.

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Stopping Command in Command queue Forcedly

Table 4.3 Stop command in command queue forcedly

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
6
 Dobot Magician API Description 4 Command queue controlling

Prototype int SetQueuedCmdForceStopExec(void)

Description Dobot controller stops to query command queue and execute command. If
one command is being executed when this API is called, this command will
be stopped forcedly.

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout (aka error)

Demo: Processing PTP Command and Control Queue

Synchronously
For details about PTP, please refer to 12 PTP.

Program 4.1 Process PTP command and control queue synchronously

#include "DobotDll.h"

int main(void)

uint64_t queuedCmdIndex = 0;

PTPCmd cmd;

cmd.ptpMode = 0;

cmd.x = 200;

cmd.y = 0;

cmd.z = 0;

cmd.r = 0;

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

SetQueuedCmdStartExec();

SetPTPCmd(&cmd, true, &queuedCmdIndex);

SetQueuedCmdStopExec();

DisconnectDobot();

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
7
 Dobot Magician API Description 4 Command queue controlling

Demo: Processing PTP Command and Controlling Queue

Asynchronously
Program 4.2 Process PTP command and control queue asynchronously

#include "DobotDll.h"

// Main thread

int main(void)

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

int onButtonClick()

static bool flag = True;

if (flag)

SetQueuedCmdStartExec();

else

SetQueuedCmdStopExec();

// Child thread

int thread(void)

uint64_t queuedCmdIndex = 0;

PTPCmd cmd;

cmd.ptpMode = 0;

cmd.x = 200;

cmd.y = 0;

cmd.z = 0;

cmd.r = 0;

while(true)

SetPTPCmd(&cmd, true, &queuedCmdIndex);

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
8
 Dobot Magician API Description 4 Command queue controlling

Downloading Commands
The Dobot controller supports downloading commands to the controller's external Flash, and
the commands can be triggered by pressing the keys on the controller. That is, the operation is in
offline mode.

Table 4.4 Download commands

Prototype int SetQueuedCmdStartDownload(uint32_t totalLoop, uint32_t

linePerLoop)

Description Download commands. If the operation of Dobot need to be in offline mode,

please call this API

Parameter totalLoop: Loops of commands in offline mode

linePerLoop: loops of per command in offline mode. The number of the
issued commands must be the same as linePerLoop. The issued commands
should be added to the command queue.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Stopping Downloading Commands.

Table 4.5 Stop to download commands

Prototype int SetQueuedCmdStopDownload(void)

Description Stop downloading commands. If the Dobot is in offline mode, please call this
API

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Demo: Downloading PTP Command

Program 4.3 Download PTP command

#include "DobotDll.h"

int main(void)

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
9
 Dobot Magician API Description 4 Command queue controlling

uint64_t queuedCmdIndex = 0;

PTPCmd cmd;

cmd.ptpMode = 0;

cmd.x = 200;

cmd.y = 0;

cmd.z = 0;

cmd.r = 0;

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

// Issue only one PTP command, so linePerLoop is set to 1

// totalLoop is set to 2, so Dobot controller executes the PTP command twice.

SetQueuedCmdStartDownload(2, 1);

SetPTPCmd(&cmd, true, &queuedCmdIndex);

SetQueuedCmdStopDownload();
DisconnectDobot();

The general flow of commands to download is:

Call the SetQueuedCmdStartDownload API.
Send commands and add to the command queue.
Call the SetQueuedCmdStopDownload API.

Clearing Command queue

This API can clear the command queue buffered in the Dobot controller.

Table 4.6 Clear command queue

Prototype int SetQueuedCmdClear(void)

Description Clear command queue

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting Command Index

In the Dobot controller, there is a 64-bit internal counter. When the controller executes a
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
10
 Dobot Magician API Description 4 Command queue controlling

command, the counter will automatically increment. With this internal index, you can get how many
commands the controller has executed.

Table 4.7 Get command index

Prototype int GetQueuedCmdCurrentIndex(uint64_t *queuedCmdCurrentIndex)

Description Get the index of the command the controller has executed currently

Parameter queuedCmdCurrentIndex: Command index

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Demo: Checking Whether the Commands Have Been Executed

Program 4.4 Check whether the commands have been executed by comparing the indexes

#include "DobotDll.h"

int main(void)

uint64_t queuedCmdIndex = 0;

uint64_t executedCmdIndex = 0;

PTPCmd cmd;

cmd.ptpMode = 0;

cmd.x = 200;

cmd.y = 0;

cmd.z = 0;

cmd.r = 0;

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

SetQueuedCmdStartExec();

SetPTPCmd(&cmd, true, &queuedCmdIndex);

// Check whether the commands have been executed by comparing the indexes

While(executedCmdIndex < queuedCmdIndex)

GetQueuedCmdCurrentIndex(&executedCmdIndex);

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
11
 Dobot Magician API Description 4 Command queue controlling

SetQueuedCmdStopExec();

DisconnectDobot();

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
12
 Dobot Magician API Description 5 Device Information

Device Information

Setting the Device Serial Number

Table 5.1 Set the device serial number

Prototype int SetDeviceSN(const char *deviceSN)

Description Set the device serial number. This API is valid only when shipped out (The
special password is required)

Parameter deviceSN: String pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Device Serial Number

Table 5.2 Get the device serial number

Prototype int GetDeviceSN(char *deviceSN, uint32_t maxLen)

Description Get the device serial number

Parameter deviceSN: Strings of device serial number

maxLen: Maximum string length, to avoid overflow

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Device Name

Table 5.3 Set the device name

Prototype int SetDeviceName(const char *deviceName)

Description Set the device name. When there are multiple machines, you can use this API
to set the device name for distinction

Parameter deviceName: String pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Device Name

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
13
 Dobot Magician API Description 5 Device Information

Table 5.4 Get the device name

Prototype int GetDeviceName(char *deviceName, uint32_t maxLen)

Description Get the device name. When there are multiple machines, you can use this
API to get the device name for distinction.

Parameter deviceName: String pointer

maxLen: Maximum string length, to avoid overflow

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Device Version

Table 5.5 Get the device version

Prototype int GetDeviceVersion(uint8_t *majorVersion, uint8_t *minorVersion, uint8_t

*revision)

Description Get the device version

Parameter majorVersion: Main version

minorVersion: Secondary version
revision: Revised version

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Sliding Rail Status

Table 5.6 Set the sliding rail status

Prototype int SetDeviceWithL(bool isEnable, bool isQueued, uint64_t

*queuedCmdIndex, uint8_t version)

Description Set the sliding rail status. When the sliding rail kit is used, please call this
API. Only the status of the sliding rail is enabled, the commands related to
the sliding rail can be effected.

Parameter isEnable: 0, Disabled. 1, Enabled

isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.
version: Version flag of sliding rail. 0: The version is V1.0. 1: The version is

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
14
 Dobot Magician API Description 5 Device Information

V2.0

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Sliding Rail Status

Table 5.7 Get the sliding rail status

Prototype int GetDeviceWithL(bool *isEnable)

Description Get the sliding rail status. When the sliding rail kit is used, please call this
API

Parameter isEnable: 0, Disabled. 1, Enabled

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Device Clock

Table 5.8 Get the device clock

Prototype int GetDeviceTime(unit32_t *deviceTime)

Description Get the device clock

Parameter deviceTime: Device clock

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
15
 Dobot Magician API Description 6 Real-time pose

Real-time pose
In DobotV2.0, the Dobot controller calculates the reference value of the real-time pose based
on the following information.
 Encoder value on the base (can be obtained by Homing).
 Rear Arm angle sensor value (power on or press UNLOCK button on Forearm);
 Forearm angle sensor value (power on or press UNLOCK button on Forearm).
When controlling the Dobot, the Dobot controller will update the real-time pose based on the
reference value and the real-time motion status.

Getting the Real-time Pose of the Dobot

Table 6.1 Get the real-time pose of Dobot

Prototype int GetPose(Pose *pose)

Description Get the real-time pose of the Dobot

Parameter Pose:
typedef struct tagPose {
float x; //Cartesian coordinate system X-axis
float y; //Cartesian coordinate system Y-axis
float z; // Cartesian coordinate system Z-axis
float r; //Cartesian coordinate system R-axis
float jointAngle[4]; //Joints (including base, Rear Arm, Forearm, and
End-effector) angles
}Pose;
Pose: Pose pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Real-time Pose of the Sliding Rail

Table 6.2 Get the real-time pose of sliding rail

Prototype int GetPose(Pose *pose)

Description Get the real-time pose of the sliding rail

Parameter Pose: The current position of sliding rail. Unit: mm

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
16
 Dobot Magician API Description 6 Real-time pose

timeout

Resetting the Reference Value of the Real-time Pose

The reference value of the real-time pose can be reset in the following cases.
 Angle sensor is damaged.
 Angle sensor accuracy is too poor.

Table 6.3 Reset the reference value of the real-time pose

Prototype int ResetPose(bool manual, float rearArmAngle, float frontArmAngle)

Description Reset the reference value of the real-time pose

Parameter manual: Indicate whether to reset reference value of real-time pose

automatically. 0, reset the reference value automatically and rearArmAngle
and frontArmAngle are not to set. 1, rearArmAngle and frontArmAngle
need to be set
rearArmAngle: Rear Arm angle
frontArmAngle: Forearm angle

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
17
 Dobot Magician API Description 7 ALARM

ALARM

Getting the Alarm Status

Table 7.1 Get the alarm status

Prototype int GetAlarmsState(uint8_t *alarmsState, uint32_t *len, uint32_t maxLen)

Description Get the alarm status

Parameter alarmsState: The first address of the array. Each byte in the array
alarmsState identifies the alarms status of the eight alarm items, with the
MSB (Most Significant Bit) at the top and LSB (Least Significant Bit) at the
bottom.
len: The byte occupied by the alarm.
maxLen: Maximum array length, to avoid overflow

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Clearing the Statuses of All Alarms

Table 7.2 Clear the statuses of all alarms

Prototype int ClearAllAlarmsState(void)

Description Clear the statuses of all alarms

Parameter None

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
18
 Dobot Magician API Description 8 Homing Function

Homing Function
If your Dobot is running too fast or the load is too large for the dobot, the position precision
can be reduced. You can execute the homing function to improve the precision.

Setting the Homing Position

Table 8.1 Set the homing position

Prototype int SetHOMEParams(HOMEParams *homeParams, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the homing position

Parameter HOMEParams:
typedef struct tagHOMEParams {
float x; //Cartesian coordinate system X-axis
float y; //Cartesian coordinate system Y-axis
float z; // Cartesian coordinate system Z-axis
float r; //Cartesian coordinate system R-axis
}HOMEParams;
homeParams: HOMEParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Homing Position

Table 8.2 Get the homing position

Prototype int GetHOMEParams(HOMEParams *homeParams)

Description Get the homing position

Parameter HOMEParams:
typedef struct tagHOMEParams {
float x; //Cartesian coordinate system X-axis
float y; //Cartesian coordinate system Y-axis
float z; // Cartesian coordinate system Z-axis

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
19
 Dobot Magician API Description 8 Homing Function

float r; //Cartesian coordinate system R-axis

}HOMEParams;
homeParams: HOMEParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the Homing Function

Table 8.3 Execute the homing function

Prototype int SetHOMECmd(HOMECmd *homeCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the homing function. If you call the SetHOMEParams API before
calling this API, Dobot will move to the user-defined position. If not, Dobot
will move to the default position directly.

Parameter HOMECmd:
typedef struct tagHOMECmd {
uint32_t reserved; // Reserved for future use
}HOMECmd;
homeCmd: HOMECmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the Automatic Leveling Function

If the value of the Rear Arm angle sensor or the Forearm angle sensor is error, it means that the
position precision is reduced. You can call this API to improve the precision. If the high position
accuracy is required, you need to perform leveling manually. For more details, please see Dobot
Magician User Guide.

Table 8.4 Execute the Automatic leveling function

Prototype int SetAutoLevelingCmd(AutoLevelingCmd *autoLevelingCmd, bool

isQueued, uint64_t *queuedCmdIndex)

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
20
 Dobot Magician API Description 8 Homing Function

Description Execute the automatic leveling function

Parameter AutoLevelingCmd :
typedef struct tagAutoLevelingCmd{
uint8_t controlFlag; //Enabe Flag
float precision; //Leveling precision, the minimum is 0.02
}AutoLevelingCmd;
autoLevelingCmd : AutoLevelingCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Automatic Leveling Results

Table 8.5 Get the automatic leveling results

Prototype int GetAutoLevelingResult(float *precision)

Description Get the automatic leveling results

Parameter precision: Leveling precision

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
21
 Dobot Magician API Description 9 HHT Function

HHT Function
HHT indicates Hand-Hold Teaching. In general, you can press and hold down Unlock key on
Forearm and drag Dobot to any position. And then save point after releasing Unlock key.

Setting the Hand-Hold Teaching Trigger Mode

Table 9.1 Set the hand-hold teaching mode

Prototype int SetHHTTrigMode (HHTTrigMode hhtTrigMode)

Description Set the hand-hold teaching triggering mode. If this API is not called, Dobot
will save points when releasing the UNLOCK key on Forearm

Parameter HHTTrigMode:
typedef enum tagHHTTrigMode {
TriggedOnKeyReleased, //Trigger when releasing the
UNLOCK key
TriggeredOnPeriodicInterval //Trigger when pressing the
UNLOCK key
}HHTTrigMode;
hhtTrigMode: HHTTrigMode enum

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Hand-Hold Teaching Trigger Mode

Table 9.2 Get the hand-hold teaching trigger mode

Prototype int GetHHTTrigMode (HHTTrigMode hhtTrigMode)

Description Get the handhold teaching trigger mode.

Parameter HHTTrigMode:
typedef enum tagHHTTrigMode {
TriggedOnKeyReleased, //Trigger when releasing the
UNLOCK key
TriggeredOnPeriodicInterval //Trigger when pressing the
UNLOCK key
}HHTTrigMode;
hhtTrigMode: HHTTrigMode enum

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
22
 Dobot Magician API Description 9 HHT Function

timeout

Setting the Status of the Hand-Hold Teaching Function

Table 9.3 Set the status of the hand-hold teaching function

Prototype int SetHHTTrigOutputEnabled (bool isEnabled)

Description Set the status of the hand-hold teaching function

Parameter isEnabled: 0 : Disabled. 1 : Enabled

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Status of the Hand-Hold Teaching Function

Table 9.4 Get the status of the hand-hold teaching function

Prototype int GetHHTTrigOutputEnabled (bool *isEnabled)

Description Get the status of the hand-hold teaching function

Parameter isEnabled: 0 : Disabled. 1 : Enabled

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Hand-Hold Teaching Trigger Single

Table 9.5 Get the hand-hold teaching trigger single

Prototype int GetHHTTrigOutput(bool *isTriggered)

Description Get the hand-hold teaching trigger single

Please call the SetHHTTrigOutputEnabled API before calling this API

Parameter isTriggered: 0: Not triggered. 1: Triggered

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Demo: Hand-Hold Teaching

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
23
 Dobot Magician API Description 9 HHT Function

Program 9.1 Hand-hold Teaching

#include "DobotDll.h"

#include <queue>

#include <windows.h>

int main(void)

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

SetHHTTrigMode(TriggeredOnPeriodicInterval);

SetHHTTrigOutputEnabled(true);

bool isTriggered = false;

queue<Pose> poseQueue;

Pose pose;

while(true) {

GetHHTTrigOutput(&isTriggered);

if(isTriggered) {

GetPose(&pose);

poseQueue.push(pose);

DisconnectDobot();

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
24
 Dobot Magician API Description 10 End-effector

End-effector

Setting the Offset of the End-effector

Table 10.1 Set the offset of the end-effector

Prototype int SetEndEffectorParams(EndEffectorParams *endEffectorParams, bool

isQueued, uint64_t *queuedCmdIndex)

Description Set the offset of the end-effector. If the end-effector is installed, this API is
required
If a standard end-effector is used, please refer to Dobot Magician User Guide
to obtain the X-axis offset and Y-axis offset and call this API. Otherwise,
please confirm the structural parameters.

Parameter EndEffectorParams:
typedef struct tagEndEffectorParams {
float xBias; //X-axis offset of end-effector
float yBias; //Y-axis offset of end-effector
float zBias; //Z-axis offset of end-effector
}EndEffectorParams;
endEffectorParams: EndEffectorParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Offset of the End-effector

Table 10.2 Get offset of end-effector

Prototype int GetEndEffectorParams(EndEffectorParams *endEffectorParams)

Description Get the offset of the end-effector

Parameter EndEffectorParams:
typedef struct tagEndEffectorParams {
float xBias; //X-axis offset of end-effector
float yBias; //Y-axis offset of end-effector
float zBias; //Z-axis offset of end-effector

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
25
 Dobot Magician API Description 10 End-effector

}EndEffectorParams;
endEffectorParams: EndEffectorParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Status of the Laser

Table 10.3 Set the status of the laser

Prototype int SetEndEffectorLaser(bool enableCtrl, bool on, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the status of the laser

Parameter enableCtrl: Control end-effector. 0: Disabled. 1: Enabled

on: Start or stop laser. 0, Off. 1, On
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Status of the Laser

Table 10.4 Get the status of the laser

Prototype int GetEndEffectorLaser(bool *isCtrlEnabled, bool *isOn)

Description Get the status of the laser

Parameter isCtrlEnabled: If the status of the end-effector is enabled. 0: Disabled. 1:

Enabled
isOn: If the status of the laser is on. 0, Off. 1, On

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Status of the Air Pump

Table 10.5 Set the status of the air pump

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
26
 Dobot Magician API Description 10 End-effector

Prototype int SetEndEffectorSuctionCup(bool enableCtrl, bool suck, bool isQueued,

uint64_t *queuedCmdIndex)

Description Set the status of the air pump

Parameter enableCtrl: Control end-effector. 0: Disabled. 1: Enabled

suck: Control the intake and outtake of the air pump. 0: Outtake. 1: Intake
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Status of the Air Pump

Table 10.6 Get the status of the air pump

Prototype int GetEndEffectorSuctionCup(bool *isCtrlEnabled, bool *isSucked)

Description Get the status of the air pump

Parameter isCtrlEnabled: If the status of the end-effector is enabled. 0: Disabled. 1:

Enabled
isSucked: If the status of the air pump is intake or outtake. 0: Outtake. 1:
Intake

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Status of the Gripper

Table 10.7 Set the status of the gripper

Prototype int SetEndEffectorGripper(bool enableCtrl, bool grip, bool isQueued,

uint64_t *queuedCmdIndex)

Description Set the status of the gripper

Parameter enableCtrl: Control end-effector. 0: Disabled. 1: Enabled

grip: Control the gripper to grip or release. 0: Released, 1: Grabbed
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
27
 Dobot Magician API Description 10 End-effector

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Status of the Gripper

Table 10.8 Get the status of the gripper

Prototype int GetEndEffectorGripper(bool *isCtrlEnabled, bool *isGripped)

Description Get the status of the gripper

Parameter isCtrlEnabled: If the status of the end-effector is enabled. 0: Disabled. 1:

Enabled
isGripped: If the status of the gripper is gripped or released. 0: Released. 1:
Grabbed

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
28
 Dobot Magician API Description 11 JOG

JOG
When doing jogging, the method calculating the velocity and acceleration for each axis (in
Joint or Cartesian coordinate system) is shown as follows.
 Actual jogging velocity = the set jogging velocity * the set jogging velocity rate
 Actual jogging acceleration = the set jogging acceleration* the set jogging acceleration
rate

Setting the Velocity and Acceleration of the Joint Coordinate Axis

when Jogging
Table 11.1 Set the velocity and acceleration of the joints coordinate axis when jogging

Prototype int SetJOGJointParams(JOGJointParams *jogJointParams, bool isQueued,

uint64_t *queuedCmdIndex)

Description Set the velocity(°/s) and acceleration (°/s2) of the joint coordinate axis
when jogging

Parameter JOGJointParams:
typedef struct tagJOGJointParams {
float velocity[4]; //Joint velocity
float acceleration[4]; //Joint acceleration
}JOGJointParams;
jogJointParams: JOGJointParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration of the Joint Coordinate Axis

when Jogging
Table 11.2 Get the velocity and acceleration of joint coordinate axis when jogging

Prototype int GetJOGJointParams(JOGJointParams *jogJointParams)

Description Get the velocity(°/s) and acceleration (°/s2) of the joint coordinate axis
when jogging

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
29
 Dobot Magician API Description 11 JOG

Parameter JOGJointParams:
typedef struct tagJOGJointParams {
float velocity[4]; //Joint velocity
float acceleration[4]; //Joint acceleration
}JOGJointParams;
jogJointParams: JOGJointParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the velocity and acceleration of the Cartesian Coordinate

Axis when Jogging
Table 11.3 Set the velocity and acceleration of the Cartesian coordinate axis when jogging

Prototype int SetJOGCoordinateParams(JOGCoordinateParams

*jogCoordinateParams, bool isQueued, uint64_t *queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) of the Cartesian coordinate

axis when jogging

Parameter JOGCoordinateParams:
typedef struct tagJOGCoordinateParams {
float velocity[4]; //Cartesian coordinate axis (X,Y,Z,R)velocity
float acceleration[4]; //Cartesian coordinate axis (X,Y,Z,R)
acceleration
}JOGCoordinateParams;
jogCoordinateParams: JOGCoordinateParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the velocity and acceleration of the Cartesian Coordinate

Axis when Jogging
Table 11.4 Get the velocity and acceleration of the Cartesian coordinate axis when jogging

Prototype int GetJOGCoordinateParams(JOGCoordinateParams

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
30
 Dobot Magician API Description 11 JOG

*jogCoordinateParams)

Description Get the velocity(mm/s) and acceleration(mm/s2) of the Cartesian coordinate

axis when jogging

Parameter typedef struct tagJOGCoordinateParams {

float velocity[4]; //Cartesian coordinate axis (X,Y,Z,R)velocity
float acceleration[4]; //Cartesian coordinate axis (X,Y,Z,R)
acceleration
}JOGCoordinateParams;
jogCoordinateParams: JOGCoordinateParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the velocity and acceleration of the Sliding Rail when

Jogging
Table 11.5 Set the velocity and acceleration of the sliding rail when jogging

Prototype int SetJOGLParams(JOGLParams *jogLParams, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) of the sliding rail when
jogging

Parameter JOGLParams:
typedef struct tagJOGLParams {
float velocity; //Sliding rail velocity
float acceleration; //Sliding rail acceleration
}JOGLParams;
jogLParams: JOGLParams
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid.

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the velocity and acceleration of the Sliding Rail when

Jogging
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
31
 Dobot Magician API Description 11 JOG

Table 11.6 Get the velocity and acceleration of the sliding rail when jogging

Prototype int GetJOGLParams(JOGLParams * jogLParams )

Description Get the velocity(mm/s) and acceleration(mm/s2) of the sliding rail when
jogging

Parameter JOGLParams:
typedef struct tagJOGLParams {
float velocity; //Sliding rail velocity
float acceleration; //Sliding rail acceleration
}JOGLParams;
jogLParams: JOGLParams

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Velocity Ratio and Acceleration Ratio when Jogging

Table 11.7 Set the velocity ratio and acceleration ratio when jogging

Prototype int SetJOGCommonParams(JOGCommonParams *jogCommonParams,

bool isQueued, uint64_t *queuedCmdIndex)

Description Set the velocity ratio and acceleration ratio for each axis (in both Joint and
Cartesian coordinate system) when jogging

Parameter JOGCommonParams:
typedef struct tagJOGCommonParams {
float velocityRatio; //Velocity ratio
float accelerationRatio; //Acceleration ratio
}JOGCommonParams;
jogCommonParams: JOGCommonParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
32
 Dobot Magician API Description 11 JOG

Getting the Velocity Ratio and Acceleration Ratio when Jogging

Table 11.8 Get the velocity ratio and acceleration ratio when jogging

Prototype int GetJOGCommonParams(JOGCommonParams *jogCommonParams)

Description Get the velocity ratio and acceleration ratio for each axis (in Joint and
Cartesian coordinate system) when jogging

Parameter JOGCommonParams:
typedef struct tagJOGCommonParams {
float velocityRatio; //Velocity ratio
float accelerationRatio; //Acceleration ratio
}JOGCommonParams;
jogCommonParams: JOGCommonParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in
a timeout

Executing the Jogging Command

Table 11.9 Execute the Jogging command

Prototype int SetJOGCmd(JOGCmd *jogCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the Jogging command. Please call this API after setting the related
parameters of jogging

Parameter JOGCmd:
typedef struct tagJOGCmd {
uint8_t isJoint; //Jogging mode: 0, Jog in Cartesian coordinate
system. 1, Jog in Joint coordinate system
uint8_t cmd; //Jogging command: 0-10
}JOGCmd;
//Details for jogging commands
enum {
IDLE, // Idle
AP_DOWN, // X+/Joint1+
AN_DOWN, // X-/Joint1-
BP_DOWN, // Y+/Joint2+
BN_DOWN, // Y-/Joint2-
CP_DOWN, // Z+/Joint3+
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
33
 Dobot Magician API Description 11 JOG

CN_DOWN, // Z-/Joint3-
DP_DOWN, // R+/Joint4+
DN_DOWN, // R-/Joint4-
LP_DOWN, // L+. Only when the parameter isJoint=1, the LP_DOWN
is available
LN_DOWN // L-. Only when the parameter isJoint=1, the LN_DOWN
is available
};
jogCmd: JOGCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
34
 Dobot Magician API Description 12 PTP

PTP
PTP mode supports MOVJ, MOVL, and JUMP, which is point-to-point movement. The
trajectory of playback depends on the motion mode.
 MOVJ: Joint movement. From point A to point B, each joint will run from initial angle to
its target angle, regardless of the trajectory, as shown in Figure 12.1.

Figure 12.1 MOVL/MOVJ mode

 MOVL: Rectilinear movement. The joints will perform a straight line trajectory from
point A to point B, as shown in Figure 12.1.
 JUMP: From point A to point B, the trajectory is shown in Figure 12.2., the end effector
will lift upwards by amount of Height (in mm) and move horizontally to a point that
is above B by Height and then move down to Point B.

Figure 12.2 JUMP mode

When doing playback, the method calculating the velocity and acceleration for each axis (in
Joint or Cartesian coordinate system) is shown as follows.
 Actual playback velocity = the set playback velocity * the set playback velocity rate
 Actual playback acceleration = the set playback acceleration* the set playback
acceleration rate

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
35
 Dobot Magician API Description 12 PTP

Setting the Velocity and Acceleration of the Joint Coordinate Axis

in PTP Mode
Table 12.1 Set the velocity and acceleration of the joint coordinate axis in PTP mode

Prototype int SetPTPJointParams(PTPJointParams *ptpJointParams, bool isQueued,

uint64_t *queuedCmdIndex)

Description Set the velocity(°/s) and acceleration(°/s2) of the joint coordinate axis in
PTP mode

Parameter PTPJointParams:
typedef struct tagPTPJointParams {
float velocity[4]; // Joint velocity in PTP mode
float acceleration[4]; //Joint acceleration in PTP mode
}PTPJointParams;
ptpJointParams: PTPJointParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration of the Joint Coordinate Axis

in PTP Mode
Table 12.2 Get the velocity and acceleration of the joint coordinate axis in PTP mode

Prototype int GetPTPJointParams(PTPJointParams *ptpJointParams)

Description Get the velocity(°/s) and acceleration(°/s2) of the joint coordinate axis in
PTP mode

Parameter PTPJointParams
typedef struct tagPTPJointParams {
float velocity[4]; //Joint velocity in PTP mode
float acceleration[4]; //Joint acceleration in PTP mode
}PTPJointParams;
ptpJointParams: PTPJointParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
36
 Dobot Magician API Description 12 PTP

timeout

Setting the Velocity and Acceleration of the Cartesian Coordinate

Axis in PTP Mode
Table 12.3 Set the velocity and acceleration of the Cartesian coordinate axis in PTP mode

Prototype int SetPTPCoordinateParams(PTPCoordinateParams

*ptpCoordinateParams, bool isQueued, uint64_t *queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) of the Cartesian coordinate

axis in PTP mode

Parameter PTPCoordinateParams:
typedef struct tagPTPCoordinateParams {
float xyzVelocity; //Cartesian coordinate axis (X,Y,Z) velocity
float rVelocity; // Cartesian coordinate axis (R) velocity
float xyzAcceleration; //Cartesian coordinate axis (X,Y,Z)
acceleration
float rAcceleration; //Cartesian coordinate axis (R) acceleration
}PTPCoordinateParams;
ptpCoordinateParams: PTPCoordinateParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration of the Cartesian Coordinate

Axis in PTP Mode
Table 12.4 Get the velocity and acceleration of the Cartesian coordinate axis in PTP mode

Prototype int GetPTPCoordinateParams(PTPCoordinateParams

*ptpCoordinateParams)
Description Get the velocity(mm/s) and acceleration(mm/s2) of the Cartesian coordinate
axis in PTP mode

Parameter PTPCoordinateParams:
typedef struct tagPTPCoordinateParams {

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
37
 Dobot Magician API Description 12 PTP

float xyzVelocity; //Cartesian coordinate axis (X,Y,Z) velocity

float rVelocity; // Cartesian coordinate axis (R) velocity
float xyzAcceleration; //Cartesian coordinate axis (X,Y,Z)
acceleration
float rAcceleration; //Cartesian coordinate axis (R) acceleration
}PTPCoordinateParams;
ptpCoordinateParams: PTPCoordinateParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Lifting Height and the Maximum Lifting Height in JUMP
mode
Table 12.5 Set the lifting height and the maximum lifting height in JUMP mode

Prototype int SetPTPJumpParams(PTPJumpParams *ptpJumpParams, bool isQueued,

uint64_t *queuedCmdIndex)

Description Set the lifting height and the maximum height in JUMP mode

Parameter PTPJumpParams:
typedef struct tagPTPJumpParams {
float jumpHeight; //Lifting height
float zLimit; //Maximum lifting height
}PTPJumpParams;
ptpJumpParams: PTPJumpParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Lifting Height and the Maximum Lifting Height in JUMP
mode
Table 12.6 Get the lifting height and the maximum lifting height in JUMP mode

Prototype int GetPTPJumpParams(PTPJumpParams *ptpJumpParams)

Description Get the lifting height and the maximum lifting height in JUMP mode

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
38
 Dobot Magician API Description 12 PTP

Parameter PTPJumpParams:
typedef struct tagPTPJumpParams {
float jumpHeight; //Lifting height
float zLimit; //Maximum lifting height
}PTPJumpParams;
ptpJumpParams: PTPJumpParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Extended Parameters in JUMP mode

Table 12.7 Set the extended parameters in JUMP mode

Prototype int SetPTPJump2Params(PTPJumpParams *ptpJump2Params, bool

isQueued, uint64_t *queuedCmdIndex)

Description Set the extended parameters in JUMP mode

Parameter PTPJump2Params:
typedef struct tagPTPJump2Params {
float startJumpHeight; //Lifting height of starting point
float endJumpHeight; //Lifting height of end point
float zLimit; //Maximum lifting height
}PTPJump2Params;
ptpJump2Params: PTPJump2Params pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Extended Parameters in JUMP mode

Table 12.8 Get extended parameters in JUMP mode

Prototype int GetPTPJump2Params(PTPJumpParams *ptpJump2Params)

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
39
 Dobot Magician API Description 12 PTP

Description Get the extended parameters in JUMP mode

Parameter PTPJump2Params:
typedef struct tagPTPJump2Params {
float startJumpHeight; //Lifting height of starting point
float endJumpHeight; //Lifting height of end point
float zLimit; //Maximum lifting height
}PTPJump2Params;

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Velocity and Acceleration of the Sliding Rail in PTP

Mode
Table 12.9 Set the velocity and acceleration of the sliding rail in PTP mode

Prototype int SetPTPLParams(PTPLParams * ptpLParams, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) of the sliding rail in PTP
mode

Parameter PTPLParams:
typedef struct tagPTPJointParams {
float velocity; //Sliding rail velocity in PTP mode
float acceleration; //Sliding rail acceleration in PTP mode
}PTPLParams;
ptpLParams: PTPLParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration of the Sliding rail in PTP

Mode
Table 12.10 Get the velocity and acceleration of the Sliding rail s in PTP mode

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
40
 Dobot Magician API Description 12 PTP

Prototype int GetPTPLParams(PTPLParams *ptpLParams)

Description Get the velocity(mm/s) and acceleration(mm/s2) of the sliding rail in PTP
mode

Parameter PTPLParams:
typedef struct tagPTPJointParams {
float velocity; //Sliding rail velocity in PTP mode
float acceleration; //Sliding rail acceleration in PTP mode
}PTPLParams;
ptpLParams: PTPLParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Velocity Ratio and Acceleration Ratio in PTP Mode

Table 12.11 Set the velocity ratio and the acceleration ratio in PTP mode

Prototype int SetPTPCommonParams(PTPCommonParams *ptpCommonParams, bool

isQueued, uint64_t *queuedCmdIndex)

Description Set the velocity ratio and acceleration ratio in PTP mode

Parameter PTPCommonParams:
typedef struct tagPTPCommonParams {
float velocityRatio; //Velocity ratio
float accelerationRatio; //Acceleration ratio
}PTPCommonParams;
ptpCommonParams: PTPCommonParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity Ratio and Acceleration Ratio in PTP Mode

Table 12.12 Get the velocity ratio and acceleration ratio in PTP mode

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
41
 Dobot Magician API Description 12 PTP

Prototype int GetPTPCommonParams(PTPCommonParams *ptpCommonParams)

Description Get the velocity ratio and acceleration ratio in PTP mode

Parameter PTPCommonParams:
typedef struct tagPTPCommonParams {
float velocityRatio; //Velocity ratio
float accelerationRatio; //Acceleration ratio
}PTPCommonParams;
ptpCommonParams: PTPCommonParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing a PTP Command

Table 12.13 Execute a PTP command

Prototype int SetPTPCmd(PTPCmd *ptpCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute a PTP command. Please call this API after setting the related
parameters in PTP mode to make the Dobot move to the target point

Parameter PTPCmd:
typedef struct tagPTPCmd {
uint8_t ptpMode; //PTP mode (0-9)
float x; //Coordinate parameters in PTP mode. (x,y,z,r)
can be set to Cartesian coordinate, joints
angle, or increment of them
float y;
float z;
float r;
}PTPCmd;
Details for ptpMode:
enum {
JUMP_XYZ, //JUMP mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVJ_XYZ, //MOVJ mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVL_XYZ, //MOVL mode, (x,y,z,r) is the target point in
Cartesian coordinate system
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
42
 Dobot Magician API Description 12 PTP

JUMP_ANGLE, //JUMP mode, (x,y,z,r) is the target point in

Joint coordinate system
MOVJ_ANGLE, //MOVJ mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVL_ANGLE, //MOVL mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_INC, //MOVJ mode, (x,y,z,r) is the angle increment
in Joint coordinate system
MOVL_INC, //MOVL mode, (x,y,z,r) is the Cartesian
coordinate increment in Joint coordinate
system
MOVJ_XYZ_INC, //MOVJ mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
JUMP_MOVL_XYZ, //JUMP mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
};
ptpCmd: PTPCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing a PTP Command with the I/O Control

Table 12.14 Execute a PTP command with the I/O control

Prototype int SetPTPPOCmd(PTPCmd *ptpCmd, ParallelOutputCmd *parallelCmd,

int parallelCmdCount, bool isQueued, uint64_t *queuedCmdIndex)
Description Execute a PTP command with the I/O control. You can control the suction
cup or gripper by I/O control. For more details on the I/O description, please
see Dobot Magician User Guide

Parameter PTPCmd:
typedef struct tagPTPCmd {
uint8_t ptpMode; //PTP mode (0-9)
float x; //Coordinate parameters in PTP mode. (x,y,z,r)

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
43
 Dobot Magician API Description 12 PTP

can be set to Cartesian coordinate, joints

angle, or increment of them
float y;
float z;
float r;
}PTPCmd;
Details for ptpMode:
enum {
JUMP_XYZ, //JUMP mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVJ_XYZ, //MOVJ mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVL_XYZ, //MOVL mode, (x,y,z,r) is the target point in
Cartesian coordinate system
JUMP_ANGLE, //JUMP mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_ANGLE, //MOVJ mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVL_ANGLE, //MOVL mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_INC, //MOVJ mode, (x,y,z,r) is the angle increment
in Joint coordinate system
MOVL_INC, //MOVL mode, (x,y,z,r) is the Cartesian
coordinate increment in Joint coordinate
system
MOVJ_XYZ_INC, //MOVJ mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
JUMP_MOVL_XYZ, //JUMP mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
};
ParallelOutputCmd:
typedef struct tagParallelOutputCmd {
uint8_t ratio; //The distance ratio between the two points in
PTP mode, namely, the position where I/O
is triggered
uint16_t address; //I/O address (0-20)
uint8_t level; //Output value

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
44
 Dobot Magician API Description 12 PTP

}ParallelOutputCmd;
ptpCmd: PTPCmd pointer
parallelCmd: ParallelOutputCmd pointer
parallelCmdCount::I/O number
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing a PTP Command with the Sliding Rail

Table 12.15 Execute a PTP command with the sliding rail

Prototype int SetPTPWithLCmd(PTPWithLCmd *ptpWithLCmd, bool isQueued,

uint64_t *queuedCmdIndex)

Description Execute a PTP command with the sliding rail

Parameter PTPWithLCmd
typedef struct tagPTPWithL {
uint8_t ptpMode; //PTP mode (0-9)
float x; //Coordinate parameters in PTP mode. (x,y,z,r)
can be set to Cartesian coordinate, joints
angle, or increment of them
float y;
float z;
float r;
float l; //The distance that sliding rail moves
}PTPWithLCmd ;
Details for ptpMode:
enum {
JUMP_XYZ, //JUMP mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVJ_XYZ, //MOVJ mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVL_XYZ, //MOVL mode, (x,y,z,r) is the target point in
Cartesian coordinate system
JUMP_ANGLE, //JUMP mode, (x,y,z,r) is the target point in
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
45
 Dobot Magician API Description 12 PTP

Joint coordinate system

MOVJ_ANGLE, //MOVJ mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVL_ANGLE, //MOVL mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_INC, //MOVJ mode, (x,y,z,r) is the angle increment
in Joint coordinate system
MOVL_INC, //MOVL mode, (x,y,z,r) is the Cartesian
coordinate increment in Joint coordinate
system
MOVJ_XYZ_INC, //MOVJ mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
JUMP_MOVL_XYZ, //JUMP mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
};
ptpWithLCmd : PTPWithLCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing a PTP Command with the Sliding Rail and I/O Control
Table 12.16 Execute a PTP command with the sliding rail and I/O control

Prototype int SetPTPPOWithLCmd(PTPWithLCmd *ptpWithLCmd,

ParallelOutputCmd *parallelCmd, int parallelCmdCount, bool isQueued,
uint64_t *queuedCmdIndex)

Description Execute a PTP command with the sliding rail and I/O control

Parameter PTPWithLCmd
typedef struct tagPTPWithL {
uint8_t ptpMode; //PTP mode (0-9)
float x; //Coordinate parameters in PTP mode. (x,y,z,r)
can be set to Cartesian coordinate, joints
angle, or increment of them
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
46
 Dobot Magician API Description 12 PTP

float y;
float z;
float r;
float l; //The distance that sliding rail moves
}PTPWithLCmd;
Details for ptpMode:
enum {
JUMP_XYZ, //JUMP mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVJ_XYZ, //MOVJ mode, (x,y,z,r) is the target point in
Cartesian coordinate system
MOVL_XYZ, //MOVL mode, (x,y,z,r) is the target point in
Cartesian coordinate system
JUMP_ANGLE, //JUMP mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_ANGLE, //MOVJ mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVL_ANGLE, //MOVL mode, (x,y,z,r) is the target point in
Joint coordinate system
MOVJ_INC, //MOVJ mode, (x,y,z,r) is the angle increment
in Joint coordinate system
MOVL_INC, //MOVL mode, (x,y,z,r) is the Cartesian
coordinate increment in Joint coordinate
system
MOVJ_XYZ_INC, //MOVJ mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
JUMP_MOVL_XYZ, //JUMP mode, (x,y,z,r) is the Cartesian
coordinate increment in Cartesian
coordinate system
};
ParallelOutputCmd:
typedef struct tagParallelOutputCmd {
uint8_t ratio; //The distance ratio between the two points in
PTP mode, namely, the position where I/O
is triggered
uint16_t address; //I/O address (0-20)
uint8_t level; //Output value
}ParallelOutputCmd;

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
47
 Dobot Magician API Description 12 PTP

ptpWithLCmd : PTPWithLCmd pointer

parallelCmd: ParallelOutputCmd pointer
parallelCmdCount: I/O number
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
48
 Dobot Magician API Description 13 CP

CP
CP: Continuous Path.

Setting the Velocity and Acceleration in CP Mode

Table 13.1 Set the velocity and acceleration in CP mode

Prototype int SetCPParams(CPParams *cpParams, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) in CP mode

Parameter CPParams
typedef struct tagCPParams {
float planAcc; //The maximum planning acceleration
float junctionVel; //The maximum junction velocity
union {
float acc; //The maximum actual acceleration. It is
valid only when realTimeTrack is set to
0
float period; //Interpolation period. It is valid only when
realTimeTrack is set to 1
};
uint8_t realTimeTrack; //0: Non-real-time mode, all commands will
be executed after they are issued. 1: Real-
time mode, the command is executed while
being issued.
}CPParams;
cpParams: CPParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration in CP Mode

Table 13.2 Get the velocity and acceleration in CP mode

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
49
 Dobot Magician API Description 13 CP

Prototype int GetCPParams(CPParams *cpParams)

Description Get the velocity(mm/s) and acceleration(mm/s2) in CP mode

Parameter CPParams
typedef struct tagCPParams {
float planAcc; //The maximum planning acceleration
float junctionVel; //The maximum junction velocity
union {
float acc; //The maximum actual acceleration. It is
valid only when realTimeTrack is set to
0
float period; //Interpolation period. It is valid only when
realTimeTrack is set to 1
};
uint8_t realTimeTrack; //0: Non-real-time mode, all commands will
be executed after they are issued. 1: Real-
time mode, the command is executed while
being issued.
}CPParams;
cpParams: CPParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the CP Command

Table 13.3 Execute the CP command

Prototype int SetCPCmd(CPCmd *cpCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the CP commands

Parameter CPCmd
typedef struct tagCPCmd {
uint8_t cpMode; //CP mode. 0: indicate that (x,y,z) is the
Cartesian coordinate increment. 1:indicate
(x,y,z) is the target point in Cartesian
coordinate system
float x; //(x,y,z )can be set to Cartesian coordinate,
or Cartesian coordinate increment

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
50
 Dobot Magician API Description 13 CP

float y;
float z;
union {
float velocity; //Reserved
float power; //Reserved
}CPCmd;
cpCmd: CPCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

NOTICE

When there are multiple CP commands in the command queue, the Dobot controller will
look ahead automatically. The look-ahead condition is that there are no JOG, PTP, ARC,
WAIT, and TRIG commands between the CP commands.

Executing the CP Command with the Laser Engraving

Table 13.4 Execute the CP command with laser engraving

Prototype int SetCPLECmd(CPCmd *cpCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the CP command with the laser engraving.

Parameter typedef struct tagCPCmd {

uint8_t cpMode; //CP mode. 0: indicate that (x,y,z) is the
Cartesian coordinate increment. 1:indicate
(x,y,z) is the target point in Cartesian
coordinate system
float x; //(x,y,z )can be set to Cartesian coordinate,
or Cartesian coordinate increment
float y;
float z;
union {
float velocity; // Reserved

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
51
 Dobot Magician API Description 13 CP

float power; //Laser power 0-100

}CPCmd;

cpCmd: CPCmd pointer

isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
52
 Dobot Magician API Description 14 ARC

ARC
The trajectory of the Dobot in ARC mode is an arc, which is determined by three points (the
current point, any point and the end point on the arc), as shown in Figure 14.1.

Figure 14.1 ARC mode

Setting the Velocity and Acceleration in ARC Mode

Table 14.1 Set the velocity and acceleration in ARC mode

Prototype int SetARCParams(ARCParams *arcParams, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity(mm/s) and acceleration(mm/s2) in PTP mode

Parameter ARCParams
typedef struct tagARCParams {
float xyzVelocity; //Cartesian coordinate axis (X,Y,Z) velocity
float rVelocity; //Cartesian coordinate axis (R) velocity
float xyzAcceleration; //Cartesian coordinate axis (X,Y,Z)
acceleration
float rAcceleration; //Cartesian coordinate axis (R) acceleration
}ARCParams;
arcParams: ARCParams pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Velocity and Acceleration in ARC Mode

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
53
 Dobot Magician API Description 14 ARC

Table 14.2 Get the velocity and acceleration in ARC mode

Prototype int GetARCParams(ARCParams *arcParams)

Description Get the velocity(mm/s) and acceleration(mm/s2) in ARC mode

Parameter ARCParams
typedef struct tagARCParams {
float xyzVelocity; //Cartesian coordinate axis (X,Y,Z) velocity
float rVelocity; //Cartesian coordinate axis (R) velocity
float xyzAcceleration; //Cartesian coordinate axis (X,Y,Z)
acceleration
float rAcceleration; //Cartesian coordinate axis (R) acceleration
}ARCParams;
arcParams: ARCParams pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the ARC Command

Table 14.3 Execute the ARC command

Prototype int SetARCCmd(ARCCmd *arcCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the ARC command. Please call this API after setting the related
parameters in ARC mode to make Dobot move to the target point.
In ARC mode, it is necessary to confirm the three points with other motion
modes.

Parameter ARCCmd:
typedef struct tagARCCmd {
struct {
float x;
float y;
float z;
float r;
}cirPoint ; //Middle point. (x,y,z,r) can be set to
Cartesian coordinate
struct {
float x;

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
54
 Dobot Magician API Description 14 ARC

float y;
float z;
float r;
}toPoint; //End point. (x,y,z,r) can be set to
Cartesian coordinate
}ARCCmd;
arcCmd: ARCCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the CIRCLE Command

The CIRCLE mode is similar to the ARC mode, where the trajectory is a circle.

Table 14.4 Execute the CIRCLE command

Prototype int SetCircleCmd(CircleCmd *circleCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the CIRCLE command. Please call this API after setting the related
parameters of playback in CIRCLE mode to make Dobot move to the target
point.
In CIRCLE mode, it is necessary to confirm the three points with other
motion modes.

Parameter CircleCmd
typedef struct tagCircleCmd {
struct {
float x;
float y;
float z;
float r;
}cirPoint ; //Middle point.(x,y,z,r) can be set to
Cartesian coordinate
struct {
float x;
float y;
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
55
 Dobot Magician API Description 14 ARC

float z;
float r;
}toPoint; //End point. (x,y,z,r) can be set to
Cartesian coordinate
uint32_t count //Circle number
}CircleCmd;
circleCmd: CircleCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
56
 Dobot Magician API Description 15 Losing-Step Detection

Losing-Step Detection

Setting the losing-step threshold

Table 15.1 Set the losing-step threshold

Prototype int SetLostStepParams(float threshold, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the losing-step threshold, checking for whether the position error exceeds
this threshold. If this threshold is exceeded, the motor loses step
If you do not call this API, the default threshold is 5

Parameter threshold: Losing-step threshold

isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Executing the Losing-Step Command

Table 15.2 Execute the losing-step command

Prototype int SetLostStepCmd(bool isQueued, uint64_t *queuedCmdIndex)

Description Execute the losing-step command. If the motor loses step, the Dobot
controller will stop to query the command queue and stop executing
commands.
This command must be added to the command queue, namely, isQueued
must be set to 1.

Parameter isQueued: Whether to add this command to the queue

queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Demo: Executing the Losing-Step Command

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
57
 Dobot Magician API Description 15 Losing-Step Detection

Program 15.1 Execute the losing-step command

#include "DobotDll.h"

int main(void)

PTPCmd cmd;

cmd.ptpMode = 0;

cmd.x = 200;

cmd.y = 0;

cmd.z = 0;

cmd.r = 0;

ConnectDobot(NULL, 115200, NULL, NULL, NULL);

SetQueuedCmdStartExec();

SetPTPCmd(&cmd, true, &queuedCmdIndex);

SetLostStepCmd(true, &queuedCmdIndex)

SetQueuedCmdStopExec();

DisconnectDobot();

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
58
 Dobot Magician API Description 16 WAITING

WAITING

Executing the Waiting Command

Table 16.1 Execute the Waiting command

Prototype int SetWAITCmd(WAITCmd *waitCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the Waiting command. If you need to set the pause time between the
two commands, please call this API
This command must be added to the command queue, namely, isQueued
must be set to 1. If not, the parameter timeout of Waiting command in the
command queue being executed may be changed because the WAITCmd
memory is shared

Parameter WAITCmd:
typedef struct tagWAITCmd {
uint32_t timeout; //Unit:ms
}WAITCmd;
waitCmd: WAITCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
59
 Dobot Magician API Description 17 TRIGGERING

TRIGGERING

Executing the Triggering Command

Table 17.1 Execute the Triggering command

Prototype int SetTRIGCmd(TRIGCmd *trigCmd, bool isQueued, uint64_t

*queuedCmdIndex)

Description Execute the triggering command.

This command must be added to the command queue, namely, isQueued
must be set to 1. If not, the parameter condition of the Triggering command
in the queue command being executed may be changed because the
TRIGCmd memory is shared

Parameter TRIGCmd:
typedef struct tagTRIGCmd {
uint8_t address; // EIO address:1-20
uint8_t mode; //Triggering mode. 0: Level
trigger.1:A/D trigger
uint8_t condition; //Triggering condition
Level: 0, equal. 1, unequal
A/D: 0, less than. 1,less than or equal
2, greater than or equal. 3, greater
than
uint16_t threshold; //Triggering threshold. Level : 0,1 .A/D:
0-4095
}TRIGCmd;
trigCmd: TRIGCmd pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
60
 Dobot Magician API Description 18 EIO

EIO
In the Dobot controller, the addresses of the I/O interfaces are unified. Here, you can see as
follows:
 High-low level output;
 PWM output;
 Read High-low level output;
 Read analog-digital conversion value output.
Some of the I/Os may have all the functions listed above. You need configure I/O multiplexing
when using different functions. For more details, please see Dobot Magician User Guide.

Setting the I/O Multiplexing

Table 18.1 Set the I/O multiplexing

Prototype int SetIOMultiplexing(IOMultiplexing *ioMultiplexing, bool isQueued,

uint64_t *queuedCmdIndex)
Description Sets the I/O multiplexing. When using any I/O interface, you need to call
this API to set the I/O multiplexing
Parameter IOMultiplexing:
typedef struct tagIOMultiplexing {
uint8_t address; //I/O address:1-20
uint8_t multiplex; //I/O multiplexing function: 0-6
}IOMultiplexing;
The values supported by multiplex are shown as follows:
typedef enum tagIOFunction {
IOFunctionDummy; //Invalid
IOFunctionDO; // I/O output
IOFunctionPWM; // PWM output
IOFunctionDI; //I/O input
IOFunctionADC; //A/D input
IOFunctionDIPU; //Pull-up input
IOFunctionDIPD //Pull-down input
}IOFunction;
ioMultiplexing: IOMultiplexing pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
61
 Dobot Magician API Description 18 EIO

DobotCommunicate_Timeout: The command does not return, resulting in a

timeout

Getting the I/O multiplexing

Table 18.2 Getting the I/O multiplexing

Prototype int GetIOMultiplexing(IOMultiplexing *ioMultiplexing)

Description Get the I/O multiplexing

Parameter IOMultiplexing:
typedef struct tagIOMultiplexing {
uint8_t address; //I/O address
uint8_t multiplex; //I/O multiplexing function: 0-6
}IOMultiplexing;
The values supported by multiplex are as follows.
typedef enum tagIOFunction {
IOFunctionDummy; //Invalid
IOFunctionDO; // I/O output
IOFunctionPWM; // PWM output
IOFunctionDI; //I/O input
IOFunctionADC; //A/D input
IOFunctionDIPU; //Pull-up input
IOFunctionDIPD //Pull-down input
}IOFunction;
ioMultiplexing: IOMultiplexing pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the I/O Output

Table 18.3 Set the I/O output

Prototype int SetIODO(IODO *ioDO, bool isQueued, uint64_t *queuedCmdIndex)

Description Set the I/O output

Parameter IODO:
typedef struct tagIODO {
uint8_t address; //I/O addres

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
62
 Dobot Magician API Description 18 EIO

uint8_t level; //0: Low level.1: High level

}IODO;
ioDO: IODO pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the I/O Output

Table 18.4 Get the I/O output

Prototype int GetIODO(IODO *ioDO)

Description Get the I/O output

Parameter IODO:
typedef struct tagIODO {
uint8_t address; //I/O addres
uint8_t level; //0: Low level.1: High level
}IODO;
ioDO: IODO pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the PWM Output

Table 18.5 Set PWM output

Prototype int SetIOPWM(IOPWM *ioPWM, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the PWM output

Parameter IOPWM:
typedef struct tagIOPWM {
uint8_t address; //I/O address
float frequency; // PWM frequency: 10Hz-1MHz

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
63
 Dobot Magician API Description 18 EIO

float dutyCycle; // PWM duty cycle: 0-100

}IOPWM;
ioPWM: IOPWM pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the PWM Output

Table 18.6 Get the PWM output

Prototype int GetIOPWM(IOPWM *ioPWM)

Description Get the PWM output

Parameter IOPWM:
typedef struct tagIOPWM {
uint8_t address; //I/O address
float frequency; // PWM frequency: 10Hz-1MHz
float dutyCycle; // PWM duty cycle: 0-100
}IOPWM;
ioPWM: IOPWM pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the I/O Input

Table 18.7 Get the I/O input

Prototype int GetIODI(IODI *ioDI)

Description Get the I/O input

Parameter IODI:
typedef struct tagIODI {
uint8_t address; //I/O address
uint8_t level; //0: Low level. 1: High-level

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
64
 Dobot Magician API Description 18 EIO

}IODI;
ioDI: IODO pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the A/D Input

Table 18.8 Get the A/D Input

Prototype int GetIOADC(IOADC *ioADC)

Description Get the A/D input

Parameter IOADC:
typedef struct tagIOADC {
uint8_t address; //I/O address
uint16_t value; //Input value:0-4095
}IOADC;
ioADC: IOADC pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Velocity of the Extended Motor

Table 18.9 Set the velocity of the extended motor

Prototype int SetEMotor(EMotor *eMotor, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity of the extended motor. The motor will always be operated at
a constant velocity after calling this API

Parameter EMotor:
typedef struct tagEMotor {
uint8_t index; //Motor index. 0: Stepper1. 1:Stepper2
uint8_t isEnabled; //Control motor. 0: Disabled. 1: Enabled
uint32_t speed; //Motor velocity (Pulse number per second)
}EMotor;
eMotor: EMotor pointer
isQueued: Whether to add this command to the queue

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
65
 Dobot Magician API Description 18 EIO

queuedCmdIndex: If this command is added to the queue, queuedCmdIndex

indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Velocity of the Extended Motor and the Movement

Distance
Table 18.10 Set the velocity of extended motor and the movement distance

Prototype int SetEMotorS(EMotorS *eMotorS, bool isQueued, uint64_t

*queuedCmdIndex)

Description Set the velocity of the extended motor and the movement distance. The Dobot
will move for some distance at a constant velocity after calling this API

Parameter EMotorS:
typedef struct tagEMotorS{
uint8_t index; //Motor index. 0: Stepper1. 1:Stepper2
uint8_t isEnabled; //Control motor. 0: Disabled. 1: Enabled
uint32_t speed; //Motor velocity (Pulse number per second)
uint32_t distance //Movement distance (Pulse number)
}EMotorS;
eMotorS: EMotorS pointer
isQueued: Whether to add this command to the queue
queuedCmdIndex: If this command is added to the queue, queuedCmdIndex
indicates the index of this command in the queue. Otherwise, it is invalid

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_BufferFull: The command queue is full
DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Enabling the Photoelectric Sensor

Table 18.11 Enable the photoelectric sensor

Prototype int SetInfraredSensor(bool enable,InfraredPort infraredPort, uint8_t version)

Description Enable the photoelectric sensor

Parameter InfraredPort:

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
66
 Dobot Magician API Description 18 EIO

enum InfraredPort {
IF_PORT_GP1;
IF_PORT_GP2;
IF_PORT_GP4;
IF_PORT_GP5;
};
enable: 0, Disabled. 1, Enabled
infraredPort: The Dobot interface that the photoelectric sensor is connected
to. Please select the corresponding interface
version: Version flag of photoelectric sensor. 0: The version is V 1.0. 1: The
version is V2.0

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Photoelectric Sensor Value

Table 18.12 Get the photoelectric sensor value

Prototype int GetInfraredSensor (InfraredPort infraredPort, uint8_t *value)

Description Get the photoelectric sensor value

Parameter InfraredPort:
enum InfraredPort {
IF_PORT_GP1;
IF_PORT_GP2;
IF_PORT_GP4;
IF_PORT_GP5;
};
infraredPort: The Dobot interface that the photoelectric sensor is connected
to. Please select the corresponding interface
value: The value of the photoelectric sensor

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Enabling the Color Sensor

Table 18.13 Enable the color sensor

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
67
 Dobot Magician API Description 18 EIO

Prototype int SetColorSensor(bool enable, ColorPort colorPort, uint8_t version)

Description Enable the color sensor

Parameter ColorPort:
enum ColorPort {
IF_PORT_GP1;
IF_PORT_GP2;
IF_PORT_GP4;
IF_PORT_GP5;
};
enable: 0, Disabled. 1, Enabled
colorPort: The Dobot interface that the color sensor is connected to. Please
select the corresponding interface
version: Version flag of color sensor. 0: The version is V1.0. 1: The version
is V2.0

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Color Sensor Value

Table 18.14 Get the color sensor value

Prototype int GetColorSensor( uint8_t *r, uint8_t *g, uint8_t *b )

Description Get the color sensor value

Parameter r: Red. The range is: 0-255

g: Green. The range is: 0-255
b: Blue. The range is: 0-255

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
68
 Dobot Magician API Description 19 CAL

CAL
The Angle sensors on the Forearm and Rear Arm may have static errors due to angle sensor
welding, device status, etc. It is possible to get this static error through various means (such as
leveling, compared with the standard source), and write into the device through this API.
Forearm/Rear Arm angle = angle sensor static error of Forearm/Rear Arm + angle senor value
of Forearm/Rear Arm *Linearization parameter of Forearm/Rear Arm angle sensor
Base angle = Static error of Base Encoder + Base Encoder value

Setting the Angle Sensor Static Error

Table 19.1 Set the angle sensor static error

Prototype int SetAngleSensorStaticError(float rearArmAngleError, float

frontArmAngleError)

Description Set the angle sensor static errors of Forearm and Rear Arm

Parameter rearArmAngleError: The angle sensor static error of the Rear Arm
frontArmAngleError: The angle sensor static error of the Forearm

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Angle Sensor Static Error

Table 19.2 Get the angle sensor static error

Prototype int GetAngleSensorStaticError(float *rearArmAngleError, float

*frontArmAngleError)

Description Get the angle sensor static errors of the Forearm and Rear Arm

Parameter rearArmAngleError: The angle sensor static error of the Rear Arm
frontArmAngleError: The angle sensor static error of the Forearm

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Linearization Parameter of the Angle Sensor

Table 19.3 Set the linearization parameter of the angle sensor

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
69
 Dobot Magician API Description 19 CAL

Prototype int SetAngleSensorCoef(float rearArmAngleCoef, float

frontArmAngleCoef)

Description Set the linearization parameter of the angle sensor

Parameter rearArmAngleCoef : The linearization parameter of the Rear Arm angle

sensor
frontArmAngleCoef : The linearization parameter of the Forearm angle
sensor

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Linearization Parameter of the Angle Sensor

Table 19.4 Get the linearization parameter of the angle sensor

Prototype int GetAngleSensorCoef(float *rearArmAngleCoef, float

*frontArmAngleCoef)

Description Get the linearization parameter of the angle sensor

Parameter rearArmAngleCoef : The linearization parameter of the Rear Arm angle

sensor
frontArmAngleCoef : The linearization parameter of the Forearm angle
sensor

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Static Error of the Base Encoder

Table 19.5 Set static error of the base Encoder

Prototype int SetBaseDecoderStaticError(float baseDecoderError)

Description Set the static error of the base Encoder

Parameter baseDecoderError: The static error of the base Encoder

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Static Error of the Base Encoder

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
70
 Dobot Magician API Description 19 CAL

Table 19.6 Get the static error of the base Encoder

Prototype int GetBaseDecoderStaticError (float *baseDecoderError)

Description Get the static error of the base Encoder

Parameter baseDecoderError: The static error of the base Encoder

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
71
 Dobot Magician API Description 20 WIFI

WIFI
The Dobot can be connected to a Computer via a WIFI module. After the WIFI module is
connected to the Dobot, you need to set the IP address, Sub netmask, Gateway and enable WIFI to
make the Dobot access WLAN. After the access is successful, you can connect your Dobot to your
Computer without using a USB cable.

Enabling WIFI
Table 20.1 Enable WIFI

Prototype int SetWIFIConfigMode(bool enable)

Description Enable WIFI

Parameter enable: 0, Disabled. 1,Enabled

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the WIFI Status

Table 20.2 Get the WIFI Status

Prototype int GetWIFIConfigMode(bool *isEnabled)

Description Get the WIFI status

Parameter isEnabled: 0, Disabled. 1,Enabled

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the SSID

SSID (Service Set Identifier): WIFI network name.

Table 20.3 Set the SSID

Prototype int SetWIFISSID(const char *ssid)

Description Set the SSID

Parameter ssid: String pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
72
 Dobot Magician API Description 20 WIFI

Getting the SSID

Table 20.4 Get the SSID

Prototype int GetWIFISSID(char *ssid, uint32_t maxLen)

Description Get the SSID

Parameter ssid: String pointer

maxLen: Maximum String length, to avoid overflow

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Network Password

Table 20.5 Set the Network password

Prototype int SetWIFIPassword(const char *password)

Description Set the network password

Parameter password: String pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Network Password

Table 20.6 Get the Network password

Prototype int GetWIFIPassword(char *password, uint32_t maxLen)

Description Get the network password

Parameter password: String pointer

maxLen: Maximum String length, to avoid overflow

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the IP Address

Table 20.7 Set the IP Address

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
73
 Dobot Magician API Description 20 WIFI

Prototype int SetWIFIIPAddress(WIFIIPAddress *wifiIPAddress)

Description Set the IP address

Parameter WIFIIPAddress
typedef struct tagWIFIIPAddress {
uint8_t dhcp; //Whether to enable DHCP. 0:
Disabled1:Enabled
uint8_t addr[4]; // The IP address is divided into 4
segments, the value range of
each segment is 0-255
}WIFIIPAddress;
wifiIPAddr: WIFIIPAddress pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the IP Address

Table 20.8 Get the IP Address

Prototype int GetWIFIIPAddress(WIFIIPAddress *wifiIPAddress)

Description Get the IP address

Parameter WIFIIPAddress
typedef struct tagWIFIIPAddress {
uint8_t dhcp; //Whether to enable DHCP. 0:
Disabled1:Enabled
uint8_t addr[4]; // The IP address is divided into 4
segments, the value range of
each segment is 0-255
}WIFIIPAddress;
wifiIPAddr: WIFIIPAddress pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Sub Netmask

Table 20.9 Set the sub netmask

Getting the Sub Netmask

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
74
 Dobot Magician API Description 20 WIFI

Prototype int SetWIFINetmask(WIFINetmask *wifiNetmask)

Description Set the sub netmask

Parameter WIFINetmask
typedef struct tagWIFINetmask {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each
segment is 0-255
}WIFINetmask;
wifiNetmask: WIFINetmask pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout
Table 20.10 Get the sub netmask

Prototype int GetWIFINetmask(WIFINetmask *wifiNetmask)

Description Get the sub netmask

Parameter WIFINetmask
typedef struct tagWIFINetmask {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each
segment is 0-255
}WIFINetmask;
wifiNetmask: WIFINetmask pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the Gateway

Table 20.11 Set the gateway

Prototype int SetWIFIGateway(WIFIGateway *wifiGateway)

Description Set the gateway

Parameter WIFIGateway
typedef struct tagWIFIGateway {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
75
 Dobot Magician API Description 20 WIFI

segment is 0-255
}WIFIGateway;
wifiGateway: WIFIGateway pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the Gateway

Table 20.12 Get the gateway

Prototype int GetWIFIGateway(WIFIGateway *wifiGateway)

Description Gets the gateway

Parameter WIFIGateway
typedef struct tagWIFIGateway {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each
segment is 0-255
}WIFIGateway;
wifiGateway: WIFIGateway pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Setting the DNS

Table 20.13 Set the DNS

Prototype int SetWIFIDNS(WIFIDNS *wifiDNS)

Description Set the DNS

Parameter WIFIDNS
typedef struct tagWIFIDNS {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each
segment is 0-255
}WIFIDNS;
wifiDNS: WIFIDNS pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
76
 Dobot Magician API Description 20 WIFI

timeout

Getting the DNS

Table 20.14 Get the DNS

Prototype int GetWIFIDNS(WIFIDNS *wifiDNS)

Description Get the DNS

Parameter WIFIDNS
typedef struct tagWIFIDNS {
uint8_t addr[4]; //The IP address is divided into 4
segments, the value range of each
segment is 0-255
}WIFIDNS;
wifiDNS: WIFIDNS pointer

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Getting the WIFI Connection Status

Table 20.15 Get the WIFI connection status

Prototype int GetWIFIConnectStatus(bool *isConnected)

Description Get the WIFI connection status

Parameter isConnected: 0, Non-connected. 1, Connected

Return DobotCommunicate_NoError: The command returns with no error

DobotCommunicate_Timeout: The command does not return, resulting in a
timeout

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
77
 Dobot Magician API Description 21 Other functions

Other functions

Event Loop
In some languages, the application exits directly after calling an API because there is no event
loop, resulting in the command unable to be issued to the Dobot controller. To avoid this, we provide
an event loop API, which is called before the application exits (currently known, Python need to
follow this).

Table 21.1 Event loop

Prototype void DobotExec(void)

Description Event loop

Parameter None

Return Void

Issue V1.2.3 (2019-07-19) API Description Copyright © Yuejiang Technology Co., Ltd
78