Get Started with A2L Files

This example shows how to access and view information stored in A2L files.

XCP (Universal Measurement and Calibration Protocol) is a network protocol commonly used in the automotive industry for connecting calibration systems to electronic control units (ECUs). The calibration system is commonly referred to as the client and the ECU as the server. XCP enables read and write access to variables and memory contents at runtime.

Entire datasets can be acquired or stimulated synchronous to events triggered by timers or operating conditions. The XCP protocol specification is defined by ASAM (Association for Standardization of Automation and Measuring Systems), and allows for a variety of transport layers such as XCP over CAN or Ethernet.

An A2L file is a structured ASCII text file that contains measurement, calibration, and event definitions used with XCP for acquiring and stimulating data. This example uses an A2L file configured for XCP over Ethernet. An A2L file follows the ASAM MCD-2 MC standard (ASAP2), which defines the description format of internal server variables used in measurement and calibration. The .a2l file extension is an abbreviation of "ASAM MCD-2 MC Language."

Open an A2L File

An A2L file contains measurement, calibration, and event definitions for one or more ECUs. If you intend to read data from or write data directly to memory of an XCP server, a necessary first step is to open the A2L file representing that system. To access an A2L file, create a file object in your MATLAB® session using the xcpA2L function:

a2lfile = xcpA2L("XCPServerSineWaveGenerator.a2l")

a2lfile = 
  A2L with properties:

   File Details
                 FileName: 'XCPServerSineWaveGenerator.a2l'
                 FilePath: '/tmp/Bdoc24a_2528353_1100067/tp38a48925/vnt-ex00266724/XCPServerSineWaveGenerator.a2l'
               ServerName: 'ModuleName'
                 Warnings: [0x0 string]

   Parameter Details
                   Events: {'100 ms'}
                EventInfo: [1x1 xcp.a2l.Event]
             Measurements: {'Sine'  'SineAfterGain'  'SineAfterTable'  'XCPServer_DW.lastCos'  'XCPServer_DW.lastSin'  'XCPServer_DW.systemEnable'}
          MeasurementInfo: [6x1 containers.Map]
          Characteristics: {'Gain'  'ydata'}
       CharacteristicInfo: [2x1 containers.Map]
                 AxisInfo: [1x1 containers.Map]
            RecordLayouts: [4x1 containers.Map]
             CompuMethods: [3x1 containers.Map]
                CompuTabs: [0x1 containers.Map]
               CompuVTabs: [0x1 containers.Map]

   XCP Protocol Details
        ProtocolLayerInfo: [1x1 xcp.a2l.ProtocolLayer]
                  DAQInfo: [1x1 xcp.a2l.DAQ]
    TransportLayerCANInfo: [0x0 xcp.a2l.XCPonCAN]
    TransportLayerUDPInfo: [0x0 xcp.a2l.XCPonIP]
    TransportLayerTCPInfo: [1x1 xcp.a2l.XCPonIP]

a2lfile = 
  A2L with properties:

   File Details
                 FileName: 'XCPServerSineWaveGenerator.a2l'
                 FilePath: 'C:\examplefiles\XCPServerSineWaveGenerator.a2l'
               ServerName: 'ModuleName'
                 Warnings: [0×0 string]

   Parameter Details
                   Events: {'100 ms'}
                EventInfo: [1×1 xcp.a2l.Event]
             Measurements: {'Sine'  'SineAfterGain'  'SineAfterTable'  'XCPServer_DW.lastCos'  'XCPServer_DW.lastSin'  'XCPServer_DW.systemEnable'}
          MeasurementInfo: [6×1 containers.Map]
          Characteristics: {'Gain'  'ydata'}
       CharacteristicInfo: [2×1 containers.Map]
                 AxisInfo: [1×1 containers.Map]
            RecordLayouts: [4×1 containers.Map]
             CompuMethods: [3×1 containers.Map]
                CompuTabs: [0×1 containers.Map]
               CompuVTabs: [0×1 containers.Map]

   XCP Protocol Details
        ProtocolLayerInfo: [1×1 xcp.a2l.ProtocolLayer]
                  DAQInfo: [1×1 xcp.a2l.DAQ]
    TransportLayerCANInfo: [0×0 xcp.a2l.XCPonCAN]
    TransportLayerUDPInfo: [0×0 xcp.a2l.XCPonIP]
    TransportLayerTCPInfo: [1×1 xcp.a2l.XCPonIP]

