Legacy API¶

Note

Using this functionality requires including "pros/api_legacy.h" in addition to "api.h".

ADI Functions¶

analogCalibrate¶

Calibrates the analog sensor on the specified channel.

This method assumes that the true sensor value is not actively changing at this time and computes an average from approximately 500 samples, 1 ms apart, for a 0.5 s period of calibration. The average value thus calculated is returned and stored for later calls to the adi_analog_read_calibrated and adi_analog_read_calibrated_HR functions. These functions will return the difference between this value and the current sensor value when called.

Do not use this function when the sensor value might be unstable (gyro rotation, accelerometer movement).

Note

The ADI currently returns data at 10ms intervals, despite the calibrate function’s 1ms sample rate. This sample rate was kept for the sake of being similar to PROS 2, and increasing the sample rate would not have a tangible difference in the function’s performance.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be an analog input.

Analogous to adi_analog_calibrate.

int32_t analogCalibrate (uint8_t port )

#define ANALOG_SENSOR_PORT 1

void initialize() {
  analogCalibrate(ANALOG_SENSOR_PORT);
  printf("Calibrated Reading: %d\n", analogReadCalibrated(ANALOG_SENSOR_PORT));
  // All readings from then on will be calibrated
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to calibrate

Returns: The average sensor value computed by this function.

analogRead¶

Reads an analog input channel and returns the 12-bit value.

The value returned is undefined if the analog pin has been switched to a different mode. The meaning of the returned value varies depending on the sensor attached.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be an analog input.

Analogous to adi_analog_read.

int32_t analogRead (uint8_t port )

#define ANALOG_SENSOR_PORT 1

void opcontrol() {
  while (true) {
    printf("Sensor Reading: %d\n", analogRead(ANALOG_SENSOR_PORT));
    delay(50);
  }
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to read

Returns: The analog sensor value, where a value of 0 reflects an input voltage of nearly 0 V and a value of 4095 reflects an input voltage of nearly 5 V

analogReadCalibrated¶

Reads the calibrated value of an analog input channel.

The analogCalibrate function must be run first on that channel. This function is inappropriate for sensor values intended for integration, as round-off error can accumulate causing drift over time. Use analogReadCalibratedHR instead.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be an analog input.

Analogous to adi_analog_read_calibrated.

int32_t analogReadCalibrated (uint8_t port )

#define ANALOG_SENSOR_PORT 1

void opcontrol() {
  while (true) {
    printf("Sensor Reading: %d\n", analogReadCalibrated(ANALOG_SENSOR_PORT));
    delay(50);
  }
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to read

Returns: The difference of the sensor value from its calibrated default from -4095 to 4095.

analogReadCalibratedHR¶

Reads the calibrated value of an analog input channel 1-8 with enhanced precision.

The adi_analog_calibrate function must be run first. This is intended for integrated sensor values such as gyros and accelerometers to reduce drift due to round-off, and should not be used on a sensor such as a line tracker or potentiometer.

The value returned actually has 16 bits of “precision”, even though the ADC only reads 12 bits, so that errors induced by the average value being between two values come out in the wash when integrated over time. Think of the value as the true value times 16.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be an analog input.

Analogous to adi_analog_read_calibrated_HR.

int32_t analogReadCalibratedHR (uint8_t port )

#define ANALOG_SENSOR_PORT 1

void opcontrol() {
  while (true) {
    analogCalibrate(ANALOG_SENSOR_PORT);
    printf("Sensor Reading: %d\n", analogReadCalibratedHR(ANALOG_SENSOR_PORT));
    delay(50);
  }
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to read

Returns: The difference of the sensor value from its calibrated default from -16384 to 16384.

digitalRead¶

Gets the digital value (1 or 0) of a pin configured as a digital input.

If the pin is configured as some other mode, the digital value which reflects the current state of the pin is returned, which may or may not differ from the currently set value. The return value is undefined for pins configured as Analog inputs.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be a digital input.

Analogous to adi_digital_read.

int32_t digitalRead (uint8_t port )

#define DIGITAL_SENSOR_PORT 1

void opcontrol() {
  while (true) {
    printf("Sensor Value: %d\n", digitalRead(DIGITAL_SENSOR_PORT));
    delay(50);
  }
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to read

Returns: True if the pin is HIGH, or false if it is LOW.

digitalWrite¶

Sets the digital value (1 or 0) of a pin configured as a digital output.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured to be a digital output.

Analogous to adi_digital_write.

int32_t digitalWrite (uint8_t port,
                      const bool value )

#define DIGITAL_SENSOR_PORT

void opcontrol() {
  bool state = LOW;
  while (true) {
    state != state;
    digitalWrite(DIGITAL_SENSOR_PORT, state);
    delay(50); // toggle the sensor value every 50ms
  }
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to write to
value	an expression evaluating to “true” or “false” to set the output to HIGH or LOW respectively, or the constants HIGH or LOW themselves

Returns: 1 if the operation was successful, PROS_ERR otherwise.

encoderGet¶

Gets the number of ticks recorded by the encoder.

There are 360 ticks in one revolution.

This function uses the following values of errno when an error state is reached:

EINVAL - The encoder port number is out of range or the port is not configured to be an encoder.

Analogous to adi-encoder-get.

int32_t encoderGet ( Encoder enc )

#define PORT_TOP 1
#define PORT_BOTTOM 2

void opcontrol() {
  Encoder enc = encoderInit(PORT_TOP, PORT_BOTTOM, false);
  while (true) {
    printf("Encoder Value: %d\n", encoderGet(enc));
    delay(50);
  }
}

Parameters
enc	the `Encoder` object from encoderInit to read, or simply the ADI port number

Returns: The signed and cumulative number of counts since the last start or reset.

encoderInit¶

Initializes and enables a quadrature encoder on two ADI ports.

This function uses the following values of errno when an error state is reached:

EINVAL - The given ports do not match the criteria in the parameter list below.

Analogous to adi_encoder_init.

Encoder encoderInit (uint8_t port_top,
                     uint8_t port_bottom,
                     const bool reverse )

#define PORT_TOP 1
#define PORT_BOTTOM 2

void opcontrol() {
  Encoder enc = encoderInit(PORT_TOP, PORT_BOTTOM, false);
  while (true) {
    printf("Encoder Value: %d\n", encoderGet(enc));
    delay(50);
  }
}

Parameters
port_top	the “top” wire from the encoder sensor with the removable cover side UP. This should be in port 1, 3, 5, or 7 (‘A’, ‘C’, ‘E’, ‘G’).
port_bottom	the “bottom” wire from the encoder sensor
reverse	if “true”, the sensor will count in the opposite direction

Returns: An Encoder object to be stored and used for later calls to encoder functions.

encoderReset¶

Resets the encoder to zero.

It is safe to use this method while an encoder is enabled. It is not necessary to call this method before stopping or starting an encoder.

This function uses the following values of errno when an error state is reached:

EINVAL - The encoder port number is out of range or the port is not configured to be an encoder.

Analogous to adi_encoder_reset.

int32_t encoderReset ( Encoder enc )

#define PORT_TOP 1
#define PORT_BOTTOM 2

void opcontrol() {
  Encoder enc = encoderInit(PORT_TOP, PORT_BOTTOM, false);
  delay(1000); // Move the encoder around in this time
  encoderReset(enc); // The encoder is now zero again
}

Parameters
enc	the `Encoder` object from encoderInit to reset or simply the ADI port number

Returns: 1 if the operation was successful, PROS_ERR otherwise.

encoderShutdown¶

Stops and disables the encoder.

This function uses the following values of errno when an error state is reached:

EINVAL - The encoder port number is out of range or the port is not configured to be an encoder.

int32_t encoderShutdown ( Encoder enc )

#define PORT_TOP 1
#define PORT_BOTTOM 2

void opcontrol() {
  Encoder enc = encoderInit(PORT_TOP, PORT_BOTTOM, false);
  // Use the encoder
  encoderShutdown(enc);
}

Parameters
enc	the Encoder object from adi_encoder_init to shut down, or simply the ADI port number

Returns: 1 if the operation was successful, PROS_ERR otherwise.

adiMotorGet¶

Returns the last set speed of the motor on the given port.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured as a motor.

Analogous to adi_motor_get.

int32_t adiMotorGet ( uint8_t port )

#define MOTOR_PORT 1

void opcontrol() {
  adiMotorSet(MOTOR_PORT, 127); // Go full speed forward
  printf("Commanded Motor Power: %d\n", adiMotorGet(MOTOR_PORT)); // Will display 127
  delay(1000);
  adiMotorSet(MOTOR_PORT, 0); // Stop the motor
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to get

Returns: The last set speed of the motor on the given port.

adiMotorSet¶

Sets the speed of the motor on the given port.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured as a motor.

Analogous to adi_motor_set.

int32_t adiMotorSet ( uint8_t port,
                      const int8_t speed )

#define MOTOR_PORT 1

void opcontrol() {
  adiMotorSet(MOTOR_PORT, 127); // Go full speed forward
  delay(1000);
  adiMotorSet(MOTOR_PORT, 0); // Stop the motor
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to set
speed	the new signed speed; -127 is full reverse and 127 is full forward, with 0 being off

Returns: 1 if the operation was successful, PROS_ERR otherwise

adiMotorStop¶

Stops the motor on the given port.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range or the port is not configured as a motor.

Analogous to adi_motor_stop.

int32_t adi_motor_stop (uint8_t port )

#define MOTOR_PORT 1

void opcontrol() {
  adi_motor_set(MOTOR_PORT, 127); // Go full speed forward
  delay(1000);
  // adi_motor_set(MOTOR_PORT, 0); // Stop the motor
  adi_motor_stop(MOTOR_PORT); // use this instead
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to stop

Returns: 1 if the operation was successful, PROS_ERR otherwise.

pinMode¶

Configures the pin as an input or output with a variety of settings.

This function uses the following values of errno when an error state is reached:

EINVAL - The port number is out of range.

Analogous to adi_pin_mode.

int32_t pinMode ( uint8_t port,
                  const unsigned char mode )

#define ANALOG_SENSOR_PORT 1

void initialize() {
  pinMode(ANALOG_SENSOR_PORT, INPUT_ANALOG);
}

Parameters
port	The ADI port number (from 1-8, ‘a’-‘h’, ‘A’-‘H’) to configure
mode	one of INPUT, INPUT_ANALOG, OUTPUT, or OUTPUT_ANALOG

Returns: 1 if the operation was successful, PROS_ERR otherwise.

ultrasonicGet¶

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:

EINVAL - The ultrasonic port number is out of range or the ultrasonic port is not properly configured.

Analogous to adi_ultrasonic_get.

int32_t ultrasonicGet ( Ultrasonic ult )

#define PORT_ECHO 1
#define PORT_PING 2

void opcontrol() {
  Ultrasonic ult = ultrasonicInit(PORT_ECHO, PORT_PING);
  while (true) {
    // Print the distance read by the ultrasonic
    printf("Distance: %d\n", ultrasonicGet(ult));
    delay(50);
  }
}

Parameters
ult	the Ultrasonic object from ultrasonicInit to read, or simply the ADI port number

Returns: The distance to the nearest object in centimeters.

ultrasonicInit¶

Initializes an ultrasonic sensor on the specified ADI ports.

This function uses the following values of errno when an error state is reached:

EINVAL - The given ports do not match the parameter criteria given below.

Analogous to adi_ultrasonic_init.

Ultrasonic ultrasonicInit ( uint8_t port_echo,
                            uint8_t port_ping )

#define PORT_ECHO 1
#define PORT_PING 2

void opcontrol() {
  Ultrasonic ult = ultrasonicInit(PORT_ECHO, PORT_PING);
  while (true) {
    // Print the distance read by the ultrasonic
    printf("Distance: %d\n", ultrasonicGet(ult));
    delay(50);
  }
}

Parameters
port_echo	the port connected to the yellow INPUT cable. This should be in port 1, 3, 5, or 7 (‘A’, ‘C’, ‘E’, ‘G’).
port_ping	the port connected to the orange OUTPUT cable. This should be in the next highest port following port_echo.

Returns: An Ultrasonic object to be stored and used for later calls to ultrasonic functions.

ultrasonicShutdown¶

Stops and disables the ultrasonic sensor.

This function uses the following values of errno when an error state is reached:

EINVAL - The ultrasonic port number is out of range or the ultrasonic port is not properly configured.

Analogous to adi_ultrasonic_shutdown.

int32_t ultrasonicShutdown ( Ultrasonic ult )

#define PORT_ECHO 1
#define PORT_PING 2

void opcontrol() {
  Ultrasonic ult = ultrasonicInit(PORT_ECHO, PORT_PING);
  while (true) {
    // Print the distance read by the ultrasonic
    printf("Distance: %d\n", ultrasonicGet(ult));
    delay(50);
  }
  ultrasonicShutdown(ult);
}

Parameters
ult	the Ultrasonic object from ultrasonicInit to shut down, or simply the ADI port number

Returns: 1 if the operation was successful, PROS_ERR otherwise.

LCD Functions¶

lcdClear¶

Clear the text on the emulated three-button LCD screen.

This function uses the following values of errno when an error state is reached:

ENXIO - The LCD has not been initialized. Call lcd_initialize first.

Analogous to lcd_clear.

bool lcd_clear ( )

void initialize() {
  lcd_initialize();
  lcd_set_text(1, "Hello World!");
  lcd_clear(); // No more text will be displayed
}

Returns: true if the operation was successful, or false otherwise, setting errno values as specified above.

lcdClearLine¶

Clears a line on the emulated three-button LCD screen.

This function uses the following values of errno when an error state is reached:

ENXIO - The LCD has not been initialized. Call lcd_initialize first.
EINVAL - The line number specified is not in the range [0-7]

Analogous to lcd_clear_line.

bool lcdClearLine ( int16_t line )

void initialize() {
  lcdInit();
  lcdSetText(1, "Hello World!");
  lcdClearLine(1); // No more text will be displayed
}

Parameters
line	The line to clear

Returns: true if the operation was successful, or false otherwise, setting errno values as specified above.

lcdInit¶

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

Analogous to lcd_initialize.

bool lcdInit ( )

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

Returns: true if the LCD was successfully initialized, or false if it has already been initialized.

lcdIsInitialized¶

Determines whether the emulated three-button LCD has already been initialized.

Analogous to lcd_is_initialized.

bool lcdIsInitialized ( )

void initialize() {
  lcdInit();
  printf("Is the LCD initialized? %d\n", lcdIsInitialized());
  // Will Display True
}

Returns: True if the LCD has been initialized or false if not.

lcdPrint¶

Displays a formatted string on the emulated three-button LCD screen

This function uses the following values of errno when an error state is reached:

ENXIO - The LCD has not been initialized. Call lcdInit first.
EINVAL - The line number specified is not in the range [0-7]

Analogous to lcd_print.

bool lcdPrint ( int16_t line,
                const char* fmt,
                ... )

void initialize() {
  lcdInit();
}

void opcontrol {
  while (true) {
    lcdPrint(0, "Buttons Bitmap: %d\n", lcd_read_buttons());
    delay(20);
  }
}

Parameters
line	The line on which to display the text [0-7]
fmt	Format string
…	Optional list of arguments for the format string

Returns: true if the operation was successful, or false otherwise, setting errno values as specified above.

lcdReadButtons¶

Reads the button status from the emulated three-button LCD.

The value returned is a 3-bitinteger where 1 0 0 indicates the left button is pressed, 0 1 0 indicates the center button is pressed, and 0 0 1 indicates the right button is pressed. 0 is returned if no buttons are currently being pressed.

Note that this function is provided for legacy API compatibility purposes, with the caveat that the V5 touch screen does not actually support pressing multiple points on the screen at the same time.

Analogous to lcd_read_buttons.

uint8_t lcdReadButtons ( )

::

void initialize() {: lcdInit();

}

void opcontrol {

while (true) {: printf(“Buttons Bitmap: %dn”, lcdReadButtons()); delay(20);

}

Returns: The buttons pressed as a bit mask.

lcdSetText¶

Displays a string on the emulated three-button LCD screen

This function uses the following values of errno when an error state is reached:

ENXIO - The LCD has not been initialized. Call lcdInit first.
EINVAL - The line number specified is not in the range [0-7]

Analogous to lcd_set_text.

bool lcdSetText ( int16_t line,
                  const char* text )

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

Parameters
line	The line on which to display the text [0-7]
text	The text to display

Returns: true if the operation was successful, or false otherwise, setting errno values as specified above.

lcdShutdown¶

Turn off the Legacy LCD Emulator.

Calling this function will clear the entire display, and you will not be able to call any further LLEMU functions until another call to lcdInit.

This function uses the following values of errno when an error state is reached:

ENXIO - The LCD has not been initialized. Call lcdInit first.

Analogous to lcd_print.

bool lcdShutdown ( )

void initialize() {
  lcdInit();
  lcdSetText(1, "Hello World!");
  lcdShutdown(); // All done with the LCD
}

Returns: true if the operation was successful, or false otherwise, setting errno values as specified above.

Miscellaneous Functions¶

isAutonomous¶

Analogous to isAutonomous.

bool isAutonomous ( )

void my_task_fn(void* ignore) {
  while (!isAutonomous()) {
    // Wait to do anything until autonomous starts
    delay(2);
  }
  while (isAutonomous()) {
    // Run whatever code is desired to just execute in autonomous
  }
}

void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, NULL, TASK_PRIO_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "My Task");
}

Returns: True if the V5 Brain is in autonomous mode, false otherwise.

isOnline¶

Analogous to isOnline.

bool isOnline ( )

void initialize() {
  if (isOnline()) {
    // Field Control is Connected
    // Run LCD Selector code or similar
  }
}

Returns: True if the V5 Brain is connected to competition control, false otherwise.

isEnabled¶

Returns the opposite of isDisabled.

bool isEnabled ( )

void my_task_fn(void* ignore) {
  while (isEnabled()) {
    // Run competition tasks (like Lift Control or similar)
  }
}

void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, NULL, TASK_PRIO_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "My Task");
}

Returns: True if the V5 Brain is disabled, false otherwise.

joystickGetAnalog¶

Gets the value of an analog channel (joystick) on a controller.

This function uses the following values of errno when an error state is reached:

EINVAL - A value other than E_CONTROLLER_MASTER or E_CONTROLLER_PARTNER is given.
EACCES - Another resource is currently trying to access the controller port.

Analogous to controller_get_analog <./c/misc.html#controller-get-analog>`_.

int32_t joystickGetAnalog ( controller_id_e_t id,
                            controller_analog_e_t channel )

void opcontrol() {
  while (true) {
    motor_move(1, joystickGetAnalog(E_CONTROLLER_MASTER, E_CONTROLLER_ANALOG_LEFT_Y));
    delay(2);
  }
}

Parameters
id	The ID of the controller (e.g. the master or partner controller). Must be one of CONTROLLER_MASTER or CONTROLLER_PARTNER
channel	The analog channel to get. Must be one of ANALOG_LEFT_X, ANALOG_LEFT_Y, ANALOG_RIGHT_X, ANALOG_RIGHT_Y

Returns: The current reading of the analog channel: [-127, 127]. If the controller was not connected, then 0 is returned

joystickGetDigital¶

Gets the value of an digital channel (button) on a controller.

This function uses the following values of errno when an error state is reached:

EINVAL - A value other than E_CONTROLLER_MASTER or E_CONTROLLER_PARTNER is given.
EACCES - Another resource is currently trying to access the controller port.

Analogous to joystickGetDigital <./c/misc.html#joystickGetDigital>`_.

int32_t joystickGetDigital ( controller_id_e_t id,
                             controller_digital_e_t button )

void opcontrol() {
  while (true) {
    if (joystickGetDigital(E_CONTROLLER_MASTER, E_CONTROLLER_DIGITAL_A)) {
      adiMotorSet(1, 100);
    }
    else {
      adiMotorSet(1, 0);
    }

    delay(2);
  }
}

Parameters
id	The ID of the controller (e.g. the master or partner controller). Must be one of CONTROLLER_MASTER or CONTROLLER_PARTNER
button	The button to read. Must be one of DIGITAL_{RIGHT,DOWN,LEFT,UP,A,B,Y,X,R1,R2,L1,L2}

Returns: 1 if the button on the controller is pressed. If the controller was not connected, then 0 is returned

joystickIsConnected¶

Returns 0 or 1 if the controller is connected.

This function uses the following values of errno when an error state is reached:

EINVAL - A value other than E_CONTROLLER_MASTER or E_CONTROLLER_PARTNER is given.
EACCES - Another resource is currently trying to access the controller port.

Analogous to controller_is_connected.

int32_t joystickIsConnected ( controller_id_e_t id )

void opcontrol() {
  while (true) {
    if (joystickIsConnected(E_CONTROLLER_PARTNER)) {
      // Use a two controller control scheme
    }
    else {
      // Just use a single controller control scheme
    }

    delay(2);
  }
}

Parameters
id	The ID of the controller (e.g. the master or partner controller). Must be one of CONTROLLER_MASTER or CONTROLLER_PARTNER

Returns: 1 if the controller is connected, 0 otherwise

RTOS Functions¶

mutexCreate¶

Creates a mutex.

See Multitasking for details.

Analogous to mutex_create.

mutex_t mutexCreate ( )

Mutex mutex = mutexCreate();

// Acquire the mutex; other tasks using this command will wait until the mutex is released
// timeout can specify the maximum time to wait, or MAX_DELAY to wait forever
// If the timeout expires, "false" will be returned, otherwise "true"
mutexTake(mutex, MAX_DELAY);
// do some work
// Release the mutex for other tasks
mutexGive(mutex);

Returns: A handle to a newly created mutex. If an error occurred, NULL will be returned and errno can be checked for hints as to why mutexCreate failed.

mutexGive¶

Unlocks a mutex.

See Multitasking for details.

Analogous to mutex_give.

bool mutexGive ( mutex_t mutex )

Mutex mutex = mutexCreate();

// Acquire the mutex; other tasks using this command will wait until the mutex is released
// timeout can specify the maximum time to wait, or MAX_DELAY to wait forever
// If the timeout expires, "false" will be returned, otherwise "true"
mutexTake(mutex, timeout);
// do some work
// Release the mutex for other tasks
mutexGive(mutex);

Parameters
mutex	The mutex to unlock

Returns: True if the mutex was successfully returned, false otherwise. If false is returned, then errno is set with a hint about why the mutex couldn’t be returned.

mutexTake¶

Takes and locks a mutex, waiting for up to a certain number of milliseconds before timing out.

See Multitasking for details.

Analogous to mutex_take.

bool mutexTake ( mutex_t mutex,
                 uint32_t timeout )

Mutex mutex = mutexCreate();

// Acquire the mutex; other tasks using this command will wait until the mutex is released
// timeout can specify the maximum time to wait, or MAX_DELAY to wait forever
// If the timeout expires, "false" will be returned, otherwise "true"
mutexTake(mutex, timeout);
// do some work
// Release the mutex for other tasks
mutexGive(mutex);

Parameters

mutex

The mutex to take.

timeout

Time to wait before the mutex becomes available.

A timeout of 0 can be used to poll the mutex. TIMEOUT_MAX can be used to block indefinitely.

Returns: True if the mutex was successfully taken, false otherwise. If false is returned, then errno is set with a hint about why the the mutex couldn’t be taken.

taskCreate¶

Create a new task and add it to the list of tasks that are ready to run.

Analogous to task_create.

task_t taskCreate ( task_fn_t function,
                    void* parameters,
                    uint8_t prio,
                    uint16_t stack_depth,
                    const char* name )

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}
void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, NULL, TASK_PRIORITY_DEFAULT);
}

Parameters
function	Pointer to the task entry function
parameters	Pointer to memory that will be used as a parameter for the task being created. This memory should not typically come from stack, but rather from dynamically (i.e., malloc’d) or statically allocated memory.
prio	The priority at which the task should run. TASK_PRIO_DEFAULT plus/minus 1 or 2 is typically used.
stack_depth	The number of words (i.e. 4 * stack_depth) available on the task’s stack. TASK_STACK_DEPTH_DEFAULT is typically sufficient.

Returns: Will return a handle by which the newly created task can be referenced. If an error occurred, NULL will be returned and errno can be checked for hints as to why task_create failed.

taskDelay¶

Delay a task for a given number of milliseconds.

This is not the best method to have a task execute code at predefined intervals, as the delay time is measured from when the delay is requested. To delay cyclically, use taskDelayUntil.

Analogous to task_delay.

void taskDelay ( const uint32_t milliseconds )

void opcontrol() {
  while (true) {
    // Do opcontrol things
    taskDelay(2);
  }
}

Parameters
milliseconds	The number of milliseconds to wait (1000 milliseconds per second)

taskDelayUntil¶

Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution frequency.

The task will be woken up at the time *prev_time + delta, and *prev_time will be updated to reflect the time at which the task will unblock.

Analogous to task_delay_until <./c/rtos.html#task-delay-until>`_.

void taskDelayUntil ( uint32_t* const prev_time,
                      const uint32_t delta )

void opcontrol() {
  uint32_t now = millis();
  while (true) {
    // Do opcontrol things
    taskDelayUntil(&now, 2);
  }
}

Parameters
prev_time	A pointer to the location storing the setpoint time
delta	The number of milliseconds to wait (1000 milliseconds per second)

taskDelete¶

Remove a task from the RTOS real time kernel’s management. The task being deleted will be removed from all ready, blocked, suspended and event lists.

Memory dynamically allocated by the task is not automatically freed, and should be freed before the task is deleted.

Analogous to task_delete <./c/rtos.html#task-delete>`_.

void taskDelete ( TaskHandle task )

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}
void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  // Do other things
  taskDelete(my_task);
}

Parameters
task	The handle of the task to be deleted. Passing NULL will cause the calling task to be deleted.

taskGetCount¶

Returns the number of tasks the kernel is currently managing, including all ready, blocked, or suspended tasks. A task that has been deleted, but not yet reaped by the idle task will also be included in the count. Tasks recently created may take one context switch to be counted.

Analogous to task_get_count <./c/rtos.html#task-get-count>`_.

uint32_t taskGetCount ( )

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}
void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  printf("Number of Running Tasks: %d\n", taskGetCount());
}

