DLT Viewer User Manual
======================
Alexander Wenzel <Alexander.AW.Wenzel@bmw.de>
v0.0.4, February 2016: Updates and improvements for current DLT Viewer state
// v0.0.3, April 2013: Added Filetransfer commandline description
// v0.0.2, December 2012: Converted to asciidoc

:toc:

image::images/genivi_chrome_1_transparent.png[width=128]

Introduction
------------

Purpose
~~~~~~~
The DLT Viewer tool can decode, view and store DLT messages
generated by DLT Daemon. The DLT Viewer tool enables the software developer and
the tester of the device to view and control the log and trace information. It is
not the goal of GENIVI to provide full functional analyzing tools for traces,
but to provide a basic set of utilities to visualize, control and test all features of the
DLT Daemon component in a simple way. The DLT Daemon component and the DLT Viewer
are based on the AUTOSAR 4.0 standard DLT.

We try to keep the GUI simple for an effective and efficient workflow, but also to
integrate as much functionality as needed.

Feature List
~~~~~~~~~~~~
- Graphical User Interface
    * Menu and toolbar
    * Project widget
    * DLT Message Table
    * DLT Viewer Plugin
    * Footer with information about the current file etc.
- View DLT files
    * Drag and Drop support
    * Recent files selection
    * Temporary files support
    * Append files
    * Index cache of already opened DLT files
    * Default DLT file loading
    * Open multiple files (v2.10.1)
- Retrieve DLT messages from targets and store them in DLT files
    * Serial connections
    * TCP/IP connections
    * Multiple parallel connections
    * Autoconnect to targets
    * Configure log levels and trace status
    * Store configuration in target
    * Reset the target's configuration
    * Organise connections in projects
- Filter DLT messsages for analysing
    * Support to show only a defined subset of the messages
    * Complex filter configurations
    * Save and restore filter configurations
    * Multiple default filter configurations
    * Markers to highlight specific messages
    * Filter index cache of already filtered DLT files
    * Regular expressions
    * Sorting by time (v2.10.1)
- Clipboard support
    * Copy selected DLT messages to clipboard
- Export of DLT files in multiple formats
    * Supported formats:
        ** DLT format with selection
        ** ASCII format
        ** CSV format
    * Select the messages to be exported
        ** All messages
        ** Filtered messages
        ** Marked messages
- Search DLT messages
    * Step by step search
    * Search export view
    * Search by regular expressions
- Project configurations
    * Control log levels
    * Organise configurations in projects
    * Save and restore projects
    * Recent projects selection
    * Select displayed columns
    * Default project loading
    * Automatic timezone synchronisation (v2.10.1)
- Plugin configurations
    * Decoder plugins to decode messages
    * Viewer plugins to show more detailed information and analyse logs. Viewer plugins provide extra widgets to visualize data
    * Control plugins to control applications on the target
    * Available plugins
        ** DLT Viewer Plugin
        ** Non Verbose Mode Plugin
        ** Filetransfer Plugin
        ** DLT Statistic Plugin
        ** DLT System Viewer Plugin
- Command line support
    * Silent mode
    * Loading project
    * Loading DLT file
    * Using filter configuration
    * Export DLT files to ASCII
    * Execute commands in plugins
- Plugins programming guide


DLT Viewer GUI
--------------
Layout
~~~~~~
image::images/main_window_plain.png[width="100%"]

The screenshot above will give you a quick impression about how the Viewer
could look. The Viewer is based on Qt, so there are widgets you can move
around and resize as you like. Your settings of position and size of the
widgets are stored when you close the Viewer so that you have exactly the
same window when you launch the Viewer the next time.

To get a better understanding about the DLT Viewer parts the screenshot
below marks the relevant areas followed by a description.

image::images/main_window_annotated.png[width="100%"]

[width="100%",style="asciidoc",cols="<5%,<15%,<80%",frame="topbot",options="header"]
|=============================================================================
|Nr|Title|Description
|image:images/Mark1.png[width="64"]|Menu and Toolbar|In the window title you can find the absolute path of your
project file (if a file is used) and the project name. If you start the DLT Viewer with no default
project file it will create an unnamed project. After the project name you
can read the version of the DLT Viewer. In any case of contact with the
development team, please report the version of the DLT Viewer.

