src/dw/sensors/plugins/gps/docs/gps_fullsensor.md

Go to the documentation of this file.

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

@page sensorplugins_gpssensor Custom GPSs (Comprehensive)
@tableofcontents

@section sensorplugins_gpssensor_comm Introduction

The Comprehensive Plugin Framework for GPS sensors allows third parties to interface with
custom sensor using a shared object (.so) containing their sensor driver implementation.

The GPS may use any available interface to communicate with NVIDIA DRIVE™ AGX as the plugin
fully implements the communication channel.

@section sensorplugins_gpssensor_impl Plugin Implementation

The plugin framework defines a set of function pointer definitions which must be
implemented and exported to the SAL. For GPS sensors, the plugin must have implementation
for the function pointers defined in:

* @ref sensor_plugins_ext_common_group.
* @ref sensor_plugins_ext_gps_group.

In addition, the plugin must implement & export the function, `dwSensorGPSPlugin_getFunctionTable()`,
which is the only C function that needs to be exposed from the shared object.
This allows the developer flexibility to implement internals of their plugin in C++, if necessary.

@section sensorplugins_gpssensor_interface Plugin Interfaces

This section does not substitute the API specification, but attempts to give a high-level overview
of how implemented plugin functions will be exercised by SAL.

@subsection sensorplugins_gpssensor_interface_init Initialization

For the purpose of creation, DriveWorks sensors are specified by `dwSensorParams`,
which contains a protocol and parameter string for the sensor to be created.

For custom GPSs, the protocol and parameter string will be as follows:

    protocol: gps.custom (for live) OR gps.virtual (playback)
    params: decoder-path=<path_to_so>[,<custom params>]

At initialization, a user's call to `dwSensor_create()` will lead to SAL
dynamically loading the plugin library via `dlopen()`.
SAL will then make the following call to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| 1 | `dwSensorPlugin_createHandle()` | Initialize a context for this sensor (allocate resources, etc.) |

After the call to `dwSensorPlugin_createHandle` the plugin should be ready
to decode data (see @ref sensorplugins_gpssensor_interface_decoding).

@subsection sensorplugins_gpssensor_interface_constants Sensor Creation

The plugin framework provides a specific entrypoint to initialize the control-plane /
transport layer with the sensor. For this, SAL will make the following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| 1 | `dwSensorPlugin_createSensor()` | Initialization of communication & transport plane with the sensor |

It is up to the developer to decide what actions need to be taken during this call.
The sensor plugin is not expected to serve data until the sensor is started.

@note This section only applies for live sensors, and is skipped for virtual sensors

@subsection sensorplugins_gpssensor_interface_lifecycle Sensor Lifecycle

After sensor creation and initialization, DriveWorks provides a set of
@ref sensors_usecase1 user APIs.

These have a 1:1 mapping to plugin entrypoints, and their purpose is
self-explanatory:

| DriveWorks User API | Plugin API |
| ------------------- | ---------- |
| `dwSensor_start()` | `dwSensorPlugin_start()` |
| `dwSensor_stop()` | `dwSensorPlugin_stop()` |
| `dwSAL_releaseSensor()` | `dwSensorPlugin_reset()` |

Before querying the plugin for raw data, SAL will make a call
to start the sensor.

@subsection sensorplugins_gpssensor_interface_rawdata Raw Data Gathering

From its communication plane, the sensor plugin is responsible for gathering
raw data from the device. Once the sensor has been started via a
`dwSensorPlugin_start()` call, SAL will make the following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| 1 | `dwSensorPlugin_readRawData()` | Provide raw data for a single sensor message as a byte array |
| 2 | `dwSensorPlugin_returnRawData()` | Returns raw data previously acquired |

We recommend the following format for the data that is returned:

    ------------------------- Header -----------------------
    [Payload Size (uint32_t)][Timestamp (dwTime_t)][Payload]

@note There may be multiple calls to `dwSensorPlugin_readRawData()` before a call to
`dwSensorPlugin_returnRawData()`. The plugin is responsible for memory management of this
raw buffer; an example of a refcounted buffer pool is provided as sample code.

@note This section only applies for live sensors, and is skipped for virtual sensors

@subsection sensorplugins_gpssensor_interface_decoding Decoding

Decoding of data is intentionally split from data gathering on the sensor's communication
plane. This is done to uniformly support virtual (file-based) playback of recorded data.

In order to decode raw data into DriveWorks-specific data structures, SAL will
make the following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| ? | `dwSensorPlugin_pushData()` | Receives raw data from SAL |
| ? | `dwSensorGPSPlugin_parseDataBuffer()` | Decodes available data in the plugin buffer and returns decoded data |

The plugin should not make any assumption on the ordering of these calls, and should return
an available decoded packet when available.

@section sensorplugins_gpssensor_example Example

See @ref dwx_gps_plugin_sample.