archive/driveworks-3.0/dwx__vehicleioPlugins_8md_source.html

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

@page dwx_vehicleio_plugins VehicleIO Plugins
@tableofcontents

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

@section vehicleIO_plugin_overview VehicleIO Plugins Overview

The VehicleIO Plugin back-end enables writing fully customized drive-by-wire
abstraction that will be represented as a @ref vehicleio_mainsection interface
for the rest of the software stack.

@section vehicleIO_plugin_implementation Implementing Custom VehicleIO Plugin

A VehicleIO plugin in DriveWorks requires implementing a set of pre-defined
functions. The declarations of these functions are located in
`dw/control/vehicleio/plugins/VehicleIODriver.h`.

In this tutorial, we are going to implement a simple drive-by-wire system that
is responsible for steering wheel angle. See \ref dwx_vehicleio_plugin_sample
for the corresponding sample code.

## Initialization

In essence, our plugin is a dynamically loaded shared library, and the core
@ref vehicleio_mainsection module will first call `_dwVehicleIODriver_initialize()`
function of this library, which should prepare all objects and state that is needed
for the plugin to function:

```{.cpp}
dwStatus _dwVehicleIODriver_initialize()
{
    dwStatus status;
    dwStatus result = DW_SUCCESS;

    dwContextParameters sdkParams = {};
    dwInitialize(&gSdk, DW_VERSION, &sdkParams);

    status = dwCANInterpreter_buildFromDBC(&gIntp, ("AutonomousVehicleCANSignals.dbc"), gSdk);
    checkError(result, status, "cannot create DBC-based CAN message interpreter");

    return result;
}
```

Above, `dwCANInterpreter_buildFromDBC()` function initializes an interpreter
object that will be useful to work with our DBC file. See \ref
dwx_canbus_message_sample for more information about CAN interpreter usage.

When using the plugin with, for example, \ref dwx_vehicleio_sample, in order
for VehicleIO core to load the plugin, Rig file should specify "custom"
VehicleIO node:

```
{
    "rig": {
        "vehicleio": [
            {
                "type": "custom",
                "parent-sensor": "can:vehicle:custom",
                "custom-lib": "../../../bin/libsample_vehicleio_plugin.so"
            }
        ],
        "sensors": [
            {
                "name": "can:vehicle:custom",
                "parameter": "file=can-vio-generic.bin",
                "protocol": "can.virtual",
                "properties": null,
                "nominalSensor2Rig": { "quaternion": [ 0.0, 0.0, 0.0, 1.0 ], "t": [ 0.0, 0.0, 0.0 ] },
                "sensor2Rig": { "quaternion": [ 0.0, 0.0, 0.0, 1.0 ], "t": [ 0.0, 0.0, 0.0 ] }
            }
        ]
    }
}
```

Full example of Rig file is available in
`data/samples/vehicleio/rig-plugin.json`, and exact commands how to run the
VehicleIO sample with the plugin is available at \ref dwx_vehicleio_plugin_sample.

## Releasing

When plugin is no longer needed, VehicleIO core will call
`_dwVehicleIODriver_release()` method, which is an opportunity for the module
to cleanup any created objects and state:

```{.cpp}
dwStatus _dwVehicleIODriver_release()
{
    dwCANInterpreter_release(gIntp);
    dwRelease(gSdk);
    return DW_SUCCESS;
}
```

## CAN messages consumption

CAN messages represent the input to the module, which plugin must parse and
update its state, if needed. VehicleIO core will call plugin's
`_dwVehicleIODriver_consume()` function when there is a new message to consume:

```{.cpp}
dwStatus _dwVehicleIODriver_consume(const dwCANMessage* msg, dwVehicleIOState* state)
{
    dwStatus status;
    dwStatus result = DW_SUCCESS;

    status = dwCANInterpreter_consume(msg, gIntp);
    checkError(result ,status, "consume message failed");
    parseSteeringReport(state);

    return result;
}
```

In the example above, we simply parse current steering angle report using our
CAN/DBC interpreter:

```{.cpp}
static void parseSteeringReport(dwVehicleIOState* state)
{
    dwStatus status;
    uint32_t num;
    status = dwCANInterpreter_getNumberSignals(&num, gIntp);

    if (status == DW_SUCCESS && num > 0)
    {
        float32_t value    = 0;
        dwTime_t timestamp = 0;
        const char* name;

        for (uint32_t i = 0; i < num; ++i)
        {
            if (dwCANInterpreter_getSignalName(&name, i, gIntp) == DW_SUCCESS)
            {
                if (dwCANInterpreter_getf32(&value, &timestamp, i, gIntp) == DW_SUCCESS)
                {
                    if (0 == strcmp(name, GENERIC_ID_STEERING_WHEEL_ANGLE_REPORT))
                        state->steeringWheelAngle = value;
                    else if (0 == strcmp(name, GENERIC_ID_STEERING_WHEEL_TORQUE_REPORT))
                        state->steeringWheelTorque = value;
                    else if (0 == strcmp(name, GENERIC_ID_STEERING_WHEEL_SPEED_REPORT))
                        state->speed = value;
                }
            }
        }
    }
}
```

