PROS V5

https://pros.cs.purdue.edu/v5
Admin
PROS is a open-source platform for programming VEX Robotics V5 systems with C/C++ APIs, featuring a...
Tokens:673,752
Snippets:3,911
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Fetch Local PROS Template Archive using Conductor CLI

Source: https://pros.cs.purdue.edu/v5/cli/conductor

This command fetches a local template archive file (e.g., 'mylibrary@1.0.0.zip'). This is useful for installing templates that are not available in a remote depot or for offline installations.

```bash
> pros conduct fetch mylibrary@1.0.0.zip

```

--------------------------------

### LCD Button Callback Example (C)

Source: https://pros.cs.purdue.edu/v5/api/c/llemu

Example demonstrating how to register and implement a callback function for a button press on the emulated LCD. This example toggles text on line 2 when the center button is pressed.

```c
void on_center_button() {
  static bool pressed = false;
  pressed = !pressed;
  if (pressed) {
    lcd_set_text(2, "I was pressed!");
  } else {
    lcd_clear_line(2);
  }
}

void initialize() {
  lcd_initialize();
  lcd_register_btn1_cb(on_center_button);
}
```

--------------------------------

### Install PROS CLI and Toolchain using Homebrew

Source: https://pros.cs.purdue.edu/v5/getting-started/macos

Installs the PROS command-line interface (CLI) and the necessary ARM GCC toolchain using Homebrew. This is a streamlined installation process for macOS users who have Homebrew set up.

```bash
brew tap osx-cross/arm && brew install arm-gcc-bin
brew tap purduesigbots/pros
brew install pros-cli
```

--------------------------------

### Manually Install ARM Toolchain and Add to PATH

Source: https://pros.cs.purdue.edu/v5/getting-started/macos

Provides instructions for manually installing the GNU Arm Embedded Toolchain and adding its binaries to the system's PATH. This method is for users who prefer not to use Homebrew for the toolchain installation.

```bash
mkdir -p /usr/local/bin/pros-toolchain && ln -s /usr/local/lib/pros-toolchain/bin/* /usr/local/bin/pros-toolchain
# Add /usr/local/bin/pros-toolchain to your /etc/paths file
```

```bash
ln -s /usr/local/lib/pros-toolchain/bin/* /usr/local/bin
```

--------------------------------

### Install VEX Vision Utility using Homebrew

Source: https://pros.cs.purdue.edu/v5/getting-started/macos

Installs the VEX Vision Utility using Homebrew, which is necessary for setting up signatures for the Vision Sensor. This is an optional step for users planning to use the Vision Sensor.

```bash
brew install vcs-vision
```

--------------------------------

### Install PROS Editor with Homebrew

Source: https://pros.cs.purdue.edu/v5/pros-4/install-macos

Installs the PROS Editor and CLI using Homebrew. This requires Homebrew to be installed and involves tapping repositories and installing a cask.

```shell
brew tap osx-cross/arm && brew install arm-gcc-bin
brew tap purduesigbots/pros
brew cask install pros-editor
```

--------------------------------

### Fetch Remote PROS Template using Conductor CLI

Source: https://pros.cs.purdue.edu/v5/cli/conductor

This command fetches a specific version of a remote PROS template (e.g., 'kernel@3.1.0') from its configured depot. It downloads the template archive for later use or installation.

```bash
> pros conduct fetch kernel@3.1.0

```

--------------------------------

### Manually Install PROS Toolchain Binaries

Source: https://pros.cs.purdue.edu/v5/pros-4/install-macos

Links the manually installed GNU Arm Embedded Toolchain binaries to the system's PATH. This involves creating directories and symbolic links.

```shell
mkdir -p /usr/local/bin/pros-toolchain && ln -s /usr/local/lib/pros-toolchain/bin/* /usr/local/bin/pros-toolchain
echo "/usr/local/bin/pros-toolchain" >> /etc/paths
```

```shell
ln -s /usr/local/lib/pros-toolchain/bin/* /usr/local/bin
```

--------------------------------

### Add a Custom Remote Depot to PROS Conductor (conductor.pros)

Source: https://pros.cs.purdue.edu/v5/cli/conductor

Configure the 'depots' key in conductor.pros to add a custom remote depot. This involves specifying the depot's name, location (a URL to a JSON file describing templates), and other configuration details. This allows users to install templates using `pros conduct apply`.

```json
"my-remote-depot": {
        "config": {},
        "config-schema": {},
        "location": "https://my-username.github.io/my-remote-depot/my-remote-depot.json",
        "name": "my-remote-depot",
        "py/object": "pros.conductor.depots.http_depot.HttpDepot",
        "remote_templates": [],
        "update_frequency": {
                "py/reduce": [
                        {
                                "py/type": "datetime.timedelta"
                        },
                        {
                                "py/tuple": [
                                        0,
                                        60,
                                        0
                                ]
                        }
                ]
        }
}
```

--------------------------------

### Get VEX GPS Sensor Yaw (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the yaw of the robot in degrees relative to the starting orientation. This function specifically returns the yaw angle.

```c
double gps_get_yaw(uint8_t port);
```

--------------------------------

