Analog Inputs - Software¶
This section covers analog inputs in software. For a hardware guide to analog inputs, see Analog Inputs - Hardware.
The roboRIO’s FPGA supports up to 8 analog input channels that can be used to read the value of an analog voltage from a sensor. Analog inputs may be used for any sensor that outputs a simple voltage.
Analog inputs from the FPGA by default return a 12-bit integer proportional to the voltage, from 0 to 5 volts.
The AnalogInput class¶
It is often more convenient to use the Analog Potentiometers wrapper class than to use
AnalogInput directly, as it supports scaling to meaningful units.
Initializing an AnalogInput¶
AnalogInput may be initialized as follows:
Oversampling and Averaging¶
The FPGA’s analog input modules supports both oversampling and averaging. These behaviors are highly similar, but differ in a few important ways. Both may be used at the same time.
When oversampling is enabled, the FPGA will add multiple consecutive samples together, and return the accumulated value. Users may specify the number of bits of oversampling - for bits of oversampling, the number of samples added together is :
Averaging behaves much like oversampling, except the accumulated values are divided by the number of samples so that the scaling of the returned values does not change. This is often more-convenient, but occasionally the additional roundoff error introduced by the rounding is undesirable.
When oversampling and averaging are used at the same time, the oversampling is applied first, and then the oversampled values are averaged. Thus, 2-bit oversampling and 2-bit averaging used at the same time will increase the scale of the returned values by approximately a factor of 2, and decrease the update rate by approximately a factor of 4.
Reading values from an AnalogInput¶
Values can be read from an AnalogInput with one of four different methods:
getValue method returns the raw instantaneous measured value from the analog input, without applying any calibration and ignoring oversampling and averaging settings. The returned value is an integer.
getVoltage method returns the instantaneous measured voltage from the analog input. Oversampling and averaging settings are ignored, but the value is rescaled to represent a voltage. The returned value is a double.
getAverageValue method returns the averaged value from the analog input. The value is not rescaled, but oversampling and averaging are both applied. The returned value is an integer.
getAverageVoltage method returns the averaged voltage from the analog input. Rescaling, oversampling, and averaging are all applied. The returned value is a double.
The accumulator methods do not currently support returning a value in units of volts - the returned value will always be an integer (specifically, a
Analog input channels 0 and 1 additionally support an accumulator, which integrates (adds up) the signal indefinitely, so that the returned value is the sum of all past measured values. Oversampling and averaging are applied prior to accumulation.
Obtaining synchronized count and value¶
Sometimes, it is necessarily to obtain matched measurements of the count and the value. This can be done using the
Using analog inputs in code¶
AnalogInput class can be used to write code for a wide variety of sensors (including potentiometers, accelerometers, gyroscopes, ultrasonics, and more) that return their data as an analog voltage. However, if possible it is almost always more convenient to use one of the other existing WPILib classes that handles the lower-level code (reading the analog voltages and converting them to meaningful units) for you. Users should only directly use
AnalogInput as a “last resort.”
Accordingly, for examples of how to effectively use analog sensors in code, users should refer to the other pages of this chapter that deal with more-specific classes.