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_CheckAnalogOutputChannel" + */ public static native boolean checkAnalogOutputChannel(int channel); /** @@ -95,8 +105,22 @@ public class AnalogJNI extends JNIWrapper { */ public static native void setAnalogInputSimDevice(int handle, int device); + /** + * Sets an analog output value. + * + * @param portHandle the analog output handle + * @param voltage the voltage (0-5v) to output + * @see "HAL_SetAnalogOutput" + */ public static native void setAnalogOutput(int portHandle, double voltage); + /** + * Gets the current analog output value. + * + * @param portHandle the analog output handle + * @return the current output voltage (0-5v) + * @see "HAL_GetAnalogOutput" + */ public static native double getAnalogOutput(int portHandle); /** diff --git a/hal/src/main/java/edu/wpi/first/hal/PWMJNI.java b/hal/src/main/java/edu/wpi/first/hal/PWMJNI.java index 5166248839..3f0e3d4be6 100644 --- a/hal/src/main/java/edu/wpi/first/hal/PWMJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/PWMJNI.java @@ -5,12 +5,41 @@ package edu.wpi.first.hal; public class PWMJNI extends DIOJNI { + /** + * Initializes a PWM port. + * + * @param halPortHandle the port to initialize + * @return the created pwm handle + */ public static native int initializePWMPort(int halPortHandle); + /** + * Checks if a pwm channel is valid. + * + * @param channel the channel to check + * @return true if the channel is valid, otherwise false + */ public static native boolean checkPWMChannel(int channel); + /** + * Frees a PWM port. + * + * @param pwmPortHandle the pwm handle + */ public static native void freePWMPort(int pwmPortHandle); + /** + * Sets the configuration settings for the PWM channel. + * + *
All values are in microseconds. + * + * @param pwmPortHandle the PWM handle + * @param maxPwm the maximum PWM value + * @param deadbandMaxPwm the high range of the center deadband + * @param centerPwm the center PWM value + * @param deadbandMinPwm the low range of the center deadband + * @param minPwm the minimum PWM value + */ public static native void setPWMConfigMicroseconds( int pwmPortHandle, int maxPwm, @@ -19,30 +48,120 @@ public class PWMJNI extends DIOJNI { int deadbandMinPwm, int minPwm); + /** + * Gets the pwm configuration settings for the PWM channel. + * + *
Values are in microseconds. + * + * @param pwmPortHandle the PWM handle + * @return the pwm configuration settings + */ public static native PWMConfigDataResult getPWMConfigMicroseconds(int pwmPortHandle); + /** + * Sets if the FPGA should output the center value if the input value is within the deadband. + * + * @param pwmPortHandle the PWM handle + * @param eliminateDeadband true to eliminate deadband, otherwise false + */ public static native void setPWMEliminateDeadband(int pwmPortHandle, boolean eliminateDeadband); + /** + * Gets the current eliminate deadband value. + * + * @param pwmPortHandle the PWM handle + * @return true if set, otherwise false + */ public static native boolean getPWMEliminateDeadband(int pwmPortHandle); + /** + * Sets a PWM channel to the desired pulse width in microseconds. + * + * @param pwmPortHandle the PWM handle + * @param microsecondPulseTime the PWM value to set + */ public static native void setPulseTimeMicroseconds(int pwmPortHandle, int microsecondPulseTime); + /** + * Sets a PWM channel to the desired scaled value. + * + *
The values range from -1 to 1 and the period is controlled by the PWM Period and MinHigh + * registers. + * + * @param pwmPortHandle the PWM handle + * @param speed the scaled PWM value to set + */ public static native void setPWMSpeed(int pwmPortHandle, double speed); + /** + * Sets a PWM channel to the desired position value. + * + *
The values range from 0 to 1 and the period is controlled by the PWM Period and MinHigh + * registers. + * + * @param pwmPortHandle the PWM handle + * @param position the positional PWM value to set + */ public static native void setPWMPosition(int pwmPortHandle, double position); + /** + * Gets the current microsecond pulse time from a PWM channel. + * + * @param pwmPortHandle the PWM handle + * @return the current PWM microsecond pulse time + */ public static native int getPulseTimeMicroseconds(int pwmPortHandle); + /** + * Gets a scaled value from a PWM channel. + * + *
The values range from -1 to 1. + * + * @param pwmPortHandle the PWM handle + * @return the current speed PWM value + */ public static native double getPWMSpeed(int pwmPortHandle); + /** + * Gets a position value from a PWM channel. + * + *
The values range from 0 to 1. + * + * @param pwmPortHandle the PWM handle + * @return the current positional PWM value + */ public static native double getPWMPosition(int pwmPortHandle); + /** + * Sets a PWM channel to be disabled. + * + *
The channel is disabled until the next time it is set. Note this is different from just + * setting a 0 speed, as this will actively stop all signaling on the channel. + * + * @param pwmPortHandle the PWM handle. + */ public static native void setPWMDisabled(int pwmPortHandle); + /** + * Forces a PWM signal to go to 0 temporarily. + * + * @param pwmPortHandle the PWM handle. + */ public static native void latchPWMZero(int pwmPortHandle); + /** + * Sets the PWM output to be a continuous high signal while enabled. + * + * @param pwmPortHandle the PWM handle. + */ public static native void setAlwaysHighMode(int pwmPortHandle); + /** + * Sets how how often the PWM signal is squelched, thus scaling the period. + * + * @param pwmPortHandle the PWM handle. + * @param squelchMask the 2-bit mask of outputs to squelch + */ public static native void setPWMPeriodScale(int pwmPortHandle, int squelchMask); /** Utility class. */ diff --git a/wpinet/src/main/java/edu/wpi/first/net/WPINetJNI.java b/wpinet/src/main/java/edu/wpi/first/net/WPINetJNI.java index 8e79cdc2e5..4f0e189a16 100644 --- a/wpinet/src/main/java/edu/wpi/first/net/WPINetJNI.java +++ b/wpinet/src/main/java/edu/wpi/first/net/WPINetJNI.java @@ -69,8 +69,21 @@ public class WPINetJNI { libraryLoaded = true; } + /** + * Forward a local TCP port to a remote host and port. Note that local ports less than 1024 won't + * work as a normal user. + * + * @param port local port number + * @param remoteHost remote IP address / DNS name + * @param remotePort remote port number + */ public static native void addPortForwarder(int port, String remoteHost, int remotePort); + /** + * Stop TCP forwarding on a port. + * + * @param port local port number + */ public static native void removePortForwarder(int port); public static native int createMulticastServiceAnnouncer( diff --git a/wpiutil/src/main/java/edu/wpi/first/util/WPIUtilJNI.java b/wpiutil/src/main/java/edu/wpi/first/util/WPIUtilJNI.java index 96e693dfea..94165e9618 100644 --- a/wpiutil/src/main/java/edu/wpi/first/util/WPIUtilJNI.java +++ b/wpiutil/src/main/java/edu/wpi/first/util/WPIUtilJNI.java @@ -82,18 +82,67 @@ public class WPIUtilJNI { public static native long getSystemTime(); + /** + * Creates an event. Events have binary state (signaled or not signaled) and may be either + * automatically reset or manually reset. Automatic-reset events go to non-signaled state when a + * WaitForObject is woken up by the event; manual-reset events require ResetEvent() to be called + * to set the event to non-signaled state; if ResetEvent() is not called, any waiter on that event + * will immediately wake when called. + * + * @param manualReset true for manual reset, false for automatic reset + * @param initialState true to make the event initially in signaled state + * @return Event handle + */ public static native int createEvent(boolean manualReset, boolean initialState); + /** + * Destroys an event. Destruction wakes up any waiters. + * + * @param eventHandle event handle + */ public static native void destroyEvent(int eventHandle); + /** + * Sets an event to signaled state. + * + * @param eventHandle event handle + */ public static native void setEvent(int eventHandle); + /** + * Sets an event to non-signaled state. + * + * @param eventHandle event handle + */ public static native void resetEvent(int eventHandle); + /** + * Creates a semaphore. Semaphores keep an internal counter. Releasing the semaphore increases the + * count. A semaphore with a non-zero count is considered signaled. When a waiter wakes up it + * atomically decrements the count by 1. This is generally useful in a single-supplier, + * multiple-consumer scenario. + * + * @param initialCount initial value for the semaphore's internal counter + * @param maximumCount maximum value for the samephore's internal counter + * @return Semaphore handle + */ public static native int createSemaphore(int initialCount, int maximumCount); + /** + * Destroys a semaphore. Destruction wakes up any waiters. + * + * @param semHandle semaphore handle + */ public static native void destroySemaphore(int semHandle); + /** + * Releases N counts of a semaphore. + * + * @param semHandle semaphore handle + * @param releaseCount amount to add to semaphore's internal counter; must be positive + * @return True on successful release, false on failure (e.g. release count would exceed maximum + * value, or handle invalid) + */ public static native boolean releaseSemaphore(int semHandle, int releaseCount); static native long allocateRawFrame(); diff --git a/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLogJNI.java b/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLogJNI.java index 7a58ee8705..70ff70ae2a 100644 --- a/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLogJNI.java +++ b/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLogJNI.java @@ -13,34 +13,139 @@ import java.nio.ByteBuffer; * @see "wpiutil/DataLog.h" */ public class DataLogJNI extends WPIUtilJNI { + /** + * Create a new Data Log. The log will be initially created with a temporary filename. + * + * @param dir directory to store the log + * @param filename filename to use; if none provided, a random filename is generated of the form + * "wpilog_{}.wpilog" + * @param period time between automatic flushes to disk, in seconds; this is a time/storage + * tradeoff + * @param extraHeader extra header data + * @return data log implementation handle + */ static native long create(String dir, String filename, double period, String extraHeader); + /** + * Change log filename. + * + * @param impl data log implementation handle + * @param filename filename + */ static native void setFilename(long impl, String filename); + /** + * Explicitly flushes the log data to disk. + * + * @param impl data log implementation handle + */ static native void flush(long impl); + /** + * Pauses appending of data records to the log. While paused, no data records are saved (e.g. + * AppendX is a no-op). Has no effect on entry starts / finishes / metadata changes. + * + * @param impl data log implementation handle + */ static native void pause(long impl); + /** + * Resumes appending of data records to the log. If called after Stop(), opens a new file (with + * random name if SetFilename was not called after Stop()) and appends Start records and schema + * data values for all previously started entries and schemas. + * + * @param impl data log implementation handle + */ static native void resume(long impl); + /** + * Stops appending all records to the log, and closes the log file. + * + * @param impl data log implementation handle + */ static native void stop(long impl); + /** + * Registers a data schema. Data schemas provide information for how a certain data type string + * can be decoded. The type string of a data schema indicates the type of the schema itself (e.g. + * "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In the data log, schemas + * are saved just like normal records, with the name being generated from the provided name: + * "/.schema/<name>". Duplicate calls to this function with the same name are silently + * ignored. + * + * @param impl data log implementation handle + * @param name Name (the string passed as the data type for records using this schema) + * @param type Type of schema (e.g. "protobuf", "struct", etc) + * @param schema Schema data + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void addSchema(long impl, String name, String type, byte[] schema, long timestamp); static native void addSchemaString( long impl, String name, String type, String schema, long timestamp); + /** + * Start an entry. Duplicate names are allowed (with the same type), and result in the same index + * being returned (Start/Finish are reference counted). A duplicate name with a different type + * will result in an error message being printed to the console and 0 being returned (which will + * be ignored by the Append functions). + * + * @param impl data log implementation handle + * @param name Name + * @param type Data type + * @param metadata Initial metadata (e.g. data properties) + * @param timestamp Time stamp (may be 0 to indicate now) + * @return Entry index + */ static native int start(long impl, String name, String type, String metadata, long timestamp); + /** + * Finish an entry. + * + * @param impl data log implementation handle + * @param entry Entry index + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void finish(long impl, int entry, long timestamp); + /** + * Updates the metadata for an entry. + * + * @param impl data log implementation handle + * @param entry Entry index + * @param metadata New metadata for the entry + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void setMetadata(long impl, int entry, String metadata, long timestamp); + /** + * Closes the data log implementation handle. + * + * @param impl data log implementation handle + */ static native void close(long impl); + /** + * Appends a raw record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by WPI_DataLog_Start() + * @param data Byte array to record + * @param len Length of byte array + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendRaw( long impl, int entry, byte[] data, int start, int len, long timestamp); + /** + * Appends a raw record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by WPI_DataLog_Start() + * @param data ByteBuffer to record + * @param len Length of byte array + * @param timestamp Time stamp (may be 0 to indicate now) + */ static void appendRaw(long impl, int entry, ByteBuffer data, int start, int len, long timestamp) { if (data.isDirect()) { if (start < 0) { @@ -63,23 +168,103 @@ public class DataLogJNI extends WPIUtilJNI { private static native void appendRawBuffer( long impl, int entry, ByteBuffer data, int start, int len, long timestamp); + /** + * Appends a boolean record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param value Boolean value to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendBoolean(long impl, int entry, boolean value, long timestamp); + /** + * Appends an integer record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param value Integer value to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendInteger(long impl, int entry, long value, long timestamp); + /** + * Appends a float record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param value Float value to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendFloat(long impl, int entry, float value, long timestamp); + /** + * Appends a double record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param value Double value to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendDouble(long impl, int entry, double value, long timestamp); + /** + * Appends a string record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param value String value to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendString(long impl, int entry, String value, long timestamp); + /** + * Appends a boolean array record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param arr Boolean array to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendBooleanArray(long impl, int entry, boolean[] value, long timestamp); + /** + * Appends an integer array record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param arr Integer array to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendIntegerArray(long impl, int entry, long[] value, long timestamp); + /** + * Appends a float array record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param arr Float array to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendFloatArray(long impl, int entry, float[] value, long timestamp); + /** + * Appends a double array record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param arr Double array to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendDoubleArray(long impl, int entry, double[] value, long timestamp); + /** + * Appends a string array record to the log. + * + * @param impl data log implementation handle + * @param entry Entry index, as returned by Start() + * @param arr String array to record + * @param timestamp Time stamp (may be 0 to indicate now) + */ static native void appendStringArray(long impl, int entry, String[] value, long timestamp); }