### Get VEX GPS Sensor Roll (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the roll of the robot in degrees relative to the starting orientation. This function specifically returns the roll angle.

```c
double gps_get_roll(uint8_t port);
```

--------------------------------

### Initialize LLEMU in C

Source: https://pros.cs.purdue.edu/v5/tutorials/topical/llemu

Initializes the Legacy LCD Emulator (LLEMU) using the PROS C API. This function should be called at the program's entry point, typically within the `initialize()` function, to make the LLEMU available for displaying output.

```c
void initialize() {
  lcd_initialize();
}
```

--------------------------------

### Initialize LLEMU LCD

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-llemu

Initializes the Legacy LCD Emulator, creating a virtual VEX LCD on the display. Returns true on success and false if already initialized. Requires including 'pros/llemu.h'.

```c++
#include "pros/llemu.h"

void initialize() {
  if (pros::c::lcd_initialize()) {
    pros::c::lcd_print("LLEMU!");   
  }
  else {
       printf("Error: LLEMU could not initailize\n");
  }
}
```

--------------------------------

### Get VEX GPS Sensor Pitch (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the pitch of the robot in degrees relative to the starting orientation. This function specifically returns the pitch angle.

```c
double gps_get_pitch(uint8_t port);
```

--------------------------------

### Create New PROS Project using Conductor CLI

Source: https://pros.cs.purdue.edu/v5/cli/conductor

This command initiates the creation of a new PROS project in the specified directory. It fetches and applies necessary kernel and library templates, providing detailed progress feedback. The output confirms project creation, target platform, and lists applied templates with their versions and origins.

```bash
> pros conduct new-project ./Top-5-At-Worlds
Updating pros-mainline... Done
Downloading kernel@3.0.7 (https://www.cs.purdue.edu/~brookea/kernel@3.0.7.zip) [####################################] 100%
Extracting kernel@3.0.7 [####################################] 100%
Fetched kernel@3.0.7 from pros-mainline depot
Adding kernel@3.0.7 to registry...Done
Applying kernel@3.0.7 [####################################] 100%
Finished applying kernel@3.0.7 to ./Top-5-At-Worlds
Downloading okapilib@3.0.1 (https://www.cs.purdue.edu/~berman5/okapilib@3.0.1.zip) [####################################] 100%
Extracting okapilib@3.0.1 [####################################] 100%
Fetched okapilib@3.0.1 from pros-mainline depot
Adding okapilib@3.0.1 to registry...Done
Applying okapilib@3.0.1 [####################################] 100%
Finished applying okapilib@3.0.1 to ./Top-5-At-Worlds
New PROS Project was created:
PROS Project for v5 at: /home/me/Top-5-At-Worlds (Top-5-At-Worlds)
Name      Version    Origin
--------  ---------  -------------
kernel    3.0.7      pros-mainline
okapilib  3.0.1      pros-mainline

```

--------------------------------

### Get VEX GPS Sensor Y Position (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the Y position in meters of the robot relative to the starting position. This function isolates the Y-coordinate of the robot's location.

```c
double gps_get_position_y(uint8_t port);
```

--------------------------------

### Initialize VEX Optical Sensor C++

Source: https://pros.cs.purdue.edu/v5/api/cpp/optical

Demonstrates how to initialize the VEX Optical Sensor using its constructor. The constructor takes the V5 port number as a parameter. An optional second parameter allows setting the integration time.

```cpp
#define OPTICAL_PORT 1

void initialize() {
  pros::Optical optical_sensor(OPTICAL_PORT);
}
```

```cpp
#define OPTICAL_PORT 1

void initialize() {
  pros::Optical optical_sensor(OPTICAL_PORT, 50);
}
```

--------------------------------

### GET /motor/temperature

Source: https://pros.cs.purdue.edu/v5/api/cpp/motors

Gets the temperature of the motor in degrees Celsius. The resolution of this reading is 5 degrees Celsius. The motor will start to reduce its power when the temperature reading is greater than or equal to 55 C.

```APIDOC
## GET /motor/temperature

### Description
Gets the temperature of the motor in degrees Celsius. The resolution of this reading is 5 degrees Celsius. The motor will start to reduce its power when the temperature reading is greater than or equal to 55 C.

### Method
GET

### Endpoint
/motor/temperature

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body for this GET request)

### Response
#### Success Response (200)
- **temperature** (double) - The motor's temperature in degrees Celsius.

#### Response Example
{
  "temperature": 45.5
}
```

--------------------------------

### Get VEX GPS Sensor X Position (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the X position in meters of the robot relative to the starting position. This function isolates the X-coordinate of the robot's location.

```c
double gps_get_position_x(uint8_t port);
```

--------------------------------

### Install/Upgrade PROS Template using Conductor CLI

Source: https://pros.cs.purdue.edu/v5/cli/conductor

This command applies a specified template (e.g., 'okapilib') to the current PROS project. It handles downloading, extracting, and integrating the template's files and configurations.

```bash
> pros conduct apply okapilib

```

--------------------------------

### gps_get_x_position

Source: https://pros.cs.purdue.edu/v5/api/c/gps

Gets the X position in meters of the GPS relative to the starting position.

