Shield sensors is an API that allows to access sensors from a Spin shield easily. Acquiring data without a shield is done using Data API, but Shield sensors API builds on Data API to provide access to sensors by name as well as automatically configuring the parameters for the raw data conversion.

Quick start with Shield sensor API

To enable the Twist Shield channels, indicate which shield you are using by editing the file platformio.ini to define the board_shield= and board_shield_version= commands. From there, the Shield sensors API will be available simply by including ShieldAPI.h in your code.

Using shield sensor API is done quite similarly to the Data API. The difference is that you do not have to know which pin a sensor is connected to.

For example, if you want to access the V1_LOW sensor from the Twist shield using Data API, you would have to consult the pinout of the shield and identify that it is connected to pin 29 of the Spin, then write:

spin.data.enableAcquisition(29);

However, using Shield sensor API, you just have to write:

shield.sensors.enableAcquisition(V1_LOW);

Everything else should be used similarly as Data API, just replace spin.data by shield.sensors in your code, then use the sensor name instead of the pin number as a parameter for the functions.

Auto-configuration of the API

Moreover, as Shield sensor API is aware of what sensors are available on the shield you use, it provides an auto-configuration that enables acquisition for all the sensors from the shield.

The function is named shield.sensors.enableDefault***Sensors(). For example, for the Twist shield, the function is named shield.sensors.enableDefaultTwistSensors(). Just call this function then start the API, and you're ready to go!

API Reference

Class SensorsAPI

ClassList > SensorsAPI

Public Functions