Returns: The number of tasks that are currently being managed by the kernel

taskGetPriority¶

Obtains the priority of the specified task.

Analogous to task_get_priority <./c/rtos.html#task-get-priority>`_.

uint32_t taskGetPriority ( TaskHandle task )

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}
void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  printf("Task Priority: %d\n", taskGetPriority(my_task));
}

Parameters
task	The handle of the task to check

Returns: The priority of the task.

taskGetState¶

Returns the state of the specified task.

Analogous to task_get_state <./c/rtos.html#task-get-state>`_.

task_state_e_t taskGetState ( TaskHandle task )

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}
void initialize() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  printf("Task's State: %d\n", taskGetState(my_task));
}

Parameters
task	The handle of the task to check

Returns: The state of the task. (see task_state_e_t).

taskResume¶

Resumes the specified task, making it eligible to be scheduled.

Analogous to task_resume <./c/rtos.html#task-resume>`_.

void taskResume ( TaskHandle task )

void my_task_fn(void* ign) {
  // Do things
}
void opcontrol() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  // Do things
  taskSuspend(my_task); // The task will no longer execute
  // Do other things
  taskResume(my_task); // The task will resume execution
}

Parameters
task	The handle of the task to resume

taskSetPriority¶

Sets the priority of the specified task.

If the specified task’s state is available to be scheduled (e.g. not blocked) and new priority is higher than the currently running task, a context switch may occur.

