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.IntBuffer;
008
009/**
010 * Counter HAL JNI functions.
011 *
012 * @see "hal/Counter.h"
013 */
014public class CounterJNI extends JNIWrapper {
015  public static final int TWO_PULSE = 0;
016  public static final int SEMI_PERIOD = 1;
017  public static final int PULSE_LENGTH = 2;
018  public static final int EXTERNAL_DIRECTION = 3;
019
020  /**
021   * Initializes a counter.
022   *
023   * @param mode the counter mode
024   * @param index the compressor index (output)
025   * @return the created handle
026   * @see "HAL_InitializeCounter"
027   */
028  public static native int initializeCounter(int mode, IntBuffer index);
029
030  /**
031   * Frees a counter.
032   *
033   * @param counterHandle the counter handle
034   * @see "HAL_FreeCounter"
035   */
036  public static native void freeCounter(int counterHandle);
037
038  /**
039   * Sets the average sample size of a counter.
040   *
041   * @param counterHandle the counter handle
042   * @param size the size of samples to average
043   * @see "HAL_SetCounterAverageSize"
044   */
045  public static native void setCounterAverageSize(int counterHandle, int size);
046
047  /**
048   * Sets the source object that causes the counter to count up.
049   *
050   * @param counterHandle the counter handle
051   * @param digitalSourceHandle the digital source handle (either a HAL_AnalogTriggerHandle or a
052   *     HAL_DigitalHandle)
053   * @param analogTriggerType the analog trigger type if the source is an analog trigger
054   * @see "HAL_SetCounterUpSource"
055   */
056  public static native void setCounterUpSource(
057      int counterHandle, int digitalSourceHandle, int analogTriggerType);
058
059  /**
060   * Sets the up source to either detect rising edges or falling edges.
061   *
062   * <p>Note that both are allowed to be set true at the same time without issues.
063   *
064   * @param counterHandle the counter handle
065   * @param risingEdge true to trigger on rising
066   * @param fallingEdge true to trigger on falling
067   * @see "HAL_SetCounterUpSourceEdge"
068   */
069  public static native void setCounterUpSourceEdge(
070      int counterHandle, boolean risingEdge, boolean fallingEdge);
071
072  /**
073   * Disables the up counting source to the counter.
074   *
075   * @param counterHandle the counter handle
076   * @see "HAL_ClearCounterUpSource"
077   */
078  public static native void clearCounterUpSource(int counterHandle);
079
080  /**
081   * Sets the source object that causes the counter to count down.
082   *
083   * @param counterHandle the counter handle
084   * @param digitalSourceHandle the digital source handle (either a HAL_AnalogTriggerHandle or a
085   *     HAL_DigitalHandle)
086   * @param analogTriggerType the analog trigger type if the source is an analog trigger
087   * @see "HAL_SetCounterDownSource"
088   */
089  public static native void setCounterDownSource(
090      int counterHandle, int digitalSourceHandle, int analogTriggerType);
091
092  /**
093   * Sets the down source to either detect rising edges or falling edges. Note that both are allowed
094   * to be set true at the same time without issues.
095   *
096   * @param counterHandle the counter handle
097   * @param risingEdge true to trigger on rising
098   * @param fallingEdge true to trigger on falling
099   * @see "HAL_SetCounterDownSourceEdge"
100   */
101  public static native void setCounterDownSourceEdge(
102      int counterHandle, boolean risingEdge, boolean fallingEdge);
103
104  /**
105   * Disables the down counting source to the counter.
106   *
107   * @param counterHandle the counter handle
108   * @see "HAL_ClearCounterDownSource"
109   */
110  public static native void clearCounterDownSource(int counterHandle);
111
112  /**
113   * Sets standard up / down counting mode on this counter.
114   *
115   * <p>Up and down counts are sourced independently from two inputs.
116   *
117   * @param counterHandle the counter handle
118   * @see "HAL_SetCounterUpDownMode"
119   */
120  public static native void setCounterUpDownMode(int counterHandle);
121
122  /**
123   * Sets directional counting mode on this counter.
124   *
125   * <p>The direction is determined by the B input, with counting happening with the A input.
126   *
127   * @param counterHandle the counter handle
128   * @see "HAL_SetCounterExternalDirectionMode"
129   */
130  public static native void setCounterExternalDirectionMode(int counterHandle);
131
132  /**
133   * Sets Semi-period mode on this counter.
134   *
135   * <p>The counter counts up based on the time the input is triggered. High or Low depends on the
136   * highSemiPeriod parameter.
137   *
138   * @param counterHandle the counter handle
139   * @param highSemiPeriod true for counting when the input is high, false for low
140   * @see "HAL_SetCounterSemiPeriodMode"
141   */
142  public static native void setCounterSemiPeriodMode(int counterHandle, boolean highSemiPeriod);
143
144  /**
145   * Configures the counter to count in up or down based on the length of the input pulse.
146   *
147   * <p>This mode is most useful for direction sensitive gear tooth sensors.
148   *
149   * @param counterHandle the counter handle
150   * @param threshold The pulse length beyond which the counter counts the opposite direction
151   *     (seconds)
152   * @see "HAL_SetCounterPulseLengthMode"
153   */
154  public static native void setCounterPulseLengthMode(int counterHandle, double threshold);
155
156  /**
157   * Gets the Samples to Average which specifies the number of samples of the timer to average when
158   * calculating the period. Perform averaging to account for mechanical imperfections or as
159   * oversampling to increase resolution.
160   *
161   * @param counterHandle the counter handle
162   * @return SamplesToAverage The number of samples being averaged (from 1 to 127)
163   * @see "HAL_GetCounterSamplesToAverage"
164   */
165  public static native int getCounterSamplesToAverage(int counterHandle);
166
167  /**
168   * Sets the Samples to Average which specifies the number of samples of the timer to average when
169   * calculating the period. Perform averaging to account for mechanical imperfections or as
170   * oversampling to increase resolution.
171   *
172   * @param counterHandle the counter handle
173   * @param samplesToAverage The number of samples to average from 1 to 127
174   * @see "HAL_SetCounterSamplesToAverage"
175   */
176  public static native void setCounterSamplesToAverage(int counterHandle, int samplesToAverage);
177
178  /**
179   * Resets the Counter to zero.
180   *
181   * <p>Sets the counter value to zero. This does not effect the running state of the counter, just
182   * sets the current value to zero.
183   *
184   * @param counterHandle the counter handle
185   * @see "HAL_ResetCounter"
186   */
187  public static native void resetCounter(int counterHandle);
188
189  /**
190   * Reads the current counter value.
191   *
192   * <p>Reads the value at this instant. It may still be running, so it reflects the current value.
193   * Next time it is read, it might have a different value.
194   *
195   * @param counterHandle the counter handle
196   * @return the current counter value
197   * @see "HAL_GetCounter"
198   */
199  public static native int getCounter(int counterHandle);
200
201  /**
202   * Gets the Period of the most recent count.
203   *
204   * <p>Returns the time interval of the most recent count. This can be used for velocity
205   * calculations to determine shaft speed.
206   *
207   * @param counterHandle the counter handle
208   * @return the period of the last two pulses in units of seconds
209   * @see "HAL_GetCounterPeriod"
210   */
211  public static native double getCounterPeriod(int counterHandle);
212
213  /**
214   * Sets the maximum period where the device is still considered "moving".
215   *
216   * <p>Sets the maximum period where the device is considered moving. This value is used to
217   * determine the "stopped" state of the counter using the HAL_GetCounterStopped method.
218   *
219   * @param counterHandle the counter handle
220   * @param maxPeriod the maximum period where the counted device is considered moving in seconds
221   * @see "HAL_SetCounterMaxPeriod"
222   */
223  public static native void setCounterMaxPeriod(int counterHandle, double maxPeriod);
224
225  /**
226   * Selects whether you want to continue updating the event timer output when there are no samples
227   * captured.
228   *
229   * <p>The output of the event timer has a buffer of periods that are averaged and posted to a
230   * register on the FPGA. When the timer detects that the event source has stopped (based on the
231   * MaxPeriod) the buffer of samples to be averaged is emptied.
232   *
233   * <p>If you enable the update when empty, you will be notified of the stopped source and the
234   * event time will report 0 samples.
235   *
236   * <p>If you disable update when empty, the most recent average will remain on the output until a
237   * new sample is acquired.
238   *
239   * <p>You will never see 0 samples output (except when there have been no events since an FPGA
240   * reset) and you will likely not see the stopped bit become true (since it is updated at the end
241   * of an average and there are no samples to average).
242   *
243   * @param counterHandle the counter handle
244   * @param enabled true to enable counter updating with no samples
245   * @see "HAL_SetCounterUpdateWhenEmpty"
246   */
247  public static native void setCounterUpdateWhenEmpty(int counterHandle, boolean enabled);
248
249  /**
250   * Determines if the clock is stopped.
251   *
252   * <p>Determine if the clocked input is stopped based on the MaxPeriod value set using the
253   * SetMaxPeriod method. If the clock exceeds the MaxPeriod, then the device (and counter) are
254   * assumed to be stopped and it returns true.
255   *
256   * @param counterHandle the counter handle
257   * @return true if the most recent counter period exceeds the MaxPeriod value set by SetMaxPeriod
258   * @see "HAL_GetCounterStopped"
259   */
260  public static native boolean getCounterStopped(int counterHandle);
261
262  /**
263   * Gets the last direction the counter value changed.
264   *
265   * @param counterHandle the counter handle
266   * @return the last direction the counter value changed
267   * @see "HAL_GetCounterDirection"
268   */
269  public static native boolean getCounterDirection(int counterHandle);
270
271  /**
272   * Sets the Counter to return reversed sensing on the direction.
273   *
274   * <p>This allows counters to change the direction they are counting in the case of 1X and 2X
275   * quadrature encoding only. Any other counter mode isn't supported.
276   *
277   * @param counterHandle the counter handle
278   * @param reverseDirection true if the value counted should be negated.
279   * @see "HAL_SetCounterReverseDirection"
280   */
281  public static native void setCounterReverseDirection(int counterHandle, boolean reverseDirection);
282
283  /** Utility class. */
284  private CounterJNI() {}
285}