Access Measurement Information

A measurement describes the properties of a recordable, server-internal variable. This variable can be a scalar or an array. Bit masks and bit operations can be applied to the measurement. The address, byte order, computation method, upper and lower limits, and other properties are described. The standard also allows writing to measurement objects to stimulate the server during runtime.

View all available measurements via the Measurements property of the A2L file object.

a2lfile.Measurements

ans = 1x6 cell
    {'Sine'}    {'SineAfterGain'}    {'SineAfterTable'}    {'XCPServer_DW.lastCos'}    {'XCPServer_DW.lastSin'}    {'XCPServer_DW.systemEnable'}

Get information about the Sine measurement using the getMeasurementInfo function. This function returns information about the specified measurement from the specified A2L file.

measInfo = getMeasurementInfo(a2lfile,"Sine")

measInfo = 
  Measurement with properties:
                   Name: 'Sine'
         LongIdentifier: 'Sine wave signal'
            LocDataType: FLOAT64_IEEE
             Conversion: [1x1 xcp.a2l.CompuMethod]
             Resolution: 0
               Accuracy: 0
             LowerLimit: -3.0000
             UpperLimit: 3.0000
              Dimension: 1
              ArraySize: []
                BitMask: []
           BitOperation: [1x0 xcp.a2l.BitOperation]
              ByteOrder: MSB_LAST
               Discrete: []
             ECUAddress: 1586712
    ECUAddressExtension: 0
                 Format: ''
                 Layout: ROW_DIR
               PhysUnit: ''
              ReadWrite: []

Using an xcpChannel you can read and write measurement data directly to memory of an XCP server with the readMeasurement and writeMeasurement functions, respectively. The readMeasurement function reads and scales a value for the specified measurement through the XCP channel object. This action performs a direct read from memory of the server. The writeMeasurement function scales and writes a value for the specified measurement through the XCP channel object. This action performs a direct write to memory of the server.

Access Characteristic Information

A characteristic describes the properties of a tunable parameter (Calibration). Possible types of tunable parameters include scalars, strings, and lookup tables. The address, record layout, computation method, upper and lower calibration limits are defined.

View all available characteristics by name via the Characteristics property of the A2L file object.

a2lfile.Characteristics

ans = 1x2 cell
    {'Gain'}    {'ydata'}

Get information about the Gain characteristic using the getCharacteristicInfo function. This function returns information about the specified characteristic from the specified A2L file.

charInfo = getCharacteristicInfo(a2lfile,"Gain")

charInfo = 
  Characteristic with properties:
                   Name: 'Gain'
         LongIdentifier: ''
     CharacteristicType: VALUE
             ECUAddress: 549960
                Deposit: [1x1 xcp.a2l.RecordLayout]
                MaxDiff: 0
             Conversion: [1x1 xcp.a2l.CompuMethod]
             LowerLimit: -5.0000
             UpperLimit: 5.0000
              Dimension: 1
         AxisConversion: {1x0 cell}
                BitMask: []
              ByteOrder: MSB_LAST
               Discrete: []
    ECUAddressExtension: 0
                 Format: ''
                 Number: []
               PhysUnit: ''

Using an xcpChannel you can read and write characteristic data directly to memory of an XCP server using the readCharacteristic and writeCharacteristic functions, respectively. The readCharacteristic function reads and scales a value for the specified characteristic through the XCP channel. This action performs a direct read from memory of the server. The writeCharacteristic function scales and writes a value for the specified characteristic through the XCP channel object. This action performs a direct write to memory of the server.

Access Event Information