Analogous to task_set_priority <./c/rtos.html#task-set-priority>`_.

void taskSetPriority ( TaskHandle task,
                       uint32_t prio )

void my_task_fn(void* ign) {
  // Do things
}
void opcontrol() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  taskSetPriority(my_task, TASK_PRIORITY_DEFAULT + 1);
}

Parameters
task	The handle of the task to set
prio	The new priority of the task

taskSuspend¶

Suspends the current task, making it ineligible to be scheduled.

Analogous to task_suspend <./c/rtos.html#task-suspend>`_.

void taskSuspend ( TaskHandle task )

void my_task_fn(void* ign) {
  // Do things
}
void opcontrol() {
  TaskHandle my_task = taskCreate(my_task_fn, TASK_STACK_DEPTH_DEFAULT, "PROS", TASK_PRIORITY_DEFAULT);
  // Do things
  taskSuspend(my_task); // The task will no longer execute
  // Do other things
  taskResume(my_task); // The task will resume execution
}

Parameters
task	The handle of the task to suspend

motorSet¶

Sets the voltage for the motor from -127 to 127.

This is designed to map easily to the input from the controller’s analog stick for simple opcontrol use.

This function uses the following values of errno when an error state is reached:

EINVAL - The given value is not within the range of V5 ports (1-21).
EACCES - Another resource is currently trying to access the port.

