Class DataAPI

ClassList > DataAPI

More...

• #include <DataAPI.h>

Public Functions

Type	Name
void	configureDiscontinuousMode (adc_t adc_number, uint32_t dicontinuous_count) Set the discontinuous count for an ADC.
void	configureTriggerSource (adc_t adc_number, trigger_source_t trigger_source) Change the trigger source of an ADC.
float32_t	convertValue (uint8_t pin_number, uint16_t raw_value) Use this function to convert values obtained using matching data.getRawValues() function to relevant unit for the data (Volts, Amperes, or Degree Celsius).
int8_t	enableAcquisition (uint8_t pin_number, adc_t adc_number=DEFAULT_ADC) This function is used to enable acquisition on a Spin PIN with a given ADC.
conversion_type_t	getConversionParameterType (uint8_t pin_number) Use this function to get the current conversion type for the chosen channel.
float32_t	getConversionParameterValue (uint8_t pin_number, parameter_t parameter_name) Use this function to get the current conversion parameters for the chosen channel .
float32_t	getLatestValue (uint8_t pin_number, uint8_t * dataValid=nullptr) This function returns the latest acquired measurement.
uint16_t *	getRawValues (uint8_t pin_number, uint32_t & number_of_values_acquired) Function to access the acquired data for specified pin.
float32_t *	getValues (uint8_t pin_number, uint32_t & number_of_values_acquired) Function to access the acquired data for specified pin.
float32_t	peekLatestValue (uint8_t pin_number) Function to access the latest value available from a pin.
int8_t	retrieveConversionParametersFromMemory (uint8_t pin_number) Retrieved previously configured conversion parameters from persistent memory.
void	setConversionParametersLinear (uint8_t pin_number, float32_t gain, float32_t offset) Use this function to tweak the conversion values for the channel if default values are not accurate enough.
void	setConversionParametersNtcThermistor (uint8_t pin_num, float32_t r0, float32_t b, float32_t rdiv, float32_t t0) Use this function to set the conversion values for any NTC thermistor sensor if default values are not accurate enough.
int8_t	start () This functions manually starts the acquisition chain.
bool	started () Checks if the module is already started.
int8_t	stop () Stops the module if it is started.
int8_t	storeConversionParametersInMemory (uint8_t pin_number) Store the currently configured conversion parameters of a given channel in persistent memory.
void	triggerAcquisition (adc_t adc_number) Triggers an acquisition on a given ADC.

Detailed Description

Static class definition

Public Functions Documentation

function configureDiscontinuousMode

Set the discontinuous count for an ADC.

void DataAPI::configureDiscontinuousMode (
    adc_t adc_number,
    uint32_t dicontinuous_count
) 

Note:

This is an advanced function that requires to understand the way the ADC work.

Only for use if you explicitly requires it.

Parameters:

• adc_number Number of the ADC to configure.
• discontinuous_count Number of channels to acquire on each trigger event. 0 to disable discontinuous mode (default).

---

function configureTriggerSource

Change the trigger source of an ADC.

void DataAPI::configureTriggerSource (
    adc_t adc_number,
    trigger_source_t trigger_source
) 

Parameters:

• adc_number Number of the ADC to configure
• trigger_source Source of the trigger

---

function convertValue

Use this function to convert values obtained using matching data.getRawValues() function to relevant unit for the data (Volts, Amperes, or Degree Celsius).

float32_t DataAPI::convertValue (
    uint8_t pin_number,
    uint16_t raw_value
) 

Note:

This function can NOT be called before the pin is enabled.

Parameters:

• pin_number Number of the pin from which to obtain values.
• raw_value Raw value obtained from the channel buffer.

Returns:

Converted value in the relevant unit.

---

function enableAcquisition

This function is used to enable acquisition on a Spin PIN with a given ADC.

int8_t DataAPI::enableAcquisition (
    uint8_t pin_number,
    adc_t adc_number=DEFAULT_ADC
) 

Note:

