ble-sensor-mt

Abstract:

This library provides high level functions to interact Microtronics BLE Sensors.

Supported Sensors:

BLE ADIN
BLE Gauge
BLE H2S
BLE Link
BLE Radar

General Workings:

The General Procedure to work with this library is the following:

Initalize the general part of the library
Add a Sensor by calling the respective *Ble_AddSensor() function.
Connect to the added Sensor by calling *Ble_Connect() function.

See following example code on how to add a gauge sensor:

#define GAUGEBLE_SENSOR_COUNT 1 #define BLE_SENSOR_COUNT GAUGEBLE_SENSOR_COUNT

main() { new sGaugeInit[TGaugeBleInit]; new iGaugeHandle; new iSnGauge = 12345678; // put serialnumber of your ble gauge here /* init underlying BLE-SENSOR-MT library */ catch(BleSensor_Init(APP_BLE_INTERFACE)); sGaugeInit.iMode = BLE_SENSOR_MODE_SN; rM2M_Pack(sGaugeInit.aSn, 0, iSnGauge, RM2M_PACK_U32); /* add a Gauge Sensor */ iGaugeHandle = GaugeBle_AddSensor(sGaugeInit); /* connect to Gauge Sensor */ catch(GaugeBle_Connect(iGaugeHandle)); } BleSensor_Event(iSensorIndex, iEvent, iEventResult, aData{}, iLength) { /* mandatory ble sensor event dispatcher */ if((iSensorIndex < OK) && (iEvent == BLE_SENSOR_EVT_ERROR)) { /* error on interface occured: reset sensor(s) */ #log("!ERROR %d on BleSensor_Event!", iEventResult); } GaugeBle_SensorEvent(iSensorIndex, iEvent, iEventResult, aData, iLength); } GaugeBle_EvtSensor(iGaugeHandle, iEvent, iResult) { switch(iEvent) { case GAUGEBLE_EVT_NONE: { #log("(Gauge-Sensor %d) GAUGEBLE_EVT_NONE", iGaugeHandle); } case GAUGEBLE_EVT_CONNECTED: { #log("(Gauge-Sensor %d) GAUGEBLE_EVT_CONNECTED", iGaugeHandle); } case GAUGEBLE_EVT_DISCONNECTED: { #log("(Gauge-Sensor %d) GAUGEBLE_EVT_DISCONNECTED", iGaugeHandle); } case GAUGEBLE_EVT_ERROR: { /* error occured -> get specific error */ #log("!(Gauge-Sensor %d) GAUGEBLE_EVT_ERROR %d", iGaugeHandle, iResult); } case GAUGEBLE_EVT_CONFIG_DONE: { #log("(Gauge-Sensor %d) GAUGEBLE_EVT_CONFIG_DONE", iGaugeHandle); } case GAUGEBLE_EVT_MEASUREDATA: { #log("(Gauge-Sensor %d) GAUGEBLE_EVT_MEASUREDATA", iGaugeHandle); new sGaugeValues[TGaugeBle_DataValues]; GaugeBle_GetMeasurementValues(iGaugeHandle, sGaugeValues); #log("!(Gauge-Sensor %d) %d mm", iGaugeHandle, sGaugeValues.iLevel); } } }

After this sequence, the library will start to look for a Gauge sensor with the desired Serial Number. It will use up to 3 BLE scans with 10s duration to try and find the sensor. If the sensor is found, the library automatically trys to connect and authenticate the connection. It also reads production and configuration values before emitting a callback to signalize to the application that the connection process has finished.

This procedure is the same for all other supported Sensors!

Common Functions:

Some functions within the library are the same for every sensor. These are:

#Ble_AddSensor

#Ble_RemoveSensor

#Ble_Connect

#Ble_Disconnect

The # in the following function calls is a placeholder for the subsequent sensor prefixes. Possible prefixes are: Gauge, Adin, H2s, Link and Radar.

The rest of the sensor specific functions are elaborated within the respective sensor descriptions.

BLE_SENSOR_COUNT -

Overall number of sensor slots supported by the library.

// make sure this value equals the sum of all required slots #define BLE_SENSOR_COUNT (ADINBLE_SENSOR_COUNT + GAUGEBLE_SENSOR_COUNT + H2SBLE_SENSOR_COUNT + LINKBLE_SENSOR_COUNT + RADARBLE_SENSOR_COUNT

BLE_SENSOR_X:

return codes for sensor events

BLE_SENSOR_OK = 0,

BLE_SENSOR_ERROR = -1,

BLE_SENSOR_ERROR_CONLOST = -2,

BLE_SENSOR_ERROR_NOTFOUND = -3,

BLE_SENSOR_ERROR_READ = -4,

BLE_SENSOR_ERROR_WRITE = -5,

BLE_SENSOR_ERROR_NOTIFY = -6,

BLE_SENSOR_ERROR_AUTH = -7

TBleSensor_FwRevisionString

structure that contains the firmware revision string

aFwRevisionString:astr{6} - Firmware revision string (e.g. "01v013")

TBleSensor_ConnectionValues

structure that contains the connection values

iRSSI:s8 = BLE RSSI (e.g. -72)

#Ble_AddSensor(sInit[T#BleInit])

Add a sensor with sInit params.

sInit : T#BleInit - Init structure of the specific sensor.

returns : s32

ERROR - if any error occurs

> = OK - sensor handle of the added sensor.

with this call you only add a sensor. to connect to the added sensor,

it is mandatory to call #Ble_Connect() with the returned handle from this function.

the appication should save the sensor handle to later identify which sensor a operation should be performed on.

#Ble_RemoveSensor(iHandle)

Remove a sensor

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR - if any error occurs

OK - if successfully removed

#Ble_Connect(iHandle)

Connect to a sensor

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR - if any error occurs (eg. wrong handle used)

OK - if connection procedure started successfully.

BLE_CONMNGR_OK_OP_OMITTED - if already connected.

This function works in non blocking mode. The callback function #Ble_EvtSensor is emitted upon a connection event.

#Ble_Disconnect(iHandle)

Disconnect from a sensor

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR - if any error occurs (eg. wrong handle used)

OK - if disconnection procedure started successfully.

BLE_CONMNGR_OK_OP_OMITTED - if already disconnected.

This function works in non blocking mode. The callback function #Ble_EvtSensor is emitted upon a disconnection event.

#Ble_GetState(iHandle)

Get current state from a sensor.

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR = f invalid handle used.

current = tate of the sensor.

#Ble_GetFWRevisionString(iHandle, sFwRevisionString)

Get the firmware revision string

iHandle : s32 - The handle used to identify the sensor.

sFWRevisionString : TBleSensor_FwRevisionString - Firmware revision string

#Ble_ReadFwRevisionString(iRadarHandle)

Trigger a read of the firmware revision string

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR - When invalid handle provided, or sensor ins't in the ready state, otherwise

OK

#Ble_GetConnectionValues(iHandle, sConnectionValues)

Get the connection values of peer.

iHandle : s32 - The handle used to identify the sensor.

sConnectionValues : TBleSensor_ConnectionValues - Connection values

#Ble_ReadConnectionValues(iHandle)

Trigger a read of the connection values

iHandle : s32 - The handle used to identify the sensor.

returns : s32

ERROR - When invalid handle provided, or sensor ins't in the ready state, otherwise

OK

Common Callback Functions:

The library emits a callback function that informs the application for every sensor event.

#Ble_EvtSensor

#Ble_EvtSensor(iHandle, iEvent, iResult)

Callback function for sensor event

iHandle : s32 - The handle used to identify the sensor.

iEvent : BLE#SENSOR_EVENT_X - The event that occured.

iResult : s32 - The result of the regarding event.

Abstract:

In this secion the ADIN specific functions are described.

To use the ADIN module it is necessary to set ADINBLE_SENSOR_COUNT to a value > 0 in dde.

#define ADINBLE_SENSOR_COUNT 1

ADINBLE_SENSOR_COUNT -

the number of ADIN sensor instances the application wants to use.

When modifying this value, make sure to also modify BLE_SENSOR_COUNT.

Make sure that this value, combined with all other sensor instances, does not exceed BLE_SENSOR_COUNT

ADINBLE_MEASURE_X: s32

Supported measurement modes of the ADIN sensor.

ADINBLE_MEASURE_NONE = 0x00, // channel off

ADINBLE_MEASURE_DIRECT = 0x01, // direct measurement

ADINBLE_MEASURE_VDIV = 0x02, // voltage divider measurement

ADINBLE_MEASURE_MA = 0x03, // mA measurement

ADINBLE_STATE_X:

ADIN sensor states

ADINBLE_STATE_ERROR = -1,

ADINBLE_STATE_DISCONNECTED = 0,

ADINBLE_STATE_CONNECTED = 1,

ADINBLE_STATE_READY = 3,

ADINBLE_STATE_MEAS_PENDING = 4,

ADINBLE_X:

return codes for sensor events

ADINBLE_OK = BLE_SENSOR_OK,

ADINBLE_ERROR = BLE_SENSOR_ERROR,

ADINBLE_ERROR_CONLOST = BLE_SENSOR_ERROR_CONLOST,

ADINBLE_ERROR_NOTFOUND = BLE_SENSOR_ERROR_NOTFOUND,

ADINBLE_ERROR_READ = BLE_SENSOR_ERROR_READ,

ADINBLE_ERROR_WRITE = BLE_SENSOR_ERROR_WRITE,

ADINBLE_ERROR_NOTIFY = BLE_SENSOR_ERROR_NOTIFY,

ADINBLE_ERROR_AUTH = BLE_SENSOR_ERROR_AUTH,

ADINBLE_EVT_X:

sensor events

ADINBLE_EVT_NONE = 0,

ADINBLE_EVT_CONNECTED = 1,

ADINBLE_EVT_DISCONNECTED = 2,

ADINBLE_EVT_ERROR = 3,

ADINBLE_EVT_CONFIG_DONE = 5,

ADINBLE_EVT_MEASUREDATA = 6,

ADINBLE_EVT_FWREVSTRING_READ = 7,

ADINBLE_EVT_CON_VALUES_READ = 8,

TAdinBle_MeasureValues

Structure that contains the measurement values provided by the ADIN sensor.

iValueRaw:s32 - The raw value of the last measurement

iFlags:s32 - The flags of the sensor

TAdinBle_ProductionValues

iSerial:s32 - The serial number of the device.

iProdStamp:stamp32 - The production stamp of the device.

AdinBle_Measure(iAdinHandle, iMeasureMode = ADINBLE_MEASURE_MA, iAvgSampleCount=1, iAvgSampleDelay=300, iWarmupTime=0, imVSens=0)

Trigger a measurement with the provided parameters.

iAdinHandle : s32 - The handle used to identify the ADIN sensor.

iMeasureMode : ADINBLE_MEASURE_X - The measurement mode used.

iAvgSampleCount : s32 - The samples used for averaging out the measurement

iAvgSampleDelay : s32 - The delay used in [ms] between sampling for averaging.

iWarmupTime : s32 - The warmup time in [s] used before starting to sample.

imVSens : s32 - The supply voltage in [ms] used to supply the sensor.

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When measurement started successfully.

OK+1 - When measurement already pending.

AdinBle_GetMeasurementValues(iAdinHandle, sValues[TAdinBle_MeasureValues])

Get measurement values of last measurement.

iAdinHandle : s32 - The handle used to identify the ADIN sensor.

sValues : TAdinBle_MeasureValues - A structure that is filled with the last read measurement values.

returns : s32

ERROR - When invalid handle provided, otherwise:

OK

AdinBle_GetProductionValues(iAdinHandle, sValues[TAdinBle_ProductionValues])

Get production values

These values are read while initiating the connection to ADIN sensor.

iAdinHandle : s32 - The handle used to identify the ADIN sensor.

sValues : TAdinBle_ProductionValues - A structure that is filled with the production values that are read whil initiating the sensor connection.

returns : s32

ERROR - When invalid handle provided, otherwise:

OK

Callbacks:

When using the ADIN module it is mandatory for the application to implement the following callback function.

AdinBle_EvtSensor(iAdinHandle, iAdinEvent, iEventResult)

AdinBle_EvtSensor(iAdinHandle, iAdinEvent, iEventResult) { switch(iAdinEvent) { case ADINBLE_EVT_CONNECTED: { /* sensor found and connected. the sensor is currently initalized. */ } case ADINBLE_EVT_DISCONNECTED: { /* sensor disconnected in a regular manner */ } case ADINBLE_EVT_ERROR: { /* an error occured -> check iEventResult */ switch(iEventResult) { case ADINBLE_ERROR: { /* a general error occured */ } case ADINBLE_ERROR_CONLOST: { /* connection lost unintentionally */ } case ADINBLE_ERROR_NOTFOUND: { /* requested sensor not found */ } case ADINBLE_ERROR_READ: { /* error during a read operation */ } case ADINBLE_ERROR_WRITE: { /* error during a write operation */ } case ADINBLE_ERROR_NOTIFY: { /* error when receiving a notification */ } case ADINBLE_ERROR_AUTH: { /* error during authentication */ } } } case ADINBLE_EVT_CONFIG_DONE: { /* configuration of the sensor is done: the sensor is now ready to receive measurement commands furthermore you can read the production values of the sensor an store them somewhere */ new sProductionValues[TAdinBle_ProductionValues]; new sFwRevisionString[TBleSensor_FwRevisionString]; AdinBle_GetProductionValues(iAdinHandle, sProductionValues); #log("(ADIN-Sensor %d) Production Values: %d %d", iAdinHandle, sProductionValues.iSerial, sProductionValues.iProdStamp) AdinBle_GetFwRevisionString(iAdinHandle, sFwRevisionString); #log("(ADIN-Sensor %d) Firmware Version: %s", iHandle, sFwRevisionString.aFwRevisionString); } case ADINBLE_EVT_MEASUREDATA: { /* will be emitted after triggering a measurement with AdinBle_Measure(): get mesurement values */ new sAdinMeasureValues[TAdinBle_MeasureValues]; AdinBle_GetMeasurementValues(iAdinHandle, sAdinMeasureValues) #log("(ADIN-Sensor %d) %d mV", iAdinHandle, sAdinMeasureValues.iValueRaw); } case ADINBLE_EVT_FWREVSTRING_READ: { /* will be emitted after triggering a read with AdinBle_ReadFwRevisionString */ new sFwRevisionString[TBleSensor_FwRevisionString]; AdinBle_GetFwRevisionString(iAdinHandle, sFwRevisionString); #log("(ADIN-Sensor %d) Firmware Version: %s", iAdinHandle, sFwRevisionString.aFwRevisionString); } default: { /* should never be reached */ } } }

Abstract:

In this secion the gauge specific functions are described.

To use the Gauge module it is necessary to set GAUGEBLE_SENSOR_COUNT to a value > 0 in dde.

#define GAUGEBLE_SENSOR_COUNT 1

GAUGEBLE_SENSOR_COUNT -

the number of GAUGE sensor instances the application wants to use.

When modifying this value, make sure to also modify BLE_SENSOR_COUNT.

Make sure that this value, combined with all other sensor instances, does not exceed BLE_SENSOR_COUNT

GAUGEBLE_MEASURE_X: s32

Supported measurement modes of the GAUGE sensor.

GAUGEBLE_MEASURE_START = 0x01, // start a normal measurement

GAUGEBLE_STATE_X:

GAUGE sensor states

GAUGEBLE_STATE_ERROR = -1,

GAUGEBLE_STATE_DISCONNECTED = 0,

GAUGEBLE_STATE_CONNECTED = 1,

GAUGEBLE_STATE_READY = 3,

GAUGEBLE_X:

return codes for sensor events

GAUGEBLE_OK = BLE_SENSOR_OK,

GAUGEBLE_ERROR = BLE_SENSOR_ERROR,

GAUGEBLE_ERROR_CONLOST = BLE_SENSOR_ERROR_CONLOST,

GAUGEBLE_ERROR_NOTFOUND = BLE_SENSOR_ERROR_NOTFOUND,

GAUGEBLE_ERROR_READ = BLE_SENSOR_ERROR_READ,

GAUGEBLE_ERROR_WRITE = BLE_SENSOR_ERROR_WRITE,

GAUGEBLE_ERROR_NOTIFY = BLE_SENSOR_ERROR_NOTIFY,

GAUGEBLE_ERROR_AUTH = BLE_SENSOR_ERROR_AUTH,

GAUGEBLE_EVT_X:

sensor events

GAUGEBLE_EVT_NONE = 0,

GAUGEBLE_EVT_CONNECTED = 1,

GAUGEBLE_EVT_DISCONNECTED = 2,

GAUGEBLE_EVT_ERROR = 3,

GAUGEBLE_EVT_CONFIG_DONE = 5,

GAUGEBLE_EVT_MEASUREDATA = 6,

GUAGEBLE_EVT_FWREVSTRING_READ = 7,

GAUGEBLE_EVT_CUSTOMER_READ = 8,

GAUGEBLE_EVT_CON_VALUES_READ = 9,

TGaugeBle_CmdValues

Structure that contains the command values for the Gauge sensor.

iCmd:s32 - The (measurement)command that the sensor should execute.

TGaugeBle_CustomerValues

Structure that contains the customer values for the Gauge sensor.

iLevelOffset:s32 - Level offset in [mm] to be applied to the measured value.

iLevelTrim:s32 - Level trim in [mm] to be applied to the measured value.

iStamp:stamp32 - Stamp that indicates when one (or both) of the above values has last been modified.

TGaugeBle_DataValues

Structure that contains the data values that result from one measurement

iPressureRaw:s32 - The raw pressure measured.

iTemperatureRaw:s32 - The raw temperature measured.

iPressure:s32 - The pressure measured in [mBar]

iTemperature:s32 - The temperature measured in [0.01°C]

iLevel:s32 - The level measured in [mm] (taking into account offset and trim)

iBatt:s32 - The measured battery voltage in [mV] of the sensor

iRteCnt:s32 - The remaining runtime of the sensor in [h]

iFlags:s32 - The current flags of the sensor.

TGaugeBle_ProductionValues

Structure that contains the production values of one sensor.

iSerial:u32 - The serialnumber of the sensor.

iProdStamp:stamp32 - The stamp of when the sensor was produced.

iRteCnt:s32 - The inital runtime counter set during production.

fCoefficient:f32 - The coefficent for calculating the water column from the measured pressure.

GaugeBle_Measure(iGaugeHandle, iMeasureFlags = GAUGEBLE_MEASURE_START)

Trigger a measurement with the provided parameters.

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

iMeasureFlags : GAUGEBLE_MEASURE_X - The measurement mode used.

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When measurement started successfully.

GaugeBle_UpdateCustomerConfig(iGaugeHandle, sValues[TGaugeBle_CustomerValues])

Update customer config

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

sValues : TGaugeBle_CustomerValues - Customer values that should be updated

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When update started successfully.

GaugeBle_GetMeasurementValues(iGaugeHandle, sValues[TGaugeBle_DataValues])

Get measurement values

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

sValues : TGaugeBle_DataValues - The last received measurement values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

GaugeBle_GetCustomerValues(iGaugeHandle, sValues[TGaugeBle_CustomerValues])

Get current customer values

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

sValues : TGaugeBle_CustomerValues - The last received customer values values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

GaugeBle_GetProductionValues(iGaugeHandle, sValues[TGaugeBle_ProductionValues])

Get current production values

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

sValues : TGaugeBle_ProductionValues - The last received customer values values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

GaugeBle_ReadCustomerValues(iGaugeHandle)

Trigger a read of the customer values

iGaugeHandle : s32 - The handle used to identify the Gauge sensor.

returns : s32

ERROR - When invalid handle provided, otherwise

OK

Callbacks:

When using the Gauge module it is mandatory for the application to implement the following callback function.

GaugeBle_EvtSensor(iGaugeHandle, iGaugeEvent, iEventResult)

GaugeBle_EvtSensor(iGaugeHandle, iGaugeEvent, iEventResult) { switch(iGaugeEvent) { case GAUGEBLE_EVT_CONNECTED: { /* sensor found and connected. the sensor is currently initalized. */ } case GAUGEBLE_EVT_DISCONNECTED: { /* sensor disconnected in a regular manner */ } case GAUGEBLE_EVT_ERROR: { /* an error occured -> check iEventResult */ switch(iEventResult) { case GAUGEBLE_ERROR: { /* a general error occured */ } case GAUGEBLE_ERROR_CONLOST: { /* connection lost unintentionally */ } case GAUGEBLE_ERROR_NOTFOUND: { /* requested sensor not found */ } case GAUGEBLE_ERROR_READ: { /* error during a read operation */ } case GAUGEBLE_ERROR_WRITE: { /* error during a write operation */ } case GAUGEBLE_ERROR_NOTIFY: { /* error when receiving a notification */ } case GAUGEBLE_ERROR_AUTH: { /* error during authentication */ } } } case GAUGEBLE_EVT_CONFIG_DONE: { /* configuration of the sensor is done: the sensor is now ready to receive measurement commands furthermore you can read the production values of the sensor an store them somewhere */ new sProductionValues[TGaugeBle_ProductionValues]; new sFwRevisionString[TBleSensor_FwRevisionString]; GaugeBle_GetProductionValues(iGaugeHandle, sProductionValues); #log("(Gauge-Sensor %d) Production Values: %d %d %f", iGaugeHandle, sProductionValues.iSerial, sProductionValues.iProdStamp, sProductionValues.fCoefficient) GaugeBle_GetFwRevisionString(iGaugeHandle, sFwRevisionString); #log("(Gauge-Sensor %d) Firmware Version: %s", iGaugeHandle, sFwRevisionString.aFwRevisionString); } case GAUGEBLE_EVT_MEASUREDATA: { /* will be emitted after triggering a measurement with GaugeBle_Measure(): get mesurement values */ new sGaugeValues[TGaugeBle_DataValues]; GaugeBle_GetMeasurementValues(iGaugeHandle, sGaugeValues); #log("(Gauge-Sensor %d) %d mm", iGaugeHandle, sGaugeValues.iLevel); } case GAUGEBLE_EVT_FWREVSTRING_READ: { /* will be emitted after triggering a read with GaugeBle_ReadFwRevisionString */ new sFwRevisionString[TBleSensor_FwRevisionString]; GaugeBle_GetFwRevisionString(iGaugeHandle, sFwRevisionString); #log("(Gauge-Sensor %d) Firmware Version: %s", iGaugeHandle, sFwRevisionString.aFwRevisionString); } default: { /* should never be reached */ } } }

Abstract:

In this secion the gauge specific functions are described.

To use the H2S module it is necessary to set H2SBLE_SENSOR_COUNT to a value > 0 in dde.

#define H2SBLE_SENSOR_COUNT 1

H2SBLE_SENSOR_COUNT -

the number of H2S sensor instances the application wants to use.

When modifying this value, make sure to also modify BLE_SENSOR_COUNT.

Make sure that this value, combined with all other sensor instances, does not exceed BLE_SENSOR_COUNT

H2SBLE_MEASURE_X: s32

Supported measurement modes of the H2S sensor.

H2SBLE_MEASURE_START = 0x01, // start a normal measurement

H2SBLE_MEASURE_GET_RAW = 0x02, // get only raw values

H2SBLE_STATE_X:

H2S sensor states

H2SBLE_STATE_ERROR = -1,

H2SBLE_STATE_DISCONNECTED = 0,

H2SBLE_STATE_CONNECTED = 1,

H2SBLE_STATE_READY = 3,

H2SBLE_STATE_MEAS_PENDING = 4,

H2SBLE_X:

return codes for sensor events

H2SBLE_OK = BLE_SENSOR_OK,

H2SBLE_ERROR = BLE_SENSOR_ERROR,

H2SBLE_ERROR_CONLOST = BLE_SENSOR_ERROR_CONLOST,

H2SBLE_ERROR_NOTFOUND = BLE_SENSOR_ERROR_NOTFOUND,

H2SBLE_ERROR_READ = BLE_SENSOR_ERROR_READ,

H2SBLE_ERROR_WRITE = BLE_SENSOR_ERROR_WRITE,

H2SBLE_ERROR_NOTIFY = BLE_SENSOR_ERROR_NOTIFY,

H2SBLE_ERROR_AUTH = BLE_SENSOR_ERROR_AUTH,

H2SBLE_EVT_X:

sensor events

H2SBLE_EVT_NONE = 0,

H2SBLE_EVT_CONNECTED = 1,

H2SBLE_EVT_DISCONNECTED = 2,

H2SBLE_EVT_ERROR = 3,

H2SBLE_EVT_CONFIG_DONE = 5,

H2SBLE_EVT_MEASUREDATA = 6,

H2sBLE_EVT_FWREVSTRING_READ = 7,

H2SBLE_EVT_CON_VALUES_READ = 8,

TH2SBle_ConfigValues

Structure that contains the config values for the H2S sensor.

iTiacn:u8 - Only relevant for sensors with HW Version <3.0 - The gain factor for configuration of the AFE.

iRefcn:u8 - Only relevant for sensors with HW Version <3.0 - The reference resistance for configuration of the AFE in [ohm].

iTempOffset:u8 - temperature offset in [0.1 °C]

iCalScale:u32 - calibartion scale.

iCalOffset:u32 - calibration offset.

TH2SBle_ProductionValues

Structure that contains the production values for the H2S sensor.

iSerial:u32 - The serialnumber of the sensor.

iProdDate:stamp32 - The stamp of when the sensor was produced.

iLastCalib:stamp32 - The stamp of when the sensor was last calibrated.

iNextCalib:stamp32 - The stamp of when the sensor needs the next calibration.

TH2SBle_CustomerValues

Structure that contains the customer values that result from one measurement

iTrimScale:u16 - The scale that should be applied on the measured value.

iTrimOffset:u32 - The offset that should be applied on the measured value in [ppm].

sH2SBle_DataValues

Structure that contains the data values of one sensor.

iBatt:u8 - The measured battery voltage in [?? mV] of the sensor

iRaw:u16 - The raw measurement value of the sensor. ??? [mV]

iGasRaw:u32 - The raw measurement value of th sensor. ??? [ADC]

iGas:u32 - The measured gas value in [ppm]

iTemp:u16 - The measured temperature in [0.1°C ???]

iAbrasion:u32 - The abrasion of the sensor in [ppmh].

H2SBle_Measure(iH2SHandle, iMeasureFlags = H2SBLE_MEASURE_START)

Trigger a measurement with the provided parameters.

iH2SHandle : s32 - The handle used to identify the H2S sensor.

iMeasureFlags : H2SBLE_MEASURE_X - The measurement mode used.

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When measurement started successfully.

OK+1 - When measurement already pending.

H2SBle_UpdateCustomerConfig(iH2SHandle, sValues[TH2SBle_CustomerValues])

Update customer config

iH2SHandle : s32 - The handle used to identify the H2S sensor.

sValues : TH2SBle_CustomerValues - Customer values that should be updated

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When update started successfully.

OK+1 - When update already pending.

H2SBle_GetMeasurementValues(iH2SHandle, sValues[TH2SBle_DataValues])

Get measurement values

iH2SHandle : s32 - The handle used to identify the H2S sensor.

sValues : TH2SBle_DataValues - The last received measurement values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

H2SBle_GetCustomerValues(iH2SHandle, sValues[TH2SBle_CustomerValues])

Get current customer values

iH2SHandle : s32 - The handle used to identify the H2S sensor.

sValues : TH2SBle_CustomerValues - The last received customer values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

H2SBle_GetProductionValues(iH2SHandle, sValues[TH2SBle_ProductionValues])

Get current production values

iH2SHandle : s32 - The handle used to identify the H2S sensor.

sValues : TH2SBle_ProductionValues - The last received production values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

Callbacks:

When using the H2S module it is mandatory for the application to implement the following callback function.

H2SBle_EvtSensor(iH2SHandle, iH2SEvent, iEventResult)

H2SBle_EvtSensor(iH2SHandle, iH2SEvent, iEventResult) { switch(iH2SEvent) { case H2SBLE_EVT_CONNECTED: { /* sensor found and connected. the sensor is currently initalized. */ } case H2SBLE_EVT_DISCONNECTED: { /* sensor disconnected in a regular manner */ } case H2SBLE_EVT_ERROR: { /* an error occured -> check iEventResult */ switch(iEventResult) { case H2SBLE_ERROR: { /* a general error occured */ } case H2SBLE_ERROR_CONLOST: { /* connection lost unintentionally */ } case H2SBLE_ERROR_NOTFOUND: { /* requested sensor not found */ } case H2SBLE_ERROR_READ: { /* error during a read operation */ } case H2SBLE_ERROR_WRITE: { /* error during a write operation */ } case H2SBLE_ERROR_NOTIFY: { /* error when receiving a notification */ } case H2SBLE_ERROR_AUTH: { /* error during authentication */ } } } case H2SBLE_EVT_CONFIG_DONE: { /* configuration of the sensor is done: the sensor is now ready to receive measurement commands furthermore you can read the production values of the sensor an store them somewhere */ new sProductionValues[TH2SBle_ProductionValues]; new sConfigValues[TH2SBle_ConfigValues]; new sCustomerValues[TH2SBle_CustomerValues]; new sFwRevisionString[TBleSensor_FwRevisionString]; H2SBle_GetProductionValues(iH2SHandle, sProductionValues); #log("(H2S-Sensor %d) Production Values: %d %d %d %d", iH2SHandle, sProductionValues.iSerial, sProductionValues.iProdDate, sProductionValues.iLastCalib, sProductionValues.iNextCalib) H2SBle_GetConfigValues(iH2SHandle, sConfigValues); #log("(H2S-Sensor %d) Config Values: %d %d %d %d %d", iH2SHandle, sConfigValues.iTiacn, sConfigValues.iRefcn, sConfigValues.iTempOffset, sConfigValues.iCalScale, sConfigValues.iCalOffset) H2SBle_GetCustomerValues(iH2SHandle, sCustomerValues); #log("(H2S-Sensor %d) CustomerValues: %d %d", iH2SHandle, sCustomerValues.iTrimScale, sCustomerValues.iTrimOffset) H2SBle_GetFwRevisionString(iH2SHandle, sFwRevisionString); #log("(H2S-Sensor %d) Firmware Version: %s", iH2SHandle, sFwRevisionString.aFwRevisionString); } case H2SBLE_EVT_MEASUREDATA: { /* will be emitted after triggering a measurement with H2SBle_Measure(): get mesurement values */ new sH2SValues[TH2SBle_DataValues]; H2SBle_GetMeasurementValues(iH2SHandle, sH2SValues); #log("(H2S-Sensor %d) %d mm", iH2SHandle, sH2SValues.iLevel); } case H2SBLE_EVT_FWREVSTRING_READ: { /* will be emitted after triggering a read with H2SBle_ReadFwRevisionString */ new sFwRevisionString[TBleSensor_FwRevisionString]; H2SBle_GetFwRevisionString(iH2SHandle, sFwRevisionString); #log("(H2S-Sensor %d) Firmware Version: %s", iH2SHandle, sFwRevisionString.aFwRevisionString); } default: { /* should never be reached */ } } }

Abstract:

In this secion the link specific functions are described.

To use the link module it is necessary to set LINKBLE_SENSOR_COUNT to a value > 0 in dde.

#define LINKBLE_SENSOR_COUNT 1

LINKBLE_SENSOR_COUNT -

the number of link instances the application wants to use.

When modifying this value, make sure to also modify BLE_SENSOR_COUNT.

Make sure that this value, combined with all other sensor instances, does not exceed BLE_SENSOR_COUNT

LINKBLE_STATE_ERROR:

Link sensor states

LINKBLE_STATE_ERROR = -1

LINKBLE_STATE_DISCONNECTED = 0

LINKBLE_STATE_CONNECTED = 1

LINKBLE_STATE_READY = 3

LINK_FLAG_X:

sensor flags

LINK_FLAG_LOOP_OK = 0x0008

LINKBLE_X:

error codes for error event

LINKBLE_OK = BLE_SENSOR_OK

LINKBLE_ERROR = BLE_SENSOR_ERROR

LINKBLE_ERROR_CONLOST = BLE_SENSOR_ERROR_CONLOST

LINKBLE_ERROR_NOTFOUND = BLE_SENSOR_ERROR_NOTFOUND

LINKBLE_ERROR_READ = BLE_SENSOR_ERROR_READ

LINKBLE_ERROR_WRITE = BLE_SENSOR_ERROR_WRITE

LINKBLE_ERROR_NOTIFY = BLE_SENSOR_ERROR_NOTIFY

LINKBLE_ERROR_AUTH = BLE_SENSOR_ERROR_AUTH

LINKBLE_EVT_X:

sensor events

LINKBLE_EVT_NONE = 0,

LINKBLE_EVT_CONNECTED = 1,

LINKBLE_EVT_DISCONNECTED = 2,

LINKBLE_EVT_ERROR = 3,

LINKBLE_EVT_CONFIG_DONE = 5,

LINKBLE_EVT_MEASUREDATA = 6,

LINKBLE_EVT_FWREVSTRING_READ = 7,

LINKBLE_EVT_CON_VALUES_READ = 8,

TLinkBle_ProductionValues

Structure that contains the production values for the link.

iSerial:u32 - The serialnumber of the sensor.

iProdDate:stamp32 - The stamp of when the sensor was produced.

iRteCnt:u32 - The remaining runtime of the sensor.

TLinkBle_DataValues

Structure that contains the data values of one sensor.

iFlags - Current flags of the sensor, type LINK_FLAG_X.

imVBatt - Battery voltage in [mV].

LinkBle_uASetValue(iLinkHandle, iuAValue)

Set the output value in [uA]

iLinkHandle : s32 - The handle used to identify the Link sensor.

iuAValue : u32 - The uA value to set.

returns : s32

ERROR - When invalid handle provided or not ready yet.

OK - When output is set successfully.

LinkBle_GetProductionValues(iLinkHandle, sValues[TLinkBle_ProductionValues])

Get Production values

iLinkHandle : s32 - The handle used to identify the sensor.

sValues : TLinkBle_ProductionValues - The last received production values.

returns : s32

ERROR - When invalid handle provided, otherwise

OK

LinkBle_GetDataValues(iLinkHandle, sValues[TLinkBle_DataValues])

Get Data values

iLinkHandle : s32 - The handle used to identify the Link sensor.

sValues : TLinkBle_DataValues - The last received data values.

returns : s32

ERROR - When invalid handle provided or not ready yet otherwise

OK

Callbacks:

When using the Link module it is mandatory for the application to implement the following callback function.

LinkBle_EvtSensor(iLinkHandle, iLinkEvent, iEventResult)

LinkBle_EvtSensor(iLinkHandle, iLinkEvent, iEventResult) { switch(iLinkEvent) { case LINKBLE_EVT_CONNECTED: { /* sensor found and connected. the sensor is currently initalized. */ } case LINKBLE_EVT_DISCONNECTED: { /* sensor disconnected in a regular manner */ } case LINKBLE_EVT_ERROR: { /* an error occured -> check iEventResult */ switch(iEventResult) { case LINKBLE_ERROR: { /* a general error occured */ } case LINKBLE_ERROR_CONLOST: { /* connection lost unintentionally */ } case LINKBLE_ERROR_NOTFOUND: { /* requested sensor not found */ } case LINKBLE_ERROR_READ: { /* error during a read operation */ } case LINKBLE_ERROR_WRITE: { /* error during a write operation */ } case LINKBLE_ERROR_NOTIFY: { /* error when receiving a notification */ } case LINKBLE_ERROR_AUTH: { /* error during authentication */ } } } case LINKBLE_EVT_CONFIG_DONE: { /* configuration of the sensor is done: the sensor is now ready to receive measurement commands furthermore you can read the production values of the sensor an store them somewhere */ new sProductionValues[TLinkBle_ProductionValues]; LinkBle_GetProductionValues(iLinkHandle, sProductionValues); #log("(Link-Sensor %d) Production Values: %d %d", iLinkHandle, sProductionValues.iSerial, sProductionValues.iProdStamp) } case LINKBLE_EVT_MEASUREDATA: { new sLinkValues[TLinkBle_DataValues]; LinkBle_GetDataValues(iLinkHandle, sLinkValues); #log("(Link-Sensor %d) %dmV", iLinkHandle, sLinkValues.imVBatt); } case LINKBLE_EVT_FWREVSTRING_READ: { /* will be emitted after triggering a read with LinkBle_ReadFwRevisionString */ new sFwRevisionString[TBleSensor_FwRevisionString]; LinkBle_GetFwRevisionString(iLinkHandle, sFwRevisionString); #log("(Link-Sensor %d) Firmware Version: %s", iLinkHandle, sFwRevisionString.aFwRevisionString); } default: { /* should never be reached */ } } }

Abstract:

In this secion the Radar specific functions are described.

To use the Radar module it is necessary to set RADARBLE_SENSOR_COUNT to a value > 0 in the dde.

#define RADARBLE_SENSOR_COUNT 1

Measuring modes:

This sensor supports 2 measuring modes with 3 measurement profiles each.

These modes are:

Static: Each time the whole range is measured. This is quite power intense and only recomended for demonstration purposes, or if the measurement interval is longer (e.g. 5min).

Dynamic: After an initial scan of the whole range a measurement window is placed around the current water level. When measuring only this window is measured. This way is more power efficient and accureate. If the water level gets near the border of this window or jumps outside of it, the window gets moved.

The profiles are:

Default: Optimal performance to guarantee a runtime of 10 years with measurements every 10 seconds.

Filtered: Same as default but with additional median filter (filter depth = 5) and average filter (filter depth = 2).

Expert: Can be configured via RadarBle_UpdateConfig / RadarBle_UpdateConfigDynamic. Depending on the use case different radar settings might be needed. See TRadarBle_ConfigValues / TRadarBle_ConfigDynamicValues for all possible settings.

Keep in mind that the runtime of 10 years cannot be guaranteed if the expert mode with different radar settings is used. Depending on your settings it could be shorter or longer.

RADARBLE_SENSOR_COUNT -

The number of Radar sensor instances the application wants to use.

When modifying this value, make sure to also modify BLE_SENSOR_COUNT.

Make sure that this value, combined with all other sensor instances, does not exceed BLE_SENSOR_COUNT

RADARBLE_DEBUG_NOTIFICATION -

Enable debug notifications to get additional data of the dynamic mode in use and latest measurement.

If you do not want to get debug notifications set this define to 0 or remove it completely.

If you want to get debug notifications set this define to >= 1.

RADARBLE_MEASURE_X:

Supported measurement modes of the Radar sensor.

RADARBLE_MEASURE_DEFAULT = 0x01 - start a measurement with preset default

RADARBLE_MEASURE_FILTERED = 0x02 - start a measurement with preset filtered

RADARBLE_MEASURE_EXPERT = 0x03 - start a measurement with expert configuration

RADARBLE_MEASURE_DYN_DEFAULT = 0x11 - start a dynamic measurement with preset default

RADARBLE_MEASURE_DYN_FILTERED = 0x12 - start a dynamic measurement with preset filtered

RADARBLE_MEASURE_DYN_EXPERT = 0x13 - start a dynamic measurement with expert configuration

RADARBLE_X:

return codes for sensor events

RADARBLE_OK = BLE_SENSOR_OK

RADARBLE_ERROR = BLE_SENSOR_ERROR

RADARBLE_ERROR_CONLOST = BLE_SENSOR_ERROR_CONLOST

RADARBLE_ERROR_NOTFOUND = BLE_SENSOR_ERROR_NOTFOUND

RADARBLE_ERROR_READ = BLE_SENSOR_ERROR_READ

RADARBLE_ERROR_WRITE = BLE_SENSOR_ERROR_WRITE

RADARBLE_ERROR_NOTIFY = BLE_SENSOR_ERROR_NOTIFY

RADARBLE_ERROR_AUTH = BLE_SENSOR_ERROR_AUTH

RADARBLE_EVT_X:

sensor events

RADARBLE_EVT_NONE = 0

RADARBLE_EVT_CONNECTED = 1

RADARBLE_EVT_DISCONNECTED = 2

RADARBLE_EVT_ERROR = 3

RADARBLE_EVT_CONFIG_DONE = 5

RADARBLE_EVT_MEASUREDATA = 6

RADARBLE_EVT_CONFIG_READ = 7

RADARBLE_EVT_PRODUCTION_READ = 8

RADARBLE_EVT_CUSTOMER_READ = 9

RADARBLE_EVT_CONFIG_DYN_READ = 10

RADARBLE_EVT_DEBUG_DATA = 11

RADARBLE_EVT_ECHO_CURVE_DATA = 12

RADARBLE_EVT_FWREVSTRING_READ = 13

RADARBLE_EVT_THRESHOLD_READ = 14,

RADARBLE_EVT_CON_VALUES_READ = 15,

RADARBLE_STATE_X:

sensor state

RADARBLE_STATE_ERROR = -1

RADARBLE_STATE_DISCONNECTED = 0

RADARBLE_STATE_CONNECTED = 1

RADARBLE_STATE_READY = 3

RADARBLE_VALUE_STATUS_X:

measurement value status

RADARBLE_VALUE_STATUS_OK = 0x00 - Value is within measurement range

RADARBLE_VALUE_STATUS_HOLD = 0x01 - Value is hold because the last measured value was outside of the measurement range

RADARBLE_VALUE_STATUS_OF = 0x02 - Value outside/above measurement range (OverFlow)

RADARBLE_VALUE_STATUS_UF = 0x04 - Value outside/below measurement range (UnderFlow)

RADARBLE_VALUE_STATUS_UF_LEVEL = 0x08 - Distance > Level Mount + Level Trim

RADARBLE_FS_X:

supported features

RADARBLE_FS_THRESHOLD = 0x00000001 - Sensor supports threshold configuration characteristic

RADARBLE_FS_PROD_TEMP_OFFSET = 0x00000002 - Production data includes temperature offset

TRadarBle_ConfigValues

Structure that contains the radar and filter configuration

iRangeStart:u16 - Start of the measurement range in [mm]

iRangeLength:u16 - Length of the measurement range in [mm]

iServiceProfile:u8 - Service profile

1 = maximum depth resolution

2 = sliding scale between profile 1 and 5

3 = sliding scale between profile 1 and 5

4 = sliding scale between profile 1 and 5

5 = maximum radar loop gain

iDownsamplingFactor:u8 - Downsampling factor/measurement resolution

1 = 0,5mm

2 = 1mm

4 = 2mm

iSweepAverage:u16 - Number of measurement sweeps used each measurement to calculate an average from

iHWAAS:u8 - Number of hardware accelerated average samples

iGain:u16 - Gain in [‰]

iFlags:u8 - Flags

iSorting:u8 - Peak sorting algorithm

0 = Closest First

1 = Strongest First

2 = Strongest Reflector First

3 = Strongest Flat Reflector First

iThreshold:u16 - Amplitude hight a peak has to have to be considered as a peak of interest

Keep in mind that any changes to these parameters so far might result in a shorter runtime of the sensor.

iMedianFilterDepth:u8 - Median filter depth, 1 to deactivate median filter

iAvgFilterDepth:u8 - Average filter depth, 1 to deactivate average filter

iHoldValues:u8 - Hold values for plausibility check

TRadarBle_ProductionValues

Structure that contains the production values for the Radar sensor

iSerial:u32 - Serialnumber of the sensor

iProdStamp:stamp32 - Timestamp of when the sensor was produced

iDevOffset:s16 - Offset from the 0 point of the sensor to the 0 point marked on the case

iRuntimeEstimation:u32 - Initial runtime counter set during production in [h]

iRuntimeFlags:u8 - Flags regarding runtime estimation

0x00 = Ok

0x01 = Expert mode activated

If in expert mode the radar config got changed the runtime estimation cannot be trusted. E.g. if the sweep average parameter got increased the runtime will be shorter.

iTempOffset:s16 - Temperature offset in [0.01°C]

This variable got introduced in the Firmware version 00v016.

TRadarBle_DataValues

Structure that contains the data values that result from one measurement

iDistance:u16 - Measured distance in [mm]

iRuntimeEstimation:u32 - Estimated runtime in [h]

iLevel:s16 - Calculated fill level in [mm]

iValueStatus:RADARBLE_VALUE_STATUS_X - State of the values regarding the plausibility check

iAmplitude:u16 - Amplitude of the measured distance

imVBatt:u16 - Battery voltage in [mV]

iTemperature:s16 - Die temperature in [0.01°C]

TRadarBle_CustomerValues

Structure that contains the customer values for the Radar sensor

iLevelMount:u16 - Mounting hight of the sensor in [mm]

iLevelTrim:s16 - Fine adjustment/trimming in [mm]

iLevelTimeStamp:stamp32 - Timestamp when this config was last changed

TRadarBle_ConfigDynamicValues

Structure that contains the radar and filter configuration for the dynamic mode

iRangeLength:u16 - Length of the measurement range in [mm]

iDownsamplingFactor:u8 - Downsampling factor/measurement resolution

1 = 0,5mm

2 = 1mm

4 = 2mm

iSweepAverage:u16 - Number of measurement sweeps used each measurement to calculate an average from

iHWAAS:u8 - Number of hardware accelerated average samples

iGain:u16 - Gain in [‰]

iFlags:u8 - Flags

iSorting:u8 - Peak sorting algorithm

0 = Closest First

1 = Strongest First

2 = Strongest Reflector First

3 = Strongest Flat Reflector First

iThreshold:u16 - Amplitude hight a peak has to have to be considered as a peak of interest

Keep in mind that any changes to these parameters so far might result in a shorter runtime of the sensor.

iMedianFilterDepth:u8 - Median filter depth, 1 to deactivate median filter

iAvgFilterDepth:u8 - Average filter depth, 1 to deactivate average filter

iHoldValues:u8 - Hold values for plausibility check

iBorderRegionSize:u8 - Size of the upper and lower border region in [mm]

TRadarBle_DebugValues

Structure that contains the debug values for the dynamic mode in use and the latest measurement

iDynamicRangeStart:u16 - Start of the measurement range in [mm] determined by the device

iDynamicServiceProfile:u8 - Service profile determined by the device

iDynamicProfileFlags:u8 - Flags of the dynamic profile

0x01 = Dynamic Default in use

0x02 = Dynamic Filtered in use

0x04 = Dynamic Expert in use

0x08 = Determination mode activate

0x10 = Measuring within blocking distance

iNumberOfPeaks:u16 - Number of found peaks during latest measurement

iMeasurementFlags:u8 - Information regarding the latest measurement

0x01 = Data Quality Warning

0x02 = Data Saturation

0x04 = Missed Data

0x08 = Sensor Communication Error

TRadarBle_EchoCurveValues

Structure that contains points of interest of the echo curve

iDistance:u16 - Distance of a point of interest

iAmplitude:u16 - Amplitude of a point of interest

TRadarBle_ThresholdValues

iType:u8 - Threshold filter type to use

0 = Fixed

Threshold is configured via the iThreshold parameter of a TRadarBle_ConfigValues or a TRadarBle_ConfigDynamicValues

1 = Recorded

Not supported

2 = CFAR

iCFARSensitivity:u16 - Sensitivity from 0.01 to 1 in 0.0001 steps

iCFARGuard:u16 - Guard from 10mm to 200mm

iCFARWindow:u16 - Windos form 1mm to 200mm

iFlags:u8 - CFAR configuration flags

0x01 = only use the lower distance for the threshold calculation

RadarBle_Measure(iRadarHandle, iMeasureProfile = RADARBLE_MEASURE_DYN_DEFAULT)

Trigger a measurement with the chosen measurement profile

iRadarHandle : s32 - Handle used to identify the Radar sensor

iMeasureProfile : RADARBLE_MEASURE_X - Profile to use for the measurement

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_UpdateConfig(iRadarHandle, sValues)

Update radar and filter configuration

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ConfigValues - Configuration values that should be updated

returns : s32

ERROR - When invalid handle provided, otherwise

OK

After a few seconds you can perform RadarBle_ReadConfig to check if the sensor accepted the new configuration values

RadarBle_UpdateCustomerConfig(iRadarHandle, sValues)

Update customer configuration

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_CustomerValues - Customer values that should be updated

returns : s32

ERROR - When invalid handle provided, otherwise

OK

After a few seconds you can perform RadarBle_ReadCustomer to check if the sensor accepted the new consumer values

RadarBle_UpdateConfigDynamic(iRadarHandle, sValues)

Update radar and filter configuration

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ConfigDynamicValues - Configuration values that should be updated

returns : s32

ERROR - When invalid handle provided, otherwise

OK

After a few seconds you can perform RadarBle_ReadConfigDynamic to check if the sensor accepted the new configuration values

RadarBle_CheckEchoCurve(iRadarHandle)

Trigger a measurement of the echo curve

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_UpdateThresholdConfig(iRadarHandle, sValues)

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ThresholdValues - Threshold configuration values that should be updated

ERROR - When invalid handle provided,

ERROR_NOTSUPPORTED - when the threshold config isn't present on the connected Radar sensor (pre Firmware version 00v016), otherwise

OK

RadarBle_GetMeasurementValues(iRadarHandle, sValues)

Get current measurement values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_DataValues - The last received measurement values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetConfigValues(iRadarHandle, sValues)

Get current configuration values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ConfigValues - The last received configuration values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetProductionValues(iRadarHandle, sValues)

Get current production values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ProductionValues - The last received production values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetCustomerValues(iRadarHandle, sValues)

Get current customer values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_CustomerValues - The last received customer values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetConfigDynamicValues(iRadarHandle, sValues)

Get current configuration dynamic values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ConfigDynamicValues - The last received configuration dynamic values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetDebugValues(iRadarHandle, sValues)

Get current debug values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_DebugValues - The last received debug values

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetEchoCurve(iRadarHandle, asValues[])

Get current echo curve

iRadarHandle : s32 - Handle used to identify the Radar sensor

asValues[] : TRadarBle_EchoCurveValues - Array which contains the last received echo curve

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_GetThresholdConfig(iRadarHandle, sValues)

Get current threshold configuration values

iRadarHandle : s32 - Handle used to identify the Radar sensor

sValues : TRadarBle_ThresholdValues - The last received threshold configuration values

returns : s32

ERROR - When invalid handle provided,

ERROR_NOTSUPPORTED - when the threshold config isn't present on the connected Radar sensor (pre Firmware version 00v016), otherwise

OK

RadarBle_GetFeatureset(iRadarHandle, iValues)

Get current featureset

iRadarHandle : s32 - Handle used to identify the Radar sensor

iValues : s32 - Featureset of the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadMeasurementValues(iRadarHandle)

Trigger a read of the measurement values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadConfig(iRadarHandle)

Trigger a read of the configuration values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadProduction(iRadarHandle)

Trigger a read of the production values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadCustomer(iRadarHandle)

Trigger a read of the customer values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadConfigDynamic(iRadarHandle)

Trigger a read of the configuration dynamic values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadDebug(iRadarHandle)

Trigger a read of the debug values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadEchoCurve(iRadarHandle)

Trigger a read of the echo curve values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided, otherwise

OK

RadarBle_ReadThresholdConfig(iRadarHandle)

Trigger a read of the threshold configuration values

iRadarHandle : s32 - Handle used to identify the Radar sensor

returns : s32

ERROR - When invalid handle provided,

ERROR_NOTSUPPORTED - when the threshold config isn't present on the connected Radar sensor (pre Firmware version 00v016), otherwise

OK

Callbacks:

When using the Radar module it is mandatory for the application to implement the following callback function.

RadarBle_EvtSensor(iRadarHandle, iRadarEvent, iEventResult)

RadarBle_EvtSensor(iRadarHandle, iRadarEvent, iEventResult) { switch(iRadarEvent) { case RADARBLE_EVT_CONNECTED: { /* sensor found and connected. the sensor is currently initalized. */ } case RADARBLE_EVT_DISCONNECTED: { /* sensor disconnected in a regular manner */ } case RADARBLE_EVT_ERROR: { /* an error occured -> check iEventResult */ switch(iEventResult) { case RADARBLE_ERROR: { /* a general error occured */ } case RADARBLE_ERROR_CONLOST: { /* connection lost unintentionally */ } case RADARBLE_ERROR_NOTFOUND: { /* requested sensor not found */ } case RADARBLE_ERROR_READ: { /* error during a read operation */ } case RADARBLE_ERROR_WRITE: { /* error during a write operation */ } case RADARBLE_ERROR_NOTIFY: { /* error when receiving a notification */ } case RADARBLE_ERROR_AUTH: { /* error during authentication */ } } } case RADARBLE_EVT_CONFIG_DONE: { /* configuration of the sensor is done: the sensor is now ready to receive measurement commands furthermore you can read the production, configuration and customer values of the sensor and store them somewhere */ /* get current values */ new sProductionValues[TRadarBle_ProductionValues]; new sConfigValues[TRadarBle_ConfigValues]; new sCustomerValues[TRadarBle_CustomerValues]; new sConfigDynamicValues[TRadarBle_ConfigDynamicValues]; new sFwRevisionString[TBleSensor_FwRevisionString]; new sThresholdValues[TRadarBle_ThresholdValues]; new iFeatureset; RadarBle_GetFeatureset(iRadarHandle, iFeatureset); RadarBle_GetProductionValues(iRadarHandle, sProductionValues); if(iFeatureset & RADARBLE_FS_PROD_TEMP_OFFSET) #log("(Radar-Sensor %d) Production Values: %d %d %d %d %d %d", iRadarHandle, sProductionValues.iSerial, sProductionValues.iProdStamp, sProductionValues.iDevOffset, sProductionValues.iRuntimeEstimation, sProductionValues.iRuntimeFlags, sProductionValues.iTempOffset); else #log("(Radar-Sensor %d) Production Values: %d %d %d %d %d", iRadarHandle, sProductionValues.iSerial, sProductionValues.iProdStamp, sProductionValues.iDevOffset, sProductionValues.iRuntimeEstimation, sProductionValues.iRuntimeFlags); RadarBle_GetConfigValues(iRadarHandle, sConfigValues); #log("(Radar-Sensor %d) Config Values: %d %d %d %d %d %d %d %d %d %d %d %d %d", iRadarHandle, sConfigValues.iRangeStart, sConfigValues.iRangeLength, sConfigValues.iServiceProfile, sConfigValues.iDownsamplingFactor, sConfigValues.iSweepAverage, sConfigValues.iHWAAS, sConfigValues.iGain, sConfigValues.iFlags, sConfigValues.iSorting, sConfigValues.iThreshold, sConfigValues.iMedianFilterDepth, sConfigValues.iAvgFilterDepth, sConfigValues.iHoldValues); RadarBle_GetCustomerValues(iRadarHandle, sCustomerValues); #log("(Radar-Sensor %d) Customer Config Values: %d %d %d", iRadarHandle, sCustomerValues.iLevelMount, sCustomerValues.iLevelTrim, sCustomerValues.iLevelTimeStamp); RadarBle_GetConfigDynamicValues(iRadarHandle, sConfigDynamicValues); #log("(Radar-Sensor %d) Config Dynamic Values: %d %d %d %d %d %d %d %d %d %d %d %d", iRadarHandle, sConfigDynamicValues.iRangeLength, sConfigDynamicValues.iDownsamplingFactor, sConfigDynamicValues.iSweepAverage, sConfigDynamicValues.iHWAAS, sConfigDynamicValues.iGain, sConfigDynamicValues.iFlags, sConfigDynamicValues.iSorting, sConfigDynamicValues.iThreshold, sConfigDynamicValues.iMedianFilterDepth, sConfigDynamicValues.iAvgFilterDepth, sConfigDynamicValues.iHoldValues, sConfigDynamicValues.iBorderRegionSize); RadarBle_GetFwRevisionString(iRadarHandle, sFwRevisionString); #log("(Radar-Sensor %d) Firmware Version: %s", iRadarHandle, sFwRevisionString.aFwRevisionString); if(iFeatureset & RADARBLE_FS_THRESHOLD) { RadarBle_GetThresholdConfig(iRadarHandle, sThresholdValues); #log("(Radar-Sensor %d) Threshold: %d %d %d %d 0x%02X", iRadarHandle, sThresholdValues.iType, sThresholdValues.iCFARSensitivity, iRadarHandle, sThresholdValues.iCFARGuard, iRadarHandle, sThresholdValues.iCFARWindow, iRadarHandle, sThresholdValues.iFlags); } } case RADARBLE_EVT_MEASUREDATA: { /* will be emitted after triggering a measurement with RadarBle_Measure() or after triggering a read with RadarBle_ReadMeasurementValues() */ /* get measurement values */ new sRadarMeasureValues[TRadarBle_DataValues]; new strStatus[40]; strcpy(strStatus, "OK"); RadarBle_GetMeasurementValues(iRadarHandle, sRadarMeasureValues); if(sRadarMeasureValues.iValueStatus & RADARBLE_VALUE_STATUS_HOLD) strcpy(strStatus, "Value on Hold"); else if(sRadarMeasureValues.iValueStatus & RADARBLE_VALUE_STATUS_OF) strcpy(strStatus, "OverFlow"); else if(sRadarMeasureValues.iValueStatus & RADARBLE_VALUE_STATUS_UF) strcpy(strStatus, "UnderFlow"); if(sRadarMeasureValues.iValueStatus & RADARBLE_VALUE_STATUS_UF_LEVEL) strcat(strStatus, " | Level UnderFlow"); #log("(Radar-Sensor %d) Distance: %d mm", iRadarHandle, sRadarMeasureValues.iDistance); #log("(Radar-Sensor %d) Runtime Estimation: %d h", iRadarHandle, sRadarMeasureValues.iRuntimeEstimation); #log("(Radar-Sensor %d) Level: %d mm", iRadarHandle, sRadarMeasureValues.iLevel); #log("(Radar-Sensor %d) Status: %d(%s)", iRadarHandle, sRadarMeasureValues.iValueStatus, strStatus); #log("(Radar-Sensor %d) Amplitude: %d", iRadarHandle, sRadarMeasureValues.iAmplitude); #log("(Radar-Sensor %d) Battery Voltage: %d mV", iRadarHandle, sRadarMeasureValues.imVBatt); #log("(Radar-Sensor %d) Temperature: %d,%d °C", iRadarHandle, sRadarMeasureValues.iTemperature / 100, sRadarMeasureValues.iTemperature % 100); } case RADARBLE_EVT_CONFIG_READ: { /* will be emitted after triggering a read with RadarBle_ReadConfig() */ /* get current configuration values */ new sConfigValues[TRadarBle_ConfigValues]; RadarBle_GetConfigValues(iRadarHandle, sConfigValues); #log("(Radar-Sensor %d) Range Start %d mm", iRadarHandle, sConfigValues.iRangeStart); #log("(Radar-Sensor %d) Range Length: %d mm", iRadarHandle, sConfigValues.iRangeLength); #log("(Radar-Sensor %d) Service Profile: %d", iRadarHandle, sConfigValues.iServiceProfile); #log("(Radar-Sensor %d) Downsampling Factor: %d", iRadarHandle, sConfigValues.iDownsamplingFactor); #log("(Radar-Sensor %d) Sweep Average: %d", iRadarHandle, sConfigValues.iSweepAverage); #log("(Radar-Sensor %d) HWAAS: %d", iRadarHandle, sConfigValues.iHWAAS); #log("(Radar-Sensor %d) Gain: %d", iRadarHandle, sConfigValues.iGain); #log("(Radar-Sensor %d) Flags: %d", iRadarHandle, sConfigValues.iFlags); #log("(Radar-Sensor %d) Sorting: %d", iRadarHandle, sConfigValues.iSorting); #log("(Radar-Sensor %d) Threshold: %d", iRadarHandle, sConfigValues.iThreshold); #log("(Radar-Sensor %d) Median Filter Depth: %d", iRadarHandle, sConfigValues.iMedianFilterDepth); #log("(Radar-Sensor %d) Avg Filter Depth: %d", iRadarHandle, sConfigValues.iAvgFilterDepth); #log("(Radar-Sensor %d) Hold Values: %d", iRadarHandle, sConfigValues.iHoldValues); } case RADARBLE_EVT_PRODUCTION_READ: { /* will be emitted after triggering a read with RadarBle_ReadProduction() */ /* get current production values */ new sProductionValues[TRadarBle_ProductionValues]; new iFeatureset; RadarBle_GetProductionValues(iRadarHandle, sProductionValues); RadarBle_GetFeatureset(iRadarHandle, iFeatureset); #log("(Radar-Sensor %d) Serial Number: %d", iRadarHandle, sProductionValues.iSerial); #log("(Radar-Sensor %d) Production Timestamp: %d", iRadarHandle, sProductionValues.iProdStamp); #log("(Radar-Sensor %d) Device Offset: %d mm", iRadarHandle, sProductionValues.iDevOffset); #log("(Radar-Sensor %d) Runtime Estimation: %d h", iRadarHandle, sProductionValues.iRuntimeEstimation); #log("(Radar-Sensor %d) Runtime Flags: %d", iRadarHandle, sProductionValues.iRuntimeFlags); if(iFeatureset & RADARBLE_FS_PROD_TEMP_OFFSET) #log("(Radar-Sensor %d) Temperature Offset: %d [0.01°C]", iRadarHandle, sProductionValues.iTempOffset); } case RADARBLE_EVT_CUSTOMER_READ: { /* will be emitted after triggering a read with RadarBle_ReadCustomer() */ /* get current customer values */ new sCustomerValues[TRadarBle_CustomerValues]; RadarBle_GetCustomerValues(iRadarHandle, sCustomerValues); #log("(Radar-Sensor %d) Level Mount: %d mm", iRadarHandle, sCustomerValues.iLevelMount); #log("(Radar-Sensor %d) Level Trim: %d mm", iRadarHandle, sCustomerValues.iLevelTrim); #log("(Radar-Sensor %d) Level Timestamp: %d", iRadarHandle, sCustomerValues.iLevelTimeStamp); } case RADARBLE_EVT_CONFIG_DYN_READ: { /* will be emitted after triggering a read with RadarBle_ReadConfigDynamic() */ /* get current configuration dynamic values*/ new sConfigDynamicValues[TRadarBle_ConfigDynamicValues]; RadarBle_GetConfigDynamicValues(iRadarHandle, sConfigDynamicValues); #log("(Radar-Sensor %d) Range Length: %d mm", iRadarHandle, sConfigDynamicValues.iRangeLength); #log("(Radar-Sensor %d) Downsampling Factor: %d", iRadarHandle, sConfigDynamicValues.iDownsamplingFactor); #log("(Radar-Sensor %d) Sweep Average: %d", iRadarHandle, sConfigDynamicValues.iSweepAverage); #log("(Radar-Sensor %d) HWAAS: %d", iRadarHandle, sConfigDynamicValues.iHWAAS); #log("(Radar-Sensor %d) Gain: %d", iRadarHandle, sConfigDynamicValues.iGain); #log("(Radar-Sensor %d) Flags: %d", iRadarHandle, sConfigDynamicValues.iFlags); #log("(Radar-Sensor %d) Sorting: %d", iRadarHandle, sConfigDynamicValues.iSorting); #log("(Radar-Sensor %d) Threshold: %d", iRadarHandle, sConfigDynamicValues.iThreshold); #log("(Radar-Sensor %d) Median Filter Depth: %d", iRadarHandle, sConfigDynamicValues.iMedianFilterDepth); #log("(Radar-Sensor %d) Avg Filter Depth: %d", iRadarHandle, sConfigDynamicValues.iAvgFilterDepth); #log("(Radar-Sensor %d) Hold Values: %d", iRadarHandle, sConfigDynamicValues.iHoldValues); #log("(Radar-Sensor %d) Border Region Size: %d mm", iRadarHandle, sConfigDynamicValues.iBorderRegionSize); } case RADARBLE_EVT_DEBUG_DATA: { /* will be emitted after triggering a read with RadarBle_ReadDebug() or if debug notifications are activated */ /* get currend debug values */ new sDebugValues[TRadarBle_DebugValues]; RadarBle_GetDebugValues(iRadarHandle, sDebugValues); #log("(Radar-Sensor %d) Range Start: %d mm", iRadarHandle, sDebugValues.iDynamicRangeStart); #log("(Radar-Sensor %d) Service profile: %d", iRadarHandle, sDebugValues.iDynamicServiceProfile); #log("(Radar-Sensor %d) Profile Flags: 0x%02X", iRadarHandle, sDebugValues.iDynamicProfileFlags); #log("(Radar-Sensor %d) Peaks found: %d", iRadarHandle, sDebugValues.iNumberOfPeaks); #log("(Radar-Sensor %d) Measurement Flags: 0x%02X", iRadarHandle, sDebugValues.iMeasurementFlags); } case RADARBLE_EVT_ECHO_CURVE_DATA: { /* will be emitted after triggering a measurement of the measurement range with RadarBle_CheckMeasurementRange() or after triggering a read with RadarBle_ReadMeasurementRange() */ /* get currend debug values */ new asEchoCurveValues[RADARBLE_MAX_POINTS_OF_INTEREST][TRadarBle_EchoCurveValues]; RadarBle_GetEchoCurve(iRadarHandle, asEchoCurveValues); #log("(Radar-Sensor %d) Meas Range:", iRadarHandle); for(new i = 0; asEchoCurveValues[i].iDistance != 0 && i < RADARBLE_MAX_POINTS_OF_INTEREST; i++) { #log(" distance: %d mm", asEchoCurveValues[i].iDistance); #log(" amplitude: %d", asEchoCurveValues[i].iAmplitude); } } case RADARBLE_EVT_THRESHOLD_READ: { /* will be emitted after triggering a read with RadarBle_ReadThresholdConfig() */ /* get currend threshold config values */ #log("(Radar-Sensor %d) RADARBLE_EVT_THRESHOLD_READ", iRadarHandle); new sThresholdValues[TRadarBle_ThresholdValues]; RadarBle_GetThresholdConfig(iRadarHandle, sThresholdValues); #log("(Radar-Sensor %d) Type: %d", iRadarHandle, sThresholdValues.iType); #log("(Radar-Sensor %d) CFAR Sensitivity: %d", iRadarHandle, sThresholdValues.iCFARSensitivity); #log("(Radar-Sensor %d) CFAR Guard: %d", iRadarHandle, sThresholdValues.iCFARGuard); #log("(Radar-Sensor %d) CFAR Window: %d", iRadarHandle, sThresholdValues.iCFARWindow); #log("(Radar-Sensor %d) Flags: 0x%02X", iRadarHandle, sThresholdValues.iFlags); } case RADARBLE_EVT_FWREVSTRING_READ: { /* will be emitted after triggering a read with RadarBle_ReadFwRevisionString */ /* get current firmware revision string */ new sFwRevisionString[TBleSensor_FwRevisionString]; RadarBle_GetFwRevisionString(iRadarHandle, sFwRevisionString); #log("(Radar-Sensor %d) Firmware Version: %s", iRadarHandle, sFwRevisionString.aFwRevisionString); } default: { /* should never be reached */ } } }

Libraries

BLE Sensor Library

Description

Overview

Supported Sensors:

Common

BLE ADIN

BLE Gauge

BLE H2S

BLE Link

BLE Radar

On this page

BLE Sensor Library