Interface Programming between CANape and …kr.vector.com/portal/medien/cmc/application_notes/AN-IMC...Interface Programming between CANape and MATLAB® Version 5.6 2013/04/11 Application
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Interface Programming between CANape and MATLAB®
Version 5.6 2013/04/11
Application Note AN-IMC-1-004 Author(s) Sven Deckardt Restrictions Public Document Abstract The purpose of this application note is to show how MATLAB/Simulink® can be used for
accessing an ECU for measurement and calibration. MATLAB and Simulink are registered trademarks of The MathWorks, Inc.
1.0 Overview The purpose of this application note is to show how MATLAB/Simulink can be used for accessing an ECU for measurement and calibration. This application note explains how to use the interface between MATLAB and CANape and how to program with the CANape API.
This document should be used as a framework which enables the reader to write his own application.
1.1 General Usage of the API CANape contains an interface, called CANape API, which provides services to other programs for accessing an ECU at runtime for measurement and calibration. Its main purpose is to use the functionality of CANape from another program like MATLAB. The CANape API enables the user to access ECUs through CANape. Since version 2.0, it supports the simultaneous usage of more than one ECU.
ECU - Device 1
MATLAB+
Simulink
Data transfer by using the
API
CalculatedData
CANape
CANape API
ECU - Device 2
Figure 1: Normal operation between MATLAB/Simulink, CANape and the ECU
Interface Programming between CANape and MATLAB®
4 Application Note AN-IMC-1-004
2.0 General Preparation This chapter describes the installation/setup process.
2.1 Installation The CANape/MATLAB Interface requires at least the following product versions:
• CANape 6.1 or later • MATLAB 7 Release 14.0 SP3 • WIN 2000/WINXPs
After execution of the SETUP, the CANape/MATLAB Interface files are located in the following directory: $(MATLABROOT)\API-DLL-Interface
Note: After the installation you must add the following path to your MATLAB environment: $(MATLABROOT)\API-DLL-Interface
The sample files are located in the following directory: $(MATLABROOT)\API-DLL-Interface
2.2 CANape If you want to use CANape in the "non-modal" mode, you have to start it with the option –u. This mode allows the simultaneous usage of CANape as the server and the client application (MATLAB).
2.3 MATLAB After the start of MATLAB, the drop-down menu Current Directory must be set to the installation path (e.g. C:\MATLAB6p1\API-DLL-Interface).
Figure 2: MATLAB/Simulink workspace
Interface Programming between CANape and MATLAB®
5 Application Note AN-IMC-1-004
3.0 Using the CANape API in MATLAB
3.1 Measurement Via CANape API The first step is to open a session and to initialize CANape. The second step is to load an A2L file and to configure the measurement. Finally, the measurement must be started. The configured measurement data is transmitted to the application. It is the job of the application to process this data. The measurement can be stopped by the CANape API:
4.1 General The generated MATLAB/CANape Interface DLL contains all necessary functions of the CANape API. These functions are used to control the behavior of CANape. The interface between CANape and MATLAB is referenced in the MEX functions. These MEX functions are responsible for the function calls to the CANape API interface.
Sets the path of the working folder • Double Fifosize
Sets the FIFO buffer size for the measurement • Double Samplesize
Sets the sample buffer size for the measurement • Double TimeOut
Sets the timeout in ms • Double Modalmode
Sets the start mode of CANape Value: Modal mode = 1 non-modal (MATLAB Client and CANape) Modal mode = 0 modal (only MATLAB Client)
Description: The ml_CANapeInit function is used for initializing and starting the CANape runtime environment. The first parameter sets the project path where the A2L file and the other configuration files are located. The FIFO and sample size buffer are used for the measurement buffer. The whole memory is calculated by the following formula.
Size = FIFO * sample
Note: For more information, read the documentation of the CANape API.
• Double canChnl Set the logical communication channel to be used from CANape. Value: channel = 1 – 4 can channel 1-4 channel = 5 TCP/IP channel = 261 FlexRay
Note: If the XCP driver is used, the channel for TCP/IP or UDP has to be set to the value TCP = 255 or UDP = 256 and for FlexRay = 261.
Description: The ml_CANapeCreateModule function is used for creating a new module/device and for loading an ASAP2 file or a DB file. The function configures the logical communication channel which will be used (like CCP: 1-4 = CAN1-CAN4) and the driver type like KWPOnCAN, or CCP. The return value is a two-dimensional array which contains the module handle of the device and if the function is successful.
ReturnValue = z(:,1) // OK = 1, NOK = 0 and fatal error = -1;
ModuleHandle = z(:,2) // Module handle for this device
Interface Programming between CANape and MATLAB®
8 Application Note AN-IMC-1-004
Return: double[0] OK = 1, NOK = 0, fatal error = -1
double[1] Module handle of the device
4.4 ml_CANapeSetTCPOptions
Function: Double ml_CANapeSetTCPOptions(char *ipNumber, short port);
Description:
Note: This function must be called before any of the ml_CANapeInit calls. It will prepare the ASAP3 module for the connection of the ASAP3 CANape Server.
Description: This function is used in the same way as ml_CANapeCreateModule. The difference is only an additional parameter which is responsible for creating a device in the offline or online mode.
Function: Double ml_CANapeOpenAsap2File(char *A2LFilename, short Canchannel);
Note: This function can only be used with an CCP Driver!
Interface Programming between CANape and MATLAB®
9 Application Note AN-IMC-1-004
Parameters: • Char *A2LFilename
Sets the filename of ASAP 2 File
Note: If the ASAP2 file is not located in the project path, the parameter must include the path name and the file name.
• Short Canchannel Sets the channel of the CAN bus to be used
• Value: Canchannel = 1 CAN bus channel 1 Canchannel = 2 CAN bus channel 2
Description: The ml_CANapeOpenAsap2File function is used for loading the ASAP2 file and for creating a new module/device. Additionally the function sets the logical communication channel which will be used by the CCP Driver (like 1-4 = CAN1-CAN4).
Description: The ml_CANapeGetEcuTasks determines the number of available data acquisition tasks and their accessory properties, like task id, task cycle and the description.
Function: Double ml_CANapeCheckFifoBlock(int ModuleNumber, short TaskIndex)
Parameters: • Int ModuleHandle
Identification handle of the device • Short Taskid
Index of the task to query.
Description: Check if data have been lost due to FIFO overrun.
Example: [State] = ml_CANapeCheckFifoBlock(0, 2);
Return: State [0] = Buffer Overrun or fatal error = -1 State [1] = FIFO Error
4.16 ml_CANapeGetCurrentValueMatrix
Function: Double[] ml_CANapeGetCurrentValueMatrix(int ModuleHandle, short Taskindex)
Parameters: • Int ModuleHandle
Identification handle of the device • Short Taskid
Index of the task to query
Description: The ml_CANapeGetCurrentValueMatrix function is used for getting current values and returns the last received values, does not use or affects the FIFO.
Function: Double[] ml_CANapeGetCurrentValues(int ModuleHandle, short Taskindex)
Parameters: • Int ModuleHandle
Identification handle of the device • Short Taskid
Index of the task to query
Description: The ml_CANapeGetCurrentValues function is used for getting current values and returns the last received values, does not use or affects the FIFO. Is the same like ml_CANapeGetCurrentValueMatrix.
This parameter describes the mode of the shutdown of CANape. If the closeMode = 1, CANape is closed otherwise only the connection to CANape is terminated.
Description: The ml_CANapeQuitNonModalMode function terminates the connection to CANape.
Description: The ml_CANapeSetDebugInfo function is used for setting the debug verbosity. If it is set to 1, some message boxes appear with information. If it set to 2, all messages are displayed in the program of DebugView from Sysinternals. This program can be downloaded from www.sysinternals.com. The debug mode is turned off with 0.
Example: ml_CANapeSetDebugInfo(1);
Return: Returns the actual state of the debug info.
4.28 ml_CANapeGetLastError
Function: double ml_CANapeGetLastError(void)
Parameters: • no
Description: This function is used for retrieving error information (error codes) about the previously executed function call.
Example: Errorcode = ml_CANapeGetLastError();
Note: The description of the error values are defined in the CANape API help document (CANapAPI.chm).
A script file name or a single script command • ScriptType
Declares interpretation of parameter ScriptText. If 'ScriptType' is true, parameter 'ScriptText' is interpreted as the file name of the script file to be executed. If 'ScriptType' is false, 'ScriptText' is interpreted as a single script command.
Note: This function should be only used in the non-modal mode. (ml_CANapeInit('c:\',4000,200,100,1)).
Description: This function executes a script file or a single script command.
Return: The return value contains the whole string.
Interface Programming between CANape and MATLAB®
34 Application Note AN-IMC-1-004
6.0 Measurement example The current chapter describes an example of a measurement with the ECU simulation CCPSim from Vector.
6.1 CCPSim The first step is to execute CCPSim. The program is located in the folder ($CANape\ccpsim).
The second step is to execute CCPSim again with other parameters (e.g., CCPSim.exe –dto1 –cto2), for more information type "h".
Note: Please check the configuration settings of the CAN hardware if there is no connection between CANape and CCPSim.
6.2 CANape After the execution of 2 * CCPSim, CANape can be started with the option –u for the non-modal mode. CANape is automatically executed by using the function CANapeInit (see chapter 4.2).
6.3 MATLAB Start MATLAB and change the working directory to the path which was set during the installation (see chapter 2.3) and open the file CCPSIMDaqMehrkanaeleMatrix.m.
Interface Programming between CANape and MATLAB®
35 Application Note AN-IMC-1-004
The following window appears:
Figure 6: Script example (measurement DAQ)
Start the program by clicking the button (for more information, see the MATLAB help). The program starts CANape, initializes and sets the project folder. The next instructions load the A2L files and configure the CAN channel. The other two statements are used for the configuration of the measurement (for more details see chapter 4.11). If the configuration of the data acquisition has been successful, the measurement is started with the instruction ml_CANapeStartMeasurement.
Interface Programming between CANape and MATLAB®
36 Application Note AN-IMC-1-004
The data acquisition starts and with the function ml_CANapeGetCurrentValueMatrix the records are returned to the specified parameters (data, time). The plot command from MATLAB displays the whole measurement data.
Figure 7: Plot window
With the function ml_CANapeStopMeasurement the measurement is stopped. The function ml_CANapeExit terminates CANape and closes all windows of CANape.
Interface Programming between CANape and MATLAB®
37 Application Note AN-IMC-1-004
7.0 Calibration example This example describes a configuration for calibration with the ECU simulation CCPSim from Vector.
7.1 CCPSim The first step is to execute CCPSim. The program is located in the folder ($CANape\ccpsim).
Note: Please check the configuration settings of the CAN hardware whether there is any connection between CANape and CCPSim.
7.2 CANape After the execution of CCPSim, CANape can be started with the option –u for the non-modal mode. CANape is automatically executed by using the function CANapeInit (see chapter 4.2).
Interface Programming between CANape and MATLAB®
38 Application Note AN-IMC-1-004
8.0 MATLAB
8.1 Read Calibration Start MATLAB and change the working directory to the path which has been set during the installation (see chapter 2.3) and open the file CCPSIMCalibrationMap.m.
The following window appears:
Figure 8: Script example calibration (read)
Start the program by clicking the button (for more information see MATLAB help). The program starts CANape, initializes and sets the project folder. The next instruction loads the A2L file and configures the CAN channel. The calibration starts with the instruction ml_CANapeReadCalibrationObject. This example loads the calibration data from the map KF2 and the other three commands from MATLAB display the following window:
Interface Programming between CANape and MATLAB®
39 Application Note AN-IMC-1-004
Figure 9: 3-D model
Interface Programming between CANape and MATLAB®
40 Application Note AN-IMC-1-004
8.2 Write Calibration Open the M-File CCPSIMWriteCalibrationMap.m with the MATLAB editor.
Figure 10: Script example calibration (write)
Start the script by clicking the run button. The script starts CANape, loads the ASAP file, and connects to the CCPSim ECU simulator.
Interface Programming between CANape and MATLAB®
41 Application Note AN-IMC-1-004
The next instruction creates a data matrix like this:
After the creation of the matrix, the function ml_CanapeWriteCalibrationObject writes all of the values to the map "map4_80_uc".
Interface Programming between CANape and MATLAB®
42 Application Note AN-IMC-1-004
9.0 Database Example The current chapter describes an example to determine the names of database objects with the ECU simulation CCPSim from Vector.
9.1 Read all Objects Start MATLAB and change the working directory to the path which has been set during the installation (see chapter 2.3) and open the file CCPSIMDBListAllNames.m.
The following window appears:
Figure 11: Script example to read database objects
Interface Programming between CANape and MATLAB®
43 Application Note AN-IMC-1-004
Start the program by clicking the button (for more information see MATLAB help). The program starts CANape, initializes and sets the project folder. The next instruction loads the A2L file and configures the CAN channel. With the instruction ml_CCPSIMDBListAllNames it is possible to determine all of the database objects. This example loads the database names from the CCPSim.a2l file. The other command from MATLAB displays the whole list in the command window.
Figure 12: Example output
Interface Programming between CANape and MATLAB®
44 Application Note AN-IMC-1-004
10.0 ECU Example Start MATLAB and change the working directory to the path which has been set during the installation (see chapter 2.3) and open the file CCPSIMECUTasksListAll.m.
Figure 13: Script example to read database objects
Start the program by clicking the button (for more information see MATLAB help). The program starts CANape, initializes and sets the project folder. The next instruction loads the A2L file and configures the CAN channel. With the instruction ml_GetEcuTasksAllInfos it is possible to determine all tasks of the ECU. This example loads the database names from the CCPSim.a2l file. The other command from MATLAB displays the whole list in the command window.
Interface Programming between CANape and MATLAB®
45 Application Note AN-IMC-1-004
Figure 14: Example output
The interpretation of the list:
Index Task ID Rate Name
0 1 0 = Event polling
1 3 0 Cyclic
2 10 10 = Time in ms 10 ms
3 11 100 100 ms
4 12 0 Key_T
Table 8: Task ID matrix
Interface Programming between CANape and MATLAB®
46 Application Note AN-IMC-1-004
11.0 Contacts
Germany and all countries not named below: Vector Informatik GmbH Ingersheimer Str. 24 70499 Stuttgart GERMANY Phone: +49 711-80670-0 Fax: +49 711-80670-111 E-mail: [email protected]
France, Belgium, Luxemburg: Vector France S.A.S. 168, Boulevard Camélinat 92240 Malakoff FRANCE Phone: +33 1 42 31 40 00 Fax: +33 1 42 31 40 09 E-mail: [email protected]
Sweden, Denmark, Norway, Finland, Iceland: VecScan AB Theres Svenssons Gata 9 41755 Göteborg SWEDEN Phone: +46 31 764 76 00 Fax: +46 31 764 76 19 E-mail: [email protected]
United Kingdom, Ireland: Vector GB Ltd. Rhodium, Central Boulevard Blythe Valley Park Solihull, Birmingham West Midlands B90 8AS UNITED KINGDOM Phone: +44 121 50681-50 Fax: +44 121 50681-69 E-mail: [email protected]
India: Vector Informatik India Pvt. Ltd. 4/1/1/1, Sutar Icon, Sus Road, Pashan, Pune - 411 021 INDIA Phone: +91 20 2587 2023 Fax: +91 20 2587 2025 E-mail: [email protected]
USA, Canada, Mexico: Vector CANtech, Inc. 39500 Orchard Hill Place, Suite 550 Novi, MI 48375 USA Phone: +1 248 449 9290 Fax: +1 248 449 9704 E-mail: [email protected]
Japan: Vector Japan Co. Ltd. Tennozu Yusen Bldg. 16F 2-2-20 Higashi-shinagawa, Shinagawa-ku, Tokyo 140-0002 JAPAN Phone: +81 3 5769 7800 Fax: +81 3 5769 6975 E-mail: [email protected]
Korea: Vector Korea IT Inc. 5F, Gomoas bldg. 12 Hannam-daero 11-gil, Yongsan-gu Seoul, 140-889 REPUBLIC OF KOREA Phone: +82 2 807 0600 Fax: +82 2 807 0601 E-mail: [email protected]