The menu consists of:

* *File* + 
    Open and save files, access DLT Viewer settings etc.
* *Search* + 
    Search for specific messages in the current log.
* *Project* + 
    Create, open and save DLT Viewer projects.
* *Config* + 
    Add, edit and remove ECUs, applications and contexts.
* *DLT* + 
    Additional functions concerning the DLT daemon and the current configuration.
* *Filter* + 
    Create, open and save filters for the message log.
* *Plugin* + 
    Enable, show and edit plugins.
* *View* + 
    Select the visible components of the DLT Viewer.
* *Help* + 
    Get information and help for the DLT Viewer.

The menu provides main functions to the user. Many menu functions are also easily accessible through the toolbar.
Hover the cursor over toolbar buttons to see their functions.
|image:images/Mark2.png[width="64"]|Project Panel

* Config 
* Filter 
* Plugin |The project widget allows you to configure and control the project,
load an existing project, save a changed configuration to the DLT Daemon and
more. The project panel is split into three tabs:

* The "Config" tab, which contains all connected ECUs/Devices. Each Device contains
its connected applications. Each application contains its used contexts.
* The "Filter" tab lets you configure filters and markers, which are used to show or
mark only a defined subset of DLT messages in the log.
* The "Plugin" tab shows the available DLT Viewer plugins. The development team provides a
plugin SDK to you. You are able to write your own DLT Viewer plugins to decode
messages, display an extra GUI panel or control the Viewer and target applications. More information about the Plugin SDK can be found here: + 
http://projects.genivi.org/diagnostic-log-trace/sites/projects.genivi.org.diagnostic-log-trace/files/dlt_viewer_plugins_programming_guide.html

In the settings you can select a default project, which is loaded during start-up.
|image:images/Mark3.png[width="64"]|DLT Message Table|In the DLT Message Table you
see all DLT messages in the current DLT log file. Newly received DLT messages are written to the end of the log file.
If the _AutoScroll_ option is enabled in the settings, the table will scroll along with
new DLT messages while they are received.

The columns in the message table are:

* *Index* + 
    Index of the DLT message in the DLT log file.
* *Time* + 
    Time when the message was received.
* *Timestamp* + 
    Time when the message was sent, measured since the startup of the target.
* *Count* + 
    Cyclical counter, one per context. Can be used to detect lost messages.
* *Ecuid* + 
    Name of the sending ECU. Defined in the "Projects" tab.
* *Apid* + 
    Indetifier of the message sender application. Defined by the sending application.
* *Ctid* +
    Context indentifier of the message sender. Defined by the sending application.
* *Type* + 
    Type of the message (Log / Trace).
* *Subtype* + 
    Log level or trace type.
* *Mode* + 
    Verbose or Non-Verbose.
* *Args* + 
    The number of arguments in the payload of the message.
* *Payload* + 
    The payload shows all parameters of the log message as text.

If a filter is configured, you will see only DLT messages which match
this filter. Remove or disable all filters if you want to see all messages.
If there are decoder plugins and a DLT message matches one of these plugins, the decoded
payload is displayed instead of the raw payload.
DLT log files can be loaded and saved in the file menu.
|image:images/Mark4.png[width="64"]|Plugin Widgets|Viewer plugins provide one or more widgets to
display additional data. You can choose which plugins are to be shown in the "Plugin" tab.
|image:images/Mark5.png[width="64"]|Footer|The footer shows information about the current log file
and the build version and options of the DLT Viewer.
|=============================================================================

Project Panel
~~~~~~~~~~~~~

Config Tab
^^^^^^^^^^

image:images/project_widget.png[]

In the config tab you can see a hierarchical list of all configured devices,
applications and contexts.

* The ECU item lists the ID of the ECU, its status (red = offline, yellow = connecting,
green = online), a description of the ECU including the connection interface, the default
log level and the default trace status.
* The application item lists the ID and the description of the application.
* The context item lists the ID, the description, the log level and the trace
status of the context.

Double clicking an item lets you configure it. Right clicking an item gets you a context menu, depending on the type of the item:

