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 * Analog Input / Output / Trigger JNI Functions.
009 *
010 * @see "hal/AnalogInput.h"
011 */
012public class AnalogJNI extends JNIWrapper {
013  /**
014   * Initializes the analog input port using the given port object.
015   *
016   * @param channel The smartio channel.
017   * @return the created analog input handle
018   * @see "HAL_InitializeAnalogInputPort"
019   */
020  public static native int initializeAnalogInputPort(int channel);
021
022  /**
023   * Frees an analog input port.
024   *
025   * @param analogPortHandle Handle to the analog port.
026   * @see "HAL_FreeAnalogInputPort"
027   */
028  public static native void freeAnalogInputPort(int analogPortHandle);
029
030  /**
031   * Checks that the analog module number is valid.
032   *
033   * @param module The analog module number.
034   * @return Analog module is valid and present
035   * @see "HAL_CheckAnalogModule"
036   */
037  public static native boolean checkAnalogModule(byte module);
038
039  /**
040   * Checks that the analog output channel number is valid. Verifies that the analog channel number
041   * is one of the legal channel numbers. Channel numbers are 0-based.
042   *
043   * @param channel The analog output channel number.
044   * @return Analog channel is valid
045   * @see "HAL_CheckAnalogInputChannel"
046   */
047  public static native boolean checkAnalogInputChannel(int channel);
048
049  /**
050   * Indicates the analog input is used by a simulated device.
051   *
052   * @param handle the analog input handle
053   * @param device simulated device handle
054   * @see "HAL_SetAnalogInputSimDevice"
055   */
056  public static native void setAnalogInputSimDevice(int handle, int device);
057
058  /**
059   * Sets the sample rate.
060   *
061   * <p>This is a global setting for the Athena and effects all channels.
062   *
063   * @param samplesPerSecond The number of samples per channel per second.
064   * @see "HAL_SetAnalogSampleRate"
065   */
066  public static native void setAnalogSampleRate(double samplesPerSecond);
067
068  /**
069   * Gets the current sample rate.
070   *
071   * <p>This assumes one entry in the scan list. This is a global setting for the Athena and effects
072   * all channels.
073   *
074   * @return Sample rate.
075   * @see "HAL_GetAnalogSampleRate"
076   */
077  public static native double getAnalogSampleRate();
078
079  /**
080   * Sets the number of averaging bits.
081   *
082   * <p>This sets the number of averaging bits. The actual number of averaged samples is 2**bits.
083   * Use averaging to improve the stability of your measurement at the expense of sampling rate. The
084   * averaging is done automatically in the FPGA.
085   *
086   * @param analogPortHandle Handle to the analog port to configure.
087   * @param bits Number of bits to average.
088   * @see "HAL_SetAnalogAverageBits"
089   */
090  public static native void setAnalogAverageBits(int analogPortHandle, int bits);
091
092  /**
093   * Gets the number of averaging bits.
094   *
095   * <p>This gets the number of averaging bits from the FPGA. The actual number of averaged samples
096   * is 2**bits. The averaging is done automatically in the FPGA.
097   *
098   * @param analogPortHandle Handle to the analog port to use.
099   * @return Bits to average.
100   * @see "HAL_GetAnalogAverageBits"
101   */
102  public static native int getAnalogAverageBits(int analogPortHandle);
103
104  /**
105   * Sets the number of oversample bits.
106   *
107   * <p>This sets the number of oversample bits. The actual number of oversampled values is 2**bits.
108   * Use oversampling to improve the resolution of your measurements at the expense of sampling
109   * rate. The oversampling is done automatically in the FPGA.
110   *
111   * @param analogPortHandle Handle to the analog port to use.
112   * @param bits Number of bits to oversample.
113   * @see "HAL_SetAnalogOversampleBits"
114   */
115  public static native void setAnalogOversampleBits(int analogPortHandle, int bits);
116
117  /**
118   * Gets the number of oversample bits.
119   *
120   * <p>This gets the number of oversample bits from the FPGA. The actual number of oversampled
121   * values is 2**bits. The oversampling is done automatically in the FPGA.
122   *
123   * @param analogPortHandle Handle to the analog port to use.
124   * @return Bits to oversample.
125   * @see "HAL_GetAnalogOversampleBits"
126   */
127  public static native int getAnalogOversampleBits(int analogPortHandle);
128
129  /**
130   * Gets a sample straight from the channel on this module.
131   *
132   * <p>The sample is a 12-bit value representing the 0V to 3.3V range of the A/D converter in the
133   * module. The units are in A/D converter codes. Use GetVoltage() to get the analog value in
134   * calibrated units.
135   *
136   * @param analogPortHandle Handle to the analog port to use.
137   * @return A sample straight from the channel on this module.
138   * @see "HAL_GetAnalogValue"
139   */
140  public static native short getAnalogValue(int analogPortHandle);
141
142  /**
143   * Gets a sample from the output of the oversample and average engine for the channel.
144   *
145   * <p>The sample is 12-bit + the value configured in SetOversampleBits(). The value configured in
146   * SetAverageBits() will cause this value to be averaged 2**bits number of samples. This is not a
147   * sliding window. The sample will not change until 2**(OversampleBits + AverageBits) samples have
148   * been acquired from the module on this channel. Use GetAverageVoltage() to get the analog value
149   * in calibrated units.
150   *
151   * @param analogPortHandle Handle to the analog port to use.
152   * @return A sample from the oversample and average engine for the channel.
153   * @see "HAL_GetAnalogAverageValue"
154   */
155  public static native int getAnalogAverageValue(int analogPortHandle);
156
157  /**
158   * Converts a voltage to a raw value for a specified channel.
159   *
160   * <p>This process depends on the calibration of each channel, so the channel must be specified.
161   *
162   * <p>todo This assumes raw values. Oversampling not supported as is.
163   *
164   * @param analogPortHandle Handle to the analog port to use.
165   * @param voltage The voltage to convert.
166   * @return The raw value for the channel.
167   * @see "HAL_GetAnalogVoltsToValue"
168   */
169  public static native int getAnalogVoltsToValue(int analogPortHandle, double voltage);
170
171  /**
172   * Get the analog voltage from a raw value.
173   *
174   * @param analogPortHandle Handle to the analog port the values were read from.
175   * @param value The raw analog value
176   * @return The voltage relating to the value
177   * @see "HAL_GetAnalogValueToVolts"
178   */
179  public static native double getAnalogValueToVolts(int analogPortHandle, int value);
180
181  /**
182   * Gets a scaled sample straight from the channel on this module.
183   *
184   * <p>The value is scaled to units of Volts using the calibrated scaling data from GetLSBWeight()
185   * and GetOffset().
186   *
187   * @param analogPortHandle Handle to the analog port to use.
188   * @return A scaled sample straight from the channel on this module.
189   * @see "HAL_GetAnalogVoltage"
190   */
191  public static native double getAnalogVoltage(int analogPortHandle);
192
193  /**
194   * Gets a scaled sample from the output of the oversample and average engine for the channel.
195   *
196   * <p>The value is scaled to units of Volts using the calibrated scaling data from GetLSBWeight()
197   * and GetOffset(). Using oversampling will cause this value to be higher resolution, but it will
198   * update more slowly. Using averaging will cause this value to be more stable, but it will update
199   * more slowly.
200   *
201   * @param analogPortHandle Handle to the analog port to use.
202   * @return A scaled sample from the output of the oversample and average engine for the channel.
203   * @see "HAL_GetAnalogAverageVoltage"
204   */
205  public static native double getAnalogAverageVoltage(int analogPortHandle);
206
207  /**
208   * Gets the factory scaling least significant bit weight constant. The least significant bit
209   * weight constant for the channel that was calibrated in manufacturing and stored in an eeprom in
210   * the module.
211   *
212   * <p>Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
213   *
214   * @param analogPortHandle Handle to the analog port to use.
215   * @return Least significant bit weight.
216   * @see "HAL_GetAnalogLSBWeight"
217   */
218  public static native int getAnalogLSBWeight(int analogPortHandle);
219
220  /**
221   * Gets the factory scaling offset constant. The offset constant for the channel that was
222   * calibrated in manufacturing and stored in an eeprom in the module.
223   *
224   * <p>Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
225   *
226   * @param analogPortHandle Handle to the analog port to use.
227   * @return Offset constant.
228   * @see "HAL_GetAnalogOffset"
229   */
230  public static native int getAnalogOffset(int analogPortHandle);
231
232  /** Utility class. */
233  private AnalogJNI() {}
234}