You are on page 1of 74

INCA-MIP V5.

4
User’s Guide

Copyright
The information in this document may not be altered or amended without
special notification from ETAS GmbH. ETAS GmbH undertakes no further obligation in relation to this document. The software presented herein is provided
on the basis of a general license agreement or a single license. Using and copying this document is allowed only in accordance with the stipulations specified
in this contract.
Under no circumstances may any part of this document be copied, reproduced, stored in a retrieval system or translated into another language without
the express written permission of ETAS GmbH.
© Copyright 2006 ETAS GmbH, Stuttgart, Germany
The names and designations used in this document are trademarks or brands
belonging to the respective owners.
Document AM010101 R5.4.1 EN

2

Contents
1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 About this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 INCA Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7
8
8
9

2

Installing the INCA-MIP Add-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Installing INCA-MIP from CD-ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Updating the Cache for MATLAB Toolbox directories . . . . . . . . . . . . . . . .
2.4 Disabling the Cache for MATLAB Toolbox Directories . . . . . . . . . . . . . . . .

3

Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4

The API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1 Getting to know the INCA-MIP API through Sample Files . . . . . . . . . . . . . 24
4.2 General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.2.1
List INCA-MIP Interface Message IDs. . . . . . . . . . . . . . . . . . . . . 26
4.2.2
Show Messages During Script Execution . . . . . . . . . . . . . . . . . . 27
4.2.3
Show whether Valid License exists . . . . . . (INCA-MIP Extended)28
4.2.4
Read INCA Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.5
Read INCA Properties . . . . . . . . . . . . . . . . (INCA-MIP Extended)28

13
13
13
15
16

Contents

3

. . . . . . . .3 Add Measurement Variable to Measure Raster . . . . .3. .2 Read Measure Rasters. . . . . . . . . . . . . . . . . . . . . . . (INCA-MIP Extended)43 4. . . . . . . . . . . . . . . . . . .1 Read Calibration Elements . . . . . . . . . . . . 47 4. . 61 4. . . .3 Import a Database . . . . . . .10 Set Data Reading Mode (Online / Offline Data) . . . . . . . . . .3. . . . (INCA-MIP Extended)47 4. . . . . . . . . . (INCA-MIP Extended)41 4. . .3. . . . . . . .5 Stop Measurement . (INCA-MIP Extended)60 Memory Page Manager . . . . . .4. . . 30 4. . . . . . . . . .17 Read List of Measurement Variables . . . . .4. . . . . . . . . . . . 38 4.5. . . . . . . . . (INCA-MIP Extended)59 4. . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Write DCM File. . .1 Open INCA. . . . . . . . . . . . . . . . . .6 4 Contents Initialization . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . 52 4. . (INCA-MIP Extended)58 4. .5. . . . . . (INCA-MIP Extended)36 Measuring and Recording . . . . . . . . . . . . . . (INCA-MIP Extended)39 4. . . . . . . . . . (INCA-MIP Extended)58 4. . . .3 4. . . . 44 4. . .4. . . . . . . . . 52 4. . .3. . . . . . .2 Open a Database . . . 40 4. . . . . . . . . . . . . . . (INCA-MIP Extended)51 4. . . .5 4. . . . .8 Group Devices . . . .4. . . . .5. . . . .11 Read Measure Data .16 Read Recording State . . . . . . . . (INCA-MIP Extended)31 4. . . . . . . . . .1 Activate Memory Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Open an Experiment. . . . . . . . . . . . . . . . . .7 Set Calibration Mode . . . . . . . . . . . . . . . . . . . .4. . . . . (INCA-MIP Extended)38 4. . . . . . . . . . . . . . . . .4. . . . . . . . . .12 Reset Ring Buffer . . . . . . .3 Read Calibration Value . . . . . . . . . . . . . . . 35 4. . . . . . . . . 45 4. . . .1 Read Measurement Elements . . . . . . . . .4. . . . . . . . . . . . . . . . . .6 Read Recording Properties . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . .4 Start Measurement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 Execute Manual Trigger . . . . . . . . . . .14 Set Trigger . . . . . . 31 4. . . .5 Assign Project and Dataset in Device. . . . . . .6. . . . . .7 Set Recording Properties . . .4 Read Database Items . . .5. . . . . . . .8 Read Devices . . . . . . . . . . . . . . . .9 Stop Recording. . . .8 Start Recording. . . . . . . . . . . . . . . . . . . . 34 4. . . . . . . . . . . . . . . . . . . (INCA-MIP Extended)33 4. . . . . . . (INCA-MIP Extended)35 4. . . .4. . . . . .4.4. .5. . . . . . . . . 40 4. . . . . . . .4. . . . . .4 Change Calibration Value . . . . . . . . . (INCA-MIP Extended)49 4. .3. . . . . . . . . .13 Read Hardware Status .4. . 46 4. . . . . .5. . . . . . .9 Read Device Properties . . . . .7 Reset an Experiment .3. .5. . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4. 51 4.6 List Datasets of a Device . . . . . . . . . . . . . . . . (INCA-MIP Extended)48 4. . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . .2 Add Calibration Element. 39 4. . .5. . . . . . . . .3. . . . . . . . . . . . . . . . . (INCA-MIP Extended)49 4. . . . .3. . . . . . . . . . 61 . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . (INCA-MIP Extended)57 4. . . . . (INCA-MIP Extended)50 Calibrating . . . . . . . . . . .4 4. 30 4. . . 55 4.5 Assign Dataset to Device . . . . . . . . . . . . . (INCA-MIP Extended)32 4.4. . . . . . . . .

. . . . . . . . . . 73 Contents 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5 Creation and Distribution of Stand-alone Executable Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 5. . . . . . . . . . . . . . . . .7 Upload Pages . . . . . . . . . . . . . . . . . . . . . . . . . .4 Download Memory Page . . . . . . . .6. . . . . . . . . (INCA-MIP Extended)61 4. . . . . . . .7 4. . . . . . . . . . . . . . .2 Get Current Page . . . . . . . . . . . . . . . . . . . . . .6. . . . . 63 4. . . . . . . . 69 7 ETAS Contact Addresses . . . . . . . . . . . . . . . . . . . . .3 Check Write-Protection . . . . . 62 4. . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Index . . .6. . . . . . . .5 Copy Memory Page . .6. . . . .6. . . . . . . . . . . . . . . . . . .2 Distribution of Stand-alone Executable Files . 68 6 Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4. . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . . 67 5. . . . . .6 Download Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Compilation of m-Files containing MATLAB API Functions . . . 62 4. . . . . (INCA-MIP Extended)63 Application Examples . . .

6 Contents .

Introduction 7 . MATLAB as client read measure data INCA ETK as server on ECU write calibration data The following overview outlines the INCA functionality that can be accessed from within MATLAB. The following chart illustrates a typical application for the INCA-MIP API. Since INCA generates measurement and calibration variables as doubles. which can be used to define the entire control flow for INCA experiments. which in this case is the server. Memory Page Management Switching back and forth between memory pages and downloading memory pages to the control unit are supported. Within this context. The values can be read and updated for each element and for the associated break point distributions. MATLAB acts as a client accessing INCA's resources. Measuring All measurement variables from an INCA experiment can be read. Calibrating All the calibration variables for an INCA experiment can be modified. using INCA to address an ETK. In addition. All performance data that are available in INCA can also be accessed from MATLAB. The performance data throughput at the INCA-MIP interface has been optimized. The INCA API functions described in this document are invoked from MATLAB scripts (so-called M files). where applicable. conversion formulas for reprocessing in MATLAB are not required.1 Introduction The INCA-MIP Add-On (INCA MATLAB Integration Package) is an application programming interface that controls INCA's functionality from within MATLAB. measurements can be started and stopped from within MATLAB.

