Detailed Description

Defines the Ultrasonic sensor.

Data Structures
struct	dwUltrasonicEnvelope
	Data structure containing all relevant information about a single envelope measurement Not available as of current release. More...

struct	dwUltrasonicMountingPositions
	Set of mounting parameters for each sensor. More...

struct	dwUltrasonicProperties
	Contextual information of the ultrasonic sensors currently used. More...

Macros
#define	DW_ULTRASONIC_MAX_NUM_SENSORS 12
	The maximum number of sensors of any vendor, to allow compile time declarations. More...

#define	DW_ULTRASONIC_MAX_NUM_SIGNAL_WAYS 32
	The maximum number of signal ways in one cycle of any vendor, to allow compile time declarations. More...

#define	DW_ULTRASONIC_MAX_SAMPLE_SIZE 320
	The maximum envelope sample array size of any vendor, to allow compile time declarations. More...

Enumerations
enum	dwUltrasonicMeasurementMode { DW_ULTRASONIC_MEASURE_MODE_UNKNOWN = 0, DW_ULTRASONIC_MEASURE_MODE_DUAL_AM_LOW = 1, DW_ULTRASONIC_MEASURE_MODE_DUAL_AM_HIGH = 2, DW_ULTRASONIC_MEASURE_MODE_DUAL_CHIRP_LOW = 3, DW_ULTRASONIC_MEASURE_MODE_DUAL_CHIRP_HIGH = 4, DW_ULTRASONIC_MEASURE_MODE_SINGLE_CHIRP_UP = 5, DW_ULTRASONIC_MEASURE_MODE_SINGLE_CHIRP_DOWN = 6 }
	Measurement modes that define the transmission frequencies and firing patterns. More...

enum	dwUltrasonicNearRangeDetectionStatus { DW_ULTRASONIC_NEAR_RANGE_UNAVAILABLE = 0, DW_ULTRASONIC_NEAR_RANGE_NO_DETECTION = 1, DW_ULTRASONIC_NEAR_RANGE_VALID_DETECTION = 2 }
	Status to indicate whether the ultrasonic system could estimate a near range detection or not. More...

Functions
DW_API_PUBLIC dwStatus	dwSensorUltrasonic_disableDecoding (dwSensorHandle_t sensor)
	Disable the decoding of the Ultrasonic envelopes, which frees additional CPU load. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_enableDecoding (dwSensorHandle_t sensor)
	Enables the decoding of the Ultrasonic envelopes, which incurs an additional CPU load. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_getProperties (dwUltrasonicProperties *properties, dwSensorHandle_t sensor)
	Gets information about the Ultrasonic sensor. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_isDecodingEnabled (bool *enable, dwSensorHandle_t sensor)
	Retrieves the state of packet decoding. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_processRawData (uint8_t const *data, size_t size, dwSensorHandle_t sensor)
	Reads the Ultrasonic envelope from raw data. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_readEnvelope (dwUltrasonicEnvelope const **envelope, dwTime_t timeout_us, dwSensorHandle_t sensor)
	Reads a Ultrasonic envelope. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_returnEnvelope (dwUltrasonicEnvelope const *envelope, dwSensorHandle_t sensor)
	Returns the Ultrasonic envelope to the internal pool. More...

DW_API_PUBLIC dwStatus	dwSensorUltrasonic_setTemperature (float32_t const temperature, dwSensorHandle_t sensor)
	Sets the environment temperature to be used in temperature compensation of the incoming data. More...

Data Structure Documentation

◆ dwUltrasonicEnvelope

struct dwUltrasonicEnvelope