Analogous to motor_move.

int32_t motorSet ( uint8_t port,
                   const int8_t voltage )

void opcontrol() {
  while (true) {
    motorSet(1, joystickGetAnalog(E_CONTROLLER_MASTER, E_CONTROLLER_ANALOG_LEFT_Y));
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
voltage	The new motor voltage from -127 to 127

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

motorGet¶

Gets the voltage delivered to the motor in mV.

This function uses the following values of errno when an error state is reached:

EINVAL - The given value is not within the range of V5 ports (1-21).
EACCES - Another resource is currently trying to access the port.

Analogous to motor_get_voltage.

double motorGet ( uint8_t port )

void opcontrol() {
  while (true) {
    motorSet(1, joystickGetAnalog(E_CONTROLLER_MASTER, E_CONTROLLER_ANALOG_LEFT_Y));
    printf("Motor Voltage: %lf\n", motorGet(1));
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21

Returns: The motor’s voltage in mV or PROS_ERR_F if the operation failed, setting errno.

motorStop¶

Sets the motor’s output to zero.

This function uses the following values of errno when an error state is reached:

EINVAL - The given value is not within the range of V5 ports (1-21).
EACCES - Another resource is currently trying to access the port.

int32_t motorStop ( uint8_t port )

void autonomous() {
  motorSet(1, 127);
  delay(1000); // Move for 1 second
  motorStop(1);
}

Parameters
port	The V5 port number from 1-21
voltage	The new motor voltage from -127 to 127

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

Typedefs¶

Encoder¶

Reference type for an initialized encoder.

This merely contains the port number for the encoder, unlike its use as an object to store encoder data in PROS 2.

typedef int32_t Encoder;

TaskHandle¶

Points to a task handle. Used for referencing a task.

typedef void* TaskHandle;

Ultrasonic¶

Reference type for an initialized ultrasonic.

This merely contains the port number for the ultrasonic, unlike its use as an object to store encoder data in PROS 2.

typedef int32_t Ultrasonic;