```APIDOC
## GET /gps/get_x_position

### Description
Gets the X position in meters of the GPS relative to the starting position.

### Method
GET

### Endpoint
/gps/get_x_position

### Parameters
#### Path Parameters
None

#### Query Parameters
- **port** (uint8_t) - Required - The V5 GPS port number from (1-21).

#### Request Body
None

### Request Example
```json
{
  "port": 1
}
```

### Response
#### Success Response (200)
- **x_position** (double) - The X position in meters.

#### Response Example
```json
{
  "x_position": 0.75
}
```
```

--------------------------------

### PROS Project Structure Overview

Source: https://pros.cs.purdue.edu/v5/tutorials/walkthrough/clawbot

This code snippet illustrates the typical file and directory structure of a PROS project for the VEX Clawbot. It includes essential files like the project configuration, Makefile, source files, header files, and pre-compiled libraries. Understanding this structure is key to organizing and building your PROS projects.

```plaintext
project
│   project.pros        (used by PROS CLI to know kernel version and other metadata)
│   Makefile            (instructs make how to compile your project)
|   common.mk           (helper file for Makefile)
│
└───src                 (source files should go here)
│   │   main.cpp        (source for competition task functions, like operator control and autonomous)
|
└───include             (Header files should go in here)
│   │   api.h           (Lets source files know PROS API functions)
│   │   main.h          (Includes api.h and anything else you want to include project-wide)
|   └───pros            (Contains all of the specific header files for the PROS API functions)
|   └───okapi           (Contains all of the header files for OkapiLib)
|   └───display         (Contains all of the header files for LVGL, the graphics library for the V5 screen)
│
└───firmware
│   libpros.a       (Pre-compiled PROS library)
│   okapilib.a      (Pre-compiled OkapiLib library)
|   v5.ld           (Instructs the linker how to construct binaries for the V5)


```

```plaintext
project
│   project.pros        (used by PROS CLI to know kernel version and other metadata)
│   Makefile            (instructs make how to compile your project)
|   common.mk           (helper file for Makefile)
│
└───src                 (source files should go here)
│   │   autonomous.cpp  (source for autonomous function)
│   │   initialize.cpp  (source for initialization)
│   │   opcontrol.cpp   (source for operator control)
|
└───include             (Header files should go in here)
│   │   api.h           (Lets source files know PROS API functions)
│   │   main.h          (Includes api.h and anything else you want to include project-wide)
|   └───pros            (Contains all of the specific header files for the PROS API functions)
|   └───okapi           (Contains all of the header files for OkapiLib)
|   └───display         (Contains all of the header files for LVGL, the graphics library for the V5 screen)
│
└───firmware
│   libpros.a       (Pre-compiled PROS library)
│   okapilib.a      (Pre-compiled OkapiLib library)
|   v5.ld           (Instructs the linker how to construct binaries for the V5)

```

--------------------------------

### Initialize LLEMU in C++

Source: https://pros.cs.purdue.edu/v5/tutorials/topical/llemu

Initializes the Legacy LCD Emulator (LLEMU) using the PROS C++ API. This function should be called at the program's entry point, typically within the `initialize()` function, to make the LLEMU available for displaying output.

```cpp
void initialize() {
  pros::lcd::initialize();
}
```

--------------------------------

### Get Motor Actual Velocity (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-motors

Gets a vector containing the actual velocity of the motor in RPM. Returns PROS_ERR_F on failure, setting errno. Fails if the port cannot be configured as a motor. Example shows printing the actual velocity in a loop.

```cpp
#include <pros/motors.hpp>
#include <pros/controller.hpp>
#include <iostream>

void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move_velocity(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    std::cout << "Motor Velocity: " << motor.get_actual_velocity_all()[0];
    // Prints the value of E_CONTROLLER_ANALOG_LEFT_Y
    pros::delay(2);
  }
}
```

--------------------------------

### GPS Yaw

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the yaw of the robot in degrees relative to the starting orientation.

```APIDOC
## gps_get_yaw

### Description
Gets the yaw of the robot in degrees relative to the starting orientation.

### Method
C Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#define GPS_PORT 1

void opcontrol() {
  double yaw;

  while (true) {
    yaw = gps_get_yaw(GPS_PORT);
    printf("yaw: %f\n", yaw);
    delay(20);
  }
}
```

### Response
#### Success Response (double)
- **yaw** (double) - The yaw in [0,360) degree values.

#### Response Example
```
180.0
```

### Error Handling
Returns PROS_ERR_F and sets errno if the operation failed.
- **ENXIO**: The given value is not within the range of V5 ports (1-21).
- **ENODEV**: The port cannot be configured as a GPS.
- **EAGAIN**: The sensor is still calibrating.
```

--------------------------------

### Standard C++ Object Construction for V5 Devices (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/user-literals

This snippet illustrates the equivalent standard C++ object construction for V5 devices, serving as a comparison to the user literal syntax. It achieves the same initialization results as the literals but uses traditional constructor calls.

```C++
pros::Motor front_motor(1);   // Constructs a motor on port 1
pros::Motor back_motor(-2);   // Constructs a motor on port 2, and reverses it
pros::Imu imu(12);            // Constructs an IMU object on port 12
```

--------------------------------

### GPS Roll

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the roll of the robot in degrees relative to the starting orientation.

```APIDOC
## gps_get_roll