- Right click on empty space: + 
    image:images/ecu_add.png[]

- Right click on an ECU: + 
    image:images/ecu_context_menu.png[]

- Right click on an application: + 
    image:images/app_context_menu.png[]

- Right click on a context: + 
    image:images/ctx_context_menu.png[]


Filter Tab
^^^^^^^^^^

image:images/filter_widget.png[]

The Filter list gives you an overview of all configured filters. Only DLT messages which match the enabled filters are displayed.
Double clicking a filter item lets you change the filter. Each filter can be customized to include or exclude messages, to check for
specific ECUs, applications or contexts, for header and payload content and more. It is also possible to create marker filters, which don't
include or exclude any messages but highlight them in a selected color.

By right clicking you get the following context menu:

image:images/filter_context_menu.png[]

Both the "Load Filter" and the "Append Filter" option will load a saved filter file, but "Load Filter" will reset your current filter list while appending keeps it.

The filters you set will apply to all incoming or loaded DLT messages. If you also want to apply the filters to previously logged messages, hit the
"Apply Configuration" button on the top of the "Filter" tab.

Plugin Tab
^^^^^^^^^^

image:images/plugin_widget.png[]

The plugin list shows all loaded plugins. 
Plugins are used to decode DLT messages, to provide additional graphical widgets, to control the viewer, to send injection messages to target applications or a mixture of all these. Double clicking a
plugin item creates a popup window which lets you enable/disable the plugin and select a configuration file for it.

* The "Name" column shows the name of each plugin. This name is provided by the plugin itself.
* The "Interface" column tells you the type of the plugin (or more precisely: what interfaces it implements). For each plugin this column shows a combination of "View", "Decode", "Ctrl" and "Command".
* The "Status" column shows which plugins are enabled and visible. Only plugins that implement the "View" interface can have the status "Visible".
* The "Info" column lists the number of description items for each plugin. The description items can be seen by expanding plugin items that have an arrow next to them.
* The "File" column tells you the path of the configuration file or files for plugins that have such a file or files selected. Double click on plugin items to choose configuration files for them.

Plugin overview
~~~~~~~~~~~~~~~

The feature set of the DLT Viewer can be easily extended with DLT Viewer plugins.
Plugins have full read access to trace messages, they can decode messages,
provide additional representations inside the DLT Viewer GUI, control the Viewer or send injection messages to target applications,
depending on which DLT interfaces the respective plugin implements. It's easy to write your own DLT Viewer plugin, examples are provided in the DLT Viewer source code.

Plugin SDK
^^^^^^^^^^

You can find a more detailed documenation of all plugin interfaces in the "Dlt Viewer Plugins Programming Guide": +
http://projects.genivi.org/diagnostic-log-trace/sites/projects.genivi.org.diagnostic-log-trace/files/dlt_viewer_plugins_programming_guide.html

Here is an overview of the some useful plugins:

Non Verbose Mode Plugin
^^^^^^^^^^^^^^^^^^^^^^^

Interface::
    * QDLTPluginInterface
    * QDLTPluginDecoderInterface
Description::
    Decodes the DLT non-verbose messages after a catalog file has been loaded.


DLT Viewer Plugin
^^^^^^^^^^^^^^^^^

Interface::
    * QDLTPluginInterface
    * QDltPluginViewerInterface
Description::
    Advanced visual representation for selected log messages.
Screenshot::
    image:images/Viewer_plugin.png[]


Filetransfer Plugin
^^^^^^^^^^^^^^^^^^^

*Widget:*

Interface::
    * QDLTPluginInterface
    * QDltPluginViewerInterface
    * QDltPluginControlInterface
Description::
    Files like screenshots, coredumps etc. logged by a DLT Filetransfer application
    can be viewed and saved with this plugin.
Screenshot::
    image:images/filetransfer_plugin.png[]

*Command line usage:*

You can use the Filetransfer Plugin to extract files out of a stored dlt file.
To do this, call the Viewer with this command:

[dlt_Viewer.exe] -p project_filetransfer.dlp -l filewithattachements.dlt -e "Filetransfer Plugin|export|[path_to_extract]"

