MiR Serial Interface. Technical Documentation

Transcription

1 MiR Serial Interface Technical Documentation Version 1.4 Software release 1.5 Release date:

2 Table of contents 1 Introduction Serial Protocol Specifications Installing a USB to Serial Adapter Description of error scenarios Automatic activation of the Serial Interface node Interface protocol Command set Commands Special notes Set Register -!R Get Register -?R Get Current Position -?P Get Status -?S Registers Web interface for the Registers Examples Pause/Continue/Abort button Using the registers as synchronization between MiR100 and a PLC Interfacing using PuTTy Changelog Copyright Mobile Industrial Robots Page 2 of 21

3 1 Introduction The MiR Serial interface is a generic interface protocol, suitable for interfacing e.g. PLCs to the MiR mobile robot platform. The interface offers capabilities to set new waypoints, start and stop robot mission execution as well as making bit integer and bit floating point registers available for the user for storing e.g. process variables, mission parameters etc. The registers can be used as a shared memory interface for data sharing between the mobile robot, the device connected through the serial port and devices using the build-in REST interface. Through this device, the system can be programmed e.g. to wait for a certain register to be set before proceeding on a mission, useful for e.g. waiting for a PLC controlled process to finish or a button to be pressed before continuing. In addition to this, the interface offer the possibility of a limited interaction with the Mission subsystem of the MiR100 robot as it offers the possibility of e.g. retrieving a list of available Missions and queueing, starting and aborting Missions in the Mission queue. 2 Serial Protocol 2.1 Specifications The parameters of the Serial Interface is as listed in the table below. The values marked in bold are the default values. The parameters of the interface can be configured by editing a configuration file, for how to do that, please refer to section 2.2. Parameter Specification Serial Interface type RS232 Baud Rate Standard 1200, 2400, 4800, 9600, 19200, 38400, 57600, User specific Data Bits 7 or 8 Stop Bits 0, 1 or 2 Parity None, Even, Odd Synchronization (CTS/RTS) Not supported Table 1 - MiR Serial Interface specification parameters The MiR100 support a wide array of USB to RS232 converters out of the box. MiR recommend buying a FTDI-based USB to RS232 from In case of doubt, contact MiR Technical Support at support@mir-robots.com. 2.2 Installing a USB to Serial Adapter This section describes how to install and configure a USB to Serial Adapter for use with the MiR Serial Interface. A prerequisite for the process is that you have a compatible USB to Serial Adapter available. The USB to Serial Adapters can be installed either on the top mounted USB ports if the physical layout of the top module allows it, or in one of the USB ports of the embedded PC found inside the MiR100 platform. If you need to connect to a USB port of the embedded PC, be careful not to pull cables, connectors etc. as, although they are fastened securely at time of delivery of the MiR platform, may come loose if subjected to physical strain. Copyright Mobile Industrial Robots Page 3 of 21

4 Step Instruction Illustration 1 Turn on the robot. 2 Log onto the robots WIFI using external PC/tablet 3 Open browser at 4 Navigate through the menu: Service -> Configuration -> System settings -> MiR Setup 5 Plug in the USB to Serial Adapter 6 Press the Setup serial adapter button 7 Check command response at the bottom of the page Success scenarios: Successfully configured serial adapter using VendorID=xxxx, ProductID=yyyy and Serial=zzzzzzzz Serial adapter is already configured with this serial number: zzzzzzzz Error scenarios: The serial number is already used for another rule: SYMLINK+="S300Back" Copyright Mobile Industrial Robots Page 4 of 21

5 8 Unplug the USB to Serial Adapter and insert it again to make the changes take effect 9 Navigate through the menu: Service -> Configuration -> System settings -> ROS parameters Last connected USB device on /dev/ttyusb2 is no longer available! Last connected USB device on /dev/ttyusb2 does not contain a valid serial number: 0000:00:1d.0 10 Locate section Serial Interface and modify to desired values. Press the Save button, when all changes are complete Instruction List 1 - Install USB to Serial Adapter Description of error scenarios This section describes how to handle the error scenarios listed in step 7 of the instruction list. The serial number is already used for another rule: SYMLINK+="S300Back" The last connected USB device is already configured for other use (likely for laser scanners). Try to reboot the embedded PC without the serial adapter connected until step 5 and retry configuration. Last connected USB device on /dev/ttyusb2 does not contain a valid serial number: 0000:00:1d.0 The last connected USB device is not a FTDI-based adapter, which is strongly recommended for a robot in production. The adapter can still be used by changing the Serial Port in ROS parameters from the default value /dev/serialadapter to the current port /dev/ttyusb2. The drawback is that the port may change on every startup, and therefore require a reconfiguration of the serial port, which can be avoided by used a FTDI-based adapter. Last connected USB device on /dev/ttyusb2 is no longer available! The last connected USB device has been removed again. Make sure the serial adapter is properly connected at step 5 of the instruction list. Copyright Mobile Industrial Robots Page 5 of 21

