ECU M&C API Basic Programming Model

ECU Measurement and Calibration Toolkit Help

Edition Date: October 2018

Part Number: 371602T-01

»View Product Info
Download Help (Windows Only)

This topic discusses the programming model of the ECU M&C API.

The following figure illustrates the process to initiate communication to an ECU with the ECU M&C Channel functions. A description of each step in the decision process follows the flowchart.

flowchart

ECU Open

The ECU Open function combines the opening of a selected ASAM MCD 2MC database file with the .A2L file extension and the selection of a stored ECU name. The required parameters are the ASAM MCD 2MC database path and filename, and the dedicated CAN interface if you are using XCP or CCP with CAN. The CAN interface is used for communication with the ECU. If you are using XCP with UDP or TCP, a port number and IP address or hostname must be defined in the A2L database.

The function to open and select an ECU is MC ECU Open.vi in LabVIEW or mcDatabaseOpen followed by mcECUSelect in C.

Note Note  The import of ASAM MCD 2MC database files into MAX is not supported.

ASAM MCD 2MC Communication Properties for XCP or CCP with CAN

If your ASAM MCD 2MC database file already contains communication properties, you can directly open the communication to your selected ECU.

If the communication properties are not stored in the ASAM MCD 2MC file, the communication properties must be manually set. To establish communication through XCP or CCP with CAN, the target ECU slave should be addressed by setting the following properties.

CRO ID

The CRO ID (Command Receive Object) is used to send commands and data from the host to the slave device.

DTO ID

The DTO ID (Data Transmission Object) is used by the ECU to respond to CCP commands, and to send data and status information to the CCP master.

Station Address

CCP is based on the idea that several ECUs can share the same CAN Arbitration IDs for CCP communication. To avoid communication conflicts, CCP defines a Station Address that has to be unique for all ECUs sharing the same CAN Arbitration IDs. Unless an ECU has been addressed by its Station Address, the ECU must not react to CCP commands sent by the CCP master.

Baudrate

The baudrate property may be missing in an A2L database file and can be set explicitly within the application. This property provides the baud rate at which communication will occur, and applies to all tasks initialized with the interface. You can specify one of the predefined baud rates, or specify advanced baud rates which refer to the settings of the Bit Timing Register 0 (BTR0) and 1 (BTR1). For more information, refer to the Interface Properties dialog in MAX, or the NI-CAN Hardware and Software Manual. The baud rate is originally set within MAX.

ASAM MCD 2MC Communication Properties for XCP with UDP or TCP

If the XCP communication properties are not stored in the ASAM MCD 2MC file, the communication properties must be manually set. To establish communication through XCP with UDP or TCP the target ECU slave should be addressed by setting the following properties.

IP Address or hostname

The IP address refers to the identifier for a computer or device on a TCP/IP network. Networks using the TCP/IP protocol route messages based on the IP address of the destination.

A hostname describes the unique name by which a device is known on a network. Hostnames are used by various naming systems: NIS, DNS, SMB, etc. Hostnames are high-level aliases which ultimately correlate to unique network hardware MAC addresses.

Port number

In TCP/IP and UDP networks, a port is an end-point to a logical connection through which a client program specifies a server program on a computer in a network. Port numbers range from 0 to 65536, but only port numbers 0 to 1024 are reserved for privileged services and designated as well-known ports.

ECU Connect

The ECU Connect function establishes communication to the selected ECU through CCP using the CCP CONNECT command or through XCP using the CONNECT command. It establishes a logical connection to an ECU. Unless a slave device (ECU) is unconnected, it must not execute or respond to any command sent by the application. The only exception to this rule is the Test command, in which case the slave with the specified address may acknowledge the command. After a successful ECU Connect you can create a Measurement Task or read/write a Characteristic.

The function to open and select an ECU is MC ECU Connect.vi in LabVIEW and mcECUConnect in C.

ECU Disconnect

The ECU Disconnect function permanently disconnects the specified CCP slave and ends the measurement and calibration session. When the measurement and calibration session is terminated, all CCP DAQ lists for the device is stopped and cleared, and the protection masks of the device are set to their default values.

The function to disconnect an ECU is MC ECU Disconnect.vi in LabVIEW or mcECUDisconnect in C.

ECU Close

The MC ECU Close function deselects the ECU and closes the remaining database reference handle. MC ECU Close must always be the final ECU M&C function call. If you do not use MC ECU Close, the remaining task configurations can cause problems in the execution of subsequent ECU M&C applications.

The function to close an ECU is MC ECU Close.vi in LabVIEW. To deselect the ECU and close the database reference handle in C, call the function mcECUDeselect followed by mcDatabaseClose.

Characteristic Read and Write

Access Characteristics

To access the Characteristics of an ECU you must select and connect to the specified ECU through the procedure given above. The function to open and select an ECU is MC ECU Open.vi in LabVIEW, or mcDatabaseOpen followed by mcECUSelectEx in C. Once the ECU has been connected an ECU Reference handle (ECU ref out in LabVIEW, ECURefNum in C) must be acquired before any additional actions can be performed.

Characteristic Read

The application must call the Read Characteristic function to obtain scaled floating point samples. The application typically calls Read Characteristic on demand. Calling Read Characteristic in a loop can cause significant CAN network traffic, as Characteristics may contain large amounts of data.

The function to read 0- to 2-dimensional Characteristics is MC Characteristic Read.vi in LabVIEW or mcCharacteristicRead in C. The function to read single double values as Characteristics is MC Characteristic Read Single Value.vi in LabVIEW or mcCharacteristicReadSingleValue in C.