### Description
Gets the roll of the robot in degrees relative to the starting orientation.

### Method
C Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#define GPS_PORT 1

void opcontrol() {
  double roll;

  while (true) {
    roll = gps_get_roll(GPS_PORT);
    printf("roll: %f\n", roll);
    delay(20);
  }
}
```

### Response
#### Success Response (double)
- **roll** (double) - The roll in [0,360) degree values.

#### Response Example
```
1.2
```

### Error Handling
Returns PROS_ERR_F and sets errno if the operation failed.
- **ENXIO**: The given value is not within the range of V5 ports (1-21).
- **ENODEV**: The port cannot be configured as a GPS.
- **EAGAIN**: The sensor is still calibrating.
```

--------------------------------

### GPS Pitch

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Gets the pitch of the robot in degrees relative to the starting orientation.

```APIDOC
## gps_get_pitch

### Description
Gets the pitch of the robot in degrees relative to the starting orientation.

### Method
C Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#define GPS_PORT 1

void opcontrol() {
  double pitch;

  while (true) {
    pitch = gps_get_pitch(GPS_PORT);
    printf("pitch: %f\n", pitch);
    delay(20);
  }
}
```

### Response
#### Success Response (double)
- **pitch** (double) - The pitch in [0,360) degree values.

#### Response Example
```
3.5
```

### Error Handling
Returns PROS_ERR_F and sets errno if the operation failed.
- **ENXIO**: The given value is not within the range of V5 ports (1-21).
- **ENODEV**: The port cannot be configured as a GPS.
- **EAGAIN**: The sensor is still calibrating.
```

--------------------------------

### Extended API Macros

Source: https://pros.cs.purdue.edu/v5/extended/apix

Documentation for various action macros used with `fdctl` and `serctl`.

```APIDOC
## Extended API Macros

### SERCTL_ACTIVATE

#### Description
Action macro to pass into `serctl` or `fdctl` that activates the stream identifier.

#### Value
`10`

### SERCTL_DEACTIVATE

#### Description
Action macro to pass into `serctl` or `fdctl` that deactivates the stream identifier.

#### Value
`11`

### SERCTL_BLKWRITE

#### Description
Action macro to pass into `fdctl` that enables blocking writes for the file.

#### Value
`12`

### SERCTL_NOBLKWRITE

#### Description
Action macro to pass into `fdctl` that makes writes non-blocking for the file.

#### Value
`13`

### SERCTL_ENABLE_COBS

#### Description
Action macro to pass into `serctl` that enables advanced stream multiplexing capabilities.

#### Value
`14`

### Notes on Macros:
- When used with `serctl`, the `extra_arg` must be the little endian representation of the stream identifier (e.g., `"sout"` -> `0x74756f73`).
- When `SERCTL_BLKWRITE` or `SERCTL_NOBLKWRITE` are used with `fdctl`, the `extra_arg` is not used and should be `NULL`.
- When `SERCTL_ACTIVATE` or `SERCTL_DEACTIVATE` are used with `fdctl`, the `extra_arg` should be the stream identifier.
- When `SERCTL_ENABLE_COBS` is used, the `extra_arg` is not used and should be `NULL`.
```

--------------------------------

### Get Name of a PROS Task

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-rtos

Retrieves the name of the specified task. This function returns a C-style string representing the task's name. The example demonstrates initializing a task and then attempting to print its name, though the usage in the example is incorrect (get_name() returns a const char*, not a count).

```cpp
void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  pros::Task my_task(my_task_fn, "My Task");
  // printf("Number of Running Tasks: %d\n", my_task.get_name()); // Incorrect usage
  printf("Task Name: %s\n", my_task.get_name()); // Corrected usage
}
```

--------------------------------

### Tank Drive Control Setup (C++ and C)

Source: https://pros.cs.purdue.edu/v5/tutorials/walkthrough/clawbot

Implements tank drive control by mapping the left joystick to the left drive motors and the right joystick to the right drive motors. This snippet shows the C++ and C implementations for setting up and running tank drive.

```cpp
#define LEFT_WHEELS_PORT 1
#define RIGHT_WHEELS_PORT 10

void opcontrol() {
  pros::Motor left_wheels (LEFT_WHEELS_PORT);
  pros::Motor right_wheels (RIGHT_WHEELS_PORT, true); // This reverses the motor
  pros::Controller master (CONTROLLER_MASTER);

  while (true) {
    left_wheels.move(master.get_analog(ANALOG_LEFT_Y));
    right_wheels.move(master.get_analog(ANALOG_RIGHT_Y));

    pros::delay(2);
  }
}
```

```c
#define LEFT_WHEELS_PORT 1
#define RIGHT_WHEELS_PORT 10