Data can be acquired or stimulated synchronous to events triggered by timers or operating conditions.

View all available events via the Events property of the A2L file object.

a2lfile.Events

ans = 1x1 cell array
    {'100 ms'}

Get information about the 100 ms event using the getEventInfo function. This function returns information about the specified event from the specified A2L file.

eventInfo = getEventInfo(a2lfile, "100 ms")

eventInfo = 
  Event with properties:
                         Name: '100 ms'
                    ShortName: '100 ms'
                ChannelNumber: 0
                    Direction: DAQ
                   MaxDAQList: 255
             ChannelTimeCycle: 1
              ChannelTimeUnit: 8
              ChannelPriority: 0
    ChannelTimeCycleInSeconds: 0.1000

Using an xcpChannel and specifying an event, you can acquire and stimulate measurements using the available XCP functions, such as readDAQList and writeSTIM. The use of events to acquire measurement data is further explored in the example Read XCP Measurements with Dynamic DAQ Lists.

View Protocol Layer Information

The protocol layer defines some of the core operation and organization of the messaging between the XCP server and client. This includes the sizing and structure of the bytes in XCP command and response messages.

Display protocol layer details via the ProtocolLayerInfo property of the A2L file object.

a2lfile.ProtocolLayerInfo

ans = 
  ProtocolLayer with properties:
                    T1: 1000
                    T2: 200
                    T3: 0
                    T4: 0
                    T5: 0
                    T6: 0
                    T7: 0
                MaxCTO: 255
                MaxDTO: 65532
             ByteOrder: BYTE_ORDER_MSB_LAST
    AddressGranularity: ADDRESS_GRANULARITY_BYTE

View DAQ Information

XCP offers the synchronous data acquisition (DAQ) mode, as described in ASAM MDC-2 MC. DAQ is one of the main XCP services that a server can provide. XCP DAQ events can be defined by the client to trigger the sampling of measurement data. When the algorithm in the server reaches the location of such a sampling event, the server collects the values of the measurement parameters and sends them to the client. Display DAQ details via the DAQInfo property of the A2L file object.

a2lfile.DAQInfo

ans = 
  DAQ with properties:
                    ConfigType: DYNAMIC
                        MaxDAQ: 65535
              MaxEventChannels: 128
                        MinDAQ: 0
              OptimizationType: OPTIMISATION_TYPE_DEFAULT
              AddressExtension: ADDRESS_EXTENSION_FREE
       IdentificationFieldType: IDENTIFICATION_FIELD_TYPE_ABSOLUTE
    GranularityODTEntrySizeDAQ: GRANULARITY_ODT_ENTRY_SIZE_DAQ_BYTE
            MaxODTEntrySizeDAQ: 255
            OverloadIndication: NO_OVERLOAD_INDICATION
       DAQAlternatingSupported: []
            PrescalerSupported: []
               ResumeSupported: []
                          STIM: [1x0 xcp.a2l.STIM]
                     Timestamp: [1x1 xcp.a2l.TimestampSupported]
                        Events: [1x1 xcp.a2l.Event Map]

View Transport Layer Information

The XCP packet is embedded in a frame of the transport layer, which is a packet of the chosen transport protocol. An A2L file provides transport layer information for the supported protocols. If the transport layer information for a particular protocol is empty, the server does not support that transport. The XCP protocol specification allows for a variety of transport layers, such as CAN or Ethernet.

This example uses an A2L file configured for XCP over Ethernet, which requires an IP address and a port. These are specified in the A2L file.

Display transport layer details via the TransportLayerTCPInfo property of the A2L file object.

a2lfile.TransportLayerTCPInfo

ans = 
  XCPonIP with properties:
          CommonParameters: [1x1 xcp.a2l.CommonParameters]
    TransportLayerInstance: ''
                      Port: 17725
                   Address: 2.1307e+09
             AddressString: '127.0.0.1'

Close the A2L File

Close access to the A2L file by clearing its variable from the workspace.

clear a2lfile