Data Fields
float32_t	amplitudeSamples[DW_ULTRASONIC_MAX_SAMPLE_SIZE]	Envelope amplitude data.
uint32_t	cycleCount	Cycle counter of packet received by the host.
float32_t	distanceInterval	Fixed distance interval between amplitude samples [m].
dwTime_t	hostTimestamp	Timestamp when the data was received by the host [us].
uint32_t	maxNumAmplitudeSamples	Maximum number of valid amplitude samples in the data.
dwUltrasonicMeasurementMode	measurementMode	Operating mode of the ultrasonic system during this measurement.
dwUltrasonicNearRangeDetectionStatus	nearRangeDetectionStatus	Indicator of near range detection out put status.
float32_t	nearRangeDistance	Separate estimation of a near range detection's distance [m]. Note Only valid if indicated by detectionStatus
uint32_t	numAmplitudeSamples	Number of valid amplitude samples in the data.
float32_t	reverberationPeriod	Period of the reverberation decay [ns].
float32_t	rxFrequency	Center frequency of the received signal [Hz].
uint32_t	rxSensorId	ID of the sensor that received the echo. Note Sensor IDs are not necessarily a 0-index value - be careful with indexing
dwTime_t	sensorTimestamp	Timestamp when the data was updated on the sensor [us].
float32_t	speed	Vehicle speed reported by ultrasonic sensor [km/h].
int32_t	temperature	Temperature reported by ultrasonic sensor [C].
float32_t	txFrequency	Center frequency of the transmitted signal [Hz].
uint32_t	txSensorId	ID of the sensor that transmitted the signal. Note Sensor IDs are not necessarily a 0-index value - be careful with indexing

◆ dwUltrasonicMountingPositions

struct dwUltrasonicMountingPositions

Data Fields
dwVector3f	angles[DW_ULTRASONIC_MAX_NUM_SENSORS]	Roll, pitch, yaw Euler angles of each individual sensor [radians].
dwVector3f	coordinates[DW_ULTRASONIC_MAX_NUM_SENSORS]	X,Y,Z translation of each individual sensor [m].
float32_t	horizontalFoV	Horizontal FoV relative to sensor for standard target conditions [radians].
float32_t	verticalFoV	Vertical FoV relative to the sensor for standard target conditions [radians].

◆ dwUltrasonicProperties

struct dwUltrasonicProperties

Data Fields
uint32_t	fwVersion[3]	Version information of ultrasonic firmware {major_number, minor_number, patch}.
float32_t	horizontalFoV	Horizontal FoV for standard target conditions [radians].
uint32_t	maxNumSignalWays	Maximum number of signal ways that report data in one measurement cycle.
uint32_t	maxRawSizeInBytes	Maximum size of Ultrasonic data payload.
uint32_t	numSensors	Number of physical sensors installed in the system.
float32_t	sampleTimeInterval	Sensor sample rate [seconds].
uint32_t	versionId[3]	Version information of the logical interface {major_number, minor_number, patch}.
float32_t	verticalFoV	Vertical FoV for standard target conditions [radians].

Macro Definition Documentation

◆ DW_ULTRASONIC_MAX_NUM_SENSORS

#define DW_ULTRASONIC_MAX_NUM_SENSORS 12

The maximum number of sensors of any vendor, to allow compile time declarations.

Definition at line 60 of file Ultrasonic.h.

◆ DW_ULTRASONIC_MAX_NUM_SIGNAL_WAYS

#define DW_ULTRASONIC_MAX_NUM_SIGNAL_WAYS 32

The maximum number of signal ways in one cycle of any vendor, to allow compile time declarations.

Definition at line 63 of file Ultrasonic.h.

◆ DW_ULTRASONIC_MAX_SAMPLE_SIZE

#define DW_ULTRASONIC_MAX_SAMPLE_SIZE 320

The maximum envelope sample array size of any vendor, to allow compile time declarations.

Definition at line 57 of file Ultrasonic.h.

Enumeration Type Documentation

◆ dwUltrasonicMeasurementMode

enum dwUltrasonicMeasurementMode

Measurement modes that define the transmission frequencies and firing patterns.

