Transcription
Engineering and Technical NotesDobot APIDobot MagicianTN01010101V1.0.0Date: 2016/07/29Shenzhen Yuejiang Technology Co.,Ltd
Dobot APIShenzhen Yuejiang Technology Co.,LtdDobot MagicianRevised HistoryVersionDateReasonV1.0.02016/07/29Create a documentV1.0.12016/08/09Modify protocol classification, description and so onV1.0.22016/08/22Modify the interface description of EndEffector settingsparameters, also support quene wayV1.0.32016/08/26Increase search Dobot function; modify EIO part of 62016/08/31Add Wi-Fi configuration functionV1.0.72016/09/09Modify the control connection of the EndEffectorV1.0.82016/09/13Modify Home Parameter and maxJumpHeightV1.0.92016/09/19Add the connection of DNSV1.1.02016/09/27Add an API interface to detect whether the -Fi module isin placeV1.1.12016/10/24Modify output parameters description in ConnectDobot工程技术笔记Modify searched API definition and so onAmend the reset real-time poseAPI interface errorShenzhen Yuejiang Technology Co., Ltd
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot MagicianContents1. Application Scope . 12. API Interface Description . 22.12.22.3Dobot Commands. 2API Background API. 2Connect/Disconnect . 22.3.1 Search Dobot . 22.3.2 Connect Dobot . 32.3.3 Disconnect Dobot . 32.4Instruction Timeout . 32.5Command queen controlling . 32.5.1 SetQueuedCmdStartExec . 32.5.2 SetQueuedCmdStopExec . 42.5.3 SetQueuedCmdForceStopExec . 42.5.4 SetQueuedCmdStartDownload . 42.5.5 Complete the instruction queue download. . 52.5.6 SetQueuedCmdClear . 52.5.7 GetQueuedCmdCurrentIndex. 52.6Device Information . 62.6.1 Set the device serial number. 62.6.2 Get the device serial number . 62.6.3 Set the device name . 62.6.4 GetDeviceName . 72.6.5 GetDeviceVersion . 72.7Real-time pose . 72.7.1 Get real-time pose . 82.7.2 Reset real-time pose . 82.7.3 GetKinematicsParams . 92.8ALARM . 92.8.1 GetAlarmsState . 92.8.2 ClearAllAlarmsState . 92.9HOME . 102.9.1 Set Home Parameter . 102.9.2 Get Home Parameter . 102.9.3 Execute HOME function . 112.10HHT . 112.10.1 Set trigger mode . 112.10.2 Get trigger mode . 122.10.3 SetHHTTrigOutputEnabled/Disabled . 122.10.4 GetHHTTrigOutputEnabled/Disabled. 122.10.5 Get trigger output . 132.11End-effector. 132.11.1 Set EndEffectorParams . 13工程技术笔记Shenzhen Yuejiang Technology Co., Ltd
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician2.11.2 GetEndEffectorParams . 142.11.3 SetEndEffectorLaser Output . 142.11.4 GetEndEffectorLaser Output. 142.11.5 SetEndEffectorSuctionCup Output . 152.11.6 GetEndEffectorSuctionCup Output . 152.11.7 Set gripper output . 152.11.8 Get gripper output . 162.12ARM Orientation . 162.12.1 SetArmOrientation . 162.12.2 GetArmOrientation . 172.13JOG . 172.13.1 SetJOGJointParams . 172.13.2 GetJOGJointParams . 182.13.3 SetJOGCoordinateParams . 182.13.4 GetJOGCoordinateParams . 192.13.5 SetJOGCommonParams Parameter . 192.13.6 GetJOGCommonParams . 202.13.7 Execute JOG command . 202.14PTP . 212.14.1 SetPTPJointParams . 212.14.2 GetPTPJointParams. 212.14.3 SetPTPCoordinateParams . 222.14.4 GetPTPCoordinateParams . 222.14.5 SetPTPJumpMode . 232.14.6 GetPTPJumpMode . 232.14.7 SetPTPCommonParams . 242.14.8 GetPTPCommonParams. 242.14.9 SetPTPCmd . 252.15CP . 252.15.1 SetCPParams . 252.15.2 GetCPParams . 262.15.3 SetCPCmd . 272.16ARC . 281.Set circular interpolation parameter . 282.16.2 Get circular interpolation parameter. 282.16.3 Perform circular interpolation function . 292.17WAIT . 292.17.1 Perform wait function . 292.18TRIG . 302.18.1 Execute the trigger function . 302.19EIO . 312.19.1 Set I/O multiplex . 312.19.2 Read I/O multiplex . 312.19.3 Set I/O level output . 32工程技术笔记Shenzhen Yuejiang Technology Co., Ltd
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician2.19.4 Read I / O output level . 332.19.5 Set PWM Output . 332.19.6 Read PWM output . 332.19.7 Read I/O output level . 342.19.8 Read I/O analog-digital conversion values . 342.20CAL. 352.20.1 Set angle sensor static error. 352.20.2 Get angle sensor static error . 352.21WIFI . 362.21.1 Set WIFI configuration mode . 362.21.2 Get the current WIFI configuration mode if it is enabled . 362.21.3 Set SSID . 362.21.4 Get the current SSID settings . 372.21.5 Set the network password. 372.21.6 Get the current network password . 372.21.7 Set IP address . 382.21.8 GetWIFIIPAddress . 382.21.9 Set WIFI Sub Netmask . 392.21.10GetWIFINetmask . 392.21.11 SetWIFIGateway . 392.21.12Gets the current settings of gateway . 402.21.13Set DNS. 402.21.14Get the current settings of DNS . 412.21.15Get Wi-Fi connect status . 412.22Other functions . 412.22.1 Event loop . 41工程技术笔记Shenzhen Yuejiang Technology Co., Ltd
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician1. Application ScopeThe document is aiming to have a detailed description of Dobot API and general process of DobotAPI development program.文档类型Shenzhen Yuejiang Technology Co., Ltd1
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician2. API Interface Description2.1Dobot CommandsThere are two features of communication commands when communicating with Dobot controller:1.All commands can be returned to the controller; regarding to setup commands, thecontroller can cut command parameter domain and then return; while for gettingcommands, the controller can fill the parameters got in parameter domain and thenreturn.2.Dobot controller supports two kind of commands: Immidinate instruction and queeninstruction: Immidinate instruction: Dobot controller will process the command once receivedregardless of whether there is the rest commands processing or not in the currentcontroller; Queue command: Dobot controller receives the queue instruction, the command ispressed into the controller internal instruction queue. Dobot controller will executeinstructions in the order in which the instruction was pushed into the queue.For more detailed information about Dobot commands, please refer to Dobot protocol.2.2API Background APIIn order to use API properly, call API background task periodically at first. One can createtimer or thread to call the task in different languages.Figure 2.1PrototypeAPI description of background task APIvoid PeriodicTask(void)DescriptionAPI background task, recommend call 100ms connect2.3.1 Search DobotFigure 2.2PrototypeGet number of Dobot interfaceint SearchDobot(char *dobotList, uint32 t maxLen)DescriptionSearch Dobot, dll will store connected Dobot information and useConnectDobot.ParameterdobotList:array TPTR transmitted externally,dll will write serialport/UDPsearched into dobotList, for example, a specific returned dobotList is "COM1COM3 COM6 192.168.0.5", different interface should be separated by thespace.maxLen: The max length that dobotList transmitted externally can support toavoid internalstorage overflow.ReturnDobot number文档类型Shenzhen Yuejiang Technology Co., Ltd2
Dobot APIShenzhen Yuejiang Technology Co.,LtdDobot Magician2.3.2 Connect DobotFigure 2.3PrototypeDescripition of Connect Dobot controller interfaceint ConnectDobot(const char * portName, int baudrate)DescriptionConnect Dobot controller, in this process, portName can be got from thedobotList oflast API.Note：If we don’t call SearchDobot but call ConnectDobot directly (portNameis empty), and then dll will connect the first found Dobot controllerautomatically.ParametersportName，Dobot port name;As for serial port, maybe is COM3; WhileforUDP, maybe is 192.168.0.5baudrateReturnDobotConnect NoError：Connect Dobot controller successfullyDobotConnect NotFound：Dobot controller port is not foundDobotConnect Occupied：Dobot controller port is occupiedNote：In order to make API recognize Dobot controller interface, please install the needed driver in advance, referto Dobot user manual for detailed information.2.3.3 Disconnect DobotFigure 2.4Disconnect Dobot interfacePrototypevoid DisconnectDobot(void)DescriptionDisconnect Dobot controllerParameterVoidReturnVoid2.4Instruction TimeoutAs described in Section 2.1, all instructions sent to Dobot controller have Return. When aninstruction error occurs due to a communication link interference or any other factors, thecontroller can be recognized by the Void method and the Void method Return. Therefore, eachinstruction issued to the controller has a time-out period. The instruction timeout period can be setby the following API.Figure 2.5Interface of setup command timeoutPrototypevoid SetCmdTimeout(uint32 t cmdTimeout)DescrptionSetup commands timeoutParametercmdTimeout Unit：msReturn2.5VoidCommand queen controllingDobot controller support start, stop the execution of quene command.2.5.1 SetQueuedCmdStartExec文档类型Shenzhen Yuejiang Technology Co., Ltd3
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot MagicianFigure 2.6PrototypeInterface of start up commands queneint SetQueuedCmdStartExec(void)DescriptionOperation of startup commandsParameterVoidReturnDobotCommunicate NoError: The command is returned normallyDobotCommunicate BufferFull: The command quene is full.(The interface donot return the value)DobotCommunicate Timeout: The command doesn’t return, which results intimeout.2.5.2 SetQueuedCmdStopExecFigure 2.7PrototypeOperation of stop commands quene interfaceint SetQueuedCmdStopExec(void)DescriptionStop instruction queue operation. If the current instruction queue is running aninstruction, it will stop the instruction queue after finishing running theinstruction.ParameterVoidReturnDobotCommunicate NoError: The command returns normallyDobotCommunicate BufferFull: The command quene is full (The interfacewill not return the value)DobotCommunicate Timeout: The command has no return,which resultsintimeout.2.5.3 SetQueuedCmdForceStopExecFigure 2.8PrototypeThe interface description of SetQueuedCmdForceStopExecint SetQueuedCmdForceStopExec(void)DescriptionStop instruction queue operation forcely.No matter whether the instructionquene is running an instruction or not,the controller will force it to stoprunning.ParameterVoidReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.5.4 SetQueuedCmdStartDownloadDobot controller supports storing instructions in the controller's external Flash, and then itcan be triggered by pressing the keys on the controller, that is, the offline function.The general flow of instructions to download is:1. Call the start instruction queue to download API. Where totalLoop is the total number ofthe instruction is run offline;文档类型Shenzhen Yuejiang Technology Co., Ltd4
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician2. Send queue instructions;3. Repeat until the queue instruction transmission is complete;4. Call the Stop Instruction Queue to download API.Figure 2.9PrototypeThe interface description of SetQueuedCmdStartDownloadint SetQueuedCmdStartDownload(uint32 t totalLoop, uint32 t rametertotalLoop: the total number of running offlinelinePerLoop: The number of per cycle instructionReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.5.5 Complete the instruction queue download.Figure 2.10PrototypeThe interface instruction of completing the instruction queue downloadint SetQueuedCmdStopDownload(void)DescriptionComplete the instruction queue download.ParameterVoidReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.5.6 SetQueuedCmdClearThis interface can clear the instruction queue buffered in Dobot controller.Figure 2.11 SetQueuedCmdClearPrototypeint SetQueuedCmdClear(void)DescriptionClear command queneParameterVoidReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.5.7 GetQueuedCmdCurrentIndexIn Dobot controller instruction queue mechanism, there is a 64-bit internal count index.Whenever the controller executes a command, the counter is automatically incremented. With thisinternal index, you can query how many queue instructions the controller has executed and theinstructions that have been executed. (Indicate the progress of the run)文档类型Shenzhen Yuejiang Technology Co., Ltd5
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot MagicianFigure 2.12PrototypeThe interface description of GetQueuedCmdCurrentIndexint GetQueuedCmdCurrentIndex(uint64 t ex ExecutedParameterqueuedCmdCurrentIndex:Quene command index variable pointers；Return2.6DobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.Device Information2.6.1 Set the device serial numberFigure 2.13PrototypeThe interface instruction of setting the device serial numberint SetDeviceSN(const char *deviceSN)DescriptionSet the device serial numberParameterdeviceSN:Device serial number string pointer.ReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.NOTE: The device serial number setting interface is only valid when shipped out (requires specialpassword).2.6.2 Get the device serial numberFigure 2.14PrototypeGet the device serial numberThe interface description ofint GetDeviceSN(char *deviceSN, uint32 t maxLen)DescriptionGet the device serial numberParameterdeviceSN:Device serial number string pointer.maxLen:Incoming external buffer length to avoid overflow.ReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.6.3 Set the device name文档类型Shenzhen Yuejiang Technology Co., Ltd6
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot MagicianFigure 2.15PrototypeThe interface instruction of setting the device nameint SetDeviceName(const char *deviceName)DescriptionSet the device name. When there are multiple machines, you can use thisinterface to set the device name for distinction.ParameterdeviceName: Device name string pointerReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.6.4 GetDeviceNameFigure 2.16PrototypeThe interface description of GetDeviceNameint GetDeviceName(char *deviceName, uint32 t : Device name string pointermaxLen:Incoming external buffer length to avoid overflow.ReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.6.5 GetDeviceVersionFigure 2.17 2.6.5 The interface instruction of getting the device version numberPrototypeint GetDeviceVersion(uint8 t *majorVersion, uint8 t *minorVersion, uint8 t*revision)DescriptionGet equipment version onReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.Real-time pose2.7In DobotV2.0, Dobot controller calculates the real-time pose initial value based on thefollowing information: Encoder position (can be obtained by Home); Rear arm angle sensor (power on or by the arm when press UNLOCK button);文档类型Shenzhen Yuejiang Technology Co., Ltd7
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician Forearm angle sensor(power on or by the arm when press UNLOCK button).Then in the later process of controlling Dobot, Dobot controller will update real-time posebased on real-time pose initial value.2.7.1 Get real-time poseFigure 2.18 The interface description of getting real-time posePrototypeint GetPose(Pose *pose)DescriptionGet real-time poseParameterPose definition：typedef struct tagPose {float x;float y;float z;float r;float jointAngle[4];}Pose;pose:Real-time pose pointerReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.2.7.2 Reset real-time poseThe real-time pose (initial value) can be reset in the following cases: Angle sensor is damaged, which must rely on the external angle measurement means; Angle sensor accuracy is too poor, which need an external angle measurement means toconfirm the exact value directly or indirectly.Figure 2.19PrototypeThe interface description of setting initial poseint ResetPose(bool manual, float rearArmAngle, float frontArmAngle)DescriptionReset poseParametermanual:If got 0,reset the pose and don’t need incoming rearArmAngle andfrontArmAngle；If got 1, need incoming rearArmAngle and otCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.文档类型Shenzhen Yuejiang Technology Co., Ltd8
Shenzhen Yuejiang Technology Co.,LtdDobot APIDobot Magician2.7.3 GetKinematicsParamsFigure 2.20PrototypeThe interface of getting kinematica parameterint GetKinematics(Kinematcis *kinematics)DescriptionGet Kinematics ParameterParametertypedef struct tagKinematics {float velocity;float acceleration;}Kinematics;kinematics:Kinematica Parameter of variable pointersReturn2.8DobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.ALARM2.8.1 GetAlarmsStateFigure 2.21PrototypeThe interface description of GetAlarmsStateint GetAlarmsState(uint8 t *alarmsState,uint32 t *len, uint32 t maxLen)DescriptionGets the system alarm statusParameteralarmsState: The first address of the array used to receive the alarm bit.len: The byte occupied by the alarm.maxLen:Incoming external buffer length to avoid overflow.ReturnDobotCommunicate NoError: The instruction returns normally.DobotCommunicate BufferFull: The instruction queue is full. (The interfacedoes not return this value)DobotCommunicate Timeout: The instruction did not return, resulting in atimeout.Note: For specific alarms and indexes, refer to Dobot User Manual. Each byte in the array alarmsStateidentifies the alarm status of the eight alarm items, with the MSB (Most Significant Bit) in the high order and LSB(Least Significant Bit) in the low2.8.2 ClearAllAlarmsState文档类型Shenzhen Yuejiang Technology Co., Ltd9
Shenzhen Yuejiang Technolo
2.2 API Background API In order to use API properly, call API background task periodically at first. One can create timer or thread to call the task in different languages. Figure 2.1 API description of background task API 2.3 Connect/Disconnect 2.3.1 Search Dobot Figure 2.2 Get number of Dobot interface Prototype void PeriodicTask(void)