## CAN messages generation

CAN messages are also the output of the module, thus when VehicleIO is
requested to send a command, the core module will relay the request to the
plugin, issuing two calls: `_dwVehicleIODriver_sendCommand()` and
`_dwVehicleIODriver_sendMiscCommand()`. Each of the function should encode
command arguments into CAN messages and send via a provided sensor handle:

```{.cpp}
dwStatus _dwVehicleIODriver_sendCommand(const dwVehicleIOCommand* cmd,
                       dwSensorHandle_t sensor)
{
    dwCANMessage msgCAN{};
    dwStatus status;
    dwStatus result = DW_SUCCESS;

    status = dwCANInterpreter_createMessageFromName(&msgCAN, GENERIC_MSG_STEERING_CMD, gIntp);
    checkError(result, status, "create steering message failed");

    status = encodeSteering(msgCAN, cmd);
    checkError(result, status, "encode steering failed");

    status = dwSensorCAN_sendMessage(&msgCAN, 1000000, sensor);
    checkError(result, status, "send steering failed");

    return result;
}

dwStatus _dwVehicleIODriver_sendMiscCommand(const dwVehicleIOMiscCommand*,
                       dwSensorHandle_t)
{
    return DW_NOT_IMPLEMENTED;
}
```

If certain type of commands are not relevant, the plugin is permitted to return
`DW_NOT_IMPLEMENTED` status, as was shown in
`_dwVehicleIODriver_sendMiscCommand()` above.

And as in previous section, we use CAN interpreter to encode commands into CAN
messages:

```{.cpp}
static dwStatus encodeSteering(dwCANMessage& msgCAN, const dwVehicleIOCommand* cmd)
{
    dwStatus status;
    dwStatus result = DW_SUCCESS;

    status = dwCANInterpreter_encodef32(cmd->steeringWheelAngle,
                                        GENERIC_ID_STEERING_WHEEL_ANGLE_COMMAND,
                                        &msgCAN, gIntp);
    checkError(result, status, "encode steering angle failed");

    status = dwCANInterpreter_encodei32(cmd->steeringValid,
                                        GENERIC_ID_STEERING_WHEEL_ANGLE_COMMAND_VALID,
                                        &msgCAN, gIntp);
    checkError(result, status, "encode steering valid failed");

    status = dwCANInterpreter_encodef32(cmd->steeringSpeed,
                                        GENERIC_ID_STEERING_WHEEL_STEER_SPEED,
                                        &msgCAN, gIntp);
    checkError(result, status, "encode steering speed failed");

    status = dwCANInterpreter_encodei32(cmd->clearFaults ? true : false,
                                        GENERIC_ID_STEERING_WHEEL_STEER_CLEAR_FAULT,
                                        &msgCAN, gIntp);
    checkError(result, status, "encode steering clear fault failed");
    return result;
}
```

## Building plugin as a dynamic library

The plugin code must be compiled into a dynamic library.

Firstly, we should create a folder under `samples` called `vehicleio_plugin` and create a `CMakeLists.txt` under this folder:

```
project(sample_vehicleio_plugin C CXX)

set(SOURCES
    driverConf.hpp
    driver.cpp
)

set(LIBRARIES
    samples_framework
    ${Driveworks_LIBRARIES}
)

add_library(${PROJECT_NAME} SHARED ${SOURCES})
target_link_libraries(${PROJECT_NAME} PRIVATE ${LIBRARIES})
set_property(TARGET ${PROJECT_NAME} PROPERTY FOLDER "Samples")

get_property(TARGET_PACKAGE GLOBAL PROPERTY TARGET_PACKAGE)
install(TARGETS ${PROJECT_NAME}
    COMPONENT dw-samples-${TARGET_PACKAGE} # targeted package (dw / dav / ..)
    DESTINATION ${SDK_SAMPLE_DESTINATION}
)

sdk_add_sample(${PROJECT_NAME})
```

Run `cmake` and the preferred build system to compile the library. This will generate a `libsample_vehicleio_plugin.so`.

See \ref dwx_vehicleio_plugin_sample for more details.