Possible settings: • v: value • x: x break point (curves and maps • y: y break point (maps) . it must match the data types specified below: • Scalars: a (1. size} {. Parentheses are used for the functions argument. braces for the optional input arguments.1.2 Typographic Conventions This manual uses the following conventions to describe the API functions in addition to the usual typographic conventions found in the INCA User Manual: The name of the API function is written in a non-proportional font. start. You should also be familiar with using scripts in MATLAB. Example: Reading a Calibration Variable value = IncaGetCalibrationValue(deviceName.1)-matrix Input Arguments: deviceName name of the device calibrationName the name of the calibration element valueType 8 Introduction Selection of the output argument (string). To use the INCA-MIP API.1) matrix • Curves: an (x. calibrationName {.1) matrix • Maps: an (x.y) matrix • Break point distributions: an (x.1 About this Manual The following sections describe the underlying architecture for the INCA-MIP API and the available API functions as well as the installation procedures. 1. you should be familiar with both INCA and MATLAB. The function either returns the value of the calibration variable (default) or the X. valueType}) Output Arguments: value Current value of the calibration variable. MATLAB or INCA operation falls outside the scope of this manual.and Y-break point distribution.

For example. Device A measuring device used for capturing measurement variables within a certain measurement grid. ’Map’.3 INCA Glossary The API description uses certain technical terms that experienced INCA users should be familiar with. These values have to be enclosed in “’ ’”. Calibration Variable A calibration variable is an element that can be read and modified. curves and maps. while the ETK is suitable both for measurements and calibrations. 1. The associated break point distributions can also be read and modified. matrices. Measurement Raster Acquisition rate (measuring frequency) used for measuring one or more signals in a signal group. Calibration variables can be scalars. The measurement data for a signal group consists of several records that are generated throughout the entire measurement process. Measure Data All the records captured in one measurement for individual measure rasters. vectors. Below is a brief definition of these terms. Some measuring devices also support calibration for corresponding variables. SMB devices can be used for measurements only. Introduction 9 . ’y’). x and y in non-proportional font represent the possible values that can be generated. Data record A record consists of a time stamp and all the measurement values in a signal group for a single acquisition. Example: yMap = IncaGetCalibrationValue(’anEtk’.The values v.

All data already saved in the ring buffer will get lost: INCA Data Acquisition INCA Data Acquisition MATLAB Interface IncaResetRecords 10 Introduction . During an INCA online visualization or recording the acquired measurement data is automatically saved in the ring buffer. With the command IncaResetRecords the time stamps and data in the ring buffer for all measurement rasters can be cleared. Typically this will be done about once each second. a dedicated ring buffer is used for each measurement raster (signal group). After this time old measurement data will get overwritten.Ring Buffer To ensure a reliable transfer of measurement data from INCA to MATLAB. The command IncaGetRecords can be used to read the time stamps and data from the ring buffer into MATLAB: INCA Data Acquisition INCA Data Acquisition MATLAB Interface IncaGetRecords Independent of the measurement rate the ring buffer can hold up to approximately 30 seconds of measurement data. To avoid losing data IncaGetRecords periodically has to be executed.

4 or 8 bytes) and conversion formula. It is characterized by its measurement raster. Each signal is characterized by its data type (Boolean. integer. length (1. The conversion from the physical measure value on the implementation level is specified in the conversion formula. Signal Group A signal group consists of several individual signals. Introduction 11 .Signal A signal is an element whose value is measured in INCA. 2. float). which is the same for all signals in the signal group. Each signal group has a unique name.

12 Introduction .

The INCA-MIP API consists of a collection of MEX files that are copied into the associated sub-directories of your MATLAB program directory during installation. to communicate with other applications. INCA must be installed on your computer. Please refer to the INCA Getting Started manual for the INCA system requirements. • Installation into ETASData Select this option if you would just like to run compiled MATLAB scripts or if you would like to use INCA-MIP with different MATLAB versions on your PC. so-called MEX files. Installing the INCA-MIP Add-on 13 . MATLAB uses dynamically linked function calls. For a more detailed description see below on page 14. A list of APIs and the respective API set can be found in "The API Functions" on page 21. INCA-MIP is packaged in two versions. If you would like to develop MATLAB scripts yourself for accessing INCA. The following types are possible: • MATLAB integrated installation Select this option if you use one MATLAB version for developing MATLAB scripts. In order to use the INCA-MIP Extended API set a software license key is required.1 System Requirements To use the INCA-MIP add-on.4 requires the following program releases: 2.4 or higher • MATLAB V6. The INCA-MIP Base API set is readily available after the installation. To install INCA-MIP: • Make sure that INCA is installed on your computer and that the release number of the INCA installation is compatible with the release number of the INCA-MIP add-on package.0 or higher (for MATLAB integrated installation) Installing INCA-MIP from CD-ROM Before installing the add-on it is necessary to determine the type of installation.2 • INCA V5.2 Installing the INCA-MIP Add-on INCA-MIP is a functional extension of INCA. you also need a full MATLAB license. 2. INCA-MIP V5.

• If the installation routine does not start automatically. or • 14 Installing the INCA-MIP Add-on Select the option Installation into ETASData if one of the following cases applies: . make sure that MATLAB is installed on your computer and that the release number of the MATLAB installation is compatible with the release number of the INCA-MIP add-on package • Close all active programs. • Follow the instructions in the installation routine to install INCA-MIP on your computer. execute the INCA-MIP. In the installation routine.exe program on the CD manually. you are asked to indicate the desired type of installation: • If you would like to develop MATLAB scripts with exactly one MATLAB version installed on your PC select the option MATLAB integrated installation.• If you would like to develop your own MATLAB scripts for accessing INCA. • Insert the CD with the installation program into the CD-ROM drive of your computer.

See your MATLAB user documentation on how to add directories to the MATLAB path. 2. For a description of how to license your installation of INCA-MIP Extended please refer to "Licensing" on page 17. Note You need the installation into ETASData if you use executable files that contain MATLAB commands for controlling INCA. Installing the INCA-MIP Add-on 15 . • Continue with the installation routine. In this case you do not need a MATLAB license. See your MATLAB user documentation to update the cache for the MATLAB toolbox directories. We recommend to obtain the license file prior to installing the product. The executable files have to be provided by developers with a MATLAB installation (see „Creation and Distribution of Stand-alone Executable Files“ on page 67).3 Updating the Cache for MATLAB Toolbox directories After installing the INCA-MIP API. The license is provided by your local tool coordinator or your respective ETAS representative. In this case you must add the INCA-MIP subdirectory to the MATLAB toolbox directory of each MATLAB installation on your PC before you can use INCA-MIP commands. you should first update the cache for the MATLAB toolbox directories.– You would like to use INCA-MIP with different MATLAB versions. Note Should you plan to use the extended set of API functions. – You would only like to run readily available MATLAB R12 or R13 stand-alone executables. a software license file will be required. the cache was disabled in earlier releases. This is true for MATLAB V6 and higher if you are using the default settings. The cache needs to be updated so that the files used in INCA-MIP API are registered in MATLAB. in case this cache is enabled during your MATLAB installation.

See your MATLAB user documentation for enabling or disabling the cache for the MATLAB toolbox directories. As an alternative to disabling the caching. it is recommended that you disable the cache while working with the INCA-MIP API. malfunctions may occur because either the INCA-MIP API or individual. to avoid any faulty operation. 16 Installing the INCA-MIP Add-on . However. it is recommended that you disable caching for the MATLAB toolbox directories. newly added script files may not be found. Otherwise. you can force the cache to update as described above while the cache is enabled.4 Disabling the Cache for MATLAB Toolbox Directories When working with the INCA-MIP API.2.

The license file can be obtained from ETAS. • In the Windows start menu. In order to work with INCA-MIP Extended. The "Obtain License Info" window opens. To obtain the license file: The license is tied to username and workstation. select the INCA folder of the current INCA version. Note If you would like to request the license file before installing INCA-MIP . you can only use the API functions which are included in the INCA-MIP Base package. after the installation. It shows the MAC and IP addresses for each network board of your computer. Without this file.exe from the product CD-ROM. To obtain the information required for the creation of the license file. you need a license file for your computer. you can start the program LicenseInfo.3 Licensing INCA-MIP Extended is subject to license management. • In the INCA folder. select LicenseInfo. Licensing 17 . but not the extended function range. use the LicenseInfo tool in the INCA program group.

You find the required license number on the license contract. license number. Otherwise. Send the completed text file to ETAS. Besides your host ID and user name. The file is created and opened in a text editor.• Select one of the listed Ethernet adapters and click on Get License Info. it contains input lines for your E-mail address. 18 Licensing . enter path and name for the text file. Note The license file must not be edited. and other specifications. it becomes invalid. • • Close the "Obtain License Info" window. • Click on Save. • Click OK to store the information in a text file. therefore you only have to enter the INCA-MIP Extended license number. • In the file selection dialog window. as well as the ETAS contact addresses. ETAS will send you the license file with the required license key for your computer. INCA itself is not subject to license management. The information about your computer required by ETAS to create a license file are collected and displayed in the "License Info" window.

however. to modify the license file directory by modifying the environment variable ETAS_LICENSE_FILE. In this directory. By default this is the directory ETAS\ETASShared6\Licenses. the license file is recognized automatically when you start the program. It is possible. Licensing 19 .• Store the license file in the installation directory intended for that purpose.

20 Licensing .

Should you use an Extended API function without a valid software license. • whether the function is used for initialization.4 The API Functions INCA-MIP provides a number of API functions for automating INCA processes. memory page management or whether it is a more general function. The following table lists all INCA-MIP API functions which are available in the add-on for INCA V5.b Category refer to IncaAddCalibrationElement x x Calibration page 52 IncaAddMeasureElement x x Measuring page 39 IncaBrowseCalibrationEleme nts x Calibration page 51 IncaBrowseItemsInFolder x Initialization page 32 IncaBrowseMeasureElements x Measuring page 38 x MemoryPageManager page 62 x Initialization IncaCopyPageFromTo x IncaDatabaseImport page 31 IncaDownloadDifferences x x MemoryPageManager page 63 IncaDownloadPage x x MemoryPageManager page 62 x Measuring page 49 x Calibration page 52 IncaExecuteManualTrigger IncaGetCalibrationValue x The API Functions 21 .4. Function Basea Ext. It indicates • whether the function is also available in the INCA-MIP Base package or only in the INCA-MIP Extended package. MATLAB script execution will throw an exception. calibrating. • where in this document you can find more information about the corresponding function. As a development guideline we recommend that prior to using INCA-MIP Extended commands. measuring. Some functions are available in the INCA-MIP Base package. Note Commands which are available only through INCA-MIP Extended are protected by a software license key. others can be used only if you have purchased the INCA-MIP Extended package. . you verify the validity of the license by means of the IncaIsLicenseValid command.

Function Basea Ext.b Category IncaGetCurrentPage x MemoryPageManager page 61 IncaGetDatasetsForDevice x Calibration page 58 IncaGetDeviceProperties x Initialization page 36 IncaGetDevices x Initialization page 35 IncaGetHardwareStatus x Measuring page 47 IncaGetMeasureRatesForDevi ce x Measuring page 39 IncaGetProperties x General page 28 IncaGetRecordingProperties x Measuring page 41 IncaGetRecordingState x Measuring page 49 x Measuring page 46 x Measuring page 50 IncaGetRecords x IncaGetRecordStruct IncaGetVersion x General page 28 IncaGroupDevices x x Calibration page 59 IncaIsLicenseValid x General page 28 page 26 IncaMessageIds x x General IncaIsPageWriteProtected x x MemoryPageManager page 62 IncaOpen x x Initialization page 30 IncaOpenDatabase x x Initialization page 31 IncaOpenExperiment x x Initialization page 34 IncaResetExperiment x x Initialization page 35 IncaResetRecords x x Measuring page 47 x Calibration page 58 x x Calibration page 55 x Calibration page 57 x x Measuring page 45 x Initialization page 33 IncaSetCalibrationMode IncaSetCalibrationValue IncaSetDatasetInDevice IncaSetMeasureReadMode IncaSetProjectAndDatasetInD evice IncaSetRecordingProperties x Measuring page 43 IncaSetTrigger x Measuring page 48 x General page 27 IncaShowMessages 22 refer to The API Functions x .

a number of sample files are provided. For further information on INCA User Options please see the INCA Documentation. Application examples are given under "Application Examples" on page 65.b Category refer to IncaStartMeasurement x x Measuring page 40 IncaStartRecording x x Measuring page 44 IncaStopMeasurement x x Measuring page 40 IncaStopRecording x x Measuring page 45 IncaSwitchPage x x MemoryPageManager page 61 IncaUploadPages x MemoryPageManager page 63 IncaWriteToFile x Calibration page 60 a Function is supported in INCA-MIP Base Package b Function is supported in INCA-MIP Extended Package In this manual. These are described under "Getting to know the INCA-MIP API through Sample Files" on page 24. The API Functions 23 . the function descriptions are ordered according to their application area: • "General Functions" on page 26 • "Initialization" on page 30 • "Measuring and Recording" on page 38 • "Calibrating" on page 51 • "Memory Page Manager" on page 61 Moreover. Note The INCA-MIP Interface always operates on the global settings of the INCA User Options.Function Basea Ext.

1 Getting to know the INCA-MIP API through Sample Files INCA-MIP comes with a group of examples. No hardware is required. These sample files are automatically installed on your computer in addition to the MEX files. This function must be used at the start of each MATLAB session before using any other function of the INCA-MIP API. This function can be used both in connection with the VADI and ETK example (for “measure rasters. 24 • tOpen. and modifies the values for individual calibration variables. It also downloads the working and reference pages.” see "INCA Glossary" on page 9. the complete database hierarchy is printed to the standard output. The API Functions .m – opens an empty INCA experiment using a hardware configuration with the VADI test device.m – establishes a connection between INCA and MATLAB. The sample files use several examples to demonstrate the use of the INCA-MIP API. aFileId}}). The script creates several measurement variables in the INCA experiment. The sample files are copied into the following directories during the installation (see „Installing INCA-MIP from CD-ROM“ on page 13): • For installation into MATLAB: M files: %MatlabDir%\toolbox\matlab\demos • For installation into ETASData: M files: %EtasDataDir%\INCA-MIP To use the sample files. you must first start INCA and open the sample database. The function of the M files is described below. This script creates several measurement and calibration variables in the INCA experiment.m – Writes the complete contents of the database beginning with directory aFolder to the file aFileId.) • tPrintDB ({aFolder{. If the function is executed without parameters. The examples include a number of M files that access the INCA-MIP API. • tEtkDummy.4.m – opens an empty INCA experiment using a hardware configuration with the ETK test device.m – gathers the measured data for the aGroupName group for 20 seconds and then passes the data to MATLAB. as well as an INCA database where the elements used in the sample scripts have already been created. • tGetRecords(aGroupName). • tDummy. reads the measurement and calibration variables.

• tHWStatus. It continues with a measurement of 5 minutes.m – Example for using the API function IncaGetHardwareStatus. The API Functions 25 . If there is a warning or error during the measurement the measurement cycle gets aborted and restarted after a delay of 5 seconds. MATLAB attaches to an already opened experiment and chooses the first measurement element found in the first measurement device found.

[msgstr..2 General Functions The following general API functions are available: 4.msgid] = lasterr . <command_1> ... When using try/catch blocks.1 List INCA-MIP Interface Message IDs INCA-MIP Interface commands may return with an error. end whereas: msgstr a descriptional string msgid the message id.. Example try.4. The following message ids are available: • INCA:ParameterError • INCA:ReturnParameterError • INCA:WrongParameterValue • INCA:WrongParameterType • INCA:NaN • INCA:ExecutionError • INCA:ResourceError • INCA:RasterFull • INCA:ObjectIsWriteProtected • INCA:CallSeqenceError • INCA:LicenseError Hints for reaction on error ids: 26 INCA:ParameterError Wrong number of input arguments (right hand side parameters) INCA:ReturnParameterError Wrong number of output arguments (left hand side parameters) The API Functions . detailed error information can be returned. <command_n> catch.2.

IncaOpenExperiment is necessary before IncaAddMeasureElement.2. INCA:ResourceError Unable to get operating system resources.2 INCA:CallSeqenceError Before executing the requested command other commands have to be executed first. INCA:LicenseError To execute the command with the given parameters a license is needed Show Messages During Script Execution Name IncaShowMessages Description Enable/disable the information display in the MATLAB window during script execution Syntax IncaShowMessages(trueOrFalse) Output Arguments The API Functions 27 . Restarting INCA or a reboot could help. Trying to execute functionality on the INCA user interface could give more information about the reason. Restarting INCA or a reboot could also help. INCA:RasterFull The acquisition list is full for the requested measure raster when trying to add a measurement INCA:ObjectIsWriteProtected Unable to calibrate because of a write protected object 4.INCA:WrongParameterValue Any of the values of the input arguments is out of its valid range or specification INCA:WrongParameterType Any of the input arguments has a wrong data type INCA:NaN Any of the parameters contains a 'not a number' value INCA:ExecutionError During the command execution an error occurred for some reason.g. E.

2.2.3 Show whether Valid License exists (INCA-MIP Extended) Name IncaIsLicenseValid Description Return a status indicating whether a valid license is available or not Syntax s = IncaIsLicenseValid Output Arguments s license status: • 0: no valid license • 1: valid license Input Arguments Examples 4.5 28 Read INCA Properties Name IncaGetProperties Description Read properties of INCA Syntax p = IncaGetProperties The API Functions (INCA-MIP Extended) .Input Arguments trueOrFalse Numerical parameter whose value either equals or does not equal zero. otherwise it is enabled (default). the information display is disabled.4 status = IncaIsLicenseValid Read INCA Version Name IncaGetVersion Description Return the INCA version Syntax IncaGetVersion Output Arguments Input Arguments Examples 4. Examples 4.2. If the parameter is zero.

Pathname of the open INCA database.databasePath .Pathname of the directory which is used by ETAS applications for temporary files. • p.dataPath . • p.installationPath . If no INCA database is open an empty string is returned. consisting of the following entries: • p.Pathname of the INCA data directory.tempPath .Pathname of the INCA installation directory.Output Arguments p Properties of INCA as MATLAB struct. The API Functions 29 . Input Arguments Examples p = IncaGetProperties. • p.

The experiment can be opened from within MATLAB. a workspace with a valid hardware configuration must first be created and assigned.1 Open INCA Name IncaOpen Description Open INCA and initialize the connection between MATLAB and INCA. To work with the INCA-MIP API.4. The following API functions are available for initializing: 4. there must an empty experiment in the INCA database which is linked to a valid workspace and hardware configuration.3 Initialization All measurement and calibration operations in INCA will be performed within the context of an experiment. Syntax IncaOpen Output Arguments Input Arguments Examples 30 The API Functions . Before opening an experiment.3.

Examples IncaOpenDatabase. If you do not specify a directory.2 Open a Database Name IncaOpenDatabase Description Open the database in the specified directory Syntax IncaOpenDatabase({pathName}) Output Arguments 4. Syntax IncaDatabaseImport(path) name = IncaDatabaseImport(path) [name. Import a Database (INCA-MIP Extended) Name IncaDatabaseImport Description Import a database export file (*.3 Input Arguments pathName The directory in which the database to be opened is stored. type] = IncaDatabaseImport(path) Output Arguments name Array of the full path names of all imported database items use deblank() when accessing an array element: name2 = deblank(name(2. the current database is opened.% open current database IncaOpenDatabase(’c:\etasdata\mydatabase’).4.exp) into INCA.3.3.:)) The API Functions 31 . Existing database items will always be overwritten.

folderName) Output Arguments name List of names of the database items type List of types of the database items: • Folder: Database folder • Experiment: Experiment • Workspace: Workspace • Asap2Project: ASAP2 Project The API Functions .exp') Read Database Items (INCA-MIP Extended) Name IncaBrowseItemsInFolder Description Read database items in the given database folder with a search pattern Syntax [name.type Array of types of all imported database items Possible values are: • Folder: a database folder • Experiment: an Experiment Environment • Workspace: a Workspace • Asap2Project: an ASAP2 Project • MeasurementCatalog: an ASAP2 Measurement Catalog • CanDB: an ASAP2 CAN DB use deblank() when accessing an array element: type2 = deblank(type(2. type] = IncaBrowseItemsInFolder(pattern.exp file to be imported Examples names = IncaDatabaseImport('D:\ ETASData\INCA5.4\export\Project0815.:)) 4.4 32 Input Arguments path The full path of the *.3.

