Analog input support

Functions
void	HuboLib::Set_VRef (double volt)
	Set the reference voltage value for the ADC. More...
double	HuboLib::Get_VRef ()
	Retrieves the reference voltage value used for ADC count convertion. More...
double	HuboLib::Get_VRef_Raw ()
	Retrieves the reference voltage value used for ADC count convertion. More...
bool	HuboLib::Set_MCP3x08_Oversampling (unsigned short overSampling[MAX_MCP3x08_CHANNELS])
	Specifies the ADC channels to be sampled as well as the number they get oversampled. More...
bool	HuboLib::Get_AI_Channel (int channel, unsigned long &count, double &volt)
	Get the buffered and oversampled data from the MCP3x08. More...
bool	HuboLib::Get_AI_Channel_Raw (int channel, unsigned short &value)
	Gets an unbuffered value from the MCP3x08. More...

Detailed Description

Function Documentation

bool HuboLib::Get_AI_Channel	(	int	channel,
		unsigned long &	count,
		double &	volt
	)

Get the buffered and oversampled data from the MCP3x08.

For a channel being specified a call to Get_AI_Channel() returns the buffered and oversampled ADC counts during the last cycle time. Using the reference voltage as specified by a call to Set_VRef() the voltage of this channel is computed as well.

Parameters

channel	Specifies the analog channel from which to retrieve the data.
count	Contains the oversampled (simply added) ADC counts taken during the last cycle time. Counts are not averaged but just added for the number of times as specified in the oversampling vector.
volt	Contains the voltage as being calculated from the (over-) sampled values taken during the last cycle time.

Returns

The function returns true if the ADC chip was successfully initialized, an oversampling count > 0 was specified for the channel given and the channel is within the allowed range. Otherwise the return value is false.

See also

Set_MCP3x08_Oversampling(), Set_VRef(), Set_Cycle_Time()

For a simple example on how to sample one analog channel refer to the demo AnalogInput1.cpp.
AnalogInput2.cpp illustrates how to increase the resolution by oversampling a channel 4 times.

bool HuboLib::Get_AI_Channel_Raw	(	int	channel,
		unsigned short &	value
	)

Gets an unbuffered value from the MCP3x08.

For a channel being specified a call to Get_AI_Channel_Raw() returns the unbuffered counts of the ADC. While this function requires a proper initialization by a call to Initialize() it does not require any further operations. Since Get_AI_Channel_Raw() bypasses all buffers but directly accesses the hardware instead - it does not need other preceeding operations such as setting the the oversampling array. The function should be used in cases where very fast access to analog values is required (up to 8kHz) which cannot be achieved by further decreasing of the cycle time. This can be handy when trying to follow (or capture) a signal once a certain condition is met. However, remember that the background thread runs at a very high priority likely to prevent the rest of the system from running. So make sure your callback routine is taking this into account.

Parameters

channel	Specifies the analog channel from which to retrieve the data.
value	The analog count of the ADC.

Returns

True if the analog value could be read, otherwise false.

See also

Get_AI_Channel()

For a an example on how to sample raw data refer to the demo AnalogRawInput.cpp.

Note

A call to this function is only allowed from the background thread - hence one of the several callback functions. Do not call this function from any other thread - e.g. the main thread!

double HuboLib::Get_VRef

(

)

Retrieves the reference voltage value used for ADC count convertion.

This function retrieves the reference voltage of the ADC taken into account when calculating an absolut voltage from an ADC count.

Returns

The reference voltage currently being in used for convertion.

See also

Set_VRef(), Get_AI_Channel(), Set_MCP3x08_Oversampling

For an example on how to read and set the reference voltage refer to the demo AnalogInput4.cpp.

double HuboLib::Get_VRef_Raw

(

)

Retrieves the reference voltage value used for ADC count convertion.

This function retrieves the reference voltage of the ADC taken into account when calculating an absolut voltage from an ADC count.

Returns

The reference voltage currently being in used for convertion.

See also

Get_VRef(), Get_AI_Channel_Raw()

For an example on how to read the reference voltage from a callback function refer to the demo AnalogRawInput.cpp.

Note

A call to this function is only allowed from the background thread - hence one of the several callback functions. Do not call this function from any other thread - e.g. the main thread!

bool HuboLib::Set_MCP3x08_Oversampling

(

unsigned short

overSampling[MAX_MCP3x08_CHANNELS]

)

Specifies the ADC channels to be sampled as well as the number they get oversampled.

The library supports up to 8 analog channels that can be sampled within one cycle tick. However, not all applications might require all 8 analog channels to be sampled but on the other hand might require some of the channels be oversampled in order to gain a higher resolution.
With a call to Set_MCP3x08_Oversampling() an array of 8 shorts is provided from which each short represents a number that defines whether the channel should be sampled and if so how many times it should get (over-) sampled. So a value of 0 means to skip the channel for sampling, 1 will sample exactly once a cycle tick and a value of 10 means to add 10 ADC counts to the internal analog input buffer.
Specifying large values for the oversampling values can lead to heavy CPU usage. Therefore a call to the function might not succeed e.g. when the etsimated amount of time for all cycles exceeds the cycle time as specified by a call to Set_Cycle_Time().
After initialization of the library no analog channel will be acquired. So using analog channels first requires a successfull call to Set_MCP3x08_Oversampling().

Parameters

overSampling

A vector specifying how many ADC samples should be taken per analog channel for calculating the analog voltage.

Returns

If the estimation of the CPU load required for sampling at a given cycle time and oversampling shows up to not break the cycle time then the result will be true and the oversampling values are being used. Otherwise the function will return false and the old valued are being used.

See also

Set_VRef(), Get_AI_Channel(), Set_Cycle_Time()

For a simple example on how to sample one analog channel refer to the demo AnalogInput1.cpp.
AnalogInput2.cpp illustrates how to oversample a channel 4 times.
Testing ranges that can be used for oversampling is shown in AnalogInput3.cpp.
The impact of the reference voltage when calculating absolut voltage values from ADC counts can be seen in AnalogInput4.cpp.

Note

The new oversampling values are effective beginning with the next cycle tick count.

void HuboLib::Set_VRef

(

double

volt

)

Set the reference voltage value for the ADC.

This function is to adjust the reference voltage of the ADC according to a measured value as being provided by the high precision reference voltage TL431.
The new reference voltage is effective beginning with the next cycle tick count.

Parameters

volt	The reference voltage of the TL431 to be adjusted.

See also

Get_VRef(), Get_AI_Channel(), Set_MCP3x08_Oversampling

For an example on how to read and set the reference voltage refer to the demo AnalogInput4.cpp.

Note

The default reference voltage is 2.53V and usually does not need to be changed. If so - use a high precision instrument to measure the TL431's reference voltage.