diff --git a/hal/src/main/native/athena/FRCDriverStation.cpp b/hal/src/main/native/athena/FRCDriverStation.cpp index 3607fdd533..520fd25c0d 100644 --- a/hal/src/main/native/athena/FRCDriverStation.cpp +++ b/hal/src/main/native/athena/FRCDriverStation.cpp @@ -226,7 +226,7 @@ double HAL_GetMatchTime(int32_t* status) { return matchTime; } -int HAL_GetMatchInfo(HAL_MatchInfo* info) { +int32_t HAL_GetMatchInfo(HAL_MatchInfo* info) { uint16_t gameSpecificMessageSize = 0; int status = FRC_NetworkCommunication_getMatchInfo( nullptr, nullptr, nullptr, nullptr, nullptr, &gameSpecificMessageSize); diff --git a/hal/src/main/native/include/HAL/Accelerometer.h b/hal/src/main/native/include/HAL/Accelerometer.h index f218c95fd7..0b2c6db03f 100644 --- a/hal/src/main/native/include/HAL/Accelerometer.h +++ b/hal/src/main/native/include/HAL/Accelerometer.h @@ -9,6 +9,9 @@ #include "HAL/Types.h" +/** + * The acceptable accelerometer ranges. + */ enum HAL_AccelerometerRange : int32_t { HAL_AccelerometerRange_k2G = 0, HAL_AccelerometerRange_k4G = 1, @@ -19,35 +22,47 @@ enum HAL_AccelerometerRange : int32_t { extern "C" { #endif /** - * Set the accelerometer to active or standby mode. It must be in standby - * mode to change any configuration. + * Sets the accelerometer to active or standby mode. + * + * It must be in standby mode to change any configuration. + * + * @param active true to set to active, false for standby */ void HAL_SetAccelerometerActive(HAL_Bool active); /** - * Set the range of values that can be measured (either 2, 4, or 8 g-forces). + * Sets the range of values that can be measured (either 2, 4, or 8 g-forces). + * * The accelerometer should be in standby mode when this is called. + * + * @param range the accelerometer range */ void HAL_SetAccelerometerRange(HAL_AccelerometerRange range); /** - * Get the x-axis acceleration + * Gets the x-axis acceleration. * - * This is a floating point value in units of 1 g-force + * This is a floating point value in units of 1 g-force. + * + * @return the X acceleration */ double HAL_GetAccelerometerX(void); /** - * Get the y-axis acceleration + * Gets the y-axis acceleration. * - * This is a floating point value in units of 1 g-force + * This is a floating point value in units of 1 g-force. + * + * @return the Y acceleration */ double HAL_GetAccelerometerY(void); /** - * Get the z-axis acceleration + * Gets the z-axis acceleration. * - * This is a floating point value in units of 1 g-force + * This is a floating point value in units of 1 g-force. + * + * @return the Z acceleration */ double HAL_GetAccelerometerZ(void); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/AnalogGyro.h b/hal/src/main/native/include/HAL/AnalogGyro.h index 94b47fd2b8..2ee8df408c 100644 --- a/hal/src/main/native/include/HAL/AnalogGyro.h +++ b/hal/src/main/native/include/HAL/AnalogGyro.h @@ -15,23 +15,116 @@ extern "C" { #endif +/** + * Initializes an analog gyro. + * + * @param handle handle to the analog port + * @return the initialized gyro handle + */ HAL_GyroHandle HAL_InitializeAnalogGyro(HAL_AnalogInputHandle handle, int32_t* status); + +/** + * Sets up an analog gyro with the proper offsets and settings for the KOP + * analog gyro. + * + * @param handle the gyro handle + */ void HAL_SetupAnalogGyro(HAL_GyroHandle handle, int32_t* status); + +/** + * Frees an analog gyro. + * + * @param handle the gyro handle + */ void HAL_FreeAnalogGyro(HAL_GyroHandle handle); + +/** + * Sets the analog gyro parameters to the specified values. + * + * This is meant to be used if you want to reuse the values from a previous + * calibration. + * + * @param handle the gyro handle + * @param voltsPerDegreePerSecond the gyro volts scaling + * @param offset the gyro offset + * @param center the gyro center + */ void HAL_SetAnalogGyroParameters(HAL_GyroHandle handle, double voltsPerDegreePerSecond, double offset, int32_t center, int32_t* status); + +/** + * Sets the analog gyro volts per degrees per second scaling. + * + * @param handle the gyro handle + * @param voltsPerDegreePerSecond the gyro volts scaling + */ void HAL_SetAnalogGyroVoltsPerDegreePerSecond(HAL_GyroHandle handle, double voltsPerDegreePerSecond, int32_t* status); + +/** + * Resets the analog gyro value to 0. + * + * @param handle the gyro handle + */ void HAL_ResetAnalogGyro(HAL_GyroHandle handle, int32_t* status); + +/** + * Calibrates the analog gyro. + * + * This happens by calculating the average value of the gyro over 5 seconds, and + * setting that as the center. Note that this call blocks for 5 seconds to + * perform this. + * + * @param handle the gyro handle + */ void HAL_CalibrateAnalogGyro(HAL_GyroHandle handle, int32_t* status); + +/** + * Sets the deadband of the analog gyro. + * + * @param handle the gyro handle + * @param volts the voltage deadband + */ void HAL_SetAnalogGyroDeadband(HAL_GyroHandle handle, double volts, int32_t* status); + +/** + * Gets the gyro angle in degrees. + * + * @param handle the gyro handle + * @return the gyro angle in degrees + */ double HAL_GetAnalogGyroAngle(HAL_GyroHandle handle, int32_t* status); + +/** + * Gets the gyro rate in degrees/second. + * + * @param handle the gyro handle + * @return the gyro rate in degrees/second + */ double HAL_GetAnalogGyroRate(HAL_GyroHandle handle, int32_t* status); + +/** + * Gets the calibrated gyro offset. + * + * Can be used to not repeat a calibration but reconstruct the gyro object. + * + * @param handle the gyro handle + * @return the gryo offset + */ double HAL_GetAnalogGyroOffset(HAL_GyroHandle handle, int32_t* status); + +/** + * Gets the calibrated gyro center. + * + * Can be used to not repeat a calibration but reconstruct the gyro object. + * + * @param handle the gyro handle + * @return the gyro center + */ int32_t HAL_GetAnalogGyroCenter(HAL_GyroHandle handle, int32_t* status); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/AnalogInput.h b/hal/src/main/native/include/HAL/AnalogInput.h index 7ec004a3d9..445d6f54b7 100644 --- a/hal/src/main/native/include/HAL/AnalogInput.h +++ b/hal/src/main/native/include/HAL/AnalogInput.h @@ -16,20 +16,23 @@ extern "C" { #endif /** - * Initialize the analog input port using the given port object. + * Initializes the analog input port using the given port object. * * @param portHandle Handle to the port to initialize. + * @return the created analog input handle */ HAL_AnalogInputHandle HAL_InitializeAnalogInputPort(HAL_PortHandle portHandle, int32_t* status); /** + * Frees an analog input port. + * * @param analogPortHandle Handle to the analog port. */ void HAL_FreeAnalogInputPort(HAL_AnalogInputHandle analogPortHandle); /** - * Check that the analog module number is valid. + * Checks that the analog module number is valid. * * @param module The analog module number. * @return Analog module is valid and present @@ -37,8 +40,8 @@ void HAL_FreeAnalogInputPort(HAL_AnalogInputHandle analogPortHandle); HAL_Bool HAL_CheckAnalogModule(int32_t module); /** - * Check that the analog output channel number is value. - * Verify that the analog channel number is one of the legal channel numbers. + * Checks that the analog output channel number is value. + * Verifies that the analog channel number is one of the legal channel numbers. * Channel numbers are 0-based. * * @param channel The analog output channel number. @@ -47,7 +50,7 @@ HAL_Bool HAL_CheckAnalogModule(int32_t module); HAL_Bool HAL_CheckAnalogInputChannel(int32_t channel); /** - * Set the sample rate. + * Sets the sample rate. * * This is a global setting for the Athena and effects all channels. * @@ -56,7 +59,7 @@ HAL_Bool HAL_CheckAnalogInputChannel(int32_t channel); void HAL_SetAnalogSampleRate(double samplesPerSecond, int32_t* status); /** - * Get the current sample rate. + * Gets the current sample rate. * * This assumes one entry in the scan list. * This is a global setting for the Athena and effects all channels. @@ -66,7 +69,7 @@ void HAL_SetAnalogSampleRate(double samplesPerSecond, int32_t* status); double HAL_GetAnalogSampleRate(int32_t* status); /** - * Set the number of averaging bits. + * Sets the number of averaging bits. * * This sets the number of averaging bits. The actual number of averaged samples * is 2**bits. Use averaging to improve the stability of your measurement at the @@ -79,7 +82,7 @@ void HAL_SetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, int32_t bits, int32_t* status); /** - * Get the number of averaging bits. + * Gets the number of averaging bits. * * This gets the number of averaging bits from the FPGA. The actual number of * averaged samples is 2**bits. The averaging is done automatically in the FPGA. @@ -91,7 +94,7 @@ int32_t HAL_GetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Set the number of oversample bits. + * Sets the number of oversample bits. * * This sets the number of oversample bits. The actual number of oversampled * values is 2**bits. Use oversampling to improve the resolution of your @@ -105,7 +108,7 @@ void HAL_SetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, int32_t bits, int32_t* status); /** - * Get the number of oversample bits. + * Gets the number of oversample bits. * * This gets the number of oversample bits from the FPGA. The actual number of * oversampled values is 2**bits. The oversampling is done automatically in the @@ -118,7 +121,7 @@ int32_t HAL_GetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Get a sample straight from the channel on this module. + * Gets a sample straight from the channel on this module. * * The sample is a 12-bit value representing the 0V to 5V range of the A/D * converter in the module. The units are in A/D converter codes. Use @@ -131,7 +134,7 @@ int32_t HAL_GetAnalogValue(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Get a sample from the output of the oversample and average engine for the + * Gets a sample from the output of the oversample and average engine for the * channel. * * The sample is 12-bit + the value configured in SetOversampleBits(). @@ -148,7 +151,7 @@ int32_t HAL_GetAnalogAverageValue(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Convert a voltage to a raw value for a specified channel. + * Converts a voltage to a raw value for a specified channel. * * This process depends on the calibration of each channel, so the channel must * be specified. @@ -163,7 +166,7 @@ int32_t HAL_GetAnalogVoltsToValue(HAL_AnalogInputHandle analogPortHandle, double voltage, int32_t* status); /** - * Get a scaled sample straight from the channel on this module. + * Gets a scaled sample straight from the channel on this module. * * The value is scaled to units of Volts using the calibrated scaling data from * GetLSBWeight() and GetOffset(). @@ -175,7 +178,7 @@ double HAL_GetAnalogVoltage(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Get a scaled sample from the output of the oversample and average engine for + * Gets a scaled sample from the output of the oversample and average engine for * the channel. * * The value is scaled to units of Volts using the calibrated scaling data from @@ -191,7 +194,7 @@ double HAL_GetAnalogAverageVoltage(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Get the factory scaling least significant bit weight constant. + * Gets the factory scaling least significant bit weight constant. * The least significant bit weight constant for the channel that was calibrated * in manufacturing and stored in an eeprom in the module. * @@ -204,7 +207,7 @@ int32_t HAL_GetAnalogLSBWeight(HAL_AnalogInputHandle analogPortHandle, int32_t* status); /** - * Get the factory scaling offset constant. + * Gets the factory scaling offset constant. * The offset constant for the channel that was calibrated in manufacturing and * stored in an eeprom in the module. * diff --git a/hal/src/main/native/include/HAL/AnalogOutput.h b/hal/src/main/native/include/HAL/AnalogOutput.h index 6254a3ed39..d0884294f0 100644 --- a/hal/src/main/native/include/HAL/AnalogOutput.h +++ b/hal/src/main/native/include/HAL/AnalogOutput.h @@ -16,22 +16,43 @@ extern "C" { #endif /** - * Initialize the analog output port using the given port object. + * Initializes the analog output port using the given port object. + * + * @param handle handle to the port + * @return the created analog output handle */ HAL_AnalogOutputHandle HAL_InitializeAnalogOutputPort(HAL_PortHandle portHandle, int32_t* status); +/** + * Frees an analog output port. + * + * @param analogOutputHandle the analog output handle + */ void HAL_FreeAnalogOutputPort(HAL_AnalogOutputHandle analogOutputHandle); +/** + * Sets an analog output value. + * + * @param analogOutputHandle the analog output handle + * @param voltage the voltage (0-5v) to output + */ void HAL_SetAnalogOutput(HAL_AnalogOutputHandle analogOutputHandle, double voltage, int32_t* status); +/** + * Gets the current analog output value. + * + * @param analogOutputHandle the analog output handle + * @return the current output voltage (0-5v) + */ double HAL_GetAnalogOutput(HAL_AnalogOutputHandle analogOutputHandle, int32_t* status); /** - * Check that the analog output channel number is value. - * Verify that the analog channel number is one of the legal channel numbers. + * Checks that the analog output channel number is value. + * + * Verifies that the analog channel number is one of the legal channel numbers. * Channel numbers are 0-based. * * @return Analog channel is valid diff --git a/hal/src/main/native/include/HAL/AnalogTrigger.h b/hal/src/main/native/include/HAL/AnalogTrigger.h index 72cfbdeedf..59face9bd3 100644 --- a/hal/src/main/native/include/HAL/AnalogTrigger.h +++ b/hal/src/main/native/include/HAL/AnalogTrigger.h @@ -11,6 +11,9 @@ #include "HAL/Types.h" +/** + * The type of analog trigger to trigger on. + */ enum HAL_AnalogTriggerType : int32_t { HAL_Trigger_kInWindow = 0, HAL_Trigger_kState = 1, @@ -21,60 +24,107 @@ enum HAL_AnalogTriggerType : int32_t { #ifdef __cplusplus extern "C" { #endif + +/** + * Initializes an analog trigger. + * + * @param portHandle the analog input to use for triggering + * @param index the trigger index value (output) + * @return the created analog trigger handle + */ HAL_AnalogTriggerHandle HAL_InitializeAnalogTrigger( HAL_AnalogInputHandle portHandle, int32_t* index, int32_t* status); + +/** + * Frees an analog trigger. + * + * @param analogTriggerHandle the trigger handle + */ void HAL_CleanAnalogTrigger(HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); + +/** + * Sets the raw ADC upper and lower limits of the analog trigger. + * + * HAL_SetAnalogTriggerLimitsVoltage is likely better in most cases. + * + * @param analogTriggerHandle the trigger handle + * @param lower the lower ADC value + * @param upper the upper ADC value + */ void HAL_SetAnalogTriggerLimitsRaw(HAL_AnalogTriggerHandle analogTriggerHandle, int32_t lower, int32_t upper, int32_t* status); /** - * Set the upper and lower limits of the analog trigger. + * Sets the upper and lower limits of the analog trigger. + * * The limits are given as floating point voltage values. + * + * @param analogTriggerHandle the trigger handle + * @param lower the lower voltage value + * @param upper the upper voltage value */ void HAL_SetAnalogTriggerLimitsVoltage( HAL_AnalogTriggerHandle analogTriggerHandle, double lower, double upper, int32_t* status); /** - * Configure the analog trigger to use the averaged vs. raw values. + * Configures the analog trigger to use the averaged vs. raw values. + * * If the value is true, then the averaged value is selected for the analog * trigger, otherwise the immediate value is used. + * + * @param analogTriggerHandle the trigger handle + * @param useAveragedValue true to use averaged values, false for raw */ void HAL_SetAnalogTriggerAveraged(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_Bool useAveragedValue, int32_t* status); /** - * Configure the analog trigger to use a filtered value. + * Configures the analog trigger to use a filtered value. + * * The analog trigger will operate with a 3 point average rejection filter. This * is designed to help with 360 degree pot applications for the period where the * pot crosses through zero. + * + * @param analogTriggerHandle the trigger handle + * @param useFilteredValue true to use filtered values, false for average or + * raw */ void HAL_SetAnalogTriggerFiltered(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_Bool useFilteredValue, int32_t* status); /** - * Return the InWindow output of the analog trigger. + * Returns the InWindow output of the analog trigger. + * * True if the analog input is between the upper and lower limits. - * @return The InWindow output of the analog trigger. + * + * @param analogTriggerHandle the trigger handle + * @return the InWindow output of the analog trigger */ HAL_Bool HAL_GetAnalogTriggerInWindow( HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); /** - * Return the TriggerState output of the analog trigger. + * Returns the TriggerState output of the analog trigger. + * * True if above upper limit. * False if below lower limit. * If in Hysteresis, maintain previous state. - * @return The TriggerState output of the analog trigger. + * + * @param analogTriggerHandle the trigger handle + * @return the TriggerState output of the analog trigger */ HAL_Bool HAL_GetAnalogTriggerTriggerState( HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); /** - * Get the state of the analog trigger output. - * @return The state of the analog trigger output. + * Gets the state of the analog trigger output. + * + * @param analogTriggerHandle the trigger handle + * @param type the type of trigger to trigger on + * @return the state of the analog trigger output */ HAL_Bool HAL_GetAnalogTriggerOutput(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_AnalogTriggerType type, diff --git a/hal/src/main/native/include/HAL/CAN.h b/hal/src/main/native/include/HAL/CAN.h index 16a1577d97..01da4ff34a 100644 --- a/hal/src/main/native/include/HAL/CAN.h +++ b/hal/src/main/native/include/HAL/CAN.h @@ -27,6 +27,9 @@ #define HAL_ERR_CANSessionMux_NotInitialized -44089 #define HAL_ERR_CANSessionMux_SessionOverrun 44050 +/** + * Storage for CAN Stream Messages. + */ struct HAL_CANStreamMessage { uint32_t messageID; uint32_t timeStamp; @@ -38,19 +41,73 @@ struct HAL_CANStreamMessage { extern "C" { #endif +/** + * Sends a CAN message. + * + * @param messageID the CAN ID to send + * @param data the data to send (0-8 bytes) + * @param dataSize the size of the data to send (0-8 bytes) + * @param periodMs the period to repeat the packet at. Use + * HAL_CAN_SEND_PERIOD_NO_REPEAT to not repeat. + */ void HAL_CAN_SendMessage(uint32_t messageID, const uint8_t* data, uint8_t dataSize, int32_t periodMs, int32_t* status); + +/** + * Receives a CAN message. + * + * @param messageID store for the received message ID + * @param messageIDMask the message ID mask to look for + * @param data data output (8 bytes) + * @param dataSize data length (0-8 bytes) + * @param timeStamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + */ void HAL_CAN_ReceiveMessage(uint32_t* messageID, uint32_t messageIDMask, uint8_t* data, uint8_t* dataSize, uint32_t* timeStamp, int32_t* status); + +/** + * Opens a CAN stream. + * + * @param sessionHandle output for the session handle + * @param messageID the message ID to read + * @param messageIDMask the mssage ID mask + * @param maxMessages the maximum number of messages to stream + */ void HAL_CAN_OpenStreamSession(uint32_t* sessionHandle, uint32_t messageID, uint32_t messageIDMask, uint32_t maxMessages, int32_t* status); + +/** + * Closes a CAN stream. + * + * @param sessionHandle the session to close + */ void HAL_CAN_CloseStreamSession(uint32_t sessionHandle); + +/** + * Reads a CAN stream message. + * + * @param sessionHandle the session handle + * @param messages array of messages + * @param messagesToRead the max number of messages to read + * @param messageRead the number of messages actually read + */ void HAL_CAN_ReadStreamSession(uint32_t sessionHandle, struct HAL_CANStreamMessage* messages, uint32_t messagesToRead, uint32_t* messagesRead, int32_t* status); + +/** + * Gets CAN status information. + * + * @param percentBusUtilization the bus utilization + * @param busOffCount the number of bus off errors + * @param txFullCount the number of tx full errors + * @param receiveErrorCount the number of receive errors + * @param transmitErrorCount the number of transmit errors + */ void HAL_CAN_GetCANStatus(float* percentBusUtilization, uint32_t* busOffCount, uint32_t* txFullCount, uint32_t* receiveErrorCount, uint32_t* transmitErrorCount, int32_t* status); diff --git a/hal/src/main/native/include/HAL/CANAPI.h b/hal/src/main/native/include/HAL/CANAPI.h index d996047709..46a255520e 100644 --- a/hal/src/main/native/include/HAL/CANAPI.h +++ b/hal/src/main/native/include/HAL/CANAPI.h @@ -11,6 +11,11 @@ #include "HAL/Types.h" +/** + * The CAN device type. + * + * Teams should use HAL_CAN_Dev_kMiscellaneous + */ enum HAL_CANDeviceType : int32_t { HAL_CAN_Dev_kBroadcast = 0, HAL_CAN_Dev_kRobotController = 1, @@ -26,6 +31,11 @@ enum HAL_CANDeviceType : int32_t { HAL_CAN_Dev_kFirmwareUpdate = 31 }; +/** + * The CAN manufacturer ID. + * + * Teams should use HAL_CAN_Man_kTeamUse. + */ enum HAL_CANManufacturer : int32_t { HAL_CAN_Man_kBroadcast = 0, HAL_CAN_Man_kNI = 1, @@ -40,34 +50,135 @@ enum HAL_CANManufacturer : int32_t { extern "C" { #endif +/** + * Initializes a CAN device. + * + * These follow the FIRST standard CAN layout. Link TBD + * + * @param manufacturer the can manufacturer + * @param deviceId the device ID (0-63) + * @param deviceType the device type + * @return the created CAN handle + */ HAL_CANHandle HAL_InitializeCAN(HAL_CANManufacturer manufacturer, int32_t deviceId, HAL_CANDeviceType deviceType, int32_t* status); +/** + * Frees a CAN device + * + * @param handle the CAN handle + */ void HAL_CleanCAN(HAL_CANHandle handle); +/** + * Writes a packet to the CAN device with a specific ID. + * + * This ID is 10 bits. + * + * @param handle the CAN handle + * @param data the data to write (0-8 bytes) + * @param length the length of data (0-8) + * @param apiId the ID to write (0-1023 bits) + */ void HAL_WriteCANPacket(HAL_CANHandle handle, const uint8_t* data, int32_t length, int32_t apiId, int32_t* status); +/** + * Writes a repeating packet to the CAN device with a specific ID. + * + * This ID is 10 bits. + * + * The RoboRIO will automatically repeat the packet at the specified interval + * + * @param handle the CAN handle + * @param data the data to write (0-8 bytes) + * @param length the length of data (0-8) + * @param apiId the ID to write (0-1023) + * @param repeatMs the period to repeat in ms + */ void HAL_WriteCANPacketRepeating(HAL_CANHandle handle, const uint8_t* data, int32_t length, int32_t apiId, int32_t repeatMs, int32_t* status); +/** + * Stops a repeating packet with a specific ID. + * + * This ID is 10 bits. + * + * @param handle the CAN handle + * @param apiId the ID to stop repeating (0-1023) + */ void HAL_StopCANPacketRepeating(HAL_CANHandle handle, int32_t apiId, int32_t* status); +/** + * Reads a new CAN packet. + * + * This will only return properly once per packet received. Multiple calls + * without receiving another packet will return an error code. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param data the packet data (8 bytes) + * @param length the received length (0-8 bytes) + * @param receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + */ void HAL_ReadCANPacketNew(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, int32_t* status); +/** + * Reads a CAN packet. The will continuously return the last packet received, + * without accounting for packet age. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param data the packet data (8 bytes) + * @param length the received length (0-8 bytes) + * @param receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + */ void HAL_ReadCANPacketLatest(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, int32_t* status); +/** + * Reads a CAN packet. The will return the last packet received until the + * packet is older then the requested timeout. Then it will return an error + * code. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param data the packet data (8 bytes) + * @param length the received length (0-8 bytes) + * @param receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param timeoutMs the timeout time for the packet + */ void HAL_ReadCANPacketTimeout(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, int32_t timeoutMs, int32_t* status); + +/** + * Reads a CAN packet. The will return the last packet received until the + * packet is older then the requested timeout. Then it will return an error + * code. The period parameter is used when you know the packet is sent at + * specific intervals, so calls will not attempt to read a new packet from the + * network until that period has passed. We do not recommend users use this + * API unless they know the implications. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param data the packet data (8 bytes) + * @param length the received length (0-8 bytes) + * @param receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param timeoutMs the timeout time for the packet + * @param periodMs the standard period for the packet + */ void HAL_ReadCANPeriodicPacket(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, int32_t timeoutMs, diff --git a/hal/src/main/native/include/HAL/Compressor.h b/hal/src/main/native/include/HAL/Compressor.h index 5c7e57fb49..664dbe8af7 100644 --- a/hal/src/main/native/include/HAL/Compressor.h +++ b/hal/src/main/native/include/HAL/Compressor.h @@ -15,32 +15,120 @@ extern "C" { #endif +/** + * Initializes a compressor on the given PCM module. + * + * @param module the module number + * @return the created handle + */ HAL_CompressorHandle HAL_InitializeCompressor(int32_t module, int32_t* status); + +/** + * Gets if a compressor module is valid. + * + * @param module the module number + * @return true if the module is valid, otherwise false + */ HAL_Bool HAL_CheckCompressorModule(int32_t module); +/** + * Gets the compressor state (on or off). + * + * @param compressorHandle the compressor handle + * @return true if the compressor is on, otherwise false + */ HAL_Bool HAL_GetCompressor(HAL_CompressorHandle compressorHandle, int32_t* status); +/** + * Sets the compressor to closed loop mode. + * + * @param compressorHandle the compressor handle + * @param value true for closed loop mode, false for off + */ void HAL_SetCompressorClosedLoopControl(HAL_CompressorHandle compressorHandle, HAL_Bool value, int32_t* status); + +/** + * Gets if the compressor is in closed loop mode. + * + * @param compressorHandle the compressor handle + * @return true if the compressor is in closed loop mode, + * otherwise false + */ HAL_Bool HAL_GetCompressorClosedLoopControl( HAL_CompressorHandle compressorHandle, int32_t* status); +/** + * Gets the compressor pressure switch state. + * + * @param compressorHandle the compressor handle + * @return true if the pressure switch is triggered, otherwise + * false + */ HAL_Bool HAL_GetCompressorPressureSwitch(HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets the compressor current. + * + * @param compressorHandle the compressor handle + * @return the compressor current in amps + */ double HAL_GetCompressorCurrent(HAL_CompressorHandle compressorHandle, int32_t* status); +/** + * Gets if the compressor is faulted because of too high of current. + * + * @param compressorHandle the compressor handle + * @return true if falted, otherwise false + */ HAL_Bool HAL_GetCompressorCurrentTooHighFault( HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets if a sticky fauly is triggered because of too high of current. + * + * @param compressorHandle the compressor handle + * @return true if falted, otherwise false + */ HAL_Bool HAL_GetCompressorCurrentTooHighStickyFault( HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets if a sticky fauly is triggered because of a short. + * + * @param compressorHandle the compressor handle + * @return true if falted, otherwise false + */ HAL_Bool HAL_GetCompressorShortedStickyFault( HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets if the compressor is faulted because of a short. + * + * @param compressorHandle the compressor handle + * @return true if shorted, otherwise false + */ HAL_Bool HAL_GetCompressorShortedFault(HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets if a sticky fault is triggered of the compressor not connected. + * + * @param compressorHandle the compressor handle + * @return true if falted, otherwise false + */ HAL_Bool HAL_GetCompressorNotConnectedStickyFault( HAL_CompressorHandle compressorHandle, int32_t* status); + +/** + * Gets if the compressor is not connected. + * + * @param compressorHandle the compressor handle + * @return true if not connected, otherwise false + */ HAL_Bool HAL_GetCompressorNotConnectedFault( HAL_CompressorHandle compressorHandle, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/Constants.h b/hal/src/main/native/include/HAL/Constants.h index 60c72f6cb2..9be68e5dd4 100644 --- a/hal/src/main/native/include/HAL/Constants.h +++ b/hal/src/main/native/include/HAL/Constants.h @@ -13,6 +13,11 @@ extern "C" { #endif +/** + * Gets the number of FPGA system clock ticks per microsecond. + * + * @return the number of clock ticks per microsecond + */ int32_t HAL_GetSystemClockTicksPerMicrosecond(void); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/Counter.h b/hal/src/main/native/include/HAL/Counter.h index cc7a1a2797..85bdc5c732 100644 --- a/hal/src/main/native/include/HAL/Counter.h +++ b/hal/src/main/native/include/HAL/Counter.h @@ -12,6 +12,9 @@ #include "HAL/AnalogTrigger.h" #include "HAL/Types.h" +/** + * The counter mode. + */ enum HAL_Counter_Mode : int32_t { HAL_Counter_kTwoPulse = 0, HAL_Counter_kSemiperiod = 1, @@ -22,15 +25,41 @@ enum HAL_Counter_Mode : int32_t { #ifdef __cplusplus extern "C" { #endif + +/** + * Initializes a counter. + * + * @param mode the counter mode + * @param index the compressor index (output) + * @return the created handle + */ HAL_CounterHandle HAL_InitializeCounter(HAL_Counter_Mode mode, int32_t* index, int32_t* status); + +/** + * Frees a counter. + * + * @param counterHandle the counter handle + */ void HAL_FreeCounter(HAL_CounterHandle counterHandle, int32_t* status); + +/** + * Sets the average sample size of a counter. + * + * @param counterHandle the counter handle + * @param size the size of samples to average + */ void HAL_SetCounterAverageSize(HAL_CounterHandle counterHandle, int32_t size, int32_t* status); /** - * Set the source object that causes the counter to count up. - * Set the up counting DigitalSource. + * Sets the source object that causes the counter to count up. + * + * @param counterHandle the counter handle + * @param digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle of a HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog + * trigger */ void HAL_SetCounterUpSource(HAL_CounterHandle counterHandle, HAL_Handle digitalSourceHandle, @@ -38,21 +67,33 @@ void HAL_SetCounterUpSource(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the edge sensitivity on an up counting source. - * Set the up source to either detect rising edges or falling edges. + * Sets the up source to either detect rising edges or falling edges. + * + * Note that both are allowed to be set true at the same time without issues. + * + * @param counterHandle the counter handle + * @param risingEdge true to trigger on rising + * @param fallingEdge true to trigger on falling */ void HAL_SetCounterUpSourceEdge(HAL_CounterHandle counterHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, int32_t* status); /** - * Disable the up counting source to the counter. + * Disables the up counting source to the counter. + * + * @param counterHandle the counter handle */ void HAL_ClearCounterUpSource(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the source object that causes the counter to count down. - * Set the down counting DigitalSource. + * Sets the source object that causes the counter to count down. + * + * @param counterHandle the counter handle + * @param digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle of a HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog + * trigger */ void HAL_SetCounterDownSource(HAL_CounterHandle counterHandle, HAL_Handle digitalSourceHandle, @@ -60,139 +101,194 @@ void HAL_SetCounterDownSource(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the edge sensitivity on a down counting source. - * Set the down source to either detect rising edges or falling edges. + * Sets the down source to either detect rising edges or falling edges. + * Note that both are allowed to be set true at the same time without issues. + * + * @param counterHandle the counter handle + * @param risingEdge true to trigger on rising + * @param fallingEdge true to trigger on falling */ void HAL_SetCounterDownSourceEdge(HAL_CounterHandle counterHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, int32_t* status); /** - * Disable the down counting source to the counter. + * Disables the down counting source to the counter. + * + * @param counterHandle the counter handle */ void HAL_ClearCounterDownSource(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set standard up / down counting mode on this counter. + * Sets standard up / down counting mode on this counter. + * * Up and down counts are sourced independently from two inputs. + * + * @param counterHandle the counter handle */ void HAL_SetCounterUpDownMode(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set standard up / down counting mode on this counter. - * Up and down counts are sourced independently from two inputs. + * Sets directional counting mode on this counter. + * + * The direction is determined by the B input, with counting happening with the + * A input. + * + * @param counterHandle the counter handle */ void HAL_SetCounterExternalDirectionMode(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set Semi-period mode on this counter. - * Counts up on both rising and falling edges. + * Sets Semi-period mode on this counter. + * + * The counter counts up based on the time the input is triggered. High or Low + * depends on the highSemiPeriod parameter. + * + * @param counterHandle the counter handle + * @param highSemiPeriod true for counting when the input is high, false for low */ void HAL_SetCounterSemiPeriodMode(HAL_CounterHandle counterHandle, HAL_Bool highSemiPeriod, int32_t* status); /** - * Configure the counter to count in up or down based on the length of the input - * pulse. + * Configures the counter to count in up or down based on the length of the + * input pulse. + * * This mode is most useful for direction sensitive gear tooth sensors. + * + * @param counterHandle the counter handle * @param threshold The pulse length beyond which the counter counts the - * opposite direction. Units are seconds. + * opposite direction (seconds) */ void HAL_SetCounterPulseLengthMode(HAL_CounterHandle counterHandle, double threshold, int32_t* status); /** - * Get the Samples to Average which specifies the number of samples of the timer - * to - * average when calculating the period. Perform averaging to account for - * mechanical imperfections or as oversampling to increase resolution. + * Gets the Samples to Average which specifies the number of samples of the + * timer to average when calculating the period. Perform averaging to account + * for mechanical imperfections or as oversampling to increase resolution. + * + * @param counterHandle the counter handle * @return SamplesToAverage The number of samples being averaged (from 1 to 127) */ int32_t HAL_GetCounterSamplesToAverage(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the Samples to Average which specifies the number of samples of the timer - * to average when calculating the period. Perform averaging to account for - * mechanical imperfections or as oversampling to increase resolution. - * @param samplesToAverage The number of samples to average from 1 to 127. + * Sets the Samples to Average which specifies the number of samples of the + * timer to average when calculating the period. Perform averaging to account + * for mechanical imperfections or as oversampling to increase resolution. + * + * @param counterHandle the counter handle + * @param samplesToAverage The number of samples to average from 1 to 127 */ void HAL_SetCounterSamplesToAverage(HAL_CounterHandle counterHandle, int32_t samplesToAverage, int32_t* status); /** - * Reset the Counter to zero. - * Set the counter value to zero. This doesn't effect the running state of the + * Resets the Counter to zero. + * + * Sets the counter value to zero. This does not effect the running state of the * counter, just sets the current value to zero. + * + * @param counterHandle the counter handle */ void HAL_ResetCounter(HAL_CounterHandle counterHandle, int32_t* status); /** - * Read the current counter value. - * Read the value at this instant. It may still be running, so it reflects the + * Reads the current counter value. + * + * Reads the value at this instant. It may still be running, so it reflects the * current value. Next time it is read, it might have a different value. + * + * @param counterHandle the counter handle + * @return the current counter value */ int32_t HAL_GetCounter(HAL_CounterHandle counterHandle, int32_t* status); /* - * Get the Period of the most recent count. + * Gets the Period of the most recent count. + * * Returns the time interval of the most recent count. This can be used for * velocity calculations to determine shaft speed. - * @returns The period of the last two pulses in units of seconds. + * + * @param counterHandle the counter handle + * @returns the period of the last two pulses in units of seconds */ double HAL_GetCounterPeriod(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the maximum period where the device is still considered "moving". + * Sets the maximum period where the device is still considered "moving". + * * Sets the maximum period where the device is considered moving. This value is - * used to determine the "stopped" state of the counter using the GetStopped - * method. - * @param maxPeriod The maximum period where the counted device is considered - * moving in seconds. + * used to determine the "stopped" state of the counter using the + * HAL_GetCounterStopped method. + * + * @param counterHandle the counter handle + * @param maxPeriod the maximum period where the counted device is + * considered moving in seconds */ void HAL_SetCounterMaxPeriod(HAL_CounterHandle counterHandle, double maxPeriod, int32_t* status); /** - * Select whether you want to continue updating the event timer output when - * there are no samples captured. The output of the event timer has a buffer of - * periods that are averaged and posted to a register on the FPGA. When the - * timer detects that the event source has stopped (based on the MaxPeriod) the - * buffer of samples to be averaged is emptied. If you enable the update when - * empty, you will be notified of the stopped source and the event time will - * report 0 samples. If you disable update when empty, the most recent average - * will remain on the output until a new sample is acquired. You will never see - * 0 samples output (except when there have been no events since an FPGA reset) - * and you will likely not see the stopped bit become true (since it is updated - * at the end of an average and there are no samples to average). + * Selects whether you want to continue updating the event timer output when + * there are no samples captured. + * + * The output of the event timer has a buffer of periods that are averaged and + * posted to a register on the FPGA. When the timer detects that the event + * source has stopped (based on the MaxPeriod) the buffer of samples to be + * averaged is emptied. + * + * If you enable the update when empty, you will be + * notified of the stopped source and the event time will report 0 samples. + * + * If you disable update when empty, the most recent average will remain on the + * output until a new sample is acquired. + * + * You will never see 0 samples output (except when there have been no events + * since an FPGA reset) and you will likely not see the stopped bit become true + * (since it is updated at the end of an average and there are no samples to + * average). + * + * @param counterHandle the counter handle + * @param enabled true to enable counter updating with no samples */ void HAL_SetCounterUpdateWhenEmpty(HAL_CounterHandle counterHandle, HAL_Bool enabled, int32_t* status); /** - * Determine if the clock is stopped. + * Determines if the clock is stopped. + * * Determine if the clocked input is stopped based on the MaxPeriod value set * using the SetMaxPeriod method. If the clock exceeds the MaxPeriod, then the * device (and counter) are assumed to be stopped and it returns true. - * @return Returns true if the most recent counter period exceeds the MaxPeriod - * value set by SetMaxPeriod. + * + * @param counterHandle the counter handle + * @return true if the most recent counter period exceeds the + * MaxPeriod value set by SetMaxPeriod */ HAL_Bool HAL_GetCounterStopped(HAL_CounterHandle counterHandle, int32_t* status); /** - * The last direction the counter value changed. - * @return The last direction the counter value changed. + * Gets the last direction the counter value changed. + * + * @param counterHandle the counter handle + * @return the last direction the counter value changed */ HAL_Bool HAL_GetCounterDirection(HAL_CounterHandle counterHandle, int32_t* status); /** - * Set the Counter to return reversed sensing on the direction. + * Sets the Counter to return reversed sensing on the direction. + * * This allows counters to change the direction they are counting in the case of * 1X and 2X quadrature encoding only. Any other counter mode isn't supported. + * + * @param counterHandle the counter handle * @param reverseDirection true if the value counted should be negated. */ void HAL_SetCounterReverseDirection(HAL_CounterHandle counterHandle, diff --git a/hal/src/main/native/include/HAL/DIO.h b/hal/src/main/native/include/HAL/DIO.h index de53f3c199..0756dd0fe5 100644 --- a/hal/src/main/native/include/HAL/DIO.h +++ b/hal/src/main/native/include/HAL/DIO.h @@ -16,167 +16,176 @@ extern "C" { #endif /** - * Create a new instance of a digital port. + * Creates a new instance of a digital port. + * + * @param portHandle the port handle to create from + * @param input true for input, false for output + * @return the created digital handle */ HAL_DigitalHandle HAL_InitializeDIOPort(HAL_PortHandle portHandle, HAL_Bool input, int32_t* status); +/** + * Checks if a DIO channel is valid. + * + * @param channel the channel number to check + * @return true if the channel is correct, otherwise false + */ HAL_Bool HAL_CheckDIOChannel(int32_t channel); void HAL_FreeDIOPort(HAL_DigitalHandle dioPortHandle); /** - * Allocate a DO PWM Generator. - * Allocate PWM generators so that they are not accidentally reused. + * Allocates a DO PWM Generator. * - * @return PWM Generator handle + * @return the allocated digital PWM handle */ HAL_DigitalPWMHandle HAL_AllocateDigitalPWM(int32_t* status); /** - * Free the resource associated with a DO PWM generator. + * Frees the resource associated with a DO PWM generator. * - * @param pwmGenerator The pwmGen to free that was allocated with - * allocateDigitalPWM() + * @param pwmGenerator the digital PWM handle */ void HAL_FreeDigitalPWM(HAL_DigitalPWMHandle pwmGenerator, int32_t* status); /** - * Change the frequency of the DO PWM generator. + * Changes the frequency of the DO PWM generator. * - * The valid range is from 0.6 Hz to 19 kHz. The frequency resolution is - * logarithmic. + * The valid range is from 0.6 Hz to 19 kHz. * - * @param rate The frequency to output all digital output PWM signals. + * The frequency resolution is logarithmic. + * + * @param rate the frequency to output all digital output PWM signals */ void HAL_SetDigitalPWMRate(double rate, int32_t* status); /** - * Configure the duty-cycle of the PWM generator + * Configures the duty-cycle of the PWM generator. * - * @param pwmGenerator The generator index reserved by allocateDigitalPWM() - * @param dutyCycle The percent duty cycle to output [0..1]. + * @param pwmGenerator the digital PWM handle + * @param dutyCycle the percent duty cycle to output [0..1] */ void HAL_SetDigitalPWMDutyCycle(HAL_DigitalPWMHandle pwmGenerator, double dutyCycle, int32_t* status); /** - * Configure which DO channel the PWM signal is output on + * Configures which DO channel the PWM signal is output on. * - * @param pwmGenerator The generator index reserved by allocateDigitalPWM() - * @param channel The Digital Output channel to output on + * @param pwmGenerator the digital PWM handle + * @param channel the channel to output on */ void HAL_SetDigitalPWMOutputChannel(HAL_DigitalPWMHandle pwmGenerator, int32_t channel, int32_t* status); /** - * Write a digital I/O bit to the FPGA. - * Set a single value on a digital I/O channel. + * Writes a digital value to a DIO channel. * - * @param channel The Digital I/O channel - * @param value The state to set the digital channel (if it is configured as an - * output) + * @param dioPortHandle the digital port handle + * @param value the state to set the digital channel (if it is + * configured as an output) */ void HAL_SetDIO(HAL_DigitalHandle dioPortHandle, HAL_Bool value, int32_t* status); /** - * Set direction of a DIO channel. + * Sets the direction of a DIO channel. * - * @param channel The Digital I/O channel - * @param input true to set input, false for output + * @param dioPortHandle the digital port handle + * @param input true to set input, false for output */ void HAL_SetDIODirection(HAL_DigitalHandle dioPortHandle, HAL_Bool input, int32_t* status); /** - * Read a digital I/O bit from the FPGA. - * Get a single value from a digital I/O channel. + * Reads a digital value from a DIO channel. * - * @param channel The digital I/O channel - * @return The state of the specified channel + * @param dioPortHandle the digital port handle + * @return the state of the specified channel */ HAL_Bool HAL_GetDIO(HAL_DigitalHandle dioPortHandle, int32_t* status); /** - * Read the direction of a the Digital I/O lines - * A 1 bit means output and a 0 bit means input. + * Reads the direction of a DIO channel. * - * @param channel The digital I/O channel - * @return The direction of the specified channel + * @param dioPortHandle the digital port handle + * @return true for input, false for output */ HAL_Bool HAL_GetDIODirection(HAL_DigitalHandle dioPortHandle, int32_t* status); /** - * Generate a single pulse. + * Generates a single digital pulse. + * * Write a pulse to the specified digital output channel. There can only be a * single pulse going at any time. * - * @param channel The Digital Output channel that the pulse should be output on - * @param pulseLength The active length of the pulse (in seconds) + * @param dioPortHandle the digital port handle + * @param pulseLength the active length of the pulse (in seconds) */ void HAL_Pulse(HAL_DigitalHandle dioPortHandle, double pulseLength, int32_t* status); /** - * Check a DIO line to see if it is currently generating a pulse. + * Checks a DIO line to see if it is currently generating a pulse. * - * @return A pulse is in progress + * @return true if a pulse is in progress, otherwise false */ HAL_Bool HAL_IsPulsing(HAL_DigitalHandle dioPortHandle, int32_t* status); /** - * Check if any DIO line is currently generating a pulse. + * Checks if any DIO line is currently generating a pulse. * - * @return A pulse on some line is in progress + * @return true if a pulse on some line is in progress */ HAL_Bool HAL_IsAnyPulsing(int32_t* status); /** - * Write the filter index from the FPGA. + * Writes the filter index from the FPGA. + * * Set the filter index used to filter out short pulses. * - * @param dioPortHandle Handle to the digital I/O channel - * @param filterIndex The filter index. Must be in the range 0 - 3, where 0 - * means "none" and 1 - 3 means filter # filterIndex - 1. + * @param dioPortHandle the digital port handle + * @param filterIndex the filter index (Must be in the range 0 - 3, where 0 + * means "none" and 1 - 3 means filter # filterIndex - 1) */ void HAL_SetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t filterIndex, int32_t* status); /** - * Read the filter index from the FPGA. - * Get the filter index used to filter out short pulses. + * Reads the filter index from the FPGA. * - * @param dioPortHandle Handle to the digital I/O channel - * @return filterIndex The filter index. Must be in the range 0 - 3, - * where 0 means "none" and 1 - 3 means filter # filterIndex - 1. + * Gets the filter index used to filter out short pulses. + * + * @param dioPortHandle the digital port handle + * @return filterIndex the filter index (Must be in the range 0 - 3, + * where 0 means "none" and 1 - 3 means filter # filterIndex - 1) */ int32_t HAL_GetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t* status); /** - * Set the filter period for the specified filter index. + * Sets the filter period for the specified filter index. * - * Set the filter period in FPGA cycles. Even though there are 2 different + * Sets the filter period in FPGA cycles. Even though there are 2 different * filter index domains (MXP vs HDR), ignore that distinction for now since it * compilicates the interface. That can be changed later. * - * @param filterIndex The filter index, 0 - 2. - * @param value The number of cycles that the signal must not transition to be - * counted as a transition. + * @param filterIndex the filter index, 0 - 2 + * @param value the number of cycles that the signal must not transition + * to be counted as a transition. */ void HAL_SetFilterPeriod(int32_t filterIndex, int64_t value, int32_t* status); /** - * Get the filter period for the specified filter index. + * Gets the filter period for the specified filter index. * - * Get the filter period in FPGA cycles. Even though there are 2 different + * Gets the filter period in FPGA cycles. Even though there are 2 different * filter index domains (MXP vs HDR), ignore that distinction for now since it * compilicates the interface. Set status to NiFpga_Status_SoftwareFault if the * filter values miss-match. * - * @param filterIndex The filter index, 0 - 2. - * @param value The number of cycles that the signal must not transition to be - * counted as a transition. + * @param filterIndex the filter index, 0 - 2 + * @param value the number of cycles that the signal must not transition + * to be counted as a transition. */ int64_t HAL_GetFilterPeriod(int32_t filterIndex, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/DriverStation.h b/hal/src/main/native/include/HAL/DriverStation.h index 534d68b579..3a09a0c620 100644 --- a/hal/src/main/native/include/HAL/DriverStation.h +++ b/hal/src/main/native/include/HAL/DriverStation.h @@ -98,19 +98,71 @@ struct HAL_MatchInfo { extern "C" { #endif +/** + * Sends an error to the driver station. + * + * @param isError true for error, false for warning + * @param errorCode the error code + * @param isLVCode true for a LV error code, false for a standard error code + * @param details the details of the error + * @param location the file location of the errror + * @param callstack the callstack of the error + * @param printMsg true to print the error message to stdout as well as to the + * DS + */ int32_t HAL_SendError(HAL_Bool isError, int32_t errorCode, HAL_Bool isLVCode, const char* details, const char* location, const char* callStack, HAL_Bool printMsg); +/** + * Gets the current control word of the driver station. + * + * The control work contains the robot state. + * + * @param controlWord the control word (out) + * @return the error code, or 0 for success + */ int32_t HAL_GetControlWord(HAL_ControlWord* controlWord); + +/** + * Gets the current alliance station ID. + * + * @param status the error code, or 0 for success + * @return the alliance station ID + */ HAL_AllianceStationID HAL_GetAllianceStation(int32_t* status); + +/** + * Gets the axes of a specific joystick. + * + * @param joystickNum the joystick number + * @param axes the axes values (output) + * @return the error code, or 0 for success + */ int32_t HAL_GetJoystickAxes(int32_t joystickNum, HAL_JoystickAxes* axes); + +/** + * Gets the POVs of a specific joystick. + * + * @param joystickNum the joystick number + * @param povs the POV values (output) + * @return the error code, or 0 for success + */ int32_t HAL_GetJoystickPOVs(int32_t joystickNum, HAL_JoystickPOVs* povs); + +/** + * Gets the buttons of a specific joystick. + * + * @param joystickNum the joystick number + * @param buttons the button values (output) + * @return the error code, or 0 for success + */ int32_t HAL_GetJoystickButtons(int32_t joystickNum, HAL_JoystickButtons* buttons); /** - * Retrieve the Joystick Descriptor for particular slot + * Retrieves the Joystick Descriptor for particular slot. + * * @param desc [out] descriptor (data transfer object) to fill in. desc is * filled in regardless of success. In other words, if descriptor is not * available, desc is filled in with default values matching the init-values in @@ -123,16 +175,101 @@ int32_t HAL_GetJoystickButtons(int32_t joystickNum, int32_t HAL_GetJoystickDescriptor(int32_t joystickNum, HAL_JoystickDescriptor* desc); +/** + * Gets is a specific joystick is considered to be an XBox controller. + * + * @param joystickNum the joystick number + * @return true if xbox, false otherwise + */ HAL_Bool HAL_GetJoystickIsXbox(int32_t joystickNum); + +/** + * Gets the type of joystick connected. + * + * This is device specific, and different depending on what system input type + * the joystick uses. + * + * @param joystickNum the joystick number + * @return the enumerated joystick type + */ int32_t HAL_GetJoystickType(int32_t joystickNum); + +/** + * Gets the name of a joystick. + * + * The returned array must be freed with HAL_FreeJoystickName. + * + * Will be null terminated. + * + * @param joystickNum the joystick number + * @return the joystick name + */ char* HAL_GetJoystickName(int32_t joystickNum); + +/** + * Frees a joystick name received with HAL_GetJoystickName + * + * @param name the name storage + */ void HAL_FreeJoystickName(char* name); + +/** + * Gets the type of a specific joystick axis. + * + * This is device specific, and different depending on what system input type + * the joystick uses. + * + * @param joystickNum the joystick number + * @param axis the axis number + * @return the enumerated axis type + */ int32_t HAL_GetJoystickAxisType(int32_t joystickNum, int32_t axis); + +/** + * Set joystick outputs. + * + * @param joystickNum the joystick numer + * @param outputs bitmask of outputs, 1 for on 0 for off + * @param leftRumble the left rumble value (0-FFFF) + * @param rightRumble the right rumble value (0-FFFF) + * @return the error code, or 0 for success + */ int32_t HAL_SetJoystickOutputs(int32_t joystickNum, int64_t outputs, int32_t leftRumble, int32_t rightRumble); + +/** + * Returns the approximate match time. + * + * The FMS does not send an official match time to the robots, but does send + * an approximate match time. The value will count down the time remaining in + * the current period (auto or teleop). + * + * Warning: This is not an official time (so it cannot be used to dispute ref + * calls or guarantee that a function will trigger before the match ends). + * + * The Practice Match function of the DS approximates the behaviour seen on + * the field. + * + * @param status the error code, or 0 for success + * @return time remaining in current match period (auto or teleop) + */ double HAL_GetMatchTime(int32_t* status); -int HAL_GetMatchInfo(HAL_MatchInfo* info); +/** + * Gets info about a specific match. + * + * Note that the match info must be freed with HAL_FreeMatchInfo + * + * @param info the match info (output) + * @return the error code, or 0 for success + */ +int32_t HAL_GetMatchInfo(HAL_MatchInfo* info); + +/** + * Frees a match info structure allocated with HAL_GetMatchInfo. + * + * @param info the match info + */ void HAL_FreeMatchInfo(HAL_MatchInfo* info); #ifndef HAL_USE_LABVIEW @@ -143,6 +280,12 @@ void HAL_FreeMatchInfo(HAL_MatchInfo* info); */ void HAL_ReleaseDSMutex(void); +/** + * Has a new control packet from the driver station arrived since the last + * time this function was called? + * + * @return true if the control data has been updated since the last call + */ bool HAL_IsNewControlData(void); /** @@ -153,21 +296,61 @@ void HAL_WaitForDSData(void); /** * Waits for the newest DS packet to arrive. If timeout is <= 0, this will wait * forever. Otherwise, it will wait until either a new packet, or the timeout - * time has passed. Returns true on new data, false on timeout. + * time has passed. + * + * @param timeout timeout in seconds + * @return true for new data, false for timeout */ HAL_Bool HAL_WaitForDSDataTimeout(double timeout); /** - * Call this to initialize the driver station communication. This will properly + * Initializes the driver station communication. This will properly * handle multiple calls. However note that this CANNOT be called from a library * that interfaces with LabVIEW. */ void HAL_InitializeDriverStation(void); +/** + * Sets the program starting flag in the DS. + * + * This is what changes the DS to showing robot code ready. + */ void HAL_ObserveUserProgramStarting(void); + +/** + * Sets the disabled flag in the DS. + * + * This is used for the DS to ensure the robot is properly responding to its + * state request. Ensure this get called about every 50ms, or the robot will be + * disabled by the DS. + */ void HAL_ObserveUserProgramDisabled(void); + +/** + * Sets the autonomous enabled flag in the DS. + * + * This is used for the DS to ensure the robot is properly responding to its + * state request. Ensure this get called about every 50ms, or the robot will be + * disabled by the DS. + */ void HAL_ObserveUserProgramAutonomous(void); + +/** + * Sets the teleoperated enabled flag in the DS. + * + * This is used for the DS to ensure the robot is properly responding to its + * state request. Ensure this get called about every 50ms, or the robot will be + * disabled by the DS. + */ void HAL_ObserveUserProgramTeleop(void); + +/** + * Sets the test mode flag in the DS. + * + * This is used for the DS to ensure the robot is properly responding to its + * state request. Ensure this get called about every 50ms, or the robot will be + * disabled by the DS. + */ void HAL_ObserveUserProgramTest(void); #endif // HAL_USE_LABVIEW diff --git a/hal/src/main/native/include/HAL/Encoder.h b/hal/src/main/native/include/HAL/Encoder.h index d26e16016b..d9fc1412d8 100644 --- a/hal/src/main/native/include/HAL/Encoder.h +++ b/hal/src/main/native/include/HAL/Encoder.h @@ -12,12 +12,19 @@ #include "HAL/AnalogTrigger.h" #include "HAL/Types.h" +/** + * The type of index pulse for the encoder. + */ enum HAL_EncoderIndexingType : int32_t { HAL_kResetWhileHigh, HAL_kResetWhileLow, HAL_kResetOnFallingEdge, HAL_kResetOnRisingEdge }; + +/** + * The encoding scaling of the encoder. + */ enum HAL_EncoderEncodingType : int32_t { HAL_Encoder_k1X, HAL_Encoder_k2X, @@ -27,51 +34,257 @@ enum HAL_EncoderEncodingType : int32_t { #ifdef __cplusplus extern "C" { #endif + +/** + * Initializes an encoder. + * + * @param digitalSourceHandleA the A source (either a HAL_DigitalHandle or a + * HAL_AnalogTriggerHandle) + * @param analogTriggerTypeA the analog trigger type of the A source if it is + * an analog trigger + * @param digitalSourceHandleB the B source (either a HAL_DigitalHandle or a + * HAL_AnalogTriggerHandle) + * @param analogTriggerTypeB the analog trigger type of the B source if it is + * an analog trigger + * @param reverseDirection true to reverse the counting direction from + * standard, otherwise false + * @param encodingType the encoding type + @return the created encoder handle + */ HAL_EncoderHandle HAL_InitializeEncoder( HAL_Handle digitalSourceHandleA, HAL_AnalogTriggerType analogTriggerTypeA, HAL_Handle digitalSourceHandleB, HAL_AnalogTriggerType analogTriggerTypeB, HAL_Bool reverseDirection, HAL_EncoderEncodingType encodingType, int32_t* status); + +/** + * Frees an encoder. + * + * @param encoderHandle the encoder handle + */ void HAL_FreeEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the current counts of the encoder after encoding type scaling. + * + * This is scaled by the value passed duing initialization to encodingType. + * + * @param encoderHandle the encoder handle + * @return the current scaled count + */ int32_t HAL_GetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the raw counts of the encoder. + * + * This is not scaled by any values. + * + * @param encoderHandle the encoder handle + * @return the raw encoder count + */ int32_t HAL_GetEncoderRaw(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the encoder scale value. + * + * This is set by the value passed during initialization to encodingType. + * + * @param encoderHandle the encoder handle + * @return the encoder scale value + */ int32_t HAL_GetEncoderEncodingScale(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Reads the current encoder value. + * + * Read the value at this instant. It may still be running, so it reflects the + * current value. Next time it is read, it might have a different value. + * + * @param encoderHandle the encoder handle + * @return the current encoder value + */ void HAL_ResetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); + +/* + * Gets the Period of the most recent count. + * + * Returns the time interval of the most recent count. This can be used for + * velocity calculations to determine shaft speed. + * + * @param encoderHandle the encoder handle + * @returns the period of the last two pulses in units of seconds + */ double HAL_GetEncoderPeriod(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Sets the maximum period where the device is still considered "moving". + * + * Sets the maximum period where the device is considered moving. This value is + * used to determine the "stopped" state of the encoder using the + * HAL_GetEncoderStopped method. + * + * @param encoderHandle the encoder handle + * @param maxPeriod the maximum period where the counted device is + * considered moving in seconds + */ void HAL_SetEncoderMaxPeriod(HAL_EncoderHandle encoderHandle, double maxPeriod, int32_t* status); + +/** + * Determines if the clock is stopped. + * + * Determines if the clocked input is stopped based on the MaxPeriod value set + * using the SetMaxPeriod method. If the clock exceeds the MaxPeriod, then the + * device (and encoder) are assumed to be stopped and it returns true. + * + * @param encoderHandle the encoder handle + * @return true if the most recent encoder period exceeds the + * MaxPeriod value set by SetMaxPeriod + */ HAL_Bool HAL_GetEncoderStopped(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the last direction the encoder value changed. + * + * @param encoderHandle the encoder handle + * @return the last direction the encoder value changed + */ HAL_Bool HAL_GetEncoderDirection(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the current distance traveled by the encoder. + * + * This is the encoder count scaled by the distance per pulse set for the + * encoder. + * + * @param encoderHandle the encoder handle + * @return the encoder distance (units are determined by the units + * passed to HAL_SetEncoderDistancePerPulse) + */ double HAL_GetEncoderDistance(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Gets the current rate of the encoder. + * + * This is the encoder period scaled by the distance per pulse set for the + * encoder. + * + * @param encoderHandle the encoder handle + * @return the encoder rate (units are determined by the units + * passed to HAL_SetEncoderDistancePerPulse, time value is seconds) + */ double HAL_GetEncoderRate(HAL_EncoderHandle encoderHandle, int32_t* status); + +/** + * Sets the minimum rate to be considered moving by the encoder. + * + * Units need to match what is set by HAL_SetEncoderDistancePerPulse, with time + * as seconds. + * + * @param encoderHandle the encoder handle + * @param minRate the minimum rate to be considered moving (units are + * determined by the units passed to HAL_SetEncoderDistancePerPulse, time value + * is seconds) + */ void HAL_SetEncoderMinRate(HAL_EncoderHandle encoderHandle, double minRate, int32_t* status); + +/** + * Sets the distance traveled per encoder pulse. This is used as a scaling + * factor for the rate and distance calls. + * + * @param encoderHandle the encoder handle + * @param distancePerPulse the distance traveled per encoder pulse (units user + * defined) + */ void HAL_SetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, double distancePerPulse, int32_t* status); + +/** + * Sets if to reverse the direction of the encoder. + * + * Note that this is not a toggle. It is an absolute set. + * + * @param encoderHandle the encoder handle + * @param reverseDirection true to reverse the direction, false to not. + */ void HAL_SetEncoderReverseDirection(HAL_EncoderHandle encoderHandle, HAL_Bool reverseDirection, int32_t* status); + +/** + * Sets the number of encoder samples to average when calculating encoder rate. + * + * @param encoderHandle the encoder handle + * @param samplesToAverage the number of samples to average + */ void HAL_SetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, int32_t samplesToAverage, int32_t* status); + +/** + * Gets the current samples to average value. + * + * @param encoderHandle the encoder handle + * @return the current samples to average value + */ int32_t HAL_GetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, int32_t* status); +/** + * Sets the source for an index pulse on the encoder. + * + * The index pulse can be used to cause an encoder to reset based on an external + * input. + * + * @param encoderHandle the encoder handle + * @param digitalSourceHandle the index source handle (either a + * HAL_AnalogTriggerHandle of a HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog + * trigger + * @param type the index triggering type + */ void HAL_SetEncoderIndexSource(HAL_EncoderHandle encoderHandle, HAL_Handle digitalSourceHandle, HAL_AnalogTriggerType analogTriggerType, HAL_EncoderIndexingType type, int32_t* status); +/** + * Gets the FPGA index of the encoder. + * + * @param encoderHandle the encoder handle + * @return the FPGA index of the encoder + */ int32_t HAL_GetEncoderFPGAIndex(HAL_EncoderHandle encoderHandle, int32_t* status); +/** + * Gets the decoding scale factor of the encoder. + * + * This is used to perform the scaling from raw to type scaled values. + * + * @param encoderHandle the encoder handle + * @return the scale value for the encoder + */ double HAL_GetEncoderDecodingScaleFactor(HAL_EncoderHandle encoderHandle, int32_t* status); +/** + * Gets the user set distance per pulse of the encoder. + * + * @param encoderHandle the encoder handle + * @return the set distance per pulse + */ double HAL_GetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, int32_t* status); +/** + * Gets the encoding type of the encoder. + * + * @param encoderHandle the encoder handle + * @return the encoding type + */ HAL_EncoderEncodingType HAL_GetEncoderEncodingType( HAL_EncoderHandle encoderHandle, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/Extensions.h b/hal/src/main/native/include/HAL/Extensions.h index f3b9d1687a..df45dce178 100644 --- a/hal/src/main/native/include/HAL/Extensions.h +++ b/hal/src/main/native/include/HAL/Extensions.h @@ -20,11 +20,21 @@ typedef int halsim_extension_init_func_t(void); extern "C" { +/** + * Loads a single extension from a direct path. + * + * Expected to be called internally, not by users. + * + * @param library the library path + * @return the succes state of the initialization + */ int HAL_LoadOneExtension(const char* library); /** - * Load any extra halsim libraries provided in the HALSIM_EXTENSIONS + * Loads any extra halsim libraries provided in the HALSIM_EXTENSIONS * environment variable. + * + * @return the succes state of the initialization */ int HAL_LoadExtensions(void); } // extern "C" diff --git a/hal/src/main/native/include/HAL/HAL.h b/hal/src/main/native/include/HAL/HAL.h index f2e2f438d7..4de10c7cc8 100644 --- a/hal/src/main/native/include/HAL/HAL.h +++ b/hal/src/main/native/include/HAL/HAL.h @@ -49,21 +49,31 @@ enum HAL_RuntimeType : int32_t { HAL_Athena, HAL_Mock }; extern "C" { #endif +/** + * Gets the error message for a specific status code. + * + * @param code the status code + * @return the error message for the code. This does not need to be freed. + */ const char* HAL_GetErrorMessage(int32_t code); /** - * Return the FPGA Version number. + * Returns the FPGA Version number. + * * For now, expect this to be competition year. + * * @return FPGA Version number. */ int32_t HAL_GetFPGAVersion(int32_t* status); /** - * Return the FPGA Revision number. + * Returns the FPGA Revision number. + * * The format of the revision is 3 numbers. * The 12 most significant bits are the Major Revision. * the next 8 bits are the Minor Revision. * The 12 least significant bits are the Build Number. + * * @return FPGA Revision number. */ int64_t HAL_GetFPGARevision(int32_t* status); @@ -71,27 +81,64 @@ int64_t HAL_GetFPGARevision(int32_t* status); HAL_RuntimeType HAL_GetRuntimeType(void); /** - * Get the state of the "USER" button on the roboRIO + * Gets the state of the "USER" button on the roboRIO. + * * @return true if the button is currently pressed down */ HAL_Bool HAL_GetFPGAButton(int32_t* status); +/** + * Gets if the system outputs are currently active + * + * @return true if the system outputs are active, false if disabled + */ HAL_Bool HAL_GetSystemActive(int32_t* status); + +/** + * Gets if the system is in a browned out state. + * + * @return true if the system is in a low voltage brown out, false otherwise + */ HAL_Bool HAL_GetBrownedOut(int32_t* status); +/** + * The base HAL initialize function. Useful if you need to ensure the DS and + * base HAL functions (the ones above this declaration in HAL.h) are properly + * initialized. For normal programs and executables, please use HAL_Initialize. + * + * This is mainly expected to be use from libraries that are expected to be used + * from LabVIEW, as it handles its own initialization for objects. + */ void HAL_BaseInitialize(int32_t* status); #ifndef HAL_USE_LABVIEW +/** + * Gets a port handle for a specific channel. + * + * The created handle does not need to be freed. + * + * @param channel the channel number + * @return the created port + */ HAL_PortHandle HAL_GetPort(int32_t channel); /** - * @deprecated Uses module numbers + * Gets a port handle for a specific channel and module. + * + * This is expected to be used for PCMs, as the roboRIO does not work with + * modules anymore. + * + * The created handle does not need to be freed. + * + * @param module the module number + * @param channel the channel number + * @return the created port */ HAL_PortHandle HAL_GetPortWithModule(int32_t module, int32_t channel); /** - * Read the microsecond-resolution timer on the FPGA. + * Reads the microsecond-resolution timer on the FPGA. * * @return The current time in microseconds according to the FPGA (since FPGA * reset). @@ -100,14 +147,54 @@ uint64_t HAL_GetFPGATime(int32_t* status); /** * Call this to start up HAL. This is required for robot programs. + * + * This must be called before any other HAL functions. Failure to do so will + * result in undefined behavior, and likely segmentation faults. This means that + * any statically initialized variables in a program MUST call this function in + * their constructors if they want to use other HAL calls. + * + * The common parameters are 500 for timeout and 0 for mode. + * + * This function is safe to call from any thread, and as many times as you wish. + * It internally guards from any reentrancy. + * + * The applicable modes are: + * 0: Try to kill an existing HAL from another program, if not successful, + * error. + * 1: Force kill a HAL from another program. + * 2: Just warn if another hal exists and cannot be killed. Will likely result + * in undefined behavior. + * + * @param timeout the initialization timeout (ms) + * @param mode the initialization mode (see remarks) + * @return true if initialization was successful, otherwise false. */ HAL_Bool HAL_Initialize(int32_t timeout, int32_t mode); // ifdef's definition is to allow for default parameters in C++. #ifdef __cplusplus +/** + * Reports a hardware usage to the HAL. + * + * @param resource the used resource + * @param instanceNumber the instance of the resource + * @param context a user specified context index + * @param feature a user specified feature string + * @return the index of the added value in NetComm + */ int64_t HAL_Report(int32_t resource, int32_t instanceNumber, int32_t context = 0, const char* feature = nullptr); #else + +/** + * Reports a hardware usage to the HAL. + * + * @param resource the used resource + * @param instanceNumber the instance of the resource + * @param context a user specified context index + * @param feature a user specified feature string + * @return the index of the added value in NetComm + */ int64_t HAL_Report(int32_t resource, int32_t instanceNumber, int32_t context, const char* feature); #endif diff --git a/hal/src/main/native/include/HAL/I2C.h b/hal/src/main/native/include/HAL/I2C.h index e3750c2519..90941efeff 100644 --- a/hal/src/main/native/include/HAL/I2C.h +++ b/hal/src/main/native/include/HAL/I2C.h @@ -16,18 +16,22 @@ extern "C" { #endif /** - * Initialize the I2C port. Opens the port if necessary and saves the handle. - * If opening the MXP port, also sets up the channel functions appropriately + * Initializes the I2C port. + * + * Opens the port if necessary and saves the handle. + * If opening the MXP port, also sets up the channel functions appropriately. + * * @param port The port to open, 0 for the on-board, 1 for the MXP. */ void HAL_InitializeI2C(HAL_I2CPort port, int32_t* status); /** - * Generic transaction. + * Generic I2C read/write transaction. * * This is a lower-level interface to the I2C hardware giving you more control * over each transaction. * + * @param port The I2C port, 0 for the on-board, 1 for the MXP. * @param dataToSend Buffer of data to send as part of the transaction. * @param sendSize Number of bytes to send as part of the transaction. * @param dataReceived Buffer to read data into. @@ -39,11 +43,12 @@ int32_t HAL_TransactionI2C(HAL_I2CPort port, int32_t deviceAddress, uint8_t* dataReceived, int32_t receiveSize); /** - * Execute a write transaction with the device. + * Executes a write transaction with the device. * - * Write a single byte to a register on a device and wait until the + * Writes a single byte to a register on a device and wait until the * transaction is complete. * + * @param port The I2C port, 0 for the on-board, 1 for the MXP. * @param registerAddress The address of the register on the device to be * written. * @param data The byte to write to the register on the device. @@ -53,12 +58,13 @@ int32_t HAL_WriteI2C(HAL_I2CPort port, int32_t deviceAddress, const uint8_t* dataToSend, int32_t sendSize); /** - * Execute a read transaction with the device. + * Executes a read transaction with the device. * - * Read bytes from a device. + * Reads bytes from a device. * Most I2C devices will auto-increment the register pointer internally allowing * you to read consecutive registers on a device in a single transaction. * + * @param port The I2C port, 0 for the on-board, 1 for the MXP. * @param registerAddress The register to read first in the transaction. * @param count The number of bytes to read in the transaction. * @param buffer A pointer to the array of bytes to store the data read from the @@ -68,6 +74,11 @@ int32_t HAL_WriteI2C(HAL_I2CPort port, int32_t deviceAddress, int32_t HAL_ReadI2C(HAL_I2CPort port, int32_t deviceAddress, uint8_t* buffer, int32_t count); +/** + * Closes an I2C port + * + * @param port The I2C port, 0 for the on-board, 1 for the MXP. + */ void HAL_CloseI2C(HAL_I2CPort port); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/Interrupts.h b/hal/src/main/native/include/HAL/Interrupts.h index 850b279ac2..a98095a276 100644 --- a/hal/src/main/native/include/HAL/Interrupts.h +++ b/hal/src/main/native/include/HAL/Interrupts.h @@ -19,60 +19,127 @@ extern "C" { typedef void (*HAL_InterruptHandlerFunction)(uint32_t interruptAssertedMask, void* param); +/** + * Initializes an interrupt. + * + * @param watcher true for synchronous interrupts, false for asynchronous + * @return the created interrupt handle + */ HAL_InterruptHandle HAL_InitializeInterrupts(HAL_Bool watcher, int32_t* status); + +/** + * Frees an interrupt. + * + * @param interruptHandle the interrupt handle + * @return the param passed to the interrupt, or nullptr if one + * wasn't passed. + */ void* HAL_CleanInterrupts(HAL_InterruptHandle interruptHandle, int32_t* status); /** - * In synchronous mode, wait for the defined interrupt to occur. - * @param timeout Timeout in seconds - * @param ignorePrevious If true, ignore interrupts that happened before - * waitForInterrupt was called. - * @return The mask of interrupts that fired. + * In synchronous mode, waits for the defined interrupt to occur. + * + * @param interruptHandle the interrupt handle + * @param timeout timeout in seconds + * @param ignorePrevious if true, ignore interrupts that happened before + * waitForInterrupt was called + * @return the mask of interrupts that fired */ int64_t HAL_WaitForInterrupt(HAL_InterruptHandle interruptHandle, double timeout, HAL_Bool ignorePrevious, int32_t* status); /** - * Enable interrupts to occur on this input. + * Enables interrupts to occur on this input. + * * Interrupts are disabled when the RequestInterrupt call is made. This gives * time to do the setup of the other options before starting to field * interrupts. + * + * @param interruptHandle the interrupt handle */ void HAL_EnableInterrupts(HAL_InterruptHandle interruptHandle, int32_t* status); /** - * Disable Interrupts without without deallocating structures. + * Disables interrupts without without deallocating structures. + * + * @param interruptHandle the interrupt handle */ void HAL_DisableInterrupts(HAL_InterruptHandle interruptHandle, int32_t* status); /** - * Return the timestamp for the rising interrupt that occurred most recently. - * This is in the same time domain as GetClock(). - * @return Timestamp in seconds since boot. + * Returns the timestamp for the rising interrupt that occurred most recently. + * + * This is in the same time domain as HAL_GetFPGATime(). + * + * @param interruptHandle the interrupt handle + * @return timestamp in seconds since FPGA Initialization */ double HAL_ReadInterruptRisingTimestamp(HAL_InterruptHandle interruptHandle, int32_t* status); /** - * Return the timestamp for the falling interrupt that occurred most recently. - * This is in the same time domain as GetClock(). - * @return Timestamp in seconds since boot. + * Returns the timestamp for the falling interrupt that occurred most recently. + * + * This is in the same time domain as HAL_GetFPGATime(). + * + * @param interruptHandle the interrupt handle + * @return timestamp in seconds since FPGA Initialization */ double HAL_ReadInterruptFallingTimestamp(HAL_InterruptHandle interruptHandle, int32_t* status); +/** + * Requests interrupts on a specific digital source. + * + * @param interruptHandle the interrupt handle + * @param digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle of a HAL_DigitalHandle) + * @param analogTriggerType the trigger type if the source is an AnalogTrigger + */ void HAL_RequestInterrupts(HAL_InterruptHandle interruptHandle, HAL_Handle digitalSourceHandle, HAL_AnalogTriggerType analogTriggerType, int32_t* status); + +/** + * Attaches an asynchronous interrupt handler to the interrupt. + * + * This interrupt gets called directly on the FPGA interrupt thread, so will + * block other interrupts while running. + * + * @param interruptHandle the interrupt handle + * @param handler the handler function for the interrupt to call + * @param param a parameter to be passed to the handler + */ void HAL_AttachInterruptHandler(HAL_InterruptHandle interruptHandle, HAL_InterruptHandlerFunction handler, void* param, int32_t* status); + +/** + * Attaches an asynchronous interrupt handler to the interrupt. + * + * This interrupt gets called on a thread specific to the interrupt, so will not + * block other interrupts. + * + * @param interruptHandle the interrupt handle + * @param handler the handler function for the interrupt to call + * @param param a parameter to be passed to the handler + */ void HAL_AttachInterruptHandlerThreaded(HAL_InterruptHandle interruptHandle, HAL_InterruptHandlerFunction handler, void* param, int32_t* status); + +/** + * Sets the edges to trigger the interrupt on. + * + * Note that both edges triggered is a valid configuration. + * + * @param interruptHandle the interrupt handle + * @param risingEdge true for triggering on rising edge + * @param fallingEdge true for triggering on falling edge + */ void HAL_SetInterruptUpSourceEdge(HAL_InterruptHandle interruptHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, int32_t* status); diff --git a/hal/src/main/native/include/HAL/Notifier.h b/hal/src/main/native/include/HAL/Notifier.h index bd8544bcdc..33a61654b8 100644 --- a/hal/src/main/native/include/HAL/Notifier.h +++ b/hal/src/main/native/include/HAL/Notifier.h @@ -15,13 +15,64 @@ extern "C" { #endif +/** + * Initializes a notifier. + * + * A notifier is an FPGA controller timer that triggers at requested intervals + * based on the FPGA time. This can be used to make precise control loops. + * + * @return the created notifier + */ HAL_NotifierHandle HAL_InitializeNotifier(int32_t* status); + +/** + * Stops a notifier from running. + * + * This will cause any call into HAL_WaitForNotifierAlarm to return. + * + * @param notifierHandle the notifier handle + */ void HAL_StopNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); + +/** + * Cleans a notifier. + * + * Note this also stops a notifier if it is already running. + * + * @param notifierHandle the notifier handle + */ void HAL_CleanNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); + +/** + * Updates the trigger time for a notifier. + * + * Note that this time is an absolute time relative to HAL_GetFPGATime() + * + * @param notifierHandle the notifier handle + * @param triggerTime the updated trigger time + */ void HAL_UpdateNotifierAlarm(HAL_NotifierHandle notifierHandle, uint64_t triggerTime, int32_t* status); + +/** + * Cancels the next notifier alarm. + * + * This does not cause HAL_WaitForNotifierAlarm to return. + * + * @param notifierHandle the notifier handle + */ void HAL_CancelNotifierAlarm(HAL_NotifierHandle notifierHandle, int32_t* status); + +/** + * Waits for the next alarm for the specific notifier. + * + * This is a blocking call until either the time elapses or HAL_StopNotifier + * gets called. + * + * @param notifierHandle the notifier handle + * @return the FPGA time the notifier returned + */ uint64_t HAL_WaitForNotifierAlarm(HAL_NotifierHandle notifierHandle, int32_t* status); diff --git a/hal/src/main/native/include/HAL/PDP.h b/hal/src/main/native/include/HAL/PDP.h index 6e609b9769..8a90cf737f 100644 --- a/hal/src/main/native/include/HAL/PDP.h +++ b/hal/src/main/native/include/HAL/PDP.h @@ -15,18 +15,99 @@ extern "C" { #endif +/** + * Initializes a Power Distribution Panel. + * + * @param module the module number to initialize + * @return the created PDP + */ HAL_PDPHandle HAL_InitializePDP(int32_t module, int32_t* status); + +/** + * Cleans a PDP module. + * + * @param handle the module handle + */ void HAL_CleanPDP(HAL_PDPHandle handle); + +/** + * Checks if a PDP channel is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + */ HAL_Bool HAL_CheckPDPChannel(int32_t channel); + +/** + * Checks if a PDP module is valid. + * + * @param channel the module to check + * @return true if the module is valid, otherwise false + */ HAL_Bool HAL_CheckPDPModule(int32_t module); + +/** + * Gets the temperature of the PDP. + * + * @param handle the module handle + * @return the module temperature (celsius) + */ double HAL_GetPDPTemperature(HAL_PDPHandle handle, int32_t* status); + +/** + * Gets the PDP input voltage. + * + * @param handle the module handle + * @return the input voltage (volts) + */ double HAL_GetPDPVoltage(HAL_PDPHandle handle, int32_t* status); + +/** + * Gets the current of a specific PDP channel. + * + * @param module the module + * @param channel the channel + * @return the channel current (amps) + */ double HAL_GetPDPChannelCurrent(HAL_PDPHandle handle, int32_t channel, int32_t* status); + +/** + * Gets the total current of the PDP. + * + * @param handle the module handle + * @return the total current (amps) + */ double HAL_GetPDPTotalCurrent(HAL_PDPHandle handle, int32_t* status); + +/** + * Gets the total power of the PDP. + * + * @param handle the module handle + * @return the total power (watts) + */ double HAL_GetPDPTotalPower(HAL_PDPHandle handle, int32_t* status); + +/** + * Gets the total energy of the PDP. + * + * @param handle the module handle + * @return the total energy (joules) + */ double HAL_GetPDPTotalEnergy(HAL_PDPHandle handle, int32_t* status); + +/** + * Resets the PDP accumulated energy. + * + * @param handle the module handle + */ void HAL_ResetPDPTotalEnergy(HAL_PDPHandle handle, int32_t* status); + +/** + * Clears any PDP sticky faults. + * + * @param handle the module handle + */ void HAL_ClearPDPStickyFaults(HAL_PDPHandle handle, int32_t* status); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/PWM.h b/hal/src/main/native/include/HAL/PWM.h index 70361584bc..90f26571c8 100644 --- a/hal/src/main/native/include/HAL/PWM.h +++ b/hal/src/main/native/include/HAL/PWM.h @@ -15,111 +15,210 @@ extern "C" { #endif +/** + * Initializes a PWM port. + * + * @param portHandle the port to initialize + * @return the created pwm handle + */ HAL_DigitalHandle HAL_InitializePWMPort(HAL_PortHandle portHandle, int32_t* status); + +/** + * Frees a PWM port. + * + * @param pwmPortHandle the pwm handle + */ void HAL_FreePWMPort(HAL_DigitalHandle pwmPortHandle, int32_t* status); +/** + * Checks if a pwm channel is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + */ HAL_Bool HAL_CheckPWMChannel(int32_t channel); +/** + * Sets the configuration settings for the PWM channel. + * + * All values are in milliseconds. + * + * @param pwmPortHandle the PWM handle + * @param maxPwm the maximum PWM value + * @param deadbandMaxPwm the high range of the center deadband + * @param centerPwm the center PWM value + * @param deadbandMinPwm the low range of the center deadband + * @param minPwm the minimum PWM value + */ void HAL_SetPWMConfig(HAL_DigitalHandle pwmPortHandle, double maxPwm, double deadbandMaxPwm, double centerPwm, double deadbandMinPwm, double minPwm, int32_t* status); + +/** + * Sets the raw configuration settings for the PWM channel. + * + * We recommend using HAL_SetPWMConfig() instead, as those values are properly + * scaled. Usually used for values grabbed by HAL_GetPWMConfigRaw(). + * + * Values are in raw FPGA units. + * + * @param pwmPortHandle the PWM handle + * @param maxPwm the maximum PWM value + * @param deadbandMaxPwm the high range of the center deadband + * @param centerPwm the center PWM value + * @param deadbandMinPwm the low range of the center deadband + * @param minPwm the minimum PWM value + */ void HAL_SetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t maxPwm, int32_t deadbandMaxPwm, int32_t centerPwm, int32_t deadbandMinPwm, int32_t minPwm, int32_t* status); + +/** + * Gets the raw pwm configuration settings for the PWM channel. + * + * Values are in raw FPGA units. These units have the potential to change for + * any FPGA release. + * + * @param pwmPortHandle the PWM handle + * @param maxPwm the maximum PWM value + * @param deadbandMaxPwm the high range of the center deadband + * @param centerPwm the center PWM value + * @param deadbandMinPwm the low range of the center deadband + * @param minPwm the minimum PWM value + */ void HAL_GetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t* maxPwm, int32_t* deadbandMaxPwm, int32_t* centerPwm, int32_t* deadbandMinPwm, int32_t* minPwm, int32_t* status); + +/** + * Sets if the FPGA should output the center value if the input value is within + * the deadband. + * + * @param pwmPortHandle the PWM handle + * @param eliminateDeadband true to eliminate deadband, otherwise false + */ void HAL_SetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, HAL_Bool eliminateDeadband, int32_t* status); + +/** + * Gets the current eliminate deadband value. + * + * @param pwmPortHandle the PWM handle + * @return true if set, otherwise false + */ HAL_Bool HAL_GetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** - * Set a PWM channel to the desired value. The values range from 0 to 255 and - * the period is controlled - * by the PWM Period and MinHigh registers. + * Sets a PWM channel to the desired value. * - * @param channel The PWM channel to set. - * @param value The PWM value to set. + * The values are in raw FPGA units, and have the potential to change with any + * FPGA release. + * + * @param pwmPortHandle the PWM handle + * @param value the PWM value to set */ void HAL_SetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t value, int32_t* status); /** - * Set a PWM channel to the desired scaled value. The values range from -1 to 1 - * and - * the period is controlled - * by the PWM Period and MinHigh registers. + * Sets a PWM channel to the desired scaled value. * - * @param channel The PWM channel to set. - * @param value The scaled PWM value to set. + * The values range from -1 to 1 and the period is controlled by the PWM Period + * and MinHigh registers. + * + * @param pwmPortHandle the PWM handle + * @param value the scaled PWM value to set */ void HAL_SetPWMSpeed(HAL_DigitalHandle pwmPortHandle, double speed, int32_t* status); /** - * Set a PWM channel to the desired position value. The values range from 0 to 1 - * and - * the period is controlled - * by the PWM Period and MinHigh registers. + * Sets a PWM channel to the desired position value. * - * @param channel The PWM channel to set. - * @param value The scaled PWM value to set. + * The values range from 0 to 1 and the period is controlled by the PWM Period + * and MinHigh registers. + * + * @param pwmPortHandle the PWM handle + * @param value the positional PWM value to set */ void HAL_SetPWMPosition(HAL_DigitalHandle pwmPortHandle, double position, int32_t* status); +/** + * Sets a PWM channel to be disabled. + * + * The channel is disabled until the next time it is set. Note this is different + * from just setting a 0 speed, as this will actively stop all signalling on the + * channel. + * + * @param pwmPortHandle the PWM handle. + */ void HAL_SetPWMDisabled(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** - * Get a value from a PWM channel. The values range from 0 to 255. + * Gets a value from a PWM channel. * - * @param channel The PWM channel to read from. - * @return The raw PWM value. + * The values are in raw FPGA units, and have the potential to change with any + * FPGA release. + * + * @param pwmPortHandle the PWM handle + * @return the current raw PWM value */ int32_t HAL_GetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** - * Get a scaled value from a PWM channel. The values range from -1 to 1. + * Gets a scaled value from a PWM channel. * - * @param channel The PWM channel to read from. - * @return The scaled PWM value. + * The values range from -1 to 1. + * + * @param pwmPortHandle the PWM handle + * @return the current speed PWM value */ double HAL_GetPWMSpeed(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** - * Get a position value from a PWM channel. The values range from 0 to 1. + * Gets a position value from a PWM channel. * - * @param channel The PWM channel to read from. - * @return The scaled PWM value. + * The values range from 0 to 1. + * + * @param pwmPortHandle the PWM handle + * @return the current positional PWM value */ double HAL_GetPWMPosition(HAL_DigitalHandle pwmPortHandle, int32_t* status); +/** + * Forces a PWM signal to go to 0 temporarily. + * + * @param pwmPortHandle the PWM handle. + */ void HAL_LatchPWMZero(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** - * Set how how often the PWM signal is squelched, thus scaling the period. + * Sets how how often the PWM signal is squelched, thus scaling the period. * - * @param channel The PWM channel to configure. - * @param squelchMask The 2-bit mask of outputs to squelch. + * @param pwmPortHandle the PWM handle. + * @param squelchMask the 2-bit mask of outputs to squelch */ void HAL_SetPWMPeriodScale(HAL_DigitalHandle pwmPortHandle, int32_t squelchMask, int32_t* status); /** - * Get the loop timing of the PWM system + * Gets the loop timing of the PWM system. * - * @return The loop time + * @return the loop time */ int32_t HAL_GetPWMLoopTiming(int32_t* status); /** - * Get the pwm starting cycle time + * Gets the pwm starting cycle time. * - * @return The pwm cycle start time. + * This time is relative to the FPGA time. + * + * @return the pwm cycle start time */ uint64_t HAL_GetPWMCycleStartTime(int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/Ports.h b/hal/src/main/native/include/HAL/Ports.h index 858e8dd960..a6478968ad 100644 --- a/hal/src/main/native/include/HAL/Ports.h +++ b/hal/src/main/native/include/HAL/Ports.h @@ -13,23 +13,130 @@ extern "C" { #endif +/** + * Gets the number of analog accumulators in the current system. + * + * @return the number of analog accumulators + */ int32_t HAL_GetNumAccumulators(void); + +/** + * Gets the number of analog triggers in the current system. + * + * @return the number of analog triggers + */ int32_t HAL_GetNumAnalogTriggers(void); + +/** + * Gets the number of analog inputs in the current system. + * + * @return the number of analog inputs + */ int32_t HAL_GetNumAnalogInputs(void); + +/** + * Gets the number of analog outputs in the current system. + * + * @return the number of analog outputs + */ int32_t HAL_GetNumAnalogOutputs(void); + +/** + * Gets the number of analog counters in the current system. + * + * @return the number of counters + */ int32_t HAL_GetNumCounters(void); + +/** + * Gets the number of digital headers in the current system. + * + * @return the number of digital headers + */ int32_t HAL_GetNumDigitalHeaders(void); + +/** + * Gets the number of PWM headers in the current system. + * + * @return the number of PWM headers + */ int32_t HAL_GetNumPWMHeaders(void); + +/** + * Gets the number of digital channels in the current system. + * + * @return the number of digital channels + */ int32_t HAL_GetNumDigitalChannels(void); + +/** + * Gets the number of PWM channels in the current system. + * + * @return the number of PWM channels + */ int32_t HAL_GetNumPWMChannels(void); + +/** + * Gets the number of digital IO PWM outputs in the current system. + * + * @return the number of digital IO PWM outputs + */ int32_t HAL_GetNumDigitalPWMOutputs(void); + +/** + * Gets the number of quadrature encoders in the current system. + * + * @return the number of quadrature encoders + */ int32_t HAL_GetNumEncoders(void); + +/** + * Gets the number of interrupts in the current system. + * + * @return the number of interrupts + */ int32_t HAL_GetNumInterrupts(void); + +/** + * Gets the number of relay channels in the current system. + * + * @return the number of relay channels + */ int32_t HAL_GetNumRelayChannels(void); + +/** + * Gets the number of relay headers in the current system. + * + * @return the number of relay headers + */ int32_t HAL_GetNumRelayHeaders(void); + +/** + * Gets the number of PCM modules in the current system. + * + * @return the number of PCM modules + */ int32_t HAL_GetNumPCMModules(void); + +/** + * Gets the number of solenoid channels in the current system. + * + * @return the number of solenoid channels + */ int32_t HAL_GetNumSolenoidChannels(void); + +/** + * Gets the number of PDP modules in the current system. + * + * @return the number of PDP modules + */ int32_t HAL_GetNumPDPModules(void); + +/** + * Gets the number of PDP channels in the current system. + * + * @return the number of PDP channels + */ int32_t HAL_GetNumPDPChannels(void); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/Power.h b/hal/src/main/native/include/HAL/Power.h index 280eb833a7..721b48788b 100644 --- a/hal/src/main/native/include/HAL/Power.h +++ b/hal/src/main/native/include/HAL/Power.h @@ -16,72 +16,100 @@ extern "C" { #endif /** - * Get the roboRIO input voltage + * Gets the roboRIO input voltage. + * + * @return the input voltage (volts) */ double HAL_GetVinVoltage(int32_t* status); /** - * Get the roboRIO input current + * Gets the roboRIO input current. + * + * @return the input current (amps) */ double HAL_GetVinCurrent(int32_t* status); /** - * Get the 6V rail voltage + * Gets the 6V rail voltage. + * + * @return the 6V rail voltage (volts) */ double HAL_GetUserVoltage6V(int32_t* status); /** - * Get the 6V rail current + * Gets the 6V rail current. + * + * @return the 6V rail current (amps) */ double HAL_GetUserCurrent6V(int32_t* status); /** - * Get the active state of the 6V rail + * Gets the active state of the 6V rail. + * + * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive6V(int32_t* status); /** - * Get the fault count for the 6V rail + * Gets the fault count for the 6V rail. + * + * @return the number of 6V fault counts */ int32_t HAL_GetUserCurrentFaults6V(int32_t* status); /** - * Get the 5V rail voltage + * Gets the 5V rail voltage. + * + * @return the 5V rail voltage (volts) */ double HAL_GetUserVoltage5V(int32_t* status); /** - * Get the 5V rail current + * Gets the 5V rail current. + * + * @return the 5V rail current (amps) */ double HAL_GetUserCurrent5V(int32_t* status); /** - * Get the active state of the 5V rail + * Gets the active state of the 5V rail. + * + * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive5V(int32_t* status); /** - * Get the fault count for the 5V rail + * Gets the fault count for the 5V rail. + * + * @return the number of 5V fault counts */ int32_t HAL_GetUserCurrentFaults5V(int32_t* status); /** - * Get the 3.3V rail voltage + * Gets the 3V3 rail voltage. + * + * @return the 3V3 rail voltage (volts) */ double HAL_GetUserVoltage3V3(int32_t* status); /** - * Get the 3.3V rail current + * Gets the 3V3 rail current. + * + * @return the 3V3 rail current (amps) */ double HAL_GetUserCurrent3V3(int32_t* status); /** - * Get the active state of the 3.3V rail + * Gets the active state of the 3V3 rail. + * + * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive3V3(int32_t* status); /** - * Get the fault count for the 3.3V rail + * Gets the fault count for the 3V3 rail. + * + * @return the number of 3V3 fault counts */ int32_t HAL_GetUserCurrentFaults3V3(int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/Relay.h b/hal/src/main/native/include/HAL/Relay.h index 1538b68611..655f26dacb 100644 --- a/hal/src/main/native/include/HAL/Relay.h +++ b/hal/src/main/native/include/HAL/Relay.h @@ -15,21 +15,48 @@ extern "C" { #endif +/** + * Initializes a relay. + * + * Note this call will only initialize either the forward or reverse port of the + * relay. If you need both, you will need to initialize 2 relays. + * + * @param portHandle the port handle to initialize + * @param fwd true for the forward port, false for the reverse port + * @return the created relay handle + */ HAL_RelayHandle HAL_InitializeRelayPort(HAL_PortHandle portHandle, HAL_Bool fwd, int32_t* status); + +/** + * Frees a relay port. + * + * @param relayPortHandle the relay handle + */ void HAL_FreeRelayPort(HAL_RelayHandle relayPortHandle); +/** + * Checks if a relay channel is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + */ HAL_Bool HAL_CheckRelayChannel(int32_t channel); /** - * Set the state of a relay. - * Set the state of a relay output. + * Sets the state of a relay output. + * + * @param relayPortHandle the relay handle + * @param on true for on, false for off */ void HAL_SetRelay(HAL_RelayHandle relayPortHandle, HAL_Bool on, int32_t* status); /** - * Get the current state of the relay channel + * Gets the current state of the relay channel. + * + * @param relayPortHandle the relay handle + * @return true for on, false for off */ HAL_Bool HAL_GetRelay(HAL_RelayHandle relayPortHandle, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/SPI.h b/hal/src/main/native/include/HAL/SPI.h index 7508ad4034..25b756da94 100644 --- a/hal/src/main/native/include/HAL/SPI.h +++ b/hal/src/main/native/include/HAL/SPI.h @@ -25,137 +25,220 @@ extern "C" { #endif /** - * Initialize the spi port. Opens the port if necessary and saves the handle. - * If opening the MXP port, also sets up the channel functions appropriately + * Initializes the SPI port. Opens the port if necessary and saves the handle. + * + * If opening the MXP port, also sets up the channel functions appropriately. + * * @param port The number of the port to use. 0-3 for Onboard CS0-CS3, 4 for MXP */ void HAL_InitializeSPI(HAL_SPIPort port, int32_t* status); /** - * Generic transaction. + * Performs an SPI send/receive transaction. * * This is a lower-level interface to the spi hardware giving you more control * over each transaction. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP - * @param dataToSend Buffer of data to send as part of the transaction. + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP + * @param dataToSend Buffer of data to send as part of the transaction. * @param dataReceived Buffer to read data into. - * @param size Number of bytes to transfer. [0..7] - * @return Number of bytes transferred, -1 for error + * @param size Number of bytes to transfer. [0..7] + * @return Number of bytes transferred, -1 for error */ int32_t HAL_TransactionSPI(HAL_SPIPort port, const uint8_t* dataToSend, uint8_t* dataReceived, int32_t size); /** - * Execute a write transaction with the device. + * Executes a write transaction with the device. * - * Write to a device and wait until the transaction is complete. + * Writes to a device and wait until the transaction is complete. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP * @param datToSend The data to write to the register on the device. - * @param sendSize The number of bytes to be written - * @return The number of bytes written. -1 for an error + * @param sendSize The number of bytes to be written + * @return The number of bytes written. -1 for an error */ int32_t HAL_WriteSPI(HAL_SPIPort port, const uint8_t* dataToSend, int32_t sendSize); /** - * Execute a read from the device. + * Executes a read from the device. * - * This method does not write any data out to the device - * Most spi devices will require a register address to be written before - * they begin returning data + * This method does not write any data out to the device. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * Most spi devices will require a register address to be written before they + * begin returning data. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP * @param buffer A pointer to the array of bytes to store the data read from the * device. - * @param count The number of bytes to read in the transaction. [1..7] - * @return Number of bytes read. -1 for error. + * @param count The number of bytes to read in the transaction. [1..7] + * @return Number of bytes read. -1 for error. */ int32_t HAL_ReadSPI(HAL_SPIPort port, uint8_t* buffer, int32_t count); /** - * Close the SPI port + * Closes the SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP */ void HAL_CloseSPI(HAL_SPIPort port); /** - * Set the clock speed for the SPI bus. + * Sets the clock speed for the SPI bus. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP * @param speed The speed in Hz (0-1MHz) */ void HAL_SetSPISpeed(HAL_SPIPort port, int32_t speed); /** - * Set the SPI options + * Sets the SPI options. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP - * @param msbFirst True to write the MSB first, False for LSB first + * @param port The number of the port to use. 0-3 for Onboard + * CS0-CS2, 4 for MXP + * @param msbFirst True to write the MSB first, False for LSB first * @param sampleOnTrailing True to sample on the trailing edge, False to sample * on the leading edge - * @param clkIdleHigh True to set the clock to active low, False to set the + * @param clkIdleHigh True to set the clock to active low, False to set the * clock active high */ void HAL_SetSPIOpts(HAL_SPIPort port, HAL_Bool msbFirst, HAL_Bool sampleOnTrailing, HAL_Bool clkIdleHigh); /** - * Set the CS Active high for a SPI port + * Sets the CS Active high for a SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP */ void HAL_SetSPIChipSelectActiveHigh(HAL_SPIPort port, int32_t* status); /** - * Set the CS Active low for a SPI port + * Sets the CS Active low for a SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP */ void HAL_SetSPIChipSelectActiveLow(HAL_SPIPort port, int32_t* status); /** - * Get the stored handle for a SPI port + * Gets the stored handle for a SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP - * @return The stored handle for the SPI port. 0 represents no stored handle. + * @return The stored handle for the SPI port. 0 represents no stored + * handle. */ int32_t HAL_GetSPIHandle(HAL_SPIPort port); /** - * Set the stored handle for a SPI port + * Sets the stored handle for a SPI port. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for * MXP. * @param handle The value of the handle for the port. */ void HAL_SetSPIHandle(HAL_SPIPort port, int32_t handle); +/** + * Initializes the SPI automatic accumulator. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param bufferSize The accumulator buffer size. + */ void HAL_InitSPIAuto(HAL_SPIPort port, int32_t bufferSize, int32_t* status); +/** + * Frees an SPI automatic accumulator. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP. + */ void HAL_FreeSPIAuto(HAL_SPIPort port, int32_t* status); +/** + * Sets the period for automatic SPI accumulation. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP. + * @param period The accumlation period (seconds). + */ void HAL_StartSPIAutoRate(HAL_SPIPort port, double period, int32_t* status); +/** + * Starts the auto SPI accumulator on a specific trigger. + * + * Note that triggering on both rising and falling edges is a valid + * configuration. + * + * @param port The number of the port to use. 0-3 for Onboard + * CS0-CS2, 4 for MXP. + * @param digitalSourceHandle The trigger source to use (Either + * HAL_AnalogTriggerHandle or HAL_DigitalHandle). + * @param analogTriggerType The analog trigger type, if the source is an + * analog trigger. + * @param triggerRising Trigger on the rising edge if true. + * @param triggerFalling Trigger on the falling edge if true. + */ void HAL_StartSPIAutoTrigger(HAL_SPIPort port, HAL_Handle digitalSourceHandle, HAL_AnalogTriggerType analogTriggerType, HAL_Bool triggerRising, HAL_Bool triggerFalling, int32_t* status); +/** + * Stops an automatic SPI accumlation. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP. + */ void HAL_StopSPIAuto(HAL_SPIPort port, int32_t* status); +/** + * Sets the data to be transmitted to the device to initiate a read. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param dataToSend Pointer to the data to send (Gets copied for continue use, + * so no need to keep alive). + * @param dataSize The length of the data to send. + * @param zeroSize The number of zeros to send after the data. + */ void HAL_SetSPIAutoTransmitData(HAL_SPIPort port, const uint8_t* dataToSend, int32_t dataSize, int32_t zeroSize, int32_t* status); +/** + * Immediately forces an SPI read to happen. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP. + */ void HAL_ForceSPIAutoRead(HAL_SPIPort port, int32_t* status); +/** + * Reads data received by the SPI accumulator. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param buffer The buffer to store the data into. + * @param numToRead The number of bytes to read. + * @param timeout The read timeout (in seconds). + * @return The number of bytes actually read. + */ int32_t HAL_ReadSPIAutoReceivedData(HAL_SPIPort port, uint8_t* buffer, int32_t numToRead, double timeout, int32_t* status); +/** + * Gets the count of how many SPI accumulations have been missed. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP. + * @return The number of missed accumulations. + */ int32_t HAL_GetSPIAutoDroppedCount(HAL_SPIPort port, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/HAL/SerialPort.h b/hal/src/main/native/include/HAL/SerialPort.h index 7bc5ee5d25..e9e7021008 100644 --- a/hal/src/main/native/include/HAL/SerialPort.h +++ b/hal/src/main/native/include/HAL/SerialPort.h @@ -20,32 +20,199 @@ enum HAL_SerialPort : int32_t { extern "C" { #endif +/** + * Initializes a serial port. + * + * The channels are either the onboard RS232, the mxp uart, or 2 USB ports. The + * top port is USB1, the bottom port is USB2. + * + * @param port the serial port to initialize + */ void HAL_InitializeSerialPort(HAL_SerialPort port, int32_t* status); + +/** + * Initializes a serial port with a direct name. + * + * This name is the VISA name for a specific port (find this in the web dash). + * Note these are not always consistent between roboRIO reboots. + * + * @param port the serial port to initialize + * @param portName the VISA port name + */ void HAL_InitializeSerialPortDirect(HAL_SerialPort port, const char* portName, int32_t* status); + +/** + * Sets the baud rate of a serial port. + * + * Any value between 0 and 0xFFFFFFFF may be used. Default is 9600. + * + * @param port the serial port + * @param baud the baud rate to set + */ void HAL_SetSerialBaudRate(HAL_SerialPort port, int32_t baud, int32_t* status); + +/** + * Sets the number of data bits on a serial port. + * + * Defaults to 8. + * + * @param port the serial port + * @param bits the number of data bits (5-8) + */ void HAL_SetSerialDataBits(HAL_SerialPort port, int32_t bits, int32_t* status); + +/** + * Sets the number of parity bits on a serial port. + * + * Valid values are: + * 0: None (default) + * 1: Odd + * 2: Even + * 3: Mark - Means exists and always 1 + * 4: Space - Means exists and always 0 + * + * @param port the serial port + * @param parity the parity bit mode (see remarks for valid values) + */ void HAL_SetSerialParity(HAL_SerialPort port, int32_t parity, int32_t* status); + +/** + * Sets the number of stop bits on a serial port. + * + * Valid values are: + * 10: One stop bit (default) + * 15: One and a half stop bits + * 20: Two stop bits + * + * @param port the serial port + * @param stopBits the stop bit value (see remarks for valid values) + */ void HAL_SetSerialStopBits(HAL_SerialPort port, int32_t stopBits, int32_t* status); + +/** + * Sets the write mode on a serial port. + * + * Valid values are: + * 1: Flush on access + * 2: Flush when full (default) + * + * @param port the serial port + * @param mode the mode to set (see remarks for valid values) + */ void HAL_SetSerialWriteMode(HAL_SerialPort port, int32_t mode, int32_t* status); + +/** + * Sets the flow control mode of a serial port. + * + * Valid values are: + * 0: None (default) + * 1: XON-XOFF + * 2: RTS-CTS + * 3: DTR-DSR + * + * @param port the serial port + * @param flow the mode to set (see remarks for valid values) + */ void HAL_SetSerialFlowControl(HAL_SerialPort port, int32_t flow, int32_t* status); + +/** + * Sets the minimum serial read timeout of a port. + * + * @param port the serial port + * @param timeout the timeout in milliseconds + */ void HAL_SetSerialTimeout(HAL_SerialPort port, double timeout, int32_t* status); + +/** + * Sets the termination character that terminates a read. + * + * By default this is disabled. + * + * @param port the serial port + * @param terminator the termination character to set + */ void HAL_EnableSerialTermination(HAL_SerialPort port, char terminator, int32_t* status); + +/** + * Disables a termination character for reads. + * + * @param port the serial port + */ void HAL_DisableSerialTermination(HAL_SerialPort port, int32_t* status); + +/** + * Sets the size of the read buffer. + * + * @param port the serial port + * @param size the read buffer size + */ void HAL_SetSerialReadBufferSize(HAL_SerialPort port, int32_t size, int32_t* status); + +/** + * Sets the size of the write buffer. + * + * @param port the serial port + * @param size the write buffer size + */ void HAL_SetSerialWriteBufferSize(HAL_SerialPort port, int32_t size, int32_t* status); + +/** + * Gets the number of bytes currently in the read buffer. + * + * @param port the serial port + * @return the number of bytes in the read buffer + */ int32_t HAL_GetSerialBytesReceived(HAL_SerialPort port, int32_t* status); + +/** + * Reads data from the serial port. + * + * Will wait for either timeout (if set), the termination char (if set), or the + * count to be full. Whichever one comes first. + * + * @param port the serial port + * @param count the number of bytes maximum to read + * @return the number of bytes actually read + */ int32_t HAL_ReadSerial(HAL_SerialPort port, char* buffer, int32_t count, int32_t* status); + +/** + * Writes data to the serial port. + * + * @param port the serial port + * @param buffer the buffer to write + * @param count the number of bytes to write from the buffer + * @return the number of bytes actually written + */ int32_t HAL_WriteSerial(HAL_SerialPort port, const char* buffer, int32_t count, int32_t* status); + +/** + * Flushes the serial write buffer out to the port. + * + * @param port the serial port + */ void HAL_FlushSerial(HAL_SerialPort port, int32_t* status); + +/** + * Clears the receive buffer of the serial port. + * + * @param port the serial port + */ void HAL_ClearSerial(HAL_SerialPort port, int32_t* status); + +/** + * Closes a serial port. + * + * @param port the serial port to close + */ void HAL_CloseSerial(HAL_SerialPort port, int32_t* status); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/Solenoid.h b/hal/src/main/native/include/HAL/Solenoid.h index d788f27168..c9022137a0 100644 --- a/hal/src/main/native/include/HAL/Solenoid.h +++ b/hal/src/main/native/include/HAL/Solenoid.h @@ -15,23 +15,119 @@ extern "C" { #endif +/** + * Initializes a solenoid port. + * + * @param portHandle the port handle of the module and channel to initialize + * @return the created solenoid handle + */ HAL_SolenoidHandle HAL_InitializeSolenoidPort(HAL_PortHandle portHandle, int32_t* status); + +/** + * Frees a solenoid port. + * + * @param solenoidPortHandle the solenoid handle + */ void HAL_FreeSolenoidPort(HAL_SolenoidHandle solenoidPortHandle); + +/** + * Checks if a solenoid module is in the valid range. + * + * @param module the module number to check + * @return true if the module number is valid, otherwise false + */ HAL_Bool HAL_CheckSolenoidModule(int32_t module); + +/** + * Checks if a solenoid channel is in the valid range. + * + * @param channel the channel number to check + * @return true if the channel number is valid, otherwise false + */ HAL_Bool HAL_CheckSolenoidChannel(int32_t channel); + +/** + * Gets the current solenoid output value. + * + * @param solenoidPortHandle the solenoid handle + * @return true if the solenoid is on, otherwise false + */ HAL_Bool HAL_GetSolenoid(HAL_SolenoidHandle solenoidPortHandle, int32_t* status); + +/** + * Gets the status of all solenoids on a specific module. + * + * @param module the module to check + * @return bitmask of the channels, 1 for on 0 for off + */ int32_t HAL_GetAllSolenoids(int32_t module, int32_t* status); + +/** + * Sets a solenoid output value. + * + * @param solenoidPortHandle the solenoid handle + * @param value true for on, false for off + */ void HAL_SetSolenoid(HAL_SolenoidHandle solenoidPortHandle, HAL_Bool value, int32_t* status); + +/** + * Sets all channels on a specific module. + * + * @param module the module to set the channels on + * @param state bitmask of the channels to set, 1 for on 0 for off + */ void HAL_SetAllSolenoids(int32_t module, int32_t state, int32_t* status); + +/** + * Gets the channels blacklisted from being enabled on a module. + * + * @param module the module to check + * @retur bitmask of the blacklisted channels, 1 for true 0 for false + */ int32_t HAL_GetPCMSolenoidBlackList(int32_t module, int32_t* status); + +/** + * Gets if a specific module has an over or under voltage sticky fault. + * + * @param module the module to check + * @return true if a stick fault is set, otherwise false + */ HAL_Bool HAL_GetPCMSolenoidVoltageStickyFault(int32_t module, int32_t* status); + +/** + * Gets if a specific module has an over or under voltage fault. + * + * @param module the module to check + * @return true if faulted, otherwise false + */ HAL_Bool HAL_GetPCMSolenoidVoltageFault(int32_t module, int32_t* status); + +/** + * Clears all faults on a module. + * + * @param module the module to clear + */ void HAL_ClearAllPCMStickyFaults(int32_t module, int32_t* status); + +/** + * Sets the one shot duration on a solenoid channel. + * + * @param solenoidPortHandle the solenoid handle + * @param durMS the one shot duration in ms + */ void HAL_SetOneShotDuration(HAL_SolenoidHandle solenoidPortHandle, int32_t durMS, int32_t* status); + +/** + * Fires a single pulse on a solenoid channel. + * + * The pulse is the duration set by HAL_SetOneShotDuration(). + * + * @param solenoidPortHandle the solenoid handle + */ void HAL_FireOneShot(HAL_SolenoidHandle solenoidPortHandle, int32_t* status); #ifdef __cplusplus } // extern "C" diff --git a/hal/src/main/native/include/HAL/Threads.h b/hal/src/main/native/include/HAL/Threads.h index 91c80279c4..725f744a7b 100644 --- a/hal/src/main/native/include/HAL/Threads.h +++ b/hal/src/main/native/include/HAL/Threads.h @@ -19,52 +19,52 @@ extern "C" { /** - * Get the thread priority for the specified thread. + * Gets the thread priority for the specified thread. * - * @param handle Native handle pointer to the thread to get the priority for + * @param handle Native handle pointer to the thread to get the priority for * @param isRealTime Set to true if thread is realtime, otherwise false - * @param status Error status variable. 0 on success - * @return The current thread priority. Scaled 1-99, with 1 being highest. + * @param status Error status variable. 0 on success + * @return The current thread priority. Scaled 1-99, with 1 being + * highest. */ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime, int32_t* status); /** - * Get the thread priority for the current thread. + * Gets the thread priority for the current thread. * - * @param handle Native handle pointer to the thread to get the priority for + * @param handle Native handle pointer to the thread to get the priority for * @param isRealTime Set to true if thread is realtime, otherwise false - * @param status Error status variable. 0 on success - * @return The current thread priority. Scaled 1-99, with 1 being highest. + * @param status Error status variable. 0 on success + * @return The current thread priority. Scaled 1-99, with 1 being + * highest. */ int32_t HAL_GetCurrentThreadPriority(HAL_Bool* isRealTime, int32_t* status); /** - * Sets the thread priority for the specified thread + * Sets the thread priority for the specified thread. * - * @param thread Reference to the thread to set the priority of + * @param thread Reference to the thread to set the priority of * @param realTime Set to true to set a realtime priority, false for standard * priority * @param priority Priority to set the thread to. Scaled 1-99, with 1 being * highest - * @param status Error status variable. 0 on success - * - * @return The success state of setting the priority + * @param status Error status variable. 0 on success + * @return The success state of setting the priority */ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime, int32_t priority, int32_t* status); /** - * Sets the thread priority for the current thread + * Sets the thread priority for the current thread. * - * @param thread Reference to the thread to set the priority of + * @param thread Reference to the thread to set the priority of * @param realTime Set to true to set a realtime priority, false for standard * priority * @param priority Priority to set the thread to. Scaled 1-99, with 1 being * highest - * @param status Error status variable. 0 on success - * - * @return The success state of setting the priority + * @param status Error status variable. 0 on success + * @return The success state of setting the priority */ HAL_Bool HAL_SetCurrentThreadPriority(HAL_Bool realTime, int32_t priority, int32_t* status); diff --git a/hal/src/main/native/include/HAL/UsageReporting.h b/hal/src/main/native/include/HAL/UsageReporting.h index aaa7d8df81..8b7cc9849e 100644 --- a/hal/src/main/native/include/HAL/UsageReporting.h +++ b/hal/src/main/native/include/HAL/UsageReporting.h @@ -140,7 +140,7 @@ namespace nUsageReporting } tInstances; /** - * Report the usage of a resource of interest. + * Reports the usage of a resource of interest. * * @param resource one of the values in the tResourceType above (max value 51). * @param instanceNumber an index that identifies the resource instance. diff --git a/hal/src/main/native/include/HAL/cpp/SerialHelper.h b/hal/src/main/native/include/HAL/cpp/SerialHelper.h index df8b0417bb..df33529e2c 100644 --- a/hal/src/main/native/include/HAL/cpp/SerialHelper.h +++ b/hal/src/main/native/include/HAL/cpp/SerialHelper.h @@ -19,14 +19,45 @@ #include "HAL/SerialPort.h" namespace hal { +/** + * A class for deterministically getting information about Serial Ports. + */ class SerialHelper { public: SerialHelper(); + /** + * Get the VISA name of a serial port. + * + * @param port the serial port index + * @param status status check + * @return the VISA name + */ std::string GetVISASerialPortName(HAL_SerialPort port, int32_t* status); + + /** + * Get the OS name of a serial port. + * + * @param port the serial port index + * @param status status check + * @return the OS name + */ std::string GetOSSerialPortName(HAL_SerialPort port, int32_t* status); + /** + * Get a vector of all serial port VISA names. + * + * @param status status check + * @return vector of serial port VISA names + */ std::vector GetVISASerialPortList(int32_t* status); + + /** + * Get a vector of all serial port OS names. + * + * @param status status check + * @return vector of serial port OS names + */ std::vector GetOSSerialPortList(int32_t* status); private: diff --git a/hal/src/main/native/include/HAL/cpp/UnsafeDIO.h b/hal/src/main/native/include/HAL/cpp/UnsafeDIO.h index caf1ab135e..aefb4fade5 100644 --- a/hal/src/main/native/include/HAL/cpp/UnsafeDIO.h +++ b/hal/src/main/native/include/HAL/cpp/UnsafeDIO.h @@ -13,6 +13,13 @@ #include "HAL/Types.h" namespace hal { + +/** + * Proxy class for directly manipulating the DIO pins. + * + * This class is not copyable or movable, and should never be used + * outside of the UnsafeManipulateDIO callback. + */ struct DIOSetProxy { DIOSetProxy(const DIOSetProxy&) = delete; DIOSetProxy(DIOSetProxy&&) = delete; @@ -54,6 +61,9 @@ int32_t ComputeDigitalMask(HAL_DigitalHandle handle, int32_t* status); * functions on the Proxy object passed as a parameter can deadlock your * program. * + * @param handle the HAL digital handle of the pin to toggle. + * @param status status check + * @param func A functor taking a ref to a DIOSetProxy object. */ template void UnsafeManipulateDIO(HAL_DigitalHandle handle, int32_t* status, diff --git a/hal/src/main/native/include/HAL/cpp/fpga_clock.h b/hal/src/main/native/include/HAL/cpp/fpga_clock.h index 6b13aaf0ec..5097190df1 100644 --- a/hal/src/main/native/include/HAL/cpp/fpga_clock.h +++ b/hal/src/main/native/include/HAL/cpp/fpga_clock.h @@ -12,6 +12,9 @@ namespace hal { +/** + * A std::chrono compatible wrapper around the FPGA Timer. + */ class fpga_clock { public: typedef std::chrono::microseconds::rep rep; diff --git a/hal/src/main/native/include/HAL/handles/HandlesInternal.h b/hal/src/main/native/include/HAL/handles/HandlesInternal.h index c0f9ca2cf7..25ba56f83b 100644 --- a/hal/src/main/native/include/HAL/handles/HandlesInternal.h +++ b/hal/src/main/native/include/HAL/handles/HandlesInternal.h @@ -23,6 +23,9 @@ namespace hal { +/** + * Base for all HAL Handles. + */ class HandleBase { public: HandleBase(); @@ -38,6 +41,9 @@ class HandleBase { constexpr int16_t InvalidHandleIndex = -1; +/** + * Enum of HAL handle types. Vendors/Teams should use Vendor (17). + */ enum class HAL_HandleEnum { Undefined = 0, DIO = 1, @@ -61,20 +67,63 @@ enum class HAL_HandleEnum { CAN = 19, }; +/** + * Get the handle index from a handle. + * + * @param handle the handle + * @return the index + */ static inline int16_t getHandleIndex(HAL_Handle handle) { // mask and return last 16 bits return static_cast(handle & 0xffff); } + +/** + * Get the handle type from a handle. + * + * @param handle the handle + * @return the type + */ static inline HAL_HandleEnum getHandleType(HAL_Handle handle) { // mask first 8 bits and cast to enum return static_cast((handle >> 24) & 0xff); } + +/** + * Get if the handle is a specific type. + * + * @param handle the handle + * @param handleType the type to check + * @return true if the type is correct, otherwise false + */ static inline bool isHandleType(HAL_Handle handle, HAL_HandleEnum handleType) { return handleType == getHandleType(handle); } + +/** + * Get if the version of the handle is correct. + * + * Do not use on the roboRIO, used specifically for the sim to handle resets. + * + * @param handle the handle + * @param version the handle version to check + * @return true if the handle is the right version, otherwise false + */ static inline bool isHandleCorrectVersion(HAL_Handle handle, int16_t version) { return (((handle & 0xFF0000) >> 16) & version) == version; } + +/** + * Get if the handle is a correct type and version. + * + * Note the version is not checked on the roboRIO. + * + * @param handle the handle + * @param handleType the type to check + * @param version the handle version to check + * @return true if the handle is proper version and type, otherwise + * false. + */ static inline int16_t getHandleTypedIndex(HAL_Handle handle, HAL_HandleEnum enumType, int16_t version) { @@ -95,27 +144,68 @@ static inline int16_t getHandleTypedIndex(HAL_Handle handle, */ // using a 16 bit value so we can store 0-255 and still report error +/** + * Gets the port channel of a port handle. + * + * @param handle the port handle + * @return the port channel + */ static inline int16_t getPortHandleChannel(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) return InvalidHandleIndex; return static_cast(handle & 0xff); } // using a 16 bit value so we can store 0-255 and still report error +/** + * Gets the port module of a port handle. + * + * @param handle the port handle + * @return the port module + */ static inline int16_t getPortHandleModule(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) return InvalidHandleIndex; return static_cast((handle >> 8) & 0xff); } // using a 16 bit value so we can store 0-255 and still report error +/** + * Gets the SPI channel of a port handle. + * + * @param handle the port handle + * @return the port SPI channel + */ static inline int16_t getPortHandleSPIEnable(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) return InvalidHandleIndex; return static_cast((handle >> 16) & 0xff); } +/** + * Create a port handle. + * + * @param channel the channel + * @param module the module + * @return port handle for the module and channel + */ HAL_PortHandle createPortHandle(uint8_t channel, uint8_t module); +/** + * Create a port handle for SPI. + * + * @param channel the SPI channel + * @return port handle for the channel + */ HAL_PortHandle createPortHandleForSPI(uint8_t channel); +/** + * Create a handle for a specific index, type and version. + * + * Note the version is not checked on the roboRIO. + * + * @param index the index + * @param handleType the handle type + * @param version the handle version + * @return the created handle + */ HAL_Handle createHandle(int16_t index, HAL_HandleEnum handleType, int16_t version); } // namespace hal diff --git a/hal/src/main/native/sim/DriverStation.cpp b/hal/src/main/native/sim/DriverStation.cpp index 7a57e94e9a..ebdf0636ca 100644 --- a/hal/src/main/native/sim/DriverStation.cpp +++ b/hal/src/main/native/sim/DriverStation.cpp @@ -168,7 +168,7 @@ double HAL_GetMatchTime(int32_t* status) { return SimDriverStationData->GetMatchTime(); } -int HAL_GetMatchInfo(HAL_MatchInfo* info) { +int32_t HAL_GetMatchInfo(HAL_MatchInfo* info) { SimDriverStationData->GetMatchInfo(info); return 0; }