There is no difference between lower and upper case.5 pattern Search pattern for database entries to look for. ’’). All other characters have to match with the database items. A ’#’ matches exactly one character.3.type]=IncaBrowseItemsInFolder(’Prj*_# #’. folderName Database folder in which the database items are read.Input Arguments Examples 4. An empty string is used for the upper most hierarchy level. device. This can only be done if no experiment is currently opened. Folder hierarchies are separated by a ’\’.dataset) Output Arguments Input Arguments Examples workspace database path of workspace device name of device project database path of project dataset database path of dataset IncaSetProjectAndDatasetInDevice('DEFAULT\w orkspace'.'DEFAULT\Prj0815'.t]=IncaBrowseItemsInFolder(’*’. [name. Assign Project and Dataset in Device (INCA-MIP Extended) Name IncaSetProjectAndDatasetInDevice Description Assign a project and dataset to a device in a given workspace.'ETK:1'.project. A ’*’ matches zero or any number of additional characters. ’DEFAULT\MyProject’).'Ds4711 \Ds4711_3') The API Functions 33 . Syntax IncaSetProjectAndDatasetInDevice(workspace. [n.

4.3.6

Open an Experiment
Note
This function has changed since INCA V3.0, because two input arguments
have been added to the re-worked workspace.
If the experiment is already open when the function
IncaOpenExperiment is called, the input arguments specifiying the environment are optional. If the experiment is not yet open, you need to call
IncaOpenDatabase before IncaOpenExperiment.
Name

