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 java.nio.ByteBuffer;
008
009/**
010 * SPI HAL JNI functions.
011 *
012 * @see "SPI.h"
013 */
014public class SPIJNI extends JNIWrapper {
015  public static final int INVALID_PORT = -1;
016  public static final int ONBOARD_CS0_PORT = 0;
017  public static final int ONBOARD_CS1_PORT = 1;
018  public static final int ONBOARD_CS2_PORT = 2;
019  public static final int ONBOARD_CS3_PORT = 3;
020  public static final int MXP_PORT = 4;
021
022  public static final int SPI_MODE0 = 0;
023  public static final int SPI_MODE1 = 1;
024  public static final int SPI_MODE2 = 2;
025  public static final int SPI_MODE3 = 3;
026
027  /**
028   * Initializes the SPI port. Opens the port if necessary and saves the handle.
029   *
030   * <p>If opening the MXP port, also sets up the channel functions appropriately.
031   *
032   * @param port The number of the port to use. 0-3 for Onboard CS0-CS3, 4 for MXP
033   * @see "HAL_InitializeSPI"
034   */
035  public static native void spiInitialize(int port);
036
037  /**
038   * Performs an SPI send/receive transaction.
039   *
040   * <p>This is a lower-level interface to the spi hardware giving you more control over each
041   * transaction.
042   *
043   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
044   * @param dataToSend Buffer of data to send as part of the transaction.
045   * @param dataReceived Buffer to read data into.
046   * @param size Number of bytes to transfer. [0..7]
047   * @return Number of bytes transferred, -1 for error
048   * @see "HAL_TransactionSPI"
049   */
050  public static native int spiTransaction(
051      int port, ByteBuffer dataToSend, ByteBuffer dataReceived, byte size);
052
053  /**
054   * Performs an SPI send/receive transaction.
055   *
056   * <p>This is a lower-level interface to the spi hardware giving you more control over each
057   * transaction.
058   *
059   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
060   * @param dataToSend Buffer of data to send as part of the transaction.
061   * @param dataReceived Buffer to read data into.
062   * @param size Number of bytes to transfer. [0..7]
063   * @return Number of bytes transferred, -1 for error
064   * @see "HAL_TransactionSPI"
065   */
066  public static native int spiTransactionB(
067      int port, byte[] dataToSend, byte[] dataReceived, byte size);
068
069  /**
070   * Executes a write transaction with the device.
071   *
072   * <p>Writes to a device and wait until the transaction is complete.
073   *
074   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
075   * @param dataToSend The data to write to the register on the device.
076   * @param sendSize The number of bytes to be written
077   * @return The number of bytes written. -1 for an error
078   * @see "HAL_WriteSPI"
079   */
080  public static native int spiWrite(int port, ByteBuffer dataToSend, byte sendSize);
081
082  /**
083   * Executes a write transaction with the device.
084   *
085   * <p>Writes to a device and wait until the transaction is complete.
086   *
087   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
088   * @param dataToSend The data to write to the register on the device.
089   * @param sendSize The number of bytes to be written
090   * @return The number of bytes written. -1 for an error
091   * @see "HAL_WriteSPI"
092   */
093  public static native int spiWriteB(int port, byte[] dataToSend, byte sendSize);
094
095  /**
096   * Executes a read from the device.
097   *
098   * <p>This method does not write any data out to the device.
099   *
100   * <p>Most spi devices will require a register address to be written before they begin returning
101   * data.
102   *
103   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
104   * @param initiate initiates a transaction when true. Just reads when false.
105   * @param dataReceived A pointer to the array of bytes to store the data read from the device.
106   * @param size The number of bytes to read in the transaction. [1..7]
107   * @return Number of bytes read. -1 for error.
108   * @see "HAL_ReadSPI"
109   */
110  public static native int spiRead(int port, boolean initiate, ByteBuffer dataReceived, byte size);
111
112  /**
113   * Executes a read from the device.
114   *
115   * <p>This method does not write any data out to the device.
116   *
117   * <p>Most spi devices will require a register address to be written before they begin returning
118   * data.
119   *
120   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
121   * @param initiate initiates a transaction when true. Just reads when false.
122   * @param dataReceived A pointer to the array of bytes to store the data read from the device.
123   * @param size The number of bytes to read in the transaction. [1..7]
124   * @return Number of bytes read. -1 for error.
125   * @see "HAL_ReadSPI"
126   */
127  public static native int spiReadB(int port, boolean initiate, byte[] dataReceived, byte size);
128
129  /**
130   * Closes the SPI port.
131   *
132   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
133   * @see "HAL_CloseSPI"
134   */
135  public static native void spiClose(int port);
136
137  /**
138   * Sets the clock speed for the SPI bus.
139   *
140   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
141   * @param speed The speed in Hz (500KHz-10MHz)
142   * @see "HAL_SetSPISpeed"
143   */
144  public static native void spiSetSpeed(int port, int speed);
145
146  /**
147   * Sets the SPI Mode.
148   *
149   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
150   * @param mode The SPI mode to use
151   * @see "HAL_SetSPIMode"
152   */
153  public static native void spiSetMode(int port, int mode);
154
155  /**
156   * Gets the SPI Mode.
157   *
158   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
159   * @return The SPI mode currently set
160   * @see "HAL_GetSPIMode"
161   */
162  public static native int spiGetMode(int port);
163
164  /**
165   * Sets the CS Active high for a SPI port.
166   *
167   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
168   * @see "HAL_SetSPIChipSelectActiveHigh"
169   */
170  public static native void spiSetChipSelectActiveHigh(int port);
171
172  /**
173   * Sets the CS Active low for a SPI port.
174   *
175   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP
176   * @see "HAL_SetSPIChipSelectActiveLow"
177   */
178  public static native void spiSetChipSelectActiveLow(int port);
179
180  /**
181   * Initializes the SPI automatic accumulator.
182   *
183   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
184   * @param bufferSize The accumulator buffer size.
185   * @see "HAL_InitSPIAuto"
186   */
187  public static native void spiInitAuto(int port, int bufferSize);
188
189  /**
190   * Frees an SPI automatic accumulator.
191   *
192   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
193   * @see "HAL_FreeSPIAuto"
194   */
195  public static native void spiFreeAuto(int port);
196
197  /**
198   * Sets the period for automatic SPI accumulation.
199   *
200   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
201   * @param period The accumulation period (seconds).
202   * @see "HAL_StartSPIAutoRate"
203   */
204  public static native void spiStartAutoRate(int port, double period);
205
206  /**
207   * Starts the auto SPI accumulator on a specific trigger.
208   *
209   * <p>Note that triggering on both rising and falling edges is a valid configuration.
210   *
211   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
212   * @param digitalSourceHandle The trigger source to use (Either HAL_AnalogTriggerHandle or
213   *     HAL_DigitalHandle).
214   * @param analogTriggerType The analog trigger type, if the source is an analog trigger.
215   * @param triggerRising Trigger on the rising edge if true.
216   * @param triggerFalling Trigger on the falling edge if true.
217   * @see "HAL_StartSPIAutoTrigger"
218   */
219  public static native void spiStartAutoTrigger(
220      int port,
221      int digitalSourceHandle,
222      int analogTriggerType,
223      boolean triggerRising,
224      boolean triggerFalling);
225
226  /**
227   * Stops an automatic SPI accumulation.
228   *
229   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
230   * @see "HAL_StopSPIAuto"
231   */
232  public static native void spiStopAuto(int port);
233
234  /**
235   * Sets the data to be transmitted to the device to initiate a read.
236   *
237   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
238   * @param dataToSend Pointer to the data to send (Gets copied for continue use, so no need to keep
239   *     alive).
240   * @param zeroSize The number of zeros to send after the data.
241   * @see "HAL_SetSPIAutoTransmitData"
242   */
243  public static native void spiSetAutoTransmitData(int port, byte[] dataToSend, int zeroSize);
244
245  /**
246   * Immediately forces an SPI read to happen.
247   *
248   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
249   * @see "HAL_ForceSPIAutoRead"
250   */
251  public static native void spiForceAutoRead(int port);
252
253  /**
254   * Reads data received by the SPI accumulator. Each received data sequence consists of a timestamp
255   * followed by the received data bytes, one byte per word (in the least significant byte). The
256   * length of each received data sequence is the same as the combined dataSize + zeroSize set in
257   * spiSetAutoTransmitData.
258   *
259   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
260   * @param buffer The buffer to store the data into.
261   * @param numToRead The number of words to read.
262   * @param timeout The read timeout (in seconds).
263   * @return The number of words actually read.
264   * @see "HAL_ReadSPIAutoReceivedData"
265   */
266  public static native int spiReadAutoReceivedData(
267      int port, ByteBuffer buffer, int numToRead, double timeout);
268
269  /**
270   * Reads data received by the SPI accumulator. Each received data sequence consists of a timestamp
271   * followed by the received data bytes, one byte per word (in the least significant byte). The
272   * length of each received data sequence is the same as the combined dataSize + zeroSize set in
273   * spiSetAutoTransmitData.
274   *
275   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
276   * @param buffer The buffer to store the data into.
277   * @param numToRead The number of words to read.
278   * @param timeout The read timeout (in seconds).
279   * @return The number of words actually read.
280   * @see "HAL_ReadSPIAutoReceivedData"
281   */
282  public static native int spiReadAutoReceivedData(
283      int port, int[] buffer, int numToRead, double timeout);
284
285  /**
286   * Gets the count of how many SPI accumulations have been missed.
287   *
288   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
289   * @return The number of missed accumulations.
290   * @see "HAL_GetSPIAutoDroppedCount"
291   */
292  public static native int spiGetAutoDroppedCount(int port);
293
294  /**
295   * Configure the Auto SPI Stall time between reads.
296   *
297   * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP.
298   * @param csToSclkTicks the number of ticks to wait before asserting the cs pin
299   * @param stallTicks the number of ticks to stall for
300   * @param pow2BytesPerRead the number of bytes to read before stalling
301   * @see "HAL_ConfigureSPIAutoStall"
302   */
303  public static native void spiConfigureAutoStall(
304      int port, int csToSclkTicks, int stallTicks, int pow2BytesPerRead);
305
306  /** Utility class. */
307  private SPIJNI() {}
308}