001// Copyright (c) FIRST and other WPILib contributors. 002// Open Source Software; you can modify and/or share it under the terms of 003// the WPILib BSD license file in the root directory of this project. 004 005package edu.wpi.first.hal; 006 007import edu.wpi.first.hal.can.CANReceiveMessage; 008 009/** 010 * CAN API HAL JNI Functions. 011 * 012 * @see "hal/CANAPI.h" 013 */ 014public class CANAPIJNI extends JNIWrapper { 015 /** 016 * Initializes a CAN device. 017 * 018 * <p>These follow the FIRST standard CAN layout. 019 * https://docs.wpilib.org/en/stable/docs/software/can-devices/can-addressing.html 020 * 021 * @param busId the bus ID 022 * @param manufacturer the can manufacturer 023 * @param deviceId the device ID (0-63) 024 * @param deviceType the device type 025 * @return the created CAN handle 026 * @see "HAL_InitializeCAN" 027 */ 028 public static native int initializeCAN(int busId, int manufacturer, int deviceId, int deviceType); 029 030 /** 031 * Frees a CAN device. 032 * 033 * @param handle the CAN handle 034 * @see "HAL_CleanCAN" 035 */ 036 public static native void cleanCAN(int handle); 037 038 /** 039 * Writes a packet to the CAN device with a specific ID. 040 * 041 * <p>This ID is 10 bits. 042 * 043 * @param handle the CAN handle 044 * @param apiId the ID to write (0-1023 bits) 045 * @param data the data to send. 046 * @param dataLength the length of data to send 047 * @param flags the message flags 048 * @see "HAL_WriteCANPacket" 049 */ 050 public static native void writeCANPacket( 051 int handle, int apiId, byte[] data, int dataLength, int flags); 052 053 /** 054 * Writes a repeating packet to the CAN device with a specific ID. 055 * 056 * <p>This ID is 10 bits. 057 * 058 * <p>The RoboRIO will automatically repeat the packet at the specified interval 059 * 060 * @param handle the CAN handle 061 * @param apiId the ID to write (0-1023) 062 * @param data the data to send. 063 * @param dataLength the length of data to send 064 * @param flags the message flags 065 * @param repeatMs the period to repeat in ms 066 * @see "HAL_WriteCANPacketRepeating" 067 */ 068 public static native void writeCANPacketRepeating( 069 int handle, int apiId, byte[] data, int dataLength, int flags, int repeatMs); 070 071 /** 072 * Writes an RTR frame of the specified length to the CAN device with the specific ID. 073 * 074 * <p>By spec, the length must be equal to the length sent by the other device, otherwise behavior 075 * is unspecified. 076 * 077 * @param handle the CAN handle 078 * @param apiId the ID to write (0-1023) 079 * @param data the data to send. 080 * @param dataLength the length of data to send 081 * @param flags the message flags 082 * @see "HAL_WriteCANRTRFrame" 083 */ 084 public static native void writeCANRTRFrame( 085 int handle, int apiId, byte[] data, int dataLength, int flags); 086 087 /** 088 * Writes a packet to the CAN device with a specific ID without throwing on error. 089 * 090 * <p>This ID is 10 bits. 091 * 092 * @param handle the CAN handle 093 * @param apiId the ID to write (0-1023 bits) 094 * @param data the data to send. 095 * @param dataLength the length of data to send 096 * @param flags the message flags 097 * @return Error status variable. 0 on success. 098 * @see "HAL_WriteCANPacket" 099 */ 100 public static native int writeCANPacketNoThrow( 101 int handle, int apiId, byte[] data, int dataLength, int flags); 102 103 /** 104 * Writes a repeating packet to the CAN device with a specific ID without throwing on error. 105 * 106 * <p>This ID is 10 bits. 107 * 108 * <p>The RoboRIO will automatically repeat the packet at the specified interval 109 * 110 * @param handle the CAN handle 111 * @param apiId the ID to write (0-1023) 112 * @param data the data to send. 113 * @param dataLength the length of data to send 114 * @param flags the message flags 115 * @param repeatMs the period to repeat in ms 116 * @return Error status variable. 0 on success. 117 * @see "HAL_WriteCANPacketRepeating" 118 */ 119 public static native int writeCANPacketRepeatingNoThrow( 120 int handle, int apiId, byte[] data, int dataLength, int flags, int repeatMs); 121 122 /** 123 * Writes an RTR frame of the specified length to the CAN device with the specific ID without 124 * throwing on error. 125 * 126 * <p>By spec, the length must be equal to the length sent by the other device, otherwise behavior 127 * is unspecified. 128 * 129 * @param handle the CAN handlee 130 * @param apiId the ID to write (0-1023) 131 * @param data the data to send. 132 * @param dataLength the length of data to send 133 * @param flags the message flags 134 * @return Error status variable. 0 on success. 135 * @see "HAL_WriteCANRTRFrame" 136 */ 137 public static native int writeCANRTRFrameNoThrow( 138 int handle, int apiId, byte[] data, int dataLength, int flags); 139 140 /** 141 * Stops a repeating packet with a specific ID. 142 * 143 * <p>This ID is 10 bits. 144 * 145 * @param handle the CAN handle 146 * @param apiId the ID to stop repeating (0-1023) 147 * @see "HAL_StopCANPacketRepeating" 148 */ 149 public static native void stopCANPacketRepeating(int handle, int apiId); 150 151 /** 152 * Reads a new CAN packet. 153 * 154 * <p>This will only return properly once per packet received. Multiple calls without receiving 155 * another packet will return false. 156 * 157 * @param handle the CAN handle 158 * @param apiId the ID to read (0-1023) 159 * @param data the received message 160 * @return true on success, false on error 161 * @see "HAL_ReadCANPacketNew" 162 */ 163 public static native boolean readCANPacketNew(int handle, int apiId, CANReceiveMessage data); 164 165 /** 166 * Reads a CAN packet. The will continuously return the last packet received, without accounting 167 * for packet age. 168 * 169 * @param handle the CAN handle 170 * @param apiId the ID to read (0-1023) 171 * @param data the received message 172 * @return true on success, false on error 173 * @see "HAL_ReadCANPacketLatest" 174 */ 175 public static native boolean readCANPacketLatest(int handle, int apiId, CANReceiveMessage data); 176 177 /** 178 * Reads a CAN packet. The will return the last packet received until the packet is older then the 179 * requested timeout. Then it will return false. 180 * 181 * @param handle the CAN handle 182 * @param apiId the ID to read (0-1023) 183 * @param data the received message 184 * @param timeoutMs the timeout time for the packet 185 * @return true on success, false on error 186 * @see "HAL_ReadCANPacketTimeout" 187 */ 188 public static native boolean readCANPacketTimeout( 189 int handle, int apiId, CANReceiveMessage data, int timeoutMs); 190 191 /** Utility class. */ 192 private CANAPIJNI() {} 193}