DriveWorks SDK Reference
3.0.4260 Release
For Test and Development only

Detailed Description

Provides an interface for non-standard sensors.

Data Structures

struct  dwSensorCommonPluginFunctions
 Function Table exposing common plugin functions. More...
 
struct  dwSensorPluginProperties
 Structure for generic constants returned by the plugin. More...
 

Typedefs

typedef dwStatus(* dwSensorPlugin_createHandle) (dwSensorPluginSensorHandle_t *handle, dwSensorPluginProperties *properties, const char *params, dwContextHandle_t ctx)
 Creates a new handle to the sensor managed by the plugin module. More...
 
typedef dwStatus(* dwSensorPlugin_createSensor) (const char *params, dwSALHandle_t sal, dwSensorPluginSensorHandle_t handle)
 Creates and initializes a new sensor managed by the plugin. More...
 
typedef dwStatus(* dwSensorPlugin_pushData) (size_t *lenPushed, const uint8_t *data, const size_t size, dwSensorPluginSensorHandle_t handle)
 Pushes raw data obtained from a previous 'dwSensorPlugin_readRawData' call for decoding. More...
 
typedef dwStatus(* dwSensorPlugin_readRawData) (const uint8_t **data, size_t *size, dwTime_t *timestamp, dwTime_t timeout_us, dwSensorPluginSensorHandle_t handle)
 Reads RAW data for one single message from the sensor as byte array. More...
 
typedef dwStatus(* dwSensorPlugin_release) (dwSensorPluginSensorHandle_t handle)
 Releases a sensor managed by the plugin module. More...
 
typedef dwStatus(* dwSensorPlugin_reset) (dwSensorPluginSensorHandle_t handle)
 Resets the sensor. More...
 
typedef dwStatus(* dwSensorPlugin_returnRawData) (const uint8_t *data, dwSensorPluginSensorHandle_t handle)
 Returns RAW data to sensor as a byte array. More...
 
typedef dwStatus(* dwSensorPlugin_start) (dwSensorPluginSensorHandle_t handle)
 Starts the sensor previously successfully created with 'dwSensorPlugin_createSensor' interface. More...
 
typedef dwStatus(* dwSensorPlugin_stop) (dwSensorPluginSensorHandle_t handle)
 Stops the sensor. More...
 
typedef void * dwSensorPluginSensorHandle_t
 

Data Structure Documentation

◆ dwSensorCommonPluginFunctions

struct dwSensorCommonPluginFunctions

◆ dwSensorPluginProperties

struct dwSensorPluginProperties
Data Fields
size_t packetSize Packet size for each raw data message.

Typedef Documentation

◆ dwSensorPlugin_createHandle

typedef dwStatus(* dwSensorPlugin_createHandle) (dwSensorPluginSensorHandle_t *handle, dwSensorPluginProperties *properties, const char *params, dwContextHandle_t ctx)

Creates a new handle to the sensor managed by the plugin module.

Parameters
[out]handleA pointer to sensor handle.
[out]propertiesSensor-specific properties & constants returned by the plugin.
[in]paramsSpecifies the parameters for the sensor.
[in]ctxcontext handle.
Returns
DW_INVALID_ARGUMENT - if pointer to the sensor handle is NULL.
DW_SUCCESS

Definition at line 96 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_createSensor

typedef dwStatus(* dwSensorPlugin_createSensor) (const char *params, dwSALHandle_t sal, dwSensorPluginSensorHandle_t handle)

Creates and initializes a new sensor managed by the plugin.

The created sensor will be released using the 'dwSensorPlugin_releaseSensor' interface.

Parameters
[in]paramsSpecifies the parameters for sensor creation.
[in]salSAL handle.
[in]handleA sensor handle previously created w/ the 'dwSensorPlugin_createHandle' interface.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_SAL_SENSOR_ERROR - if a non recoverable error happens during sensor creation.
DW_SUCCESS

Definition at line 126 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_pushData

typedef dwStatus(* dwSensorPlugin_pushData) (size_t *lenPushed, const uint8_t *data, const size_t size, dwSensorPluginSensorHandle_t handle)

Pushes raw data obtained from a previous 'dwSensorPlugin_readRawData' call for decoding.

Depending on the sensor implementation, actual decoding may happen synchronously on this call, or on a subsequently 'dwSensorPlugin_pushData' call when enough raw data has been received.

Parameters
[out]lenPushedA pointer to the amount of data that was successfully pushed to the plugin
[in]dataA pointer to data that was populated with the RAW data.
[in]sizeSize of the data to be pushed
[in]handleSpecifies the sensor the data came from.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_CALL_NOT_ALLOWED - if sensor cannot execute the call, for example, due to decoding data.
DW_NOT_SUPPORTED - if sensor does not implement this functionality.
DW_INVALID_ARGUMENT - if given data pointer is invalid.
DW_SUCCESS

Definition at line 246 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_readRawData

