1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.
#pragma once
#include <stdint.h>
#include "hal/Types.h"
/**
* @defgroup hal_analoginput Analog Input Functions
* @ingroup hal_capi
* @{
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* Initializes the analog input port using the given port object.
*
* @param[in] portHandle Handle to the port to initialize.
* @param[in] allocationLocation the location where the allocation is occurring
* (can be null)
* @param[out] status the error code, or 0 for success
* @return the created analog input handle
*/
HAL_AnalogInputHandle HAL_InitializeAnalogInputPort(
HAL_PortHandle portHandle, const char* allocationLocation, int32_t* status);
/**
* Frees an analog input port.
*
* @param analogPortHandle Handle to the analog port.
*/
void HAL_FreeAnalogInputPort(HAL_AnalogInputHandle analogPortHandle);
/**
* Checks that the analog module number is valid.
*
* @param[in] module The analog module number.
* @return Analog module is valid and present
*/
HAL_Bool HAL_CheckAnalogModule(int32_t module);
/**
* Checks that the analog output channel number is valid.
* Verifies that the analog channel number is one of the legal channel numbers.
* Channel numbers are 0-based.
*
* @param[in] channel The analog output channel number.
* @return Analog channel is valid
*/
HAL_Bool HAL_CheckAnalogInputChannel(int32_t channel);
/**
* Indicates the analog input is used by a simulated device.
*
* @param handle the analog input handle
* @param device simulated device handle
*/
void HAL_SetAnalogInputSimDevice(HAL_AnalogInputHandle handle,
HAL_SimDeviceHandle device);
/**
* Sets the sample rate.
*
* This is a global setting for the Athena and effects all channels.
*
* @param[in] samplesPerSecond The number of samples per channel per second.
* @param[out] status the error code, or 0 for success
*/
void HAL_SetAnalogSampleRate(double samplesPerSecond, int32_t* status);
/**
* Gets the current sample rate.
*
* This assumes one entry in the scan list.
* This is a global setting for the Athena and effects all channels.
*
* @param[out] status the error code, or 0 for success
* @return Sample rate.
*/
double HAL_GetAnalogSampleRate(int32_t* status);
/**
* Sets the number of averaging bits.
*
* This sets the number of averaging bits. The actual number of averaged samples
* is 2**bits. Use averaging to improve the stability of your measurement at the
* expense of sampling rate. The averaging is done automatically in the FPGA.
*
* @param[in] analogPortHandle Handle to the analog port to configure.
* @param[in] bits Number of bits to average.
* @param[out] status the error code, or 0 for success
*/
void HAL_SetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle,
int32_t bits, int32_t* status);
/**
* Gets the number of averaging bits.
*
* This gets the number of averaging bits from the FPGA. The actual number of
* averaged samples is 2**bits. The averaging is done automatically in the FPGA.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return Bits to average.
*/
int32_t HAL_GetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Sets the number of oversample bits.
*
* This sets the number of oversample bits. The actual number of oversampled
* values is 2**bits. Use oversampling to improve the resolution of your
* measurements at the expense of sampling rate. The oversampling is done
* automatically in the FPGA.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[in] bits Number of bits to oversample.
* @param[out] status the error code, or 0 for success
*/
void HAL_SetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle,
int32_t bits, int32_t* status);
/**
* Gets the number of oversample bits.
*
* This gets the number of oversample bits from the FPGA. The actual number of
* oversampled values is 2**bits. The oversampling is done automatically in the
* FPGA.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return Bits to oversample.
*/
int32_t HAL_GetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Gets a sample straight from the channel on this module.
*
* The sample is a 12-bit value representing the 0V to 5V range of the A/D
* converter in the module. The units are in A/D converter codes. Use
* GetVoltage() to get the analog value in calibrated units.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return A sample straight from the channel on this module.
*/
int32_t HAL_GetAnalogValue(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Gets a sample from the output of the oversample and average engine for the
* channel.
*
* The sample is 12-bit + the value configured in SetOversampleBits().
* The value configured in SetAverageBits() will cause this value to be averaged
* 2**bits number of samples. This is not a sliding window. The sample will not
* change until 2**(OversampleBits + AverageBits) samples have been acquired
* from the module on this channel. Use GetAverageVoltage() to get the analog
* value in calibrated units.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return A sample from the oversample and average engine for the channel.
*/
int32_t HAL_GetAnalogAverageValue(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Converts a voltage to a raw value for a specified channel.
*
* This process depends on the calibration of each channel, so the channel must
* be specified.
*
* @todo This assumes raw values. Oversampling not supported as is.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[in] voltage The voltage to convert.
* @param[out] status the error code, or 0 for success
* @return The raw value for the channel.
*/
int32_t HAL_GetAnalogVoltsToValue(HAL_AnalogInputHandle analogPortHandle,
double voltage, int32_t* status);
/**
* Gets a scaled sample straight from the channel on this module.
*
* The value is scaled to units of Volts using the calibrated scaling data from
* GetLSBWeight() and GetOffset().
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return A scaled sample straight from the channel on this module.
*/
double HAL_GetAnalogVoltage(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Gets a scaled sample from the output of the oversample and average engine for
* the channel.
*
* The value is scaled to units of Volts using the calibrated scaling data from
* GetLSBWeight() and GetOffset(). Using oversampling will cause this value to
* be higher resolution, but it will update more slowly. Using averaging will
* cause this value to be more stable, but it will update more slowly.
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return A scaled sample from the output of the oversample and average engine
* for the channel.
*/
double HAL_GetAnalogAverageVoltage(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Gets the factory scaling least significant bit weight constant.
* The least significant bit weight constant for the channel that was calibrated
* in manufacturing and stored in an eeprom in the module.
*
* Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status the error code, or 0 for success
* @return Least significant bit weight.
*/
int32_t HAL_GetAnalogLSBWeight(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Gets the factory scaling offset constant.
* The offset constant for the channel that was calibrated in manufacturing and
* stored in an eeprom in the module.
*
* Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9)
*
* @param[in] analogPortHandle Handle to the analog port to use.
* @param[out] status Error status variable. 0 on success.
* @return Offset constant.
*/
int32_t HAL_GetAnalogOffset(HAL_AnalogInputHandle analogPortHandle,
int32_t* status);
/**
* Get the analog voltage from a raw value.
*
* @param[in] analogPortHandle Handle to the analog port the values were read
* from.
* @param[in] rawValue The raw analog value
* @param[out] status Error status variable. 0 on success.
* @return The voltage relating to the value
*/
double HAL_GetAnalogValueToVolts(HAL_AnalogInputHandle analogPortHandle,
int32_t rawValue, int32_t* status);
#ifdef __cplusplus
} // extern "C"
#endif
/** @} */