Purdue Robotics Operating System 2b10
Simple, high-performance operating system for the VEX Cortex Microcontroller
PROS is a lightweight and fast alternative operating system for the VEX Cortex Microcontroller. It features multitasking, low-level control, and Wiring compatible functions to harness the full power of the Cortex.
Nextto install PROS. Additional prompts may appear for the installation of Java or the VEX drivers.
.debfile will successfully install PROS and all its dependencies. If this does not work, open a terminal in the directory where PROS was downloaded and run
sudo dpkg -i prose*.deb; sudo apt-get -f install
/opt/pros. Device rules and symlinks to the included toolchain may also be installed in
Development > PROS IDEshortcut in the
Startmenu, or through the search feature in the desktop environment.
3.2and newer (Ubuntu
12.04and newer), both the new orange VEX Programming Kit and the older serial Programming Kit will work without installing any drivers.
.pkg. Accept the license agreement to install PROS.
Applications > PROSshortcut or through the Spotlight or Applications List.
Copyright (c) 2011-2013, Purdue University ACM SIG BOTS. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PURDUE UNIVERSITY ACM SIG BOTS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Workspace Launcherprompt may appear. The default location is usually acceptable, but if it serves better to move it to an easy-to-remember place, it can be moved here. The workspace is the default location of new PROS projects.
File > New > VEX Cortex PROS Project. Enter a short name without spaces or punctuation into the dialog box. To change the location where the project will be saved, deselect
Use default locationand enter an alternative location (preferably accessible to the whole team...). Click
Finishto create the project.
Project Explorerview. This view is useful to navigate among the multiple files present in each PROS project. To make code easier to maintain, the autonomous and driver control are split by default into two files,
Project Explorerwill open it in a text editor in the main window.
CTRL + SPACE) can make coding fast and joyful.
CTRL + S) the code often. PROS will auto-save files with a confirmation dialog, but this popup gets annoying quickly.
CTRL + B.
;will cause the code to fail compilation.
Problemstab on the bottom. Double-click a message to go to the location where the error occurred.
Uploadtoolbar button, the
VEX > Upload to Cortexmenu item, or the
VEX > File System > Upload Preserving Filesystemmenu item; this will be slower than a regular upload.
File Systemsub-menu. Copying files to the VEX Cortex can be accomplished with
Write File to Cortex, while copying files from the VEX Cortex is done with
Read File from Cortex. The PROS File System cannot store more than one program at a time and is intended for storing data or logs.
Window > Show View > Terminal; if
Terminalis unavailable, select
Window > Show View > Other...and select
Terminalfrom the list.
Connectbutton. If the terminal has been used before, it will connect immediately; otherwise, a prompt will appear.
Baud Ratein the pop up dialog to
115200. The default choice for
Portis usually correct on Windows. For Linux and Mac OS X, the most likely correct
Portis the entry containing "usb" or "acm" in the name. If the suggested option fails, experiment to find which one works.
Disconnecticons can be used to manually open and close the connection.
Portof the VEX connection changes, simply close the
Terminalview and re-open a new one to connect to a different port.
Project Explorerand select
Project Explorerand selecting
Project Explorerand pressing the
DELETEkey. This may not be the same as the
BACKSPACEkey on Macintosh machines. Unless the
Delete project contents from diskoption is selected, the files will not actually be removed from the directory where the project is stored. Deleting projects should be a last resort unless one plans to immediately add them back through Source control. Old code can be very useful.
Projects by default remain on the version of PROS that was used to create them. Therefore, users of different versions of PROS will still run that project in the same way. However, individual old projects can be updated to incorporate new PROS features using the
VEX > Switch project to PROS .... Check the confirmation dialog to ensure that the correct project is selected for upgrade!
PROS also automatically checks for new versions. This check occurs on startup and can be disabled by using
Window > Preferences... (Windows/Linux) or
Eclipse > Preferences (Mac), then selecting
Startup and Shutdown under the
General tab and deselecting
PROS Project Manager and Update:
PROS is a library built on C. This document does not aspire to teach beginners C. Excellent tutorials are available on the Internet by searching for "C" in a browser, bringing up results such as this tutorial on C.
Note that not all information presented in C tutorials is relevant to programming VEX robots with PROS. For example, pointers are used only occasionally, and there is little need for topics such as recursion and file I/O.
PROS projects are internally composed of three parts: the user code, the PROS library and the header files.
The PROS library is a single file containing the core PROS routines. This file does not need to be changed. If there appears to be an issue with a core PROS function, please file an issue on the PROS website.
The header files are all found in the
include directory. One header file,
API.h, is required to declare the PROS library functions, and also serves as a quick reference. The other file,
main.h, is intended for declaring functions and variables shared between the user code files. New header files can be created in the
include directory, as long as the name ends with
User code has the actual sequential instructions that govern the robot's behavior. PROS by default splits the user code up into autonomous (auto.c), driver control (opcontrol.c), and initialization (init.c) files. Code in one file can talk to code in another file using declarations in the header files. New user code files can be created in the
src directory, as long as the name ends with
.c it will be compiled with the others.
All user code files should start with
While more complicated than some environments, splitting up code grants powerful modularity and code reusability, especially when combined with Source control.
Functions and variables must be declared before use, as described in many of the C Basics tutorials. Functions and variables can be declared in the typical C manner:
Doing so will make the variables and functions local to the file in which they exist.
Some functions and variables are useful in more than one location (e.g. a function to use motorSet on all the robot's drive motors with the same value). Such functions can be declared in any of the three files (or a custom file in the
src directory). To make them accessible to any other user code file, prototype the function in main.h.
Functions can be prototyped by copying the function's declaration line into main.h and replacing the function code with
Any function can be prototyped in main.h regardless of which user code file in which it appears. Variables are a little more difficult; the word
extern must be placed in front of the declaration line when it is copied into main.h.
For pieces of code intended for frequent reuse, it may be better to create a separate header file with the related declarations, and to include that file in main.h. Therefore, large pieces of code involving look-up tables, control algorithms, or other complex structures can be quickly ported between projects by copying one
.c user code file and one
.h header file.
Most sensors follow a similar pattern. The sensor is initialized in initialize and used in multiple places, including autonomous and operatorControl. Typical sensor initialization code thus looks like:
Tasks are a great tool to do multiple things at once, but they can be difficult to use properly. Each task has a priority and a stack size. Most of the time, tasks should have the default stack size of
TASK_DEFAULT_STACK_SIZE. The higher the priority, the more crucial the task is considered; tasks of higher priority will always run in preference to lower priority tasks, unless the higher priority task is using
delay() or some other waiting action.
Tasks are created using taskCreate(), which invokes a user function in the new task:
autonomous. Tasks running while disabled cannot use the VEX Joystick or VEX Motors. If the task should stop when the robot is disabled, use the isOnline and/or the isAutonomous function to control the program accordingly. If taskRunLoop is used, the task will automatically be cancelled if the robot is disabled or switched between driver and autonomous.
TASK_PRIORITY_LOWEST + 1to
TASK_PRIORITY_HIGHEST - 1. Tasks of the lowest or highest priority may cause unexpected behavior.
delay(2)will probably make no noticable difference, but will prevent future task starvation issues.
delay(20)as the motors and joysticks are only updated every 20 ms.
One problem which often beguiles tasks is synchronization. If two tasks try to read the same sensor or control the same motor at the same time, unexpected behavior may occur.
Tasks can be designed never to conflict over motors or sensors:
If this is impossible, PROS features two types of elements, mutexes and semaphores, that can be used to coordinate tasks. Mutexes stand for mutual exclusion; only one task can hold a mutex at any given time. Other tasks trying to use the mutex must wait for the first task to finish. For this reason, mutexes must always be released after use.
Semaphores are like signals - one task can take the semaphore to wait for a coordination signal from another task which gives it. If multiple tasks wait on the same semaphore, the highest priority one will continue per signal given.
undefined reference to ...or
implicit declaration of function ...: A function name is not spelled correctly, or the function was not correctly declared in a header file. Custom headers must be included in
main.hor in the file in which they are used; declarations do not appear like magic.
format ... expects argument of type ..., but argument has type ...: The value provided to a function like printf() or lcdPrint() does not match the expected type inferred from the format string. Some instances of this warning can be ignored, but crashes can occur if
long longis mixed with another type.
assignment makes pointer from integer without a cast: Typically caused by a C pointer having the wrong number of asterisks to dereference it, or when accidentally assigning a constant to
pointer(instead of to
delay(). The LCD usually is less important than how well the robot is running, so PROS prioritizes user tasks over the LCD. Only if all other tasks are waiting is the LCD updated.
delay(). Higher or equal priority tasks will still run, but lower priority tasks will not.
initialize()function may be still running. Some tasks such as gyroInit or analogCalibrate take time. If the
initialize()function implements some type of loop or autonomous selection routine, verify that it actually has a means of ending.
Segmentation Faultindicates that an invalid C pointer has been used. Check for confusion between pointers and regular variables, or that an invalid pointer has not been passed to a PROS API function.
Stack Overflowoften indicates infinite recursion, or that the stack size for a custom task is too small. Calling layers of functions and declaring large local variables can require large amounts of space on the stack. If this error occurs in a default task like autonomous(), consider changing code to reduce the stack requirements, or creating a new task with a larger stack using taskCreate() to handle large jobs. Large arrays declared inside functions can be declared globally to alleviate pressure on stack space.
System Task Failuremeans that too many tasks were running for the system to start a new one. Disable or merge unnecessary tasks to eliminate this error.
File > New > Other...and select
Git Repositoryfrom the dialog.
2013Codeas the name. Multiple projects can (and should) be stored in the same Git repository. Do not check
Create as bare repository.
Finish. Nothing appears to happen, but some useful files have been created.
File > Import...in the PROS IDE. In the pop-up dialog, select
Projects from Git.
URIand enter the clone URL from the website:
Yesif a warning appears about "host key cannot be verified" and enter the public key passphrase or user password if required.
Import existing projectsin the next dialog box and navigate to the project directory. Click
Finishand the project will appear in the
Project Explorer. Do not delete the contents from disk. Don't worry, it will reappear momentarily!
File > Import...in the PROS IDE. In the pop-up dialog, select
Projects from Git.
Localand then the repository previously created.
Import existing projectsin the next dialog box, then select the folder that was just copied into the repository. If the project does not appear, verify that the project was copied into the correct location. It should not be inside the
Finishand the project will re-appear in the
Project Explorerand selecting
Team > Add to Index...in the menu that appears.
Team > Commit...or pressing the
CTRL + #(
CTRL + SHIFT + 3on most keyboards) keyboard shortcut.
Committerfields are blank, fill them in with the user's name and e-mail, tremendously helpful for identifying the person to credit (or blame) with new code changes. Make sure to click the check mark button near the list of files between the question mark and the square!
Commitand the code changes will be stored away. If a file is changed in the project, the icon in the
Project Explorerwill gain a
>indicating that it was modified.
Compare With > Commit....
Replace With > Commit...and select the commit to which to roll the file back. This will wipe out any changes since the last commit. It might be better to commit the current code and then roll back the changes.
PROS can be used with just command line utilities, in Windows, Linux, and Mac OS X. Make sure to install the PROS IDE before trying, as important tools such as the ARM cross compiler are installed on the system path when installing the base PROS IDE. Any text editor can be used to edit source code and header files.
make uploadJava must be installed
A copy of Visual Studio and Windows is required. Visual Studio 2010 was used for this document, but the same or similar directions should apply to Visual Studio 2008 or 2013.
Makefile Projectin the
Visual C++category in the desired directory.
Finishin the wizard to create a blank project.
Header Filessection, and the
Source Filessection, using
Add > Existing Item...:
Project > Properties...add the include directory to the
Include Directoriesin the
NMakepanel, add references to
make cleanwhere prompted:
prosload.cmdin a convenient location (preferably where it will not be accidentally moved or committed to Source control) containing the following text:
@echo off cd /d %~dps1 make -k upload
Tools > External Toolsto create a tool named "PROS Upload" with the following settings:
@echo off cd /d %~dps1 PROS=path-to-PROS-IDE-installation for %%f in (%PROS%\plugins\com.purduesigbots.newcortexproject_*.jar) do java -jar %%f .The VS settings for the external tool are the same as the previous example (with the command name changed).
Buildfunctionality will compile the project; the
PROS Uploadoption in the
Toolsmenu will upload the project to an attached VEX Cortex. Not all warning and error messages will be the same as in the Eclipse-based PROS IDE.