void opcontrol() {
  while (true) {
    int left = controller_get_analog(CONTROLLER_MASTER, ANALOG_LEFT_Y);
    int right = controller_get_analog(CONTROLLER_MASTER, ANALOG_RIGHT_Y);
    right *= -1; // This will reverse the right motor
    motor_move(LEFT_WHEELS_PORT, left);
    motor_move(RIGHT_WHEELS_PORT, right);

    delay(2);
  }
}
```

--------------------------------

### Get Motor Target Position (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-motors

Gets a vector containing the target position set for the motor in its encoder units. This function can return PROS_ERR_F on failure, setting errno. It fails if the port cannot be configured as a motor. Example shows retrieving the target position for the first motor.

```cpp
#include <pros/motors.hpp>
#include <iostream>

void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(100, 100);
  std::cout << "Motor Target: " << motor.get_target_position_all()[0];
  // Prints 100
}
```

--------------------------------

### Get Motor Target Velocity (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-motors

Gets a vector containing the velocity commanded to the motor by the user. The velocity is typically from +-100, +-200, or +-600. Returns PROS_ERR on failure, setting errno. Fails if the port cannot be configured as a motor. Example shows printing the commanded velocity in a loop.

```cpp
#include <pros/motors.hpp>
#include <pros/controller.hpp>
#include <iostream>

void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move_velocity(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    std::cout << "Motor Velocity: " << motor.get_target_velocity_all()[0];
    // Prints the value of E_CONTROLLER_ANALOG_LEFT_Y
    pros::delay(2);
  }
}
```

--------------------------------

### Initialize LCD Emulator - C

Source: https://pros.cs.purdue.edu/v5/api/c/llemu

Initializes the emulated three-button LCD screen. Returns true if successfully initialized, false if it has already been initialized. Analogous to pros::lcd::initialize.

```c
bool lcd_initialize ( )
```

```c
void initialize() {
  lcd_initialize();
  lcd_set_text(1, "Hello World!");
}
```

--------------------------------

### PROS API Overview

Source: https://pros.cs.purdue.edu/v5/api/index

This section outlines the main PROS API, which is designed to meet the needs of most users. It lists the available C and C++ API headers for various hardware components and functionalities.

```APIDOC
## PROS API Home

This document covers the main PROS API, which is completely sufficient for most users’ needs.

### C API Headers

*   ADI (TriPort) C API
*   ADI Expander C API
*   VEX Distance Sensor C API
*   VEX GPS Sensor C API
*   VEX Inertial Sensor C API
*   LLEMU (Legacy LCD Emulator) C API
*   Miscellaneous C API
*   Motors C API
*   VEX Optical Sensor C API
*   VEX Rotation Sensor C API
*   RTOS Facilities C API
*   Vision Sensor C API
*   VEX Link C API

### C++ API Headers

*   ADI (TriPort) C++ API
*   VEX Distance Sensor C++ API
*   VEX GPS Sensor C++ API
*   VEX Inertial Sensor C++ API
*   LLEMU (Legacy LCD Emulator) C++ API
*   Miscellaneous C++ API
*   Motors C++ API
*   Motor Groups C++ API
*   VEX Optical Sensor C++ API
*   VEX Rotation Sensor C++ API
*   RTOS Facilities C++ API
*   Vision Sensor C++ API
*   VEX Link C++ API

### Legacy API

To aid in transitioning from PROS 2 syntax to PROS 3, a Legacy API Header is provided. This header provides PROS 2 functionality in its original syntax.

### Extended API

For additional RTOS-related features, check out the Extended API. Be warned, these features are intended for advanced users only and may be very complex to use.

### Versions

*   V5 (3.8.0)
*   Cortex
```

--------------------------------

### Get GPS Pitch

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the current pitch of the robot in degrees, relative to its starting orientation. This provides a single-axis rotational reading.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
double pitch = gps.get_pitch();
// Use pitch for controlling robot movement or stability
```

--------------------------------

### Configure Project as a PROS Library in Makefile

Source: https://pros.cs.purdue.edu/v5/pros-4/wireless-upload

This snippet demonstrates how to configure a project as a PROS library, which is then included in the 'cold image' for large projects. Set IS_LIBRARY to 1, define a LIBNAME, and specify the VERSION. Exclude frequently changing source files from the library using EXCLUDE_SRC_FROM_LIB.

```makefile
# Set this to 1 to add additional rules to compile your project as a PROS library template
IS_LIBRARY:=0
# TODO: CHANGE THIS!
LIBNAME:=libbest
VERSION:=1.0.0
# EXCLUDE_SRC_FROM_LIB= $(SRCDIR)/unpublishedfile.c
```

```makefile
# Set this to 1 to add additional rules to compile your project as a PROS library template
IS_LIBRARY:=1
LIBNAME:=libtheseus
VERSION:=1.0.0
# this line excludes opcontrol.c and similar files
EXCLUDE_SRC_FROM_LIB+=$(foreach file, $(SRCDIR)/opcontrol $(SRCDIR)/initialize $(SRCDIR)/autonomous,$(foreach cext,$(CEXTS),$(file).$(cext)) $(foreach cxxext,$(CXXEXTS),$(file).$(cxxext)))
EXCLUDE_SRC_FROM_LIB+=$(SRCDIR)/scripts             # exclude any files in the src/scripts directory
EXCLUDE_SRC_FROM_LIB+=$(SRCDIR)/lcdselector.cpp     # exclude src/lcdselector.cpp
```

