control/vehicleio/docs/usecase1.md

Go to the documentation of this file.

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

@page vehicleio_usecase1 VehicleIO Workflow

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

#### Initialization

The `dwVehicleIO_initialize()` function creates a VehicleIO instance. That functions takes the following parameters:

- VehicleIO handle: `::dwVehicleIOHandle_t`
- Type of interface device: `::dwVehicleIOType` (::DW_VEHICLEIO_DATASPEED / ::DW_VEHICLEIO_GENERIC / ::DW_VEHICLEIO_SPACEDRIVE / ::DW_VEHICLEIO_CUSTOM)
- Handle to the vehicle: `dwVehicle` 

@note Before creating a VehicleIO instance, you must initialize the rig configuration module using `dwRig_initializeFromFile()` and then get the vehicle properties using `dwRig_getVehicle()`. For more information, see Rig Configuration in this guide.

- Context Handle : `::dwContextHandle_t`

#### Driving Mode

The `dwVehicleIO_setDrivingMode()` function sets the driving mode. This function consumes the dwVehicleIODrivingMode() enum as an argument, which is defined as
```{.cpp}
typedef enum dwVehicleIODrivingMode
{
    /// Comfortable driving is expected (most conservative). Commands that leave
    /// the comfort zone are treated as unsafe, which immediately leads to
    /// VehicleIO being disabled.
    DW_VEHICLEIO_DRIVING_LIMITED = 0x000,
    /// Same as above, but unsafe commands are clamped to safe limits and
    /// warnings are isssued. VehicleIO stays enabled.
    DW_VEHICLEIO_DRIVING_LIMITED_ND = 0x100,
    /// Safety checks suitable for collision avoidance logic (right now same as
    /// NO_SAFETY below).
    DW_VEHICLEIO_DRIVING_COLLISION_AVOIDANCE = 0x200,
    /// VehicleIO will bypass all safety checks.
    DW_VEHICLEIO_DRIVING_NO_SAFETY = 0x300
} dwVehicleIODrivingMode; 
```
#### Vehicle State Information

The `dwVehicleIO_consumeCANFrame()` function parses received CAN messages. The resulting parsed messages generate certain reports, which can be gathered using the predefined callbacks.

The current vehicle state information can be retrieved with `dwVehicleIO_getVehicleState()`, which returns the vehicle state in the `dwVehicleIOState` format.

#### Sending Vehicle Commands

The `dwVehicleIO_sendVehicleCommand()` function sends a command to the vehicle via VehicleIO. The command is sent in the `dwVehicleIOCommand` format and is passed as one of the arguments. An additional argument is passed as a handle to the underlying sensor that VehicleIO uses to pass this command.

#### Selecting Driver Overrides

Signals that the driver uses to override Vehicle control are configurable and can be selected using `dwVehicleIO_selectDriverOverrides()`. The driver can override vehicle control with any combination of throttle, steering, brake, and/or gear.

## Conditions for Engagement and Disengagement

In order to enable vehicle actuation (i.e. engage), several conditions must be
satisfied:

- `dwVehicleIOCommand::enable` must be set to `true`.
- Desired `dwVehicleIOCommand::*Valid` flags must be set to `true`, for example
  `dwVehicleIOCommand::brakeValid` to actuate vehicle braking.
- All bits in `dwVehicleIOState::faults` must be clear. Recoverable faults can
  be cleared by sending a command with `dwVehicleIOCommand::clearFaults` set to
  `true`.
- `dwVehicleIOState::overrides` must be clear for all enabled driver overrides.
  To clear `dwVehicleIOState::overrides`, one has to send a command with
  `dwVehicleIOCommand::clearFaults` set to `true` (same field is used to clear
  faults and overrides).

Once engaged, both Drive-By-Wire hardware and/or VehicleIO might decide to
disable vehicle actuation (i.e. disengage), there are a few cases when this
might happen:

- Application-requested disengagement: `dwVehicleIOCommand::enable` is set to
  `false`.
- Disengagement due to Drive-By-Wire faults. Which hardware actuation unit
  caused the disengagement will be indicated via `dwVehicleIOState::faults` (see
  corresponding `::dwVehicleIOFaults` enumeration). Exact reason for
  disengagement can be traced back using CAN logs and Drive-By-Wire vendor
  documentation.
- Disengagement due to driver overrides as detected by Drive-By-Wire hardware.
  Exact reason will be indicated via corresponding bits in
  `dwVehicleIOState::overrides` (see corresponding `::dwVehicleIOOverrides`
  enumeration).
- If VehicleIO is in `::DW_VEHICLEIO_DRIVING_LIMITED` mode, some commands (such
  as braking) that are considered not appropriate for limited actuation will
  cause VehicleIO to stop sending commands to the vehicle (i.e. VehicleIO will
  disengage). In this case, `::DW_VEHICLEIO_FAULT_SAFETY` bit will set in
  `dwVehicleIOState::faults`.
- If VehicleIO stopped receiving Drive-By-Wire reports for more than 100
  milliseconds and VehicleIO is in `::DW_VEHICLEIO_DRIVING_LIMITED` mode, then
  `::DW_VEHICLEIO_FAULT_SAFETY` bit will set in `dwVehicleIOState::faults` and
  VehicleIO will disengage.

#### VehicleIO Sample

See @ref dwx_vehicleio_sample