tools/preFlightChecker/docs/README.md

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property
 * and proprietary rights in and to this software, related documentation
 * and any modifications thereto.  Any use, reproduction, disclosure or
 * distribution of this software and related documentation without an express
 * license agreement from NVIDIA Corporation is strictly prohibited.
 */

@page pfc Pre-Flight Checker Tool (PFC)
@tableofcontents

@section pfc_tool_description Description

The NVIDIA<sup>&reg;</sup> DriveWorks Pre-Flight Checker tool (PFC) ensures proper operation for all connected
sensors, and checks prerequisites before the car can be safely driven
autonomously.<br>
The PFC can only be used in a stationary car.

The PFC checks the following items:
- System sanity checks for the NVIDIA DRIVE<sup>&trade;</sup> AV component.
- Sensor sanity checks for the front camera, Radar, GPS, IMU, and CAN.
- Vehicle sanity checks for the steering, brake, and throttle.

You can run PFC in these modes:
- **Autonomous vehicle mode**: where PFC validates data from live sensors.
- **Bench mode**: where PFC validates data from recorded or live sensors.

During installation, PFC is initialized for the current configuration.

@note The PFC tool bench validation currently only supports data obtained directly from sensors. It does not support recorded data.

@subsection pfc_tool_features Features

The Pre-Flight Checker (PFC) tool performs the following in both
**autonomous vehicle mode** and **bench mode**:

#### Validates the Following Sensors:

- Camera sensors with data-validation based on histogram.
- CAN sensor-based steering, brake, throttle, and gear.
- IMU sensor with timestamp-based data validation (Xsense only).
- GPS sensor with timestamp- and DOP-based data validation (Xsense only).
- Ethernet Radar sensor.

#### Displays the Following Version Information:

- DriveWorks and NVIDIA DRIVE<sup>&trade;</sup> AV.
- AURIX MCU firmware.
- PDK versions.
- Provides the status for the disk storage space, including whether it is critically low.

#### Performs Data Validation:

PFC performs sensor validation by calculating the frequencies for which sensors provide data. It performs data validations specific for the following sensors:

- Camera: Ensures the
  captured data is good and contains valid frames. During camera validation, PFC
  checks the captured data by examining histograms for RAW frames.<br>
  It divides the histogram into low, medium, and high percentiles. It then compares the high and
  low percentiles to ensure they exceed a threshold value, <br>and the mid-percentiles
  lie within a lower and upper boundary.
- IMU: Uses timestamps and IMU frame flag correctness to
  validate IMU data correctness.
- CAN: Uses timely receipt of CAN messages to verify functional
  steering, brake, throttle, and gear.
- GPS: Determines the GPS data correctness based on timestamps, GPS
  frame flag correctness, and dilution of precision. <br>If multiple GPS sensors are
  defined, PFC also performs cross validation.

@section pfc_tool_prereq Prerequisites

This tool is available on NVIDIA DRIVE<sup>&trade;</sup> OS Linux and NVIDIA DRIVE<sup>&trade;</sup> OS QNX.

PFC runs on these hardware platforms:
- NVIDIA DRIVE<sup>&trade;</sup> AGX Platform:
  Bench setup with all sensors connected.
- NVIDIA DRIVE AGX Platform: In-Car.

For information related to the following, see the _NVIDIA DRIVE AV Release Notes_:
- Specifications on the supported NVIDIA DRIVE AGX Platform
- Software versions that PFC and NVIDIA DRIVE AV use

PFC must be installed with NVIDIA DRIVE<sup>&trade;</sup> AV.

@subsection pfc_tool_prereq_bench Bench Mode Validation Prerequisites

Below are the prerequisites to ensure correct PFC results during **bench mode**
validation. In bench mode, sensor data can come from both recordings and sensors.

- The GPS sensor must have a clear sky. If PFC is executed in a garage or closed environment, the GPS data-validity may
  indicate failure.
- The Radar sensors must be separated from objects by at least 1-meter. Otherwise, Radar data-validity fails.
- All camera and Radar sensors must be exposed to a valid environment. Cameras must:
  - Be exposed to appropriate lights.
  - Have a valid, unobstructed view.\n
    Cameras must not face a static view, e.g., a wall.\n
    Cameras must not be obstructed by barriers, e.g., trees, cloth, or mud.

@subsection pfc_tool_prereq_av Autonomous Vehicle Mode Validation Prerequisites

Below are the prerequisites to ensure correct PFC results during **autonomous vehicle mode** validation.

- The prerequisites specified in @ref pfc_tool_prereq_bench.
- The following must be true, otherwise CAN sanity fails:
  - Car engine must be ON.
  - Transmission must be in Park.
  - Steering wheel must be unlocked.

@section pfc_tool_usage Usage

Run this tool by navigating to:

    /usr/local/driveworks/tools/preFlightChecker/config

and executing:

    ./pfc_run.sh

@subsection pfc_tool_usage_av For Autonomous Vehicle Mode

Run the tool by executing:

    ./pfc_run.sh --rig=[rig_file_path]
                 --car=[car name] 
                 --no-gui

For example:

    ./pfc_run.sh --rig=hyperion-7-1-release.json
                 --car=agx-rel
                 --no-gui

For NVIDIA Hyperion 7.1, the config rig file is available at:

    /usr/local/driveworks/tools/preFlightChecker/config/hyperion7-1-release.json

PFC updates the log output as specified in this file. For more information regarding this log, refer to @ref pfc_tool_log_output.



