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/**
007 * Analog Input / Output / Accumulator / Trigger JNI Functions.
008 *
009 * @see "hal/AnalogInput.h"
010 * @see "hal/AnalogOutput.h"
011 * @see "hal/AnalogAccumulator.h"
012 * @see "hal/AnalogTrigger.h"
013 */
014public class AnalogJNI extends JNIWrapper {
015  /**
016   * <i>native declaration : AthenaJava\target\native\include\HAL\Analog.h:58</i><br>
017   * enum values
018   */
019  public interface AnalogTriggerType {
020    /** <i>native declaration : AthenaJava\target\native\include\HAL\Analog.h:54</i> */
021    int kInWindow = 0;
022    /** <i>native declaration : AthenaJava\target\native\include\HAL\Analog.h:55</i> */
023    int kState = 1;
024    /** <i>native declaration : AthenaJava\target\native\include\HAL\Analog.h:56</i> */
025    int kRisingPulse = 2;
026    /** <i>native declaration : AthenaJava\target\native\include\HAL\Analog.h:57</i> */
027    int kFallingPulse = 3;
028  }
029
030  /**
031   * Initializes the analog input port using the given port object.
032   *
033   * @param halPortHandle Handle to the port to initialize.
034   * @return the created analog input handle
035   * @see "HAL_InitializeAnalogInputPort"
036   */
037  public static native int initializeAnalogInputPort(int halPortHandle);
038
039  /**
040   * Frees an analog input port.
041   *
042   * @param portHandle Handle to the analog port.
043   * @see "HAL_FreeAnalogInputPort"
044   */
045  public static native void freeAnalogInputPort(int portHandle);
046
047  /**
048   * Initializes the analog output port using the given port object.
049   *
050   * @param halPortHandle handle to the port
051   * @return the created analog output handle
052   * @see "HAL_InitializeAnalogOutputPort"
053   */
054  public static native int initializeAnalogOutputPort(int halPortHandle);
055  /**
056   * Frees an analog output port.
057   *
058   * @param portHandle the analog output handle
059   * @see "HAL_FreeAnalogOutputPort"
060   */
061  public static native void freeAnalogOutputPort(int portHandle);
062
063  /**
064   * Checks that the analog module number is valid.
065   *
066   * @param module The analog module number.
067   * @return Analog module is valid and present
068   * @see "HAL_CheckAnalogModule"
069   */
070  public static native boolean checkAnalogModule(byte module);
071
072  /**
073   * Checks that the analog output channel number is valid. Verifies that the analog channel number
074   * is one of the legal channel numbers. Channel numbers are 0-based.
075   *
076   * @param channel The analog output channel number.
077   * @return Analog channel is valid
078   * @see "HAL_CheckAnalogInputChannel"
079   */
080  public static native boolean checkAnalogInputChannel(int channel);
081
082  public static native boolean checkAnalogOutputChannel(int channel);
083
084  /**
085   * Indicates the analog input is used by a simulated device.
086   *
087   * @param handle the analog input handle
088   * @param device simulated device handle
089   * @see "HAL_SetAnalogInputSimDevice"
090   */
091  public static native void setAnalogInputSimDevice(int handle, int device);
092
093  public static native void setAnalogOutput(int portHandle, double voltage);
094
095  public static native double getAnalogOutput(int portHandle);
096
097  /**
098   * Sets the sample rate.
099   *
100   * <p>This is a global setting for the Athena and effects all channels.
101   *
102   * @param samplesPerSecond The number of samples per channel per second.
103   * @see "HAL_SetAnalogSampleRate"
104   */
105  public static native void setAnalogSampleRate(double samplesPerSecond);
106
107  /**
108   * Gets the current sample rate.
109   *
110   * <p>This assumes one entry in the scan list. This is a global setting for the Athena and effects
111   * all channels.
112   *
113   * @return Sample rate.
114   * @see "HAL_GetAnalogSampleRate"
115   */
116  public static native double getAnalogSampleRate();
117
118  /**
119   * Sets the number of averaging bits.
120   *
121   * <p>This sets the number of averaging bits. The actual number of averaged samples is 2**bits.
122   * Use averaging to improve the stability of your measurement at the expense of sampling rate. The
123   * averaging is done automatically in the FPGA.
124   *
125   * @param analogPortHandle Handle to the analog port to configure.
126   * @param bits Number of bits to average.
127   * @see "HAL_SetAnalogAverageBits"
128   */
129  public static native void setAnalogAverageBits(int analogPortHandle, int bits);
130
131  /**
132   * Gets the number of averaging bits.
133   *
134   * <p>This gets the number of averaging bits from the FPGA. The actual number of averaged samples
135   * is 2**bits. The averaging is done automatically in the FPGA.
136   *
137   * @param analogPortHandle Handle to the analog port to use.
138   * @return Bits to average.
139   * @see "HAL_GetAnalogAverageBits"
140   */
141  public static native int getAnalogAverageBits(int analogPortHandle);
142
143  /**
144   * Sets the number of oversample bits.
145   *
146   * <p>This sets the number of oversample bits. The actual number of oversampled values is 2**bits.
147   * Use oversampling to improve the resolution of your measurements at the expense of sampling
148   * rate. The oversampling is done automatically in the FPGA.
149   *
150   * @param analogPortHandle Handle to the analog port to use.
151   * @param bits Number of bits to oversample.
152   * @see "HAL_SetAnalogOversampleBits"
153   */
154  public static native void setAnalogOversampleBits(int analogPortHandle, int bits);
155
156  /**
157   * Gets the number of oversample bits.
158   *
159   * <p>This gets the number of oversample bits from the FPGA. The actual number of oversampled
160   * values is 2**bits. The oversampling is done automatically in the FPGA.
161   *
162   * @param analogPortHandle Handle to the analog port to use.
163   * @return Bits to oversample.
164   * @see "HAL_GetAnalogOversampleBits"
165   */
166  public static native int getAnalogOversampleBits(int analogPortHandle);
167
168  /**
169   * Gets a sample straight from the channel on this module.
170   *
171   * <p>The sample is a 12-bit value representing the 0V to 5V range of the A/D converter in the
172   * module. The units are in A/D converter codes. Use GetVoltage() to get the analog value in
173   * calibrated units.
174   *
175   * @param analogPortHandle Handle to the analog port to use.
176   * @return A sample straight from the channel on this module.
177   * @see "HAL_GetAnalogValue"
178   */
179  public static native short getAnalogValue(int analogPortHandle);
180
181  /**
182   * Gets a sample from the output of the oversample and average engine for the channel.
183   *
184   * <p>The sample is 12-bit + the value configured in SetOversampleBits(). The value configured in
185   * SetAverageBits() will cause this value to be averaged 2**bits number of samples. This is not a
186   * sliding window. The sample will not change until 2**(OversampleBits + AverageBits) samples have
187   * been acquired from the module on this channel. Use GetAverageVoltage() to get the analog value
188   * in calibrated units.
189   *
190   * @param analogPortHandle Handle to the analog port to use.
191   * @return A sample from the oversample and average engine for the channel.
192   * @see "HAL_GetAnalogAverageValue"
193   */
194  public static native int getAnalogAverageValue(int analogPortHandle);
195
196  /**
197   * Converts a voltage to a raw value for a specified channel.
198   *
199   * <p>This process depends on the calibration of each channel, so the channel must be specified.
200   *
201   * <p>todo This assumes raw values. Oversampling not supported as is.
202   *
203   * @param analogPortHandle Handle to the analog port to use.
204   * @param voltage The voltage to convert.
205   * @return The raw value for the channel.
206   * @see "HAL_GetAnalogVoltsToValue"
207   */
208  public static native int getAnalogVoltsToValue(int analogPortHandle, double voltage);
209  /**
210   * Get the analog voltage from a raw value.
211   *
212   * @param analogPortHandle Handle to the analog port the values were read from.
213   * @param value The raw analog value
214   * @return The voltage relating to the value
215   * @see "HAL_GetAnalogValueToVolts"
216   */
217  public static native double getAnalogValueToVolts(int analogPortHandle, int value);
218
219  /**
220   * Gets a scaled sample straight from the channel on this module.
221   *
222   * <p>The value is scaled to units of Volts using the calibrated scaling data from GetLSBWeight()
223   * and GetOffset().
224   *
225   * @param analogPortHandle Handle to the analog port to use.
226   * @return A scaled sample straight from the channel on this module.
227   * @see "HAL_GetAnalogVoltage"
228   */
229  public static native double getAnalogVoltage(int analogPortHandle);
230
231  /**
232   * Gets a scaled sample from the output of the oversample and average engine for the channel.
233   *
234   * <p>The value is scaled to units of Volts using the calibrated scaling data from GetLSBWeight()
235   * and GetOffset(). Using oversampling will cause this value to be higher resolution, but it will
236   * update more slowly. Using averaging will cause this value to be more stable, but it will update
237   * more slowly.
238   *
239   * @param analogPortHandle Handle to the analog port to use.
240   * @return A scaled sample from the output of the oversample and average engine for the channel.
241   * @see "HAL_GetAnalogAverageVoltage"
242   */
243  public static native double getAnalogAverageVoltage(int analogPortHandle);
244
245  /**
246   * Gets the factory scaling least significant bit weight constant. The least significant bit
247   * weight constant for the channel that was calibrated in manufacturing and stored in an eeprom in
248   * the module.
249   *
250   * <p>Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
251   *
252   * @param analogPortHandle Handle to the analog port to use.
253   * @return Least significant bit weight.
254   * @see "HAL_GetAnalogLSBWeight"
255   */
256  public static native int getAnalogLSBWeight(int analogPortHandle);
257
258  /**
259   * Gets the factory scaling offset constant. The offset constant for the channel that was
260   * calibrated in manufacturing and stored in an eeprom in the module.
261   *
262   * <p>Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
263   *
264   * @param analogPortHandle Handle to the analog port to use.
265   * @return Offset constant.
266   * @see "HAL_GetAnalogOffset"
267   */
268  public static native int getAnalogOffset(int analogPortHandle);
269
270  /**
271   * Is the channel attached to an accumulator.
272   *
273   * @param analogPortHandle Handle to the analog port.
274   * @return The analog channel is attached to an accumulator.
275   * @see "HAL_IsAccumulatorChannel"
276   */
277  public static native boolean isAccumulatorChannel(int analogPortHandle);
278
279  /**
280   * Initialize the accumulator.
281   *
282   * @param analogPortHandle Handle to the analog port.
283   * @see "HAL_InitAccumulator"
284   */
285  public static native void initAccumulator(int analogPortHandle);
286
287  /**
288   * Resets the accumulator to the initial value.
289   *
290   * @param analogPortHandle Handle to the analog port.
291   * @see "HAL_ResetAccumulator"
292   */
293  public static native void resetAccumulator(int analogPortHandle);
294
295  /**
296   * Set the center value of the accumulator.
297   *
298   * <p>The center value is subtracted from each A/D value before it is added to the accumulator.
299   * This is used for the center value of devices like gyros and accelerometers to make integration
300   * work and to take the device offset into account when integrating.
301   *
302   * <p>This center value is based on the output of the oversampled and averaged source from channel
303   * 1. Because of this, any non-zero oversample bits will affect the size of the value for this
304   * field.
305   *
306   * @param analogPortHandle Handle to the analog port.
307   * @param center The center value of the accumulator.
308   * @see "HAL_SetAccumulatorCenter"
309   */
310  public static native void setAccumulatorCenter(int analogPortHandle, int center);
311
312  /**
313   * Set the accumulator's deadband.
314   *
315   * @param analogPortHandle Handle to the analog port.
316   * @param deadband The deadband of the accumulator.
317   * @see "HAL_SetAccumulatorDeadband"
318   */
319  public static native void setAccumulatorDeadband(int analogPortHandle, int deadband);
320
321  /**
322   * Read the accumulated value.
323   *
324   * <p>Read the value that has been accumulating on channel 1. The accumulator is attached after
325   * the oversample and average engine.
326   *
327   * @param analogPortHandle Handle to the analog port.
328   * @return The 64-bit value accumulated since the last Reset().
329   * @see "HAL_GetAccumulatorValue"
330   */
331  public static native long getAccumulatorValue(int analogPortHandle);
332
333  /**
334   * Read the number of accumulated values.
335   *
336   * <p>Read the count of the accumulated values since the accumulator was last Reset().
337   *
338   * @param analogPortHandle Handle to the analog port.
339   * @return The number of times samples from the channel were accumulated.
340   * @see "HAL_GetAccumulatorCount"
341   */
342  public static native int getAccumulatorCount(int analogPortHandle);
343
344  /**
345   * Read the accumulated value and the number of accumulated values atomically.
346   *
347   * <p>This function reads the value and count from the FPGA atomically. This can be used for
348   * averaging.
349   *
350   * @param analogPortHandle Handle to the analog port.
351   * @param result Accumulator result.
352   * @see "HAL_GetAccumulatorOutput"
353   */
354  public static native void getAccumulatorOutput(int analogPortHandle, AccumulatorResult result);
355
356  /**
357   * Initializes an analog trigger.
358   *
359   * @param analogInputHandle the analog input to use for triggering
360   * @return the created analog trigger handle
361   * @see "HAL_InitializeAnalogTrigger"
362   */
363  public static native int initializeAnalogTrigger(int analogInputHandle);
364
365  /**
366   * Initializes an analog trigger with a Duty Cycle input.
367   *
368   * @param dutyCycleHandle the analog input to use for duty cycle
369   * @return tbe created analog trigger handle
370   * @see "HAL_InitializeAnalogTriggerDutyCycle"
371   */
372  public static native int initializeAnalogTriggerDutyCycle(int dutyCycleHandle);
373
374  /**
375   * Frees an analog trigger.
376   *
377   * @param analogTriggerHandle the trigger handle
378   * @see "HAL_CleanAnalogTrigger"
379   */
380  public static native void cleanAnalogTrigger(int analogTriggerHandle);
381
382  /**
383   * Sets the raw ADC upper and lower limits of the analog trigger.
384   *
385   * <p>HAL_SetAnalogTriggerLimitsVoltage or HAL_SetAnalogTriggerLimitsDutyCycle is likely better in
386   * most cases.
387   *
388   * @param analogTriggerHandle the trigger handle
389   * @param lower the lower ADC value
390   * @param upper the upper ADC value
391   * @see "HAL_SetAnalogTriggerLimitsRaw"
392   */
393  public static native void setAnalogTriggerLimitsRaw(
394      int analogTriggerHandle, int lower, int upper);
395
396  /**
397   * Sets the upper and lower limits of the analog trigger.
398   *
399   * <p>The limits are given as floating point duty cycle values.
400   *
401   * @param analogTriggerHandle the trigger handle
402   * @param lower the lower duty cycle value
403   * @param higher the upper duty cycle value
404   * @see "HAL_SetAnalogTriggerLimitsDutyCycle"
405   */
406  public static native void setAnalogTriggerLimitsDutyCycle(
407      int analogTriggerHandle, double lower, double higher);
408
409  /**
410   * Sets the upper and lower limits of the analog trigger.
411   *
412   * <p>The limits are given as floating point voltage values.
413   *
414   * @param analogTriggerHandle the trigger handle
415   * @param lower the lower voltage value
416   * @param upper the upper voltage value
417   * @see "HAL_SetAnalogTriggerLimitsVoltage"
418   */
419  public static native void setAnalogTriggerLimitsVoltage(
420      int analogTriggerHandle, double lower, double upper);
421  /**
422   * Configures the analog trigger to use the averaged vs. raw values.
423   *
424   * <p>If the value is true, then the averaged value is selected for the analog trigger, otherwise
425   * the immediate value is used.
426   *
427   * <p>This is not allowed to be used if filtered mode is set. This is not allowed to be used with
428   * Duty Cycle based inputs.
429   *
430   * @param analogTriggerHandle the trigger handle
431   * @param useAveragedValue true to use averaged values, false for raw
432   * @see "HAL_SetAnalogTriggerAveraged"
433   */
434  public static native void setAnalogTriggerAveraged(
435      int analogTriggerHandle, boolean useAveragedValue);
436  /**
437   * Configures the analog trigger to use a filtered value.
438   *
439   * <p>The analog trigger will operate with a 3 point average rejection filter. This is designed to
440   * help with 360 degree pot applications for the period where the pot crosses through zero.
441   *
442   * <p>This is not allowed to be used if averaged mode is set.
443   *
444   * @param analogTriggerHandle the trigger handle
445   * @param useFilteredValue true to use filtered values, false for average or raw
446   * @see "HAL_SetAnalogTriggerFiltered"
447   */
448  public static native void setAnalogTriggerFiltered(
449      int analogTriggerHandle, boolean useFilteredValue);
450
451  /**
452   * Returns the InWindow output of the analog trigger.
453   *
454   * <p>True if the analog input is between the upper and lower limits.
455   *
456   * @param analogTriggerHandle the trigger handle
457   * @return the InWindow output of the analog trigger
458   * @see "HAL_GetAnalogTriggerInWindow"
459   */
460  public static native boolean getAnalogTriggerInWindow(int analogTriggerHandle);
461
462  /**
463   * Returns the TriggerState output of the analog trigger.
464   *
465   * <p>True if above upper limit. False if below lower limit. If in Hysteresis, maintain previous
466   * state.
467   *
468   * @param analogTriggerHandle the trigger handle
469   * @return the TriggerState output of the analog trigger
470   * @see "HAL_GetAnalogTriggerTriggerState"
471   */
472  public static native boolean getAnalogTriggerTriggerState(int analogTriggerHandle);
473
474  /**
475   * Gets the state of the analog trigger output.
476   *
477   * @param analogTriggerHandle the trigger handle
478   * @param type the type of trigger to trigger on
479   * @return the state of the analog trigger output
480   * @see "HAL_GetAnalogTriggerOutput"
481   */
482  public static native boolean getAnalogTriggerOutput(int analogTriggerHandle, int type);
483
484  /**
485   * Get the FPGA index for the AnlogTrigger.
486   *
487   * @param analogTriggerHandle the trigger handle
488   * @return the FPGA index
489   * @see "HAL_GetAnalogTriggerFPGAIndex"
490   */
491  public static native int getAnalogTriggerFPGAIndex(int analogTriggerHandle);
492}