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.
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:
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.
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.
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.
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.
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.
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]
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.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 |
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 |
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 |
See CAN Plugin Sample.