6 2.2.2 Automatic activation of the Serial Interface node When using the serial interface, the Serial Interface node is automatically activated. However, you can manually start and stop it under the Launch Menu, which is located under Service/Configuration/Launch Menu. 3 Interface protocol 3.1 Command set There is two basic ways of interacting with the robot over the serial protocol: setting parameters by prefixing a command with!, or getting parameters by prefixing a command with?. Prefix Syntax Command Example explanation Example Response! R<n>#<value> Set Register Set register 101 with value!r101# OK: Register set ! P Pause Signal Pause robot!p OK: Wait called! C Continue Signal Un-Pause robot!c OK: Continue called! GO:<x>,<y>,<theta> Go to point Go to point with!go:2.4,45.2,0.29 OK: Position set coordinates (2.4,45.2) 0.29 radians! GO:<position Go to position Go to position called!go:home OK: Goal position set name> Home! X Abort current Abort current mission!x OK: Mission aborted mission! MA:<Mission name> Append Mission to Mission queue Append Mission Move to List!MA:Move to List OK: Mission appended! MC Clear Mission Queue Clear the Mission queue!mc OK: Mission queue cleared? R<n> Get Register Get value in register 101?R101 OK: R101# ? P Get current position Get current position (X, Y, theta)?p OK: 52.15, 0.81, 1.929? S Get robot status Get Status (platform state, distance traveled, uptime,battery,mode)?s OK: 3, 0.0, 83.87, 25.50, manual? L Get list of available position names? MQ Get Missions in Mission Queue? MA Get name of active Mission? ML Get name of available Missions Table 2- Command Set of the MiR Serial Interface - overview Get list of position names?l OK: Home,FAM,Production Returns the names of the Missions in the Mission queue Returns the name of the active Mission in the Mission queue Returns the names of the available Missions?MQ?MA?ML OK: Call Elevator, Go to Dock, Dock OK: Call Elevator OK: Call Elevator, Go to Dock, Dock, Production, Open Door All commands must be terminated with the Carriage Return character \r with the hexadecimal value of 0x0D. The response send back will be terminated with a Carriage Return character \r as well. Copyright Mobile Industrial Robots Page 6 of 21

7 3.2 Commands Special notes There are a few commands and associated return values of the Command Set found in Table 2 that deserve special attention. The commands are listed in this section for easy reference. As handling of dynamic strings on devices such as PLCs, some of the replies utilize fixed positions for the return values to allow for the device to index directly to the values they require. Please note that the commands are case sensitive and the serial interface will thus not accept lower-case letters as commands Set Register -!R The syntax of the command is!r<n>#<value>\r, with!r being the Set Register command, <n> being the number of the register e.g. 37 and # the value specification character and <value> being the value e.g. 82. In this case, the complete command would be!r37#82\r. For registers , the syntax of the command are basically the same but it allow floating point values. An example of such a command is!r101#3.1459\r for setting register 101 to the value Get Register -?R The syntax of the command is?r<n>\r with?r being the Get Register command and <n> being the register to query for value. An example of such a command is?r101\r to get the value in register 101. The return string of the command is formatted as follows: OK: R%i#%i\r in the case of registers and OK: R%i#%lf\r in the case of registers The register number will be filled with leading zeroes, such that?r7 returns OK: R007#1234\r. Another example of a reply from a floating point register is OK: R101#3.1459\r denoting a value of in register 101. Copyright Mobile Industrial Robots Page 7 of 21

8 3.2.3 Get Current Position -?P By querying with the Get Current Position, it is possible to get the position of the MiR in the internal coordinate system. The units of the coordinate system is meters and the resolution of the positions given are in centimeters. The origin of the coordinate system will be the point where the mapping procedure started. This means that a X/Y position will not necessarily be at a corner of a map but most likely somewhere inside it. Fejl! Henvisningskilde ikke fundet. show the axes of the coordinate system used in the MiR. The X coordinate can be thought of as the longitude of the map, the Y coordinate as the latitude and the Theta as the rotation around the origin versus the X axis measured in radians (multiply by to get degrees). Figure 1 - Coordinate system of the MiR100 The return string of the command is formatted as follows: OK: %7.2lf,%7.2lf,%5.3lf\r, which mean space is reserved for coordinates up to with centimeter precision and rotations with precision of a thousand of a radians. An example of a reply is OK: 52.15, 0.81, 1.929\r, denoting a X coordinate of 52.15, Y coordinate of 0.81 and rotation of radians Get Status -?S State ID State The possible system states of the MiR100 robot are listed in Table 3. 1 Starting The first field of the Get Status reply denotes the system state of the 2 Shutting down robot. During the execution of a mission, the normal state of the robot is 3 Ready 5 i.e. the robot is Executing a mission. 4 Pause 5 Executing By polling with the Get Status command, it is possible to i.e. see if the 6 Aborted robot is in Emergency mode and from that e.g. activate a blinking light 7 Completed on the attached PLC. 8 Docked The status reply from the command is formatted as follows: OK: 9 Docking %2u, %6.1f, %6.2f, %4.2f, %s\r. An example of a status 10 Emergency Stop reply is OK: 3, 0.0, 83.87, 25.50, manual, 11 Manual Control meaning the robot is in state 3 (Ready), it has moved 0.0m, the uptime is 12 Error minutes, the battery voltage is 25.50V and its operating in manual Table 3 - MiR100 System states mode. Copyright Mobile Industrial Robots Page 8 of 21