@subsection pfc_tool_usage_bench For Bench Mode

PFC performs the same checks in bench mode as it does in autonomous vehicle mode. However, CAN devices are unavailable in bench mode. These devices include <br> brake, throttle, gear, and steering. As a result, validation for these devices will always fail.

Run the tool by executing:

    ./pfc_run.sh --rig=[rig_file_path]

For example:

    ./pfc_run.sh --rig=hyperion-7-1-release.json

For NVIDIA Hyperion 7.1, the config rig file is available at:

    /usr/local/driveworks/tools/preFlightChecker/config/hyperion7-1-release.json

@section pfc_tool_command_options Command Line Options

The following lists the required command line arguments for each mode.

@subsection pfc_tool_command_options_av Required Arguments for Autonomous Vehicle Mode

    --rig=
        Parameter: --rig=[rig_file_path]
        Description: The path of the rig.json file specifying each sensor to validate based on the setup configuration.
        Example: --rig=hyperion7-1-release.json

    --car=
        Parameter: --car=[rig_file_path]
        Description: Identifies the specific vehicle for PFC. For the NVIDIA AGX Platform, set this parameter to `agx-rel`.
        Default value: bench
        Example: --car=agx-rel

@subsection pfc_tool_command_options_bench Required Arguments for Bench Mode

    --rig=
        Parameter: --rig=[rig_file_path]
        Description: The path of the rig.json file specifying each sensor to validate based on the setup configuration.
        Example: --rig=hyperion7-1-release.json

@subsection pfc_tool_command_options_optional Optional Arguments

    --no-gui
        Parameter: --no-gui
        Description: Disables the PFC GUI, and displays only the result on the console.

@subsection pfc_tool_hyperion8 Usage on Hyperion 8 Platform

Run this tool by navigating to:

    /usr/local/driveworks/tools/preFlightChecker/config

Execution:

    python3 hyp8_pfc_run.py --rig, -r [rig_folder_path]
                            --rigname, -rn [rig_folder_name]
                            --autorig, -a
                            --output, -o [output_folder_path]
                            --car, -c [car_designation]
                            --inspection, -i

@subsection pfc_tool_command_options_av Arguments for Hyperion 8 Execution

    --rig
        Parameter: --rig, -r [rig_folder_path]
        Description: The path of the rig folder specifying the supported sensors attached to each tegra.
        Example: --rig /usr/local/driveworks/tools/capture/configs/campaign/hyperion8-protoplus-dc

    --rigname
        Parameter: --rigname, -rn [rig_folder_name]
        Description: The rig folder name specifying the supported sensors attached to the platform.
        Example: --rigname hyperion8-protoplus-dc

    --autorig
        Parameter: --autorig, -a 
        Description: Runs PFC with automatically-selected rigs based on the vehicle BOM ID. 

    --car
        Parameter: --car, -c [car_designation]
        Description: The designator for the given car. Used only to seperate outputs of PFC results.
        Example: --car 27

    --output
        Parameter: --output, -o [output_folder_path]
        Description: Ouput folder to write logs from all tegras. An output file for each tegra will be generated in folder location.
                     Default: /tmp/pfc_logs. 
        Example: --output /home/nvidia/pfc_output

    --inspection
        Parameter: --inspection, -i
        Description: Run automated inspection process. Requires the 'car' argument to be set. 

@section pfc_tool_log_output Output

This is an example of the log output specified in @ref pfc_tool_usage_av. It displays the current sensor status in a sequence of four pages: one **Summary** and three **Detail**.

## Summary

Displays a status summary for all sensors. Press the LEFT-ARROW and RIGHT-ARROW keys to navigate between pages.

![PFC Summary](pfc_summary.png)

## Detail

Displays a detailed status log with sensor information. The log provides the following information:

| Information | Description|
|-------------|------------|
| SENSOR TYPE | The type of sensor. |
| SENSOR NAME | Sensor name and type as specified in rig file, i.e., camera, Lidar, or Radar. This field also displays the sensor position if available. |
| INIT | Sensor initialization status. |
| DATA-RATE (MP/s) | Rate for which the sensor feeds data to the PFC (in megapixels per second). Applies to camera sensors only. |
| FREQUENCY (Hz) | Number of frames available per second (in Hertz). |
| DATA-VALIDATE | Status of the data validity check performed on sensors. Possible values are: \n - **VALID**: Sensor provides valid data. \n - **NOT_IMPL**: Support for the specified sensor is not implemented. \n - **NA**: Indicates the attribute does not apply to the sensor. |

The following is an example of the detailed status log.

![PFC Detail Table](pfc_detail_table.png)

If debug logs are enabled, there is a possibility of CAN Sanity and IMU/GPS data-validity failure. This failure is from the logging latency.

For information on how PFC determines data validity, please refer to @ref pfc_tool_features.

@section pfc_tool_additional_info Additional Information

This section explains how to interpret information in the detailed sensor log.

#### If the Sensor Frequency Is Zero

The `FREQUENCY` field for a sensor shows a value of zero when data is not available.
This can happen even though the sensor is connected properly.<br>
These symptoms can be due to:
- A weak GPS signal strength.
- A blocked Lidar or Radar sensor.

#### If the Sensor has an INVALID Status

The `DATA-VALIDATE` field for a camera shows `INVALID` when there are issues with
the sensor position.

- To fix this in bench mode, re-align the camera sensor.
- To fix this in autonomous vehicle mode, move the vehicle to a different location.