Generic Serial C API module

Contents

Files

file serial.h

Serial communication functions

These functions allow programmers to communicate using UART over RS485

int32_t serial_enable(uint8_t port)
Enables generic serial on the given port.
int32_t serial_set_baudrate(uint8_t port, int32_t baudrate)
Sets the baudrate for the serial port to operate at.
int32_t serial_flush(uint8_t port)
Clears the internal input and output FIFO buffers.
int32_t serial_get_read_avail(uint8_t port)
Returns the number of bytes available to be read in the the port's FIFO input buffer.
int32_t serial_get_write_free(uint8_t port)
Returns the number of bytes free in the port's FIFO output buffer.
int32_t serial_peek_byte(uint8_t port)
Reads the next byte avaliable in the port's input buffer without removing it.
int32_t serial_read_byte(uint8_t port)
Reads the next byte avaliable in the port's input buffer.
int32_t serial_read(uint8_t port, uint8_t* buffer, int32_t length)
Reads up to the next length bytes from the port's input buffer and places them in the user supplied buffer.
int32_t serial_write_byte(uint8_t port, uint8_t buffer)
Write the given byte to the port's output buffer.
int32_t serial_write(uint8_t port, uint8_t* buffer, int32_t length)
Writes up to length bytes from the user supplied buffer to the port's output buffer.

Function documentation

int32_t serial_enable(uint8_t port)
#include <pros/serial.h>

Enables generic serial on the given port.

Parameters
port The V5 port number from 1-21
Returns 1 if the operation was successful 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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
}

int32_t serial_set_baudrate(uint8_t port, int32_t baudrate)
#include <pros/serial.h>

Sets the baudrate for the serial port to operate at.

Parameters
port The V5 port number from 1-21
baudrate The baudrate to operate at
Returns 1 if the operation was successful 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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        serial_write(1, "Hello World!", 12);
        delay(100);
    }
}

int32_t serial_flush(uint8_t port)
#include <pros/serial.h>

Clears the internal input and output FIFO buffers.

Parameters
port The V5 port number from 1-21
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:

void opcontrol() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        serial_flush(1);
        serial_write(1, "Hello World!", 12);
        delay(100);
    }
}

int32_t serial_get_read_avail(uint8_t port)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_get_read_avail(1) >= 12) {
            char buffer[12];
            serial_read(1, buffer, 12);
            printf("%s", buffer);
        }
        delay(100);
    }
}

int32_t serial_get_write_free(uint8_t port)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_get_write_free(1) >= 12) {
            serial_write(1, "Hello World!", 12);
        }
        delay(100);
    }
}

int32_t serial_peek_byte(uint8_t port)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_peek_byte(1) == 'H') {
            char buffer[12];
            serial_read(1, buffer, 12);
            printf("%s", buffer);
        }
        delay(100);
    }
}

int32_t serial_read_byte(uint8_t port)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_read_byte(1) == 'H') {
            char buffer[12];
            serial_read(1, buffer, 12);
            printf("%s", buffer);
        }
        delay(100);
    }
}

int32_t serial_read(uint8_t port, uint8_t* buffer, int32_t length)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_get_read_avail(1) >= 12) {
            char buffer[12];
            serial_read(1, buffer, 12);
            printf("%s", buffer);
        }
        delay(100);
    }
}

int32_t serial_write_byte(uint8_t port, uint8_t buffer)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_get_write_free(1) >= 12) {
            serial_write_byte(1, 'H');
            serial_write_byte(1, 'e');
            serial_write_byte(1, 'l');
            serial_write_byte(1, 'l');
            serial_write_byte(1, 'o');
            serial_write_byte(1, ' ');
            serial_write_byte(1, 'W');
            serial_write_byte(1, 'o');
            serial_write_byte(1, 'r');
            serial_write_byte(1, 'l');
            serial_write_byte(1, 'd');
            serial_write_byte(1, '!');
            serial_write_byte(1, '\n');
        }
        delay(100);
    }
}

int32_t serial_write(uint8_t port, uint8_t* buffer, int32_t length)
#include <pros/serial.h>

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

Parameters
port The V5 port number from 1-21
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() {
    serial_enable(1);
    serial_set_baudrate(1, 9600);
    while (true) {
        if (serial_get_write_free(1) >= 12) {
            serial_write(1, "Hello World!\n", 12);
        }
        delay(100);
    }
}