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