--------------------------------

### Get GPS Yaw

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the current yaw of the robot in degrees, relative to its starting orientation. This provides the primary rotational reading for turning.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
double yaw = gps.get_yaw();
// Use yaw for navigation and turning
```

--------------------------------

### Set LCD Text (C)

Source: https://pros.cs.purdue.edu/v5/api/api-legacy

Displays a string on the emulated three-button LCD screen. Requires lcdInit to be called first. Returns true on success, false on error (setting errno to ENXIO or EINVAL). Analogous to lcd_set_text.

```c
bool lcdSetText ( int16_t line,
                  const char* text )
```

```c
void initialize() {
  lcd_initialize();
  lcd_set_text(1, "Hello World!");
}
```

--------------------------------

### Get GPS Roll

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the current roll of the robot in degrees, relative to its starting orientation. This provides another single-axis rotational reading.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
double roll = gps.get_roll();
// Use roll for controlling robot movement or stability
```

--------------------------------

### pros::Optical Constructor

Source: https://pros.cs.purdue.edu/v5/api/cpp/optical

Initializes the pros::Optical sensor on a specified V5 port. Optionally, an integration time can be provided.

```APIDOC
## pros::Optical Constructor

### Description
Initializes the pros::Optical sensor on a specified V5 port. Optionally, an integration time can be provided.

### Method
Constructor

### Parameters
#### Path Parameters
- **port** (uint8_t) - Required - The V5 port number from 1-21.
- **time** (double) - Optional - The integration time (update rate) to set for the optical sensor, clamped to the range 3ms - 712ms. The default is 100 ms.

### Request Example
```cpp
#define OPTICAL_PORT 1

void initialize() {
  pros::Optical optical_sensor(OPTICAL_PORT);
  // Or with integration time:
  // pros::Optical optical_sensor(OPTICAL_PORT, 50);
}
```

### Response
N/A (Constructor)

### Error Handling
- `ENXIO` - The given value is not within the range of V5 ports (1-21).
- `ENODEV` - The port cannot be configured as an Optical Sensor.
```

--------------------------------

### Get Specific Object

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-aivision

Retrieves a specific detected object from the AI Vision sensor using its index. Objects are indexed starting from 0.

```APIDOC
## Object get_object(uint32_t object_index)

### Description
Get the detected object at a given object index; there are aivision_get_object_count objects and the index starts from 0.

### Method
GET

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```cpp
pros::AIVision ai_sensor(2);
// Assuming an object exists at index 0
pros::AIVision::Object first_object = ai_sensor.get_object(0);
// Access properties of first_object
```

### Response
#### Success Response (200)
- **Object** - The detected object at the specified index.

#### Response Example
```json
{
  "x": 100,
  "y": 50,
  "width": 30,
  "height": 40,
  "rotation": 15,
  "signature": {
    "x": 100,
    "y": 50,
    "width": 30,
    "height": 40,
    "rotation": 15
  },
  "centerX": 115,
  "centerY": 70
}
```
```

--------------------------------

### LCD Initialization

Source: https://pros.cs.purdue.edu/v5/api/api-legacy

Initializes the display to emulate the three-button, UART-based VEX LCD. This function is analogous to lcd_initialize.

```APIDOC
## lcdInit

### Description
Initialize the display to be an emulation of the three-button, UART-based VEX LCD.
Analogous to lcd_initialize.

### Method
bool

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
void initialize() {
  lcdInit();
  lcdSetText(1, "Hello World!");
}
```

### Response
#### Success Response (200)
`true` if the LCD was successfully initialized.

#### Response Example
```json
{
  "status": true
}
```
```

--------------------------------

### Get Ultrasonic Sensor Value

Source: https://pros.cs.purdue.edu/v5/api/c/adi_ext

Retrieves the current distance reading from the ultrasonic sensor in centimeters. Returns zero if no object is detected, or PROS_ERR if the sensor was not started.

```APIDOC
## ext_adi_ultrasonic_get

### Description
Gets the current ultrasonic sensor value in centimeters.
If no object was found, zero is returned. If the ultrasonic sensor was never started, the return value is PROS_ERR. Round and fluffy objects can cause inaccurate values to be returned.
This function uses the following values of `errno` when an error state is reached:
  * `ENXIO` - The given port is not within the range of ADI Ports
  * `EADDRINUSE` - The port is not configured as an ultrasonic

Analogous to pros::ADIUltrasonic::get_value.

### Method
`int32_t` ext_adi_ultrasonic_get ( ext_adi_ultrasonic_t ult )

### Parameters
#### Path Parameters
- **ult** (ext_adi_ultrasonic_t) - Required - The `ext_adi_ultrasonic_t`_ object from ext_adi_ultrasonic_init to read, or simply the ADI port number.

### Request Example
```c
#define PORT_PING 1
#define PORT_ECHO 2
#define ADI_EXPANDER_PORT 20

void opcontrol() {
  ext_adi_ultrasonic_t ult = ext_adi_ultrasonic_init(ADI_EXPANDER_PORT, PORT_PING, PORT_ECHO);
  while (true) {
    // Print the distance read by the ultrasonic
    printf("Distance: %d\n", ext_adi_ultrasonic_get(ult));
    delay(5);
  }
}
```

