sensors/plugins/canbus/docs/canbus_fullsensor.md

Go to the documentation of this file.

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

@page sensorplugins_canbussensor Custom CANs (Comprehensive)
@tableofcontents

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

@section sensorplugins_canbussensor_comm Introduction

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

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

@section sensorplugins_canbussensor_impl Plugin Implementation

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

* @ref sensor_plugins_ext_common_group.
* @ref sensor_plugins_ext_canbus_group.

In addition, the plugin must implement & export the function, `dwSensorCANPlugin_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_canbussensor_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_canbussensor_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 CANs, the protocol and parameter string will be as follows:

    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.

@subsection sensorplugins_canbussensor_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_canbussensor_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_canbussensor_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_canbussensor_interface_filter Filter

Specifes a set of CAN IDs to be filtered.

In order to set filtering on CAN IDs to be processed, SAL will
make the following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| ? | `dwSensorCANPlugin_clearFilter()` | Clear previously set filters |
| ? | `dwSensorCANPlugin_setFilter()` | Set filters |

@subsection sensorplugins_canbussensor_interface_send Send

Sends a message over the CAN bus within a specified timeout.

In order to send message over the CAN bus, SAL will make the 
following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| ? | `dwSensorCANPlugin_send()` | Send message over CAN |

@subsection  sensorplugins_canbussensor_interface_setUseHwTimestamps TimeStamps

Enables or disables hardware timestamp of the CAN messages.

In order to enable or disable hardware timestamp, SAL will make the 
following calls to your plugin:

| # | Function Call | Purpose |
| - | ------------- | ------- |
| ? | `dwSensorCANPlugin_setUseHwTimestamps()` | Enables or disables hardware timestamp |

@section sensorplugins_canbussensor_example Example

See @ref dwx_canbus_plugin_sample.