Source code

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