### Response
#### Success Response
- **int32_t** - The distance to the nearest object in centimeters.

#### Response Example
```c
int32_t distance = 50; // Example distance in centimeters
```

#### Error Response
- **0** - If no object was found.
- **PROS_ERR** - If the ultrasonic sensor was never started.
```

--------------------------------

### Device Class and Constructors

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-device

Information about the Device class and its constructors for creating and initializing device objects.

```APIDOC
## Classes

### class pros::v5::Device

## Function documentation

### Device(const std::uint8_t port) explicit
#include <pros/device.hpp>
Creates a Device object.
Parameters  
---
port | The V5 port number from 1-21  
**Example**
```cpp
#define DEVICE_PORT 1

void opcontrol() {
  pros::v5::Device device(DEVICE_PORT);
}
```

### Device(const std::uint8_t port, const enum DeviceType deviceType) private
#include <pros/device.hpp>
Creates a Device object.
Parameters  
---
port | The V5 port number from 1-21  
deviceType | The type of the constructed device
```

--------------------------------

### Get Current Task Handle (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-rtos

Retrieves the handle of the currently executing task. This can be useful for a task to refer to itself, for example, when passing its handle to another task or for introspection.

```c
#include <pros/rtos.h>

task_t task_get_current();
```

--------------------------------

### Linker Error Example in PROS

Source: https://pros.cs.purdue.edu/v5/pros-4/wireless-upload

This example shows a typical linker error that occurs when 'cold' code attempts to link against 'hot' code. The error message indicates an undefined reference, highlighting the limitation that cold image code cannot directly call functions or use variables from the hot image.

```text
bin/libtheseus.a(lcdselector.cpp.o):(.data.inits+0x0): undefined reference to `auton::allianceInit(auton::color)'

```

--------------------------------

### Get GPS Orientation

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Fetches the current pitch, roll, and yaw of the GPS sensor relative to the starting orientation. This function returns the rotational data.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
pros::gps_orientation_s_t orientation = gps.get_orientation();
// Access orientation.pitch, orientation.roll, orientation.yaw
```

--------------------------------

### pros::usd API

Source: https://pros.cs.purdue.edu/v5/api/cpp/misc

Provides methods for interacting with the V5 Smart Device port for USB storage.

```APIDOC
## pros::usd

### is_installed

Checks if a USB drive is installed in the V5 Brain's USB port.

```cpp
bool pros::usd::is_installed ( )
```

**Returns:** True if a USB drive is installed, false otherwise.
```

--------------------------------

### Get GPS Position Y

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the current Y-coordinate of the robot's position in meters, relative to its starting position. This provides the other single-axis position reading.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
double pos_y = gps.get_position_y();
// Use pos_y for calculations
```

--------------------------------

### Get GPS Y Position (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the Y position in meters of the robot relative to its starting position. Returns the Y position or PROS_ERR_F if the operation failed, with errno being set.

```cpp
#define GPS_PORT 1

void opcontrol() {
    Gps gps(GPS_PORT);
 while(true) {
    double pos_y = gps.get_position_y();
    printf("Y: %f\n", pos_y);
    pros::delay(20);
 }
}
```

--------------------------------

### GPS Initialization and Configuration

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Documents the `initialize_full` and `set_offset` methods for configuring the GPS sensor's initial state and offsets after creation.

```APIDOC
## `initialize_full` and `set_offset` Methods

### Description

`initialize_full` sets the GPS's offset and initial position. `set_offset` updates the GPS's offset relative to the center of turning.

### Method

`initialize_full`: `virtual std::int32_t initialize_full(double xInitial, double yInitial, double headingInitial, double xOffset, double yOffset) const`
`set_offset`: `virtual std::int32_t set_offset(double xOffset, double yOffset) const`

### Endpoint

N/A (Class Methods)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```cpp
#define GPS_PORT 1

void opcontrol() {
    pros::Gps gps(GPS_PORT, 1.1, 1.2, 180, .4, .4);
    gps.initialize_full(1.1, 1.2, 180, .4, .4); // Set initial position and offset
    gps.set_offset(.4, .4); // Update offset
    while (true) {
        delay(20);
    }
}
```

### Response

#### Success Response (200)

- **return value** (`std::int32_t`): 1 if the operation was successful.

#### Response Example

N/A

### Error Handling

- **ENXIO**: The given value is not within the range of V5 ports (1-21).
- **ENODEV**: The port cannot be configured as a GPS.
- **EAGAIN**: The sensor is still calibrating.
```

--------------------------------

### Get GPS Position X

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the current X-coordinate of the robot's position in meters, relative to its starting position. This provides a single-axis position reading.

```cpp
#include <pros/gps.hpp>

// Example usage:
pros::Gps gps(1);
double pos_x = gps.get_position_x();
// Use pos_x for calculations
```

--------------------------------

### GPS Constructor Overloads

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Provides documentation for the different constructors available for the `pros::Gps` class, allowing for initialization with various combinations of port, initial position, and offset values.

