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}