Enumerator
DW_ULTRASONIC_MEASURE_MODE_UNKNOWN
DW_ULTRASONIC_MEASURE_MODE_DUAL_AM_LOW
DW_ULTRASONIC_MEASURE_MODE_DUAL_AM_HIGH
DW_ULTRASONIC_MEASURE_MODE_DUAL_CHIRP_LOW
DW_ULTRASONIC_MEASURE_MODE_DUAL_CHIRP_HIGH
DW_ULTRASONIC_MEASURE_MODE_SINGLE_CHIRP_UP
DW_ULTRASONIC_MEASURE_MODE_SINGLE_CHIRP_DOWN

Definition at line 83 of file Ultrasonic.h.

◆ dwUltrasonicNearRangeDetectionStatus

enum dwUltrasonicNearRangeDetectionStatus

Status to indicate whether the ultrasonic system could estimate a near range detection or not.

Enumerator
DW_ULTRASONIC_NEAR_RANGE_UNAVAILABLE	Near range detection algorithm is not providing results.
DW_ULTRASONIC_NEAR_RANGE_NO_DETECTION	Near range detection algorithm is active but does not sense any obstacles.
DW_ULTRASONIC_NEAR_RANGE_VALID_DETECTION	Near range detection algorithm is active and providing range information.

Definition at line 94 of file Ultrasonic.h.

Function Documentation

◆ dwSensorUltrasonic_disableDecoding()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_disableDecoding ( dwSensorHandle_t sensor )

Disable the decoding of the Ultrasonic envelopes, which frees additional CPU load.

Method fails if the sensor has been started and is capturing data. Stop the sensor first. The default state is to have decoding on. If on, dwSensor_readRawData returns DW_CALL_NOT_ALLOWED.

Parameters

[in] sensor Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns: DW_INVALID_HANDLE, DW_CALL_NOT_ALLOWED, DW_SUCCESS

◆ dwSensorUltrasonic_enableDecoding()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_enableDecoding ( dwSensorHandle_t sensor )

Enables the decoding of the Ultrasonic envelopes, which incurs an additional CPU load.

Method fails if the sensor has been started and is capturing data. Stop the sensor first. The default state is to have decoding on. If on, dwSensor_readRawData returns DW_CALL_NOT_ALLOWED.

Parameters

[in] sensor Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns: DW_INVALID_HANDLE, DW_CALL_NOT_ALLOWED, DW_SUCCESS

◆ dwSensorUltrasonic_getProperties()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_getProperties	(	dwUltrasonicProperties *	properties,
		dwSensorHandle_t	sensor
	)

Gets information about the Ultrasonic sensor.

Parameters

[out]	properties	A pointer to the struct containing the properties of the Ultrasonic.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns: DW_INVALID_HANDLE, DW_INVALID_ARGUMENT, DW_SUCCESS

◆ dwSensorUltrasonic_isDecodingEnabled()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_isDecodingEnabled	(	bool *	enable,
		dwSensorHandle_t	sensor
	)

Retrieves the state of packet decoding.

Parameters

[out]	enable	Contains the result of the query, which is true when decoding. False if RAW data.
[in]	sensor	Specifies the sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns: DW_INVALID_HANDLE, DW_CALL_NOT_ALLOWED, DW_SUCCESS

◆ dwSensorUltrasonic_processRawData()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_processRawData	(	uint8_t const *	data,
		size_t	size,
		dwSensorHandle_t	sensor
	)

Reads the Ultrasonic envelope from raw data.

Any processed messages can be picked up using the dwSensorUltrasonic_popEnvelope() method. This happens on the CPU thread where the function is called, incurring an additional load on that thread.

Parameters

[in]	data	Undecoded Ultrasonic data.
[in]	size	Size in bytes of the raw data.
[in]	sensor	Sensor handle of the sensor previously created with `dwSAL_createSensor()`.

Returns: DW_INVALID_HANDLE - if given sensor handle is invalid,
DW_INVALID_ARGUMENTS - if given arguments are invalid,
DW_NOT_READY - if more data needs to be passed in (loop while it returns DW_NOT_READY).
DW_SUCCESS

