Generic Serial C++ API module

Contents

Files

file serial.hpp

Classes

class pros::Serial

Functions

Serial(std::uint8_t port, std::int32_t baudrate) explicit
Creates a Serial object for the given port and specifications.
Serial(std::uint8_t port) explicit
Creates a Serial object for the given port without a set baudrate.
std::int32_t set_baudrate(std::int32_t baudrate) const virtual
Serial communication functions
std::int32_t flush() const virtual
Clears the internal input and output FIFO buffers.
std::int32_t get_read_avail() const virtual
Returns the number of bytes available to be read in the the port's FIFO input buffer.
std::int32_t get_write_free() const virtual
Returns the number of bytes free in the port's FIFO output buffer.
std::int32_t peek_byte() const virtual
Reads the next byte avaliable in the port's input buffer without removing it.
std::int32_t read_byte() const virtual
Reads the next byte avaliable in the port's input buffer.
std::int32_t read(std::uint8_t* buffer, std::int32_t length) const virtual
Reads up to the next length bytes from the port's input buffer and places them in the user supplied buffer.
std::int32_t write_byte(std::uint8_t buffer) const virtual
Write the given byte to the port's output buffer.
std::int32_t write(std::uint8_t* buffer, std::int32_t length) const virtual
Writes up to length bytes from the user supplied buffer to the port's output buffer.

Function documentation

Serial(std::uint8_t port, std::int32_t baudrate) explicit
#include <pros/serial.hpp>

Creates a Serial object for the given port and specifications.

Parameters
port The V5 port number from 1-21
baudrate The baudrate to run the port at

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.

Example: pros::Serial serial(1, 9600);

Serial(std::uint8_t port) explicit
#include <pros/serial.hpp>

Creates a Serial object for the given port without a set baudrate.

Parameters
port The V5 port number from 1-21

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.

Example: pros::Serial serial(1);

std::int32_t set_baudrate(std::int32_t baudrate) const virtual
#include <pros/serial.hpp>

Serial communication functions

Parameters
baudrate The baudrate to operate at
Returns 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

These functions allow programmers to communicate using UART over RS485
Sets the baudrate for the serial port to operate at.

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.

Example:

pros::Serial serial(1);
serial.set_baudrate(9600);

std::int32_t flush() const virtual
#include <pros/serial.hpp>

Clears the internal input and output FIFO buffers.

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

This can be useful to reset state and remove old, potentially unneeded data from the input FIFO buffer or to cancel sending any data in the output FIFO buffer.

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.

Example:

pros::Serial serial(1);
serial.flush();

std::int32_t get_read_avail() const virtual
#include <pros/serial.hpp>

Returns the number of bytes available to be read in the the port's FIFO input buffer.

Returns The number of bytes avaliable to be read or PROS_ERR if the operation failed, setting errno.

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.

Example:

void opcontrol() {
    pros::Serial serial(1);
    if(serial.get_read_avail() > 0) {
     std::uint8_t byte = serial.read_byte();
    }
}

std::int32_t get_write_free() const virtual
#include <pros/serial.hpp>

Returns the number of bytes free in the port's FIFO output buffer.

Returns The number of bytes free or PROS_ERR if the operation failed, setting errno.

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.

Example:

void opcontrol() {
pros::Serial serial(1);
    if(serial.get_write_free() > 0) {
        serial.write_byte(0x01);
    pros::delay(10);
    }
}

std::int32_t peek_byte() const virtual
#include <pros/serial.hpp>

Reads the next byte avaliable in the port's input buffer without removing it.

Returns The next byte avaliable to be read, -1 if none are available, or PROS_ERR if the operation failed, setting errno.

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.

Example:

void opcontrol() {
    pros::Serial serial(1);
    if(serial.peek_byte() == 0x01) {
        serial.read_byte();
    }
}

std::int32_t read_byte() const virtual
#include <pros/serial.hpp>

Reads the next byte avaliable in the port's input buffer.

Returns The next byte avaliable to be read, -1 if none are available, or PROS_ERR if the operation failed, setting errno.

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.

Example:

void opcontrol() {
    pros::Serial serial(1);
    if(serial.read_byte() == 0x01) {
        // Do something
    }
}

std::int32_t read(std::uint8_t* buffer, std::int32_t length) const virtual
#include <pros/serial.hpp>

Reads up to the next length bytes from the port's input buffer and places them in the user supplied buffer.

Parameters
buffer The location to place the data read
length The maximum number of bytes to read
Returns The number of bytes read or PROS_ERR if the operation failed, setting errno.

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.

Example:

void opcontrol() {
    pros::Serial serial(1);
    std::uint8_t buffer[10];
    serial.read(buffer, 10);
}

std::int32_t write_byte(std::uint8_t buffer) const virtual
#include <pros/serial.hpp>

Write the given byte to the port's output buffer.

Parameters
buffer The byte to write
Returns The number of bytes written or PROS_ERR if the operation failed, setting errno.

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. EIO - Serious internal write error.

Example:

void opcontrol() {
    pros::Serial serial(1);
    serial.write_byte(0x01);
}

std::int32_t write(std::uint8_t* buffer, std::int32_t length) const virtual
#include <pros/serial.hpp>

Writes up to length bytes from the user supplied buffer to the port's output buffer.

Parameters
buffer The data to write
length The maximum number of bytes to write
Returns The number of bytes written or PROS_ERR if the operation failed, setting errno.

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. EIO - Serious internal write error.

Example:

void opcontrol() {
    pros::Serial serial(1);
    std::uint8_t buffer[10];
    serial.write(buffer, 10);
}