DriveWorks SDK Reference
3.5.78 Release
For Test and Development only

Custom GPSs (Comprehensive)
Note
SW Release Applicability: This tutorial is applicable to modules in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

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.

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:

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.

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.

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 Decoding).

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

Sensor Lifecycle

After sensor creation and initialization, DriveWorks provides a set of Sensors Life Cycle 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.

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.
This section only applies for live sensors, and is skipped for virtual sensors

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.

Example

See GPS Plugin Sample.