Get Started with Writing Timetable Data to MDF Files

Open Live Script

This example shows how to write timetable data into an MDF file. The MAT-file used in this example MDFTimetables.mat contains two timetables.

Timetable TT1 has variables of numeric data types, including uint8, uint16, uint32, uint64, int8, int16, int32, int64, single, and double.
Timetable TT2 has variables of string and byte array data types, including both fixed-length and variable-length data.

Introduction

A simplified model to represent the structure of an ASAM MDF file is a three-level hierarchy composed of the file, the channel group, and the channel. A file consists of a number of channel groups; a channel group consists of a number of channels.

There are two important elements to the content of an MDF file: the data and the metadata.

Signal or channel data written into an MDF file is generally either acquired or calculated. Typical signals for an automotive application are sensor data, ECU-internal variables/states, bus traffic in a vehicle network, or internally calculated values. In most applications, data in all channels of a channel group is synchronized by time, but it is also possible for them to be synchronized by angle, distance, or index. In rare cases, there could be no synchronization domain or multiple synchronization domains. Currently, the MDF functions in MATLAB® only support one synchronization domain by time.
Metadata are additional descriptive information about the measurement environment. They are applicable to the three hierarchical levels: the file, the channel group and the channel. Each level has a set of metadata fields defined by the ASAM MDF standard.

In this example, data in TT1 and TT2 are written into channel groups 1 and 2, respectively, of a new MDF file. You should use this workflow if there is no need to customize metadata at any of the three hierarchical levels.

If you need to customize metadata when writing to an MDF file, use the advanced workflow in example Customize Metadata When Writing Timetable Data to MDF Files.

Load Timetables into Workspace

Load the timetable variables, TT1 and TT2, from MDFTimetables.mat into the workspace.

load("MDFTimetables.mat")

Write Timetable Data Directly to a New MDF File

Use the mdfWrite function with the target MDF file name and the timetable variable TT1 specified as input arguments. Because the target file TimetableBasic.mf4 does not exist yet, the function creates the file automatically and displays a warning to inform the path of the newly created file. Data in TT1 is written to the first available channel group index of the file, which is channel group 1 since TimetableBasic.mf4 is a newly created file.

mdfWrite("TimetableBasic.mf4", TT1)

Warning: Specified target file did not exist. Created file: 
/tmp/Bdoc24b_2725827_3770958/tp7650169a/vnt-ex65847646/TimetableBasic.mf4

Call mdfWrite again to write TT2 to the next available channel group index 2.

mdfWrite("TimetableBasic.mf4", TT2)

Examine the Default File Metadata

Using this workflow, default values for file metadata were applied by mdfWrite while creating the MDF file. To examine the file metadata of TimetableBasic.mf4, call mdfInfo with the MDF file name specified.

info = mdfInfo("TimetableBasic.mf4")

info = 
  MDFInfo with properties:

   File Details
                  Name: "TimetableBasic.mf4"
                  Path: "/tmp/Bdoc24b_2725827_3770958/tp7650169a/vnt-ex65847646/TimetableBasic.mf4"
                Author: ""
            Department: ""
               Project: ""
               Subject: ""
               Comment: ""
               Version: "4.20"
      InitialTimestamp: 2024-09-06 03:17:37.000000000

   Creator Details
     ProgramIdentifier: "MATLAB"
     CreatorVendorName: "The MathWorks, Inc."
       CreatorToolName: "MATLAB"
    CreatorToolVersion: "24.2.0.2712019 (R2024b)"
       CreatorUserName: ""
        CreatorComment: ""

   File Contents
            Attachment: [0x7 table]
     ChannelGroupCount: 2
                 Event: [0x8 eventtable]

Examine the Channel Group Metadata

Examine metadata for the two channel groups written to TimetableBasic.mf4 using mdfChannelGroupInfo. Metadata fields such as AcquisitionName and Comment were assigned default values. Other fields such as NumSamples, DataSize and Sorted are dependent on the data.

chanGrpInfo = mdfChannelGroupInfo("TimetableBasic.mf4")

chanGrpInfo=2×13 table
    GroupNumber    AcquisitionName      Comment      NumSamples    DataSize    Sorted    SourceName     SourcePath     SourceComment    SourceType     SourceBusType    SourceBusChannelNumber    SourceSimulated
    ___________    _______________    ___________    __________    ________    ______    ___________    ___________    _____________    ___________    _____________    ______________________    _______________

         1           <undefined>      <undefined>       100          5000      true      <undefined>    <undefined>     <undefined>     Unspecified     Unspecified               0                    false     
         2           <undefined>      <undefined>        10           340      true      <undefined>    <undefined>     <undefined>     Unspecified     Unspecified               0                    false