Not any pin can be used for acquisition: the pin must be linked to a channel of the given ADC. Refer to Spin pinout image for PIN/ADC relations.

Note:

This function must be called before Data API is started.

Parameters:

• pin_number Number of the Spin pin on which to enable acquisition.

• adc_number Number of the ADC on which acquisition is to be done. This parameter can be omitted, in which case:

• If only one ADC is linked to the given pin, it will be selected.

• If two ADCs are available for acquisition on the given pin, the ADC with the lowest number will be selected.

Returns:

0 if acquisition was correctly enabled, -1 if there was an error.

Errors generally indicate that the given pin is not linked to and ADC, and thus can not be used for acquisition.

If the adc_number parameter was explicitly provided, it can also indicate that the given ADC is not available for acquisition on the provided pin.

Public functions accessible only when using a power shield

---

function getConversionParameterType

Use this function to get the current conversion type for the chosen channel.

conversion_type_t DataAPI::getConversionParameterType (
    uint8_t pin_number
) 

Note:

This function can NOT be called before the channel is enabled.

Parameters:

• pin_number Number of the pin from which to obtain values.

Returns:

Returns the type of conversion of the given pin.

---

function getConversionParameterValue

Use this function to get the current conversion parameters for the chosen channel .

float32_t DataAPI::getConversionParameterValue (
    uint8_t pin_number,
    parameter_t parameter_name
) 

Note:

This function can NOT be called before the channel is enabled.

Parameters:

• pin_number Number of the pin from which to obtain values.
• parameter_name Paramater to be retrieved: gain or offset.

Returns:

Returns the value of the parameter.

---

function getLatestValue

This function returns the latest acquired measurement.

float32_t DataAPI::getLatestValue (
    uint8_t pin_number,
    uint8_t * dataValid=nullptr
) 

Note:

This function can NOT be called before the pin is enabled.

Note:

When using this functions, you loose the ability to access raw values using data.getRawValues() function for the matching channel, as data.getLatestValue() function clears the buffer on each call.

Parameters:

• pin_number Number of the pin from which to obtain values.
• dataValid Pointer to an uint8_t variable.

Returns:

Latest acquired measure for the channel.

---

function getRawValues

Function to access the acquired data for specified pin.

uint16_t * DataAPI::getRawValues (
    uint8_t pin_number,
    uint32_t & number_of_values_acquired
) 

Note:

The count of these values is returned as an output parameter.

Note:

This function can NOT be called before the pin is enabled.

Note:

When calling this function, it invalidates the buffer returned by a previous call to the same function.

However, different channels buffers are independent from each other.

Note:

When using this functions, the user is responsible for data conversion. Use data.convertValue() function for this purpose.

Note:

When using this function, DO NOT use the function to get the latest converted value for the same channel as this function will clear the buffer and disregard all values but the latest.

Parameters:

• pin_number Number of the pin from which to obtain values.
• number_of_values_acquired Pass an uint32_t variable. This variable will be updated with the number of values that are present in the returned buffer.

Returns:

Pointer to a buffer in which the acquired values are stored.

---

function getValues

Function to access the acquired data for specified pin.

float32_t * DataAPI::getValues (
    uint8_t pin_number,
    uint32_t & number_of_values_acquired
) 

Warning:

This is an expensive function.

Note:

This function can NOT be called before the pin is enabled.

Note:

When calling this function, it invalidates the array returned by a previous call to the same function.

However, different channels buffers are independent from each other.

Parameters:

• pin_number Number of the pin from which to obtain values.
• number_of_values_acquired Pass an uint32_t variable. This variable will be updated with the number of values that are present in the returned buffer.

Returns:

Pointer to an array in which the acquired values are stored.

---

function peekLatestValue

Function to access the latest value available from a pin.

float32_t DataAPI::peekLatestValue (
    uint8_t pin_number
) 

Note:

This function can NOT be called before the pin is enabled.

Parameters:

• pin_number Number of the pin from which to obtain values.

Returns:

Latest available value available from the given channel.

