WPILibC++ 2024.3.2
AnalogInput.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#include <hal/Types.h>
12
13namespace frc {
14
15class DMA;
16class DMASample;
17
18/**
19 * Analog input class.
20 *
21 * Connected to each analog channel is an averaging and oversampling engine.
22 * This engine accumulates the specified ( by SetAverageBits() and
23 * SetOversampleBits() ) number of samples before returning a new value. This is
24 * not a sliding window average. The only difference between the oversampled
25 * samples and the averaged samples is that the oversampled samples are simply
26 * accumulated effectively increasing the resolution, while the averaged samples
27 * are divided by the number of samples to retain the resolution, but get more
28 * stable values.
29 */
31 public wpi::SendableHelper<AnalogInput> {
32 friend class AnalogTrigger;
33 friend class AnalogGyro;
34 friend class DMA;
35 friend class DMASample;
36
37 public:
38 static constexpr int kAccumulatorModuleNumber = 1;
39 static constexpr int kAccumulatorNumChannels = 2;
40 static constexpr int kAccumulatorChannels[kAccumulatorNumChannels] = {0, 1};
41
42 /**
43 * Construct an analog input.
44 *
45 * @param channel The channel number on the roboRIO to represent. 0-3 are
46 * on-board 4-7 are on the MXP port.
47 */
48 explicit AnalogInput(int channel);
49
50 ~AnalogInput() override;
51
54
55 /**
56 * Get a sample straight from this channel.
57 *
58 * The sample is a 12-bit value representing the 0V to 5V range of the A/D
59 * converter in the module. The units are in A/D converter codes. Use
60 * GetVoltage() to get the analog value in calibrated units.
61 *
62 * @return A sample straight from this channel.
63 */
64 int GetValue() const;
65
66 /**
67 * Get a sample from the output of the oversample and average engine for this
68 * channel.
69 *
70 * The sample is 12-bit + the bits configured in SetOversampleBits().
71 * The value configured in SetAverageBits() will cause this value to be
72 * averaged 2**bits number of samples.
73 *
74 * This is not a sliding window. The sample will not change until
75 * 2**(OversampleBits + AverageBits) samples have been acquired from the
76 * module on this channel.
77 *
78 * Use GetAverageVoltage() to get the analog value in calibrated units.
79 *
80 * @return A sample from the oversample and average engine for this channel.
81 */
82 int GetAverageValue() const;
83
84 /**
85 * Get a scaled sample straight from this channel.
86 *
87 * The value is scaled to units of Volts using the calibrated scaling data
88 * from GetLSBWeight() and GetOffset().
89 *
90 * @return A scaled sample straight from this channel.
91 */
92 double GetVoltage() const;
93
94 /**
95 * Get a scaled sample from the output of the oversample and average engine
96 * for this channel.
97 *
98 * The value is scaled to units of Volts using the calibrated scaling data
99 * from GetLSBWeight() and GetOffset().
100 *
101 * Using oversampling will cause this value to be higher resolution, but it
102 * will update more slowly.
103 *
104 * Using averaging will cause this value to be more stable, but it will update
105 * more slowly.
106 *
107 * @return A scaled sample from the output of the oversample and average
108 * engine for this channel.
109 */
110 double GetAverageVoltage() const;
111
112 /**
113 * Get the channel number.
114 *
115 * @return The channel number.
116 */
117 int GetChannel() const;
118
119 /**
120 * Set the number of averaging bits.
121 *
122 * This sets the number of averaging bits. The actual number of averaged
123 * samples is 2^bits.
124 *
125 * Use averaging to improve the stability of your measurement at the expense
126 * of sampling rate. The averaging is done automatically in the FPGA.
127 *
128 * @param bits Number of bits of averaging.
129 */
131
132 /**
133 * Get the number of averaging bits previously configured.
134 *
135 * This gets the number of averaging bits from the FPGA. The actual number of
136 * averaged samples is 2^bits. The averaging is done automatically in the
137 * FPGA.
138 *
139 * @return Number of bits of averaging previously configured.
140 */
141 int GetAverageBits() const;
142
143 /**
144 * Set the number of oversample bits.
145 *
146 * This sets the number of oversample bits. The actual number of oversampled
147 * values is 2^bits. Use oversampling to improve the resolution of your
148 * measurements at the expense of sampling rate. The oversampling is done
149 * automatically in the FPGA.
150 *
151 * @param bits Number of bits of oversampling.
152 */
154
155 /**
156 * Get the number of oversample bits previously configured.
157 *
158 * This gets the number of oversample bits from the FPGA. The actual number of
159 * oversampled values is 2^bits. The oversampling is done automatically in the
160 * FPGA.
161 *
162 * @return Number of bits of oversampling previously configured.
163 */
164 int GetOversampleBits() const;
165
166 /**
167 * Get the factory scaling least significant bit weight constant.
168 *
169 * Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
170 *
171 * @return Least significant bit weight.
172 */
173 int GetLSBWeight() const;
174
175 /**
176 * Get the factory scaling offset constant.
177 *
178 * Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
179 *
180 * @return Offset constant.
181 */
182 int GetOffset() const;
183
184 /**
185 * Is the channel attached to an accumulator.
186 *
187 * @return The analog input is attached to an accumulator.
188 */
190
191 /**
192 * Initialize the accumulator.
193 */
195
196 /**
197 * Set an initial value for the accumulator.
198 *
199 * This will be added to all values returned to the user.
200 *
201 * @param value The value that the accumulator should start from when reset.
202 */
203 void SetAccumulatorInitialValue(int64_t value);
204
205 /**
206 * Resets the accumulator to the initial value.
207 */
209
210 /**
211 * Set the center value of the accumulator.
212 *
213 * The center value is subtracted from each A/D value before it is added to
214 * the accumulator. This is used for the center value of devices like gyros
215 * and accelerometers to take the device offset into account when integrating.
216 *
217 * This center value is based on the output of the oversampled and averaged
218 * source from the accumulator channel. Because of this, any non-zero
219 * oversample bits will affect the size of the value for this field.
220 */
221 void SetAccumulatorCenter(int center);
222
223 /**
224 * Set the accumulator's deadband.
225 */
226 void SetAccumulatorDeadband(int deadband);
227
228 /**
229 * Read the accumulated value.
230 *
231 * Read the value that has been accumulating.
232 * The accumulator is attached after the oversample and average engine.
233 *
234 * @return The 64-bit value accumulated since the last Reset().
235 */
236 int64_t GetAccumulatorValue() const;
237
238 /**
239 * Read the number of accumulated values.
240 *
241 * Read the count of the accumulated values since the accumulator was last
242 * Reset().
243 *
244 * @return The number of times samples from the channel were accumulated.
245 */
246 int64_t GetAccumulatorCount() const;
247
248 /**
249 * Read the accumulated value and the number of accumulated values atomically.
250 *
251 * This function reads the value and count from the FPGA atomically.
252 * This can be used for averaging.
253 *
254 * @param value Reference to the 64-bit accumulated output.
255 * @param count Reference to the number of accumulation cycles.
256 */
257 void GetAccumulatorOutput(int64_t& value, int64_t& count) const;
258
259 /**
260 * Set the sample rate per channel for all analog channels.
261 *
262 * The maximum rate is 500kS/s divided by the number of channels in use.
263 * This is 62500 samples/s per channel.
264 *
265 * @param samplesPerSecond The number of samples per second.
266 */
267 static void SetSampleRate(double samplesPerSecond);
268
269 /**
270 * Get the current sample rate for all channels
271 *
272 * @return Sample rate.
273 */
274 static double GetSampleRate();
275
276 /**
277 * Indicates this input is used by a simulated device.
278 *
279 * @param device simulated device handle
280 */
282
283 void InitSendable(wpi::SendableBuilder& builder) override;
284
285 private:
286 int m_channel;
288 int64_t m_accumulatorOffset;
289};
290
291} // namespace frc
Use a rate gyro to return the robots heading relative to a starting position.
Definition: AnalogGyro.h:33
Analog input class.
Definition: AnalogInput.h:31
static void SetSampleRate(double samplesPerSecond)
Set the sample rate per channel for all analog channels.
void SetAccumulatorCenter(int center)
Set the center value of the accumulator.
void InitSendable(wpi::SendableBuilder &builder) override
Initializes this Sendable object.
static constexpr int kAccumulatorNumChannels
Definition: AnalogInput.h:39
double GetAverageVoltage() const
Get a scaled sample from the output of the oversample and average engine for this channel.
void SetSimDevice(HAL_SimDeviceHandle device)
Indicates this input is used by a simulated device.
int64_t GetAccumulatorValue() const
Read the accumulated value.
static double GetSampleRate()
Get the current sample rate for all channels.
void SetAverageBits(int bits)
Set the number of averaging bits.
bool IsAccumulatorChannel() const
Is the channel attached to an accumulator.
static constexpr int kAccumulatorModuleNumber
Definition: AnalogInput.h:38
int GetAverageBits() const
Get the number of averaging bits previously configured.
int GetOffset() const
Get the factory scaling offset constant.
void SetOversampleBits(int bits)
Set the number of oversample bits.
int GetValue() const
Get a sample straight from this channel.
void SetAccumulatorInitialValue(int64_t value)
Set an initial value for the accumulator.
~AnalogInput() override
int GetLSBWeight() const
Get the factory scaling least significant bit weight constant.
void GetAccumulatorOutput(int64_t &value, int64_t &count) const
Read the accumulated value and the number of accumulated values atomically.
static constexpr int kAccumulatorChannels[kAccumulatorNumChannels]
Definition: AnalogInput.h:40
int GetChannel() const
Get the channel number.
AnalogInput & operator=(AnalogInput &&)=default
int GetAverageValue() const
Get a sample from the output of the oversample and average engine for this channel.
int64_t GetAccumulatorCount() const
Read the number of accumulated values.
AnalogInput(AnalogInput &&)=default
void SetAccumulatorDeadband(int deadband)
Set the accumulator's deadband.
double GetVoltage() const
Get a scaled sample straight from this channel.
int GetOversampleBits() const
Get the number of oversample bits previously configured.
void ResetAccumulator()
Resets the accumulator to the initial value.
AnalogInput(int channel)
Construct an analog input.
void InitAccumulator()
Initialize the accumulator.
Definition: AnalogTrigger.h:21
Class for configuring Direct Memory Access (DMA) of FPGA inputs.
Definition: DMA.h:23
DMA sample.
Definition: DMASample.h:23
Helper class for building Sendable dashboard representations.
Definition: SendableBuilder.h:21
A helper class for use with objects that add themselves to SendableRegistry.
Definition: SendableHelper.h:19
Interface for Sendable objects.
Definition: Sendable.h:16
HAL_Handle HAL_SimDeviceHandle
Definition: Types.h:53
constexpr auto count() -> size_t
Definition: core.h:1203
Definition: AprilTagPoseEstimator.h:15
bits
Definition: data.h:44