9 3.3 Registers The Serial Interface offer 200 custom registers. Registers are 32bit integer registers, while registers are 64bit floating point registers. Writing floating point values to integer registers will truncate the values and loose the information found in the value after the decimal point. The registers can be used for e.g. persistent storage of values or interacting with Missions of the MiR platform. For an example of this, please refer to section 4.2 and 4.3. If you are using the registers for synchronization between the MiR100 and e.g. a PLC, please note that the Mission subsystem of the MiR100 will accept a difference in values of lower than 10-5 as a match due to internal handling of the numbers. This means that if a Mission is programmed to wait for a value of in a register and the value stored by the PLC is , the values are accepted as a match. It is recommended only to use the integer registers as synchronization registers Web interface for the Registers To allow for further customization, synchronization and editing, the Registers are available from the normal web interface of the MiR100. From the webpage, it is possible to use the Quick edit button to enter a value for a specific register, or selecting the individual register to edit it manually. The instruction list below demonstrate both procedures. Step Instruction Illustration 1 From the MiR homepage, go to Service->Configuration and press the PLC Registers button. 2 Press the Quick edit button and input 2 in the ID field and 20 in the value field. Press the Edit button. The Editing window closes and Register 2 now has the value 20. Copyright Mobile Industrial Robots Page 9 of 21

10 3 Press the Edit button next to in the 1 row. The value in the ID field is automatically filled by the system. Input 10 in the Value field and press the Edit button. The Edit PLC register window closes and the value for Register 1 is updated. Copyright Mobile Industrial Robots Page 10 of 21

11 4 Query the register values by e.g. a PLC or a terminal (in this case a PuTTy terminal) to see the register values. Copyright Mobile Industrial Robots Page 11 of 21

12 4 Examples In this section, a series of examples will be listed to serve as inspiration to the users of the MiR Serial Interface. They should be regarded as demonstrations of the interface only, and thus not regarded as complete in terms of feedback to the users etc., as they focus on the communication over the serial interface. For illustration of the examples, the CLICK PLC C0-00DD1-D and associated programming software from AutomationDirect has been used Pause/Continue/Abort button Consider the case when a user would like to be able to pause, resume or abort the robot during execution of a mission. This could be beneficial if e.g. the robot is entering an area in which personnel are operating heavy equipment and due to the risk of equipment damage, it should wait until they are finished before continuing. If the operation of heavy equipment takes too long, the personnel would like to be able to cancel the current mission and reassign it to go back to the dock for assignment to new missions. This example can be realized with a PLC, on which two buttons are connected: one for controlling the pause/continue/abort operation and one for commanding the MiR100 to return to the Dock position after the abort signal has been send over the serial interface. The operation of the program is as follows: 1. When the StopButton is pressed, a timer starts. If the timer is pressed more than 5 seconds, the abort signal!x is send over the serial interface 2. If the StopButton (X1) is activated and pause has not been send, the!p signal is send over the serial interface 3. If the StopButton is released and the abort timer has not fired, the continue signal!c is send over the serial interface 4. If the abort signal has been send and the DockButton has been pressed, the Go To Position with position Dock is send!go:dock. Figure 2 - CLICK PLC Ladder program of Pause/Continue/Abort example 1 _Micro_Brick)/PLC_Units/C0-00DD1-D Copyright Mobile Industrial Robots Page 12 of 21