◆ dwSensorUltrasonic_readEnvelope()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_readEnvelope	(	dwUltrasonicEnvelope const **	envelope,
		dwTime_t	timeout_us,
		dwSensorHandle_t	sensor
	)

Reads a Ultrasonic envelope.

The pointer returned is to the internal data pool. DW guarantees that the data remains constant until returned by the application. The data must be explicitly returned by the application. The method blocks until either a new valid envelope is received from the sensor or the given timeout is exceeded.

Parameters

[out]	envelope	A pointer to the pointer of an Ultrasonic envelope structure in the internal pool from sensor contains envelope data.
[in]	timeout_us	Timeout, in us, to wait for a new message. Special values: DW_TIMEOUT_INFINITE - to wait infinitely. Zero - means polling of internal queue.
[in]	sensor	Sensor handle of the Ultrasonic sensor previously created with dwSAL_createSensor().

Returns: DW_INVALID_HANDLE - if given sensor handle is invalid
DW_INVALID_ARGUMENTS - if given arguments are invalid
DW_TIME_OUT - if operation has timeout
DW_NOT_AVAILABLE - if sensor has not been started or data is not available in polling mode.
DW_END_OF_STREAM - if end of stream reached (virtual sensor only).
DW_SAL_SENSOR_ERROR - if there was an i/o or bus error.
DW_SUCCESS

◆ dwSensorUltrasonic_returnEnvelope()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_returnEnvelope	(	dwUltrasonicEnvelope const *	envelope,
		dwSensorHandle_t	sensor
	)

Returns the Ultrasonic envelope to the internal pool.

At this point the pointer is still valid, but data will be changed based on newer sensor readings.

Parameters

[in]	envelope	A pointer to the Ultrasonic envelope previously read using 'dwSensorUltrasonic_readEnvelope() be returned to the pool.
[in]	sensor	Specifies the sensor handle of the sensor previously created with dwSAL_createSensor().

Returns: DW_INVALID_HANDLE - if given handle is not valid.
DW_INVALID_ARGUMENT - if given handle is NULL
DW_NOT_AVAILABLE - if sensor has not been started or data is not available in polling mode.
DW_SAL_SENSOR_ERROR - if there was an i/o or bus error.
DW_CALL_NOT_ALLOWED - if the sensor this envelope from has already been released.
DW_SUCCESS

◆ dwSensorUltrasonic_setTemperature()

DW_API_PUBLIC dwStatus dwSensorUltrasonic_setTemperature	(	float32_t const	temperature,
		dwSensorHandle_t	sensor
	)

Sets the environment temperature to be used in temperature compensation of the incoming data.

Note: Temperature should be updated as frequently as a temperature signal is available for maximum sensor distance accuracy

Parameters

[in]	temperature	Ambient external temperature at the current time [C]
[in]	sensor	Sensor handle of the Ultrasonic sensor previously created with dwSAL_createSensor()

Detailed Description

Data Structures

Macros

Enumerations

Functions

Data Structure Documentation

◆ dwUltrasonicEnvelope

◆ dwUltrasonicMountingPositions

◆ dwUltrasonicProperties

Macro Definition Documentation

◆ DW_ULTRASONIC_MAX_NUM_SENSORS

◆ DW_ULTRASONIC_MAX_NUM_SIGNAL_WAYS

◆ DW_ULTRASONIC_MAX_SAMPLE_SIZE

Enumeration Type Documentation

◆ dwUltrasonicMeasurementMode

◆ dwUltrasonicNearRangeDetectionStatus

Function Documentation

◆ dwSensorUltrasonic_disableDecoding()

◆ dwSensorUltrasonic_enableDecoding()

◆ dwSensorUltrasonic_getProperties()

◆ dwSensorUltrasonic_isDecodingEnabled()

◆ dwSensorUltrasonic_processRawData()

◆ dwSensorUltrasonic_readEnvelope()

◆ dwSensorUltrasonic_returnEnvelope()

◆ dwSensorUltrasonic_setTemperature()