---

function retrieveConversionParametersFromMemory

Retrieved previously configured conversion parameters from persistent memory.

int8_t DataAPI::retrieveConversionParametersFromMemory (
    uint8_t pin_number
) 

Parameters:

• pin_number SPIN pin number

Returns:

0 if parameters were correctly retrieved, negative value if there was an error:

• -1: persistent memory is empty
• -2: persistent memory contains data, but its version doesn't match current version
• -3: data in persistent memory is corrupted
• -4: persistent memory contains data, but not for the requested pin
• -5000: pin not found.

---

function setConversionParametersLinear

Use this function to tweak the conversion values for the channel if default values are not accurate enough.

void DataAPI::setConversionParametersLinear (
    uint8_t pin_number,
    float32_t gain,
    float32_t offset
) 

Note:

This function can NOT be called before the pin is enabled.

Parameters:

• pin_number Number of the pin from which to obtain values.
• gain Gain to be applied (multiplied) to the channel raw value.
• offset Offset to be applied (added) to the channel value after gain has been applied.

---

function setConversionParametersNtcThermistor

Use this function to set the conversion values for any NTC thermistor sensor if default values are not accurate enough.

void DataAPI::setConversionParametersNtcThermistor (
    uint8_t pin_num,
    float32_t r0,
    float32_t b,
    float32_t rdiv,
    float32_t t0
) 

Note:

This function can NOT be called before the sensor is enabled. The DataAPI must not have been started, neither explicitly nor by starting the Uninterruptible task.

Parameters:

• pin_number Number of the pin from which to obtain values.
• r0 The NTC resistance at a reference temperature.
• b The sensibility coefficient of the resistance to temperature.
• rdiv The bridge divider resistance used to condition the NTC.
• t0 The reference temperature of the thermistor.

---

function start

This functions manually starts the acquisition chain.

int8_t DataAPI::start () 

Note:

If your code uses an uninterruptible task, you do not need to start Data Acquisition manually:

It will instead start automatically at the same time as the task as their internal behavior is intrinsically linked.

If, for some reason, you have an uninterruptible task in your code, but do not want the Scheduling module to be in charge of Data Acquisition, you need to indicate it when starting the uninterruptible task.

In that case, Data Acquisition must be manually started using this function.

Note that in that case, dispatch will use DMA interrupts which consumes a non-negligible amount of processor time and it is not advised.

Note:

Data Acquisition must be started only after ADC module configuration has been fully carried out.

No ADC configuration change is allowed after module has been started.

If you're using a power shield and are not sure how to initialize ADCs, you can use data.enableShieldDefaultChannels() for that purpose.

Note:

Data Acquisition must be started before accessing any data.get*() or data.peek*() function.

Other Data Acquisition functions are safe to use before starting the module.

Returns:

0 if everything went well, -1 if there was an error Error is triggered when dispatch method is set to be external, but the repetition value has not provided.

Another source of error is trying to start Data Acquisition after it has already been started.

---

function started

Checks if the module is already started.

bool DataAPI::started () 

Returns:

true is the module has been started, false otherwise.

---

function stop

Stops the module if it is started.

int8_t DataAPI::stop () 

Returns:

0 if everything went well, -1 if there was an error.

---

function storeConversionParametersInMemory

Store the currently configured conversion parameters of a given channel in persistent memory.

int8_t DataAPI::storeConversionParametersInMemory (
    uint8_t pin_number
) 

Parameters:

• pin_number SPIN pin number

Returns:

0 if parameters were correctly stored, negative value if there was an error:

• -1: There was an error,
• -5000: pin not found.

---

function triggerAcquisition

Triggers an acquisition on a given ADC.

void DataAPI::triggerAcquisition (
    adc_t adc_number
) 

Note:

This function can NOT be called before:

Parameters:

• adc_number Number of the ADC on which to acquire channels.

---

---

The documentation for this class was generated from the following file docs/core/zephyr/modules/owntech_spin_api/zephyr/src/DataAPI.h