Communicating with the Dobot Magician using raw protocol

9 May

I got this little robot a while ago as part of a larger project and I have to say it’s very good value for money, and from what I’m told the accompanying documentation is great—if you can speak Chinese.

Unfortunately, the English documentation provided by the manufacturer is somewhat lacking, and the Dobot forum isn’t very active. So, after struggling with the official Matlab API, giving up, followed by some more pain trying to interpret the Magician Communication Protocol document, I have decided to release this post with the aim of sparing someone the trouble when using this manipulator outside of the official Magician Studio software.

Throughout this guide I’ll be drawing from the Dobot Magician Communication Protocol user manual (v1.1.3). I suggest you have this document handy for reference while reading this post.

Dobot protocol document

Admittedly I have only interfaced with the Magician via USB but according to the manual, this protocol is the same regardless of mode of communication. Serial port parameters:

    Parameter
    Value
  
    Baud rate
    115,200 bps
  
    Data bits
    8
  
    Stop bit
    1
  
    Parity bit
    None

For the sake of simplicity and understanding, I have included decimal values in each of my figures. Before continuing, you should make sure you’re familiar with decimal, hexadecimal and binary conversions.

The Magician command protocol length is not fixed, and command packets consist of a header, payload length descriptor, the payload itself and a checksum. Packets are made up of 8-bit characters. Each character is represented by two hex values. The Magician executes and responds to a received packet immediately, provided it has been correctly interpreted.

Dobot comms are little-endian. This means the order of hex values might be flipped compared to what you’re used to. This is important for multi-character sub-packets like the 32-bit float values used to represent arm position. I’ll illustrate this with a later example.

Let’s see what a getPose command looks like (command to get the current position of the Dobot).

    Hex
    AA
    AA
    02
    0A
    00
    -
    F6
  


    Dec
    170
    170
    2
    10
    0
    -
    246
  

    
    Header
    Len
    ID
    Ctrl
    Params
    Checksum
  

    Payload
  

Header. The first two characters in each command are always 0xAAAA, which signifies the beginning of a new packet.

Len. This character denotes the number of payload characters.

Payload. The structure of the payload portion of each instruction packet can be found in the communication protocol document and varies with each command, but always begins with the ID and Ctrl sub-packets. Note the user manual references the ID command descriptor as a decimal, rather than its hex value which is communicated to the Dobot.

The Ctrl sub-packet indicates whether a command is queued (isQueue) and specifies a read [0] or write [1] instruction (RW). Only the last two bits within the Ctrl sub-packet are manipulated:

The RW bit is toggled HIGH for commands that write information such as SetHOMECmd (ID 31) or SetPTPCmd (ID 84), and LOW for commands that only read information, such as getDeviceTime (ID 4) or getPose (ID 10).

The isQueue bit can be used to queue several commands and run them in their received order. By default, the run queue command buffer is set to true, which means that queued commands will be executed as soon as they are received. To construct a queue of commands, queue execution must first be halted with the SetQueuedCmdStopExec command (ID 241). Once paused, instructions sent to the Magician will be saved in series and can be played in order with the SetQueuedCmdStartExec command (ID 240). Note that the returned packet will be different depending on isQueue status. If the isQueue bit is toggled HIGH, a 64-bit index will be returned within the payload. Read commands are not queued, which means a Ctrl value of 0x02 is not used.

The returned value of Ctrl is always 0x00.

Checksum. The checksum value is calculated based only on the payload portion of a command and used to both signify the end of an instruction and provide some assurance that data has been transmitted correctly. The checksum for the getPose command (above) is calculated as follows:

First sum all the values in the payload—including ID and Ctrl. This sum must always be 8 bits long. If the calculated value is larger than 255, it must be truncated so that only the 8 least significant bits are kept. 277 (1 0001 0101) for example, will become 21 (0001 0101). The sum for the getPose command is 10 (10 + 0).
The two’s complement of the sum can then be calculated in decimal as 256 – sum. In this case it is 246 (256-10).
Finally, convert this value to a two-digit hexadecimal number: 0xF6.

The getPose command may not be a very clear example as it doesn’t contain any multi-valued sub-packets, so let’s analyse the returned pose packet we might get from the Magician:

    Hex
    AA
    AA
    22
    0A
    00
    83
    35
    16
    43
    A4
    93
    8F
    BF
    10
    67
    A0
    41
    48
    0F
    DB
    BE
    00
    31
    A3
    BE
    DD
    B8
    FB
    BE
    F0
    C8
    4D
    42
    00
    00
    00
    00
    F1
  


    Dec
    170
    170
    34
    10
    0
    131
    53
    22
    67
    164
    147
    143
    191
    16
    103
    160
    65
    72
    15
    219
    190
    0
    49
    163
    190
    221
    184
    251
    190
    240
    200
    77
    66
    0
    0
    0
    0
    241
  

    
    Header
    Len
    ID
    Ctrl
    X
    Y
    Z
    r
    Base angle
    Rear arm angle
    Fore arm angle
    Effector angle
    Checksum
  

    Payload
  

In this case, each positional sub-packet within the returned payload params segment is a 32-bit little-endian floating-point number. If you would like the float value of this number, I would recommend this tool. Converting each sub-packet, we get the Cartesian coordinates of the Magician:

We also get the joint angle of each arm:

    
    Base angle
    Rear arm angle
    Fore arm angle
    Effector angle
  


    Hex
    0031A3BE
    DDB8FBBE
    F0C84D42
    00000000
  

    Float
    -0.318733
    -0.491645
    51.4462
    0
  

For clarity, I have included the checksum calculation:

Sum: 3,599 (10+0+131+53+22+67+164+147+143+191+16+103+160+65+72+15+219+190+0+49+163+190+221+184+251+190+240+200+77+66+0+0+0+0)
Sum in binary: ‘1110 0000 1111’ (3,599)
8 LSB: ‘0000 1111’ (15)
2’s complement: 241 (256-15)
Hexadecimal representation: 0xF1

Additional commands:

SetHomeCmd (ID 31): homes the Dobot Magician.

SetPTPCmd (ID 84): moves the Magician to the specified coordinates. (X: 250, Y: 150, Z: 50, R: 150).

SetPTPJointParams (ID 83): sets the acceleration and top speed multipliers. (Vel ratio: 20, Acc ratio: 40).

A final note on the official Dobot Magician Communication Protocol document. Keep in mind the decimal values of Len and ID used throughout and must be converted to hexadecimal for communication. This document is also incomplete, somewhat confusing and contains some mistakes, but to be fair, they did give a brief disclaimer.

For my project, I used the Magician with Matlab and implemented my own library to bypass the Matlab API—which I found to be very problematic. Most of the information within this post was gained by using a combination of the user manual and analysis of the traffic sent to the Dobot by the official Magician Studio software. If you are still struggling to communicate with this little robot, I suggest capturing the packet information at the hardware level using a packet sniffer such as Wireshark.

Good luck and enjoy the development process!

Dobot MagicianCommunication porotocolRobotic arm

Jacques Johnston

	X	Y	Z	r
Hex	83351643	A4938FBF	1067A041	480FDBBE
Float	150.209	-1.12169	20.0503	-0.427851

Communicating with the Dobot Magician using raw protocol

A simple stepper motor control algorithm