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}