13 4.2 Using the registers as synchronization between MiR100 and a PLC One of the key features of the MiR Serial Interface is the ability to share information between the MiR100 robot and peripheral devices connected via the MiR Serial Interface such as e.g. PLCs using one or more of the 200 available registers. These registers can be assigned with values by the PLC and used for triggering events in the MiR100 programming interface, useful for signaling when a PLC based process is finished and the MiR100 can proceed on its mission. The procedure of the program is a follows: 1. MiR100: The MiR100 drives to the ProcessEquipment position 2. MiR100: The Register 10 is set to value 1 to signal the top mounted PLC to start operation. 3. MiR100: The robot waits while monitoring the status of Register 10. When the value of the Register is 0, it proceeds to position OffloadPosition 4. PLC: The subroutine Proc MiR SerialInterface monitors the serial interface, send periodic commands to get the value of Register 10 (?R#10 ) and parses the incoming string. The value of Register 10 is put into the register DS1. 5. PLC: If this value is equal to 1, the StartSignal register is activated which in turn activates the, in this case abstract, process of the TopModuleProcess subroutine. This process uses the PLC register C2 to signal when the process is complete. 6. PLC: When the process is complete and register C2 is enabled, the PLC writes the value 0 to register 10 with the command!r10#0. 7. MiR100: The robot observes that Register 10 is returned to value 0, and proceeds to position OffloadPosition Figure 3 - CLICK PLC ladder diagram example of using the registers as synchronization between MiR100 and a PLC. Please note that teh process of parsing the incoming strings is now shown Figure 4 - Mission of the process as described in the list. The first entry is the "Move To Known Postion" with the ProcessEquipment position. After this, the Mission sets Register 10 to 1 as the start signal to the PLC. The "Wait for PLC Register" monitors Register 10 until it reaches the value 0. After this, the MiR100 continues to position OffloadPosition. 4.3 Interfacing using PuTTy The serial interface protocol is a generic protocol which use extends beyond the realm of PLCs. If the users wish to use it with e.g. a PC equipped with a RS232 port, it is possible either through custom software or by commercially or freeware software available from a wide range of vendors and organizations. Copyright Mobile Industrial Robots Page 13 of 21

14 An example of such a piece of software is the PuTTy 2 client. Originally written with SSH and Telnet clients in mind, the program is also able to handle serial connections in the terminal. Other terminal programs such as e.g. Windows Hyperterminal, Docklight, RealTerm or similar can also be used. Please note that the PuTTy terminal program does not offer the use of delete or backspace characters in the terminal window so any commands with spelling errors will not be accepted. The example will demonstrate how to interact with the Mission subsystem of the MiR100 platform. The example assume that three Missions called Go Home, Dock and Call Elevator have been created using the MiR web interface and the current Mission queue is empty. Step Instruction Illustration 1 Download the PuTTy executable from e.g. latest/x86/putty.exe to the Desktop or wherever you wish. 2 Open the program with sufficient user privileges 3 Click the Serial button 2 Copyright Mobile Industrial Robots Page 14 of 21

15 4 Enter the correct parameters for the serial port in the Serial line and Speed fields. In this case COM10 and the default speed of 19200baud. 5 Optional: Click Terminal in the Category list. Put a checkmark in the Implicit LF in every CR to make the terminal put in an extra Line Feed character when a Carriage Return is received. Click the Force on button in the Local echo field of the Line discipline options block to make the terminal echo user inputs. Copyright Mobile Industrial Robots Page 15 of 21

16 6 Click the Open button. The PuTTy terminal will open. Copyright Mobile Industrial Robots Page 16 of 21

17 7 Input?ML in the terminal and press Enter to get the currently available Missions. The MiR responds with the Missions. In this case Go Home, Dock and Call Elevator. 8 Input?MQ in the terminal and press Enter to get the Missions in the queue. The MiR respond with an empty list OK: as there are no Missions in the queue at this point. 9 Input!MA: Go Home to queue the Go Home Mission to the Mission queue and automatically start the Mission. The MiR responds with OK: Mission appended Copyright Mobile Industrial Robots Page 17 of 21

18 10 Input?MA to view the currently active Mission in the Mission queue. The MiR respond with OK: Go Home 11 Input!MA: Dock and press enter to append the Dock Mission to the queue. The MiR respond with OK: Mission appended 12 Input?MQ to get the Mission queue. The MiR responds with OK: Go Home,Dock Copyright Mobile Industrial Robots Page 18 of 21

19 Input?MA and press enter to get the currently executing Mission from the Mission queue. The MiR respond with OK: Go Home Input!X and press Enter to abort the currently running Mission. The MiR respond with OK: Mission aborted Input?MA and press Enter to view the currently running Mission. The MiR respond with OK: Dock as the Go Home Mission was aborted. Copyright Mobile Industrial Robots Page 19 of 21

20 Input!MC and press Enter to clear the Mission queue. The MiR respond with OK: Mission queue cleared Input?MQ and press Enter to view the Mission queue. The MiR return an empty list with the response OK: Copyright Mobile Industrial Robots Page 20 of 21

21 5 Changelog Version Date Changes Document created Document updated Document for review Document updated more descriptions of commands an replies Images added. Document for review Review and updated section for installing serial adapter Corrected default value for stop bit to Added subsection for checking that the Serial interface node is running in the Launch menu Changed subsection Node automatically starts Added new link to FTDIchip.com Copyright Mobile Industrial Robots Page 21 of 21