There is a lot to learn about PROS, and C++ in general. These are the topics we cover:
- Creating a New Project
- Understanding PROS project structure
- Understanding header files, the linker, and the code assembly process
- Defining Motors and Devices
- Creating Functions, Prototypes, and Externs to allow the use of an function or object over multiple files
- Creating a Task and properly managing tasks
- Making a simple driver-control program
We will you assume you have a working PROS environment.
To learn more about installing PROS, read this tutorial.
The official tutorials and API is available here
CREATING A NEW PROJECT
First, we need to create a PROS Project. There are two ways of doing this, either with the PROS Editor or with the PROS CLI.
On the toolbar, click
After that, choose your directory, and keep the default settings for the target and kernel. Make sure you create a new folder for your project, as a mistake some people make is they try create a project in a parent directory.
Create Project. It will then go through the process of setting up the new project. Once the project is set up, it should open the folder in the editor.
Before we proceed with using the PROS CLI, let’s cover how to use a terminal.
To open a terminal, there are multiple ways. One of them is you can press
Win+R and then type
cmd. One of the best ways that many people don’t know about is you can open Explorer, navigate to the directory you want to open the project in, and then type
cmd in the menu bar.
This will open a command prompt window in the current directory.
There is also a terminal built into the PROS Editor (terminal-tab-plus) . However, it is quite buggy and it crashes the Editor on many computers. It is recommended to install the
platformio-ide-terminal package to use as a terminal instead, as the it can be accessed from the bottom of the window instead of as a separate tab. The other advantage is that it has better project recognition and puts you in the proper working directory.
To open a terminal using terminal-tab-plus, click the terminal button in the toolbar.
To use the terminal, it is necessary to know these commands:
cd PATH– Navigates to specified directory
cd ..– Navigates to parent directory
cd .\FOLDER– Navigates to folder inside current directory
ls– Lists files and folders in the directory
TABto autocomplete or run through possible directories
Ctrl-Cto abort command in the terminal
- An example of
Now that we know how to navigate around the terminal, we are ready to create a new project.
In the terminal of your choice, type
prosv5 conduct new <path_to_project>. This will create a new project directory in the path you specify.
Now your project has been created. It contains a basic project structure and some placeholder code. To open it in the PROS editor, click
File->Open Folder and navigate to the folder you just created.
Now you have PROS set up with a new project and are ready to start programming. If you want to add this project to a GitHub repository, read this tutorial.
The first thing to do is remove the example code in
initialize.cpp. Select and delete everything except from the declaration of
After everything is gone, we should compile to make sure everything was set up properly.
There are three steps to get a code running on the robot. First, make sure that all your files are saved. You can check this by looking if there is a blue dot on one of the file tabs. Second, you have to compile your project. Third, you have to upload the code to the robot. Once the code is on the V5 Brain you can run it using the touchscreen.
The compiler uses
make to build the project. One benefit of using the make system is that it can detect and only recompile modified files when you build without recompiling the whole project.
There are four compile modes
- Default/Quick – Only compile changed files
- All – Clean compiled files then compile everything
- Clean – Clean compiled files
It is a good idea to
make all when making drastic changes to your code or when there are linker errors. This is because there may be files that have not been directly modified but use modified functions and variables from other files, so there is a conflict of function references.
To compile and upload, follow one of the below methods.
To compile the project, click the
Build button in the PROS toolbar. You can also access this command under
PROS->Build in the editor toolbar. This will open a terminal window and start compiling and displaying errors if there are any. If you find it annoying that the terminal window with the erros disappears after a bit of time, go to
Settings->Packages->Terminal Tab Plus->Linger and change the value. When you have zero build errors, you can then upload the compiled binary to the V5 by pressing the
Upload button. To see robot output, you can open the Robot Terminal using the next button to the right.
To compile your project using the PROS CLI, open a terminal and navigate to your project directory using
prosv5 make to compile the project. It will tell you if there are any errors in your code.
Once the project is compiled, to upload the binary to the V5 type
To see the robot output type
prosv5 terminal. To exit from the terminal press
The last 3 commands can be simplified to
prosv5 mut or
prosv5 mu. You would use this command if you want to quickly make a change to the code then run it on the robot.
We prefer to use the CLI, as it is slightly faster to compile and upload than the Editor buttons, and also it does not open a new terminal every time.
Choosing an API
There are two API’s for PROS. There is a C API and a C++ API. The latter is mostly wrappers for the former, but it has a couple advantages that make it better to use.
We recommend using the C++ API for PROS, because of it’s capabilities and neatness. The C++ API is much better organized and intuitive, as the functions belong to the object you are applying the function to. For example, using the C API, you have to specify the motor port every time you use the
motor_move(2, 127); function. You could use defines, constants, or enums for better neatness that allow you to type
motor_move(rightMotor, 127);, but that is a lot of work.
Instead, if you use C++, you can define
Motor rightMotor(2); once. Then whenever you want to move that motor you can say
rightMotor.move(127);. Or you can say
rightMotor.stop();. It is simply a much more elegant and intuitive solution than you could have with C.
You can also still use the knowledge you have in C with C++, because anything that works in C will also work in C++.
However, learning PROS is still quite a steep learning curve. You must understand prototypes, classes, namespaces, methods, and header files.
HEADER FILES AND THE LINKER
Here we will explain what a header file is, its uses, and how the compiler and linker work.
In your code, you have separate source files. By default, you have
initialize.cpp. This is only for organization, you could have your entire code in one file or split up into multiple more specific files.
When you compile, this is what happens:
- The compiler reads and deals with any pre-processor directives such as #define or #include
- The compiler compiles each source file individually and independently with no knowledge of each other
- The linker combines each compiled file into one final file and merges the kernel file to make a final executable
You cannot declare a variable in one file and read it in another file without using a header file. If you try to do so, you will receive errors, as the compiler does not know about any variables in a separate file.
To understand what header files are, read this tutorial.
Basically, header files are a counterpart of your source files, to declare to the rest of the program what those source files contain. Good practice is to create a header file for each source file you create. If you create a variable or function in a source file, you need to forward declare it in the header file. Examples of a forward declaration are
int addNumbers(int, int);
extern int myVariable;
extern Motor leftMotor;