Examine the Channel Metadata

Examine metadata for the channels in channel group 1 using mdfChannelInfo. Specify the AdditionalMetadata option as true to view the additional metadata as well.

Row times of the timetable were written into a time channel, while variables of the timetable were written into respective data channels.

Metadata fields Type, DataType and NumBits were derived from the data stored in the corresponding timetable variable by mdfWrite. For instance, variable named uint8_data in TT1 contains 8-bit unsigned integers, so Type of the channel is asam.mdf.ChannelType.FixedLength (0), DataType is asam.mdf.ChannelDataType.IntegerUnsignedLittleEndian (0), and NumBits is 8.

Other metadata fields were assigned default values by mdfWrite. In the case of the time channel, Unit is known to be second, so it was assigned value 's'.

chanGrp1Info = mdfChannelInfo("TimetableBasic.mf4", GroupNumber=1, AdditionalMetadata=true)

chanGrp1Info=11×25 table
        Name         GroupNumber    GroupNumSamples    GroupAcquisitionName    GroupComment    GroupSourceName    GroupSourcePath    DisplayName       Unit          Comment      ExtendedNamePrefix    SourceName     SourcePath        Type        SyncType             DataType              NumBits    ComponentType    CompositionType    ConversionType    SourceComment    SourceType     SourceBusType    SourceBusChannelNumber    SourceSimulated
    _____________    ___________    _______________    ____________________    ____________    _______________    _______________    ___________    ___________    ___________    __________________    ___________    ___________    ___________    ________    ___________________________    _______    _____________    _______________    ______________    _____________    ___________    _____________    ______________________    _______________

    "Time"                1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         s              <undefined>       <undefined>        <undefined>    <undefined>    Master           Time      RealLittleEndian                 64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "double_data"         1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      RealLittleEndian                 64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "int16_data"          1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerSignedLittleEndian        16           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "int32_data"          1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerSignedLittleEndian        32           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "int64_data"          1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerSignedLittleEndian        64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "int8_data"           1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerSignedLittleEndian         8           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "single_data"         1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      RealLittleEndian                 32           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "uint16_data"         1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerUnsignedLittleEndian      16           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "uint32_data"         1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerUnsignedLittleEndian      32           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "uint64_data"         1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerUnsignedLittleEndian      64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "uint8_data"          1               100              <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength      None      IntegerUnsignedLittleEndian       8           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false

Similarly, examine the metadata for channels in channel group 2. Metadata fields Type, DataType and NumBits were also derived from the data stored in the corresponding timetable variable by mdfWrite.

Data samples in variables fixed_length_string_data and fixed_length_byte_array_data of TT2 are fixed-length, so Type of these two channels are asam.mdf.ChannelType.FixedLength (0). Variables variable_length_string_data and variable_length_byte_array_data contain data samples with variable lengths, so Type of these two channels are asam.mdf.ChannelType.VariableLength (1).
For the two variables that have string data, fixed_length_string_data and variable_length_string_data, DataType is asam.mdf.ChannelDataType.StringASCII (6). For the two variables that have byte array data, fixed_length_byte_array_data and variable_length_byte_array_data, DataType is asam.mdf.ChannelDataType.ByteArray (10).
NumBits for a fixed-length channel is derived from the data. For a variable-length channel, NumBits has a default value of 64.

chanGrp2Info = mdfChannelInfo("TimetableBasic.mf4", GroupNumber=2, AdditionalMetadata=true)