IncaOpenExperiment

Description

Open the specified experiment (Experiment Environment).
After an experiment has been opened, you can use the
INCA-MIP API to add your measurement and calibration
variables as desired.

Syntax

IncaOpenExperiment({closeAllViewsFlag})
or
IncaOpenExperiment(expFolderName,
experimentName, workspaceFolderName,
workspaceName {, closeAllViewsFlag})

Output
Arguments
Input
Arguments

34

The API Functions

expFolderName

directory in which the
experiment is stored

experimentName

name of the experiment

workspaceFolderName

directory in which the workspace
is stored

workspaceName

name of the workspace

closeAllViewsFlag

Examples

4.3.7

Closes all measure and
calibration windows in the
selected experiment. Possible
settings:
• 1: closes all windows
(default)
• 0: leaves the windows
unchanged.

IncaOpenExperiment(’ExpFolder’,
’MyExperiment’, ’WorkspaceFolder’,
’MyWorkspace’);

Reset an Experiment
Name

IncaResetExperiment

Description

Reset and close the current experiment. You can use this
function to remove all variables from an experiment.
Removing individual variables is currently not supported.

Syntax

IncaResetExperiment

Output
Arguments
Input
Arguments
Examples
Note
If the experiment has been opened manually and not by means of a MATLAB
command, IncaResetExperiment releases the experiment, but does not
close the window. You need to execute IncaOpenExperiment before you
can access the experiment once again.

4.3.8

Read Devices

(INCA-MIP Extended)

Name

IncaGetDevices

Description

Read all devices in the experiment

Syntax

[name, type] = IncaGetDevices

Output
Arguments

name

List of names of the devices

The API Functions

35

type

List of device types:
• WorkbaseDevice: Device with
datasets
• MeasurementDevice: Measurement
device

Input
Arguments
Examples

4.3.9

[name,type]=IncaGetDevices;

Read Device Properties

(INCA-MIP Extended)

Name

IncaGetDeviceProperties

Description

Read properties of a device

Syntax

p = IncaGetDeviceProperties(deviceName)

Output
Arguments

p

Device properties as MATLAB struct,
consisting of the following entries:

p.name

device name

p.descriptionFile Pathname of the description file of
the project assigned to the device.
An empty string is returned if there
is no project assigned to the device.
p.binaryFile

Pathname of the binary file of the
project assigned to the device. An
empty string is returned if there is
no project assigned to the device.

p.projectDBPath

Pathname within the INCA database
of the project assigned to the
device. An empty string is returned
if there is no project assigned to the
device.

p.isWriteProtecte •
d

p.isActive


36

The API Functions

0: Device has no memory pages
or current page is not write protected
1: Current page is write protected
0: Device is not connected or
not active
1: Device is connected and
active

p. The API Functions 37 .isWorkbaseDevic • e • 0: Device has no datasets 1: Device has datasets Input Arguments deviceName name of the device Examples p = IncaGetDeviceProperties(’Device’).

