# MDF Import Tool Help

This document describes how to import MDF files with the `mdfimport` tool. To learn how to call `mdfimport` as a function, see separate MDF import function help.

## Contents

- Starting the tool
- Opening an MDF File
- Selecting signals
- Importing the signals
- Signal Import Options
- Creating a signal selection file
- Using a signal selection file
- Changing the created time vectors
- Clearing MDF and signal selection files
- Generating command line equivalent
- Appendix

## Starting the tool

To open the MDF import tool, type `mdfimport` at the command line, with no arguments.

## Opening an MDF File

From the MDF File menu, select Open MDF File.... Use the dialog that appears to browse and select an MDF (`.dat` or `.mdf`) file. After an MDF file has been selected, the names of all available signals will appear in the Unselected signals list in the Select Signals panel. The name of the MDF file is also listed at the top of this panel.

The available signal names shown are the 'long' names and are displayed with the device names hidden by default. If you want to see the device names, uncheck the Hide device names check box below this Unselected signals list. The device names are always removed from the signal names when the variables are created in the workspace. The names are also appended with textual information from the MDF file about the sample rate of the signal. It is usually a string such as '125ms' but can also a string like 'Cly Event' or 'Synchro' for asynchronously sampled signals.

## Selecting signals

You specify a signal for importing by selecting it from the Unselected signals list with the mouse then pressing the '>' button. This will move it to the Selected signals list. You can use the ctrl and shift keys to make multiple selections. You can select all signals with the '>>' button. You can unselect signals from the Selected signals list, returning them to the Unselected signals list in a similar way using the '<' and '<<' buttons.

## Importing the signals

You import the selected signals by pressing the Import signals button in the lower right corner. All signals will be loaded into the MATLAB workspace by default as individual column vector variables. By default, each variable name is appended with `_N` where `N`, usually in the range 1 to 5, denotes one of the sampling rates in the MDF file. A time vector variable `time_N` is also created in the workspace and contains the associated sample times of the signal. The time vector can be used for plotting the signal against time correctly or to provide the timing information for a Simulink "From Workspace" block.

## Signal Import Options

You can import the generated signals into a MAT-File instead. Go to the Signal Import Options panel. Then in the Import signals to: option, choose MAT-File. After pressing the Import signal(s) button, choose the name of a MAT-file in the browser that appears. The name defaults to the MDF filename with the `.mat` suffix instead.

You can differentiate variables and time vectors of different sample rates by having them appended with a string representing the sample rate (e.g. `_10ms`) instead of a rate number. To do this, choose rate string in the Differentiate rates by appending variable names with option. This is useful if the tool generating the MDF file changes the rate number between different tests, making it difficult to compare the variables.

You can also append variable names with additional text. This can be useful if you want to differentiate the same set of data from multiple different sessions, simulation runs or experiments. To do this add any text into the edit box labeled Append variable names with additional text.

## Creating a signal selection file

You can save the list of signals you selected in a file for use again. From the Signal Selection File menu, select Create Signal Selection File.... This brings up a dialog to allow you to locate a directory and text file to store the selected signal names.

## Using a signal selection file

You can open a previously stored signal selection file before or after you have loaded an MDF file. From the Signal Selection File menu, select Open Signal Selection File.... Use the dialog that appears to browse and select a `.txt` file.

If an MDF file is currently loaded, the signals will be selected immediately. Any signals not found in the currently loaded MDF file with be listed in the command window.

If an MDF file is not currently loaded yet, the requested signals from the signal selection file will be shown in italics in the Selected signals list. Then when an MDF file is loaded, the signals will be selected and any signals not found in the MDF file with be listed in the command window. If you do not clear the signal selection file, the signal selection will remain active and be applied to each MDF file loaded. This provides a method of selecting the same signals in multiple MDF files.

The signal selection file can be edited or manually created with the signal names you want to select. The MDF Import tool selects signals with names (with device names removed) that exactly match the strings in the signal selection file.

## Changing the created time vectors

Although signals in an MDF file have a nominal sample rate, e.g. 125ms, in practice, the sampling is non-uniform and thus the time vectors generated are non-uniform. You can generate uniform time vectors by choosing Create ideal uniform time vectors in the Time Vector Generation panel.

The 1-5 different sample rates used in the selected signals are displayed in the Selected rates list. This list shows the textual information about the samepl rates of the signals (e.g. 125ms) together with the actual numerical value of the sample rate (e.g. 0.125). You can override a rate by selecting it and changing its value in the New sample rate edit box to the right.

## Clearing MDF and signal selection files

From the MDF File or Signal Selection File menu, select Clear.

## Generating command line equivalent

You can generate the command line equivalent call to `mdfimport` with appropriate parameters, based on the current options set in the GUI tool. This is useful in automating tasks in a script such as importing many files. See separate MDF import function help for examples of using `mdfimport` as a function/command.

Choose the Command Generation menu and select Generate. The command line equivalent is displayed in the command window. Copy and paste this into the command window or an M-file to run. If there are many signals selected, you can replace long the list of names with a signal selection file (see "Creating a signal selection file" earlier in this document). If all signals are selected, the signal selection parameter is set to the default `[]` meaning import all signals.

## Appendix

Known limitations

- This tool has only been tested with MDF files generated by ETAS INCA.
- You cannot load signals from "unsorted" MDF files.
- You cannot load signals with names greater that 64 characters. The conversion of illegal variable characters like '.' and '\' to legal characters (see below) will make names longer.
- You cannot load signals in data blocks containing byte arrays.
- You can only load signals with conversion formulae type 0, 1, 2, 6, 10 (assuming 'x' as variable), 11, 12, 65535.
- Only MDF files with data from one device is supported. The work around is to store data from more than one device in sepertate MDF files.

Signal name creation

As variables are created for each signal, legal MATLAB variable names must be created from the signal names. This is done by converting illegal characters to legal character combinations and by optionally adding an `'x'` to the start when signal names begin with numbers. The convertion process can be customized by modifying the `mygenvarname` subfunction inside `mdfimport`. The following illegal characters are converted as shown:

- `'\'` replaced with `'_bs_'`
- `'/'` replaced with `'_fs_'`
- `'['` replaced with `'_ls_'`
- `']'` replaced with `'_rs_'`
- `'('` replaced with `'_lp_'`
- `')'` replaced with `'_rp_'`
- `':'` replaced with `'_co_'`
- `'-'` replaced with `'_hy_'`
- `' '` (space) replaced with `'_'`
- `'.'` replaced with `'p'`
- `'$'` replaced with `'S_'`

References

This is a list of useful links:

- ETAS, INCA
- MATLAB Add-on for INCA
- Vecto CANTech, CANape Graph