From 9a0164816c816033ab186c7eae5a63d8f6440ef8 Mon Sep 17 00:00:00 2001 From: s1827137 Date: Sun, 31 Dec 2023 12:37:44 -0500 Subject: [PATCH 1/4] Add Docs to CANJNI --- .../java/edu/wpi/first/hal/can/CANJNI.java | 95 ++++++++++++++++--- 1 file changed, 80 insertions(+), 15 deletions(-) diff --git a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java index 177833bf821..8bad541481e 100644 --- a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java @@ -9,28 +9,93 @@ import java.nio.ByteBuffer; import java.nio.IntBuffer; +/** + * The CANJNI class provides Java Native Interface (JNI) methods for interfacing + * with the + * Controller Area Network (CAN) bus. + */ @SuppressWarnings("MethodName") public class CANJNI extends JNIWrapper { - public static final int CAN_SEND_PERIOD_NO_REPEAT = 0; - public static final int CAN_SEND_PERIOD_STOP_REPEATING = -1; + public static final int CAN_SEND_PERIOD_NO_REPEAT = 0; + public static final int CAN_SEND_PERIOD_STOP_REPEATING = -1; - /* Flags in the upper bits of the messageID */ - public static final int CAN_IS_FRAME_REMOTE = 0x80000000; - public static final int CAN_IS_FRAME_11BIT = 0x40000000; + /* Flags in the upper bits of the messageID */ + public static final int CAN_IS_FRAME_REMOTE = 0x80000000; + public static final int CAN_IS_FRAME_11BIT = 0x40000000; - public static native void FRCNetCommCANSessionMuxSendMessage( - int messageID, byte[] data, int periodMs); + /** + * Sends a CAN message + * + * @param messageID The ID of the CAN message. + * @param data The data bytes to be sent. + * @param periodMs The period in milliseconds at which to send the message, use + * {@link #CAN_SEND_PERIOD_NO_REPEAT} for a single send. + */ + public static native void FRCNetCommCANSessionMuxSendMessage( + int messageID, byte[] data, int periodMs); - public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( - IntBuffer messageID, int messageIDMask, ByteBuffer timeStamp); + /** + * Receives a CAN message. + * + * @param messageID store for the received message ID (output parameter). + * @param messageIDMask the message ID mask to look for + * @param timeStamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) (output + * parameter). + * @return The data bytes of the received message. + */ + public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( + IntBuffer messageID, int messageIDMask, ByteBuffer timeStamp); - public static native void getCANStatus(CANStatus status); + /** + * Retrieves the current status of the CAN bus. + * + * @param status The CANStatus object to hold the retrieved status. + */ + public static native void getCANStatus(CANStatus status); - public static native int openCANStreamSession(int messageID, int messageIDMask, int maxMessages); + /** + * Opens a new CAN stream session for receiving CAN messages with specified + * filters. + * + * @param messageID The CAN messageID to match against. The bits of the + * messageID are bitwise ANDed with the messageIDMask. + * @param messageIDMask The CAN messageIDMask is a bit-wise mask of bits in the + * messageID + * to match against. This allows + * matching against multiple frames. For example, providing + * an messageID of 0x2050001 and a + * mask of 0x1FFF003F would match all REV motor controller + * frames for a device with CAN ID 1. + * Providing a mask of 0x1FFFFFFF means that only the exact + * messageID will be matched. Providing + * a mask of 0 would match any frame of any type. + * @param maxMessages The maximum number of messages that can be buffered in + * the session. + * @return The handle to the opened CAN stream session. + */ + public static native int openCANStreamSession(int messageID, int messageIDMask, int maxMessages); - public static native void closeCANStreamSession(int sessionHandle); + /** + * Closes a CAN stream session. + * + * @param sessionHandle The handle of the CAN stream session to be closed. + */ + public static native void closeCANStreamSession(int sessionHandle); - public static native int readCANStreamSession( - int sessionHandle, CANStreamMessage[] messages, int messagesToRead) - throws CANStreamOverflowException; + /** + * Reads messages from a CAN stream session. + * + * @param sessionHandle The handle of the CAN stream session. + * @param messages An array to hold the CANStreamMessage objects (output + * parameter). + * @param messagesToRead The number of messages to read from the session. + * @throws CANStreamOverflowException If the number of messages to read exceeds + * the capacity + * of the provided messages array. + * @returns The number of messages read + */ + public static native int readCANStreamSession( + int sessionHandle, CANStreamMessage[] messages, int messagesToRead) + throws CANStreamOverflowException; } From c73472bad30eab8ee5a981b2d91681ed461c6cf5 Mon Sep 17 00:00:00 2001 From: s1827137 Date: Sun, 31 Dec 2023 12:42:29 -0500 Subject: [PATCH 2/4] Fix Formatting --- .../java/edu/wpi/first/hal/can/CANJNI.java | 145 ++++++++---------- 1 file changed, 67 insertions(+), 78 deletions(-) diff --git a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java index 8bad541481e..2b11ecaf663 100644 --- a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java @@ -10,92 +10,81 @@ import java.nio.IntBuffer; /** - * The CANJNI class provides Java Native Interface (JNI) methods for interfacing - * with the - * Controller Area Network (CAN) bus. + * The CANJNI class provides Java Native Interface (JNI) methods for interfacing with the Controller + * Area Network (CAN) bus. */ @SuppressWarnings("MethodName") public class CANJNI extends JNIWrapper { - public static final int CAN_SEND_PERIOD_NO_REPEAT = 0; - public static final int CAN_SEND_PERIOD_STOP_REPEATING = -1; + public static final int CAN_SEND_PERIOD_NO_REPEAT = 0; + public static final int CAN_SEND_PERIOD_STOP_REPEATING = -1; - /* Flags in the upper bits of the messageID */ - public static final int CAN_IS_FRAME_REMOTE = 0x80000000; - public static final int CAN_IS_FRAME_11BIT = 0x40000000; + /* Flags in the upper bits of the messageID */ + public static final int CAN_IS_FRAME_REMOTE = 0x80000000; + public static final int CAN_IS_FRAME_11BIT = 0x40000000; - /** - * Sends a CAN message - * - * @param messageID The ID of the CAN message. - * @param data The data bytes to be sent. - * @param periodMs The period in milliseconds at which to send the message, use - * {@link #CAN_SEND_PERIOD_NO_REPEAT} for a single send. - */ - public static native void FRCNetCommCANSessionMuxSendMessage( - int messageID, byte[] data, int periodMs); + /** + * Sends a CAN message + * + * @param messageID The ID of the CAN message. + * @param data The data bytes to be sent. + * @param periodMs The period in milliseconds at which to send the message, use {@link + * #CAN_SEND_PERIOD_NO_REPEAT} for a single send. + */ + public static native void FRCNetCommCANSessionMuxSendMessage( + int messageID, byte[] data, int periodMs); - /** - * Receives a CAN message. - * - * @param messageID store for the received message ID (output parameter). - * @param messageIDMask the message ID mask to look for - * @param timeStamp the packet received timestamp (based off of - * CLOCK_MONOTONIC) (output - * parameter). - * @return The data bytes of the received message. - */ - public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( - IntBuffer messageID, int messageIDMask, ByteBuffer timeStamp); + /** + * Receives a CAN message. + * + * @param messageID store for the received message ID (output parameter). + * @param messageIDMask the message ID mask to look for + * @param timeStamp the packet received timestamp (based off of CLOCK_MONOTONIC) (output + * parameter). + * @return The data bytes of the received message. + */ + public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( + IntBuffer messageID, int messageIDMask, ByteBuffer timeStamp); - /** - * Retrieves the current status of the CAN bus. - * - * @param status The CANStatus object to hold the retrieved status. - */ - public static native void getCANStatus(CANStatus status); + /** + * Retrieves the current status of the CAN bus. + * + * @param status The CANStatus object to hold the retrieved status. + */ + public static native void getCANStatus(CANStatus status); - /** - * Opens a new CAN stream session for receiving CAN messages with specified - * filters. - * - * @param messageID The CAN messageID to match against. The bits of the - * messageID are bitwise ANDed with the messageIDMask. - * @param messageIDMask The CAN messageIDMask is a bit-wise mask of bits in the - * messageID - * to match against. This allows - * matching against multiple frames. For example, providing - * an messageID of 0x2050001 and a - * mask of 0x1FFF003F would match all REV motor controller - * frames for a device with CAN ID 1. - * Providing a mask of 0x1FFFFFFF means that only the exact - * messageID will be matched. Providing - * a mask of 0 would match any frame of any type. - * @param maxMessages The maximum number of messages that can be buffered in - * the session. - * @return The handle to the opened CAN stream session. - */ - public static native int openCANStreamSession(int messageID, int messageIDMask, int maxMessages); + /** + * Opens a new CAN stream session for receiving CAN messages with specified filters. + * + * @param messageID The CAN messageID to match against. The bits of the messageID are bitwise + * ANDed with the messageIDMask. + * @param messageIDMask The CAN messageIDMask is a bit-wise mask of bits in the messageID to match + * against. This allows matching against multiple frames. For example, providing an messageID + * of 0x2050001 and a mask of 0x1FFF003F would match all REV motor controller frames for a + * device with CAN ID 1. Providing a mask of 0x1FFFFFFF means that only the exact messageID + * will be matched. Providing a mask of 0 would match any frame of any type. + * @param maxMessages The maximum number of messages that can be buffered in the session. + * @return The handle to the opened CAN stream session. + */ + public static native int openCANStreamSession(int messageID, int messageIDMask, int maxMessages); - /** - * Closes a CAN stream session. - * - * @param sessionHandle The handle of the CAN stream session to be closed. - */ - public static native void closeCANStreamSession(int sessionHandle); + /** + * Closes a CAN stream session. + * + * @param sessionHandle The handle of the CAN stream session to be closed. + */ + public static native void closeCANStreamSession(int sessionHandle); - /** - * Reads messages from a CAN stream session. - * - * @param sessionHandle The handle of the CAN stream session. - * @param messages An array to hold the CANStreamMessage objects (output - * parameter). - * @param messagesToRead The number of messages to read from the session. - * @throws CANStreamOverflowException If the number of messages to read exceeds - * the capacity - * of the provided messages array. - * @returns The number of messages read - */ - public static native int readCANStreamSession( - int sessionHandle, CANStreamMessage[] messages, int messagesToRead) - throws CANStreamOverflowException; + /** + * Reads messages from a CAN stream session. + * + * @param sessionHandle The handle of the CAN stream session. + * @param messages An array to hold the CANStreamMessage objects (output parameter). + * @param messagesToRead The number of messages to read from the session. + * @throws CANStreamOverflowException If the number of messages to read exceeds the capacity of + * the provided messages array. + * @returns The number of messages read + */ + public static native int readCANStreamSession( + int sessionHandle, CANStreamMessage[] messages, int messagesToRead) + throws CANStreamOverflowException; } From bc84282b87d37df7b321c2996a66c368c2b2315e Mon Sep 17 00:00:00 2001 From: s1827137 Date: Sun, 31 Dec 2023 12:56:56 -0500 Subject: [PATCH 3/4] Fix JavaDoc Typo --- hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java index 2b11ecaf663..f21b18a9890 100644 --- a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java @@ -10,8 +10,9 @@ import java.nio.IntBuffer; /** - * The CANJNI class provides Java Native Interface (JNI) methods for interfacing with the Controller - * Area Network (CAN) bus. + * CAN API HAL JNI Functions. + * + * @see "hal/CAN.h" */ @SuppressWarnings("MethodName") public class CANJNI extends JNIWrapper { @@ -82,7 +83,7 @@ public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( * @param messagesToRead The number of messages to read from the session. * @throws CANStreamOverflowException If the number of messages to read exceeds the capacity of * the provided messages array. - * @returns The number of messages read + * @return The number of messages read into the buffer */ public static native int readCANStreamSession( int sessionHandle, CANStreamMessage[] messages, int messagesToRead) From f69907ced10d21f7a7f21d9955609a10bd2ce9c6 Mon Sep 17 00:00:00 2001 From: s1827137 Date: Sun, 31 Dec 2023 13:25:26 -0500 Subject: [PATCH 4/4] Fix Formatting Errors --- hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java index f21b18a9890..4d12774361b 100644 --- a/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/can/CANJNI.java @@ -24,7 +24,7 @@ public class CANJNI extends JNIWrapper { public static final int CAN_IS_FRAME_11BIT = 0x40000000; /** - * Sends a CAN message + * Sends a CAN message. * * @param messageID The ID of the CAN message. * @param data The data bytes to be sent. @@ -81,9 +81,9 @@ public static native byte[] FRCNetCommCANSessionMuxReceiveMessage( * @param sessionHandle The handle of the CAN stream session. * @param messages An array to hold the CANStreamMessage objects (output parameter). * @param messagesToRead The number of messages to read from the session. + * @return The number of messages read into the buffer * @throws CANStreamOverflowException If the number of messages to read exceeds the capacity of * the provided messages array. - * @return The number of messages read into the buffer */ public static native int readCANStreamSession( int sessionHandle, CANStreamMessage[] messages, int messagesToRead)