. deviceName Name of the device Input Arguments Examples 38 (INCA-MIP Extended) The API Functions [n.t]=IncaBrowseMeasureElements(’ign*’.4.4. [name. signals.4 Measuring and Recording A signal or measurement variable is always captured as part of a measure raster for that particular measuring device. A ’#’ matches exactly one character. All other characters have to match with the measurement element. and measure rasters are case-sensitive. ’Device’).1 Read Measurement Elements Name IncaBrowseMeasureElements Description Get measurement elements of the experiment with search pattern and optional device Syntax [name. To configure an experiment. Note Note that the names of elements. Each measurement variable may appear in one measure raster only. first assign the measurement variables to the individual measure rasters. type] = IncaBrowseMeasureElements (pattern. {deviceName}) [name] = IncaBrowseMeasureElements(pattern. There is no difference between lower and upper case. devices. A ’*’ matches zero or any number of additional characters.type]=IncaBrowseMeasureElements(’*’). 4. {deviceName}) Output Arguments name List of names of measurement elements type List of types of the measurement elements: • Scalar: Scalar • Array: Vector • Matrix: Matrix pattern Search pattern for the measurement elements to look for.

’10ms+100ms’.m] has to be appended to the name. e. For scalars.4. the index in the format [n] or [n. name=IncaGetMeasureRatesForDevice(’Dev’).3 Read Measure Rasters (INCA-MIP Extended) Name IncaGetMeasureRatesForDevice Description Get all measure rasters of a device Syntax [name] = IncaGetMeasureRatesForDevice(deviceName) Output Arguments name List of names of the measure rasters Input Arguments deviceName Name of the device Examples n=IncaGetMeasureRatesForDevice(’Device’). signalName name of the measurement signal.” The API Functions 39 . Syntax IncaAddMeasureElement(deviceName.4. signalName {. for vectors and matrices.2 4.g. The first element has the index of “zero. displayMode}) Output Arguments Input Arguments deviceName name of the device groupName name of the measure raster (corresponds to the sampling rate) It is possible to use multiple rasters by simply combining raster names by means of a ’+’ character.4. groupName. Add Measurement Variable to Measure Raster Name IncaAddMeasureElement Description Add a measurement variable to a measure raster. just the name is sufficient.

1]’).4. ’Matrix[2.displayMode Examples display mode for the element: • 1: measurement variable is displayed (default) • 0: no display IncaAddMeasureElement(’Device’. Note If the measure raster is full.5 Stop Measurement Name IncaStopMeasurement Description Stop the current measurement and recording (if enabled) in INCA Syntax IncaStopMeasurement{(mdfFileName)} Output Arguments 40 The API Functions .4 Start Measurement Name IncaStartMeasurement Description Start a measurement in INCA Syntax IncaStartMeasurement Output Arguments Input Arguments Examples 4. ’10ms’.4. the measurement variable does not get added to the raster. ’Chan1’. IncaAddMeasureElement(’Dev’. 0). 4. ’10ms’.

consisting of the following entries: properties.4.directory the directory for the recording file The API Functions 41 .dat’). Always specify the full access path to the file (e. Follow this up with the IncaGetRecords command to transfer the remaining data to MATLAB.dat’). Examples IncaStopMeasurement(’c:\mydata\store1.g.fileName the recording file name properties.. Note To avoid data loss due to ongoing measurements. 4. ’c:\mydata\store1.Input Arguments mdfFileName name of the MDF file in which the recorded data are saved if recording is stopped together with the current measurement. be sure to stop the current recording with the IncaStopMeasurement(mdfFileName) command if the data volume is high.6 Read Recording Properties (INCA-MIP Extended) Name IncaGetRecordingProperties Description Read the properties used for the next recording Syntax properties = IncaGetRecordingProperties Output Arguments properties Recording properties as MATLAB struct.

properties. the following format strings are valid: • ETAS binary data file format • Diadem ATF measure format (write only) • ASCII • ASCII (Multirate/ Write only) • MATLAB M-File • MATLAB M-File (Multirate/Write only) • FAMOS (imc) • MDF (Measure Data Format) • MDF4 (Measure Data Format for VSG using 4byte floats only) properties.vehicle The vehicle in the recording file header .project The project in the recording file header properties.user The user in the recording file header properties.company The company in the recording file header properties.properties.fileForma the file format of the recording t file. It must not exceed 1024 characters minus number of characters used for the default comment.autoIncre Automatically increment the ment recording file name • 0: don't auto increment • 1: do auto increment properties.comment The comment in the recording file header.defaultCo The default comment in the mment recording file header generated by INCA 42 The API Functions properties.

7 properties = IncaGetRecordingProperties.fileName the recording file name properties.fileForma the file format of the recording t file.Input Arguments Examples 4. Set Recording Properties (INCA-MIP Extended) Name IncaSetRecordingProperties Description Set properties for the next measurement data recording Syntax IncaSetRecordingProperties(properties) Output Arguments Input Arguments properties recording properties as matlab struct containing any combination of the following field designators: properties.4.directory the directory for the recording file properties. the following format strings are valid: • ETAS binary data file format • Diadem ATF measure format (write only) • ASCII • ASCII (Multirate/ Write only) • MATLAB M-File • MATLAB M-File (Multirate/Write only) • FAMOS (imc) • MDF (Measure Data Format) • MDF4 (Measure Data Format for VSG using 4byte floats only) The API Functions 43 .

Start Recording Name IncaStartRecording Description Start recording in INCA.user = ’Michael’.4.comment The API Functions . After a measurement or recording has been started.vehicle the vehicle in the recording file header properties. the measured data are also available in MATLAB.8 the recording file header comment must contain max.autoIncre Automatically increment the ment recording file name • 0: don't auto increment • 1: do auto increment Examples 4. Syntax IncaStartRecording Output Arguments Input Arguments Examples 44 properties. This function can be used after or instead of IncaStartMeasurement.properties. 1024 characters minus the character count of the default comment properties.user the user in the recording file header properties.company the company in the recording file header company properties. properties. IncaSetRecordingProperties(properties).project the project in the recording file header properties.project = ’K70’.

offline data can only be transmitted with a certain time delay at high loads.9 Stop Recording Name IncaStopRecording Description Stop the current recording in INCA. It is recommended that you use only offline data while measured data are being recorded. it is recommended to use only online data.. Syntax IncaSetMeasureReadMode(measureReadMode) Output Arguments The API Functions 45 . Always specify the complete access path to the file (e. During the measure data display. When recording measure data. or they are read directly from the device buffer (online data). Examples IncaStopRecording(’c:\mydata\store1. It is possible to toggle the recording on/off several times during a running measurement. The measurement continues to run and must be stopped explicitely with IncaStopMeasurement. Syntax IncaStopRecording(mdfFileName) Output Arguments 4. while offline data are always complete when measured data are recorded.g. The data are either first prepared in INCA and then transferred to MATLAB (offline data).dat’). there are no offline data available during the display of measure data.4.dat’).4. In each case. However. Set Data Reading Mode (Online / Offline Data) Name IncaSetMeasureReadMode Description Determine from which source the measured data are transmitted to MATLAB. the optimized transmission features produce special display characteristics of the results: online data may be incomplete at high loads. ’c:\mydata\store1. For some devices.10 Input Arguments mdfFileName The name of the MDF file where the recorded data are saved. such as the ES1303 card and the ES6xx series devices.4. both online and offline data can be used.

whereas m <= maxRecords. The measure data are retrieved from MATLAB in groups.g. maxRecords) Output Arguments time Name of the variable containing the time stamps of the transferred records. This is a matrix whose dimension m reflects the number of transferred records. The greater the amount of data being transferred at each time.4. The measure data for each measure raster are stored in a dedicated ring buffer that can hold data for up to 30 seconds of measuring time. whereas n indicates the number of measure rasters.4. the more efficiently the data transfer is. deviceName Name of the device groupName Name of the measure raster It is possible to use multiple rasters by simply combining raster names by means of a ’+’ character. Possible settings: • 1: Offline data • 0: Online data (default) Examples IncaSetMeasureReadMode(0).11 Input Arguments measureReadMode numerical parameter whose value specifies the data source. Syntax [time. You should therefore stop your script execution in MATLAB after you have retrieved the measure data. Read Measure Data Name IncaGetRecords Description The transfer of measure data to MATLAB begins right after starting the measurement. ’10ms+100ms’. data] = IncaGetRecords(deviceName. data Name of the variable containing the transferred records. e. This function transmits a specified number of records for the specified measure raster. Input Arguments 46 The API Functions . For further information on the ring buffer see the corresponding entry in the "INCA Glossary" on page 9. groupName. This variable contains a maximum number of m values.

For a larger context using this piece of code please see "Example 2" on page 65. t].maxRecords Examples Maximum number of records to be transferred.4.12 Reset Ring Buffer Name IncaResetRecords Description Reset the ring buffer for all measure rasters.13 Read Hardware Status (INCA-MIP Extended) Name IncaGetHardwareStatus Description Get the current Hardware Status during a measurement or recording The API Functions 47 . 500 ). Syntax IncaResetRecords Output Arguments Input Arguments Examples 4. it is not necessary to issue this command explicitely. The number you enter here is the dimension m for the time or data variable above. For further information on the ring buffer see the corresponding entry in the "INCA Glossary" on page 9. data = [data. ’10ms’. 4. time = [time.4. They are reset automatically when starting a measurement or recording. d ]=IncaGetRecords( ’MyDevice’. only the existing records are transferred. If fewer records exist. This function can even be used during a running measurement to reset all ring buffers. an insufficient number of records will be read and the ring buffer can overflow. [ t. If this dimension reaches the value of maxRecords. d].

message] = IncaGetHardwareStatus Output Arguments status current Hardware Status • 0: Status ok • 1: Warning • 2: Error message If status returns 1 or 2.Syntax [status. See also example script tHWStatus. • manual for a manual stop trigger • none if no trigger is to be used (default) . stopTrigger{. preTriggerTime{. message returns a text describing the warning or error. postTriggerTime{. If status returns 1 or 2. duration}}}}) Output Arguments Input Arguments 48 The API Functions startTrigger Start trigger condition. • manual for a manual start trigger • none if no trigger is to be used stopTrigger Stop trigger condition. the measurement or recording has to be finished before IncaGetHardwareStatus can be called once again.14 Set Trigger (INCA-MIP Extended) Name IncaSetTrigger Description Set the trigger condition before starting a measurement or recording with IncaStartMeasurement or IncaStartRecording Syntax IncaSetTrigger(startTrigger{.4.m in "Getting to know the INCA-MIP API through Sample Files" on page 24 Input Arguments Examples 4.

'none'.16 type Trigger type • start for executing a manual start trigger • stop for executing a manual stop trigger IncaExecuteManualTrigger('start') Read Recording State (INCA-MIP Extended) Name IncaGetRecordingState Description Get the current recording status.0. 3.4. 2.preTriggerTime The pre trigger time in seconds • none if unspecified (default) postTriggerTim The post trigger time in seconds e • none if unspecified (default) duration Examples 4.0) IncaSetTrigger('none'. Syntax result = IncaGetRecordingState The API Functions 49 . 'none'. in this case the duration is infinite.4. IncaSetTrigger('nmot\ETK:1 > 2000'. 'none'. 360) Execute Manual Trigger (INCA-MIP Extended) Name IncaExecuteManualTrigger Description Execute a manual start or stop trigger.15 Duration of measurement or recording in seconds • none if unspecified (default). Syntax IncaExecuteManualTrigger(type) Output Arguments Input Arguments Examples 4. 'none'. This only has an effect if a IncaSetTrigger command has been set before with the startTrigger or stopTrigger parameter set to manual .

Syntax list = IncaGetRecordStruct(device.g. list = IncaGetRecordStruct('device1'.4. '10ms'). e.17 s = IncaGetRecordingState Read List of Measurement Variables (INCA-MIP Extended) Name IncaGetRecordStruct Description Get list of measurement variables which have been assigned for measurement or recording. l = IncaGetRecordStruct('ETK:1'.Output Arguments result recording status • 0: switched off • 1: waiting for trigger or recording in progress Input Arguments Examples 4. ’10ms+100ms’. 'Syncro'). The list returns the measurement names in the same order as they have been assigned with IncaAddMeasureElement.groupName) Output Arguments Input Arguments Examples 50 The API Functions device name of device groupName name of measure raster It is possible to use multiple rasters by simply combining raster names by means of a ’+’ character. .

A ’#’ matches exactly one character. Syntax [name. ’Device’).type]=IncaBrowseCalibrationElements(’ *’). All other characters have to match with the calibration element. type] = IncaBrowseCalibrationElements (pattern. There is no difference between lower and upper case. {deviceName}) name = IncaBrowseCalibrationElements (pattern. {deviceName}) Output Arguments name List of names of calibration elements type List of types of the calibration elements: • Distribution: Axis distribution • OneDTable: Curve • TwoDTable: Map • Scalar: Scalar • Array: Vector • Matrix: Matrix pattern Search pattern for the calibration elements to look for. deviceName Name of the device Input Arguments Examples [n.4.1 Read Calibration Elements (INCA-MIP Extended) Name IncaBrowseCalibrationElements Description Get calibration elements of the experiment with search pattern and optional device. The API Functions 51 .5 Calibrating Calibrations can be performed with scalars.t]=IncaBrowseCalibrationElements(’MAP*’. 4. characteristic curves and maps. [name. including the associated break point distributions.5. it is possible to define any number of calibration variables. Note Note that the names of calibration variables are case-sensitive. A ’*’ matches zero or any number of additional characters. In each experiment.

size} {. IncaAddCalibrationElement(’anEtk’. IncaAddCalibrationElement(’anEtk’.5. ’Map’). valueType}) The API Functions .3 52 IncaAddCalibrationElement(’anEtk’. displayMode}) Output Arguments Input Arguments deviceName name of the device calibrationName name of the calibration element displayMode display mode for the element: • 2: the calibration variable is displayed and constantly updated (default) • 1: it is displayed but not updated • 0: no display Selecting 1 (display only) may considerably improve the performance at high data volumes.2 Add Calibration Element Name IncaAddCalibrationElement Description Add a calibration element to the current experiment Syntax IncaAddCalibrationElement(deviceName. ’Curve’).5. Examples 4. calibrationName {.4. ’Scalar’). calibrationName {. Read Calibration Value Name IncaGetCalibrationValue Description Read the current value of a calibration variable or the associated break point distribution Syntax value = IncaGetCalibrationValue(deviceName. start.

m >= 1 The API Functions 53 .Output Arguments value the current value of the calibration variable. Supported datatypes: • For curves and break point distributions a count n has to be specified. n >= 1 • For maps a count [n. Supported datatypes: • For curves and break point distributions a startindex x has to be specified.1) matrix • Curves: an (x.m] has to be specified. x.1) matrix • Maps: an (x. x >= 1 • For maps a startindex [x.y] has to be specified. n. it must match the data types specified below: • Scalars: a (1.1)-matrix Input Arguments deviceName name of the device calibrationName the name of the calibration element start Startindex.y >= 1 size Number of values to read.y) matrix • Break point distributions: an (x.

’Curve’). 2. aMapRange = IncaGetCalibrationValue (’anEtk’. ’y’). aCurveRange = IncaGetCalibrationValue (’anEtk’. ’Map’. [2.valueType Examples 54 The API Functions selection of the output argument (string). . ’Map’). Possible settings: • v: value • x: x break point (curves and maps • y: y break point (maps) aValue = IncaGetCalibrationValue(’anEtk’. yMap = IncaGetCalibrationValue(’anEtk’.and Y-break point distribution. 2. The function either returns the value of the calibration variable (default) or the X. 3). [3. ’x’). ’Map’.3]. aMap = IncaGetCalibrationValue(’anEtk’. ’Curve’. 3. ’Scalar’). ’x’). aCurve = IncaGetCalibrationValue(’anEtk’. xMap = IncaGetCalibrationValue(’anEtk’. ’Map’. ’Map’.4]). xMapRange = IncaGetCalibrationValue (’anEtk’.

value. valueType ) result = IncaSetCalibrationValue( deviceName. value. value. valueType ) The API Functions 55 . value. calibrationName. calibrationName. calibrationName. start ) IncaSetCalibrationValue( deviceName.4. start ) result = IncaSetCalibrationValue( deviceName. calibrationName. start. value ) result = IncaSetCalibrationValue( deviceName. start. value. calibrationName.4 Change Calibration Value Name IncaSetCalibrationValue Description Assign a value to a calibration variable or associated break point Syntax IncaSetCalibrationValue( deviceName. value. value ) IncaSetCalibrationValue( deviceName. valueType ) IncaSetCalibrationValue( deviceName.5. calibrationName. calibrationName. valueType ) result = IncaSetCalibrationValue( deviceName. calibrationName.

Acceptable data types: • Scalars: a (1. depending on the active calibration mode. y) matrix • x and y break point distributions: an (x. Input Arguments deviceName name of the device calibrationName name of the calibration element value 56 The API Functions value of the calibration element. In this case more detailed in formation is returned by bit 1 to 4.or ydistribution would be violating the monotony. 1) matrix . 1) matrix • Maps: an (x. 1) matrix • Curves: an (x. any of the bounds would have been violated. For instance. In all these cases only bit 0 is set.Output Arguments result result of calibration (optional) The result is a bit coded value: • Bit 0 set: calibration not done • Bit 1 set: lower weak bound violated • Bit 2 set: upper weak bound violated • Bit 3 set: lower hard bound violated • Bit 4 set: upper hard bound violated • Bit 5 set: limited to lower weak bound • Bit 6 set: limited to upper weak bound • Bit 7 set: limited to lower hard bound • Bit 8 set: limited to upper hard bound There may be different causes for a calibration not to be executed. Another cause might be that the calibration element or active page is write protected or a x.

y] has to be specified. IncaSetCalibrationValue(’anEtk’. x >= 1 For maps a startindex [x. ’Curve’. xMap. 2). IncaSetCalibrationValue(’anEtk’.5 start Start index. yMap.y >= 1 valueType Selection of value (string). IncaSetCalibrationValue(’anEtk’. IncaSetCalibrationValue(’anEtk’. IncaSetCalibrationValue(’anEtk’. The function modifies either the value of the calibration variable (default) or the X/Y break point distribution. aCurveRange. ’x’).5. Supported datatypes: • For curves and break point distributions a startindex x has to be specified. x.[2. 2. aValue). aMapRange. xMapRange.Examples 4. ’Map’. ’x’). (INCA-MIP Extended) Name IncaSetDatasetInDevice Description Assign a dataset to a device in an open experiment Syntax IncaSetDatasetInDevice(device. IncaSetCalibrationValue(’anEtk’. ’Map’. ’y’). IncaSetCalibrationValue(’anEtk’. ’Curve’. ’Map’.3]). aCurve). aMap).dataset) Output Arguments The API Functions 57 . Possible settings: • v: value (default) • x: x break point (curves and maps) • y: y break point (maps) IncaSetCalibrationValue(’anEtk’. ’Map’. ’Map’. Assign Dataset to Device ’Scalar’.

Input Arguments Examples 4. When starting the MATLAB Interface the default mode for both lower and upper limits is rejectWeakBoundViolation.7 device l = IncaGetDatasetsForDevice('ETK:1') Set Calibration Mode (INCA-MIP Extended) Name IncaSetCalibrationMode Description Set the global calibration mode valid for all subsequent calibrations done with IncaSetCalibrationValue. properties] = IncaGetDatasetsForDevice(device) Output Arguments name A string list with the full path of all datasets found properties A string list of the dataset properties Possible values are: • '' (empty string): A dataset with readwrite access • r : A dataset with read-only access • m : A master dataset with read-write access • mr: A master dataset with read-only access device name of device Examples 58 name of device List Datasets of a Device Input Arguments 4.5. The mode remains valid even after closing and reopening an experiment.5. The API Functions .'Ds4711\Ds47 11_3') (INCA-MIP Extended) Name IncaGetDatasetsForDevice Description Get a list of all dataset names for a given device Syntax name = IncaGetDatasetsForDevice(device) [name.6 dataset database path of dataset IncaSetDatasetInDevice('ETK:1'.

8 lowerLimitMode The new Calibration Mode for lower limits upperLimitMode The new Calibration Mode for upper limits: • rejectWeakBoundViolation: reject complete calibration if weak bound would be violated at least once (default) • limitToWeakBound: If min. or max. If min. or max.Syntax IncaSetCalibrationMode(lowerLimitMode. weak bound limit would be violated use min. or max. hard bound value instead IncaSetCalibrationMode('rejectHardBoundViol ation'.5. weak bound value instead • rejectHardBoundViolation: Ignore weak bounds. or max. Reject complete calibration if hard bound would be violated at least once • limitToHardBound: Ignore weak bounds. hard bound limit would be violated use min. upperLimitMode) Output Arguments Input Arguments Examples 4. 'limitToHardBound') Group Devices (INCA-MIP Extended) Name IncaGroupDevices Description Activate or deactivate Device Grouping Syntax IncaGroupDevices(onOff) Output Arguments Input Arguments onOff • • 0: Deactivate device grouping 1: Activate device grouping Examples IncaGroupDevices(1) The API Functions 59 .

dcm'. 'BRABEVI_KL'. 'ETK:1'. 'KFZW_GKF'}. IncaWriteToFile('DCM'.5.4.device.file. calibs).calibs{.'C:\DCMOut2. options}) Output Arguments Input Arguments Examples 60 The API Functions format File format identifier: • 'DCM': DCM format file Full path of file to be written to device Device whose calibration elements will be written calibs List of calibration elements to write (as cell array) options Options used for writing in specified format calibs = {'A0_KW'.'A0_KW'). 'device1'.9 Write DCM File (INCA-MIP Extended) Name IncaWriteToFile Description Write a DCM file within an open experiment Syntax IncaWriteToFile(format. IncaWriteToFile('DCM'.'C:\DCMOut1. .dcm'.

4. calibration access is possible only from the working page.6.6.4.1 Activate Memory Page Name IncaSwitchPage Description Activate the specified memory page.6 Memory Page Manager All previously described API functions are effective for a device’s currently active page. The following API functions can be used for memory page management. However. Syntax IncaSwitchPage(deviceName. pageName) Output Arguments Input Arguments deviceName name of the device pageName name of the page: • wp: working page • rp: reference page Examples 4. it might occur that write access to the ETK’s working page is blocked because the checksums of the working pages in the INCA database and in the ETK do not match. In principle.2 Get Current Page (INCA-MIP Extended) Name IncaGetCurrentPage Description Get the currently active memory page Syntax pageName = IncaGetCurrentPage(deviceName) Output Arguments pageName name of the active memory page: • wp: working page • rp: reference page Input Arguments deviceName Name of the device Examples The API Functions 61 .

Syntax IncaCopyPageFromTo( deviceName.4 Download Memory Page Name IncaDownloadPage Description Download the specified memory page to the control unit Syntax IncaDownloadPage(deviceName.3 Check Write-Protection Name IncaIsPageWriteProtected Description Check whether the specified memory page is write-protected Syntax isRW = IncaIsPageWriteProtected(deviceName.6. other combinations of sources and targets are not supported. it is only possible to copy from the reference page to the working page.6. Currently.4.5 62 Copy Memory Page Name IncaCopyPageFromTo Description Copy the specified memory page. pageName) Output Arguments isRw • • Input Arguments deviceName name of the device pageName name of the page: • wp: working page • rp : reference page 0: page is not write-protected not 0: page is write-protected Examples 4. pageName) Output Arguments Input Arguments deviceName name of the device pageName name of the page to download • wp: working page • rp: reference page Examples 4.6. sourcePageName. destinationPageName) The API Functions .

Syntax IncaDownloadDifferences( deviceName ) Output Arguments Input Arguments deviceName name of the device Examples 4. As with the corresponding menu option. The new datasets are automatically assigned to the device.6.referencePage. this is only updated if the working page and reference page in the target unit match the reference page in INCA. workingPage}) Output Arguments The API Functions 63 .6.7 Upload Pages (INCA-MIP Extended) Name IncaUploadPages Description Upload reference and working page to newly created datasets.6 Download Differences Name IncaDownloadDifferences Description Load the differences between the working page and reference page into the control unit. Syntax IncaUploadPages(device{.Output Arguments Input Arguments deviceName name of the device sourcePageName name of the page to be copied: • wp: working page • rp: reference page destinationPageName name of the page to copy to: • wp: working page • rp: reference page Examples 4.

IncaUploadPages('ETK:1'. If not specified. INCA uses a default name IncaUploadPages('ETK:1'). 'work_1'). INCA uses a default name workingPage Examples 64 The API Functions Dataset name for uploaded working page. 'ref_1'. .Input Arguments device name of device referencePage Dataset name for uploaded reference page. If not specified.

IncaAddMeasureElement( ’MyDevice’. To execute this example. ’wp’)) IncaDownloadPage(’anEtk’.1) % Get up to 500 records for group 10ms [ t. t]. ). ’wp’). the functions described above are used to read measured values from the device MyDevice and measure raster 10ms. ).1 seconds to have more than one % record -. end % Switch to the working page IncaSwitchPage( ’anEtk’. ’10ms’. deltaT = 0.saves processor time. % Append t and d to time and data data = [data. time = []. ’Chan1’ ’Chan2’ ’Chan3’ ’Chan4’ ). % Now measure data = []. IncaSetMeasureReadMode(0) IncaStartMeasurement. ’10ms’. 500 ). d ]=IncaGetRecords( ’MyDevice’. ’wp’). you must first open an experiment in INCA that includes an assigned device named MyDevice. time = [time. Example 2 In the following example. IncaShowMessages(0).4. ’10ms’. ). IncaAddMeasureElement( ’MyDevice’. % Measure for 20 seconds while( deltaT < 20 ) % Pause for 0. ’10ms’.7 Application Examples Example 1 % Check if working page is write-protected and % download the page if it is write-protected if(IncaIsPageWriteProtected (’anEtk’. d]. IncaAddMeasureElement( ’MyDevice’. % Measure the following signals IncaAddMeasureElement( ’MyDevice’. ’10ms’. if( length(time) ) % Calculate time measured The API Functions 65 . pause(0.

data). This example uses only one measure raster. However. end end IncaStopMeasurement.deltaT = time( length(time)) .time(1). you can use several groups and request the data for each group independent of MATLAB. % Plot the results plot(time. IncaShowMessages(1). 66 The API Functions .

exe. 5. Note INCA can be controlled by only one MATLAB session at a time. Trying to control INCA simultaneously from different instances of MATLAB or standalone executables will be aborted with an error message. Creation and Distribution of Stand-alone Executable Files 67 .5 Creation and Distribution of Stand-alone Executable Files With INCA-MIP.1 Compilation of m-Files containing MATLAB API Functions After creation and test of an m-file containing MATLAB API functions it is possible to create a stand-alone executable file by using the MATLAB compiler: mcc -m <m-file-script> Example: With the following command a stand-alone executable file is created from the file testCase1. you can create and compile m-files containing MATLAB API functions.m: mcc -m testCase1 Result is the file testCase1. The resulting stand-alone files can be executed also in environments without a MATLAB installation. See your MATLAB user documentation under the keyword MATLAB Compiler or mcc for further settings of the MATLAB compiler.

To distribute stand-alone executable files • Install the required MATLAB runtime libraries. Creation and Distribution of Stand-alone Executable Files . or • Copy the required files from the following locations within your MATLAB installation on your development machine : %MATLABDir%\bin\win32\ incaRci2Matlab. See your MATLAB user documentation under Distributing Stand-Alone Applications for information on how to install the MATLAB runtime libraries. install the INCA-MIP Add-On and select Installation into ETASData in the installation routine (see "Installing INCA-MIP from CD-ROM" on page 13).dll • 68 Copy these files together with the stand-alone executable files into the same directory.dll %MatlabDir%\toolbox\matlab\ general\Inca*.5. To install the ETAS runtime libraries. A MATLAB installation is not neccessary.2 Distribution of Stand-alone Executable Files Stand-alone executable files created as described above need runtime libraries both from MATLAB and from ETAS.

Transferring these 1000 measurement values takes approximately 13 ms. Performance 69 . 10 * 100 = 1000 measurement values are ready for transfer. This means that after one second. Therefore the time it takes to transfer one single measurement value can be derived from the values above as roughly 13 µs. which roughly corresponds to one per-cent of the available processor time. a measure raster with 10 measurement signals is used that are written at 10 ms intervals.6 Performance The data throughput for the INCA-MIP API has been tested on a computer with a 300 MHz Pentium II processor. However. The data are retrieved from MATLAB at one-second intervals. the data throughput during the measurements depends largely on the total amount of data to be transferred during the function call. Calibrating: Access time for reading/writing • Scalar: ~20 ms • One-dimensional table with 10 values: ~50 ms • Two-dimensional table with 3 x 8 values: ~150 ms Measuring: To determine the data throughput.

70 Performance .

Belgium. Great Britain USA ETAS Inc. Centrum 100 Fax: +44 1283 54 87 67 Burton-upon-Trent E-mail: sales@etas-uk. Belgium.etasgroup.7 ETAS Contact Addresses ETAS Europe (except France. Luxembourg ETAS S.S.com 3021 Miller Road Phone: +1 888 ETAS INC Ann Arbor.fr France WWW: www.com Studio 3.etasgroup. MI 48103 Fax: +1 734 997-9449 USA E-mail: sales@etas. Waterside Court Phone: +44 1283 54 65 12 Third Avenue.de WWW: www.net Staffordshire DE14 2WQ WWW: www.A.com 1.etasgroup. place des Etats-Unis Phone: +33 1 56 70 00 50 SILIC 307 Fax: +33 1 56 70 00 51 94588 Rungis Cedex E-mail: sales@etas.com France. Luxembourg and Great Britain) ETAS GmbH Borsigstraße 14 Phone: +49 711 89661-0 70469 Stuttgart Fax: +49 711 89661-105 Germany E-mail: sales@etas.us WWW: www.etasgroup. Great Britain ETAS Ltd. ETAS Contact Addresses 71 .

com Korea ETAS Korea Co. 70-5 Phone: +82 2 57 47-016 Yangjae-dong. Bank of China Tower Phone: +86 21 5037 2220 200 Yincheng Road Central Fax: +86 21 5037 2221 E-mail: sales.co.Japan ETAS K. Minatomirai.com 4F. Korea P.etasgroup. China ETAS (Shanghai) Co. Ltd.R. Shanghai 200120..co. P.jp Japan WWW: www. Queen's Tower C-17F Phone: +81 45 222-0900 2-3-5.etasgroup. China 72 ETAS Contact Addresses .R.kr 2404.com WWW: www. 705 Bldg. Nishi-ku Fax: +81 45 222-0956 Yokohama 220-6217 E-mail: sales@etas.cn@etasgroup.K. Seocho-gu Fax: +82 2 57 47-120 Seoul 137-889 E-mail: sales@etas. Ltd.

59 IncaSetCalibrationValue 55 73 . 52 IncaGetCurrentPage 61 IncaGetDatasetsForDevice 58 IncaGetDeviceProperties 36 IncaGetDevices 35 IncaGetHardwareStatus 47.Index C Calibrating 7 Calibration Variable 9 Compilation of m-files 67 D Data record 9 Device 9 I IncaAddCalibrationElement 52 IncaAddMeasureElement 39 IncaBrowseCalibrationElements 51 IncaBrowseItemsInFolder 32 IncaBrowseMeasureElements 38 IncaCopyPageFromTo 62 IncaDatabaseImport 31 IncaDownloadDifferences 63 IncaDownloadPage 62 IncaExecuteManualTrigger 49 IncaGetCalibrationValue 8. 48 IncaGetMeasureRatesForDevice 39 IncaGetProperties 28 IncaGetRecordingProperties 41 IncaGetRecordingState 49 IncaGetRecords 46 IncaGetRecordStruct 50 IncaGetVersion 28 IncaGroupDevices 59 IncaIsLicenseValid 28 IncaIsPageWriteProtected 62 IncaOpen 30 IncaOpenDatabase 31 IncaOpenExperiment 34 IncaResetExperiment 35 IncaResetRecords 47 IncaSetCalibrationMode 58.

24 MATLAB scripts 7 mcc 67 Measure Data 9 Measurement Raster 9 Measuring 7 Memory Page Management 7 MEX files 13 O obtain license file 17 R Ring Buffer 10 S sample files 24 Signal 11 Signal Group 11 stand-alone executable files 67 74 store license file 19 .IncaSetDatasetInDevice 57 IncaSetMeasureReadMode 45 IncaSetProjectAndDatasetInDevice 33 IncaSetRecordingProperties 43 IncaSetTrigger 48 IncaShowMessages 27 IncaStartMeasurement 40 IncaStartRecording 44 IncaStopMeasurement 40 IncaStopRecording 45 IncaSwitchPage 61 IncaUploadPages 63 IncaWriteToFile 60 Installation obtain license file 17 store license file 19 L license file obtain 17 store 19 M M files 7.