diff --git a/hal/src/main/java/edu/wpi/first/hal/AccelerometerJNI.java b/hal/src/main/java/edu/wpi/first/hal/AccelerometerJNI.java index 3f22bcb1eb..5f34924eb5 100644 --- a/hal/src/main/java/edu/wpi/first/hal/AccelerometerJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/AccelerometerJNI.java @@ -4,14 +4,59 @@ package edu.wpi.first.hal; +/** + * Accelerometer HAL JNI methods. + * + * @see "hal/Accelerometer.h" + */ public class AccelerometerJNI extends JNIWrapper { + /** + * Sets the accelerometer to active or standby mode. + * + *

It must be in standby mode to change any configuration. + * + * @see "HAL_SetAccelerometerActive" + * @param active true to set to active, false for standby + */ public static native void setAccelerometerActive(boolean active); + /** + * 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. + * + * @see "HAL_SetAccelerometerRange(int range)" + * @param range the accelerometer range + */ public static native void setAccelerometerRange(int range); + /** + * Gets the x-axis acceleration. + * + *

This is a floating point value in units of 1 g-force. + * + * @see "HAL_GetAccelerometerX()" + * @return the X acceleration + */ public static native double getAccelerometerX(); + /** + * Gets the y-axis acceleration. + * + *

This is a floating point value in units of 1 g-force. + * + * @see "HAL_GetAccelerometerY()" + * @return the Y acceleration + */ public static native double getAccelerometerY(); + /** + * Gets the z-axis acceleration. + * + *

This is a floating point value in units of 1 g-force. + * + * @see "HAL_GetAccelerometerZ()" + * @return the Z acceleration + */ public static native double getAccelerometerZ(); } diff --git a/hal/src/main/java/edu/wpi/first/hal/AddressableLEDJNI.java b/hal/src/main/java/edu/wpi/first/hal/AddressableLEDJNI.java index 57f4b5dc14..b2695a3827 100644 --- a/hal/src/main/java/edu/wpi/first/hal/AddressableLEDJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/AddressableLEDJNI.java @@ -4,21 +4,97 @@ package edu.wpi.first.hal; +/** + * Addressable LED HAL JNI Methods. + * + * @see "hal/AdressableLED.h" + */ public class AddressableLEDJNI extends JNIWrapper { + /** + * Initialize Addressable LED using a PWM Digital handle. + * + * @param pwmHandle handle of the digital port for PWM + * @return Addressable LED handle + * @see "HAL_InitializeAddressableLED" + */ public static native int initialize(int pwmHandle); + /** + * Free the Addressable LED Handle. + * + * @param handle the Addressable LED handle to free + * @see "HAL_FreeAddressableLED" + */ public static native void free(int handle); + /** + * Sets the length of the LED strip. + * + *

The max length is 5460 LEDs. + * + * @param handle the Addressable LED handle + * @param length the strip length + * @see "HAL_SetAddressableLEDLength" + */ public static native void setLength(int handle, int length); + /** + * Sets the led output data. + * + *

If the output is enabled, this will start writing the next data cycle. It is safe to call, + * even while output is enabled. + * + * @param handle the Addressable LED handle + * @param data the buffer to write + * @see "HAL_WriteAddressableLEDData" + */ public static native void setData(int handle, byte[] data); + /** + * Sets the bit timing. + * + *

By default, the driver is set up to drive WS2812Bs, so nothing needs to be set for those. + * + * @param handle the Addressable LED handle + * @param highTime0NanoSeconds high time for 0 bit (default 400ns) + * @param lowTime0NanoSeconds low time for 0 bit (default 900ns) + * @param highTime1NanoSeconds high time for 1 bit (default 900ns) + * @param lowTime1NanoSeconds low time for 1 bit (default 600ns) + * @see "HAL_SetAddressableLEDBitTiming" + */ public static native void setBitTiming( - int handle, int highTime0, int lowTime0, int highTime1, int lowTime1); + int handle, + int highTime0NanoSeconds, + int lowTime0NanoSeconds, + int highTime1NanoSeconds, + int lowTime1NanoSeconds); - public static native void setSyncTime(int handle, int syncTime); + /** + * Sets the sync time. + * + *

The sync time is the time to hold output so LEDs enable. Default set for WS2812B. + * + * @param handle the Addressable LED handle + * @param syncTimeMicroSeconds the sync time (default 280us) + * @see "HAL_SetAddressableLEDSyncTime" + */ + public static native void setSyncTime(int handle, int syncTimeMicroSeconds); + /** + * Starts the output. + * + *

The output writes continuously. + * + * @param handle the Addressable LED handle + * @see "HAL_StartAddressableLEDOutput" + */ public static native void start(int handle); + /** + * Stops the output. + * + * @param handle the Addressable LED handle + * @see "HAL_StopAddressableLEDOutput" + */ public static native void stop(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/AnalogGyroJNI.java b/hal/src/main/java/edu/wpi/first/hal/AnalogGyroJNI.java index 5763f6ebf4..cbc3d4f8e5 100644 --- a/hal/src/main/java/edu/wpi/first/hal/AnalogGyroJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/AnalogGyroJNI.java @@ -4,30 +4,126 @@ package edu.wpi.first.hal; +/** + * Analog Gyro JNI Functions. + * + * @see "hal/AnalogGyro.h" + */ public class AnalogGyroJNI extends JNIWrapper { + /** + * Initializes an analog gyro. + * + * @param halAnalogInputHandle handle to the analog input port + * @return the initialized gyro handle + * @see "HAL_InitializeAnalogGyro" + */ public static native int initializeAnalogGyro(int halAnalogInputHandle); + /** + * Sets up an analog gyro with the proper offsets and settings for the KOP analog gyro. + * + * @param handle the gyro handle + * @see "HAL_SetupAnalogGyro" + */ public static native void setupAnalogGyro(int handle); + /** + * Frees an analog gyro. + * + * @param handle the gyro handle + * @see "HAL_FreeAnalogGyro" + */ public static native void freeAnalogGyro(int 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 + * @see "HAL_SetAnalogGyroParameters" + */ public static native void setAnalogGyroParameters( int handle, double voltsPerDegreePerSecond, double offset, int center); + /** + * Sets the analog gyro volts per degrees per second scaling. + * + * @param handle the gyro handle + * @param voltsPerDegreePerSecond the gyro volts scaling + * @see "HAL_SetAnalogGyroVoltsPerDegreePerSecond" + */ public static native void setAnalogGyroVoltsPerDegreePerSecond( int handle, double voltsPerDegreePerSecond); + /** + * Resets the analog gyro value to 0. + * + * @param handle the gyro handle + * @see "HAL_ResetAnalogGyro" + */ public static native void resetAnalogGyro(int handle); + /** + * 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 + * @see "HAL_CalibrateAnalogGyro" + */ public static native void calibrateAnalogGyro(int handle); + /** + * Sets the deadband of the analog gyro. + * + * @param handle the gyro handle + * @param volts the voltage deadband + * @see "HAL_SetAnalogGyroDeadband" + */ public static native void setAnalogGyroDeadband(int handle, double volts); + /** + * Gets the gyro angle in degrees. + * + * @param handle the gyro handle + * @return the gyro angle in degrees + * @see "HAL_GetAnalogGyroAngle" + */ public static native double getAnalogGyroAngle(int handle); + /** + * Gets the gyro rate in degrees/second. + * + * @param handle the gyro handle + * @return the gyro rate in degrees/second + * @see "HAL_GetAnalogGyroRate" + */ public static native double getAnalogGyroRate(int handle); + /** + * 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 + * @see "HAL_GetAnalogGyroOffset" + */ public static native double getAnalogGyroOffset(int handle); + /** + * 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 + * @see "HAL_GetAnalogGyroCenter" + */ public static native int getAnalogGyroCenter(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/AnalogJNI.java b/hal/src/main/java/edu/wpi/first/hal/AnalogJNI.java index b80388d722..551f3be8f5 100644 --- a/hal/src/main/java/edu/wpi/first/hal/AnalogJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/AnalogJNI.java @@ -3,7 +3,14 @@ // the WPILib BSD license file in the root directory of this project. package edu.wpi.first.hal; - +/** + * Analog Input / Output / Accumulator / Trigger JNI Functions. + * + * @see "hal/AnalogInput.h" + * @see "hal/AnalogOutput.h" + * @see "hal/AnalogAccumulator.h" + * @see "hal/AnalogTrigger.h" + */ public class AnalogJNI extends JNIWrapper { /** * native declaration : AthenaJava\target\native\include\HAL\Analog.h:58
@@ -20,96 +27,466 @@ public class AnalogJNI extends JNIWrapper { int kFallingPulse = 3; } + /** + * Initializes the analog input port using the given port object. + * + * @param halPortHandle Handle to the port to initialize. + * @return the created analog input handle + * @see "HAL_InitializeAnalogInputPort" + */ public static native int initializeAnalogInputPort(int halPortHandle); + /** + * Frees an analog input port. + * + * @param portHandle Handle to the analog port. + * @see "HAL_FreeAnalogInputPort" + */ public static native void freeAnalogInputPort(int portHandle); + /** + * Initializes the analog output port using the given port object. + * + * @param halPortHandle handle to the port + * @return the created analog output handle + * @see "HAL_InitializeAnalogOutputPort" + */ public static native int initializeAnalogOutputPort(int halPortHandle); - + /** + * Frees an analog output port. + * + * @param portHandle the analog output handle + * @see "HAL_FreeAnalogOutputPort" + */ public static native void freeAnalogOutputPort(int portHandle); + /** + * Checks that the analog module number is valid. + * + * @param module The analog module number. + * @return Analog module is valid and present + * @see "HAL_CheckAnalogModule" + */ public static native boolean checkAnalogModule(byte module); + /** + * Checks that the analog output channel number is valid. 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. + * @return Analog channel is valid + * @see "HAL_CheckAnalogInputChannel" + */ public static native boolean checkAnalogInputChannel(int channel); public static native boolean checkAnalogOutputChannel(int channel); + /** + * Indicates the analog input is used by a simulated device. + * + * @param handle the analog input handle + * @param device simulated device handle + * @see "HAL_SetAnalogInputSimDevice" + */ public static native void setAnalogInputSimDevice(int handle, int device); public static native void setAnalogOutput(int portHandle, double voltage); public static native double getAnalogOutput(int portHandle); + /** + * Sets the sample rate. + * + *

This is a global setting for the Athena and effects all channels. + * + * @param samplesPerSecond The number of samples per channel per second. + * @see "HAL_SetAnalogSampleRate" + */ public static native void setAnalogSampleRate(double samplesPerSecond); + /** + * 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. + * + * @return Sample rate. + * @see "HAL_GetAnalogSampleRate" + */ public static native double getAnalogSampleRate(); + /** + * 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 expense of sampling rate. The + * averaging is done automatically in the FPGA. + * + * @param analogPortHandle Handle to the analog port to configure. + * @param bits Number of bits to average. + * @see "HAL_SetAnalogAverageBits" + */ public static native void setAnalogAverageBits(int analogPortHandle, int 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. + * + * @param analogPortHandle Handle to the analog port to use. + * @return Bits to average. + * @see "HAL_GetAnalogAverageBits" + */ public static native int getAnalogAverageBits(int analogPortHandle); + /** + * 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 measurements at the expense of sampling + * rate. The oversampling is done automatically in the FPGA. + * + * @param analogPortHandle Handle to the analog port to use. + * @param bits Number of bits to oversample. + * @see "HAL_SetAnalogOversampleBits" + */ public static native void setAnalogOversampleBits(int analogPortHandle, int 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 FPGA. + * + * @param analogPortHandle Handle to the analog port to use. + * @return Bits to oversample. + * @see "HAL_GetAnalogOversampleBits" + */ public static native int getAnalogOversampleBits(int analogPortHandle); + /** + * 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 GetVoltage() to get the analog value in + * calibrated units. + * + * @param analogPortHandle Handle to the analog port to use. + * @return A sample straight from the channel on this module. + * @see "HAL_GetAnalogValue" + */ public static native short getAnalogValue(int analogPortHandle); + /** + * 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(). The value configured in + * SetAverageBits() will cause this value to be averaged 2**bits number of samples. This is not a + * sliding window. The sample will not change until 2**(OversampleBits + AverageBits) samples have + * been acquired from the module on this channel. Use GetAverageVoltage() to get the analog value + * in calibrated units. + * + * @param analogPortHandle Handle to the analog port to use. + * @return A sample from the oversample and average engine for the channel. + * @see "HAL_GetAnalogAverageValue" + */ public static native int getAnalogAverageValue(int analogPortHandle); + /** + * 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. + * + *

todo This assumes raw values. Oversampling not supported as is. + * + * @param analogPortHandle Handle to the analog port to use. + * @param voltage The voltage to convert. + * @return The raw value for the channel. + * @see "HAL_GetAnalogVoltsToValue" + */ public static native int getAnalogVoltsToValue(int analogPortHandle, double voltage); - + /** + * Get the analog voltage from a raw value. + * + * @param analogPortHandle Handle to the analog port the values were read from. + * @param value The raw analog value + * @return The voltage relating to the value + * @see "HAL_GetAnalogValueToVolts" + */ public static native double getAnalogValueToVolts(int analogPortHandle, int value); + /** + * 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(). + * + * @param analogPortHandle Handle to the analog port to use. + * @return A scaled sample straight from the channel on this module. + * @see "HAL_GetAnalogVoltage" + */ public static native double getAnalogVoltage(int analogPortHandle); + /** + * 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 GetLSBWeight() + * and GetOffset(). Using oversampling will cause this value to be higher resolution, but it will + * update more slowly. Using averaging will cause this value to be more stable, but it will update + * more slowly. + * + * @param analogPortHandle Handle to the analog port to use. + * @return A scaled sample from the output of the oversample and average engine for the channel. + * @see "HAL_GetAnalogAverageVoltage" + */ public static native double getAnalogAverageVoltage(int analogPortHandle); + /** + * 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. + * + *

Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9) + * + * @param analogPortHandle Handle to the analog port to use. + * @return Least significant bit weight. + * @see "HAL_GetAnalogLSBWeight" + */ public static native int getAnalogLSBWeight(int analogPortHandle); + /** + * 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. + * + *

Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9) + * + * @param analogPortHandle Handle to the analog port to use. + * @return Offset constant. + * @see "HAL_GetAnalogOffset" + */ public static native int getAnalogOffset(int analogPortHandle); + /** + * Is the channel attached to an accumulator. + * + * @param analogPortHandle Handle to the analog port. + * @return The analog channel is attached to an accumulator. + * @see "HAL_IsAccumulatorChannel" + */ public static native boolean isAccumulatorChannel(int analogPortHandle); + /** + * Initialize the accumulator. + * + * @param analogPortHandle Handle to the analog port. + * @see "HAL_InitAccumulator" + */ public static native void initAccumulator(int analogPortHandle); + /** + * Resets the accumulator to the initial value. + * + * @param analogPortHandle Handle to the analog port. + * @see "HAL_ResetAccumulator" + */ public static native void resetAccumulator(int analogPortHandle); + /** + * Set the center value of the accumulator. + * + *

The center value is subtracted from each A/D value before it is added to the accumulator. + * This is used for the center value of devices like gyros and accelerometers to make integration + * work and to take the device offset into account when integrating. + * + *

This center value is based on the output of the oversampled and averaged source from channel + * 1. Because of this, any non-zero oversample bits will affect the size of the value for this + * field. + * + * @param analogPortHandle Handle to the analog port. + * @param center The center value of the accumulator. + * @see "HAL_SetAccumulatorCenter" + */ public static native void setAccumulatorCenter(int analogPortHandle, int center); + /** + * Set the accumulator's deadband. + * + * @param analogPortHandle Handle to the analog port. + * @param deadband The deadband of the accumulator. + * @see "HAL_SetAccumulatorDeadband" + */ public static native void setAccumulatorDeadband(int analogPortHandle, int deadband); + /** + * Read the accumulated value. + * + *

Read the value that has been accumulating on channel 1. The accumulator is attached after + * the oversample and average engine. + * + * @param analogPortHandle Handle to the analog port. + * @return The 64-bit value accumulated since the last Reset(). + * @see "HAL_GetAccumulatorValue" + */ public static native long getAccumulatorValue(int analogPortHandle); + /** + * Read the number of accumulated values. + * + *

Read the count of the accumulated values since the accumulator was last Reset(). + * + * @param analogPortHandle Handle to the analog port. + * @return The number of times samples from the channel were accumulated. + * @see "HAL_GetAccumulatorCount" + */ public static native int getAccumulatorCount(int analogPortHandle); + /** + * Read the accumulated value and the number of accumulated values atomically. + * + *

This function reads the value and count from the FPGA atomically. This can be used for + * averaging. + * + * @param analogPortHandle Handle to the analog port. + * @param result Accumulator result. + * @see "HAL_GetAccumulatorOutput" + */ public static native void getAccumulatorOutput(int analogPortHandle, AccumulatorResult result); + /** + * Initializes an analog trigger. + * + * @param analogInputHandle the analog input to use for triggering + * @return the created analog trigger handle + * @see "HAL_InitializeAnalogTrigger" + */ public static native int initializeAnalogTrigger(int analogInputHandle); + /** + * Initializes an analog trigger with a Duty Cycle input. + * + * @param dutyCycleHandle the analog input to use for duty cycle + * @return tbe created analog trigger handle + * @see "HAL_InitializeAnalogTriggerDutyCycle" + */ public static native int initializeAnalogTriggerDutyCycle(int dutyCycleHandle); + /** + * Frees an analog trigger. + * + * @param analogTriggerHandle the trigger handle + * @see "HAL_CleanAnalogTrigger" + */ public static native void cleanAnalogTrigger(int analogTriggerHandle); + /** + * Sets the raw ADC upper and lower limits of the analog trigger. + * + *

HAL_SetAnalogTriggerLimitsVoltage or HAL_SetAnalogTriggerLimitsDutyCycle is likely better in + * most cases. + * + * @param analogTriggerHandle the trigger handle + * @param lower the lower ADC value + * @param upper the upper ADC value + * @see "HAL_SetAnalogTriggerLimitsRaw" + */ public static native void setAnalogTriggerLimitsRaw( int analogTriggerHandle, int lower, int upper); + /** + * Sets the upper and lower limits of the analog trigger. + * + *

The limits are given as floating point duty cycle values. + * + * @param analogTriggerHandle the trigger handle + * @param lower the lower duty cycle value + * @param higher the upper duty cycle value + * @see "HAL_SetAnalogTriggerLimitsDutyCycle" + */ public static native void setAnalogTriggerLimitsDutyCycle( int analogTriggerHandle, double lower, double higher); + /** + * 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 + * @see "HAL_SetAnalogTriggerLimitsVoltage" + */ public static native void setAnalogTriggerLimitsVoltage( int analogTriggerHandle, double lower, double upper); - + /** + * 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. + * + *

This is not allowed to be used if filtered mode is set. This is not allowed to be used with + * Duty Cycle based inputs. + * + * @param analogTriggerHandle the trigger handle + * @param useAveragedValue true to use averaged values, false for raw + * @see "HAL_SetAnalogTriggerAveraged" + */ public static native void setAnalogTriggerAveraged( int analogTriggerHandle, boolean useAveragedValue); - + /** + * 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. + * + *

This is not allowed to be used if averaged mode is set. + * + * @param analogTriggerHandle the trigger handle + * @param useFilteredValue true to use filtered values, false for average or raw + * @see "HAL_SetAnalogTriggerFiltered" + */ public static native void setAnalogTriggerFiltered( int analogTriggerHandle, boolean useFilteredValue); + /** + * Returns the InWindow output of the analog trigger. + * + *

True if the analog input is between the upper and lower limits. + * + * @param analogTriggerHandle the trigger handle + * @return the InWindow output of the analog trigger + * @see "HAL_GetAnalogTriggerInWindow" + */ public static native boolean getAnalogTriggerInWindow(int analogTriggerHandle); + /** + * Returns the TriggerState output of the analog trigger. + * + *

True if above upper limit. False if below lower limit. If in Hysteresis, maintain previous + * state. + * + * @param analogTriggerHandle the trigger handle + * @return the TriggerState output of the analog trigger + * @see "HAL_GetAnalogTriggerTriggerState" + */ public static native boolean getAnalogTriggerTriggerState(int analogTriggerHandle); + /** + * 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 + * @see "HAL_GetAnalogTriggerOutput" + */ public static native boolean getAnalogTriggerOutput(int analogTriggerHandle, int type); + /** + * Get the FPGA index for the AnlogTrigger. + * + * @param analogTriggerHandle the trigger handle + * @return the FPGA index + * @see "HAL_GetAnalogTriggerFPGAIndex" + */ public static native int getAnalogTriggerFPGAIndex(int analogTriggerHandle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/CANAPIJNI.java b/hal/src/main/java/edu/wpi/first/hal/CANAPIJNI.java index d95cf4541d..b42def47ea 100644 --- a/hal/src/main/java/edu/wpi/first/hal/CANAPIJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/CANAPIJNI.java @@ -4,33 +4,177 @@ package edu.wpi.first.hal; +/** + * CAN API HAL JNI Functions. + * + * @see "hal/CANAPI.h" + */ public class CANAPIJNI extends JNIWrapper { + /** + * Reads the current value of the millisecond-resolution timer that the CAN API functions use as a + * time base. + * + * @return Current value of timer used as a base time by the CAN API in milliseconds. + * @see "HAL_GetCANPacketBaseTime" + */ public static native long getCANPacketBaseTime(); + /** + * Initializes a CAN device. + * + *

These follow the FIRST standard CAN layout. + * https://docs.wpilib.org/en/stable/docs/software/can-devices/can-addressing.html + * + * @param manufacturer the can manufacturer + * @param deviceId the device ID (0-63) + * @param deviceType the device type + * @return the created CAN handle + * @see "HAL_InitializeCAN" + */ public static native int initializeCAN(int manufacturer, int deviceId, int deviceType); + /** + * Frees a CAN device. + * + * @param handle the CAN handle + * @see "HAL_CleanCAN" + */ public static native void cleanCAN(int 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 apiId the ID to write (0-1023 bits) + * @see "HAL_WriteCANPacket" + */ public static native void writeCANPacket(int handle, byte[] data, int apiId); + /** + * 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 apiId the ID to write (0-1023) + * @param repeatMs the period to repeat in ms + * @see "HAL_WriteCANPacketRepeating" + */ public static native void writeCANPacketRepeating( int handle, byte[] data, int apiId, int repeatMs); + /** + * Writes an RTR frame of the specified length to the CAN device with the specific ID. + * + *

By spec, the length must be equal to the length sent by the other device, otherwise behavior + * is unspecified. + * + * @param handle the CAN handle + * @param length the length of data to request (0-8) + * @param apiId the ID to write (0-1023) + * @see "HAL_WriteCANRTRFrame" + */ public static native void writeCANRTRFrame(int handle, int length, int apiId); + /** + * Writes a packet to the CAN device with a specific ID without throwing on error. + * + *

This ID is 10 bits. + * + * @param handle the CAN handle + * @param data the data to write (0-8 bytes) + * @param apiId the ID to write (0-1023 bits) + * @return Error status variable. 0 on success. + * @see "HAL_WriteCANPacket" + */ public static native int writeCANPacketNoThrow(int handle, byte[] data, int apiId); + /** + * Writes a repeating packet to the CAN device with a specific ID without throwing on error. + * + *

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 apiId the ID to write (0-1023) + * @param repeatMs the period to repeat in ms + * @return Error status variable. 0 on success. + * @see "HAL_WriteCANPacketRepeating" + */ public static native int writeCANPacketRepeatingNoThrow( int handle, byte[] data, int apiId, int repeatMs); + /** + * Writes an RTR frame of the specified length to the CAN device with the specific ID without + * throwing on error. + * + *

By spec, the length must be equal to the length sent by the other device, otherwise behavior + * is unspecified. + * + * @param handle the CAN handle + * @param length the length of data to request (0-8) + * @param apiId the ID to write (0-1023) + * @return Error status variable. 0 on success. + * @see "HAL_WriteCANRTRFrame" + */ public static native int writeCANRTRFrameNoThrow(int handle, int length, int apiId); + /** + * 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) + * @see "HAL_StopCANPacketRepeating" + */ public static native void stopCANPacketRepeating(int handle, int apiId); + /** + * Reads a new CAN packet. + * + *

This will only return properly once per packet received. Multiple calls without receiving + * another packet will return false. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param data the packet data (8 bytes) + * @return true on success, false on error + * @see "HAL_ReadCANPacketNew" + */ public static native boolean readCANPacketNew(int handle, int apiId, CANData data); + /** + * 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) + * @return true on success, false on error + * @see "HAL_ReadCANPacketLatest" + */ public static native boolean readCANPacketLatest(int handle, int apiId, CANData data); + /** + * Reads a CAN packet. The will return the last packet received until the packet is older then the + * requested timeout. Then it will return false. + * + * @param handle the CAN handle + * @param apiId the ID to read (0-1023) + * @param timeoutMs the timeout time for the packet + * @param data the packet data (8 bytes) + * @return true on success, false on error + * @see "HAL_ReadCANPacketTimeout" + */ public static native boolean readCANPacketTimeout( int handle, int apiId, int timeoutMs, CANData data); } diff --git a/hal/src/main/java/edu/wpi/first/hal/CTREPCMJNI.java b/hal/src/main/java/edu/wpi/first/hal/CTREPCMJNI.java index e94b183a44..b657da592e 100644 --- a/hal/src/main/java/edu/wpi/first/hal/CTREPCMJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/CTREPCMJNI.java @@ -4,48 +4,221 @@ package edu.wpi.first.hal; +/** + * CTRE Pneumatic Control Module (PCM) Functions. + * + * @see "CTREPCM.h" + */ public class CTREPCMJNI extends JNIWrapper { + /** + * Initializes a PCM. + * + * @param module the CAN ID to initialize + * @return the created PH handle + * @see "HAL_InitializeCTREPCM" + */ public static native int initialize(int module); + /** + * Frees a PCM handle. + * + * @param handle the PCMhandle + * @see "HAL_FreeCTREPCM" + */ public static native void free(int handle); + /** + * Checks if a solenoid channel number is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + */ public static native boolean checkSolenoidChannel(int channel); + /** + * Get whether compressor is turned on. + * + * @param handle the PCM handle + * @return true if the compressor is turned on + * @see "HAL_GetCTREPCMCompressor" + */ public static native boolean getCompressor(int handle); + /** + * Enables the compressor closed loop control using the digital pressure switch. The compressor + * will turn on when the pressure switch indicates that the system is not full, and will turn off + * when the pressure switch indicates that the system is full. + * + * @param handle the PCM handle + * @param enabled true to enable closed loop control + * @see "HAL_SetCTREPCMClosedLoopControl" + */ public static native void setClosedLoopControl(int handle, boolean enabled); + /** + * Get whether the PCM closed loop control is enabled. + * + * @param handle the PCM handle + * @return True if closed loop control is enabled, otherwise false. + */ public static native boolean getClosedLoopControl(int handle); + /** + * Returns the state of the pressure switch. + * + * @param handle the PCM handle + * @return True if pressure switch indicates that the system is full, otherwise false. + * @see "HAL_GetCTREPCMPressureSwitch" + */ public static native boolean getPressureSwitch(int handle); + /** + * Returns the current drawn by the compressor. + * + * @param handle the PCM handle + * @return The current drawn by the compressor in amps. + * @see "HAL_GetCTREPCMCompressorCurrent" + */ public static native double getCompressorCurrent(int handle); + /** + * Return whether the compressor current is currently too high. + * + * @param handle the PCM handle + * @return True if the compressor current is too high, otherwise false. + * @see getCompressorCurrentTooHighStickyFault + * @see "HAL_GetCTREPCMCompressorCurrentTooHighFault" + */ public static native boolean getCompressorCurrentTooHighFault(int handle); + /** + * Returns whether the compressor current has been too high since sticky faults were last cleared. + * This fault is persistent and can be cleared by clearAllStickyFaults() + * + * @param handle the PCM handle + * @return True if the compressor current has been too high since sticky faults were last cleared. + * @see getCompressorCurrentTooHighFault + * @see "HAL_GetCTREPCMCompressorCurrentTooHighStickyFault(" + */ public static native boolean getCompressorCurrentTooHighStickyFault(int handle); + /** + * Returns whether the compressor is currently shorted. + * + * @param handle the PCM handle + * @return True if the compressor is currently shorted, otherwise false. + * @see getCompressorCurrentTooHighStickyFault + * @see "HAL_GetCTREPCMCompressorShortedStickyFault" + */ public static native boolean getCompressorShortedFault(int handle); + /** + * Returns whether the compressor has been shorted since sticky faults were last cleared. This + * fault is persistent and can be cleared by clearAllStickyFaults() + * + * @param handle the PCM handle + * @return True if the compressor has been shorted since sticky faults were last cleared, + * otherwise false. + * @see getCompressorShortedFault + * @see "HAL_GetCTREPCMCompressorShortedFault" + */ public static native boolean getCompressorShortedStickyFault(int handle); + /** + * Returns whether the compressor is currently disconnected. + * + * @param handle the PCM handle + * @return True if compressor is currently disconnected, otherwise false. + * @see getCompressorShortedStickyFault + * @see "HAL_GetCTREPCMCompressorNotConnectedFault" + */ public static native boolean getCompressorNotConnectedFault(int handle); + /** + * Returns whether the compressor has been disconnected since sticky faults were last cleared. + * This fault is persistent and can be cleared by clearAllStickyFaults() + * + * @param handle the PCM handle + * @return True if the compressor has been disconnected since sticky faults were last cleared, + * otherwise false. + * @see getCompressorNotConnectedFault + * @see "HAL_GetCTREPCMCompressorNotConnectedStickyFault" + */ public static native boolean getCompressorNotConnectedStickyFault(int handle); + /** + * Gets a bitmask of solenoid values. + * + * @param handle the PCM handle + * @return solenoid values + * @see "HAL_GetCTREPCMSolenoids" + */ public static native int getSolenoids(int handle); + /** + * Sets solenoids on a pneumatics module. + * + * @param handle the PCM handle + * @param mask bitmask to set + * @param values solenoid values + * @see "HAL_SetCTREPCMSolenoids" + */ public static native void setSolenoids(int handle, int mask, int values); + /** + * Get a bitmask of disabled solenoids. + * + * @param handle the PCM handle + * @return bitmask of disabled solenoids + * @see "HAL_GetCTREPCMSolenoidDisabledList" + */ public static native int getSolenoidDisabledList(int handle); + /** + * Returns whether the solenoid is currently reporting a voltage fault. + * + * @param handle the PCM handle + * @return True if solenoid is reporting a fault, otherwise false. + * @see getSolenoidVoltageStickyFault + * @see "HAL_GetCTREPCMSolenoidVoltageFault" + */ public static native boolean getSolenoidVoltageFault(int handle); + /** + * Returns whether the solenoid has reported a voltage fault since sticky faults were last + * cleared. This fault is persistent and can be cleared by clearAllStickyFaults() + * + * @param handle the PCM handle + * @return True if solenoid is reporting a fault, otherwise false. + * @see getSolenoidVoltageFault + * @see "HAL_GetCTREPCMSolenoidVoltageStickyFault" + */ public static native boolean getSolenoidVoltageStickyFault(int handle); + /** + * Clears all sticky faults on this device. + * + * @param handle the PCM handle + * @see "HAL_ClearAllCTREPCMStickyFaults" + */ public static native void clearAllStickyFaults(int handle); + /** + * Fire a single solenoid shot. + * + * @param handle the PCM handle + * @param index solenoid index + * @see "HAL_FireCTREPCMOneShot" + */ public static native void fireOneShot(int handle, int index); + /** + * Set the duration for a single solenoid shot. + * + * @param handle the PCM handle + * @param index solenoid index + * @param durMs shot duration in ms + * @see "HAL_SetCTREPCMOneShotDuration" + */ public static native void setOneShotDuration(int handle, int index, int durMs); } diff --git a/hal/src/main/java/edu/wpi/first/hal/ConstantsJNI.java b/hal/src/main/java/edu/wpi/first/hal/ConstantsJNI.java index aba5b33463..48434499ff 100644 --- a/hal/src/main/java/edu/wpi/first/hal/ConstantsJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/ConstantsJNI.java @@ -4,6 +4,17 @@ package edu.wpi.first.hal; +/** + * Constants HAL JNI functions. + * + * @see "hal/Constants.h" + */ public class ConstantsJNI extends JNIWrapper { + /** + * Gets the number of FPGA system clock ticks per microsecond. + * + * @return the number of clock ticks per microsecond + * @see "HAL_GetSystemClockTicksPerMicrosecond" + */ public static native int getSystemClockTicksPerMicrosecond(); } diff --git a/hal/src/main/java/edu/wpi/first/hal/CounterJNI.java b/hal/src/main/java/edu/wpi/first/hal/CounterJNI.java index 8b95228b9b..ebc4cffe26 100644 --- a/hal/src/main/java/edu/wpi/first/hal/CounterJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/CounterJNI.java @@ -6,59 +6,277 @@ package edu.wpi.first.hal; import java.nio.IntBuffer; +/** + * Counter HAL JNI functions. + * + * @see "hal/Counter.h" + */ public class CounterJNI extends JNIWrapper { public static final int TWO_PULSE = 0; public static final int SEMI_PERIOD = 1; public static final int PULSE_LENGTH = 2; public static final int EXTERNAL_DIRECTION = 3; + /** + * Initializes a counter. + * + * @param mode the counter mode + * @param index the compressor index (output) + * @return the created handle + * @see "HAL_InitializeCounter" + */ public static native int initializeCounter(int mode, IntBuffer index); + /** + * Frees a counter. + * + * @param counterHandle the counter handle + * @see "HAL_FreeCounter" + */ public static native void freeCounter(int counterHandle); + /** + * Sets the average sample size of a counter. + * + * @param counterHandle the counter handle + * @param size the size of samples to average + * @see "HAL_SetCounterAverageSize" + */ public static native void setCounterAverageSize(int counterHandle, int size); + /** + * 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 or a + * HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog trigger + * @see "HAL_SetCounterUpSource" + */ public static native void setCounterUpSource( int counterHandle, int digitalSourceHandle, int analogTriggerType); + /** + * 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 + * @see "HAL_SetCounterUpSourceEdge" + */ public static native void setCounterUpSourceEdge( int counterHandle, boolean risingEdge, boolean fallingEdge); + /** + * Disables the up counting source to the counter. + * + * @param counterHandle the counter handle + * @see "HAL_ClearCounterUpSource" + */ public static native void clearCounterUpSource(int counterHandle); + /** + * 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 or a + * HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog trigger + * @see "HAL_SetCounterDownSource" + */ public static native void setCounterDownSource( int counterHandle, int digitalSourceHandle, int analogTriggerType); + /** + * 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 + * @see "HAL_SetCounterDownSourceEdge" + */ public static native void setCounterDownSourceEdge( int counterHandle, boolean risingEdge, boolean fallingEdge); + /** + * Disables the down counting source to the counter. + * + * @param counterHandle the counter handle + * @see "HAL_ClearCounterDownSource" + */ public static native void clearCounterDownSource(int counterHandle); + /** + * Sets standard up / down counting mode on this counter. + * + *

Up and down counts are sourced independently from two inputs. + * + * @param counterHandle the counter handle + * @see "HAL_SetCounterUpDownMode" + */ public static native void setCounterUpDownMode(int counterHandle); + /** + * 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 + * @see "HAL_SetCounterExternalDirectionMode" + */ public static native void setCounterExternalDirectionMode(int counterHandle); + /** + * 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 + * @see "HAL_SetCounterSemiPeriodMode" + */ public static native void setCounterSemiPeriodMode(int counterHandle, boolean highSemiPeriod); + /** + * 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 + * (seconds) + * @see "HAL_SetCounterPulseLengthMode" + */ public static native void setCounterPulseLengthMode(int counterHandle, double threshold); + /** + * 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) + * @see "HAL_GetCounterSamplesToAverage" + */ public static native int getCounterSamplesToAverage(int counterHandle); + /** + * 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 + * @see "HAL_SetCounterSamplesToAverage" + */ public static native void setCounterSamplesToAverage(int counterHandle, int samplesToAverage); + /** + * 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 + * @see "HAL_ResetCounter" + */ public static native void resetCounter(int counterHandle); + /** + * 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 + * @see "HAL_GetCounter" + */ public static native int getCounter(int counterHandle); + /** + * 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 counterHandle the counter handle + * @return the period of the last two pulses in units of seconds + * @see "HAL_GetCounterPeriod" + */ public static native double getCounterPeriod(int counterHandle); + /** + * 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 HAL_GetCounterStopped method. + * + * @param counterHandle the counter handle + * @param maxPeriod the maximum period where the counted device is considered moving in seconds + * @see "HAL_SetCounterMaxPeriod" + */ public static native void setCounterMaxPeriod(int counterHandle, double maxPeriod); + /** + * 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 + * @see "HAL_SetCounterUpdateWhenEmpty" + */ public static native void setCounterUpdateWhenEmpty(int counterHandle, boolean enabled); + /** + * 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. + * + * @param counterHandle the counter handle + * @return true if the most recent counter period exceeds the MaxPeriod value set by SetMaxPeriod + * @see "HAL_GetCounterStopped" + */ public static native boolean getCounterStopped(int counterHandle); + /** + * Gets the last direction the counter value changed. + * + * @param counterHandle the counter handle + * @return the last direction the counter value changed + * @see "HAL_GetCounterDirection" + */ public static native boolean getCounterDirection(int counterHandle); + /** + * 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. + * @see "HAL_SetCounterReverseDirection" + */ public static native void setCounterReverseDirection(int counterHandle, boolean reverseDirection); } diff --git a/hal/src/main/java/edu/wpi/first/hal/DIOJNI.java b/hal/src/main/java/edu/wpi/first/hal/DIOJNI.java index 689a95e7f8..3330f4ad3c 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DIOJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DIOJNI.java @@ -4,42 +4,178 @@ package edu.wpi.first.hal; +/** + * Digital Input/Output (IO) JNI Functions. + * + * @see "hal/DIO.h" + */ public class DIOJNI extends JNIWrapper { + /** + * Creates a new instance of a digital port. + * + * @param halPortHandle the port handle to create from + * @param input true for input, false for output + * @return the created digital handle + * @see "HAL_InitializeDIOPort" + */ public static native int initializeDIOPort(int halPortHandle, boolean input); + /** + * Checks if a DIO channel is valid. + * + * @param channel the channel number to check + * @return true if the channel is valid, otherwise false + * @see "HAL_CheckDIOChannel" + */ public static native boolean checkDIOChannel(int channel); + /** + * Frees a DIO port. + * + * @param dioPortHandle the DIO channel handle + * @see "HAL_FreeDIOPort" + */ public static native void freeDIOPort(int dioPortHandle); + /** + * Indicates the DIO channel is used by a simulated device. + * + * @param handle the DIO channel handle + * @param device simulated device handle + * @see "HAL_SetDIOSimDevice" + */ public static native void setDIOSimDevice(int handle, int device); + /** + * Writes a digital value to a DIO channel. + * + * @param dioPortHandle the digital port handle + * @param value the state to set the digital channel (if it is configured as an output) + * @see "HAL_SetDIO" + */ public static native void setDIO(int dioPortHandle, boolean value); + /** + * Sets the direction of a DIO channel. + * + * @param dioPortHandle the digital port handle + * @param input true to set input, false for output + * @see "HAL_SetDIODirection" + */ public static native void setDIODirection(int dioPortHandle, boolean input); + /** + * Reads a digital value from a DIO channel. + * + * @param dioPortHandle the digital port handle + * @return the state of the specified channel + * @see "HAL_GetDIO" + */ public static native boolean getDIO(int dioPortHandle); + /** + * Reads the direction of a DIO channel. + * + * @param dioPortHandle the digital port handle + * @return true for input, false for output + * @see "HAL_GetDIODirection" + */ public static native boolean getDIODirection(int dioPortHandle); + /** + * 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 dioPortHandle the digital port handle + * @param pulseLengthSeconds the active length of the pulse (in seconds) + * @see "HAL_Pulse" + */ public static native void pulse(int dioPortHandle, double pulseLengthSeconds); + /** + * Generates a single digital pulse on multiple channels. + * + *

Write a pulse to the channels enabled by the mask. There can only be a single pulse going at + * any time. + * + * @param channelMask the channel mask + * @param pulseLengthSeconds the active length of the pulse (in seconds) + * @see "HAL_PulseMultiple" + */ public static native void pulseMultiple(long channelMask, double pulseLengthSeconds); + /** + * Checks a DIO line to see if it is currently generating a pulse. + * + * @param dioPortHandle the digital port handle + * @return true if a pulse is in progress, otherwise false + * @see "HAL_IsPulsing" + */ public static native boolean isPulsing(int dioPortHandle); + /** + * Checks if any DIO line is currently generating a pulse. + * + * @return true if a pulse on some line is in progress + * @see "HAL_IsAnyPulsing" + */ public static native boolean isAnyPulsing(); public static native short getLoopTiming(); + /** + * Allocates a DO PWM Generator. + * + * @return the allocated digital PWM handle + */ public static native int allocateDigitalPWM(); + /** + * Frees the resource associated with a DO PWM generator. + * + * @param pwmGenerator the digital PWM handle + * @see "HAL_FreeDigitalPWM" + */ public static native void freeDigitalPWM(int pwmGenerator); + /** + * Changes the frequency of the DO PWM generator. + * + *

The valid range is from 0.6 Hz to 19 kHz. + * + *

The frequency resolution is logarithmic. + * + * @param rate the frequency to output all digital output PWM signals + * @see "HAL_SetDigitalPWMRate" + */ public static native void setDigitalPWMRate(double rate); + /** + * Configures the duty-cycle of the PWM generator. + * + * @param pwmGenerator the digital PWM handle + * @param dutyCycle the percent duty cycle to output [0..1] + * @see "HAL_SetDigitalPWMDutyCycle" + */ public static native void setDigitalPWMDutyCycle(int pwmGenerator, double dutyCycle); + /** + * Configures the digital PWM to be a PPS signal with specified duty cycle. + * + * @param pwmGenerator the digital PWM handle + * @param dutyCycle the percent duty cycle to output [0..1] + * @see "HAL_SetDigitalPWMPPS" + */ public static native void setDigitalPWMPPS(int pwmGenerator, double dutyCycle); + /** + * Configures which DO channel the PWM signal is output on. + * + * @param pwmGenerator the digital PWM handle + * @param channel the channel to output on + * @see "HAL_SetDigitalPWMOutputChannel" + */ public static native void setDigitalPWMOutputChannel(int pwmGenerator, int channel); } diff --git a/hal/src/main/java/edu/wpi/first/hal/DMAJNI.java b/hal/src/main/java/edu/wpi/first/hal/DMAJNI.java index 9a0cfeb5f9..00000d2f2b 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DMAJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DMAJNI.java @@ -4,53 +4,245 @@ package edu.wpi.first.hal; +/** + * DMA HAL JNI functions. + * + * @see "hal/DHA.h" + */ public class DMAJNI extends JNIWrapper { + /** + * Initializes an object for performing DMA transfers. + * + * @return the created dma handle + * @see "HAL_InitializeDMA" + */ public static native int initialize(); + /** + * Frees a DMA object. + * + * @param handle the dma handle + * @see "HAL_FreeDMA" + */ public static native void free(int handle); + /** + * Pauses or unpauses a DMA transfer. + * + *

This can only be called while DMA is running. + * + * @param handle the dma handle + * @param pause true to pause transfers, false to resume. + * @see "HAL_SetDMAPause" + */ public static native void setPause(int handle, boolean pause); + /** + * Sets DMA transfers to occur at a specific timed interval. + * + *

This will remove any external triggers. Only timed or external is supported. + * + *

Only 1 timed period is supported. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param periodSeconds the period to trigger in seconds + * @see "HAL_SetDMATimedTrigger" + */ public static native void setTimedTrigger(int handle, double periodSeconds); + /** + * Sets DMA transfers to occur at a specific timed interval in FPGA cycles. + * + *

This will remove any external triggers. Only timed or external is supported. + * + *

Only 1 timed period is supported + * + *

The FPGA currently runs at 40 MHz, but this can change. + * HAL_GetSystemClockTicksPerMicrosecond can be used to get a computable value for this. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param cycles the period to trigger in FPGA cycles + * @see "HAL_SetDMATimedTriggerCycles" + */ public static native void setTimedTriggerCycles(int handle, int cycles); + /** + * Adds position data for an encoder to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param encoderHandle the encoder to add + * @see "HAL_AddDMAEncoder" + */ public static native void addEncoder(int handle, int encoderHandle); + /** + * Adds timer data for an encoder to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param encoderHandle the encoder to add + * @see "HAL_AddDMAEncoderPeriod" + */ public static native void addEncoderPeriod(int handle, int encoderHandle); + /** + * Adds position data for an counter to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param counterHandle the counter to add + * @see "HAL_AddDMACounter" + */ public static native void addCounter(int handle, int counterHandle); + /** + * Adds timer data for an counter to be collected by DMA. + * + * @param handle the dma handle + * @param counterHandle the counter to add + * @see "HAL_AddDMACounterPeriod" + */ public static native void addCounterPeriod(int handle, int counterHandle); + /** + * Adds a digital source to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param digitalSourceHandle the digital source to add + * @see "HAL_AddDMADigitalSource" + */ public static native void addDigitalSource(int handle, int digitalSourceHandle); + /** + * Adds a duty cycle input to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param dutyCycleHandle the duty cycle input to add + * @see "HAL_AddDMADutyCycle" + */ public static native void addDutyCycle(int handle, int dutyCycleHandle); + /** + * Adds an analog input to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param analogInputHandle the analog input to add + * @see "HAL_AddDMAAnalogInput" + */ public static native void addAnalogInput(int handle, int analogInputHandle); + /** + * Adds averaged data of an analog input to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param analogInputHandle the analog input to add + * @see "HAL_AddDMAAveragedAnalogInput" + */ public static native void addAveragedAnalogInput(int handle, int analogInputHandle); + /** + * Adds accumulator data of an analog input to be collected by DMA. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param analogInputHandle the analog input to add + * @see "HAL_AddDMAAnalogAccumulator" + */ public static native void addAnalogAccumulator(int handle, int analogInputHandle); + /** + * Sets DMA transfers to occur on an external trigger. + * + *

This will remove any timed trigger set. Only timed or external is supported. + * + *

Up to 8 external triggers are currently supported. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @param digitalSourceHandle the digital source handle (either a HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog trigger + * @param rising true to trigger on rising edge + * @param falling true to trigger on falling edge + * @return the index of the trigger + * @see "HAL_SetDMAExternalTrigger" + */ public static native int setExternalTrigger( int handle, int digitalSourceHandle, int analogTriggerType, boolean rising, boolean falling); + /** + * Clear all sensors from the DMA collection list. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @see "HAL_ClearDMASensors" + */ public static native void clearSensors(int handle); + /** + * Clear all external triggers from the DMA trigger list. + * + *

This can only be called if DMA is not started. + * + * @param handle the dma handle + * @see "HAL_ClearDMAExternalTriggers" + */ public static native void clearExternalTriggers(int handle); + /** + * Starts DMA Collection. + * + * @param handle the dma handle + * @param queueDepth the number of objects to be able to queue + * @see "HAL_StartDMA" + */ public static native void startDMA(int handle, int queueDepth); + /** + * Stops DMA Collection. + * + * @param handle the dma handle + * @see "HAL_StopDMA" + */ public static native void stopDMA(int handle); - // 0-21 channelOffsets - // 22: capture size - // 23: triggerChannels (bitflags) - // 24: remaining - // 25: read status + /** + * Reads a DMA sample from the queue. + * + * @param handle the dma handle + * @param timeoutSeconds the time to wait for data to be queued before timing out + * @param buffer the sample object to place data into + * @param sampleStore index 0-21 channelOffsets, index 22: capture size, index 23: triggerChannels + * (bitflags), index 24: remaining, index 25: read status + * @return timestamp of the DMA Sample + */ public static native long readDMA( int handle, double timeoutSeconds, int[] buffer, int[] sampleStore); + /** + * Get the sensor DMA sample. + * + * @param handle the dma handle + * @return The DMA sample + */ public static native DMAJNISample.BaseStore getSensorReadData(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/DigitalGlitchFilterJNI.java b/hal/src/main/java/edu/wpi/first/hal/DigitalGlitchFilterJNI.java index cf0a781d81..9a16984d89 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DigitalGlitchFilterJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DigitalGlitchFilterJNI.java @@ -4,12 +4,59 @@ package edu.wpi.first.hal; +/** + * Digital Glitch Filter JNI functions. + * + * @see "hal/DIO.h" + */ public class DigitalGlitchFilterJNI extends JNIWrapper { + /** + * Writes the filter index from the FPGA. + * + *

Set the filter index used to filter out short pulses. + * + * @param digitalPortHandle 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) + * @see "HAL_SetFilterSelect" + */ public static native void setFilterSelect(int digitalPortHandle, int filterIndex); + /** + * Reads the filter index from the FPGA. + * + *

Gets the filter index used to filter out short pulses. + * + * @param digitalPortHandle the digital port handle + * @return the filter index (Must be in the range 0 - 3, where 0 means "none" and 1 - 3 means + * filter # filterIndex - 1) + * @see "HAL_GetFilterSelect" + */ public static native int getFilterSelect(int digitalPortHandle); + /** + * Sets the filter period for the specified filter index. + * + *

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 complicates the interface. That + * can be changed later. + * + * @param filterIndex the filter index, 0 - 2 + * @param fpgaCycles the number of cycles that the signal must not transition to be counted as a + * transition. + * @see "HAL_SetFilterPeriod" + */ public static native void setFilterPeriod(int filterIndex, int fpgaCycles); + /** + * Gets the filter period for the specified filter index. + * + *

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 complicates the interface. + * + * @param filterIndex the filter index, 0 - 2 + * @return The number of FPGA cycles of the filter period. + * @see "HAL_GetFilterPeriod" + */ public static native int getFilterPeriod(int filterIndex); } diff --git a/hal/src/main/java/edu/wpi/first/hal/DriverStationJNI.java b/hal/src/main/java/edu/wpi/first/hal/DriverStationJNI.java index 3feaee4b19..3c2afa8712 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DriverStationJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DriverStationJNI.java @@ -6,21 +6,88 @@ package edu.wpi.first.hal; import java.nio.ByteBuffer; +/** + * Driver Station JNI Functions. + * + * @see "hal/DriverStation.h" + * @see "hal/FRCUsageReporting.h" + */ public class DriverStationJNI extends JNIWrapper { + /** + * Sets the program starting flag in the DS. + * + *

This is what changes the DS to showing robot code ready. + * + * @see "HAL_ObserveUserProgramStarting" + */ public static native void observeUserProgramStarting(); + /** + * 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 gets called about every 50ms, or the robot will be disabled by the DS. + * + * @see "HAL_ObserveUserProgramDisabled" + */ public static native void observeUserProgramDisabled(); + /** + * 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 gets called about every 50ms, or the robot will be disabled by the DS. + * + * @see "HAL_ObserveUserProgramAutonomous" + */ public static native void observeUserProgramAutonomous(); + /** + * 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 gets called about every 50ms, or the robot will be disabled by the DS. + * + * @see "HAL_ObserveUserProgramTeleop" + */ public static native void observeUserProgramTeleop(); + /** + * 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 gets called about every 50ms, or the robot will be disabled by the DS. + * + * @see "HAL_ObserveUserProgramTest" + */ public static native void observeUserProgramTest(); + /** + * Report the usage of a resource of interest. + * + *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const + * char*) + * + * @param resource one of the values in the tResourceType above. + * @param instanceNumber an index that identifies the resource instance. + * @see "HAL_Report" + */ public static void report(int resource, int instanceNumber) { report(resource, instanceNumber, 0, ""); } + /** + * Report the usage of a resource of interest. + * + *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const + * char*) + * + * @param resource one of the values in the tResourceType above. + * @param instanceNumber an index that identifies the resource instance. + * @param context an optional additional context number for some cases (such as module number). + * Set to 0 to omit. + * @see "HAL_Report" + */ public static void report(int resource, int instanceNumber, int context) { report(resource, instanceNumber, context, ""); } @@ -31,19 +98,36 @@ public class DriverStationJNI extends JNIWrapper { *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const * char*) * - * @param resource one of the values in the tResourceType above (max value 51). + * @param resource one of the values in the tResourceType above. * @param instanceNumber an index that identifies the resource instance. * @param context an optional additional context number for some cases (such as module number). * Set to 0 to omit. * @param feature a string to be included describing features in use on a specific resource. * Setting the same resource more than once allows you to change the feature string. - * @return TODO + * @return the index of the added value in NetComm + * @see "HAL_Report" */ public static native int report(int resource, int instanceNumber, int context, String feature); + /** + * Gets the current control word of the driver station. + * + *

The control word contains the robot state. + * + * @return the control word + * @see "HAL_GetControlWord" + * @see getControlWord for a version easier to parse + */ public static native int nativeGetControlWord(); - @SuppressWarnings("MissingJavadocMethod") + /** + * Gets the current control word of the driver station. + * + *

The control work contains the robot state. + * + * @param controlWord the ControlWord to update + * @see "HAL_GetControlWord" + */ public static void getControlWord(ControlWord controlWord) { int word = nativeGetControlWord(); controlWord.update( @@ -55,6 +139,12 @@ public class DriverStationJNI extends JNIWrapper { ((word >> 5) & 1) != 0); } + /** + * Gets the current alliance station ID. + * + * @return the alliance station ID int + * @see "HAL_GetAllianceStation" + */ private static native int nativeGetAllianceStation(); public static final int kRed1AllianceStation = 0; @@ -64,7 +154,12 @@ public class DriverStationJNI extends JNIWrapper { public static final int kBlue2AllianceStation = 4; public static final int kBlue3AllianceStation = 5; - @SuppressWarnings("MissingJavadocMethod") + /** + * Gets the current alliance station ID. + * + * @return the alliance station ID as AllianceStationID + * @see "HAL_GetAllianceStation" + */ public static AllianceStationID getAllianceStation() { switch (nativeGetAllianceStation()) { case kRed1AllianceStation: @@ -88,32 +183,156 @@ public class DriverStationJNI extends JNIWrapper { public static final int kMaxJoystickPOVs = 12; public static final int kMaxJoysticks = 6; + /** + * Gets the axes of a specific joystick. + * + * @param joystickNum the joystick number + * @param axesArray the axes values + * @return number of joystick axes, or 0 for error + * @see "HAL_GetJoystickAxes" + */ public static native int getJoystickAxes(byte joystickNum, float[] axesArray); + /** + * Gets the axes of a specific joystick. + * + * @param joystickNum the joystick number + * @param rawAxesArray the raw int axes values (0-255) + * @return number of joystick axes, or 0 for error + * @see "HAL_GetJoystickAxes" + */ public static native int getJoystickAxesRaw(byte joystickNum, int[] rawAxesArray); + /** + * Gets the POVs of a specific joystick. + * + * @param joystickNum the joystick number + * @param povsArray the POV values + * @return number of POVs, or 0 for error + * @see "HAL_GetJoystickPOVs" + */ public static native int getJoystickPOVs(byte joystickNum, short[] povsArray); + /** + * Gets the buttons of a specific joystick. + * + * @param joystickNum the joystick number + * @param count the count of buttons + * @return The joystick button values + * @see "HAL_GetJoystickButtons" + */ public static native int getJoystickButtons(byte joystickNum, ByteBuffer count); + /** + * Get all joystick data. + * + * @param axesArray all joystick axes + * @param rawAxesArray all joystick axes as int + * @param povsArray all povs + * @param buttonsAndMetadata array of long joystick axes count, long joystick povs count, long + * jostick buttons count, long joystick buttons values + * @see "HAL_GetAllJoystickData" + */ public static native void getAllJoystickData( float[] axesArray, byte[] rawAxesArray, short[] povsArray, long[] buttonsAndMetadata); + /** + * Set joystick outputs. + * + * @param joystickNum the joystick number + * @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 + * @see "HAL_SetJoystickOutputs" + */ public static native int setJoystickOutputs( byte joystickNum, int outputs, short leftRumble, short rightRumble); + /** + * Gets whether a specific joystick is considered to be an XBox controller. + * + * @param joystickNum the joystick number + * @return 1 if xbox, 0 otherwise + * @see "HAL_GetJoystickIsXbox" + */ public static native int getJoystickIsXbox(byte 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 + * @see "HAL_GetJoystickType" + */ public static native int getJoystickType(byte joystickNum); + /** + * Gets the name of a joystick. + * + *

The returned array must be freed with HAL_FreeJoystickName. + * + * @param joystickNum the joystick number + * @return the joystick name + * @see "HAL_GetJoystickName" + */ public static native String getJoystickName(byte joystickNum); + /** + * 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 + * @see "HAL_GetJoystickAxisType" + */ public static native int getJoystickAxisType(byte joystickNum, byte axis); + /** + * 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 behavior seen on the field. + * + * @return time remaining in current match period (auto or teleop) + * @see "HAL_GetMatchTime" + */ public static native double getMatchTime(); + /** + * Gets info about a specific match. + * + * @param info the match info to populate + * @return the error code, or 0 for success + * @see "HAL_GetMatchInfo" + */ public static native int getMatchInfo(MatchInfoData info); + /** + * 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 error + * @param callStack the callstack of the error + * @param printMsg true to print the error message to stdout as well as to the DS + * @return the error code, or 0 for success + * @see "HAL_SendError" + */ public static native int sendError( boolean isError, int errorCode, @@ -123,14 +342,31 @@ public class DriverStationJNI extends JNIWrapper { String callStack, boolean printMsg); + /** + * Sends a line to the driver station console. + * + * @param line the line to send + * @return the error code, or 0 for success + */ public static native int sendConsoleLine(String line); + /** + * Refresh the DS control word. + * + * @return true if updated + * @see "HAL_RefreshDSData" + */ public static native boolean refreshDSData(); public static native void provideNewDataEventHandle(int handle); public static native void removeNewDataEventHandle(int handle); + /** + * Gets if outputs are enabled by the control system. + * + * @return true if outputs are enabled + */ public static native boolean getOutputsActive(); private DriverStationJNI() {} diff --git a/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java b/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java index f2737d8c7c..1e7dfa0ccc 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java @@ -4,18 +4,78 @@ package edu.wpi.first.hal; +/** + * DutyCycle HAL JNI functions. + * + * @see "DutyCycle.h" + */ public class DutyCycleJNI extends JNIWrapper { + /** + * Initialize a DutyCycle input. + * + * @param digitalSourceHandle the digital source to use (either a Digital Handle or a + * AnalogTrigger Handle) + * @param analogTriggerType the analog trigger type of the source if it is an analog trigger + * @return the created duty cycle handle + * @see "HAL_InitializeDutyCycle" + */ public static native int initialize(int digitalSourceHandle, int analogTriggerType); + /** + * Free a DutyCycle. + * + * @param handle the duty cycle handle + * @see "HAL_FreeDutyCycle" + */ public static native void free(int handle); + /** + * Get the frequency of the duty cycle signal. + * + * @param handle the duty cycle handle + * @return frequency in Hertz + * @see "HAL_GetDutyCycleFrequency" + */ public static native int getFrequency(int handle); + /** + * Get the output ratio of the duty cycle signal. + * + *

0 means always low, 1 means always high. + * + * @param handle the duty cycle handle + * @return output ratio between 0 and 1 + * @see "HAL_GetDutyCycleOutput" + */ public static native double getOutput(int handle); + /** + * Get the raw high time of the duty cycle signal. + * + * @param handle the duty cycle handle + * @return high time of last pulse in nanoseconds + * @see "HAL_GetDutyCycleHighTime" + */ public static native int getHighTime(int handle); + /** + * Get the scale factor of the output. + * + *

An output equal to this value is always high, and then linearly scales down to 0. Divide a + * raw result by this in order to get the percentage between 0 and 1. Used by DMA. + * + * @param handle the duty cycle handle + * @return the output scale factor + * @see "HAL_GetDutyCycleOutputScaleFactor" + */ public static native int getOutputScaleFactor(int handle); + /** + * Get the FPGA index for the DutyCycle. + * + * @param handle the duty cycle handle + * @return the FPGA index + * @see "HAL_GetDutyCycleFPGAIndex" + */ public static native int getFPGAIndex(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/EncoderJNI.java b/hal/src/main/java/edu/wpi/first/hal/EncoderJNI.java index 50ecc91d8b..d219db056b 100644 --- a/hal/src/main/java/edu/wpi/first/hal/EncoderJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/EncoderJNI.java @@ -4,7 +4,24 @@ package edu.wpi.first.hal; +/** + * Encoder JNI Functions. + * + * @see "hal/Encoder.h" + */ public class EncoderJNI extends JNIWrapper { + /** + * Initializes an encoder. + * + * @param digitalSourceHandleA the A source handle (either a digital or analog trigger) + * @param analogTriggerTypeA the analog trigger type of the A source if it is an analog trigger + * @param digitalSourceHandleB the B source handle (either a digital or analog trigger) + * @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 + * @see "HAL_InitializeEncoder" + */ public static native int initializeEncoder( int digitalSourceHandleA, int analogTriggerTypeA, @@ -13,50 +30,249 @@ public class EncoderJNI extends JNIWrapper { boolean reverseDirection, int encodingType); + /** + * Frees an encoder. + * + * @param encoderHandle the encoder handle + * @see "HAL_FreeEncoder" + */ public static native void freeEncoder(int encoderHandle); + /** + * Indicates the encoder is used by a simulated device. + * + * @param handle the encoder handle + * @param device simulated device handle + * @see "HAL_SetEncoderSimDevice" + */ public static native void setEncoderSimDevice(int handle, int device); + /** + * Gets the current counts of the encoder after encoding type scaling. + * + *

This is scaled by the value passed during initialization to encodingType. + * + * @param encoderHandle the encoder handle + * @return the current scaled count + * @see "HAL_GetEncoder" + */ public static native int getEncoder(int encoderHandle); + /** + * Gets the raw counts of the encoder. + * + *

This is not scaled by any values. + * + * @param encoderHandle the encoder handle + * @return the raw encoder count + * @see "HAL_GetEncoderRaw" + */ public static native int getEncoderRaw(int encoderHandle); + /** + * 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 + * @see "HAL_GetEncoderEncodingScale" + */ public static native int getEncodingScaleFactor(int encoderHandle); + /** + * 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 + * @see "HAL_ResetEncoder" + */ public static native void resetEncoder(int encoderHandle); + /** + * 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 + * @return the period of the last two pulses in units of seconds + * @see "HAL_GetEncoderPeriod" + */ public static native double getEncoderPeriod(int encoderHandle); + /** + * 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 getEncoderStopped method. + * + * @param encoderHandle the encoder handle + * @param maxPeriod the maximum period where the counted device is considered moving in seconds + * @see "HAL_SetEncoderMaxPeriod" + */ public static native void setEncoderMaxPeriod(int encoderHandle, double maxPeriod); + /** + * 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 + * @see "HAL_GetEncoderStopped" + */ public static native boolean getEncoderStopped(int encoderHandle); + /** + * Gets the last direction the encoder value changed. + * + * @param encoderHandle the encoder handle + * @return the last direction the encoder value changed + * @see "HAL_GetEncoderDirection" + */ public static native boolean getEncoderDirection(int encoderHandle); + /** + * 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 + * setEncoderDistancePerPulse) + * @see "HAL_GetEncoderDistance" + */ public static native double getEncoderDistance(int encoderHandle); + /** + * 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 + * setEncoderDistancePerPulse, time value is seconds) + * @see "HAL_GetEncoderRate" + */ public static native double getEncoderRate(int encoderHandle); + /** + * Sets the minimum rate to be considered moving by the encoder. + * + *

Units need to match what is set by 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 setEncoderDistancePerPulse, time value is seconds) + * @see "HAL_SetEncoderMinRate" + */ public static native void setEncoderMinRate(int encoderHandle, double minRate); + /** + * 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) + * @see "HAL_SetEncoderDistancePerPulse" + */ public static native void setEncoderDistancePerPulse(int encoderHandle, double distancePerPulse); + /** + * 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. + * @see "HAL_SetEncoderReverseDirection" + */ public static native void setEncoderReverseDirection(int encoderHandle, boolean reverseDirection); + /** + * 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 + * @see "HAL_SetEncoderSamplesToAverage" + */ public static native void setEncoderSamplesToAverage(int encoderHandle, int samplesToAverage); + /** + * Gets the current samples to average value. + * + * @param encoderHandle the encoder handle + * @return the current samples to average value + * @see "HAL_GetEncoderSamplesToAverage" + */ public static native int getEncoderSamplesToAverage(int encoderHandle); + /** + * 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 or a + * HAL_DigitalHandle) + * @param analogTriggerType the analog trigger type if the source is an analog trigger + * @param indexingType the index triggering type + * @see "HAL_SetEncoderIndexSource" + */ public static native void setEncoderIndexSource( int encoderHandle, int digitalSourceHandle, int analogTriggerType, int indexingType); + /** + * Gets the FPGA index of the encoder. + * + * @param encoderHandle the encoder handle + * @return the FPGA index of the encoder + * @see "HAL_GetEncoderFPGAIndex" + */ public static native int getEncoderFPGAIndex(int encoderHandle); + /** + * 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 + * @see "HAL_GetEncoderEncodingScale" + */ public static native int getEncoderEncodingScale(int encoderHandle); + /** + * 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 + * @see "HAL_GetEncoderDecodingScaleFactor" + */ public static native double getEncoderDecodingScaleFactor(int encoderHandle); + /** + * Gets the user set distance per pulse of the encoder. + * + * @param encoderHandle the encoder handle + * @return the set distance per pulse + * @see "HAL_GetEncoderDistancePerPulse" + */ public static native double getEncoderDistancePerPulse(int encoderHandle); + /** + * Gets the encoding type of the encoder. + * + * @param encoderHandle the encoder handle + * @return the encoding type + * @see "HAL_GetEncoderEncodingType" + */ public static native int getEncoderEncodingType(int encoderHandle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/HAL.java b/hal/src/main/java/edu/wpi/first/hal/HAL.java index 2420214913..8389682f83 100644 --- a/hal/src/main/java/edu/wpi/first/hal/HAL.java +++ b/hal/src/main/java/edu/wpi/first/hal/HAL.java @@ -8,18 +8,71 @@ import java.util.ArrayList; import java.util.List; /** - * JNI Wrapper for HAL
- * . + * JNI Wrapper for Hardware Abstraction Layer (HAL). + * + * @see "hal/HALBase.h" + * @see "hal/Main.h" + * @see "hal/FRCUsageReporting.h" */ public final class HAL extends JNIWrapper { + /** + * 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. + * @see "HAL_Initialize" + */ public static native boolean initialize(int timeout, int mode); + /** + * Call this to shut down HAL. + * + *

This must be called at termination of the robot program to avoid potential segmentation + * faults with simulation extensions at exit. + * + * @see "HAL_Shutdown" + */ public static native void shutdown(); + /** + * Returns true if HAL_SetMain() has been called. + * + * @return True if HAL_SetMain() has been called, false otherwise. + * @see "HAL_HasMain" + */ public static native boolean hasMain(); + /** + * Runs the main function provided to HAL_SetMain(). + * + *

If HAL_SetMain() has not been called, simply sleeps until exitMain() is called. + * + * @see "HAL_RunMain" + */ public static native void runMain(); + /** + * Causes HAL_RunMain() to exit. + * + *

If HAL_SetMain() has been called, this calls the exit function provided to that function. + * + * @see "HAL_ExitMain" + */ public static native void exitMain(); private static native void simPeriodicBeforeNative(); @@ -113,24 +166,100 @@ public final class HAL extends JNIWrapper { } } + /** + * Gets if the system is in a browned out state. + * + * @return true if the system is in a low voltage brown out, false otherwise + * @see "HAL_GetBrownedOut" + */ public static native boolean getBrownedOut(); + /** + * Gets if the system outputs are currently active. + * + * @return true if the system outputs are active, false if disabled + * @see "HAL_GetSystemActive" + */ public static native boolean getSystemActive(); + /** + * Gets the current state of the Robot Signal Light (RSL). + * + * @return The current state of the RSL- true if on, false if off + * @see "HAL_GetRSLState" + */ public static native boolean getRSLState(); + /** + * 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 + * @see "HAL_GetPortWithModule" + */ public static native int getPortWithModule(byte module, byte channel); + /** + * 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 + * @see "HAL_GetPort" + */ public static native int getPort(byte channel); + /** + * Report the usage of a resource of interest. + * + *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const + * char*) + * + * @param resource one of the values in the tResourceType above. + * @param instanceNumber an index that identifies the resource instance. + * @see "HAL_Report" + */ public static void report(int resource, int instanceNumber) { report(resource, instanceNumber, 0, ""); } + /** + * Report the usage of a resource of interest. + * + *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const + * char*) + * + * @param resource one of the values in the tResourceType above. + * @param instanceNumber an index that identifies the resource instance. + * @param context an optional additional context number for some cases (such as module number). + * Set to 0 to omit. + * @see "HAL_Report" + */ public static void report(int resource, int instanceNumber, int context) { report(resource, instanceNumber, context, ""); } + /** + * Report the usage of a resource of interest. + * + *

Original signature: uint32_t report(tResourceType, uint8_t, uint8_t, const + * char*) + * + * @param resource one of the values in the tResourceType above. + * @param instanceNumber an index that identifies the resource instance. + * @param context an optional additional context number for some cases (such as module number). + * Set to 0 to omit. + * @param feature a string to be included describing features in use on a specific resource. + * Setting the same resource more than once allows you to change the feature string. + * @return the index of the added value in NetComm + * @see "HAL_Report" + */ public static int report(int resource, int instanceNumber, int context, String feature) { return DriverStationJNI.report(resource, instanceNumber, context, feature); } diff --git a/hal/src/main/java/edu/wpi/first/hal/HALUtil.java b/hal/src/main/java/edu/wpi/first/hal/HALUtil.java index 7c0f41a2f2..e9e572e03d 100644 --- a/hal/src/main/java/edu/wpi/first/hal/HALUtil.java +++ b/hal/src/main/java/edu/wpi/first/hal/HALUtil.java @@ -4,6 +4,11 @@ package edu.wpi.first.hal; +/** + * Hardware Abstraction Layer (HAL) Utilities JNI Functions. + * + * @see "hal/HALBase.h" + */ public final class HALUtil extends JNIWrapper { public static final int NULL_PARAMETER = -1005; public static final int SAMPLE_RATE_TOO_HIGH = 1001; @@ -18,26 +23,100 @@ public final class HALUtil extends JNIWrapper { public static final int RUNTIME_ROBORIO2 = 1; public static final int RUNTIME_SIMULATION = 2; + /** + * Returns the FPGA Version number. + * + *

For now, expect this to be competition year. + * + * @return FPGA Version number. + * @see "HAL_GetFPGAVersion" + */ public static native short getFPGAVersion(); + /** + * 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. + * @see "HAL_GetFPGARevision" + */ public static native int getFPGARevision(); + /** + * Returns the roboRIO serial number. + * + * @return The roboRIO serial number. + * @see "HAL_GetSerialNumber" + */ public static native String getSerialNumber(); + /** + * Returns the comments from the roboRIO web interface. + * + * @return The comments string. + * @see "HAL_GetComments" + */ public static native String getComments(); + /** + * Reads the microsecond-resolution timer on the FPGA. + * + * @return The current time in microseconds according to the FPGA (since FPGA reset). + */ public static native long getFPGATime(); + /** + * Returns the runtime type of the HAL. + * + * @return HAL Runtime Type + * @see RUNTIME_ROBORIO + * @see RUNTIME_ROBORIO2 + * @see RUNTIME_SIMULATION + * @see "HAL_GetRuntimeType" + */ public static native int getHALRuntimeType(); + /** + * Gets the state of the "USER" button on the roboRIO. + * + * @return true if the button is currently pressed down + * @see "HAL_GetFPGAButton" + */ public static native boolean getFPGAButton(); + /** + * 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. + * @see "HAL_GetErrorMessage" + */ public static native String getHALErrorMessage(int code); + /** + * Get the last HAL error code. + * + * @return error code + */ public static native int getHALErrno(); + /** + * Returns the textual description of the system error code. + * + * @param errno errno to get description of + * @return description of errno + * @see "std:strerror" + */ public static native String getHALstrerror(int errno); + /** + * Gets the error message for the last HAL error. + * + * @return the error message for the code. + */ public static String getHALstrerror() { return getHALstrerror(getHALErrno()); } diff --git a/hal/src/main/java/edu/wpi/first/hal/I2CJNI.java b/hal/src/main/java/edu/wpi/first/hal/I2CJNI.java index 63f32a0bf5..90e8ddb4d8 100644 --- a/hal/src/main/java/edu/wpi/first/hal/I2CJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/I2CJNI.java @@ -6,9 +6,38 @@ package edu.wpi.first.hal; import java.nio.ByteBuffer; +/** + * I2C HAL JNI functions. + * + * @see "I2C.h" + */ public class I2CJNI extends JNIWrapper { + /** + * 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. + * @see "HAL_InitializeI2C" + */ public static native void i2CInitialize(int port); + /** + * 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 address The address of the register on the device to be read/written. + * @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. + * @param receiveSize Number of bytes to read from the device. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_TransactionI2C" + */ public static native int i2CTransaction( int port, byte address, @@ -17,6 +46,21 @@ public class I2CJNI extends JNIWrapper { ByteBuffer dataReceived, byte receiveSize); + /** + * 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 address The address of the register on the device to be read/written. + * @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. + * @param receiveSize Number of bytes to read from the device. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_TransactionI2C" + */ public static native int i2CTransactionB( int port, byte address, @@ -25,14 +69,70 @@ public class I2CJNI extends JNIWrapper { byte[] dataReceived, byte receiveSize); + /** + * Executes a write transaction with the device. + * + *

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 address The address of the register on the device to be written. + * @param dataToSend The byte to write to the register on the device. + * @param sendSize Number of bytes to send. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_WriteI2C" + */ public static native int i2CWrite(int port, byte address, ByteBuffer dataToSend, byte sendSize); + /** + * Executes a write transaction with the device. + * + *

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 address The address of the register on the device to be written. + * @param dataToSend The byte to write to the register on the device. + * @param sendSize Number of bytes to send. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_WriteI2C" + */ public static native int i2CWriteB(int port, byte address, byte[] dataToSend, byte sendSize); + /** + * Executes a read transaction with the 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 address The register to read first in the transaction. + * @param dataReceived A ByteBuffer to store the data read from the device. + * @param receiveSize The number of bytes to read in the transaction. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_ReadI2C" + */ public static native int i2CRead( int port, byte address, ByteBuffer dataReceived, byte receiveSize); + /** + * Executes a read transaction with the 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 address The register to read first in the transaction. + * @param dataReceived A byte array to store the data read from the device. + * @param receiveSize The number of bytes to read in the transaction. + * @return >= 0 on success or -1 on transfer abort. + * @see "HAL_ReadI2C" + */ public static native int i2CReadB(int port, byte address, byte[] dataReceived, byte receiveSize); + /** + * Closes an I2C port. + * + * @param port The I2C port, 0 for the on-board, 1 for the MXP. + * @see "HAL_CloseI2C" + */ public static native void i2CClose(int port); } diff --git a/hal/src/main/java/edu/wpi/first/hal/InterruptJNI.java b/hal/src/main/java/edu/wpi/first/hal/InterruptJNI.java index 7dc2e6dc6d..c60543566b 100644 --- a/hal/src/main/java/edu/wpi/first/hal/InterruptJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/InterruptJNI.java @@ -4,28 +4,113 @@ package edu.wpi.first.hal; +/** + * Interrupt HAL JNI functions. + * + * @see "hal/Interrupts.h" + */ public class InterruptJNI extends JNIWrapper { public static final int HalInvalidHandle = 0; + /** + * Initializes an interrupt. + * + * @return the created interrupt handle + * @see "HAL_InitializeInterrupts" + */ public static native int initializeInterrupts(); + /** + * Frees an interrupt. + * + * @param interruptHandle the interrupt handle + * @see "HAL_CleanInterrupts" + */ public static native void cleanInterrupts(int interruptHandle); + /** + * 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 + * @see "HAL_WaitForInterrupt" + */ public static native long waitForInterrupt( int interruptHandle, double timeout, boolean ignorePrevious); + /** + * Waits for any interrupt covered by the mask to occur. + * + * @param interruptHandle the interrupt handle to use for the context + * @param mask the mask of interrupts to wait for + * @param timeout timeout in seconds + * @param ignorePrevious if true, ignore interrupts that happened before waitForInterrupt was + * called + * @return the mask of interrupts that fired + * @see "HAL_WaitForMultipleInterrupts" + */ public static native long waitForMultipleInterrupts( int interruptHandle, long mask, double timeout, boolean ignorePrevious); + /** + * Returns the timestamp for the rising interrupt that occurred most recently. + * + *

This is in the same time domain as getFPGATime(). It only contains the bottom 32 bits of the + * timestamp. If your robot has been running for over 1 hour, you will need to fill in the upper + * 32 bits yourself. + * + * @param interruptHandle the interrupt handle + * @return timestamp in microseconds since FPGA Initialization + */ public static native long readInterruptRisingTimestamp(int interruptHandle); + /** + * Returns the timestamp for the falling interrupt that occurred most recently. + * + *

This is in the same time domain as getFPGATime(). It only contains the bottom 32 bits of the + * timestamp. If your robot has been running for over 1 hour, you will need to fill in the upper + * 32 bits yourself. + * + * @param interruptHandle the interrupt handle + * @return timestamp in microseconds since FPGA Initialization + */ public static native long readInterruptFallingTimestamp(int interruptHandle); + /** + * Requests interrupts on a specific digital source. + * + * @param interruptHandle the interrupt handle + * @param digitalSourceHandle the digital source handle (either a HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param analogTriggerType the trigger type if the source is an AnalogTrigger + * @see "HAL_RequestInterrupts" + */ public static native void requestInterrupts( int interruptHandle, int digitalSourceHandle, int analogTriggerType); + /** + * 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 + * @see "HAL_SetInterruptUpSourceEdge" + */ public static native void setInterruptUpSourceEdge( int interruptHandle, boolean risingEdge, boolean fallingEdge); + /** + * Releases a waiting interrupt. + * + *

This will release both rising and falling waiters. + * + * @param interruptHandle the interrupt handle to release + * @see "HAL_ReleaseWaitingInterrupt" + */ public static native void releaseWaitingInterrupt(int interruptHandle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/NotifierJNI.java b/hal/src/main/java/edu/wpi/first/hal/NotifierJNI.java index 648e8a2671..5620f032de 100644 --- a/hal/src/main/java/edu/wpi/first/hal/NotifierJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/NotifierJNI.java @@ -9,22 +9,34 @@ package edu.wpi.first.hal; * *

This class is not meant for direct use by teams. Instead, the edu.wpi.first.wpilibj.Notifier * class, which corresponds to the C++ Notifier class, should be used. + * + * @see "hal/Notifier.h" */ public class NotifierJNI extends JNIWrapper { /** - * Initializes the notifier. + * Initializes a notifier. * - * @return True on success. + *

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 + * @see "HAL_InitializeNotifier" */ public static native int initializeNotifier(); /** * Sets the HAL notifier thread priority. * + *

The HAL notifier thread is responsible for managing the FPGA's notifier interrupt and waking + * up user's Notifiers when it's their time to run. Giving the HAL notifier thread real-time + * priority helps ensure the user's real-time Notifiers, if any, are notified to run in a timely + * manner. + * * @param realTime Set to true to set a real-time priority, false for standard priority. * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being * highest. For non-real-time, this is forced to 0. See "man 7 sched" for more details. * @return True on success. + * @see "HAL_SetNotifierThreadPriority" */ public static native boolean setHALThreadPriority(boolean realTime, int priority); @@ -33,44 +45,60 @@ public class NotifierJNI extends JNIWrapper { * * @param notifierHandle Notifier handle. * @param name Notifier name. + * @see "HAL_SetNotifierName" */ public static native void setNotifierName(int notifierHandle, String name); /** - * Wakes up the waiter with time=0. Note: after this function is called, all calls to - * waitForNotifierAlarm() will immediately start returning 0. + * Stops a notifier from running. * - * @param notifierHandle Notifier handle. + *

This will cause any call into waitForNotifierAlarm to return with time = 0. + * + * @param notifierHandle the notifier handle + * @see "HAL_StopNotifier" */ public static native void stopNotifier(int notifierHandle); /** - * Deletes the notifier object when we are done with it. + * Cleans a notifier. * - * @param notifierHandle Notifier handle. + *

Note this also stops a notifier if it is already running. + * + * @param notifierHandle the notifier handle + * @see "HAL_CleanNotifier" */ public static native void cleanNotifier(int notifierHandle); /** - * Sets the notifier to wake up the waiter at triggerTime microseconds. + * Updates the trigger time for a notifier. * - * @param notifierHandle Notifier handle. - * @param triggerTime Trigger time in microseconds. + *

Note that this time is an absolute time relative to getFPGATime() + * + * @param notifierHandle the notifier handle + * @param triggerTime the updated trigger time + * @see "HAL_UpdateNotifierAlarm" */ public static native void updateNotifierAlarm(int notifierHandle, long triggerTime); /** - * Cancels any pending wakeups set by updateNotifierAlarm(). Does NOT wake up any waiters. + * Cancels the next notifier alarm. * - * @param notifierHandle Notifier handle. + *

This does not cause waitForNotifierAlarm to return. + * + * @param notifierHandle the notifier handle + * @see "HAL_CancelNotifierAlarm" */ public static native void cancelNotifierAlarm(int notifierHandle); /** - * Block until woken up by an alarm (or stop). + * Waits for the next alarm for the specific notifier. * - * @param notifierHandle Notifier handle. - * @return Time when woken up. + *

This is a blocking call until either the time elapses or stopNotifier gets called. If the + * latter occurs, this function will return zero and any loops using this function should exit. + * Failing to do so can lead to use-after-frees. + * + * @param notifierHandle the notifier handle + * @return the FPGA time the notifier returned */ public static native long waitForNotifierAlarm(int notifierHandle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/PortsJNI.java b/hal/src/main/java/edu/wpi/first/hal/PortsJNI.java index b4bd6cf082..20f9b42110 100644 --- a/hal/src/main/java/edu/wpi/first/hal/PortsJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/PortsJNI.java @@ -4,48 +4,185 @@ package edu.wpi.first.hal; +/** + * Ports HAL JNI functions. + * + * @see "hal/Ports.h" + */ public class PortsJNI extends JNIWrapper { + /** + * Gets the number of analog accumulators in the current system. + * + * @return the number of analog accumulators + * @see "HAL_GetNumAccumulators" + */ public static native int getNumAccumulators(); + /** + * Gets the number of analog triggers in the current system. + * + * @return the number of analog triggers + * @see "HAL_GetNumAnalogTriggers" + */ public static native int getNumAnalogTriggers(); + /** + * Gets the number of analog inputs in the current system. + * + * @return the number of analog inputs + * @see "HAL_GetNumAnalogInputs" + */ public static native int getNumAnalogInputs(); + /** + * Gets the number of analog outputs in the current system. + * + * @return the number of analog outputs + * @see "HAL_GetNumAnalogOutputs" + */ public static native int getNumAnalogOutputs(); + /** + * Gets the number of counters in the current system. + * + * @return the number of counters + * @see "HAL_GetNumCounters" + */ public static native int getNumCounters(); + /** + * Gets the number of digital headers in the current system. + * + * @return the number of digital headers + * @see "HAL_GetNumDigitalHeaders" + */ public static native int getNumDigitalHeaders(); + /** + * Gets the number of PWM headers in the current system. + * + * @return the number of PWM headers + * @see "HAL_GetNumPWMHeaders" + */ public static native int getNumPWMHeaders(); + /** + * Gets the number of digital channels in the current system. + * + * @return the number of digital channels + * @see "HAL_GetNumDigitalChannels" + */ public static native int getNumDigitalChannels(); + /** + * Gets the number of PWM channels in the current system. + * + * @return the number of PWM channels + * @see "HAL_GetNumPWMChannels" + */ public static native int getNumPWMChannels(); + /** + * Gets the number of digital IO PWM outputs in the current system. + * + * @return the number of digital IO PWM outputs + * @see "HAL_GetNumDigitalPWMOutputs" + */ public static native int getNumDigitalPWMOutputs(); + /** + * Gets the number of quadrature encoders in the current system. + * + * @return the number of quadrature encoders + * @see "HAL_GetNumEncoders" + */ public static native int getNumEncoders(); + /** + * Gets the number of interrupts in the current system. + * + * @return the number of interrupts + * @see "HAL_GetNumInterrupts" + */ public static native int getNumInterrupts(); + /** + * Gets the number of relay channels in the current system. + * + * @return the number of relay channels + * @see "HAL_GetNumRelayChannels" + */ public static native int getNumRelayChannels(); + /** + * Gets the number of relay headers in the current system. + * + * @return the number of relay headers + * @see "HAL_GetNumRelayHeaders" + */ public static native int getNumRelayHeaders(); + /** + * Gets the number of PCM modules in the current system. + * + * @return the number of PCM modules + * @see "HAL_GetNumCTREPCMModules" + */ public static native int getNumCTREPCMModules(); + /** + * Gets the number of solenoid channels in the current system. + * + * @return the number of solenoid channels + * @see "HAL_GetNumCTRESolenoidChannels" + */ public static native int getNumCTRESolenoidChannels(); + /** + * Gets the number of PDP modules in the current system. + * + * @return the number of PDP modules + * @see "HAL_GetNumCTREPDPModules" + */ public static native int getNumCTREPDPModules(); + /** + * Gets the number of PDP channels in the current system. + * + * @return the number of PDP channels + * @see "HAL_GetNumCTREPDPChannels" + */ public static native int getNumCTREPDPChannels(); + /** + * Gets the number of PDH modules in the current system. + * + * @return the number of PDH modules + * @see "HAL_GetNumREVPDHModules" + */ public static native int getNumREVPDHModules(); + /** + * Gets the number of PDH channels in the current system. + * + * @return the number of PDH channels + * @see "HAL_GetNumREVPDHChannels" + */ public static native int getNumREVPDHChannels(); + /** + * Gets the number of PH modules in the current system. + * + * @return the number of PH modules + * @see "HAL_GetNumREVPHModules" + */ public static native int getNumREVPHModules(); + /** + * Gets the number of PH channels in the current system. + * + * @return the number of PH channels + * @see "HAL_GetNumREVPHChannels" + */ public static native int getNumREVPHChannels(); } diff --git a/hal/src/main/java/edu/wpi/first/hal/PowerDistributionJNI.java b/hal/src/main/java/edu/wpi/first/hal/PowerDistributionJNI.java index 8280f93a07..bc7060d2b4 100644 --- a/hal/src/main/java/edu/wpi/first/hal/PowerDistributionJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/PowerDistributionJNI.java @@ -4,69 +4,282 @@ package edu.wpi.first.hal; +/** + * Power Distribution JNI Functions. + * + * @see "hal/PowerDistribution.h" + */ public class PowerDistributionJNI extends JNIWrapper { public static final int AUTOMATIC_TYPE = 0; public static final int CTRE_TYPE = 1; public static final int REV_TYPE = 2; public static final int DEFAULT_MODULE = -1; + /** + * Initializes a Power Distribution Panel. + * + * @param module the module number to initialize + * @param type the type of module to initialize + * @return the created PowerDistribution handle + * @see "HAL_InitializePowerDistribution" + */ public static native int initialize(int module, int type); + /** + * Cleans a PowerDistribution module. + * + * @param handle the module handle + * @see "HAL_CleanPowerDistribution" + */ public static native void free(int handle); + /** + * Gets the module number for a specific handle. + * + * @param handle the module handle + * @return the module number + * @see "HAL_GetPowerDistributionModuleNumber" + */ public static native int getModuleNumber(int handle); + /** + * Checks if a PowerDistribution module is valid. + * + * @param module the module to check + * @param type the type of module + * @return true if the module is valid, otherwise false + * @see "HAL_CheckPowerDistributionModule" + */ public static native boolean checkModule(int module, int type); + /** + * Checks if a PowerDistribution channel is valid. + * + * @param handle the module handle + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + * @see "HAL_CheckPowerDistributionChannel" + */ public static native boolean checkChannel(int handle, int channel); + /** + * Gets the type of PowerDistribution module. + * + * @param handle the module handle + * @return the type of module + * @see "HAL_GetPowerDistributionType" + */ public static native int getType(int handle); + /** + * Gets the number of channels for this handle. + * + * @param handle the handle + * @return number of channels + * @see "HAL_GetPowerDistributionNumChannels" + */ public static native int getNumChannels(int handle); + /** + * Gets the temperature of the PowerDistribution. + * + * @param handle the module handle + * @return the module temperature (celsius) + * @see "HAL_GetPowerDistributionTemperature" + */ public static native double getTemperature(int handle); + /** + * Gets the PowerDistribution input voltage. + * + * @param handle the module handle + * @return the input voltage (volts) + * @see "HAL_GetPowerDistributionVoltage" + */ public static native double getVoltage(int handle); + /** + * Gets the current of a specific PowerDistribution channel. + * + * @param handle the module handle + * @param channel the channel + * @return the channel current (amps) + * @see "HAL_GetPowerDistributionChannelCurrent" + */ public static native double getChannelCurrent(int handle, int channel); + /** + * Gets the current of all channels on the PowerDistribution. + * + *

The array must be large enough to hold all channels. + * + * @param handle the module handle + * @param currents the currents + * @see "HAL_GetPowerDistributionAllChannelCurrents" + */ public static native void getAllCurrents(int handle, double[] currents); + /** + * Gets the total current of the PowerDistribution. + * + * @param handle the module handle + * @return the total current (amps) + * @see "HAL_GetPowerDistributionTotalCurrent" + */ public static native double getTotalCurrent(int handle); + /** + * Gets the total power of the PowerDistribution. + * + * @param handle the module handle + * @return the total power (watts) + * @see "HAL_GetPowerDistributionTotalPower" + */ public static native double getTotalPower(int handle); + /** + * Gets the total energy of the PowerDistribution. + * + * @param handle the module handle + * @return the total energy (joules) + * @see "HAL_GetPowerDistributionTotalEnergy" + */ public static native double getTotalEnergy(int handle); + /** + * Resets the PowerDistribution accumulated energy. + * + * @param handle the module handle + * @see "HAL_ClearPowerDistributionStickyFaults" + */ public static native void resetTotalEnergy(int handle); + /** + * Clears any PowerDistribution sticky faults. + * + * @param handle the module handle + * @see "HAL_ClearPowerDistributionStickyFaults" + */ public static native void clearStickyFaults(int handle); + /** + * Returns true if switchable channel is powered on. + * + *

This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param handle the module handle + * @return the state of the switchable channel + * @see "HAL_GetPowerDistributionSwitchableChannel" + */ public static native boolean getSwitchableChannel(int handle); + /** + * Power on/off switchable channel. + * + *

This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param handle the module handle + * @param enabled true to turn on switchable channel + * @see "HAL_SetPowerDistributionSwitchableChannel" + */ public static native void setSwitchableChannel(int handle, boolean enabled); + /** + * Gets the PowerDistribution input voltage without throwing any errors. + * + * @param handle the module handle + * @return the input voltage (volts) + * @see "HAL_GetPowerDistributionVoltage" + */ public static native double getVoltageNoError(int handle); + /** + * Gets the current of a specific PowerDistribution channel without throwing any errors. + * + * @param handle the module handle + * @param channel the channel + * @return the channel current (amps) + * @see "HAL_GetPowerDistributionChannelCurrent" + */ public static native double getChannelCurrentNoError(int handle, int channel); + /** + * Gets the total current of the PowerDistribution without throwing any errors. + * + * @param handle the module handle + * @return the total current (amps) + * @see "HAL_GetPowerDistributionTotalCurrent" + */ public static native double getTotalCurrentNoError(int handle); + /** + * Returns true if switchable channel is powered on without throwing any errors. + * + *

This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param handle the module handle + * @return the state of the switchable channel + * @see "HAL_GetPowerDistributionSwitchableChannel" + */ public static native boolean getSwitchableChannelNoError(int handle); + /** + * Power on/off switchable channel without throwing any errors. + * + *

This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param handle the module handle + * @param enabled true to turn on switchable channel + * @see "HAL_SetPowerDistributionSwitchableChannel" + */ public static native void setSwitchableChannelNoError(int handle, boolean enabled); + /** + * Get the current faults of the PowerDistribution. + * + * @param handle the module handle + * @return the current faults + * @see "HAL_GetPowerDistributionFaults" + */ public static native int getFaultsNative(int handle); + /** + * Get the current faults of the PowerDistribution. + * + * @param handle the module handle + * @return the current faults + * @see "HAL_GetPowerDistributionFaults" + */ public static PowerDistributionFaults getFaults(int handle) { return new PowerDistributionFaults(getFaultsNative(handle)); } + /** + * Gets the sticky faults of the PowerDistribution. + * + * @param handle the module handle + * @return the sticky faults + * @see "HAL_GetPowerDistributionStickyFaults" + */ public static native int getStickyFaultsNative(int handle); + /** + * Gets the sticky faults of the PowerDistribution. + * + * @param handle the module handle + * @return the sticky faults + * @see "HAL_GetPowerDistributionStickyFaults" + */ public static PowerDistributionStickyFaults getStickyFaults(int handle) { return new PowerDistributionStickyFaults(getStickyFaultsNative(handle)); } + /** + * Get the version of the PowerDistribution. + * + * @param handle the module handle + * @return version + * @see "HAL_GetPowerDistributionVersion" + */ public static native PowerDistributionVersion getVersion(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/PowerJNI.java b/hal/src/main/java/edu/wpi/first/hal/PowerJNI.java index 0bea6edd61..a59058cb48 100644 --- a/hal/src/main/java/edu/wpi/first/hal/PowerJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/PowerJNI.java @@ -4,36 +4,139 @@ package edu.wpi.first.hal; +/** + * Power HAL JNI Functions. + * + * @see "Power.h" + */ public class PowerJNI extends JNIWrapper { + /** + * Gets the roboRIO input voltage. + * + * @return the input voltage (volts) + * @see "HAL_GetVinVoltage" + */ public static native double getVinVoltage(); + /** + * Gets the roboRIO input current. + * + * @return the input current (amps) + * @see "HAL_GetVinCurrent" + */ public static native double getVinCurrent(); + /** + * Gets the 6V rail voltage. + * + * @return the 6V rail voltage (volts) + * @see "HAL_GetUserVoltage6V" + */ public static native double getUserVoltage6V(); + /** + * Gets the 6V rail current. + * + * @return the 6V rail current (amps) + * @see "HAL_GetUserCurrent6V" + */ public static native double getUserCurrent6V(); + /** + * Gets the active state of the 6V rail. + * + * @return true if the rail is active, otherwise false + * @see "HAL_GetUserActive6V" + */ public static native boolean getUserActive6V(); + /** + * Gets the fault count for the 6V rail. + * + * @return the number of 6V fault counts + * @see "HAL_GetUserCurrentFaults6V" + */ public static native int getUserCurrentFaults6V(); + /** + * Gets the 5V rail voltage. + * + * @return the 5V rail voltage (volts) + * @see "HAL_GetUserVoltage5V" + */ public static native double getUserVoltage5V(); + /** + * Gets the 5V rail current. + * + * @return the 5V rail current (amps) + * @see "HAL_GetUserCurrent5V" + */ public static native double getUserCurrent5V(); + /** + * Gets the active state of the 5V rail. + * + * @return true if the rail is active, otherwise false + * @see "HAL_GetUserActive5V" + */ public static native boolean getUserActive5V(); + /** + * Gets the fault count for the 5V rail. + * + * @return the number of 5V fault counts + * @see "HAL_GetUserCurrentFaults5V" + */ public static native int getUserCurrentFaults5V(); + /** + * Gets the 3V3 rail voltage. + * + * @return the 3V3 rail voltage (volts) + * @see "HAL_GetUserVoltage3V3" + */ public static native double getUserVoltage3V3(); + /** + * Gets the 3V3 rail current. + * + * @return the 3V3 rail current (amps) + * @see "HAL_GetUserCurrent3V3" + */ public static native double getUserCurrent3V3(); + /** + * Gets the active state of the 3V3 rail. + * + * @return true if the rail is active, otherwise false + * @see "HAL_GetUserActive3V3" + */ public static native boolean getUserActive3V3(); + /** + * Gets the fault count for the 3V3 rail. + * + * @return the number of 3V3 fault counts + * @see "HAL_GetUserCurrentFaults3V3" + */ public static native int getUserCurrentFaults3V3(); + /** + * Set the voltage the roboRIO will brownout and disable all outputs. + * + *

Note that this only does anything on the roboRIO 2. On the roboRIO it is a no-op. + * + * @param voltage The brownout voltage + * @see "HAL_SetBrownoutVoltage" + */ public static native void setBrownoutVoltage(double voltage); + /** + * Get the current brownout voltage setting. + * + * @return The brownout voltage + * @see "HAL_GetBrownoutVoltage" + */ public static native double getBrownoutVoltage(); } diff --git a/hal/src/main/java/edu/wpi/first/hal/REVPHJNI.java b/hal/src/main/java/edu/wpi/first/hal/REVPHJNI.java index a4fb92ecee..b1935b2f98 100644 --- a/hal/src/main/java/edu/wpi/first/hal/REVPHJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/REVPHJNI.java @@ -4,21 +4,64 @@ package edu.wpi.first.hal; -/** REV Pneumatic Hub (PH) HAL JNI functions. */ +/** + * REV Pneumatic Hub (PH) HAL JNI functions. + * + * @see "REVPH.h" + */ public class REVPHJNI extends JNIWrapper { public static final int COMPRESSOR_CONFIG_TYPE_DISABLED = 0; public static final int COMPRESSOR_CONFIG_TYPE_DIGITAL = 1; public static final int COMPRESSOR_CONFIG_TYPE_ANALOG = 2; public static final int COMPRESSOR_CONFIG_TYPE_HYBRID = 3; + /** + * Initializes a PH. + * + * @param module the CAN ID to initialize + * @return the created PH handle + * @see "HAL_InitializeREVP" + */ public static native int initialize(int module); + /** + * Frees a PH handle. + * + * @param handle the PH handle + * @see "HAL_FreeREVPH" + */ public static native void free(int handle); + /** + * Checks if a solenoid channel number is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + * @see "HAL_CheckREVPHSolenoidChannel" + */ public static native boolean checkSolenoidChannel(int channel); + /** + * Get whether compressor is turned on. + * + * @param handle the PH handle + * @return true if the compressor is turned on + * @see "HAL_GetREVPHCompressor" + */ public static native boolean getCompressor(int handle); + /** + * Send compressor configuration to the PH. + * + * @param handle the PH handle + * @param minAnalogVoltage The compressor will turn on when the analog pressure sensor voltage + * drops below this value + * @param maxAnalogVoltage The compressor will turn off when the analog pressure sensor reaches + * this value. + * @param forceDisable Disable Compressor + * @param useDigital use the digital pressure switch + * @see "HAL_SetREVPHCompressorConfig" + */ public static native void setCompressorConfig( int handle, double minAnalogVoltage, @@ -26,51 +69,221 @@ public class REVPHJNI extends JNIWrapper { boolean forceDisable, boolean useDigital); + /** + * Disable Compressor. + * + * @param handle the PH handle + * @see "HAL_SetREVPHClosedLoopControlDisabled" + */ public static native void setClosedLoopControlDisabled(int handle); + /** + * Enables the compressor in digital mode using the digital pressure switch. The compressor will + * turn on when the pressure switch indicates that the system is not full, and will turn off when + * the pressure switch indicates that the system is full. + * + * @param handle the PH handle + * @see "HAL_SetREVPHClosedLoopControlDigital" + */ public static native void setClosedLoopControlDigital(int handle); + /** + * Enables the compressor in analog mode. This mode uses an analog pressure sensor connected to + * analog channel 0 to cycle the compressor. The compressor will turn on when the pressure drops + * below minAnalogVoltage and will turn off when the pressure reaches maxAnalogVoltage. This mode + * is only supported by the REV PH with the REV Analog Pressure Sensor connected to analog channel + * 0. + * + * @param handle the PH handle + * @param minAnalogVoltage The compressor will turn on when the analog pressure sensor voltage + * drops below this value + * @param maxAnalogVoltage The compressor will turn off when the analog pressure sensor reaches + * this value. + * @see "HAL_SetREVPHClosedLoopControlAnalog" + */ public static native void setClosedLoopControlAnalog( int handle, double minAnalogVoltage, double maxAnalogVoltage); + /** + * Enables the compressor in hybrid mode. This mode uses both a digital pressure switch and an + * analog pressure sensor connected to analog channel 0 to cycle the compressor. + * + *

The compressor will turn on when \a both: + * + *

- The digital pressure switch indicates the system is not full AND - The analog pressure + * sensor indicates that the pressure in the system is below the specified minimum pressure. + * + *

The compressor will turn off when \a either: + * + *

- The digital pressure switch is disconnected or indicates that the system is full OR - The + * pressure detected by the analog sensor is greater than the specified maximum pressure. + * + * @param handle the PH handle + * @param minAnalogVoltage The compressor will turn on when the analog pressure sensor voltage + * drops below this value and the pressure switch indicates that the system is not full. + * @param maxAnalogVoltage The compressor will turn off when the analog pressure sensor reaches + * this value or the pressure switch is disconnected or indicates that the system is full. + * @see "HAL_SetREVPHClosedLoopControlHybrid" + */ public static native void setClosedLoopControlHybrid( int handle, double minAnalogVoltage, double maxAnalogVoltage); + /** + * Get compressor configuration from the PH. + * + * @param handle the PH handle + * @return compressor configuration + * @see "HAL_GetREVPHCompressorConfig" + */ public static native int getCompressorConfig(int handle); + /** + * Returns the state of the digital pressure switch. + * + * @param handle the PH handle + * @return True if pressure switch indicates that the system is full, otherwise false. + * @see "HAL_GetREVPHPressureSwitch" + */ public static native boolean getPressureSwitch(int handle); + /** + * Returns the raw voltage of the specified analog input channel. + * + * @param handle the PH handle + * @param channel The analog input channel to read voltage from. + * @return The voltage of the specified analog input channel in volts. + * @see "HAL_GetREVPHAnalogVoltage" + */ public static native double getAnalogVoltage(int handle, int channel); + /** + * Returns the current drawn by the compressor. + * + * @param handle the PH handle + * @return The current drawn by the compressor in amps. + * @see "HAL_GetREVPHCompressorCurrent" + */ public static native double getCompressorCurrent(int handle); + /** + * Gets a bitmask of solenoid values. + * + * @param handle the PH handle + * @return solenoid values + * @see "HAL_GetREVPHSolenoids" + */ public static native int getSolenoids(int handle); + /** + * Sets solenoids on a PH. + * + * @param handle the PH handle + * @param mask bitmask to set + * @param values solenoid values + * @see "HAL_SetREVPHSolenoids" + */ public static native void setSolenoids(int handle, int mask, int values); + /** + * Fire a single solenoid shot for the specified duration. + * + * @param handle the PH handle + * @param index solenoid index + * @param durMs shot duration in ms + * @see "HAL_FireREVPHOneShot" + */ public static native void fireOneShot(int handle, int index, int durMs); + /** + * Clears the sticky faults. + * + * @param handle the PH handle + * @see "HAL_ClearREVPHStickyFaults" + */ public static native void clearStickyFaults(int handle); + /** + * Returns the current input voltage for the PH. + * + * @param handle the PH handle + * @return The input voltage in volts. + * @see "HAL_GetREVPHVoltage" + */ public static native double getInputVoltage(int handle); + /** + * Returns the current voltage of the regulated 5v supply. + * + * @param handle the PH handle + * @return The current voltage of the 5v supply in volts. + * @see "HAL_GetREVPH5VVoltage" + */ public static native double get5VVoltage(int handle); + /** + * Returns the total current drawn by all solenoids. + * + * @param handle the PH handle + * @return Total current drawn by all solenoids in amps. + * @see "HAL_GetREVPHSolenoidCurrent" + */ public static native double getSolenoidCurrent(int handle); + /** + * Returns the current voltage of the solenoid power supply. + * + * @param handle the PH handle + * @return The current voltage of the solenoid power supply in volts. + * @see "HAL_GetREVPHSolenoidVoltage" + */ public static native double getSolenoidVoltage(int handle); + /** + * Returns the sticky faults currently active on this device. + * + * @param handle the PH handle + * @return The sticky faults. + * @see "HAL_GetREVPHStickyFaults" + */ public static native int getStickyFaultsNative(int handle); + /** + * Returns the sticky faults currently active on this device. + * + * @param handle the PH handle + * @return The sticky faults. + * @see "HAL_GetREVPHStickyFaults" + */ public static REVPHStickyFaults getStickyFaults(int handle) { return new REVPHStickyFaults(getStickyFaultsNative(handle)); } + /** + * Returns the faults currently active on the PH. + * + * @param handle the PH handle + * @return The faults. + * @see "HAL_GetREVPHFaults" + */ public static native int getFaultsNative(int handle); + /** + * Returns the faults currently active on the PH. + * + * @param handle the PH handle + * @return The faults. + * @see "HAL_GetREVPHFaults" + */ public static REVPHFaults getFaults(int handle) { return new REVPHFaults(getFaultsNative(handle)); } + /** + * Returns the hardware and firmware versions of the PH. + * + * @param handle the PH handle + * @return The hardware and firmware versions. + * @see "HAL_GetREVPHVersion" + */ public static native REVPHVersion getVersion(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/RelayJNI.java b/hal/src/main/java/edu/wpi/first/hal/RelayJNI.java index eee2854a6a..10a39b4884 100644 --- a/hal/src/main/java/edu/wpi/first/hal/RelayJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/RelayJNI.java @@ -4,14 +4,57 @@ package edu.wpi.first.hal; +/** + * Relay Output HAL JNI Functions. + * + * @see "hal/Relay.h" + */ public class RelayJNI extends DIOJNI { + /** + * 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 halPortHandle the port handle to initialize + * @param forward true for the forward port, false for the reverse port + * @return the created relay handle + * @see "HAL_InitializeRelayPort" + */ public static native int initializeRelayPort(int halPortHandle, boolean forward); + /** + * Frees a relay port. + * + * @param relayPortHandle the relay handle + * @see "HAL_FreeRelayPort" + */ public static native void freeRelayPort(int relayPortHandle); + /** + * Checks if a relay channel is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + * @see "HAL_CheckRelayChannel" + */ public static native boolean checkRelayChannel(int channel); + /** + * Sets the state of a relay output. + * + * @param relayPortHandle the relay handle + * @param on true for on, false for off + * @see "HAL_SetRelay" + */ public static native void setRelay(int relayPortHandle, boolean on); + /** + * Gets the current state of the relay channel. + * + * @param relayPortHandle the relay handle + * @return true for on, false for off + * @see "HAL_GetRelay" + */ public static native boolean getRelay(int relayPortHandle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/SPIJNI.java b/hal/src/main/java/edu/wpi/first/hal/SPIJNI.java index 053f1929cc..82b9fed160 100644 --- a/hal/src/main/java/edu/wpi/first/hal/SPIJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/SPIJNI.java @@ -6,6 +6,11 @@ package edu.wpi.first.hal; import java.nio.ByteBuffer; +/** + * SPI HAL JNI functions. + * + * @see "SPI.h" + */ public class SPIJNI extends JNIWrapper { public static final int INVALID_PORT = -1; public static final int ONBOARD_CS0_PORT = 0; @@ -19,40 +24,198 @@ public class SPIJNI extends JNIWrapper { public static final int SPI_MODE2 = 2; public static final int SPI_MODE3 = 3; + /** + * 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 + * @see "HAL_InitializeSPI" + */ public static native void spiInitialize(int port); + /** + * 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 dataReceived Buffer to read data into. + * @param size Number of bytes to transfer. [0..7] + * @return Number of bytes transferred, -1 for error + * @see "HAL_TransactionSPI" + */ public static native int spiTransaction( int port, ByteBuffer dataToSend, ByteBuffer dataReceived, byte size); + /** + * 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 dataReceived Buffer to read data into. + * @param size Number of bytes to transfer. [0..7] + * @return Number of bytes transferred, -1 for error + * @see "HAL_TransactionSPI" + */ public static native int spiTransactionB( int port, byte[] dataToSend, byte[] dataReceived, byte size); + /** + * Executes a write transaction with the device. + * + *

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 dataToSend 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 + * @see "HAL_WriteSPI" + */ public static native int spiWrite(int port, ByteBuffer dataToSend, byte sendSize); + /** + * Executes a write transaction with the device. + * + *

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 dataToSend 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 + * @see "HAL_WriteSPI" + */ public static native int spiWriteB(int port, byte[] dataToSend, byte sendSize); + /** + * 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. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param initiate initiates a transaction when true. Just reads when false. + * @param dataReceived A pointer to the array of bytes to store the data read from the device. + * @param size The number of bytes to read in the transaction. [1..7] + * @return Number of bytes read. -1 for error. + * @see "HAL_ReadSPI" + */ public static native int spiRead(int port, boolean initiate, ByteBuffer dataReceived, byte size); + /** + * 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. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param initiate initiates a transaction when true. Just reads when false. + * @param dataReceived A pointer to the array of bytes to store the data read from the device. + * @param size The number of bytes to read in the transaction. [1..7] + * @return Number of bytes read. -1 for error. + * @see "HAL_ReadSPI" + */ public static native int spiReadB(int port, boolean initiate, byte[] dataReceived, byte size); + /** + * Closes the SPI port. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @see "HAL_CloseSPI" + */ public static native void spiClose(int port); + /** + * 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 speed The speed in Hz (500KHz-10MHz) + * @see "HAL_SetSPISpeed" + */ public static native void spiSetSpeed(int port, int speed); + /** + * Sets the SPI Mode. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param mode The SPI mode to use + * @see "HAL_SetSPIMode" + */ public static native void spiSetMode(int port, int mode); + /** + * Gets the SPI Mode. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @return The SPI mode currently set + * @see "HAL_GetSPIMode" + */ public static native int spiGetMode(int 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 + * @see "HAL_SetSPIChipSelectActiveHigh" + */ public static native void spiSetChipSelectActiveHigh(int 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 + * @see "HAL_SetSPIChipSelectActiveLow" + */ public static native void spiSetChipSelectActiveLow(int port); + /** + * 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. + * @see "HAL_InitSPIAuto" + */ public static native void spiInitAuto(int port, int bufferSize); + /** + * Frees an SPI automatic accumulator. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP. + * @see "HAL_FreeSPIAuto" + */ public static native void spiFreeAuto(int port); + /** + * 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 accumulation period (seconds). + * @see "HAL_StartSPIAutoRate" + */ public static native void spiStartAutoRate(int port, double period); + /** + * 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. + * @see "HAL_StartSPIAutoTrigger" + */ public static native void spiStartAutoTrigger( int port, int digitalSourceHandle, @@ -60,20 +223,83 @@ public class SPIJNI extends JNIWrapper { boolean triggerRising, boolean triggerFalling); + /** + * Stops an automatic SPI accumulation. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP. + * @see "HAL_StopSPIAuto" + */ public static native void spiStopAuto(int port); + /** + * 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 zeroSize The number of zeros to send after the data. + * @see "HAL_SetSPIAutoTransmitData" + */ public static native void spiSetAutoTransmitData(int port, byte[] dataToSend, int zeroSize); + /** + * 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. + * @see "HAL_ForceSPIAutoRead" + */ public static native void spiForceAutoRead(int port); + /** + * Reads data received by the SPI accumulator. Each received data sequence consists of a timestamp + * followed by the received data bytes, one byte per word (in the least significant byte). The + * length of each received data sequence is the same as the combined dataSize + zeroSize set in + * spiSetAutoTransmitData. + * + * @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 words to read. + * @param timeout The read timeout (in seconds). + * @return The number of words actually read. + * @see "HAL_ReadSPIAutoReceivedData" + */ public static native int spiReadAutoReceivedData( int port, ByteBuffer buffer, int numToRead, double timeout); + /** + * Reads data received by the SPI accumulator. Each received data sequence consists of a timestamp + * followed by the received data bytes, one byte per word (in the least significant byte). The + * length of each received data sequence is the same as the combined dataSize + zeroSize set in + * spiSetAutoTransmitData. + * + * @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 words to read. + * @param timeout The read timeout (in seconds). + * @return The number of words actually read. + * @see "HAL_ReadSPIAutoReceivedData" + */ public static native int spiReadAutoReceivedData( int port, int[] buffer, int numToRead, double timeout); + /** + * 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. + * @see "HAL_GetSPIAutoDroppedCount" + */ public static native int spiGetAutoDroppedCount(int port); + /** + * Configure the Auto SPI Stall time between reads. + * + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP. + * @param csToSclkTicks the number of ticks to wait before asserting the cs pin + * @param stallTicks the number of ticks to stall for + * @param pow2BytesPerRead the number of bytes to read before stalling + * @see "HAL_ConfigureSPIAutoStall" + */ public static native void spiConfigureAutoStall( int port, int csToSclkTicks, int stallTicks, int pow2BytesPerRead); } diff --git a/hal/src/main/java/edu/wpi/first/hal/SerialPortJNI.java b/hal/src/main/java/edu/wpi/first/hal/SerialPortJNI.java index ee9464e7bc..e156f3a0a6 100644 --- a/hal/src/main/java/edu/wpi/first/hal/SerialPortJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/SerialPortJNI.java @@ -4,42 +4,205 @@ package edu.wpi.first.hal; +/** + * Serial Port JNI HAL functions. + * + * @see "SerialPort.h" + */ public class SerialPortJNI extends JNIWrapper { + /** + * 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 + * @return Serial Port Handle + * @see "HAL_InitializeSerialPort" + */ public static native int serialInitializePort(byte port); + /** + * Initializes a serial port with a direct name. + * + *

This name is the /dev name for a specific port. Note these are not always consistent between + * roboRIO reboots. + * + * @param port the serial port to initialize + * @param portName the dev port name + * @return Serial Port Handle + * @see "HAL_InitializeSerialPortDirect" + */ public static native int serialInitializePortDirect(byte port, String portName); + /** + * Sets the baud rate of a serial port. + * + *

Any value between 0 and 0xFFFFFFFF may be used. Default is 9600. + * + * @param handle the serial port handle + * @param baud the baud rate to set + * @see "HAL_SetSerialBaudRate" + */ public static native void serialSetBaudRate(int handle, int baud); + /** + * Sets the number of data bits on a serial port. + * + *

Defaults to 8. + * + * @param handle the serial port handle + * @param bits the number of data bits (5-8) + * @see "HAL_SetSerialDataBits" + */ public static native void serialSetDataBits(int handle, byte bits); + /** + * 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 handle the serial port handle + * @param parity the parity bit mode (see remarks for valid values) + * @see "HAL_SetSerialParity" + */ public static native void serialSetParity(int handle, byte parity); + /** + * 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 handle the serial port handle + * @param stopBits the stop bit value (see remarks for valid values) + * @see "HAL_SetSerialStopBits" + */ public static native void serialSetStopBits(int handle, byte stopBits); + /** + * Sets the write mode on a serial port. + * + *

Valid values are: 1: Flush on access 2: Flush when full (default) + * + * @param handle the serial port handle + * @param mode the mode to set (see remarks for valid values) + * @see "HAL_SetSerialWriteMode" + */ public static native void serialSetWriteMode(int handle, byte mode); + /** + * 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 handle the serial port handle + * @param flow the mode to set (see remarks for valid values) + * @see "HAL_SetSerialFlowControl" + */ public static native void serialSetFlowControl(int handle, byte flow); + /** + * Sets the minimum serial read timeout of a port. + * + * @param handle the serial port handle + * @param timeout the timeout in milliseconds + * @see "HAL_SetSerialTimeout" + */ public static native void serialSetTimeout(int handle, double timeout); + /** + * Sets the termination character that terminates a read. + * + *

By default this is disabled. + * + * @param handle the serial port handle + * @param terminator the termination character to set + * @see "HAL_EnableSerialTermination" + */ public static native void serialEnableTermination(int handle, char terminator); + /** + * Disables a termination character for reads. + * + * @param handle the serial port handle + * @see "HAL_DisableSerialTermination" + */ public static native void serialDisableTermination(int handle); + /** + * Sets the size of the read buffer. + * + * @param handle the serial port handle + * @param size the read buffer size + * @see "HAL_SetSerialReadBufferSize" + */ public static native void serialSetReadBufferSize(int handle, int size); + /** + * Sets the size of the write buffer. + * + * @param handle the serial port handle + * @param size the write buffer size + * @see "HAL_SetSerialWriteBufferSize" + */ public static native void serialSetWriteBufferSize(int handle, int size); + /** + * Gets the number of bytes currently in the read buffer. + * + * @param handle the serial port handle + * @return the number of bytes in the read buffer + * @see "HAL_GetSerialBytesReceived" + */ public static native int serialGetBytesReceived(int handle); + /** + * 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 handle the serial port handle + * @param buffer the buffer in which to store bytes read + * @param count the number of bytes maximum to read + * @return the number of bytes actually read + * @see "HAL_ReadSerial" + */ public static native int serialRead(int handle, byte[] buffer, int count); + /** + * Writes data to the serial port. + * + * @param handle the serial port handle + * @param buffer the buffer to write + * @param count the number of bytes to write from the buffer + * @return the number of bytes actually written + * @see "HAL_WriteSerial" + */ public static native int serialWrite(int handle, byte[] buffer, int count); + /** + * Flushes the serial write buffer out to the port. + * + * @param handle the serial port handle + * @see "HAL_FlushSerial" + */ public static native void serialFlush(int handle); + /** + * Clears the receive buffer of the serial port. + * + * @param handle the serial port handle + * @see "HAL_ClearSerial" + */ public static native void serialClear(int handle); + /** + * Closes a serial port. + * + * @param handle the serial port handle to close + * @see "HAL_CloseSerial" + */ public static native void serialClose(int handle); } diff --git a/hal/src/main/java/edu/wpi/first/hal/ThreadsJNI.java b/hal/src/main/java/edu/wpi/first/hal/ThreadsJNI.java index c854e208ea..2ccc808560 100644 --- a/hal/src/main/java/edu/wpi/first/hal/ThreadsJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/ThreadsJNI.java @@ -4,10 +4,37 @@ package edu.wpi.first.hal; +/** + * Threads HAL JNI Functions. + * + * @see "Threads.h" + */ public class ThreadsJNI extends JNIWrapper { + /** + * Gets the thread priority for the current thread. + * + * @return The current thread priority. For real-time, this is 1-99 with 99 being highest. For + * non-real-time, this is 0. See "man 7 sched" for details. + * @see "HAL_GetCurrentThreadPriority" + */ public static native int getCurrentThreadPriority(); + /** + * Gets the real-time status for the current thread. + * + * @return Set to true if thread is real-time, otherwise false. + * @see "HAL_GetCurrentThreadPriority" + */ public static native boolean getCurrentThreadIsRealTime(); + /** + * Sets the thread priority for the current thread. + * + * @param realTime Set to true to set a real-time priority, false for standard priority. + * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being + * highest. For non-real-time, this is forced to 0. See "man 7 sched" for more details. + * @return True on success. + * @see "HAL_SetCurrentThreadPriority" + */ public static native boolean setCurrentThreadPriority(boolean realTime, int priority); } diff --git a/hal/src/main/native/include/hal/AnalogGyro.h b/hal/src/main/native/include/hal/AnalogGyro.h index ed7c3085dc..6dd948a326 100644 --- a/hal/src/main/native/include/hal/AnalogGyro.h +++ b/hal/src/main/native/include/hal/AnalogGyro.h @@ -21,7 +21,7 @@ extern "C" { /** * Initializes an analog gyro. * - * @param[in] handle handle to the analog port + * @param[in] handle handle to the analog input port * @param[in] allocationLocation the location where the allocation is occurring * (can be null) * @param[out] status the error code, or 0 for success @@ -43,7 +43,7 @@ void HAL_SetupAnalogGyro(HAL_GyroHandle handle, int32_t* status); /** * Frees an analog gyro. * - * @param handle the gyro handle + * @param[in,out] handle the gyro handle */ void HAL_FreeAnalogGyro(HAL_GyroHandle handle); diff --git a/hal/src/main/native/include/hal/AnalogInput.h b/hal/src/main/native/include/hal/AnalogInput.h index 1c9fdcbb4b..462103a4ed 100644 --- a/hal/src/main/native/include/hal/AnalogInput.h +++ b/hal/src/main/native/include/hal/AnalogInput.h @@ -33,14 +33,14 @@ HAL_AnalogInputHandle HAL_InitializeAnalogInputPort( /** * Frees an analog input port. * - * @param analogPortHandle Handle to the analog port. + * @param[in,out] analogPortHandle Handle to the analog port. */ void HAL_FreeAnalogInputPort(HAL_AnalogInputHandle analogPortHandle); /** * Checks that the analog module number is valid. * - * @param module The analog module number. + * @param[in] module The analog module number. * @return Analog module is valid and present */ HAL_Bool HAL_CheckAnalogModule(int32_t module); @@ -50,7 +50,7 @@ HAL_Bool HAL_CheckAnalogModule(int32_t module); * 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. + * @param[in] channel The analog output channel number. * @return Analog channel is valid */ HAL_Bool HAL_CheckAnalogInputChannel(int32_t channel); diff --git a/hal/src/main/native/include/hal/AnalogTrigger.h b/hal/src/main/native/include/hal/AnalogTrigger.h index 72727a8fca..f4622e3f47 100644 --- a/hal/src/main/native/include/hal/AnalogTrigger.h +++ b/hal/src/main/native/include/hal/AnalogTrigger.h @@ -45,6 +45,7 @@ HAL_AnalogTriggerHandle HAL_InitializeAnalogTrigger( * * @param[in] dutyCycleHandle the analog input to use for duty cycle * @param[out] status Error status variable. 0 on success. + * @return tbe created analog trigger handle */ HAL_AnalogTriggerHandle HAL_InitializeAnalogTriggerDutyCycle( HAL_DutyCycleHandle dutyCycleHandle, int32_t* status); diff --git a/hal/src/main/native/include/hal/CANAPI.h b/hal/src/main/native/include/hal/CANAPI.h index 005aa1bc19..f515d60540 100644 --- a/hal/src/main/native/include/hal/CANAPI.h +++ b/hal/src/main/native/include/hal/CANAPI.h @@ -47,7 +47,7 @@ HAL_CANHandle HAL_InitializeCAN(HAL_CANManufacturer manufacturer, /** * Frees a CAN device * - * @param handle the CAN handle + * @param[in,out] handle the CAN handle */ void HAL_CleanCAN(HAL_CANHandle handle); diff --git a/hal/src/main/native/include/hal/CTREPCM.h b/hal/src/main/native/include/hal/CTREPCM.h index 3cfb5e4b5d..932ed3471c 100644 --- a/hal/src/main/native/include/hal/CTREPCM.h +++ b/hal/src/main/native/include/hal/CTREPCM.h @@ -154,6 +154,8 @@ HAL_Bool HAL_GetCTREPCMCompressorShortedFault(HAL_CTREPCMHandle handle, * were last cleared. This fault is persistent and can be cleared by * HAL_ClearAllCTREPCMStickyFaults() * + * @param[in] handle the PCM handle + * @param[out] status Error status variable. 0 on success. * @return True if the compressor has been disconnected since sticky faults * were last cleared, otherwise false. * @see HAL_GetCTREPCMCompressorShortedFault() @@ -207,6 +209,8 @@ int32_t HAL_GetCTREPCMSolenoidDisabledList(HAL_CTREPCMHandle handle, * were last cleared. This fault is persistent and can be cleared by * HAL_ClearAllCTREPCMStickyFaults() * + * @param[in] handle the PCM handle + * @param[out] status Error status variable. 0 on success. * @return True if solenoid is reporting a fault, otherwise false. * @see HAL_GetCTREPCMSolenoidVoltageFault() */ @@ -223,7 +227,12 @@ HAL_Bool HAL_GetCTREPCMSolenoidVoltageStickyFault(HAL_CTREPCMHandle handle, HAL_Bool HAL_GetCTREPCMSolenoidVoltageFault(HAL_CTREPCMHandle handle, int32_t* status); -/** Clears all sticky faults on this device. */ +/** + * Clears all sticky faults on this device. + * + * @param[in] handle the PCM handle + * @param[out] status Error status variable. 0 on success. + */ void HAL_ClearAllCTREPCMStickyFaults(HAL_CTREPCMHandle handle, int32_t* status); /** diff --git a/hal/src/main/native/include/hal/Counter.h b/hal/src/main/native/include/hal/Counter.h index cc2d77692a..0338cdae7a 100644 --- a/hal/src/main/native/include/hal/Counter.h +++ b/hal/src/main/native/include/hal/Counter.h @@ -233,7 +233,7 @@ void HAL_ResetCounter(HAL_CounterHandle counterHandle, int32_t* status); */ int32_t HAL_GetCounter(HAL_CounterHandle counterHandle, 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 diff --git a/hal/src/main/native/include/hal/DIO.h b/hal/src/main/native/include/hal/DIO.h index 925a09ef33..f5313843e8 100644 --- a/hal/src/main/native/include/hal/DIO.h +++ b/hal/src/main/native/include/hal/DIO.h @@ -37,7 +37,7 @@ HAL_DigitalHandle HAL_InitializeDIOPort(HAL_PortHandle portHandle, * Checks if a DIO channel is valid. * * @param channel the channel number to check - * @return true if the channel is correct, otherwise false + * @return true if the channel is valid, otherwise false */ HAL_Bool HAL_CheckDIOChannel(int32_t channel); @@ -77,7 +77,7 @@ void HAL_FreeDigitalPWM(HAL_DigitalPWMHandle pwmGenerator, int32_t* status); * * The valid range is from 0.6 Hz to 19 kHz. * - * The frequency resolution is logarithmic. + * The frequency resolution is logarithmic. * * @param[in] rate the frequency to output all digital output PWM signals * @param[out] status Error status variable. 0 on success. @@ -227,7 +227,7 @@ int32_t HAL_GetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t* status); * * 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. + * complicates the interface. That can be changed later. * * @param[in] filterIndex the filter index, 0 - 2 * @param[in] value the number of cycles that the signal must not @@ -242,10 +242,11 @@ void HAL_SetFilterPeriod(int32_t filterIndex, int64_t value, int32_t* status); * 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 * complicates the interface. Set status to NiFpga_Status_SoftwareFault if the - * filter values miss-match. + * filter values mismatch. * * @param[in] filterIndex the filter index, 0 - 2 * @param[out] status Error status variable. 0 on success. + * @return The number of FPGA cycles of the filter period. */ int64_t HAL_GetFilterPeriod(int32_t filterIndex, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/hal/DMA.h b/hal/src/main/native/include/hal/DMA.h index b8651e5703..b735b6d265 100644 --- a/hal/src/main/native/include/hal/DMA.h +++ b/hal/src/main/native/include/hal/DMA.h @@ -185,7 +185,7 @@ void HAL_AddDMAAveragedAnalogInput(HAL_DMAHandle handle, int32_t* status); /** - * Adds acuumulator data of an analog input to be collected by DMA. + * Adds accumulator data of an analog input to be collected by DMA. * * This can only be called if DMA is not started. * diff --git a/hal/src/main/native/include/hal/DriverStation.h b/hal/src/main/native/include/hal/DriverStation.h index fb0af9aa1a..136b92471d 100644 --- a/hal/src/main/native/include/hal/DriverStation.h +++ b/hal/src/main/native/include/hal/DriverStation.h @@ -32,6 +32,7 @@ extern "C" { * @param callStack the callstack of the error * @param printMsg true to print the error message to stdout as well as to the * DS + * @return the error code, or 0 for success */ int32_t HAL_SendError(HAL_Bool isError, int32_t errorCode, HAL_Bool isLVCode, const char* details, const char* location, @@ -48,13 +49,14 @@ void HAL_SetPrintErrorImpl(void (*func)(const char* line, size_t size)); * Sends a line to the driver station console. * * @param line the line to send (null terminated) + * @return the error code, or 0 for success */ int32_t HAL_SendConsoleLine(const char* line); /** * Gets the current control word of the driver station. * - * The control work contains the robot state. + * The control word contains the robot state. * * @param controlWord the control word (out) * @return the error code, or 0 for success @@ -117,7 +119,7 @@ int32_t HAL_GetJoystickDescriptor(int32_t joystickNum, HAL_JoystickDescriptor* desc); /** - * Gets is a specific joystick is considered to be an XBox controller. + * Gets whether a specific joystick is considered to be an XBox controller. * * @param joystickNum the joystick number * @return true if xbox, false otherwise @@ -198,6 +200,8 @@ double HAL_GetMatchTime(int32_t* status); /** * Gets if outputs are enabled by the control system. + * + * @return true if outputs are enabled */ HAL_Bool HAL_GetOutputsEnabled(void); @@ -209,6 +213,11 @@ HAL_Bool HAL_GetOutputsEnabled(void); */ int32_t HAL_GetMatchInfo(HAL_MatchInfo* info); +/** + * Refresh the DS control word. + * + * @return true if updated + */ HAL_Bool HAL_RefreshDSData(void); void HAL_ProvideNewDataEventHandle(WPI_EventHandle handle); diff --git a/hal/src/main/native/include/hal/DutyCycle.h b/hal/src/main/native/include/hal/DutyCycle.h index 90266fd96a..d5e655b9cf 100644 --- a/hal/src/main/native/include/hal/DutyCycle.h +++ b/hal/src/main/native/include/hal/DutyCycle.h @@ -26,7 +26,7 @@ extern "C" { * @param[in] triggerType the analog trigger type of the source if it is * an analog trigger * @param[out] status Error status variable. 0 on success. - * @return thre created duty cycle handle + * @return the created duty cycle handle */ HAL_DutyCycleHandle HAL_InitializeDutyCycle(HAL_Handle digitalSourceHandle, HAL_AnalogTriggerType triggerType, diff --git a/hal/src/main/native/include/hal/Encoder.h b/hal/src/main/native/include/hal/Encoder.h index a6bf4afc5b..c6e16a6778 100644 --- a/hal/src/main/native/include/hal/Encoder.h +++ b/hal/src/main/native/include/hal/Encoder.h @@ -83,7 +83,7 @@ void HAL_SetEncoderSimDevice(HAL_EncoderHandle handle, /** * Gets the current counts of the encoder after encoding type scaling. * - * This is scaled by the value passed duing initialization to encodingType. + * This is scaled by the value passed during initialization to encodingType. * * @param[in] encoderHandle the encoder handle * @param[out] status Error status variable. 0 on success. @@ -125,7 +125,7 @@ int32_t HAL_GetEncoderEncodingScale(HAL_EncoderHandle encoderHandle, */ 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 diff --git a/hal/src/main/native/include/hal/HALBase.h b/hal/src/main/native/include/hal/HALBase.h index aa32841f59..0b267ab624 100644 --- a/hal/src/main/native/include/hal/HALBase.h +++ b/hal/src/main/native/include/hal/HALBase.h @@ -18,7 +18,7 @@ /** * @defgroup hal_capi WPILib HAL API - * Hardware Abstraction Layer to hardware or simulator + * Hardware Abstraction Layer (HAL) to hardware or simulator * @{ */ @@ -75,9 +75,9 @@ int32_t HAL_GetFPGAVersion(int32_t* status); int64_t HAL_GetFPGARevision(int32_t* status); /** - * Returns the serial number. + * Returns the roboRIO serial number. * - * @param[out] buffer The serial number. + * @param[out] buffer The roboRIO serial number. * @param size The maximum characters to copy into buffer. * @return Number of characters copied into buffer. */ @@ -108,7 +108,7 @@ HAL_RuntimeType HAL_GetRuntimeType(void); HAL_Bool HAL_GetFPGAButton(int32_t* status); /** - * Gets if the system outputs are currently active + * Gets if the system outputs are currently active. * * @param[out] status the error code, or 0 for success * @return true if the system outputs are active, false if disabled @@ -173,7 +173,8 @@ uint64_t HAL_GetFPGATime(int32_t* status); uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t* status); /** - * Gets the current state of the Robot Signal Light (RSL) + * Gets the current state of the Robot Signal Light (RSL). + * * @param[out] status the error code, or 0 for success * @return The current state of the RSL- true if on, false if off */ diff --git a/hal/src/main/native/include/hal/Notifier.h b/hal/src/main/native/include/hal/Notifier.h index 96452f4cc8..9b451e46f5 100644 --- a/hal/src/main/native/include/hal/Notifier.h +++ b/hal/src/main/native/include/hal/Notifier.h @@ -63,7 +63,8 @@ void HAL_SetNotifierName(HAL_NotifierHandle notifierHandle, const char* name, /** * Stops a notifier from running. * - * This will cause any call into HAL_WaitForNotifierAlarm to return. + * This will cause any call into HAL_WaitForNotifierAlarm to return with time = + * 0. * * @param[in] notifierHandle the notifier handle * @param[out] status Error status variable. 0 on success. diff --git a/hal/src/main/native/include/hal/Ports.h b/hal/src/main/native/include/hal/Ports.h index a21244644e..a6c610ac55 100644 --- a/hal/src/main/native/include/hal/Ports.h +++ b/hal/src/main/native/include/hal/Ports.h @@ -45,7 +45,7 @@ int32_t HAL_GetNumAnalogInputs(void); int32_t HAL_GetNumAnalogOutputs(void); /** - * Gets the number of analog counters in the current system. + * Gets the number of counters in the current system. * * @return the number of counters */ diff --git a/hal/src/main/native/include/hal/PowerDistribution.h b/hal/src/main/native/include/hal/PowerDistribution.h index 3ea44ff93b..47543bb2bd 100644 --- a/hal/src/main/native/include/hal/PowerDistribution.h +++ b/hal/src/main/native/include/hal/PowerDistribution.h @@ -134,7 +134,7 @@ double HAL_GetPowerDistributionChannelCurrent( HAL_PowerDistributionHandle handle, int32_t channel, int32_t* status); /** - * Gets the current of all 24 channels on the PowerDistribution. + * Gets the current of all channels on the PowerDistribution. * * The array must be large enough to hold all channels. * @@ -214,6 +214,7 @@ void HAL_SetPowerDistributionSwitchableChannel( * * @param[in] handle the module handle * @param[out] status Error status variable. 0 on success. + * @return the state of the switchable channel */ HAL_Bool HAL_GetPowerDistributionSwitchableChannel( HAL_PowerDistributionHandle handle, int32_t* status); @@ -291,12 +292,34 @@ struct HAL_PowerDistributionStickyFaults { uint32_t hasReset : 1; }; +/** + * Get the version of the PowerDistribution. + * + * @param[in] handle the module handle + * @param[out] version the HAL_PowerDistributionVersion to populate + * @param[out] status Error status variable. 0 on success. + */ void HAL_GetPowerDistributionVersion(HAL_PowerDistributionHandle handle, HAL_PowerDistributionVersion* version, int32_t* status); +/** + * Get the current faults of the PowerDistribution. + * + * @param[in] handle the module handle + * @param[out] faults the HAL_PowerDistributionFaults to populate + * @param[out] status Error status variable. 0 on success. + */ void HAL_GetPowerDistributionFaults(HAL_PowerDistributionHandle handle, HAL_PowerDistributionFaults* faults, int32_t* status); + +/** + * Gets the sticky faults of the PowerDistribution. + * + * @param[in] handle the module handle + * @param[out] stickyFaults the HAL_PowerDistributionStickyFaults to populate + * @param[out] status Error status variable. 0 on success. + */ void HAL_GetPowerDistributionStickyFaults( HAL_PowerDistributionHandle handle, HAL_PowerDistributionStickyFaults* stickyFaults, int32_t* status); diff --git a/hal/src/main/native/include/hal/REVPH.h b/hal/src/main/native/include/hal/REVPH.h index 0686c9943e..4476675a96 100644 --- a/hal/src/main/native/include/hal/REVPH.h +++ b/hal/src/main/native/include/hal/REVPH.h @@ -316,7 +316,7 @@ void HAL_GetREVPHVersion(HAL_REVPHHandle handle, HAL_REVPHVersion* version, int32_t HAL_GetREVPHSolenoids(HAL_REVPHHandle handle, int32_t* status); /** - * Sets solenoids on a pneumatics module. + * Sets solenoids on a PH. * * @param[in] handle the PH handle * @param[in] mask bitmask to set diff --git a/hal/src/main/native/include/hal/SPI.h b/hal/src/main/native/include/hal/SPI.h index f3c7fdca09..32644b6fab 100644 --- a/hal/src/main/native/include/hal/SPI.h +++ b/hal/src/main/native/include/hal/SPI.h @@ -108,7 +108,7 @@ void HAL_SetSPIMode(HAL_SPIPort port, HAL_SPIMode mode); * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for * MXP - * @returns The SPI mode currently set + * @return The SPI mode currently set */ HAL_SPIMode HAL_GetSPIMode(HAL_SPIPort port); @@ -172,7 +172,7 @@ void HAL_FreeSPIAuto(HAL_SPIPort port, int32_t* status); * * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 * for MXP. - * @param[in] period The accumlation period (seconds). + * @param[in] period The accumulation period (seconds). * @param[out] status the error code, or 0 for success */ void HAL_StartSPIAutoRate(HAL_SPIPort port, double period, int32_t* status); @@ -199,7 +199,7 @@ void HAL_StartSPIAutoTrigger(HAL_SPIPort port, HAL_Handle digitalSourceHandle, int32_t* status); /** - * Stops an automatic SPI accumlation. + * Stops an automatic SPI accumulation. * * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 * for MXP. diff --git a/hal/src/main/native/include/hal/SerialPort.h b/hal/src/main/native/include/hal/SerialPort.h index cd6140e6ef..f4a357eb9e 100644 --- a/hal/src/main/native/include/hal/SerialPort.h +++ b/hal/src/main/native/include/hal/SerialPort.h @@ -30,11 +30,12 @@ extern "C" { /** * Initializes a serial port. * - * The channels are either the onboard RS232, the mxp uart, or 2 USB ports. The + * 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[in] port the serial port to initialize * @param[out] status the error code, or 0 for success + * @return Serial Port Handle */ HAL_SerialPortHandle HAL_InitializeSerialPort(HAL_SerialPort port, int32_t* status); @@ -48,6 +49,7 @@ HAL_SerialPortHandle HAL_InitializeSerialPort(HAL_SerialPort port, * @param[in] port the serial port to initialize * @param[in] portName the dev port name * @param[out] status the error code, or 0 for success + * @return Serial Port Handle */ HAL_SerialPortHandle HAL_InitializeSerialPortDirect(HAL_SerialPort port, const char* portName,