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/Bdoc24b_2679053_3932096/tp5211b350/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]
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