MOTOPLUS SDK FOR VISUAL STUDIO USER’S MANUAL (DX100, DX200, AND FS100) Upon receipt of the product and prior to initial operation, read these instructions thoroughly and retain for future reference. MOTOMAN INSTRUCTIONS MOTOMAN- INSTRUCTIONS CONTROLLER INSTRUCTIONS OPERATOR’S MANUAL MAINTENANCE MANUAL Part Number: Revision: 169286-1CD 0 1/53 169286-1CD MotoPlus SDK for Visual Studio MANDATORY • This manual explains the MotoPlus SDK for Visual Studio. Read this manual carefully and be sure to understand its contents before handling the Controller. • General items related to safety are listed in Chapter 1: Safety of the Controller Instructions. To ensure correct and safe operation, carefully read the Controller Instructions before reading this manual. CAUTION • Some drawings in this manual are shown with the protective covers or shields removed for clarity. Be sure all covers and shields are replaced before operating this product. • The drawings and photos in this manual are representative examples and differences may exist between them and the delivered product. • YASKAWA may modify this model without notice when necessary due to product improvements, modifications, or changes in specifications. If such modification is made, the manual number will also be revised. • If your copy of the manual is damaged or lost, contact a YASKAWA representative to order a new copy. The representatives are listed on the back cover. Be sure to tell the representative the manual number listed on the front cover. • YASKAWA is not responsible for incidents arising from unauthorized modification of its products. Unauthorized modification voids your product’s warranty. ii 169286-1CD 2/53 169286-1CD MotoPlus SDK for Visual Studio Notes for Safe Operation Read this manual carefully before installation, operation, maintenance, or inspection of the Controller. In this manual, the Notes for Safe Operation are classified as “WARNING”, “CAUTION”, “MANDATORY”, or ”PROHIBITED”. WARNING CAUTION MANDATORY Indicates a potentially hazardous situation which, if not avoided, could result in death or serious injury to personnel. Indicates a potentially hazardous situation which, if not avoided, could result in minor or moderate injury to personnel and damage to equipment. It may also be used to alert against unsafe practices. Always be sure to follow explicitly the items listed under this heading. Must never be performed. PROHIBITED Even items described as “CAUTION” may result in a serious accident in some situations. At any rate, be sure to follow these important items NOTE To ensure safe and efficient operation at all times, be sure to follow all instructions, even if not designated as “CAUTION” and “WARNING”. iii 169286-1CD 3/53 169286-1CD MotoPlus SDK for Visual Studio DX Controllers WARNING • Before operating the manipulator, check that servo power is turned OFF pressing the emergency stop buttons on the front door of the Controller and the programming pendant. When the servo power is turned OFF, the SERVO ON LED on the programming pendant is turned OFF. Injury or damage to machinery may result if the emergency stop circuit cannot stop the manipulator during an emergency. The manipulator should not be used if the emergency stop buttons do not function. Figure 1: Emergency Stop Button • Once the emergency stop button is released, clear the cell of all items which could interfere with the operation of the manipulator. Then turn the servo power ON. Injury may result from unintentional or unexpected manipulator motion. Figure 2: Release of Emergency Stop TURN • Observe the following precautions when performing teaching operations within the P-point maximum envelope of the manipulator: – View the manipulator from the front whenever possible. – Always follow the predetermined operating procedure. – Keep in mind the emergency response measures against the manipulator’s unexpected motion toward you. – Ensure that you have a safe place to retreat in case of emergency. Improper or unintended manipulator operation may result in injury. • Confirm that no person is present in the P-point maximum envelope of the manipulator and that you are in a safe location before: – Turning ON the power for the Controller. – Moving the manipulator with the programming pendant. – Running the system in the check mode. – Performing automatic operations. Injury may result if anyone enters the P-point maximum envelope of the manipulator during operation. Always press an emergency stop button immediately if there is a problem. The emergency stop button is located on the right of front door of the Controller and the programming pendant. iv 169286-1CD 4/53 169286-1CD MotoPlus SDK for Visual Studio FS100 Controller WARNING • Before operating the manipulator, check that servo power is turned OFF when the emergency stop button on the programming pendant is pressed. When the servo power is turned OFF, the SERVO ON LED on the programing pendant is turned OFF. Injury or damage to machinery may result if the emergency stop circuit cannot stop the manipulator during an emergency. The manipulator should not be used if the emergency stop button does not function. Figure 3: Emergency Stop Button • In the case of not using the programming pendant, be sure to supply the emergency stop button on the equipment. Then before operating the manipulator, check to be sure that the servo power is turned OFF by pressing the emergency stop button. Connect the external emergency stop button to the 5-6 pin and 16-17 pin of the robot system signal connector (CN2). • Upon shipment of the FS100, this signal is connected by a jumper cable in the dummy connector. To use the signal, make sure to supply a new connector, and then input it. If the signal is input with the jumper cable connected, it does not function, which may result in personal injury or equipment damage. • Once the emergency stop button is released, clear the cell of all items which could interfere with the operation of the manipulator. Then turn the servo power ON. Injury may result from unintentional or unexpected manipulator motion. Figure 4: Release of Emergency Stop Button TURN • Observe the following precautions when performing teaching operations within the manipulator’s operating range: – View the manipulator from the front whenever possible. – Always follow the predetermined operating procedure. – Ensure that you have a safe place to retreat in case of emergency. Improper or unintended manipulator operation may result in injury. v 169286-1CD 5/53 169286-1CD MotoPlus SDK for Visual Studio CAUTION • Perform the following inspection procedures prior to conducting manipulator teaching. If problems are found, repair them immediately, and be sure that all other necessary processing has been performed. – Check for problems in manipulator movement. – Check for damage to insulation and sheathing of external wires. • Always return the programming pendant to the hook on the Controller cabinet after use. The programming pendant can be damaged if it is left in the P-point maximum envelope of the manipulator, on the floor, or near fixtures. • Read and understand the Explanation of Warning Labels in the Controller Instructions before operating the manipulator. Definition of Terms Used Often in This Manual The MOTOMAN is the YASKAWA industrial robot product. The MOTOMAN usually consists of the manipulator, the controller, the programming pendant, and supply cables. In this manual, the equipment is designated as follows: Equipment Manual Designation DX100, DX200, and FS100 Controller Controller Programming Pendant Programming Pendant Cable between the manipulator and Controller Manipulator Cable vi 169286-1CD 6/53 169286-1CD MotoPlus SDK for Visual Studio Descriptions of the programming pendant keys, buttons, and displays are shown as follows: Equipment Manual Designation Programming Character Pendant Keys The keys which have characters printed on them are denoted with [ ]. ex. [ENTER] Symbol Keys The keys which have a symbol printed on them are not denoted with [ ] but depicted with a small picture. GO BACK ex. page key PAGE The cursor key is an exception, and a picture is not shown. Axis Keys Number Keys “Axis Keys” and “Number Keys” are generic names for the keys for axis operation and number input. Keys pressed When two keys are to be pressed simultaneously simultaneously, the keys are shown with a “+” sign between them, ex. [SHIFT]+[COORD] Displays The menu displayed in the programming pendant is denoted with { }. ex. {JOB} Description of the Operation Procedure In the explanation of the operation procedure, the expression "Select • • • " means that the cursor is moved to the object item and the SELECT key is pressed, or that the item is directly selected by touching the screen. Registered Trademark In this manual, names of companies, corporations, or products are trademarks, registered trademarks, or brand names for each company or corporation. The indications of (R) and TM are omitted. vii 169286-1CD 7/53 169286-1CD MotoPlus SDK for Visual Studio Table of Contents Table of Contents 1 Outline ............................................................................................................................................ 1-1 1.1 Introduction ........................................................................................................................ 1-1 1.2 What MotoPlus Can Do ..................................................................................................... 1-1 1.2.1 Supported Services .............................................................................................. 1-1 1.3 Development Process........................................................................................................ 1-3 1.4 Notes ................................................................................................................................. 1-4 2 SDK Installation and Setup ............................................................................................................. 2-1 2.1 System Requirements ....................................................................................................... 2-1 2.2 Installation of SDK ............................................................................................................. 2-2 2.3 Setup of Robot Controller .................................................................................................. 2-3 2.3.1 Install VGA Adapter Cable for Debugging ............................................................ 2-3 2.3.2 Enabling MotoPlus ............................................................................................... 2-5 2.4 Enable Telnet for Debugging ............................................................................................. 2-7 3 Creating MotoPlus Application........................................................................................................ 3-1 3.1 Rules for Application Source Code.................................................................................... 3-1 3.2 Creating a MotoPlus Project in Visual Studio .................................................................... 3-2 3.3 Adding Files to the Project................................................................................................. 3-3 3.4 Creating a MotoPlus Library .............................................................................................. 3-4 3.5 Using a MotoPlus Library In Your Project.......................................................................... 3-6 3.6 Building Your Application................................................................................................... 3-7 3.7 Building Your Project for Multiple Controller Platforms.................................................... 3-10 4 Installation and Startup of MotoPlus Application............................................................................. 4-1 4.1 Installation of Application Program in Maintenance Mode................................................. 4-1 4.2 Start-up of Application Program......................................................................................... 4-6 4.3 To Temporarily Prevent MotoPlus Application from Starting ............................................. 4-6 ix 169286-1CD 8/53 169286-1CD MotoPlus SDK for Visual Studio Table of Contents 5 User Defined File ............................................................................................................................ 5-1 5.1 Saving in and Reading from External Memory .................................................................. 5-1 5.1.1 Procedure to Save or Read User Defined File ..................................................... 5-1 5.2 Initialization of User Defined File ....................................................................................... 5-4 5.3 Setting of File Control Task Priority Limit........................................................................... 5-6 5.3.1 Changing File Control Task Priority Limit ............................................................. 5-6 6 Debugging....................................................................................................................................... 6-1 6.1 Debugging Environment .................................................................................................... 6-1 6.2 Commands for Printing to Standard-output (stdout) .......................................................... 6-1 6.3 Viewing Output on Computer Monitor................................................................................ 6-1 6.4 Viewing Output on PC Console Window............................................................................ 6-2 6.4.1 Setup of Robot Controller ..................................................................................... 6-2 6.4.2 Establishing Telnet Connection ............................................................................ 6-3 6.4.2.1 Automatic Login to Telnet Shell............................................................... 6-3 6.4.2.2 Manual Login to Telnet Shell ................................................................... 6-4 7 Alarm List ........................................................................................................................................ 7-1 8 Advanced mpBuilder Usage............................................................................................................ 8-1 8.1 Visual Studio MakeFile Project .......................................................................................... 8-1 8.2 Compiler Arguments .......................................................................................................... 8-3 8.2.1 CompilerArguments.mps ...................................................................................... 8-3 8.2.2 LinkerArguments.mps........................................................................................... 8-3 Appendix A Revision History..............................................................................................................A-1 x 169286-1CD 9/53 169286-1CD MotoPlus SDK for Visual Studio 1 1 Outline 1.1 Introduction Outline 1.1 Introduction MotoPlus Software Development Kit (SDK) is used to develop customer specific applications that operate on the main CPU board of the Motoman robot controller. The application is run concurrently to the robot firmware, in real time. Programming of the application is done using C language with Microsoft Visual Studio. Users can develop a variety of application programs on their own without modifying the source code of the robot controller. This advanced toolset is intended only for experienced software developers who are familiar with the C programming language. 1.2 What MotoPlus Can Do Users can use the C language, a general programming language, and MotoPlus libraries to develop a customer specific application program in which various types of resources are used, e.g., the Ethernet communication port, the RS232C serial communication port, and the programming pendant of the robot controller. 1.2.1 Supported Services MotoPlus SDK provides users with a variety of services as follows: Application task control Application task (thread) start/stop, data transmission between application programs by the mailbox and semaphore, exclusive control and execution synchronization Robot control Robot control from the application program JOB control Start-stop control of the JOB by the application, data transmission between Jobs by variables (byte, integer, double-precision, floating point, character string, and position variable), and execution synchronization CIO control I/O between the application program and the robot CIO including read/ write access to registers Ethernet communication control Industry standard Ethernet (TCP/IP) communication available through standard sockets Programming pendant communication Data transmission between the application and the programming pendant application Robot event notification Event notification to the application at every I/O control cycle and interpolation control cycle of the system RS232C serial communication control RS232C serial communication from the application 1-1 169286-1CD 10/53 169286-1CD MotoPlus SDK for Visual Studio 1 Outline 1.2 What MotoPlus Can Do Sensor control Robot path correction, adjustment, and control can be achieved while reacting to external sensors Memory management Dynamic and static memory allocation General-purpose file control (DX200 and FS100 only) Interface with custom data files to save/load application settings Existing file control (DX200 and FS100 only) Interface with standard robot files (DAT, CND, JBI, etc…) Servo control Control servo power for automated robot operation User watchdog Watchdog to monitor whether the application operates normally Coordinate conversion (DX200 and FS100 only) Forward and inverse kinematic calculations available for position and frame calculations 1-2 169286-1CD 11/53 169286-1CD MotoPlus SDK for Visual Studio 1.3 1 Outline 1.3 Development Process Development Process 1-3 169286-1CD 12/53 169286-1CD MotoPlus SDK for Visual Studio 1.4 1 Outline 1.4 Notes Notes NOTE • C language allows for dynamic memory operations. When programming in C language, pointers with memory addresses may be used. If the pointer variable is set incorrectly, the system memory area may be rewritten. If the system memory area is rewritten, critical problems occur, e.g., the software hangs up (the hang-up status is detected by a CPU exception or the watchdog check function, then the servo power turns OFF and the system shuts down), the robot stops its operation due to an alarm, or the programming pendant becomes inoperable. If the system memory operation is incorrect, the application itself may not operate as it is designed. • The task “mpUsrRoot”, which starts when the power is turned ON, has a high priority to start other application tasks and initialize the entire application quickly. Due to its high task priority, if a time-consuming process (0.1 milliseconds or longer) is done in this task, the processing time for the robot control becomes insufficient. Then system alarms may occur or the programming pendant or the HOLD button may freeze. Thus, as shown in the sample program (refer to Task Control Sample Program” in “Programmer’s Manual for New Language Environment MotoPlus”, make sure to complete the task “mpUsrRoot” after starting up another application or creating a semaphore. • Debugging via Telnet 1.After completing debugging, set the Telnet function to INVALID (S2C1119 = 0). This is because the Telnet function consumes system processing time, and an alarm may occur due to insufficient processing time for robot operation. 2. With the Telnet function, debug only tasks with normal priority. For debugging the tasks with high priority (the tasks started with the task priority: MP_PRI_IO_CLK_TAKE, MP_PRI_IP_CLK_TAKE, or MP_TIME_CRITICAL, or task “mpUsrRoot”), use the robot variables visible on the programming pendant. This is because, if printf() or puts() is done with a high priority task, processing time for robot operation control is consumed, and a system alarm may occur due to insufficient processing time. 3. After completing debugging, make sure to disable the debugging code using printf() or puts(). This is because the processing time of printf() and puts() influences the system, and an error may occur such as insufficient processing time during robot operation. 4. When using VxWorks SHELL commands, which become available by connecting with the controller via Telnet, a system alarm may occur due to insufficient processing time for robot operation. Do NOT use the VxWorks SHELL commands. 1-4 169286-1CD 13/53 169286-1CD MotoPlus SDK for Visual Studio 2 2 SDK Installation and Setup 2.1 System Requirements SDK Installation and Setup 2.1 System Requirements The following requirements must be met for the host computer used to develop the MotoPlus application: PC with Microsoft Windows XP SP2, Vista, or 7 Windows (Not compatible with Windows 8) .Net Framework 3.5 USB Hardware Key Dongle Included with SDK package Microsoft Visual Studio 2008 Standard, Professional 2010 Professional, Premium, Ultimate Visual C++ 2010 Express (free download from Microsoft) 2012 Professional, Premium, Ultimate 2012 Express for Desktop (free download from Microsoft) 2013 Professional, Premium, Ultimate External memory card to load on robot pendant Compact Flash (CF) or USB Flash (USB) User Rights on PC Administrator rights required User Account Control (UAC) UAC must be disabled for the user account 2-1 169286-1CD 14/53 169286-1CD MotoPlus SDK for Visual Studio 2.2 2 SDK Installation and Setup 2.2 Installation of SDK Installation of SDK NOTE Do not insert the USB hardware key dongle into the computer until after installing the Sentinel driver. 1. Insert the MotoPlus SDK for Visual Studio disc into your Windows PC. If AutoRun is enabled, the installation will automatically start. Otherwise, run "setup.exe" from the root of the DVD. NOTE The license agreement is located on the root of your installation DVD. Please read this prior to installing the software. You will be required to agree to the terms of the licensing. 2. Click [Next] and continue through the installation. 3. When installation is complete, you must reboot the computer to register system environment variables required by the compiler. 4. After restarting the PC, please install the Sentinel driver located on the root of your installation DVD. This is required for the USB hardware key dongle. NOTE If you are installing the Sentinel driver on a notebook/laptop computer, it is recommended to first remove the computer from any docking station(s) prior to installation. 5. Insert the USB hardware key dongle into your PC. NOTE User Account Control (UAC) must be disabled to use the MotoPlus compiler. Installation of the SDK is now complete. 2-2 169286-1CD 15/53 169286-1CD MotoPlus SDK for Visual Studio 2.3 2.3.1 2 SDK Installation and Setup 2.3 Setup of Robot Controller Setup of Robot Controller Install VGA Adapter Cable for Debugging (DX controllers only) For DX controllers, the SDK package comes with a VGA adapter cable. This cable allows you to connect a standard VGA computer monitor to view program output. It should only be used for application debugging purposes and not shipped with a production robot controller. CAUTION Static electricity can severely damage sensitive electronics. Follow standard ESD safe procedures when handling the DX CPU board! 1. Power off the DX robot controller. 2. Locate and remove the CPU board (JANCD-YCP01 or JANCD-YCP21) in the DX controller chassis. The board is secured by two screws on top and bottom. You may also have to temporarily disconnect all cables going to connectors CN106, CN105, CN104, and CN103. 2-3 169286-1CD 16/53 169286-1CD MotoPlus SDK for Visual Studio 2 SDK Installation and Setup 2.3 Setup of Robot Controller 3. Connect the VGA adapter cable to the pin header on the CPU board. An opening is available on the front faceplate of the CPU board to route the cable out of the chassis. Carefully open the plastic tab which is securing the opening and install the cable as shown. 4. Reinsert the CPU board into the controller chassis, tighten the screws securing the board, and reconnect all cables removed in the previous steps. 2-4 169286-1CD 17/53 169286-1CD MotoPlus SDK for Visual Studio 2.3.2 2 SDK Installation and Setup 2.3 Setup of Robot Controller Enabling MotoPlus (DX200 and FS100 only) On DX200 and FS100 controllers, the MotoPlus function must be enabled in MAINTENANCE mode. 1. Boot the robot controller into MAINTENANCE mode. 2. Upgrade to MANAGEMENT level security. Touch [System] > [Setup]. 3. Select "OPTION FUNCTION". 2-5 169286-1CD 18/53 169286-1CD MotoPlus SDK for Visual Studio 2 SDK Installation and Setup 2.3 Setup of Robot Controller 4. Set "MotoPlus FUNC."To "USED". Press {ENTER} to save your change. If you are asked to "Initialize related file SRAM.DAT", touch [YES]. 2-6 169286-1CD 19/53 169286-1CD MotoPlus SDK for Visual Studio 2.4 2 SDK Installation and Setup 2.4 Enable Telnet for Debugging Enable Telnet for Debugging One of the options for debugging is to connect to the robot using a telnet connection. (See Chapter 6 "Debugging"). On Windows 7, the default telnet console is not enabled by default. This must be enabled prior to debugging. 1. Click the Windows START orb, and type "programs and features", then press [Enter]. 2. From the menu on the left, select "Turn Windows features on or off". Wi ndo wF eat ur e s 3. In the Windows Features list, check the box next to "Telnet Client" and click [OK]. 2-7 169286-1CD 20/53 169286-1CD MotoPlus SDK for Visual Studio 3 3 Creating MotoPlus Application 3.1 Rules for Application Source Code Creating MotoPlus Application 3.1 Rules for Application Source Code Be sure to observe the following rules when creating source code. Refer to the MotoPlus Programmer's manual for detailed information on programming configuration and sample programs. NOTE Sample source code files are located in your installation directory and on the MotoPlus for Visual Studio installation disc. Please remember that the source code should follow ANSI-C syntax. The only exception is that users should not define a "main (...)" function. This is replaced by "mpUsrRoot(...)". 1. Up to 32 one-byte characters can be used for a file name. Up to 16 two-byte characters can also be used. File names are case-sensitive. Set '.c' as the file extension. (C++ library is not fully supported on the MotoPlus platform) 2. Put "#include <MotoPlus.h>' at the top of each source code file. When "MotoPlus.h" is included, all services provided by MotoPlus are available. 3. MotoPlus applications do not have a "main" function. This is replaced by "mpUsrRoot". This function must have the following signature: void mpUsrRoot (int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9, int arg10) 4. mpExitUsrRoot must be called at the end of mpUsrRoot. 5. The task "mpUsrRoot" is launched at a high task priority. Due to its high task priority, if a time-consuming process (0.1 milliseconds or longer) is done in this task, the processing time for the robot control becomes insufficient. This can interrupt robot startup and freeze the pendant. Therefore, you should immediately launch a new normal priority task from mpUsrRoot and then call mpExitUsrRoot. NOTE When creating a new MotoPlus project in Visual Studio, a "main" template is automatically generated. 3-1 169286-1CD 21/53 169286-1CD MotoPlus SDK for Visual Studio 3.2 3 Creating MotoPlus Application 3.2 Creating a MotoPlus Project in Visual Studio Creating a MotoPlus Project in Visual Studio Open Visual Studio on your development PC. Select [File] > [New Project]. The MotoPlus project is found under {Templates} > {Other Languages} > {Wizards}. NOTE Do not include any spaces when naming your project. Click [OK] and a new project is created in the specified location. This project is automatically configured to build using the MotoPlus compiler. A template source file (mpMain.c) is added to the project. Also included are files which specify the project-specific arguments to the compiler and linker. NOTE The .mps files must not be removed from your MotoPlus project. 3-2 169286-1CD 22/53 169286-1CD MotoPlus SDK for Visual Studio 3 Creating MotoPlus Application 3.3 Adding Files to the Project 3.3 Adding Files to the Project Files can be added to your MotoPlus project through the standard Visual Studio interface. Right-click on the project tree and select {Add} > {New Item…} or {Add} > {Existing Item…}. Alternatively, you can perform the same action from the {Project} dropdown in the Main Menu. When adding new items to the project, the file must end in a supported extension. Header files should have a ".h" extension. Source files should have a ".c" extension. NOTE C++ (.cpp) files are not supported by the MotoPlus environment. Files for the project do not have to be in a flat directory. They can be in any folder relative to the Project Directory. 3-3 169286-1CD 23/53 169286-1CD MotoPlus SDK for Visual Studio 3.4 3 Creating MotoPlus Application 3.4 Creating a MotoPlus Library Creating a MotoPlus Library As a MotoPlus developer, you can share routines by distributing a compiled MotoPlus library. This library can be used by other developers without exposing proprietary source code. Instead of building an executable module (.out), this will build a library without the main entry point for execution. NOTE MotoPlus library files end in extension .mpLib (DX100), .fsLib (FS100), and .dnLib (DX200). Libraries must be compiled for each controller separately. A MotoPlus library is created in the same manner as a MotoPlus project. From the New Project window, select the MotoPlusLibrary wizard. 3-4 169286-1CD 24/53 169286-1CD MotoPlus SDK for Visual Studio 3 Creating MotoPlus Application 3.4 Creating a MotoPlus Library A project is generated with a template source file (mpLibrary.c) and header file (mpLibrary.h) to get you started. The project is automatically configured to build a library instead of executable file. NOTE When distributing a MotoPlus library, be sure to include a header file which provides functional declarations for each public function in your library. Function declarations should begin with "extern". Example: extern void mpLibraryFunction1(); 3-5 169286-1CD 25/53 169286-1CD MotoPlus SDK for Visual Studio 3.5 3 Creating MotoPlus Application 3.5 Using a MotoPlus Library In Your Project Using a MotoPlus Library In Your Project MotoPlus library files can be added to your project like any other file. Right-click the project tree and select {Add} > {Existing Item…}. The library developer should have also provided a header file with the declarations for all public functions in the library. Each declaration should begin with "extern". Example: extern void mpLibraryFunction1(); If your application is targeted toward multiple controller platforms, you must add a library for each controller type. When building the project, the compiler will ignore libraries which are targeted for a different controller platform. NOTE MotoPlus library files end in extension .mpLib (DX100), .fsLib (FS100), and .dnLib (DX200). 3-6 169286-1CD 26/53 169286-1CD MotoPlus SDK for Visual Studio 3.6 3 Creating MotoPlus Application 3.6 Building Your Application Building Your Application The MotoPlus application (or library) can be built directly from within Visual Studio. The project is automatically configured to pass all files in the Solution Explorer to the MotoPlus compiler. First select your target controller platform from the Configuration Manager dropdown. Co NOTE ntr o ll er You must have a license key for each target controller platform. Upgrade licenses are available for each controller type. Next, select the appropriate Build option from the {Build} menu. 3-7 169286-1CD 27/53 169286-1CD MotoPlus SDK for Visual Studio 3 Creating MotoPlus Application 3.6 Building Your Application If there are any errors/warnings in your source files, they will be displayed in the Visual Studio Error List. You can double-click the error entry to go directly to the problematic line of code. The Output pane contains the full output text of the compiler. 3-8 169286-1CD 28/53 169286-1CD MotoPlus SDK for Visual Studio 3 Creating MotoPlus Application 3.6 Building Your Application If there are no errors in the code, the Output pane will indicate "Build Successful!" By default, the compiled module will be located in the folder: <Solution Directory> \ <Controller Platform> \ <Project name> . NOTE The output directory and file name can be customized by modifying the NMake Configuration Properties. See Chapter 8 "Advanced mpBuilder Usage" for more details 3-9 169286-1CD 29/53 169286-1CD MotoPlus SDK for Visual Studio 3.7 3 Creating MotoPlus Application 3.7 Building Your Project for Multiple Controller Platforms Building Your Project for Multiple Controller Platforms The MotoPlus for Visual Studio SDK allows you to build your source code for each of the MotoPlus-enabled Motoman robot controllers. This allows you to use the same source code project for each controller. However, there are minor differences between each controller which may affect your application. For example, the Network Inputs I/O addresses start at #25010 for DX100 and FS100. However, the starting address is #27010 on the DX200. For this reason, the build environment has been configured to automatically provide a pre-processor definition for each controller type. Using preprocessor directives, you can put a decision statement around your code at compile-time, instead of run-time. Example: //evaluated at compile-time #if (DX100 || FS100) #define STARTING_NETIN_ADDRESS 25010 #elif (DX200) #define STARTING_NETIN_ADDRESS 27010 #endif void myFunction() { //set at run-time int startingIoAddress = STARTING_NETIN_ADDRESS; } NOTE You must have a license key for each target controller platform. Upgrade licenses are available for each controller type. 3-10 169286-1CD 30/53 169286-1CD MotoPlus SDK for Visual Studio 4 4 Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode 1. Load Function Load the application program and install by following the instructions below. (1) Boot the robot controller into Maintenance Mode by holding [Main Menu] on the programming pendant. (2) Set the security mode to MANAGEMENT MODE. Select the main menu {MotoPlus APL.}. Then {LOAD (USER APPLICATION)}, {FILE LIST (DX)}, {DELETE (DX)}, {DEVICE}, {FOLDER}, and {MotoPlus FUNC. SETTING} appear as submenus. (3) Specify the file location. Select an appropriate file location with the submenus {DEVICE (to select CF/USB)} and {FOLDER (to select the folder which has the application program)}. 4-1 169286-1CD 31/53 169286-1CD MotoPlus SDK for Visual Studio 4 Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode (4) Select and load a file. • Select the submenu {LOAD (USER APPLICATION)}. Then, “*.out” files in the specified folder appear as shown below. • Move the cursor and press [SELECT]. Then, the selection indicator “ ” appears on the left of the application file name. Press [SELECT] again to clear “ ”. • Press [ENTER], then the following confirmation dialog box appears. 4-2 169286-1CD 32/53 169286-1CD MotoPlus SDK for Visual Studio 4 Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode • When {YES} is selected and the selected application file contains the file which already exists in the controller, the following confirmation dialog box appears. Select “YES” to load. 2. List Select the submenu {FILE LIST (DX)}. Then, the list of the application files which already exist in the controller appears. 3. Deletion of application program By the submenu {DELETE (DX)}, the application file which already exists in the controller can be deleted. (1) Move the cursor and press [SELECT]. Then, the selection indicator “ ” appears on the left of the application file name. Press [SELECT] again to clear “ ”. 4-3 169286-1CD 33/53 169286-1CD MotoPlus SDK for Visual Studio 4 Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode (2) Press [ENTER], then the following confirmation dialog box appears. 4. MotoPlus function setting When selecting “MotoPlus FUNC. SETTING”, the following windows appear to enable or disable the autostart of the MotoPlus application program. For the detailed usage methods, refer to Section 4.2 “Startup of Application Program” on page 4-6 and Section 4.3 “To Temporarily Prevent MotoPlus Application from Starting” on page 4-6. (1) Move the cursor and press [SELECT]. The setting is changed from “ENABLE” to “DISABLE”. NOTE This screen may have different options based on which robot controller is being used. Please refer to your Programmer's Manual for more details. 4-4 169286-1CD 34/53 169286-1CD MotoPlus SDK for Visual Studio 4 Installation and Startup of MotoPlus Application 4.1 Installation of Application Program in Maintenance Mode (2) Press [ENTER], and then the confirmation dialog box appears. (3) Select {YES}. –When {YES} is selected on the confirmation dialog box, the parameter is set automatically, and then it returns to the MotoPlus setting window. 4-5 169286-1CD 35/53 169286-1CD MotoPlus SDK for Visual Studio 4.2 4 Installation and Startup of MotoPlus Application 4.2 Start-up of Application Program Start-up of Application Program When the controller is turned ON, the application program is loaded automatically and started. <Limitations> • Only one “*.out” file can be loaded. Thus, install only one application. If two or more applications are installed, the alarm 1020: “MOTOPLUS APPLICATION LOAD ERROR [1]” occurs on loading. The error status can be checked by reading $B051 from the job. • The loadable memory size is up to 2 Mbyte as the total of the code area and the static memory area. If it is more than 2 Mbyte, the start-up fails and the alarm 1020: “MOTOPLUS APPLICATION LOAD ERROR [4]” occurs on loading. The error status can be checked by reading $B051 from the job. $B051 4.3 0: The application is loaded successfully on start-up. 1: The number of files exceeds the limit. 2: The memory is insufficient. (Available memory area is less than 2 Mbyte.) 3: APPLICATION folder cannot be found in the CF. 4: The size of the MotoPlus application exceeds the limit. To Temporarily Prevent MotoPlus Application from Starting Due to a problem of the application program, the system may hang up during robot operation, and then the controller may not start normally. For recovery, it is necessary to start the controller normally while preventing the application program from operating. In this case, it is necessary to start the controller in the MAINTENANCE mode, change the settings so that the application program does not operate, start the controller normally, and operate the robot. Follow one of the following two procedures: 1. Start the controller in the MAINTENANCE mode, set the security mode to the MANAGEMENT MODE. Select “MotoPlus APL.”, then “DELETE (DX)” to delete the application. 2. Start the controller in the MAINTENANCE mode, set the security mode to the MANAGEMENT MODE. Select “MotoPlus APL.”, then “MotoPlus FUNC. SETTING” to show the setting window. Then set “APPLI. AUTOSTART AT POWER ON” to “DISABLE”. If the above problem occurs during robot operation, choose the procedure 2. The above problem during robot operation may be caused by a specific condition. If the MotoPlus application is deleted with the procedure 1, after the specific condition is cleared, the MotoPlus application must be loaded again in the CF for recovery. In this case, if the application to be loaded does not exist there, the application cannot operate and the system cannot recover. 4-6 169286-1CD 36/53 169286-1CD MotoPlus SDK for Visual Studio 5 5 User Defined File 5.1 Saving in and Reading from External Memory User Defined File (DX200 and FS100 only) NOTE This feature is not available on a DX100 controller. With MotoPlus, user defined files can be created, read, written, deleted, etc. from an application by using the file control. These files saved/loaded into the robot CMOS by using an external memory card (CF or USB) in the programming pendant. NOTE 5.1 MotoPlus File API's do not have direct access to the CF/USB drives connected to the pendant. The file API's can only access (or create) files stored in the robot CMOS memory. Saving in and Reading from External Memory Saved files can be checked on the display of the programming pendant as “USER DEFINED FILE”. The files can be saved in or read from external memory such as CF or USB on this display. 5.1.1 Procedure to Save or Read User Defined File 1. Start in the normal mode, and select {EX. MEMORY}, then {SAVE} or {LOAD}. 5-1 169286-1CD 37/53 169286-1CD MotoPlus SDK for Visual Studio 5 User Defined File 5.1 Saving in and Reading from External Memory 2. Select {USER DEFINED FILE}. 3. Select a file to be saved in external memory or to be loaded from external memory to the controller. 4. appears on the left of the selected file. Multiple files can also be selected. 5-2 169286-1CD 38/53 169286-1CD MotoPlus SDK for Visual Studio 5 User Defined File 5.1 Saving in and Reading from External Memory 5. Select a file and press [ENTER], then the following window appears. Select “YES”. 5-3 169286-1CD 39/53 169286-1CD MotoPlus SDK for Visual Studio 5.2 5 User Defined File 5.2 Initialization of User Defined File Initialization of User Defined File CAUTION This will delete all User Defined Files stored in robot CMOS memory. 1. Start the controller in the maintenance mode. Then, select {Main Menu}, {FILE}, then {INITIALIZE}. 2. Select “USER DEFINED FILE”. 5-4 169286-1CD 40/53 169286-1CD MotoPlus SDK for Visual Studio 5 User Defined File 5.2 Initialization of User Defined File 3. Select “SRAM RAM DRIVE SRAMDRV .DAT”. 4. appears as shown below. 5. Press [ENTER], then the following window appears. Select {YES}. 5-5 169286-1CD 41/53 169286-1CD MotoPlus SDK for Visual Studio 5.3 5 User Defined File 5.3 Setting of File Control Task Priority Limit Setting of File Control Task Priority Limit Only the normal priority (MP_PRI_TIME_NORMAL) is used as the task priority for the file control API. When the file control API is used from the task with higher priority, the operation differs depending on the setting of the parameter S2C1101 as shown in the following table. This setting can also be changed by using “FileControl TASK PRY. LIMIT” in maintenance mode. 5.3.1 S2C1101 FileControl TASK PRY. LIMIT Operation 0 LIMITED The API returns an error. 1 (default value) AUTO Temporarily changes the task priority to MP_PRI_TIME_NORMAL and executes the API. Changing File Control Task Priority Limit 1. Start in maintenance mode. Select {Main Menu}, {MotoPlus APL.}, then {MotoPlus FUNC. SETTING}. 5-6 169286-1CD 42/53 169286-1CD MotoPlus SDK for Visual Studio 5 User Defined File 5.3 Setting of File Control Task Priority Limit 2. Press [SELECT] at “FileControl TASK PRY. LIMIT” to select “LIMITED” or “AUTO”. 3. Press [ENTER], then select {YES} in the “Modify?” window to complete the setting. 5-7 169286-1CD 43/53 169286-1CD MotoPlus SDK for Visual Studio 6 6 Debugging 6.1 Debugging Environment Debugging 6.1 Debugging Environment Due to the nature of the real-time robotic system, MotoPlus applications cannot be debugged using a traditional source-level debugger. The most effective way to debug a MotoPlus application is to monitor application output. This is done by setting variables and I/O to view on the pendant, or by printing to standard output (stdout) within your application. Print-statements sent to stdout can be viewed by using one of two methods. On DX robot controllers, your SDK comes with a VGA adapter cable to connect a standard computer monitor to the robot controller. Alternatively, you can connect to the robot via telnet to view output within a console window on your PC. NOTE 6.2 Print-statements are extremely time consuming during execution. It is highly recommended to put a debug-switch around all print statements so that they can be disabled for final release. Commands for Printing to Standard-output (stdout) The commands "puts" and "printf" are available to print to stdout. The command “puts” will print a string and automatically append a new line. The command “printf” is used to print a formatted string with variable arguments. The line-feed is not automatically appended to printf strings. 6.3 Viewing Output on Computer Monitor (DX100 and DX200 only) Please see Section 2.3.1 “Install VGA Adapter Cable for Debugging” on page 2-3 for instructions on installing the VGA adapter cable included with the SDK. To view output using the monitor, the monitor must be connected prior to turning on the robot controller. If the monitor is blank, please cycle power on the DX robot controller. 6-1 169286-1CD 44/53 169286-1CD MotoPlus SDK for Visual Studio 6.4 6.4.1 6 Debugging 6.4 Viewing Output on PC Console Window Viewing Output on PC Console Window Setup of Robot Controller Please see Section 2.4 “Enable Telnet for Debugging” on page 2-7 for instructions on enabling the Windows Telnet Client in Windows 7. Set robot parameter S2C1119 = 2 to enable telnet output. The robot must be rebooted after setting this parameter. NOTE When debugging is completed, be sure to set S2C1119 = 0. This will prevent the telnet task from interfering with robot operation. Connect your development PC to the robot controller LAN port via Ethernet connection. DX Controller With a Hub Without a Hub 㑅ࠉᢥ X- X+ Y- Y+ Z- Z+ S- X- S+ 㑅ࠉᢥ X+ R- R+ Y- Y+ Z- Z+ T- T+ X- X+ Y- Y+ Z- Z+ S- X- S+ 㧗㏿ L- U- 7- B- L- B+ 㧗 U- ప 7+ X+ R- R+ Y- Y+ Z- Z+ T- T+ 㧗㏿ L+ U+ 7- L+ B- B+ 㧗 U+ ప 7+ 7 8 9 7 8 9 4 5 6 4 5 6 1 2 3 1 2 3 0 . - 0 . - Devices such as Vision sensor to be connected via Ethernet Robot Controller Development PC Robot Controller Development PC YCP21 <&3 &1 CN105 Ethernet Ethernet &1 CN104 Hub FS Controller With a Hub Without a Hub 㑅ࠉᢥ X- X+ Y- Y+ Z- Z+ S- X- S+ 㑅ࠉᢥ X+ R- R+ Y- Y+ Z- Z+ T- T+ X- X+ Y- Y+ Z- Z+ S- X- S+ 㧗㏿ L- U- 7- B- L- B+ 㧗 U- ప 7+ X+ R- R+ Y- Y+ Z- Z+ T- T+ 㧗㏿ L+ U+ 7- L+ B- B+ 㧗 U+ ప 7+ 7 8 9 7 8 9 4 5 6 4 5 6 1 2 3 1 2 3 0 . - 0 . - Devices such as Vision sensor to be connected via Ethernet Robot Controller Development PC Robot Controller Development PC CPU201R &385 &1 CN3 Ethernet Ethernet &1 CN2 Hub 6-2 169286-1CD 45/53 169286-1CD MotoPlus SDK for Visual Studio 6.4.2 6 Debugging 6.4 Viewing Output on PC Console Window Establishing Telnet Connection • Your computer IP address must be on the same subnet as the robot controller. – Example: Robot IP - 192.168.255.1 Computer IP - 192.168.255.xxx NOTE • Alarms such as "0500 SEGMENT PROC NOT READY" may occur when using the telnet connection. This is because the telnet task runs at a high priority in the system and can interfere with robot operation. If the alarm occurs, reboot the robot controller. – Set S2C1119 = 0 when you are done debugging to prevent these alarms during normal operation. 6.4.2.1 Automatic Login to Telnet Shell (DX200 and FS100) On the DX200 and FS100 controller, an automatic login utility is provided with the MotoPlus for Visual Studio installation. This is accessed from the START menu under Motoman \ MotoPlus Debugging. Prior to opening the automatic login utility, you must input the IP address of the robot controller. An .ini configuration file is located in your MotoPlus for Visual Studio installation directory. (Default: C:\Program Files (x86)\Yaskawa\MotoPlus for Visual Studio\Telnet Debugging) Open the .ini file for your target controller. Modify the value of "ipaddress" to match your robot controller. After saving this file, you can now open the automatic login utility. After opening the automatic login utility, do not click any other windows until the login process is complete. The process is completed when you see the telnet shell prompt "->". 6-3 169286-1CD 46/53 169286-1CD MotoPlus SDK for Visual Studio 6 Debugging 6.4 Viewing Output on PC Console Window 6.4.2.2 Manual Login to Telnet Shell (all controllers) As an alternative to the automatic login utility, you can manually login to the telnet shell. Open a Windows console window. The easiest method is through the "Run…" command in the START menu. START > Run… > Type "cmd" Type "telnet" to open the Windows Telnet Client utility. Then type "open <ipaddress>" to open a connection to the robot. It will prompt you for the VxWorks login information. You have 30 seconds to type in the login username and password before it times out. Controller Username Password DX100 Net_Maint_Mng 99999999 DX200 MOTOMANrobot MOTOMANrobot FS100 MOTOMANrobot MOTOMANrobot If the login is successful, the console window will display the shell prompt "->". 6-4 169286-1CD 47/53 169286-1CD MotoPlus SDK for Visual Studio 7 7 Alarm List Alarm List Alarm Number 1020 Alarm Name MOTOPLUS APPLICATION LOAD ERROR Subcode Meaning 1 Too many MotoPlus applications (.out files) are loaded in the controller. 2 The MotoPlus application is too large. (Available memory area is 2 Mbyte.) 3 Failed to open the directory. 4 Load failure (Failed to open the file.) 5 Load failure (Undefined symbol) (You declared an external function or variable that was never defined in the system) 6 Load failure (Others: application overloaded) (Verify that your .out file has been compiled for the correct robot controller) 7 Failed to initialize the API library. 8 No user root task. 9 Failed to create the user root task. 10 Failed to create RAM-Disk. 4478 MM TASK NO RESPONSE (MotoPlus) The process requested from the MotoPlus application to the MM task was not completed within the specified time. 4479 MOTOPLUS MM TASK WATCHDOG ERROR The man-machine task does not run for 3 seconds or more. 7-1 169286-1CD 48/53 169286-1CD MotoPlus SDK for Visual Studio 8 8 Advanced mpBuilder Usage 8.1 Visual Studio MakeFile Project Advanced mpBuilder Usage mpBuilder is the compile system utilized by MotoPlus for Visual Studio. This section describes the advanced usage for the build system. This should only be modified by experienced developers. 8.1 Visual Studio MakeFile Project When select a MotoPlus Project from the New Project menu, the wizard is creating a Visual Studio MakeFile project. This project type in Visual Studio issues a command line call to a custom compiler. The Build Command Line command can be viewed under {Project} > {Properties} > {Configuration properties} > {NMake}. The default build command is: mpbuilder.exe -c $(Configuration) -p "$(ProjectDir)\" -n "$(ProjectName)" -b "$(OutDir)\" -o build The default clean command is: mpbuilder.exe -c $(Configuration) -p "$(ProjectDir)\" -n "$(ProjectName)" -b "$(OutDir)\" -o clean The fields $(…) are Microsoft macros for MSBuild. These are documented online on the MSDN website. 8-1 169286-1CD 49/53 169286-1CD MotoPlus SDK for Visual Studio 8 Advanced mpBuilder Usage 8.1 Visual Studio MakeFile Project Using the $(…) syntax, you can also insert any system Environment Variables into the command line. Example: $(MP_VS_Install) evaluates to the MotoPlus installation directory. The default commands do not use all of the available command-line arguments for mpBuilder. Here is a list of all available arguments: • -c, --controller Required. Target Yaskawa Motoman robot controller platform. DX100, DX200, FS100 • -p, --projectFolder project. Required. Root folder for the MotoPlus • -n, --projectName Required. Name of your MotoPlus project. • -o, --operation Required. Build operation to perform. 'build' = Build Project. 'clean' = Delete output files. 'rebuild' = Clean then build. • -b, --binaryLocation Path to the output binary. If this is not specified, it will default to [ProjectDir]\output. • -i, --includeDir This is the path to the standard includedirectory for your MotoPlus API header files. If this is not specified, it will default to [InstallDir]\[Controller]\inc. • -e, --encoding The character encoding of your source files. Example: "us-ascii" or "utf-8". A list of supported encodings can be found in the Microsoft documentation for EncodingInfo.Name • -l, --library 'Y' if you are building a MotoPlus Library file. 'N' if you are building a .out Executable module. • -d, --dontParseErrors 'T' (true) if you want to see the unmodified error/warning strings returned from the compiler. Otherwise, they will be parsed and formated to be recognized by Visual Studio. • -v, --visualStudioVersion Must be specified for VS2008 (v=9). Ignored for Visual Studio 2010 - 2013. 8-2 169286-1CD 50/53 169286-1CD MotoPlus SDK for Visual Studio 8.2 8 Advanced mpBuilder Usage 8.2 Compiler Arguments Compiler Arguments The specific compiler will vary based on which robot controller is selected. The proper one is selected based on the arguments specified for mpBuilder. Regardless of which controller is selected, the final compiler will be part of the GCC build system. The arguments for the GCC build system are specified in the .mps files, which are automatically added to your MotoPlus for Visual Studio project. NOTE 8.2.1 Please see the GCC documentation for all available arguments to the build system. CompilerArguments.mps This file is used when compiling source files into binary objects. This can be used to control many variables in the build system. • Project-wide DEFINE statements • Enable/disable particular errors and warnings • Compiler code optimization (not recommended) • Directories to search for include-files for the project There are macros which can be placed in the .mps file which will be recognized by mpBuilder and resolved prior to calling the compiler. • ~ProjectDir~ : This will resolved to the temporary directory where the source files are copied and converted to ascii encoding at build time. • ~IncludeDir~ : This is the standard include directory to search for MotoPlus API header files. If the -i argument is specified to mpBuilder.exe, then this macro will resolve to the value of the -i argument. Otherwise, it will default to [MP_VS_Install]\[Controller]\inc • ~FilePath~ : This will resolve to the full path of the source file being compiled. Please note that it will point to the ascii copy of the source file, located in the temp directory. • ~OutputPath~ : This will resolve to the full path of the compiled object file which is the output from the compiler. 8.2.2 LinkerArguments.mps This file is used when linking the compiled object files into a single binary executable/library. There are macros which can be placed in this .mps file which will be recognized by mpBuilder and resolved prior to calling the compiler. • ~FileList~ : This is the list of compiled object files which will be combined into the final output file. • ~OutputPath~ : This is the full path to the final output file. 8-3 169286-1CD 51/53 169286-1CD MotoPlus SDK for Visual Studio Appendix A Appendix A Revision History Revision History Date CEN / ECN Revision No. Reason For Revision Initials 4/4/2014 46935 0 Original Release JFC A-1 169286-1CD 52/53 MOTOPLUS SDK FOR VISUAL STUDIO USER’S MANUAL (DX100, DX200, AND FS100) Specifications are subject to change without notice for ongoing product modifications and improvements. MANUAL NO. 169286-1CD 0 53/53
© Copyright 2024