chanGrp2Info=5×25 table
                  Name                   GroupNumber    GroupNumSamples    GroupAcquisitionName    GroupComment    GroupSourceName    GroupSourcePath    DisplayName       Unit          Comment      ExtendedNamePrefix    SourceName     SourcePath          Type         SyncType        DataType        NumBits    ComponentType    CompositionType    ConversionType    SourceComment    SourceType     SourceBusType    SourceBusChannelNumber    SourceSimulated
    _________________________________    ___________    _______________    ____________________    ____________    _______________    _______________    ___________    ___________    ___________    __________________    ___________    ___________    ______________    ________    ________________    _______    _____________    _______________    ______________    _____________    ___________    _____________    ______________________    _______________

    "Time"                                    2               10               <undefined>         <undefined>       <undefined>        <undefined>          ""         s              <undefined>       <undefined>        <undefined>    <undefined>    Master              Time      RealLittleEndian      64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "fixed_length_byte_array_data"            2               10               <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength         None      ByteArray             40           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "fixed_length_string_data"                2               10               <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    FixedLength         None      StringASCII           40           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "variable_length_byte_array_data"         2               10               <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    VariableLength      None      ByteArray             64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false     
    "variable_length_string_data"             2               10               <undefined>         <undefined>       <undefined>        <undefined>          ""         <undefined>    <undefined>       <undefined>        <undefined>    <undefined>    VariableLength      None      StringASCII           64           None              None           Unspecified           ""          Unspecified     Unspecified               0                    false

Examine the Data

To verify that data was successfully written to file, read data from both channel groups using mdfRead and examine the results.

data = mdfRead("TimetableBasic.mf4")

data=2×1 cell array
    {100x10 timetable}
    { 10x4  timetable}

chanGrp1Data = data{1}

chanGrp1Data=100×10 timetable
         Time      uint8_data    uint16_data    uint32_data    uint64_data    int8_data    int16_data    int32_data    int64_data    single_data    double_data
        _______    __________    ___________    ___________    ___________    _________    __________    __________    __________    ___________    ___________

        0 sec           0            200            600           1400           -99          -198          -396          -794          -9.8           -19.6   
        0.1 sec         2            204            608           1416           -97          -194          -388          -778          -9.6           -19.2   
        0.2 sec         4            208            616           1432           -95          -190          -380          -762          -9.4           -18.8   
        0.3 sec         6            212            624           1448           -93          -186          -372          -746          -9.2           -18.4   
        0.4 sec         8            216            632           1464           -91          -182          -364          -730            -9             -18   
        0.5 sec        10            220            640           1480           -89          -178          -356          -714          -8.8           -17.6   
        0.6 sec        12            224            648           1496           -87          -174          -348          -698          -8.6           -17.2   
        0.7 sec        14            228            656           1512           -85          -170          -340          -682          -8.4           -16.8   
        0.8 sec        16            232            664           1528           -83          -166          -332          -666          -8.2           -16.4   
        0.9 sec        18            236            672           1544           -81          -162          -324          -650            -8             -16   
        1 sec          20            240            680           1560           -79          -158          -316          -634          -7.8           -15.6   
        1.1 sec        22            244            688           1576           -77          -154          -308          -618          -7.6           -15.2   
        1.2 sec        24            248            696           1592           -75          -150          -300          -602          -7.4           -14.8   
        1.3 sec        26            252            704           1608           -73          -146          -292          -586          -7.2           -14.4   
        1.4 sec        28            256            712           1624           -71          -142          -284          -570            -7             -14   
        1.5 sec        30            260            720           1640           -69          -138          -276          -554          -6.8           -13.6   
      ⋮

chanGrp2Data = data{2}

chanGrp2Data=10×4 timetable
        Time     fixed_length_string_data    fixed_length_byte_array_data    variable_length_string_data    variable_length_byte_array_data
        _____    ________________________    ____________________________    ___________________________    _______________________________

        0 sec             "abcd"               {[255 255 255 255 255]}                 "zero"                   {[            255 255]}    
        1 sec             "efgh"               {[     18 35 52 69 86]}                 "one"                    {[     18 35 52 69 86]}    
        2 sec             "ijkl"               {[          0 1 2 3 4]}                 "two"                    {[    0 1 2 3 4 5 6 7]}    
        3 sec             "mnop"               {[          4 3 2 1 0]}                 "three"                  {[          4 3 2 1 0]}    
        4 sec             "qrst"               {[255 254 253 252 251]}                 "four"                   {[        253 252 251]}    
        5 sec             "uvwx"               {[250 249 248 247 246]}                 "five"                   {[250 249 248 247 246]}    
        6 sec             "yzAB"               {[245 244 243 242 241]}                 "six"                    {[245 244 243 242 241]}    
        7 sec             "CDEF"               {[240 239 238 237 236]}                 "seven"                  {[        240 238 236]}    
        8 sec             "GHIJ"               {[235 234 233 232 231]}                 "eight"                  {[        235 233 231]}    
        9 sec             "KLMN"               {[255 255 255 255 255]}                 "nine"                   {[255 255 255 255 255]}