sensors/docs/usecase1.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page sensors_usecase1 Sensors Life Cycle

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

Before you use any sensor in NVIDIA<sup>&reg;</sup> DriveWorks, you must create an instance of the sensor, then use a start-stop mechanism to collect data and finally release the sensor so all resources are freed.

![](sensors_life_cycle.png)

The following functions support the life cycle shown above:

- dwSAL_createSensor() is the function call that prepares the sensor for data delivery. This includes power up, establish connection, open channels, allocates FIFOs, etc... This function is expected to have a significant cost and should only be used during initialization. Sensor type and parameters are determined by using the above protocol and parameter strings.
- dwSensor_start() is a low latency call that starts the capturing of sensor data.
- dwSensor_stop() is a low latency call that will stop capturing data and will drain any data not consumed in preparation for the next start call.
- dwSAL_releaseSensor() is a function call used to stop the sensor, disconnect it from DriveWorks SAL and release any allocated resources. It is expected to be high latency and should only be called at application termination.

Here is an example of initialization of a virtual camera for video replay and its release:
```{.cpp}
// Initialize DriveWorks
dwInitialize(&sdk, DW_VERSION, &sdkParams);
// create SAL module of the SDK
dwSAL_initialize(&sal, sdk);
// create virtual camera interface
dwSensor cameraSensor = DW_NULL_HANDLE;
{
    dwSensorParams params;
    std::string parameterString = "file=/tmp/test.h264";
    params.protocol             = "camera.virtual";
    dwStatus result = dwSAL_createSensor(&cameraSensor, params, sal);
    if (result != DW_SUCCESS) {
        std::cerr << "Cannot create camera.virtual?"
                  << params.parameters << std::endl;
        exit(1);
    }
}
```

Once the sensor has started, it is possible to consume the data being acquired by using generic or specialized accessors. 

Generic accessors are used mainly for serialization purposes as they provide raw sensor data. The available function calls are `dwSensor_readRawData()` to get access to the data memory pointers and `dwSensor_returnRawData()` to return the pointers back to the sensor abstraction layer. 
A full workflow based on raw data use is demonstrare in @ref dwx_record_sample.

To access processed data one needs to use specialized function calls that will provide the data formatted appropriately depending on the sensor type.
For all details on specific sensors see:

- @ref dwx_sensors_camera_tutorials
- @ref dwx_sensors_canbus_tutorials
- @ref dwx_sensors_gps_tutorials
- @ref dwx_sensors_imu_tutorials
- @ref dwx_sensors_lidar_tutorials
- @ref dwx_sensors_radar_tutorials

After usage the sensor, SAL and SDK handle must be released.

```
// release camera sensor
dwSAL_releaseSensor(&cameraSensor);

// release SAL module of the SDK
dwSAL_release(&sal);

// Release DriveWorks
dwRelease(&sdk);
```