Class DataAPI

Public Functions

Type	Name
float32_t	convert (channel_t channel, 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 Celcius.*
float32_t	convert (uint8_t adc_num, uint8_t pin_num, 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 Celcius.*
int8_t	enableAcquisition (uint8_t adc_num, uint8_t pin_num) This function is used to enable acquisition on a Spin PIN with a given ADC.
int8_t	enableShieldChannel (uint8_t adc_num, channel_t channel_name) This function is used to enable a channel on a given ADC using its name on a shield, rather than the ADC channel number. This function requires the presence of an "adc-channels" node in the shield device-tree.
void	enableTwistDefaultChannels () This function is used to enable acquisition of all voltage/current channels on the Twist shield. Channels are attributed as follows: ADC1: - I1_LOW ADC2: - I2_LOW.
DispatchMethod_t	getDispatchMethod () Gets the dispatch method of the module.
float32_t	getLatest (channel_t channel, uint8_t * dataValid=nullptr) This function returns the latest acquired measure expressed in the relevant unit for the channel: Volts, Amperes, or Degree Celcius.
float32_t	getLatest (uint8_t adc_num, uint8_t pin_num, uint8_t * dataValid=nullptr) This function returns the latest acquired measure expressed in the relevant unit for the channel: Volts, Amperes, or Degree Celcius.
uint16_t *	getRawValues (channel_t channel, uint32_t & number_of_values_acquired) Function to access the acquired data for specified channel. This function provides a buffer in which all data that have been acquired since last call are stored. The count of these values is returned as an output parameter: the user has to define a variable and pass it as the parameter of the function. The variable will be updated with the number of values that are available in the buffer.
uint16_t *	getRawValues (uint8_t adc_num, uint8_t pin_num, uint32_t & number_of_values_acquired) Function to access the acquired data for specified pin. This function provides a buffer in which all data that have been acquired since last call are stored. The count of these values is returned as an output parameter: the user has to define a variable and pass it as the parameter of the function. The variable will be updated with the number of values that are available in the buffer.
float32_t	peek (channel_t channel) Function to access the latest value available from the channel, expressed in the relevant unit for the data: Volts, Amperes, or Degree Celcius. This function will not touch anything in the buffer, and thus can be called safely at any time after the module has been started.
float32_t	peek (uint8_t adc_num, uint8_t pin_num) Function to access the latest value available from a pin, expressed in the relevant unit for the data: Volts, Amperes, or Degree Celcius. This function will not touch anything in the buffer, and thus can be called safely at any time after the module has been started.
int8_t	retrieveParametersFromMemory (channel_t channel) Use this function to read the gain and offset parameters of the board to is non-volatile memory.
int8_t	retrieveParametersFromMemory (uint8_t adc_num, uint8_t pin_num) Retreived previously configured conversion parameters from NVS.
conversion_type_t	retrieveStoredConversionType (channel_t channel) Use this function to get the current conversion type for the chosen channel.
conversion_type_t	retrieveStoredConversionType (uint8_t adc_num, uint8_t pin_num) Use this function to get the current conversion type for the chosen channel.
float32_t	retrieveStoredParameterValue (channel_t channel, parameter_t parameter_name) Use this function to get the current conversion parameteres for the chosen channel .
float32_t	retrieveStoredParameterValue (uint8_t adc_num, uint8_t pin_num, parameter_t parameter_name) Use this function to get the current conversion parameteres for the chosen channel .
void	setDispatchMethod (DispatchMethod_t dispatch_method) Sets the dispatch method of the module.
void	setParameters (channel_t channel, 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	setParameters (uint8_t adc_num, uint8_t pin_num, 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	setRepetitionsBetweenDispatches (uint32_t repetition) Indicates the repetition count between two external dispatches when it is handled externally by the Scheduling module. This value is used to calibrate buffers sizes.
void	setTwistChannelsUserCalibrationFactors () Retrieve stored parameters from Flash memory and configure ADC parameters.
int8_t	start () This functions manually starts the acquisition chain.
bool	started () Checks if the module is already started.
int8_t	storeParametersInMemory (channel_t channel) Use this function to write the gain and offset parameters of the board to is non-volatile memory.
int8_t	storeParametersInMemory (uint8_t adc_num, uint8_t pin_num) Store the currently configured conversion parameters of a given channel in NVS.
void	triggerAcquisition (uint8_t adc_num) Triggers an acquisition on a given ADC. Each channel configured on this ADC will be acquired one after the other until all configured channels have been acquired.

Public Functions Documentation

function convert [1/2]

Use this function to convert values obtained using matching data.get*RawValues() function to relevant unit for the data: Volts, Amperes, or Degree Celcius.

float32_t DataAPI::convert (
    channel_t channel,
    uint16_t raw_value
)

Note:

This function can't be called before the channel is enabled.

Parameters:

channel Name of the shield channel from which the value originates
raw_value Raw value obtained from which the value originates

Returns:

Converted value in the relevant unit. Returns -5000 if the channel is not active.

function convert [2/2]

Use this function to convert values obtained using matching data.get*RawValues() function to relevant unit for the data: Volts, Amperes, or Degree Celcius.

float32_t DataAPI::convert (
    uint8_t adc_num,
    uint8_t pin_num,
    uint16_t raw_value
)

Note:

This function can't be called before the pin is enabled.

Parameters:

adc_num Number of the ADC from which the value originates.
pin_num 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. If there is an error, returns -5000.

function enableAcquisition

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

int8_t DataAPI::enableAcquisition (
    uint8_t adc_num,
    uint8_t pin_num
)

Note:

Not any pin can be used for acquisiton: 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 ADC is started.

Parameters:

adc_number Number of the ADC on which acquisition is to be done.
pin_num Number of the Spin pin to acquire.

Returns:

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

function enableShieldChannel

This function is used to enable a channel on a given ADC using its name on a shield, rather than the ADC channel number. This function requires the presence of an "adc-channels" node in the shield device-tree.

int8_t DataAPI::enableShieldChannel (
    uint8_t adc_num,
    channel_t channel_name
)

Note:

This function must be called before ADC is started.

Parameters:

adc_number Number of the ADC on which channel is to be enabled.
channel_name Name of the channel using enumeration channel_t.

Returns:

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

function enableTwistDefaultChannels

This function is used to enable acquisition of all voltage/current channels on the Twist shield. Channels are attributed as follows: ADC1: - I1_LOW ADC2: - I2_LOW.

void DataAPI::enableTwistDefaultChannels ()

V1_LOW - V2_LOW
V_HIGH - I_HIGH

Note:

This function will configure ADC 1 and 2 to be automatically triggered by the HRTIM, so the board must be configured as a power converted to enable HRTIM events. All other ADCs remain software triggered, thus will only be acquired when triggerAcquisition() is called.

Note:

This function must be called before ADC is started.

function getDispatchMethod

Gets the dispatch method of the module.

DispatchMethod_t DataAPI::getDispatchMethod ()

Note:

End-user should not worry about this function, which is used internally by the Scheduling module.

Returns:

Dispatch method indicatinng when the dispatch is done.

function getLatest [1/2]

This function returns the latest acquired measure expressed in the relevant unit for the channel: Volts, Amperes, or Degree Celcius.

float32_t DataAPI::getLatest (
    channel_t channel,
    uint8_t * dataValid=nullptr
)

Note:

This function can't be called before the channel is enabled and the DataAPI module is started, either explicitly or by starting the Uninterruptible task.

Note:

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

Parameters:

channel Name of the shield channel from which to obtain value.
dataValid Pointer to an uint8_t variable. This parameter is facultative. If this parameter is provided, it will be updated to indicate information about data. Possible values for this parameter will be:
DATA_IS_OK if returned data is a newly acquired data,
DATA_IS_OLD if returned data has already been provided before (no new data available since latest time this function was called),
DATA_IS_MISSING if returned data is NO_VALUE.

Returns:

Latest acquired measure for the channel. If no value was acquired in this channel yet, return value is NO_VALUE.

function getLatest [2/2]

This function returns the latest acquired measure expressed in the relevant unit for the channel: Volts, Amperes, or Degree Celcius.

float32_t DataAPI::getLatest (
    uint8_t adc_num,
    uint8_t pin_num,
    uint8_t * dataValid=nullptr
)

Note:

This function can't be called before the pin is enabled. The DataAPI module must have been started, either explicitly or by starting the Uninterruptible task.

Note:

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

Parameters:

adc_num Number of the ADC from which to obtain value.
pin_num Number of the pin from which to obtain values.
dataValid Pointer to an uint8_t variable. This parameter is facultative. If this parameter is provided, it will be updated to indicate information about data. Possible values for this parameter will be:
DATA_IS_OK if returned data is a newly acquired data,
DATA_IS_OLD if returned data has already been provided before (no new data available since latest time this function was called),
DATA_IS_MISSING if returned data is NO_VALUE.

Returns:

Latest acquired measure for the channel. If no value was acquired in this channel yet, return value is NO_VALUE.

function getRawValues [1/2]

Function to access the acquired data for specified channel. This function provides a buffer in which all data that have been acquired since last call are stored. The count of these values is returned as an output parameter: the user has to define a variable and pass it as the parameter of the function. The variable will be updated with the number of values that are available in the buffer.

uint16_t * DataAPI::getRawValues (
    channel_t channel,
    uint32_t & number_of_values_acquired
)

Note:

This function can't be called before the channel is enabled and the DataAPI module is started, either explicitly or by starting the Uninterruptible task.

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 matching data.convert*() 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:

channel Name of the shield channel 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. If number_of_values_acquired is 0, do not try to access the buffer as it may be nullptr.

function getRawValues [2/2]

Function to access the acquired data for specified pin. This function provides a buffer in which all data that have been acquired since last call are stored. The count of these values is returned as an output parameter: the user has to define a variable and pass it as the parameter of the function. The variable will be updated with the number of values that are available in the buffer.

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

Note:

This function can't be called before the pin is enabled. The DataAPI module must have been started, either explicitly or by starting the Uninterruptible task.

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 matching data.convert*() 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:

adc_num Number of the ADC from which to obtain values.
pin_num 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. If number_of_values_acquired is 0, do not try to access the buffer as it may be nullptr.

function peek [1/2]

Function to access the latest value available from the channel, expressed in the relevant unit for the data: Volts, Amperes, or Degree Celcius. This function will not touch anything in the buffer, and thus can be called safely at any time after the module has been started.

float32_t DataAPI::peek (
    channel_t channel
)

Note:

This function can't be called before the channel is enabled and the DataAPI module is started, either explicitly or by starting the Uninterruptible task.

Parameters:

channel Name of the shield channel from which to obtain value.

Returns:

Latest available value available from the given channel. If there was no value acquired in this channel yet, return value is NO_VALUE.

function peek [2/2]

Function to access the latest value available from a pin, expressed in the relevant unit for the data: Volts, Amperes, or Degree Celcius. This function will not touch anything in the buffer, and thus can be called safely at any time after the module has been started.

float32_t DataAPI::peek (
    uint8_t adc_num,
    uint8_t pin_num
)

Note:

This function can't be called before the pin is enabled. The DataAPI module must have been started, either explicitly or by starting the Uninterruptible task.

Parameters:

adc_num Number of the ADC from which to obtain value.
pin_num Number of the pin from which to obtain values.

Returns:

Latest available value available from the given channel. If there was no value acquired in this channel yet, return value is NO_VALUE.

function retrieveParametersFromMemory [1/2]

Use this function to read the gain and offset parameters of the board to is non-volatile memory.

int8_t DataAPI::retrieveParametersFromMemory (
    channel_t channel
)

Parameters:

channel Name of the shield channel to save the values.

function retrieveParametersFromMemory [2/2]

Retreived previously configured conversion parameters from NVS.

int8_t DataAPI::retrieveParametersFromMemory (
    uint8_t adc_num,
    uint8_t pin_num
)

Parameters:

adc_num ADC number
pin_num SPIN pin number

Returns:

0 if parameters were correcly retreived, negative value if there was an error: -1: NVS is empty -2: NVS contains data, but their version doesn't match current version -3: NVS data is corrupted -4: NVS contains data, but not for the requested channel -5000: Channel not found.

function retrieveStoredConversionType [1/2]

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

conversion_type_t DataAPI::retrieveStoredConversionType (
    channel_t channel
)

Note:

This function can't be called before the channel is enabled.

Parameters:

channel Name of the shield channel to get a conversion parameter.

function retrieveStoredConversionType [2/2]

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

conversion_type_t DataAPI::retrieveStoredConversionType (
    uint8_t adc_num,
    uint8_t pin_num
)

Note:

This function can't be called before the channel is enabled.

Parameters:

channel Name of the shield channel to get a conversion parameter.

Returns:

Returns the type of convertion of the given pin. Returns -5 if the channel is not active.

function retrieveStoredParameterValue [1/2]

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

float32_t DataAPI::retrieveStoredParameterValue (
    channel_t channel,
    parameter_t parameter_name
)

Note:

This function can't be called before the channel is enabled.

Parameters:

channel Name of the shield channel to get a conversion parameter.
parameter_name Paramater to be retreived: gain or offset.

function retrieveStoredParameterValue [2/2]

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

float32_t DataAPI::retrieveStoredParameterValue (
    uint8_t adc_num,
    uint8_t pin_num,
    parameter_t parameter_name
)

Note:

This function can't be called before the channel is enabled.

Parameters:

channel Name of the shield channel to get a conversion parameter.
parameter_name Paramater to be retreived: gain or offset.

Returns:

Returns the value of the parameter. Returns -5000 if the channel is not active.

function setDispatchMethod

Sets the dispatch method of the module.

void DataAPI::setDispatchMethod (
    DispatchMethod_t dispatch_method
)

Note:

End-user should not worry about this function, which is used internally by the Scheduling module.

Parameters:

dispatch_method Indicates when the dispatch should be done (default value: DispatchMethod_t::on_dma_interrupt)

function setParameters [1/2]

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

void DataAPI::setParameters (
    channel_t channel,
    float32_t gain,
    float32_t offset
)

Note:

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

Parameters:

channel Name of the shield channel to set conversion 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 setParameters [2/2]

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

void DataAPI::setParameters (
    uint8_t adc_num,
    uint8_t pin_num,
    float32_t gain,
    float32_t offset
)

Note:

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

Parameters:

adc_num Number of the ADC to set conversion values.
pin_num 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 setRepetitionsBetweenDispatches

Indicates the repetition count between two external dispatches when it is handled externally by the Scheduling module. This value is used to calibrate buffers sizes.

void DataAPI::setRepetitionsBetweenDispatches (
    uint32_t repetition
)

Note:

End-user should not worry about this function, which is used internally by the Scheduling module.

Parameters:

repetition Number of repetitions between two calls of dispatch. Used to calibrate buffers sizes.

function setTwistChannelsUserCalibrationFactors

Retrieve stored parameters from Flash memory and configure ADC parameters.

void DataAPI::setTwistChannelsUserCalibrationFactors ()

Note:

This function requires Console to interact with the user. You must first call console_init() before calling this function.

Note:

This function can't be called before all Twist channels have been enabled (you can use enableTwistDefaultChannels() for that purpose). The DataAPI must not have been started, neither explicitly nor by starting the Uninterruptible task.

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 automatically be started at the same time as the task as their internal behavior are 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 taht 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 the Twist shield and are not sure how to initialize ADCs, you can use data.enableTwistDefaultChannels() 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 storeParametersInMemory [1/2]

Use this function to write the gain and offset parameters of the board to is non-volatile memory.

int8_t DataAPI::storeParametersInMemory (
    channel_t channel
)

Note:

This function should be called after updating the parameters using setParameters.

Parameters:

channel Name of the shield channel to save the values.

function storeParametersInMemory [2/2]

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

int8_t DataAPI::storeParametersInMemory (
    uint8_t adc_num,
    uint8_t pin_num
)

Parameters:

adc_num ADC number
pin_num SPIN pin number

Returns:

0 if parameters were correcly stored, negative value if there was an error: -1: There was an error, -5000: Channel not found.

function triggerAcquisition

Triggers an acquisition on a given ADC. Each channel configured on this ADC will be acquired one after the other until all configured channels have been acquired.

void DataAPI::triggerAcquisition (
    uint8_t adc_num
)

Note:

This function can't be called before the at least one channel is enabled on the ADC and the DataAPI module is started, either explicitly or by starting the Uninterruptible task.

Parameters:

adc_num 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_data_api/zephyr/public_api/DataAPI.h