422 lines
12 KiB
C++
422 lines
12 KiB
C++
/**
|
|
* \file pros/link.h
|
|
* \ingroup c-link
|
|
*
|
|
* Contains prototypes for functions related to the robot to robot communications.
|
|
*
|
|
* This file should not be modified by users, since it gets replaced whenever
|
|
* a kernel upgrade occurs.
|
|
*
|
|
* \copyright (c) 2017-2023, Purdue University ACM SIGBots.
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
*
|
|
* \defgroup c-link VEX Link C API
|
|
*/
|
|
|
|
#ifndef _PROS_LINK_H_
|
|
#define _PROS_LINK_H_
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
namespace pros {
|
|
#endif
|
|
|
|
/**
|
|
* \ingroup c-link
|
|
* */
|
|
|
|
/**
|
|
* \addtogroup c-link
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* \enum link_type_e_t
|
|
* \brief Enum for the type of link (TX or RX)
|
|
*/
|
|
typedef enum link_type_e {
|
|
E_LINK_RECEIVER = 0, ///< Indicates that the radio is a receiver.
|
|
E_LINK_TRANSMITTER, ///< Indicates that the link is a transmitter.
|
|
E_LINK_RX = E_LINK_RECEIVER, ///< Alias for E_LINK_RECEIVER
|
|
E_LINK_TX = E_LINK_TRANSMITTER ///< Alias for E_LINK_TRANSMITTER
|
|
} link_type_e_t;
|
|
|
|
#ifdef PROS_USE_SIMPLE_NAMES
|
|
#ifdef __cplusplus
|
|
#define LINK_RECEIVER pros::E_LINK_RECEIVER
|
|
#define LINK_TRANSMITTER pros::E_LINK_TRANSMITTER
|
|
#define LINK_RX pros::E_LINK_RX
|
|
#define LINK_TX pros::E_LINK_TX
|
|
#else
|
|
#define LINK_RECEIVER E_LINK_RECEIVER
|
|
#define LINK_TRANSMITTER E_LINK_TRANSMITTER
|
|
#define LINK_RX E_LINK_RX
|
|
#define LINK_TX E_LINK_TX
|
|
#endif
|
|
#endif
|
|
|
|
/// @brief
|
|
/// The maximum size of a link buffer
|
|
#define LINK_BUFFER_SIZE 512
|
|
|
|
#ifdef __cplusplus
|
|
namespace c {
|
|
#endif
|
|
|
|
/**
|
|
* Initializes a link on a radio port, with an indicated type. There might be a
|
|
* 1 to 2 second delay from when this function is called to when the link is initializes.
|
|
* PROS currently only supports the use of one radio per brain.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param link_id
|
|
* Unique link ID in the form of a string, needs to be different from other links in
|
|
* the area.
|
|
* \param type
|
|
* Indicates whether the radio link on the brain is a transmitter or receiver,
|
|
* with the transmitter having double the transmitting bandwidth as the receiving
|
|
* end (1040 bytes/s vs 520 bytes/s).
|
|
*
|
|
* \return PROS_ERR if initialization fails, 1 if the initialization succeeds.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
* #define LINK_ID "ROBOT1"
|
|
*
|
|
* void initialize() {
|
|
* link_init(LINK_TRANSMITTER_PORT, LINK_ID, E_LINK_TRANSMITTER);
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_init(uint8_t port, const char* link_id, link_type_e_t type);
|
|
|
|
/**
|
|
* Initializes a link on a radio port, with an indicated type and the ability for
|
|
* vexlink to override the controller radio. There might be a 1 to 2 second delay
|
|
* from when this function is called to when the link is initializes.
|
|
* PROS currently only supports the use of one radio per brain.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param link_id
|
|
* Unique link ID in the form of a string, needs to be different from other links in
|
|
* the area.
|
|
* \param type
|
|
* Indicates whether the radio link on the brain is a transmitter or receiver,
|
|
* with the transmitter having double the transmitting bandwidth as the receiving
|
|
* end (1040 bytes/s vs 520 bytes/s).
|
|
*
|
|
* \return PROS_ERR if initialization fails, 1 if the initialization succeeds.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_PORT 1
|
|
* #define LINK_ID "ROBOT1"
|
|
*
|
|
* void initialize() {
|
|
* link_init(LINK_PORT, LINK_ID, E_LINK_TRANSMITTER);
|
|
* link_init_override(LINK_PORT, LINK_ID, E_LINK_TRANSMITTER);
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_init_override(uint8_t port, const char* link_id, link_type_e_t type);
|
|
|
|
/**
|
|
* Checks if a radio link on a port is active or not.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
*
|
|
* \return If a radio is connected to a port and it's connected to a link.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* if (link_connected(LINK_TRANSMITTER_PORT)) {
|
|
* screen_print(TEXT_MEDIUM, 1, "Link connected!");
|
|
* }
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
bool link_connected(uint8_t port);
|
|
|
|
/**
|
|
* Returns the bytes of data available to be read
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
*
|
|
* \return PROS_ERR if port is not a link/radio, else the bytes available to be
|
|
* read by the user.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_RECIVER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* uint32_t receiveable_size = link_raw_receivable_size(LINK_RECIVER_PORT);
|
|
* screen_print(TEXT_MEDIUM, 1, "link_raw_receiveable_size: %d", receiveable_size);
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_raw_receivable_size(uint8_t port);
|
|
|
|
/**
|
|
* Returns the bytes of data available in transmission buffer.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
*
|
|
* \return PROS_ERR if port is not a link/radio,
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* uint32_t transmittable_size = link_raw_transmittable_size(LINK_TRANSMITTER_PORT);
|
|
* screen_print(TEXT_MEDIUM, 1, "link_raw_transmittable_size: %d", transmittable_size);
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_raw_transmittable_size(uint8_t port);
|
|
|
|
/**
|
|
* Send raw serial data through vexlink.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
* EBUSY - The transmitter buffer is still busy with a previous transmission, and there is no
|
|
* room in the FIFO buffer (queue) to transmit the data.
|
|
* EINVAL - The data given is NULL
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param data
|
|
* Buffer with data to send
|
|
* \param data_size
|
|
* Bytes of data to be read to the destination buffer
|
|
*
|
|
* \return PROS_ERR if port is not a link, and the successfully transmitted
|
|
* data size if it succeeded.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* char* data = "Hello!";
|
|
* link_transmit_raw(LINK_TRANSMITTER_PORT, (void*)data, sizeof(*data) * sizeof(data));
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_transmit_raw(uint8_t port, void* data, uint16_t data_size);
|
|
|
|
/**
|
|
* Receive raw serial data through vexlink.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
* EINVAL - The destination given is NULL, or the size given is larger than the FIFO buffer
|
|
* or destination buffer.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param dest
|
|
* Destination buffer to read data to
|
|
* \param data_size
|
|
* Bytes of data to be read to the destination buffer
|
|
*
|
|
* \return PROS_ERR if port is not a link, and the successfully received
|
|
* data size if it succeeded.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_RECIVER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* char* result;
|
|
* char* expected = "Hello!";
|
|
* link_receive_raw(LINK_RECIVER_PORT, (void*)result, sizeof(*expected) * sizeof(expected));
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_receive_raw(uint8_t port, void* dest, uint16_t data_size);
|
|
|
|
/**
|
|
* Send packeted message through vexlink, with a checksum and start byte.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
* EBUSY - The transmitter buffer is still busy with a previous transmission, and there is no
|
|
* room in the FIFO buffer (queue) to transmit the data.
|
|
* EINVAL - The data given is NULL
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param data
|
|
* Buffer with data to send
|
|
* \param data_size
|
|
* Bytes of data to be read to the destination buffer
|
|
*
|
|
* \return PROS_ERR if port is not a link, and the successfully transmitted
|
|
* data size if it succeeded.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* char* data = "Hello!";
|
|
* link_transmit(LINK_TRANSMITTER_PORT, (void*)data, sizeof(*data) * sizeof(data));
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_transmit(uint8_t port, void* data, uint16_t data_size);
|
|
|
|
/**
|
|
* Receive packeted message through vexlink, with a checksum and start byte.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
* EINVAL - The destination given is NULL, or the size given is larger than the FIFO buffer
|
|
* or destination buffer.
|
|
* EBADMSG - Protocol error related to start byte, data size, or checksum.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
* \param dest
|
|
* Destination buffer to read data to
|
|
* \param data_size
|
|
* Bytes of data to be read to the destination buffer
|
|
*
|
|
* \return PROS_ERR if port is not a link or protocol error, and the successfully
|
|
* transmitted data size if it succeeded.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_RECIVER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* char* result;
|
|
* char* expected = "Hello!";
|
|
* link_receive(LINK_RECIVER_PORT, (void*)result, sizeof(*expected) * sizeof(expected));
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_receive(uint8_t port, void* dest, uint16_t data_size);
|
|
|
|
/**
|
|
* Clear the receive buffer of the link, and discarding the data.
|
|
*
|
|
* \note This function uses the following values of errno when an error state is
|
|
* reached:
|
|
* ENXIO - The given value is not within the range of V5 ports (1-21).
|
|
* ENODEV - The port cannot be configured as a radio.
|
|
* ENXIO - The sensor is still calibrating, or no link is connected via the radio.
|
|
*
|
|
* \param port
|
|
* The port of the radio for the intended link.
|
|
*
|
|
* \return PROS_ERR if port is not a link, and the successfully received
|
|
* data size if it succeeded.
|
|
*
|
|
* \b Example
|
|
* \code
|
|
* #define LINK_TRANSMITTER_PORT 1
|
|
*
|
|
* void opcontrol() {
|
|
* while (true) {
|
|
* char* data = "Hello!";
|
|
* link_transmit(LINK_TRANSMITTER_PORT, (void*)data, sizeof(*data) * sizeof(data));
|
|
* link_clear_receive_buf(LINK_TRANSMITTER_PORT);
|
|
* delay(20);
|
|
* }
|
|
* }
|
|
* \endcode
|
|
*/
|
|
uint32_t link_clear_receive_buf(uint8_t port);
|
|
|
|
///@}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
}
|
|
}
|
|
#endif
|
|
|
|
#endif
|