Before reading a Characteristic, it may be helpful to verify the dimension of the Characteristic based on the definition in the ASAM MCD 2MC database file. Depending on the dimension of the Characteristic, use the appropriate Read function for reading a double, a 1D array of doubles, or a 2D array of doubles.

The function to verify a dimension of a named Characteristic is MC Get Property.vi with the parameter Characteristic/Dimension in LabVIEW or mcGetProperty with the parameter mcPropChar_Dimension in C.

Characteristic Write

The application must call the Write Characteristic function to output scaled floating-point samples. The application typically calls Write Characteristic on demand. Calling Write Characteristic in a loop can cause significant network traffic, as Characteristics may contain large amounts of data.

The function to write a Characteristic is MC Characteristic Write.vi in LabVIEW or mcCharacteristicWrite in C.

Before writing a Characteristic, it may be helpful to verify the dimension of the Characteristic based on the definition in the ASAM MCD 2MC database file. Depending on the dimension of the Characteristic, use the appropriate Write function for writing a double, a 1D array of doubles, or a 2D array of doubles.

The function to verify a dimension of a named Characteristic is MC Get Property.vi with the parameter Characteristic/Dimension in LabVIEW or mcGetProperty with the parameter mcPropChar_Dimension in C.

Measurement Task

To create a Measurement task you need to select available Measurement signals from an ASAM MCD 2MC database file. Create a valid ECU Reference handle as described in the Access Characteristics section.

The following figure shows the process to perform an ECU Measurement task. A description of each step in the decision process follows the flowchart.

flowchart

DAQ Initialize

The DAQ Initialize function initializes a list of Measurement channels as a single Measurement task. The communication for that Measurement task is started by the first DAQ Read function. The DAQ Initialize function is MC DAQ Initialize.vi in LabVIEW or mcDAQInitialize in other languages.

The DAQ Initialize function uses the following input parameters:

Measurement list

Specifies the list of channels for the task with one string for each channel.

ECU Reference handle

Typically, the ECU Reference handle is created by opening the ASAM MCD 2MC database using the ECU Open function, then connecting to an ECU using the ECU Connect function.

Mode

Specifies the input mode to use for the task. This determines the data transfer for the task (Polling, DAQ list, or STIM list).

SampleRate

Specifies the sampling rate for a specific DAQ list or STIM list. The sample rate is specified in Hertz (samples per second). For more information, refer to the DAQ Read section.

DTO ID

If you are using the CCP protocol, the DTO ID (Data Transmission Object) is used by the ECU to respond to CCP commands, and to send data and status information to the CCP master.

DAQ Start Stop

The optional function DAQ Start Stop starts or stops the transmission of the DAQ lists for an ECU M&C Measurement task. If you do not specify MC DAQ Start Stop.vi before your first DAQ Read or DAQ Write function, MC DAQ Start Stop is implicitly performed by the first DAQ Read or DAQ Write call. After you start the transmission of the DAQ lists or STIM lists, you can no longer change the configuration of the Measurement task with Set Property. DAQ Start Stop is implicitly performed by DAQ Clear to stop the transmission of the DAQ lists.

The function to start a DAQ List is MC DAQ Start Stop.vi in LabVIEW or mcDAQStartStop in C.

DAQ Read

The application must call the DAQ Read function to obtain floating-point samples. The application typically calls DAQ Read in a loop until done. The Read function is MC DAQ Read.vi in LabVIEW (all types that don't end in Time & Dbl) or mcDAQRead in other languages.

The behavior of Read depends on the initialized sample rate and the selected mode.

sample rate = 0

DAQ Read returns a single sample from the most recent message(s) received from the network. One sample is returned for every channel in the DAQ Initialize list.

The following figure shows an example of DAQ Read with a sample rate = 0. A, B, and C represent messages for the initialized channels. def represents the default value 0. If no message is received after the start of the application, the default value 0 is returned along with a warning.

example

Sample Rate = 0

sample rate > 0

DAQ Read returns an array of samples for every channel in the DAQ Initialize list. Each time the clock ticks at the specified rate, a sample from the most recent message(s) is inserted into the arrays. In other words, the samples are repeated in the array at the specified rate until a new message is received. By using the same sample rate with NI-DAQ Analog Input channels or NI-DAQmx Analog Input channels, you can compare ECU DAQ and NI-DAQ/NI-DAQmx samples over time.

The following figure shows an example of DAQ Read with a sample rate > 0. A, B, and C represent messages for the initialized channels. delta-t represents the time between samples as specified by the sample rate. def represents the default value 0.

example

sample rate > 0

DAQ Write

If you are using XCP and the DAQ initialize mode is set to STIM list the application must call the DAQ Write function to output floating-point samples. The application typically calls DAQ Write in a loop until done. The DAQ Write function is MC DAQ Write.vi in LabVIEW or mcDAQWrite in other languages.

DAQ Clear

DAQ Clear must always be the final function called for a specific Measurement task. If you do not use DAQ Clear, the remaining Measurement task configuration can cause problems in the execution of subsequent ECU M&C applications. Because this function clears the Measurement task, the Measurement task reference is transferred into an ECU reference task handle. To change the properties of a running Measurement task, use DAQ Start Stop to stop the task, Set Property to change the desired DAQ property, then DAQ Start Stop to restart the Measurement task again.

The function to clear a DAQ list is MC DAQ Clear.vi in LabVIEW or mcDAQClear in C.

WAS THIS ARTICLE HELPFUL?

Not Helpful