Defines methods common to all sensors.
Data Structures | |
struct | dwSensorParams |
Holds sets of parameters for sensor creation. More... | |
struct | dwSensorSeekTable |
struct | dwSensorSeekTableEntry |
A seek structure is made of memory offset, eventcount and timestamp. More... | |
struct | dwSensorStats |
Holds the available statistics for a sensor. More... | |
Macros | |
#define | DW_SENSOR_MAX_PARAMETER_STRING_LENGTH 512 |
Maximal length of the parameter string of a sensor. More... | |
#define | DW_SENSOR_MAX_PROTOCOL_NAME_LENGTH 32 |
Maximal length of the protocol name of a sensor. More... | |
Typedefs | |
typedef struct dwSALObject * | dwSALHandle_t |
Handle representing the Sensor Abstraction Layer interface. More... | |
typedef struct dwSensorObject * | dwSensorHandle_t |
Handle representing a sensor. More... | |
Enumerations | |
enum | dwPlatformOS { DW_PLATFORM_OS_LINUX = 0, DW_PLATFORM_OS_V5L = 1, DW_PLATFORM_OS_V5Q = 2, DW_PLATFORM_NUM = 3 } |
Defines the operating system in use. More... | |
enum | dwSensorType { DW_SENSOR_CAMERA = 0, DW_SENSOR_LIDAR, DW_SENSOR_GPS, DW_SENSOR_IMU, DW_SENSOR_CAN, DW_SENSOR_RADAR, DW_SENSOR_TIME, DW_SENSOR_DATA, DW_SENSOR_ULTRASONIC, DW_SENSOR_COUNT } |
Defines the type of sensors that are available in DriveWorks. More... | |
Functions | |
DW_API_PUBLIC dwStatus | dwSAL_createSensor (dwSensorHandle_t *const sensor, dwSensorParams const params, dwSALHandle_t const sal) |
Creates a new sensor managed by the SAL module with the given parameters. More... | |
DW_API_PUBLIC dwStatus | dwSAL_getNumSensors (uint32_t *const num, dwPlatformOS const os, dwSALHandle_t const sal) |
Gets number of available sensors for a platform. More... | |
DW_API_PUBLIC dwStatus | dwSAL_getPlatform (dwPlatformOS *const os, dwSALHandle_t sal) |
Gets current platform the SDK is running on. More... | |
DW_API_PUBLIC dwStatus | dwSAL_getPlatformInfo (char8_t const **const osName, dwPlatformOS const os, dwSALHandle_t const sal) |
Gets detailed information about the running hardware platform and operating system. More... | |
DW_API_PUBLIC dwStatus | dwSAL_getSensorParameterString (const char **const parameters, uint32_t const idx, dwPlatformOS const os, dwSALHandle_t const sal) |
Gets the parameter string acceptable by a sensor. More... | |
DW_API_PUBLIC dwStatus | dwSAL_getSensorProtocol (const char **const name, uint32_t const idx, dwPlatformOS const os, dwSALHandle_t const sal) |
Gets protocol name of a sensor for a given index, e.g., 'camera.gmsl' or 'can.file'. More... | |
DW_API_PUBLIC dwStatus | dwSAL_initialize (dwSALHandle_t *const sal, dwContextHandle_t const context) |
Creates and initializes a SAL (sensor abstraction layer) module. More... | |
DW_API_PUBLIC dwStatus | dwSAL_release (dwSALHandle_t const sal) |
Releases the SAL (sensor abstraction layer) module. More... | |
DW_API_PUBLIC dwStatus | dwSAL_releaseSensor (dwSensorHandle_t const sensor) |
Releases a sensor managed by the SAL module. More... | |
DW_API_PUBLIC dwStatus | dwSAL_reset (dwSALHandle_t const sal) |
Resets the SAL (sensor abstraction layer) module. More... | |
DW_API_PUBLIC dwStatus | dwSensor_createSeekTable (dwSensorHandle_t const sensor) |
Forces recreation of the seek table, for sensors that support seeking. More... | |
DW_API_PUBLIC dwStatus | dwSensor_getCurrentSeekPosition (size_t *const event, dwSensorHandle_t const sensor) |
Gets the current seek position of the sensor. More... | |
DW_API_PUBLIC dwStatus | dwSensor_getNumSeekTableEntries (size_t *const size, dwSensorHandle_t const hsensor) |
Get the number of entries in the seek Table. More... | |
DW_API_PUBLIC dwStatus | dwSensor_getSeekRange (size_t *const eventCount, dwTime_t *const startTimestampUs, dwTime_t *const endTimestampUs, dwSensorHandle_t const sensor) |
Retrieves the valid range of seek parameters, for sensors that support seeking. More... | |
DW_API_PUBLIC dwStatus | dwSensor_getSeekTableEntries (dwSensorSeekTableEntry *const entries, size_t const numEntries, dwSensorHandle_t const sensor) |
Fill in the pre-allocated dwSensorSeekTableEntry array. More... | |
DW_API_PUBLIC dwStatus | dwSensor_getStats (dwSensorStats *const stats, dwSensorHandle_t const sensor) |
Gets sensor statistics (if available). More... | |
DW_API_PUBLIC dwStatus | dwSensor_readRawData (const uint8_t **const data, size_t *const size, dwTime_t const timeoutUs, dwSensorHandle_t const sensor) |
Reads RAW data from sensor as byte array. More... | |
DW_API_PUBLIC dwStatus | dwSensor_reset (dwSensorHandle_t const sensor) |
Resets the sensor. More... | |
DW_API_PUBLIC dwStatus | dwSensor_returnRawData (const uint8_t *const data, dwSensorHandle_t const sensor) |
Returns RAW data to sensor as a byte array. More... | |
DW_API_PUBLIC dwStatus | dwSensor_saveSeekTable (const char *const fileName, dwSensorHandle_t const sensor) |
Saves the seek table for the sensor to a file, for sensors that support seek tables. More... | |
DW_API_PUBLIC dwStatus | dwSensor_seekToEvent (size_t const event, dwSensorHandle_t const sensor) |
Seeks the sensor to an event, for sensors that support seeking. More... | |
DW_API_PUBLIC dwStatus | dwSensor_seekToTime (dwTime_t const timestampUs, dwSensorHandle_t const sensor) |
Seeks the sensor to a specific timestamp, for sensors that support seeking. More... | |
DW_API_PUBLIC dwStatus | dwSensor_setThreadAffinity (uint32_t const affinityMask, dwSensorHandle_t const sensor) |
Sets the affinity of the internal thread, for sensors that use an internal thread to communicate to the OS drivers. More... | |
DW_API_PUBLIC dwStatus | dwSensor_setThreadPriority (int32_t const priority, dwSensorHandle_t const sensor) |
Sets the priority of the internal thread, for sensors that use an internal thread to communicate to the OS drivers. More... | |
DW_API_PUBLIC dwStatus | dwSensor_start (dwSensorHandle_t const sensor) |
Starts the sensor previously successfully created with 'dwSAL_createSensor()'. More... | |
DW_API_PUBLIC dwStatus | dwSensor_stop (dwSensorHandle_t const sensor) |
Stops the sensor. More... | |
struct dwSensorParams |
Data Fields | ||
---|---|---|
const void * | auxiliarydata |
Additional data to pass to sensor creation function. This data can be also used for data which cannot be passed as a string, but is required during sensor creation. Only specific subset of sensors might expect any data here, hence in general this should be NULL. |
const char8_t * | parameters |
Array to additional parameters provided to sensor creation. In general, this array has a form of key/value pairs separated by commas, i.e., key1=value1,key2=value2,key3=value3. Only first DW_SENSOR_MAX_PARAMETER_STRING_LENGTH characters are used. |
const char8_t * | protocol |
Name of the protocol. Only first DW_SENSOR_MAX_PROTOCOL_NAME_LENGTH characters are used. |
struct dwSensorSeekTable |
struct dwSensorSeekTableEntry |
Data Fields | ||
---|---|---|
uint64_t | event | counter of this event |
uint64_t | offset | offset into a file of this event |
uint64_t | size | size of the event present in the virtual data file, in bytes |
dwTime_t | timestamp | timestamp of this entry |
struct dwSensorStats |
Data Fields | ||
---|---|---|
uint64_t | drops | Number of events dropped. |
uint64_t | errors | Number of encountered errors. |
uint64_t | events | Number of normal events (excluding errors and drops). |
dwTime_t | timeDeltaCur | Current time difference between two consecutive packets. |
dwTime_t | timeDeltaMax | Maximum observed time difference between two consecutive packets. |
float64_t | timeDeltaMean | Mean of all the deltas between consecutive timestamps. |
dwTime_t | timeDeltaMin | Minimum observed time difference between two consecutive packets. |
float64_t | timeDeltaStandardDeviation | Variance of all the deltas between consecutive timestamps. |
#define DW_SENSOR_MAX_PARAMETER_STRING_LENGTH 512 |
#define DW_SENSOR_MAX_PROTOCOL_NAME_LENGTH 32 |
typedef struct dwSALObject* dwSALHandle_t |
typedef struct dwSensorObject* dwSensorHandle_t |
enum dwPlatformOS |
enum dwSensorType |
DW_API_PUBLIC dwStatus dwSAL_createSensor | ( | dwSensorHandle_t *const | sensor, |
dwSensorParams const | params, | ||
dwSALHandle_t const | sal | ||
) |
Creates a new sensor managed by the SAL module with the given parameters.
The created sensor has to be released using the 'dwSAL_releaseSensor()' method.
[out] | sensor | A pointer to sensor handle that became valid after creation. |
[in] | params | Specifies the parameters for sensor creation. |
[in] | sal | Specifies the handle to the SAL module that will manage the sensor. |
DW_API_PUBLIC dwStatus dwSAL_getNumSensors | ( | uint32_t *const | num, |
dwPlatformOS const | os, | ||
dwSALHandle_t const | sal | ||
) |
Gets number of available sensors for a platform.
[out] | num | A pointer to return number of sensor in the SAL. |
[in] | os | Specifies the identifier of the platform you are querying for. |
[in] | sal | Specifies the SAL handle created with 'dwSAL_initialize()'. |
DW_API_PUBLIC dwStatus dwSAL_getPlatform | ( | dwPlatformOS *const | os, |
dwSALHandle_t | sal | ||
) |
Gets current platform the SDK is running on.
[out] | os | A pointer to the identifier of the platform the SDK is running on. |
[in] | sal | Specifies the SAL handle created with 'dwSAL_initialize()'. |
DW_API_PUBLIC dwStatus dwSAL_getPlatformInfo | ( | char8_t const **const | osName, |
dwPlatformOS const | os, | ||
dwSALHandle_t const | sal | ||
) |
Gets detailed information about the running hardware platform and operating system.
[out] | osName | A pointer to the pointer of the return location; short string of the name of the current platform. |
[in] | os | Specifies the identifier of the platform you are querying for. |
[in] | sal | Specifies the SAL handle created with 'dwSAL_initialize()'. |
DW_API_PUBLIC dwStatus dwSAL_getSensorParameterString | ( | const char **const | parameters, |
uint32_t const | idx, | ||
dwPlatformOS const | os, | ||
dwSALHandle_t const | sal | ||
) |
Gets the parameter string acceptable by a sensor.
A sensor generates a human readable string with parameters it accepts. It might contain optional parameters indicated with []. Parameters indicated with {a,b,c} means either or. All parameters are represented as key=value pairs, separated by a comma.
[out] | parameters | A pointer to the pointer to the null terminated string will be returned here. |
[in] | idx | Specifies the index of a sensor; index must be between 0 and 'dwSAL_getNumSensors()-1'. |
[in] | os | Specifies the identifier of the platform you query. |
[in] | sal | Specifies the SAL handle created with 'dwSAL_initialize()'. |
DW_API_PUBLIC dwStatus dwSAL_getSensorProtocol | ( | const char **const | name, |
uint32_t const | idx, | ||
dwPlatformOS const | os, | ||
dwSALHandle_t const | sal | ||
) |
Gets protocol name of a sensor for a given index, e.g., 'camera.gmsl' or 'can.file'.
[out] | name | A pointer to the pointer of the null terminated string will be returned here. |
[in] | idx | Specifies the index of a sensor; index must be between 0 and 'dwSAL_getNumSensors()-1'. |
[in] | os | Specifies the identifier of the platform you query. |
[in] | sal | Specifies the SAL handle created with 'dwSAL_initialize()'. |
DW_API_PUBLIC dwStatus dwSAL_initialize | ( | dwSALHandle_t *const | sal, |
dwContextHandle_t const | context | ||
) |
Creates and initializes a SAL (sensor abstraction layer) module.
This method loads all available sensor drivers.
[out] | sal | A pointer to the SAL handle will be returned here. |
[in] | context | Specifies the handle to the context under which the SAL module is created. |
DW_API_PUBLIC dwStatus dwSAL_release | ( | dwSALHandle_t const | sal | ) |
Releases the SAL (sensor abstraction layer) module.
This method releases all created sensors and unloads all drivers.
[in] | sal | The SAL handle to be released. |
DW_API_PUBLIC dwStatus dwSAL_releaseSensor | ( | dwSensorHandle_t const | sensor | ) |
Releases a sensor managed by the SAL module.
In cases where a specific sensor needs to be released, this method can be used. In all other cases, the automatic sensor release of the 'dwSAL_release()' method is sufficient.
[in] | sensor | The handle to a sensor created previously with 'dwSAL_createSensor()'. |
DW_API_PUBLIC dwStatus dwSAL_reset | ( | dwSALHandle_t const | sal | ) |
Resets the SAL (sensor abstraction layer) module.
This method resets all sensors managed by this module.
[in] | sal | Specifies the SAL handle to reset. |
DW_API_PUBLIC dwStatus dwSensor_createSeekTable | ( | dwSensorHandle_t const | sensor | ) |
Forces recreation of the seek table, for sensors that support seeking.
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_getCurrentSeekPosition | ( | size_t *const | event, |
dwSensorHandle_t const | sensor | ||
) |
Gets the current seek position of the sensor.
The event index corresponding to the next sensor event which will be read with sensor's read methods.
[out] | event | Event number which in the range [0;eventCount) of the next event. |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_getNumSeekTableEntries | ( | size_t *const | size, |
dwSensorHandle_t const | hsensor | ||
) |
Get the number of entries in the seek Table.
[out] | size | A pointer to the size of the seek table |
[in] | hsensor | Handle to the sensor to get size of seek table entry |
DW_API_PUBLIC dwStatus dwSensor_getSeekRange | ( | size_t *const | eventCount, |
dwTime_t *const | startTimestampUs, | ||
dwTime_t *const | endTimestampUs, | ||
dwSensorHandle_t const | sensor | ||
) |
Retrieves the valid range of seek parameters, for sensors that support seeking.
[out] | eventCount | Number of events available to be sought to. Each event represents one data unit returned by the sensor from its read() method, e.g. one camera frame for camera, one CAN message, for a CAN sensor, etc. |
[out] | startTimestampUs | Timestamp of the very first event in usec |
[out] | endTimestampUs | Timestamp of the very last event in usec |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_getSeekTableEntries | ( | dwSensorSeekTableEntry *const | entries, |
size_t const | numEntries, | ||
dwSensorHandle_t const | sensor | ||
) |
Fill in the pre-allocated dwSensorSeekTableEntry array.
[out] | entries | Filled in array with seekTable entries |
[in] | numEntries | The number of entries allocated in the entries array |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_getStats | ( | dwSensorStats *const | stats, |
dwSensorHandle_t const | sensor | ||
) |
Gets sensor statistics (if available).
[out] | stats | A pointer to a structure containing the statistics. |
[in] | sensor | Handle to the sensor |
DW_API_PUBLIC dwStatus dwSensor_readRawData | ( | const uint8_t **const | data, |
size_t *const | size, | ||
dwTime_t const | timeoutUs, | ||
dwSensorHandle_t const | sensor | ||
) |
Reads RAW data from sensor as byte array.
This call must be followed by 'dwSensor_returnRawData'. A sensor might provide access to raw data (i.e., unprocessed as received from hardware) data for an extended usage. Such data can for example be passed to serializer.
[out] | data | A pointer to the pointer to data that is populated with the RAW data. |
[out] | size | A pointer to the size of the data array. |
[in] | timeoutUs | Specifies the timeout in US to wait before unblocking. |
[in] | sensor | Specifies the sensor to read from. |
DW_API_PUBLIC dwStatus dwSensor_reset | ( | dwSensorHandle_t const | sensor | ) |
Resets the sensor.
The method blocks while the sensor is reset.
[in] | sensor | Specifies the sensor handle of a sensor previously created with 'dwSAL_createSensor()'. |
DW_API_PUBLIC dwStatus dwSensor_returnRawData | ( | const uint8_t *const | data, |
dwSensorHandle_t const | sensor | ||
) |
Returns RAW data to sensor as a byte array.
This call must be preceded by 'dwSensor_readRawData'.
[in] | data | A pointer to data that was populated with the RAW data. |
[in] | sensor | Specifies the sensor the data came from. |
DW_API_PUBLIC dwStatus dwSensor_saveSeekTable | ( | const char *const | fileName, |
dwSensorHandle_t const | sensor | ||
) |
Saves the seek table for the sensor to a file, for sensors that support seek tables.
A seek table is available if a virtual sensor has been requested to create/load one during creation. Refer to each individual sensor to see what parameters need to be passed to instantiate or load seek table.
It is guaranteed that any seek table written out by this method can be parsed by the corresponding virtual sensor.
[in] | fileName | Name of the file under a reachable path to write seek table to. |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_seekToEvent | ( | size_t const | event, |
dwSensorHandle_t const | sensor | ||
) |
Seeks the sensor to an event, for sensors that support seeking.
Next readFrame(), readMessage(), etc. method would start to read from this event.
[in] | event | Number of the event to seek to. Must be in the range [0; eventCount) |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_seekToTime | ( | dwTime_t const | timestampUs, |
dwSensorHandle_t const | sensor | ||
) |
Seeks the sensor to a specific timestamp, for sensors that support seeking.
Next readFrame(), readMessage(), etc. method would start to read from an event which timestamp is greater or equal to the seek timestamp.
[in] | timestampUs | Timestamp in usec to seek sensor to. Must be in the range [startTimestamp_us; endTimestamp_us] |
[in] | sensor | Handle to the sensor which seek table to write out |
DW_API_PUBLIC dwStatus dwSensor_setThreadAffinity | ( | uint32_t const | affinityMask, |
dwSensorHandle_t const | sensor | ||
) |
Sets the affinity of the internal thread, for sensors that use an internal thread to communicate to the OS drivers.
[in] | affinityMask | Bit mask setting 1 to CPU which shall execute sensor thread |
[in] | sensor | Handle to the sensor to set thread priority |
DW_API_PUBLIC dwStatus dwSensor_setThreadPriority | ( | int32_t const | priority, |
dwSensorHandle_t const | sensor | ||
) |
Sets the priority of the internal thread, for sensors that use an internal thread to communicate to the OS drivers.
This method sets the priority of the internal thread, if the sensor implementation supports it.
[in] | priority | Priority of the thread to set. In general the priority is in range [1;99] |
[in] | sensor | Handle to the sensor to set thread priority |
DW_API_PUBLIC dwStatus dwSensor_start | ( | dwSensorHandle_t const | sensor | ) |
Starts the sensor previously successfully created with 'dwSAL_createSensor()'.
After a sensor is successfully started, new sensor data can be acquired using corresponding sensor methods.
[in] | sensor | Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor()'. |
DW_API_PUBLIC dwStatus dwSensor_stop | ( | dwSensorHandle_t const | sensor | ) |
Stops the sensor.
The method blocks while the sensor is stopped.
[in] | sensor | Specifies the sensor handle of a sensor previously created with 'dwSAL_createSensor()'. |