Loading

7842 Navigators

Introduction to PROS

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.

PROS EDITOR

On the toolbar, click PROS->New Project

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.

Then, click 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.

Command Line

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
  • Press TAB to autocomplete or run through possible directories
  • Press Ctrl-C to abort command in the terminal
  • An example of PATH would be C:\Users\user\Documents\prosProject\

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.

COMPILING

The first thing to do is remove the example code in opcontrol.cpp and initialize.cpp. Select and delete everything except from the declaration of opcontrol() and initialize().

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 g++ and 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.

PROS Editor

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.

PROS CLI

To compile your project using the PROS CLI, open a terminal and navigate to your project directory using cd. Type 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 prosv5 upload

To see the robot output type prosv5 terminal. To exit from the terminal press CTRL-C.

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 usercontrol.cpp, autonomous.cpp, and 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

  • void myFunction();
  • int addNumbers(int, int);
  • extern int myVariable;
  • extern Motor leftMotor;

Comment

Leave us a comment or question!

Shopping Basket