```APIDOC
## `pros::Gps` Constructors

### Description

Initializes a GPS object for a specified V5 port with given initial position and heading.

### Method

Constructor

### Endpoint

N/A (Class Constructor)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```cpp
pros::Gps gps(1, 1.30, 1.20, 90); // Constructor with port, initial x, initial y, initial heading
pros::Gps gps(1, 1.30, 1.20); // Constructor with port, x offset, y offset
pros::Gps gps(1, 1.30, 1.20, 180, 1.30, 1.20); // Constructor with port, initial x, initial y, initial heading, x offset, y offset
```

### Response

#### Success Response (200)

N/A (Object Creation)

#### Response Example

N/A

### Error Handling

- **ENXIO**: The given value is not within the range of V5 ports (1-21).
- **ENODEV**: The port cannot be configured as a GPS.
- **EAGAIN**: The sensor is still calibrating.
```

--------------------------------

### PROS Startup Configuration Functions (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__apix

Controls the PROS banner display during startup. The `enable_banner` function allows enabling or disabling the console banner, while `PRE_PROS_INIT_PRIORITY` and `ENABLE_BANNER` macro provide alternative methods for controlling initialization order and banner visibility.

```c
void enable_banner(bool enabled);

#define PRE_PROS_INIT_PRIORITY
#define ENABLE_BANNER(enabled)

```

--------------------------------

### Get GPS X Position (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the X position in meters of the robot relative to its starting position. Returns the X position or PROS_ERR_F if the operation failed, with errno being set.

```cpp
#define GPS_PORT 1

void opcontrol() {
    Gps gps(GPS_PORT);
 while(true) {
    double pos_x = gps.get_position_x();
    printf("X: %f\n", pos_x);
    pros::delay(20);
 }
}
```

--------------------------------

### Initialize LCD

Source: https://pros.cs.purdue.edu/v5/api/api-legacy

Initializes the emulated three-button, UART-based VEX LCD. This function should be called before any other LCD functions. Analogous to lcd_initialize.

```c
void initialize() {
  lcdInit();
  lcdSetText(1, "Hello World!");
}
```

--------------------------------

### Get VEX GPS Sensor Orientation (C)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__c-gps

Retrieves the pitch, roll, and yaw of the GPS sensor relative to its starting orientation. This function provides the complete 3D orientation data.

```c
gps_orientation_s_t gps_get_orientation(uint8_t port);
```

--------------------------------

### OkapiLib Robot Control with PROS 3 (C++)

Source: https://pros.cs.purdue.edu/v5/blog/pros3-announcement

This C++ code snippet demonstrates how to use the OkapiLib library within the PROS 3 environment for robot control. It showcases chassis initialization, autonomous movements (distance and turning), basic LCD output, controller input handling for tank drive, and reading data from a vision sensor. Dependencies include the OkapiLib library and PROS 3 framework.

```cpp
using namespace okapi;

void opcontrol() {
  ChassisControllerIntegrated chassis({19, 20},           // Left motors in ports 19 and 20
                                      {-13, -14},         // Right motors (reversed by "-") in ports 13 and 14
                                      pros::gearset::red, // Using the 100 RPM standard red gearset
                                      {4_in, 11.5_in});   // Physical parameters of robot for autonomous control

  // Sample autonomous movements you can do
  chassis.moveDistance(3.25_ft); // Drive the robot 3.25 feet forward
  chassis.turnAngle(45_deg);     // Turn the robot 45 degrees clockwise

  pros::lcd::set_text(4, "Hello, World!"); // Use the PROS LCD Emulator of the VEX EDR LCD Screen

  Controller controller;  // Create a controller object representing the main controller
  pros::Vision vision(1); // Create a vision sensor connected to port 1

  while (true) {
    // Tank drive with left and right sticks
    chassis.tank(controller.getAnalog(CONTROLLER_ANALOG_LEFT_Y),
                 controller.getAnalog(CONTROLLER_ANALOG_RIGHT_Y));

    pros::lcd::print(5, "There are %d objects visible", vision.get_object_count());

    // Wait and give up the time we don't need to other tasks.
    pros::delay(10);
  }

}
```

--------------------------------

### Get GPS Roll (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the roll of the robot in degrees relative to its starting orientation. Returns the roll value in the range [0,360) degrees or PROS_ERR_F if the operation failed, with errno being set.

```cpp
#define GPS_PORT 1

void opcontrol() {
    Gps gps(GPS_PORT);
 while(true) {
    double roll = gps.get_roll();
    printf("roll: %f\n", roll);
    pros::delay(20);
 }
}
```

--------------------------------

### Get GPS Pitch (C++)

Source: https://pros.cs.purdue.edu/v5/pros-4/group__cpp-gps

Retrieves the pitch of the robot in degrees relative to its starting orientation. Returns the pitch value in the range [0,360) degrees or PROS_ERR_F if the operation failed, with errno being set.

```cpp
#define GPS_PORT 1

void opcontrol() {
    Gps gps(GPS_PORT);
 while(true) {
    double pitch = gps.get_pitch();
    printf("pitch: %f\n", pitch);
    pros::delay(20);
 }
}
```
Tokens:
Raw