%% 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: '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

% 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")

% 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

% 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")

% 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

% 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")

% Using an xcpChannel and specifying an event, you can acquire and stimulate measurements using the available XCP functions, such as readDAQ 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

%
%% 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

%
%% 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

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

clear a2lfile

%
% Copyright 2021 The MathWorks, Inc.
%