* [dlt_Viewer.exe] + 
    The executable of the DLT Viewer. E.g. dlt_Viewer.exe in Windows, dlt_Viewer in Linux
* project_filetransfer.dlp: + 
    A project, which has the filetransfer properly configured, by setting a valid plugin xml.
* filewithattachements.dlt: + 
    Path to a dlt trace file. If it contains embedded files, they will be extracted
* -e: + 
    triggers a plugin command
* "Filetransfer Plugin: + 
    Filetransfer Plugin will be called for the command interface
* export: + 
    the export function is called
* [path_to_extract]": + 
    Path to the folder where you want to extract all file dumps. If you apply this for a lot of files, think about using individual paths, to avoid overwriting files with identical names.


Install, remove, enable and disable plugins on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The DLT Viewer will look for plugins in two places. The first place is the
"plugins" folder inside the main application path. After that, if "pluginsPath" is
defined in the DLT Viewer settings, the application will also look in this specified location for plugins.

You can install plugins by putting them into one of the directories mentioned,
and uninstall them by removing them from these directories.

It is also possible to enable or disable plugins in the DLT Viewer itself.
To do this, double-click or right-click on a plugin in the "Plugins" tab. You will get a
drop-down menu for enabling and disabling the plugin. When enabled,
messages are passed to the plugin. When disabled, the plugin will be ignored in
the message processing chain. For plugins that implement the "viewer" interface,
there is also a third selection, "Enable and Show", which brings up the UI widget of
this plugin.

Install, remove, enable and disable plugins on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Under Linux, organizing plugins works in a similar fashion. In addition to the previously mentioned folders,
the Linux version will also look into "/usr/share/dlt-Viewer/plugins" for any plugins.
You will need to have root permissions to modify the plugin directories that are installed system-wide.
To organize plugins without root permissions, you can set the user defined plugin directory in the DLT Viewer
settings to some other path, e.g. somewhere in your home directory.

Best Practices
--------------

Connect to ECU
~~~~~~~~~~~~~~

Press the connect button to connect to the target:
image:images/connect_button.png[]

If no ECU is configured, the ECU configuration dialog appears. Select the
"Interface Type" you want to use (TCP or serial).

image:images/ecu_dialog.png[]

If you choose a TCP connection configure the Hostname of the target ECU.

image:images/ecu_dialog_tcp.png[]

If you choose a serial connection, select the serial port. Check the COM port,
where your serial device is connected in your Windows configuration. A drop down
list provides a list of examples for the port configuration.

image:images/ecu_dialog_serial.png[]

If you select "OK" the DLT Viewer will try to connect to the ECU.
The ECU Id shows "online" (green) as soon as the DLT Viewer is connected to the
specified device.
All received DLT messages should then be displayed in DLT message table.


Available List of Contexts
~~~~~~~~~~~~~~~~~~~~~~~~~~

When you are connected to an ECU, you can get a list of available contexts
in the ECU. Select an ECU item in the Config window. Right click on the
selected ECU and select the context menu item "DLT Get Log Info".
The DLT Viewer then sends a request to the target and receives a result
with all available contexts and their log levels. The list of available contexts is added
to your "Config" list.

Working with DLT Log Files
~~~~~~~~~~~~~~~~~~~~~~~~~~

When you start the DLT Viewer, a temporary log file is created.
All received DLT messages get stored in this temporary log file and
shown in the DLT message table.
Select the menu option "File"->"Save As" to copy your temporary log file to a
file you have selected. Select "File"->"New" if you want to create and save a new,
empty log file.

Non Verbose Mode Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you receive DLT messages in non verbose mode, you need to decode them
to see their plain text. To do this, go to the "Plugin" tab in the "Project" panel.
Double click on the plugin "Non Verbose Mode Plugin". In the dialog that appears,
you can open a configuration file to load. Use this to load a non verbose XML description file,
which corresponds to your software on the ECU. Hit "OK" and the Plugin shows a list of all available
non verbose messages. As soon as you select a DLT message you can view the
decoded information. Incoming messages that fit the description file will now get decoded. To also
decode the already received messages, hit "Apply Configuration" on the top of the "Plugin" tab.