Type	Name
float32_t	convertRawValue (sensor_t sensor_name, uint16_t raw_value) Use this function to convert values obtained using matching spin.data.getRawValues() function to relevant unit for the data: Volts, Amperes, or Degree Celcius.*
void	enableDefaultOwnverterSensors () This function is used to enable acquisition of all voltage/current sensors on the Twist shield. Sensors are attributed as follows: ADC1: - V1, V2, V3, VH, VN ADC2: - I1, I2, I3, IH, T.
void	enableDefaultTwistSensors () This function is used to enable acquisition of all voltage/current sensors on the Twist shield. Sensors are attributed as follows: ADC1: - I1_LOW ADC2: - I2_LOW.
int8_t	enableSensor (sensor_t sensor_name, adc_t adc_number) This function is used to enable a shield sensor for acquisition by a given ADC.
float32_t	getLatestValue (sensor_t sensor_name, uint8_t * dataValid=nullptr) This function returns the latest acquired measure expressed in the relevant unit for the sensor: Volts, Amperes, or Degree Celcius.
uint16_t *	getRawValues (sensor_t sensor_name, uint32_t & number_of_values_acquired) Function to access the acquired data for specified sensor. 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 *	getValues (sensor_t sensor_name, uint32_t & number_of_values_acquired) Function to access the acquired data for specified pin. This function converts all values that have been acquired since last call are stored and provide an array containing all of them. 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	peekLatestValue (sensor_t sensor_name) Function to access the latest value available from the sensor, 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 (sensor_t sensor_name) Use this function to read the gain and offset parameters of the board to is non-volatile memory.
conversion_type_t	retrieveStoredConversionType (sensor_t sensor_name) Use this function to get the current conversion type for the chosen sensor.
float32_t	retrieveStoredParameterValue (sensor_t sensor_name, parameter_t parameter_name) Use this function to get the current conversion parameteres for the chosen sensor.
void	setConversionParametersLinear (sensor_t sensor_name, float32_t gain, float32_t offset) Use this function to tweak the conversion values for any linear sensor if default values are not accurate enough.
void	setConversionParametersNtcThermistor (sensor_t sensor_name, 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.
void	setOwnverterTempMeas (ownverter_temp_sensor_t temperature_sensor) This function sets the gpios attached to the MUX to control which measurement will be performed. The logic is: IN1 IN2 TEMP 1 T F TEMP 2 F T TEMP 3 T T.
void	setTwistSensorsUserCalibrationFactors () Manually set parameters values using console. You will be directed via console to input the parameters of each sensor of the Twist board. After the parameters have been inputed, they will be stored in Spin Non-Volatile memory so that they are automatically applied on subsequent boots.
int8_t	storeParametersInMemory (sensor_t sensor_name) Use this function to write the gain and offset parameters of the board to is non-volatile memory.
void	triggerTwistTempMeas (sensor_t temperature_sensor) Manually triggers the temperature measurement of the Twist board.

Public Functions Documentation

function convertRawValue

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

float32_t SensorsAPI::convertRawValue (
    sensor_t sensor_name,
    uint16_t raw_value
)

Note:

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

Parameters:

sensor_name Name of the shield sensor from which the value originates
raw_value Raw value obtained from which the value originates

Returns:

Converted value in the relevant unit. Returns ERROR_CHANNEL_NOT_FOUND if the sensor is not active.

function enableDefaultOwnverterSensors

This function is used to enable acquisition of all voltage/current sensors on the Twist shield. Sensors are attributed as follows: ADC1: - V1, V2, V3, VH, VN ADC2: - I1, I2, I3, IH, T.

void SensorsAPI::enableDefaultOwnverterSensors ()

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. It also configures the gpios that control the MUX that chooses which temperature will be measured.

Note:

This function must be called before ADC is started.

function enableDefaultTwistSensors

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

void SensorsAPI::enableDefaultTwistSensors ()

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 enableSensor

This function is used to enable a shield sensor for acquisition by a given ADC.

int8_t SensorsAPI::enableSensor (
    sensor_t sensor_name,
    adc_t adc_number
)

Note:

This function requires the presence of an "shielde-sensor" node in the shield device-tree.

Note:

This function must be called before ADC is started.

Parameters:

sensor_name Name of the sensor using enumeration sensor_t.
adc_number The ADC which should be used for acquisition.

Returns:

0 if the sensor was correctly enabled, negative value if there was an error.

function getLatestValue

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

float32_t SensorsAPI::getLatestValue (
    sensor_t sensor_name,
    uint8_t * dataValid=nullptr
)

Note:

This function can't be called before the sensor 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 spin.data.get*RawValues() function for the matching sensor, as spin.data.get*() function clears the buffer on each call.

Parameters:

sensor_name Name of the shield sensor 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 spin.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 measure acquired by the sensor. If no value was acquired by this sensor yet, return value is NO_VALUE.

function getRawValues

Function to access the acquired data for specified sensor. 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 * SensorsAPI::getRawValues (
    sensor_t sensor_name,
    uint32_t & number_of_values_acquired
)

Note:

This function can't be called before the sensor 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 sensors buffers are independent from each other.

Note:

When using this functions, the user is responsible for data conversion. Use matching spin.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 sensor as this function will clear the buffer and disregard all values but the latest.

Parameters:

sensor_name Name of the shield sensor 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 getValues

Function to access the acquired data for specified pin. This function converts all values that have been acquired since last call are stored and provide an array containing all of them. 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 * SensorsAPI::getValues (
    sensor_t sensor_name,
    uint32_t & number_of_values_acquired
)

Warning:

This is an expensive function. Calling this function trigger the conversion of all values acquired since the last call. If only the lastet value is required, it is advised to call getLatestValue() instead. If multiple values are required, but not all, it is advised to call getRawValues() instead, then explicitely convert required values using convertValue().

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 array returned by a previous call to the same function. However, different channels buffers are independent from each other.

Parameters:

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

function peekLatestValue

Function to access the latest value available from the sensor, 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 SensorsAPI::peekLatestValue (
    sensor_t sensor_name
)

Note:

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

Parameters:

sensor_name Name of the shield sensor from which to obtain value.

Returns:

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

function retrieveParametersFromMemory

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

int8_t SensorsAPI::retrieveParametersFromMemory (
    sensor_t sensor_name
)

Parameters:

sensor_name Name of the shield sensor to save the values.

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

function retrieveStoredConversionType

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

conversion_type_t SensorsAPI::retrieveStoredConversionType (
    sensor_t sensor_name
)

Note:

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

Parameters:

sensor_name Name of the shield sensor to get a conversion parameter.

function retrieveStoredParameterValue

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

float32_t SensorsAPI::retrieveStoredParameterValue (
    sensor_t sensor_name,
    parameter_t parameter_name
)

Note:

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

Parameters:

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

function setConversionParametersLinear

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

void SensorsAPI::setConversionParametersLinear (
    sensor_t sensor_name,
    float32_t gain,
    float32_t offset
)

Note:

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

Parameters:

sensor_name Name of the shield sensor to set conversion values.
gain Gain to be applied (multiplied) to the sensor raw value.
offset Offset to be applied (added) to the sensor 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 SensorsAPI::setConversionParametersNtcThermistor (
    sensor_t sensor_name,
    float32_t r0,
    float32_t b,
    float32_t rdiv,
    float32_t t0
)

Note:

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

Parameters:

sensor_name Name of the shield sensor to set conversion values.
r0 The NTC resistance at a reference temperature.
b The sensibility coefficient of the resistance to temperature.
rdiv The bridge dividor resistance used to condition the NTC.
t0 The reference temperature of the thermistor.

function setOwnverterTempMeas

This function sets the gpios attached to the MUX to control which measurement will be performed. The logic is: IN1 IN2 TEMP 1 T F TEMP 2 F T TEMP 3 T T.

void SensorsAPI::setOwnverterTempMeas (
    ownverter_temp_sensor_t temperature_sensor
)

Parameters:

temperature_sensor Name of the temperature sensor to trigger. Can be either TEMP_1, TEMP_2 or TEMP_3.

Note:

This function will decide which value will be read automatically by the ADC2 to which the temperature of the Ownverter is linked.

function setTwistSensorsUserCalibrationFactors

Manually set parameters values using console. You will be directed via console to input the parameters of each sensor of the Twist board. After the parameters have been inputed, they will be stored in Spin Non-Volatile memory so that they are automatically applied on subsequent boots.

void SensorsAPI::setTwistSensorsUserCalibrationFactors ()

Note:

This function requires a console to interact with the user. The board must be connected to a computer using USB to display the console.

Note:

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

function storeParametersInMemory

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

int8_t SensorsAPI::storeParametersInMemory (
    sensor_t sensor_name
)

Note:

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

Parameters:

sensor_name Name of the shield sensor to save the values.

function triggerTwistTempMeas

Manually triggers the temperature measurement of the Twist board.

void SensorsAPI::triggerTwistTempMeas (
    sensor_t temperature_sensor
)

Parameters:

temperature_sensor Name of the temperature sensor to trigger. Can be either TEMP_SENSOR_1 or TEMP_SENSOR_2.

Note:

This function must be called to trigger a conversion of the ADC to which the sensor is linked. It must be called BEFORE reading a new measurement. Account for delays in the measurement.

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