================================================== DRAPE2 (Developing Robotic Arm Programming Environment 2) By JF Software - Joshua Foster http://www.jfsoftware.net joshua_70448@ureach.com June 14, 2003 ================================================== TABLE OF CONTENTS ================= * Introduction * The Main Window * The Task Manager * RCX Diagnostics * RCX Direct Control * Motor Settings * Language Reference * Error Messages * How to Contact INTRODUCTION ============ DRAPE2 is a programming language and environment for robotic arms made using the LEGO Mindstorms (c) construction set. In this version, it supports motor control, limited and unlimited looping, up to 10 separate sub-tasks, and inline comments. It also features a built-in debugger, pop-up reference sheet, diagnostics screen, and direct control window with macro recording feature (WYSIWYG-What You See Is What You Get). An important note: This software only supports SERIAL infrared towers: the USB towers are not supported by this version of the SPIRIT control (if you have a newer SPIRIT.OCX file, please give me a copy!). All new features are indicated with a ***NEW*** signal. THE MAIN WINDOW =============== The very first time you use DRAPE2, the first window that will appear is the Change Motor Settings window. This window lets you adapt DRAPE2 to accomodate your robotic arm's configuration. See "Motor Settings" for more information about the Change Motor Settings window. After the first time, when you open DRAPE2, only four things will appear: * The Menu Bar * The Tool Bar * The Program Editor * The Status Bar When you debug a program, another element will appear below the program editor: * The Error Console The Menu Bar ------------ File: New: Creates a new DRAPE program. (Ctrl+N) Open: Opens a previously saved DRAPE program. (Ctrl+O) Save: Saves the current DRAPE program. (Ctrl+S) Save As: Saves the current DRAPE program in a specific location. Exit: Exits the DRAPE2 editor. Port: Select Com Port: Lets you select which COM port to use with your infrared tower. Automatic (default): ***NEW*** Automatically searches for an available COM port. 1-4: Specifies a COM port to use. Initialize: Attempts to open the COM port for use with your robotic arm. One of several events will occur in the lower status bar: (F2) "Error: Can't open port and/or RCX (COMx)": Automatic search didn't find an available COM port. "Error: Can't open port (COMx)": Can't open the COM port (or no tower). "Port not open (RCX not found) (COMx)": Opened the COM port, but couldn't find an RCX. "Port initialized (COMx) but no firmware": Found an RCX, but there's no firmware loaded. (See Port>Download Firmware to download firmware) "Port initialized (COMx) with firmware": Found an RCX and ready to use. Test: Tests the COM port to see if everything's working: (F3) "Error: Tower not connected correctly (COMx)": No tower connected. "Error: Tower not functioning correctly (COMx)": Tower's not working right, or the battery's dead. "Error: No RCX found (COMx)": Tower works, but no RCX found. "Port initialized (COMx) and ready but no firmware": Found an RCX, but there's no firmware loaded. (See Port>Download Firmware to download firmware) "Port initialized (COMx) and ready with firmware": Found an RCX and ready to use. Close: Closes the COM port. (F4) Initialize on Startup (default): When this option is checked, DRAPE2 will automatically initialize the COM port when you start it. Download Firmware: Allows you to download a firmware program to your RCX. Browse using the Open dialog for your firmware (.lgo) file, or use the one included in the DRAPE2 package (firm0309.lgo). After a few minutes, the lower status bar will display one of two messages: (F12) "Error: Firmware download failed (Unlock) (COMx)": DRAPE2 couldn't unlock the new firmware for some reason. Try again, and if you fail again, use your standard LEGO software to reload your firmware. "Port initialized (COMx): downloaded firmware successfully": Firmware was successfully downloaded to the RCX. Program: Debug: Runs the automatic debugger and reports any errors found in the error message console (See View>Error Console to display/hide the error console) (Also see "The Error Console" for more information about the error console) (F5) Slot: Lets you select which program slot to use on the RCX for your program. 1-5: Selects a program slot to use. Download: Tests and downloads your program to the RCX. (F6) Download and Run: ***NEW*** Same as Program>Download, but runs the program after loading. (Shift+F6) Start Program: ***NEW*** Starts the program on the RCX in the currently selected program slot. (Does not load any new programs) Stop Program: ***NEW*** Stops any running programs on the RCX. Tasks: Task Manager: Opens the Task Manager window. (See "The Task Manager" for more information about the Task Manager) (F7) Next Task: Switches to the next task in line. (F8) Tools: Reference Sheet: Opens the quick Reference Sheet to the right of the DRAPE2 window. This shows all available commands and their syntax. (F1) RCX Diagnostics: Opens the RCX Diagnostics window. (See "RCX Diagnostics" for more information about the RCX Diagnostics window) (F9) RCX Direct Control: ***NEW*** Opens the RCX Direct Control window. (See "RCX Direct Control" for more information about the RCX Direct Control window) (F11) Change Motor Settings: ***NEW*** Opens the Change Motor Settings window to allow you to adapt DRAPE2's settings to your specific robotic arm. (See "Motor Settings" for more information about the Change Motor Settings window) View: Error Console: ***NEW*** Select this option to show or hide the error console, shown below the program editor in a grayed-out box. (See "The Error Console" for more information about the error console) Help: About: ***NEW*** Shows the author information and provides links to the author's email address and this readme document. (Shift+F1) The Tool Bar ------------ There are currently 17 buttons on the tool bar, each corresponding to a menu bar selection (see above for more information about each function): * New ==> File>New * Open ==> File>Open * Save ==> File>Save * Open Com Port ==> Port>Initialize * Test Com Port ==> Port>Test * Close Com Port ==> Port>Close * Debug Program ==> Program>Debug * Download Program ==> Program>Download * Download and Run Program ***NEW*** ==> Program>Download and Run * Start Program ***NEW*** ==> Program>Start Program * Stop Program ***NEW*** ==> Program>Stop Program * Task Manager ==> Tasks>Task Manager * Next Task ==> Tasks>Next Task * Reference Sheet ==> Tools>Reference Sheet * RCX Diagnostics ==> Tools>RCX Diagnostics * RCX Direct Control ==> Tools>RCX Direct Control * About DRAPE2 ==> Help>About The Program Editor ------------------ This is where you actually create your DRAPE2 programs. Keep in mind which task you are currently editing, however, by looking at the upper status bar. (See "The Task Manager" for more information about tasks) The Status Bar -------------- There are two status bars, upper and lower. The upper status bar shows the current task, editor row, editor column, and the status of certain "toggle" keys on the keyboard. The lower status bar shows messages about the DRAPE2<>RCX connection, program information, and other important messages. The Error Console ----------------- The error console isn't normally shown. To view this element, check it off under the View>Error Console menu selection, or debug your program. Normally, this box should show "No errors", meaning that your program was okay during the last debug. However, if you get errors during debugging or downloading, you can see each error in detail in this box. If you click on a certain error, the pertinent task will appear and the cursor will move to the error's location. For more information about each error in detail, see the "Error Messages" section. THE TASK MANAGER ================ In the DRAPE2 environment, you can have up to 10 "tasks." The main task, the one you start in and work the most in, is considered task number 0. You can add tasks 1 through 9. A task is a sort of subroutine that you can call to run a certain chunk of code in the middle of your program. By opening the Task Manager via the Tasks>Task Manager menu item, you can manipulate and view these tasks. Also, you can check your current task by looking at the upper status bar. NOTE: You must reference every task you use with at least one GOTO statement in the main task. If you don't, you will get an "unreferenced task" error. (See the "Language Reference" and "Error Messages" sections for more information on these topics) In the Task Manager window, you can see your current task, a list of available tasks, and 5 buttons: * Go To Task: Switches the program editor to show the selected task. * Delete Task: Deletes the selected task (you can't delete the main task). When you delete a task, all GOTO references to that task are remarked out ('). Also, all GOTO references to tasks after the deleted one are adjusted to match the changes. * Add Task: Adds a new task to the end of the list. * Rename Task: Gives a new name to the selected task (just for your purposes) (you can't rename the main task) * Close: Closes the Task Manager window. RCX DIAGNOSTICS =============== This window shows the DRAPE2<>RCX connection status and the RCX's battery level (if available). You must be connected to an RCX to access this window. The four status labels are: * Tower connected: An infrared tower is connected to the current COM port. * Tower working: The tower is working correctly (and has battery power). * RCX found: An RCX is within range of the infrared tower. * Battery level: This shows the current battery power level in the RCX in millivolts (1000 millivolts=1 volt). Also, a bar to the right graphically displays the battery level. Also, you can click the Turn Off RCX button to turn off the RCX. RCX DIRECT CONTROL ================== ***NEW*** With this window, you can directly control (in real-time) what your robotic arm does. There are four sections in this window: * Arm: * Raise: Tells the arm to go up until told otherwise. * Stop: Stops the arm. * Lower: Tells the arm to go down until told otherwise. * Power: Changes the power level of the arm's motor, from 0 to 7 (7 being strongest) * Base: * Left: Tells the base to go left until told otherwise. * Stop: Stops the base. * Right: Tells the base to go right until told otherwise. * Power: Changes the power level of the base's motor, from 0 to 7 (7 being strongest) * Claw: * Open: Tells the claw to open until told otherwise. * Stop: Stops the claw. * Close: Tells the claw to close until told otherwise. * Power: Changes the power level of the claw's motor, from 0 to 7 (7 being strongest) * Buttons: * Beep: Tells the RCX to beep once. * Turn Off: Turns off the RCX. * Close: Closes the RCX Direct Control window. * Record: This is a sort of "macro recording" feature. This records your actions on the RCX into a new program. Click this button to start recording, then use any controls in the Arm, Base, or Claw sections, along with the Beep and Turn Off buttons. If you click the Turn Off, Stop Record, or Close button while recording, recording will stop, and your new program will appear in the program editor. MOTOR SETTINGS ============== This window lets you adapt DRAPE2's actions to suit your particular robotic arm setup. You can change the motor outputs for the arm, base, and claw motors, invert the controls (ie: if you have the connectors reversed on your RCX), or disable a control altogether (ie: if you don't have a base motor). There are three sections in this window: * Arm: * None: Disables all arm commands. * Output A: Sets the arm motor to output A on the RCX. * Output B: Sets the arm motor to output B on the RCX. * Output C: Sets the arm motor to output C on the RCX. * Inverted: Inverts the arm motor's movements. Use this as a reference: * If forward raises your arm, leave this unchecked. * If forward lowers your arm, check this box. * Base: * None: Disables all base commands. * Output A: Sets the base motor to output A on the RCX. * Output B: Sets the base motor to output B on the RCX. * Output C: Sets the base motor to output C on the RCX. * Inverted: Inverts the base motor's movements. Use this as a reference: * If forward turns your arm left, leave this unchecked. * If forward turns your arm right, check this box. * Claw: * None: Disables all claw commands. * Output A: Sets the claw motor to output A on the RCX. * Output B: Sets the claw motor to output B on the RCX. * Output C: Sets the claw motor to output C on the RCX. * Inverted: Inverts the claw motor's movements. Use this as a reference: * If forward opens your claw, leave this unchecked. * If forward closes your claw, check this box. LANGUAGE REFERENCE ================== Contents: * How to Use * Arm Commands * Base Commands * Claw Commands * Looping Commands * Task Commands * Miscellaneous Commands How To Use ---------- For each entry, the short description is shown to the right, followed by a syntax example to the left. Following is a full description of the command and explanations of the pertinent variable (a number that you supply), if applicable. Note that variables are the only lower-case items in a syntax example. Arm Commands ------------ Raise Arm: ARM;U;msec Instructs the arm to move up for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Lower Arm: ARM;D;msec Instructs the arm to move down for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Stop Arm: ARM;S Instructs the arm to stop moving. Arm Power: ARM;P;power Sets the power level of the arm's motor. power: Power level of the motor (0=weakest, 7=strongest) Base Commands ------------- Turn Left: BASE;L;msec Instructs the base to turn left for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Turn Right: BASE;R;msec Instructs the base to turn right for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Stop Base: BASE;S Instructs the base to stop moving. Base Power: BASE;P;power Sets the power level of the base's motor. power: Power level of the motor (0=weakest, 7=strongest) Claw Commands ------------- Open Claw: CLAW;O;msec Instructs the claw to open for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Close Claw: CLAW;C;msec Instructs the claw to close for a certain amount of time. msec: Tens of milliseconds active (0 for infinitely on). (100 equals one second) Stop Claw: CLAW;S Instructs the claw to stop moving. Claw Power: CLAW;P;power Sets the power level of the claw's motor. power: Power level of the motor (0=weakest, 7=strongest) Looping Commands ---------------- Loop: LOOP;numloops Instructs the RCX to loop the following commands for a certain number of iterations. The looped commands fall between the LOOP command and its corresponding ENDLOOP command. LOOPs can be nested as long as each LOOP has a correctly placed ENDLOOP. numloops: Number of times to loop (0 for infinite loop) End Loop: ENDLOOP Ends the LOOP structure. Task Commands ------------- Note: None of these commands may be used in any tasks except the main task (task 0) Go To Task: GOTO;tasknum Transfers program control to a subroutine task. When the task is completed, the program will return to the next command after the GOTO command. Note that every used task must have a corresponding GOTO command in the main task. tasknum: Task number to subroutine to (1 thru 9) Start Program: STARTPROG This special command must be placed before any commands in the main task. Any commands placed before the STARTPROG command will be ignored. End Program: ENDPROG This special command must be placed after all program commands in the main task. Any commands placed after the ENDPROG command will be ignored. Miscellaneous Commands ---------------------- Beep: BEEP Instructs the RCX to emit a single beep sound. Wait: WAIT;msec Instructs the RCX to wait a specified amount of time before executing any more commands. msec: Tens of milliseconds waiting. (100 equals one second) Power Down: OFF Instructs the RCX to turn itself off. Remark Line: ' When this character is placed at the beginning of a line, the entire line is ignored as a remark line. This is useful for placing in-line comments in a program. (To place comments in the beginning or end of programs, try placing them before STARTPROG and after ENDPROG; you don't need to use the ' character in those situations) ERROR MESSAGES ============== There are five distinct groups of error messages: * Main task format errors * Command errors * Parameter errors * Loop errors * Task errors Main task format errors ----------------------- 101: ErrNoStart: Problem: The STARTPROG command was not found in the main task. Solution: Place a STARTPROG command in the beginning of your main task code. Also, check the spelling of any existing STARTPROG commands. 102: ErrNoEnd: Problem: The ENDPROG command was not found in the main task. Solution: Place an ENDPROG command at the end of your main task code. Also, check the spelling of any existing ENDPROG commands. Command errors -------------- 201: ErrNotValid: Problem: The command on this line is not recognized at all. Solution: Check to make sure you used the correct command spelling. 202: ErrBadCommand: Problem: The command on this line was recognized, but not formatted correctly. Solution: Check for extra semicolons or other characters on the end of commands. Also, check for extra parameters. Parameter errors ---------------- 301: ErrFewParams: Problem: There aren't enough parameters for the command on this line. Solution: Check the command's syntax in the language reference above. Also, make sure you included all required semicolons in the command. 302: ErrManyParams: Problem: There are too many parameters for the command on this line. Solution: Check the command's syntax in the language reference above. Also, make sure you included all required semicolons in the command. 303: ErrBadParam: Problem: The parameter given for a command was out of the acceptable range. Solution: Check the command's syntax in the language reference above for acceptable ranges for values. Loop errors ----------- 401: ErrNoEndLoop: Problem: A LOOP command is missing its ENDLOOP counterpart. Solution: Check through all of your LOOP-ENDLOOP pairs to make sure none are missing. Also, check the spelling on all ENDLOOP commands. 402: ErrNoLoop: Problem: An ENDLOOP command is missing its LOOP counterpart. Solution: Check through all of your LOOP-ENDLOOP pairs to make sure none are missing. Also, check the spelling and formatting on all LOOP commands. Task errors ----------- 501: ErrNoGoto: Problem: A task in your program doesn't have at least one GOTO command referencing it in your main task. Solution: Check all GOTO commands for spelling errors. If none found, add at least one GOTO command for that extra task or remove the task. 502: ErrEmptyTask: Problem: A task you added to your program has no useful code. Solution: Remove any extra tasks and check others for spelling or formatting errors. Also, if the task in question is the main task, make sure you have a STARTPROG command and it is spelled correctly. 503: ErrNoTask: Problem: A GOTO command in your program references a task that doesn't exist. Solution: Check the GOTO command to make sure that the correct number is specified. Also, make sure that you haven't deleted the required task by accident. HOW TO CONTACT ============== Contact name: Joshua Foster Email: joshua_70448@ureach.com Webpage: http://www.jfsoftware.net