typedef dwStatus(* dwSensorPlugin_readRawData) (const uint8_t **data, size_t *size, dwTime_t *timestamp, dwTime_t timeout_us, dwSensorPluginSensorHandle_t handle)

Reads RAW data for one single message from the sensor as byte array.

This should be the raw unprocessed data received from the sensor. Generally this is the entrypoint to perform a read operation on the sensor.

For each raw "message" from the sensor, data must be packed in the following memory layout:

|--------------------------------------------—|------------------------—| | Header | | ---------------------------------------------—|------------------------—| | | | | | Payload Size (uint32_t) | Timestamp (dwTime_t)| Payload | |_________________________|_____________________|___________________________|

CAN Bus sensors do not need to abide by this payload structure, as metadata is already contained within their data structure. CAN sensors may just ouput a dwCANMessage via this API.

It is the responsiblility of the plugin author to do perform the memory allocation for the memory buffer that will be given out via this API.

Please note the following considerations on the behavior of this API:

1. This API may be called several times before a call to 'dwSensorPlugin_returnRawData',
   which means your plugin implementation must support multiple "raw data" buffers in flight.
2. The buffer given out by this API will be returned by a call to '_dwSensorPlugin_returnRawData()'
3. The size reported as the output of this API shall include the header shown above
Note
To support the multiple buffers in flight behavior described again, a reference BufferPool data structure implementation is released with the plugin samples.
Parameters
[out]dataA pointer to the pointer to data that is populated with the RAW data.
[out]sizeA pointer to the size of the data array.
[out]timestampSpecifies the host timestamp of raw data message.
[in]timeout_usSpecifies the timeout in us to wait before unblocking.
[in]handleSpecifies the sensor handle to read from.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_NOT_SUPPORTED - if sensor does not implement this functionality.
DW_CALL_NOT_ALLOWED - if sensor cannot execute the call, for example, due to decoding data.
DW_INVALID_ARGUMENT - if one of the given arguments is invalid.
DW_TIME_OUT - if the requested timed out.
DW_SAL_SENSOR_ERROR - if there was an unrecoverable i/o error.
DW_SUCCESS

Definition at line 211 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_release

typedef dwStatus(* dwSensorPlugin_release) (dwSensorPluginSensorHandle_t handle)

Releases a sensor managed by the plugin module.

Note
This method renders the sensor handle unusable.
Parameters
[in]handleThe handle to a sensor created previously with the 'dwSensorPlugin_createHandle' interface.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_SUCCESS

Definition at line 111 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_reset

typedef dwStatus(* dwSensorPlugin_reset) (dwSensorPluginSensorHandle_t handle)

Resets the sensor.

The method shall block while the sensor is reset.

Note
It is guarunteed that all outstanding references to sensor data will be returned prior to this call.
Parameters
[in]handleA sensor handle previously created w/ the 'dwSensorPlugin_createHandle' interface.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_SAL_SENSOR_ERROR - if a non recoverable error happens during sensor reset.
DW_SUCCESS

Definition at line 164 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_returnRawData

typedef dwStatus(* dwSensorPlugin_returnRawData) (const uint8_t *data, dwSensorPluginSensorHandle_t handle)

Returns RAW data to sensor as a byte array.

The returned pointer must have been previously obtained by a call to the 'dwSensorPlugin_readRawData' interface.

Parameters
[in]dataA pointer to data that was populated with the RAW data.
[in]handleSpecifies the sensor the data came from.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_CALL_NOT_ALLOWED - if sensor cannot execute the call, for example, due to decoding data.
DW_NOT_SUPPORTED - if sensor does not implement this functionality.
DW_INVALID_ARGUMENT - if given data pointer is invalid.
DW_SUCCESS

Definition at line 227 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_start

typedef dwStatus(* dwSensorPlugin_start) (dwSensorPluginSensorHandle_t handle)

Starts the sensor previously successfully created with 'dwSensorPlugin_createSensor' interface.

Sensor data should ready to be received using the '_dwSensorPlugin_readRawData()' API after the execution of this call.

Parameters
[in]handleA sensor handle previously created w/ the 'dwSensorPlugin_createHandle' interface.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_SAL_SENSOR_ERROR - if a non recoverable error happens during sensor start.
DW_SUCCESS

Definition at line 140 of file SensorCommonPlugin.h.

◆ dwSensorPlugin_stop

typedef dwStatus(* dwSensorPlugin_stop) (dwSensorPluginSensorHandle_t handle)

Stops the sensor.

This method shall block while the sensor is stopped.

Parameters
[in]handleA sensor handle previously created w/ the 'dwSensorPlugin_createHandle' interface.
Returns
DW_INVALID_HANDLE - if the sensor handle is NULL or invalid
DW_SAL_SENSOR_ERROR - if a non recoverable error happens during sensor stop.
DW_SUCCESS

Definition at line 151 of file SensorCommonPlugin.h.

◆ dwSensorPluginSensorHandle_t

Definition at line 75 of file SensorCommonPlugin.h.