INCA-MIP V16.0 for INCA V7.1 User s Guide

Transcription

1 INCA-MIP V16.0 for INCA V7.1 User s Guide

2 Copyright The data 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 described in it can only be used if the customer is in possession of a general license agreement or single license. Using and copying is only allowed in concurrence with the specifications stipulated in the contract. Under no circumstances may any part of this document be copied, reproduced, transmitted, stored in a retrieval system or translated into another language without the express written permission of ETAS GmbH. Copyright ETAS GmbH, Stuttgart The names and designations used in this document are trademarks or brands belonging to the respective owners. Document AM V7.1 R01 EN

3 Contents Contents 1 Introduction Safety Advice About this Manual Typographic Conventions INCA Glossary Installing the INCA-MIP Add-on System Requirements Installing INCA-MIP from DVD Updating the Cache for MATLAB Toolbox directories Disabling the Cache for MATLAB Toolbox Directories Licensing the Software ETAS License Models How to get a License The License File Grace Mode The "Expiration Warning" Window Borrowing a License Customizing the Network Installation INCA-MIP Change Log Changes Introduced with INCA-MIP V16.0 for INCA V The API Functions Getting to know the INCA-MIP API through Sample Files General Functions List INCA-MIP Interface Message IDs Show Messages During Script Execution Show whether Valid INCA-MIP License exists (INCA-MIP Extended) Read Information on All Installed INCA Versions INCA-MIP V16.0 for INCA V7.1 - User s Guide 3

4 Contents ETAS Read Information on All Installed Product Add-Ons Read INCA Version Read INCA Properties (INCA-MIP Extended) Initialization Open INCA Close INCA (INCA-MIP Extended) Open a Database Import a Database (INCA-MIP Extended) Read Database Items (INCA-MIP Extended) Assign Project and Dataset in Device......(INCA-MIP Extended) Open an Experiment Reset an Experiment Read Devices (INCA-MIP Extended) Read Device Properties (INCA-MIP Extended) Measuring and Recording Read Measurement Elements (INCA-MIP Extended) Read Measure Rasters (INCA-MIP Extended) Add Measurement Variable to Experiment Start Measurement Stop Measurement Read Recording Properties (INCA-MIP Extended) Set Recording Properties (INCA-MIP Extended) Read Recording Mode (INCA-MIP Extended) Set Recording Mode (INCA-MIP Extended) Start Recording Stop Recording Set Data Reading Mode (Online / Offline Data) Read Measure Data Reset Ring Buffer Read Hardware Status (INCA-MIP Extended) Set Trigger (INCA-MIP Extended) Execute Manual Trigger (INCA-MIP Extended) Read Recording State (INCA-MIP Extended) Read List of Measurement Variables......(INCA-MIP Extended) Calibrating Read Calibration Elements (INCA-MIP Extended) Add Calibration Element Read Calibration Value Change Calibration Value Assign Dataset to Device (INCA-MIP Extended) List Datasets of a Device (INCA-MIP Extended) Set Calibration Mode (INCA-MIP Extended) Group Devices (INCA-MIP Extended) Write DCM File (INCA-MIP Extended) Memory Page Manager Activate Memory Page Get Current Page (INCA-MIP Extended) Check Write-Protection INCA-MIP V16.0 for INCA V7.1 - User s Guide

5 Contents Download Memory Page Copy Memory Page Download Differences Upload Pages (INCA-MIP Extended) Application Creation and Distribution of Stand-alone Executable Files Creation and Distribution of Stand-alone Executable Files using the MATLAB R13 Compiler Compilation of m-files Distribution of Stand-alone Executable Files Creation and Distribution of Stand-alone Executable Files using the MATLAB R14 Compiler or Higher Compilation of m-files Distribution of Stand-alone Executable Files ETAS Contact Addresses Tables Index INCA-MIP V16.0 for INCA V7.1 - User s Guide 5

6 Contents ETAS 6 INCA-MIP V16.0 for INCA V7.1 - User s Guide

7 Introduction 1 Introduction The INCA-MIP Add-On (INCA MATLAB Integration Package) is an application programming interface that controls INCA's functionality from within MATLAB. Within this context, MATLAB acts as a client accessing INCA's resources, which in this case is the server. The following chart illustrates a typical application for the INCA-MIP API, using INCA to address an ETK. MATLAB as client read measure data INCA as server ETK on ECU write calibration data The following overview outlines the INCA functionality that can be accessed from within MATLAB. Memory Page Management Switching back and forth between memory pages and downloading memory pages to the control unit are supported. Calibrating All the calibration variables for an INCA experiment can be modified. The values can be read and updated for each element and for the associated break point distributions, where applicable. Measuring All measurement variables from an INCA experiment can be read. In addition, measurements can be started and stopped from within MATLAB. 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. Since INCA generates measurement and calibration variables as doubles, conversion formulas for reprocessing in MATLAB are not required. The INCA API functions described in this document are invoked from MATLAB scripts (so-called M files), which can be used to define the entire control flow for INCA experiments. 1.1 Safety Advice WARNING! Calibration activities influence the behavior of the ECU and the systems controlled by the ECU. This may result in unexpected behavior of the vehicle and thus can lead to safety critical situations. Only well trained personnel should be allowed to perform calibration activities. INCA-MIP V16.0 for INCA V7.1 - User s Guide 7

8 Introduction ETAS 1.2 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. MATLAB or INCA operation falls outside the scope of this manual. To use the INCA-MIP API, you should be familiar with both INCA and MATLAB. You should also be familiar with using scripts in MATLAB. 1.3 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. Parentheses are used for the functions argument; braces for the optional input arguments. Example: Reading a Calibration Variable value = IncaGetCalibrationValue(device, calibration {, start, size} {, valuetype}) : value Current value of the calibration variable; it must match the data types specified below: Scalars: a (1,1) matrix Curves: an (x,1) matrix Maps: an (x,y) matrix Break point distributions: an (x,1)-matrix : device calibration- valuetype name of the device the name of the calibration element Selection of the output argument (string). The function either returns the value of the calibration variable (default) or the X- and Y-break point distribution. Possible settings: v: value x: x break point (curves and maps y: y break point (maps) The values v, x and y in non-proportional font represent the possible values that can be generated. These values have to be enclosed in. Example: ymap = IncaGetCalibrationValue( anetk, Map, y ); 8 INCA-MIP V16.0 for INCA V7.1 - User s Guide

9 Introduction 1.4 INCA Glossary The API description uses certain technical terms that experienced INCA users should be familiar with. Below is a brief definition of these terms. Calibration Variable A calibration variable is an element that can be read and modified. Calibration variables can be scalars, vectors, matrices, curves and maps. The associated break point distributions can also be read and modified. Data record A record consists of a time stamp and all the measurement values in a signal group for a single acquisition. The measurement data for a signal group consists of several records that are generated throughout the entire measurement process. Device A measuring device used for capturing measurement variables within a certain measurement grid. Some measuring devices also support calibration for corresponding variables. For example, SMB devices can be used for measurements only, while the ETK is suitable both for measurements and calibrations. Measure Data All the records captured in one measurement for individual measure rasters. Measurement Raster Acquisition rate (measuring frequency) used for measuring one or more signals in a signal group. It is possible to combine two or more rasters in a so-called multi-raster. This is done by simply combining the raster names by means of a + character, e.g. 10ms+100ms. When using such a multi-raster, a new virtual raster is created. Each signal can only be measured in exactly one raster or multi-raster. INCA-MIP V16.0 for INCA V7.1 - User s Guide 9

10 Introduction ETAS Ring Buffer To ensure a reliable transfer of measurement data from INCA to MATLAB, a dedicated ring buffer is used for each measurement raster (signal group). During an INCA online visualization or recording the acquired measurement data is automatically saved in the ring buffer. 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. After this time old measurement data will get overwritten. To avoid losing data IncaGetRecords periodically has to be executed. Typically this will be done about once each second. With the command IncaResetRecords the time stamps and data in the ring buffer for all measurement rasters can be cleared. All data already saved in the ring buffer will get lost: INCA Data Acquisition INCA Data Acquisition MATLAB Interface IncaResetRecords Signal A signal is an element whose value is measured in INCA. Each signal is characterized by its data type (Boolean, integer, float), length (1, 2, 4 or 8 bytes) and conversion formula. 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. It is characterized by its measurement raster, which is the same for all signals in the signal group. Each signal group has a unique name. 10 INCA-MIP V16.0 for INCA V7.1 - User s Guide

11 Installing the INCA-MIP Add-on 2 Installing the INCA-MIP Add-on INCA-MIP is a functional extension of INCA. MATLAB uses dynamically linked function calls, so-called MEX files, to communicate with other applications. 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. INCA-MIP is packaged in two versions. The INCA-MIP Base API set is readily available after the installation. In order to use the INCA-MIP Extended API set a software license key is required. A list of APIs and the respective API set can be found in "The API Functions" on page System Requirements To use the INCA-MIP add-on, INCA must be installed on your computer. Please refer to the INCA Getting Started manual for the INCA system requirements. If you would like to develop MATLAB scripts yourself for accessing INCA, you also need a full MATLAB license. INCA-MIP V16 for INCA V7.1 requires the following program releases: INCA V7.1 Note INCA V7.1 is required for the installation of this INCA-MIP version. After installation you can use this INCA-MIP version to work with any INCA V7.x version (see Open INCA on page 34). MATLAB V6.5 or higher (for MATLAB integrated installation); only 32 bit versions of MATLAB are supported. If you require more detailed information on supported MATLAB releases please contact your INCA support. 2.2 Installing INCA-MIP from DVD Before installing the add-on it is necessary to determine the type of installation. The following types are possible: MATLAB integrated installation Select this option if you use one MATLAB version for developing MATLAB scripts. 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. For a more detailed description see below on page 12. 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. INCA-MIP V16.0 for INCA V7.1 - User s Guide 11

12 Installing the INCA-MIP Add-on ETAS If you would like to develop your own MATLAB scripts for accessing INCA, 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. Insert the DVD with the installation program into the DVD drive of your computer. If the installation routine does not start automatically, execute the autostart.exe program on the DVD manually. The DVD containing the installation program for INCA, tools and utilities, documentation, and further information, is started. Click Main. Select the INCA-MIP installation. Follow the instructions in the installation routine to install INCA-MIP on your computer. In the installation routine, 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. or Select the option Installation into ETASData if one of the following cases applies: 12 INCA-MIP V16.0 for INCA V7.1 - User s Guide

13 Installing the INCA-MIP Add-on You would like to use INCA-MIP with different MATLAB versions. 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. See your MATLAB user documentation on how to add directories to the MATLAB path. You would only like to run readily available MATLAB stand-alone executables created with MATLAB R13. Note You need the installation into ETASData if you use executable files that contain MATLAB commands for controlling INCA. In this case you do not need a MATLAB license. The executable files have to be provided by developers with a MATLAB installation (see "Creation and Distribution of Stand-alone Executable Files" on page 69). To license INCA-MIP: Continue with the installation routine. Should you plan to use the extended set of API functions, a software license file will be required. For information on licensing please refer to "Licensing the Software" on page Updating the Cache for MATLAB Toolbox directories After installing the INCA-MIP API, you should first update the cache for the MATLAB toolbox directories, in case this cache is enabled during your MATLAB installation. This is true for MATLAB V6 and higher if you are using the default settings; the cache was disabled in earlier releases. The cache needs to be updated so that the files used in INCA-MIP API are registered in MATLAB. See your MATLAB user documentation to update the cache for the MATLAB toolbox directories. 2.4 Disabling the Cache for MATLAB Toolbox Directories When working with the INCA-MIP API, it is recommended that you disable caching for the MATLAB toolbox directories. Otherwise, malfunctions may occur because either the INCA-MIP API or individual, newly added script files may not be found. As an alternative to disabling the caching, you can force the cache to update as described above while the cache is enabled. However, to avoid any faulty operation, it is recommended that you disable the cache while working with the INCA- MIP API. See your MATLAB user documentation for enabling or disabling the cache for the MATLAB toolbox directories. INCA-MIP V16.0 for INCA V7.1 - User s Guide 13

14 2.5 Licensing the Software To be able to work with an ETAS software product, you require a license. This section contains basic details on this subject. "ETAS License Models" on page 14 "How to get a License" on page 15 "The License File" on page 16 "Grace Mode" on page 18 "The "Expiration Warning" Window" on page 18 "Borrowing a License" on page 19 Details concerning the scope of the licenses and other legal aspects can be found in "Terms and Conditions" ETAS License Models There are three different license models available for licensing your ETAS software: Machine-d License, Local A license of this type is managed by the user him/herself. As it is linked to a particular PC (better: to the MAC address of the Ethernet adapter), it is valid wherever the PC is used. When you change your PC, you require a new license. User-d License, Server-Based The licenses (of a department or company) are managed centrally on a server by a designated person. The license is linked to the user name with which the user is registered in the network and is available on every PC in the network. If the relevant PC is disconnected from the network, the license can be "borrowed." Concurrent (or Floating) License, Server-Based Most of what is true of the user-named license applies to this type of license. The difference is that here several users share a limited number of licenses. 14 INCA-MIP V16.0 for INCA V7.1 - User s Guide

15 2.5.2 How to get a License If your company has a tool coordinator and server-based license management for ETAS software, contact this person. Otherwise (in the case of a machine-named license) you obtain your license from the ETAS license portal (the URL is shown on your Entitlement Certificate). There are three ways of logging in on the welcome page: Activation ID Once you have logged in, a specific activation 1 is visible and can be managed the activation ID is shown on your Entitlement Certificate. Entitlement ID All activations of the entitlement 2 are visible and can be managed (e.g. for a company with just one entitlement). and password All activations of the entitlements assigned to the user account are visible and can be managed (e.g. for a tool coordinator responsible for several entitlements). If you need help in the portal, click the Help link. What Information is required? Information on the hosts must be entered to activate licenses: Machine-named license The MAC address of the Ethernet adapter to which the license is to be bound is required here User-named license Here, you need a server host or a server triad as well as a user name Concurrent (floating) license Here, you need a server host or a server triad. Note If this data changes (e.g. due to changes in the hardware or a change of user), the license must be given a "rehost". This procedure is also described in the portal help file. 1. The activations refer to a specific product, its license conditions, the available number of licenses and other details required for generating a license. Activations are identified uniquely with activation IDs. 2. An entitlement shows the authorizations you have as a user; it stands for the right to own one or more licenses for a product. It is a kind of account of rights of use for software from which you can take licenses as you need to. INCA-MIP V16.0 for INCA V7.1 - User s Guide 15

16 License File The result of your activities is the provision of a file <name>.lic with which you can license your software in the ETAS License Manager The License File To check to license status In the Windows Start menu, select Programs ETAS License Management ETAS License Manager. Click Continue. The ETAS License Manager contains one entry for each installed product. The symbol at the beginning of the entry and the "Status" column entry indicate whether a valid license has already been obtained or not. 16 INCA-MIP V16.0 for INCA V7.1 - User s Guide

17 To add a license file Open the ETAS License Manager (cf. page 16) and select File Add Licensing File. The "Install License" dialog window opens. Next to the "Select License File" field click the... button. In the file selection window, select the license file and click Open. The "Install License" dialog window shows information on the selected license. Note The "Version" column shows the version number of the license, not the version number of the software. Confirm with OK. The license just added is now listed in the ETAS License Manager. A green symbol before the entry shows that the license is valid. Note If the green symbol is not displayed, there might be a problem with the license file or the license relates to another product. Additional information on the ETAS License Manager can be found in the online help of the ETAS License Manager. INCA-MIP V16.0 for INCA V7.1 - User s Guide 17

18 2.5.4 Grace Mode Close the ETAS License Manager. If you have not yet installed a license, you can still operate the software for a limited amount of time it then runs in what is referred to as grace mode. The window shows you how long you can continue to operate the software in this mode The "Expiration Warning" Window If your installed license runs out in the next 30 days, a warning is shown when you open the ETAS software. The "Expiration Warning" window contains a list of licenses that expire in the next 30 days. The expiration date is shown for each license; in the case of borrowed licenses (see "Borrowing a License" on page 19) it also shows when the borrowing period expires (i.e. the date when borrow mode runs out). Click Manage Licenses to open the ETAS License Manager and install a valid license file. As soon as you have installed a valid license, you can continue to operate the ETAS software in normal operating mode. Click Ignore to close the dialog box and start the ETAS software. This is only possible during the grace period; as soon as the grace period has expired, you can only continue to use the ETAS software once you have installed a valid license file. As soon as the expiration date has been reached, you can continue to use the ETAS software for a further 14 days in what is referred to as limited mode (see "Grace Mode" on page 18). Once this phase is over, the ETAS software can only be used when a new or updated license file has been installed. 18 INCA-MIP V16.0 for INCA V7.1 - User s Guide

19 2.5.6 Borrowing a License The borrowing mechanism makes it possible to work offline even when using a server-based license (i.e. without being connected to the license server). Note You can only borrow a license if a server-based license is being used! To borrow a license, proceed as follows: To borrow a license Make sure that the ETAS software the license of which you want to borrow is not open. Select the license you want to borrow in the "License Listing" table of the ETAS License Manager. Select License Borrow license. The "Select Borrow end date" dialog box opens. INCA-MIP V16.0 for INCA V7.1 - User s Guide 19

20 Select the date until which you want to borrow the license from the calendar displayed and click OK. The text in the "Source" column of the ETAS License Manager changes from "SERVER" to "BOR- ROW", and the expiration date of the borrowed license is displayed. You can now use the relevant ETAS software offline until the expiration date of the borrowed license has been reached. If you want to use the ETAS software longer than you had originally planned, you can borrow the license again. If you stop using the ETAS software earlier than planned, you can return the license to the license server early (License Return License Early). A borrowed license can only be returned by the person that borrowed it; it cannot be returned by another person Customizing the Network Installation You can change certain default settings before conducting the network installation; this also includes the access to the required licenses. The customization of the installation is done by adjusting the configuration file install.ini, which is located in the installation directory of the product to be installed. 20 INCA-MIP V16.0 for INCA V7.1 - User s Guide

21 INCA-MIP Change Log 3 INCA-MIP Change Log Starting with INCA-MIP V16.0 for INCA V7.1, this chapter lists for each new version of INCA-MIP which API functions have been added, changed, removed, or which are deprecated. 3.1 Changes Introduced with INCA-MIP V16.0 for INCA V7.1 New API functions IncaGetInstalledProductInfo (page 30): Provides information on all INCA versions that are installed on the system. Note This command only works reliably if INCA V7.1 or higher is installed. IncaGetInstalledAddOnInfo (page 31): Provides information on all add-ons that are installed for a given product and version. Note This command only works reliably if INCA V7.1 or higher is installed. IncaClose (page 34): Closes INCA after it has been opened with IncaOpen. After Inca- Close, another IncaOpen can be used to connect to INCA again (e.g. in order to connect to a different INCA version). IncaGetRecordingMode (page 46): Indicates whether a signal is recorded in the default recorder or not. IncaSetRecordingMode (page 47): Enables or disables the recording of a signal in the default recorder. Changed API functions IncaOpen (page 34): The IncaOpen command gets a new, optional parameter 'version', which contains a string consisting of <MajorVersion>.<MinorVersion>. This makes it possible to launch a specific INCA version from within INCA- MIP (respecting the restrictions of INCA-MIP that compatibility between INCA-MIP and INCA is only given for installations with the same major version). IncaAddMeasureElement (page 41): For the input argument group, an empty parameter [] can be used. This is required if you want to use calculated signals or monitoring signals for measurement or recording. INCA-MIP V16.0 for INCA V7.1 - User s Guide 21

22 INCA-MIP Change Log ETAS IncaGetRecords (page 49): Two input arguments last and exact have been added. These specify if the latest or oldest records shall be transmitted, and if they should be also transmitted if less than the specified number of records are available in the ring buffer. Moreover, the optional output argument state has been added, which indicates whether records have been successfully received or the reason why they have not. IncaAddCalibrationElement (page 58): This function now also support calibration elements of the types axis or group axis. For group axes no interpolation of the dependent curves and maps is executed. IncaGetRecordingProperties (page 43): In IncaGetRecordingProperties the following measure data format IDs are returned: ETASBinary #DiademATF ETASAscii ETASGroupAscii ETASMATLABMFILE ETASGroupMatlabM FamosRecord ETASMDF ETASMDF4 Depending on the INCA settings, the string (empty string) may also be returned. This corresponds to None in the recording properties. IncaSetRecordingProperties (page 45): In IncaSetRecordingProperties the following measure data format IDs are used: ETASBinary #DiademATF ETASAscii ETASGroupAscii ETASMATLABMFILE ETASGroupMatlabM FamosRecord ETASMDF ETASMDF4 The following measure data format IDs (incl. spaces) are deprecated: ETAS binary data file format Diadem ATF measure format (write only) 22 INCA-MIP V16.0 for INCA V7.1 - User s Guide

23 INCA-MIP Change Log 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) Removed API functions none Deprecated API functions none INCA-MIP V16.0 for INCA V7.1 - User s Guide 23

24 The API Functions ETAS 4 The API Functions INCA-MIP provides a number of API functions for automating INCA processes. Some functions are available in the INCA-MIP Base package, others can be used only if you have purchased the INCA-MIP Extended package. Note Commands which are available only through INCA-MIP Extended are protected by a software license key. Should you use an Extended API function without a valid software license, MATLAB script execution will throw an exception. As a development guideline we recommend that prior to using INCA-MIP Extended commands, you verify the validity of the license by means of the IncaIsLicenseValid command. The following table lists all INCA-MIP API functions which are available in the add-on for INCA V7.1. It indicates whether the function is also available in the INCA-MIP Base package or only in the INCA-MIP Extended package; whether the function is used for initialization, measuring, calibrating, memory page management or whether it is a more general function; where in this document you can find more information about the corresponding function.. Tab. 4-1 INCA-MIP API functions Function Base a Ext. b Category refer to IncaAddCalibrationElement x x Calibration page 58 IncaAddMeasureElement x x Measuring page 41 IncaBrowseCalibrationElements x Calibration page 57 IncaBrowseItemsInFolder x Initialization page 35 IncaBrowseMeasureElements x Measuring page 40 IncaClose x Initialization page 34 IncaCopyPageFromTo x x MemoryPage- page 66 Manager IncaDatabaseImport x Initialization page 35 IncaDownloadDifferences x x MemoryPage- page 67 Manager IncaDownloadPage x x MemoryPage- page 66 Manager IncaExecuteManualTrigger x Measuring page 55 IncaGetCalibrationValue x x Calibration page 58 IncaGetCurrentPage x MemoryPage- page 65 Manager IncaGetDatasetsForDevice x Calibration page 62 IncaGetDeviceProperties x Initialization page 39 IncaGetDevices x Initialization page INCA-MIP V16.0 for INCA V7.1 - User s Guide

25 The API Functions Tab. 4-1 INCA-MIP API functions Function Base a Ext. b Category refer to IncaGetHardwareStatus x Measuring page 52 IncaGetInstalledAddOnInfo x x General page 31 IncaGetInstalledProductInfo x x General page 30 IncaGetMeasureRatesForDevice x Measuring page 41 IncaGetProperties x General page 32 IncaGetRecordingMode x Measuring page 46 IncaGetRecordingProperties x Measuring page 43 IncaGetRecordingState x Measuring page 55 IncaGetRecords x x Measuring page 49 IncaGetRecordStruct x Measuring page 55 IncaGetVersion x x General page 32 IncaGroupDevices x Calibration page 63 IncaIsLicenseValid x General page 30 IncaMessageIds x x General page 28 IncaIsPageWriteProtected x x Memory- page 65 PageManager IncaOpen x x Initialization page 34 IncaOpenDatabase x x Initialization page 34 IncaOpenExperiment x x Initialization page 37 IncaResetExperiment x x Initialization page 38 IncaResetRecords x x Measuring page 51 IncaSetCalibrationMode x Calibration page 63 IncaSetCalibrationValue x x Calibration page 60 IncaSetDatasetInDevice x Calibration page 62 IncaSetMeasureReadMode x x Measuring page 49 IncaSetProjectAndDatasetInDevice x Initialization page 36 IncaSetRecordingMode x Measuring page 47 IncaSetRecordingProperties x Measuring page 45 IncaSetTrigger x Measuring page 52 IncaShowMessages x x General page 30 IncaStartMeasurement x x Measuring page 43 IncaStartRecording x x Measuring page 48 IncaStopMeasurement x x Measuring page 43 IncaStopRecording x x Measuring page 48 IncaSwitchPage x x MemoryPage- Manager page 65 INCA-MIP V16.0 for INCA V7.1 - User s Guide 25

26 The API Functions ETAS Tab. 4-1 INCA-MIP API functions Function Base a Ext. b Category refer to IncaUploadPages x MemoryPage- page 67 Manager IncaWriteToFile x Calibration page 64 a Function is supported in INCA-MIP Base Package b Function is supported in INCA-MIP Extended Package In this manual, the function descriptions are ordered according to their application area: "General Functions" on page 28 "Initialization" on page 33 "Measuring and Recording" on page 40 "Calibrating" on page 57 "Memory Page Manager" on page 65 Moreover, a number of sample files are provided. These are described under "Getting to know the INCA-MIP API through Sample Files" on page 27. Application examples are given under "Application " on page 68. Note The INCA-MIP Interface always operates on the global settings of the INCA User Options. For further information on INCA User Options please see the INCA Documentation. 26 INCA-MIP V16.0 for INCA V7.1 - User s Guide

27 The API Functions 4.1 Getting to know the INCA-MIP API through Sample Files INCA-MIP comes with a group of examples. These sample files are automatically installed on your computer in addition to the MEX files. The sample files use several examples to demonstrate the use of the INCA-MIP API. The examples include a number of M files that access the INCA-MIP API, as well as an INCA database where the elements used in the sample scripts have already been created. The sample files are copied into the following directories during the installation (see "Installing INCA-MIP from DVD" on page 11): For installation into MATLAB: M files: %MatlabDir%\toolbox\matlab\demos For installation into ETASData: M files: %EtasDataDir%\INCA-MIP INCA demo database: %EtasDataDir%\Database\db_matlabtest To use the sample files, you must first start INCA and open the sample database. No hardware is required. The function of the M files is described below. topen.m establishes a connection between INCA and MATLAB. This function must be used at the start of each MATLAB session before using any other function of the INCA-MIP API. tdummy.m opens an empty INCA experiment using a hardware configuration with the VADI test device. The script creates several measurement variables in the INCA experiment. tetkdummy.m opens an empty INCA experiment using a hardware configuration with the ETK test device. This script creates several measurement and calibration variables in the INCA experiment. It also downloads the working and reference pages, reads the measurement and calibration variables, and modifies the values for individual calibration variables. tgetrecords(agroup).m gathers the measured data for the agroup group for 20 seconds and then passes the data to MATLAB. This function can be used both in connection with the VADI and ETK example (for measure rasters, see "INCA Glossary" on page 9.) tprintdb ({afolder{, afileid}}).m Writes the complete contents of the database beginning with directory afolder to the file afileid. If the function is executed without parameters, the complete database hierarchy is printed to the standard output. thwstatus.m Example for using the API function IncaGetHardwareStatus. MATLAB attaches to an already opened experiment and chooses the first measurement element found in the first measurement device found. It continues with a measurement of 5 minutes. If there is a warning or error during the measurement the measurement cycle gets aborted and restarted after a delay of 5 seconds. INCA-MIP V16.0 for INCA V7.1 - User s Guide 27

28 The API Functions ETAS 4.2 General Functions The following general API functions are available: List INCA-MIP Interface Message IDs INCA-MIP Interface commands may return with an error. When using try/catch blocks, detailed error information can be returned. Example try, <command_1>... <command_n> catch, [msgstr,msgid] = lasterr... end whereas: msgstr a descriptional string msgid the message id. 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 INCA:RecordingInProcess INCA:NotInstalled INCA:WrongVersion Hints for reaction on error ids: INCA:ParameterError Wrong number of input arguments (right hand side parameters) INCA:ReturnParameterError Wrong number of output arguments (left hand side parameters) INCA:WrongParameterValue INCA:WrongParameterType Any of the values of the input arguments is out of its valid range or specification Any of the input arguments has a wrong data type 28 INCA-MIP V16.0 for INCA V7.1 - User s Guide

29 The API Functions INCA:NaN INCA:ExecutionError INCA:ResourceError INCA:RasterFull The acquisition list is full for the requested measure raster when trying to add a measurement INCA:ObjectIsWriteProtected INCA:CallSeqenceError INCA:LicenseError INCA:RecordingInProcess INCA:NotInstalled INCA:WrongVersion Any of the parameters contains a 'not a number' value During the command execution an error occurred for some reason. Trying to execute functionality on the INCA user interface could give more information about the reason. Restarting INCA or a reboot could also help. Unable to get operating system resources. Restarting INCA or a reboot could help. Unable to calibrate because of a write protected object Before executing the requested command other commands have to be executed first. E.g. IncaOpenExperiment is necessary before IncaAddMeasureElement. To execute the command with the given parameters a license is needed It is not possible to execute the requested command (e.g. enable or disable signals for recording using IncaSetRecordingMode) because a recording is currently running. It is not possible to open the specified INCA version using the IncaOpen command because the corresponding INCA version is not installed. It is not possible to open the specified INCA version using the IncaOpen command because of one of the following reasons: INCA is already started and an IncaOpen command is executed with a 'version' parameter different from the already opened INCA version An IncaOpen command is executed from within INCA-MIP for INCA Vx.y with a 'version' parameter with major version!= x. INCA-MIP V16.0 for INCA V7.1 - User s Guide 29

30 The API Functions ETAS Show Messages During Script Execution IncaShowMessages Enables/disables the information display in the MATLAB window during script execution IncaShowMessages(trueOrFalse) trueorfalse Numerical parameter whose value either equals or does not equal zero. If the parameter is zero, the information display is disabled, otherwise it is enabled (default) Show whether Valid INCA-MIP License exists (INCA-MIP Extended) IncaIsLicenseValid Returns a status indicating whether a valid INCA-MIP license is available or not s = IncaIsLicenseValid s License status: 0: no valid license 1: valid license status = IncaIsLicenseValid Read Information on All Installed INCA Versions IncaGetInstalledProductInfo Provides information on all installed INCA versions. This command can be executed before IncaOpen. info = IncaGetInstalledProductInfo info info.name info.version Information on installed INCA versions as MATLAB struct for each installation, consisting of the following entries: the product name the product version string 30 INCA-MIP V16.0 for INCA V7.1 - User s Guide

31 The API Functions info.hotfixve rsion the installed hotfix as string, or an empty string if no hotfix is installed i = IncaGetInstalledProductInfo; Note This command only works reliably if INCA V7.1 or higher is installed Read Information on All Installed Product Add-Ons IncaGetInstalledAddOnInfo Provides information on all installed add-ons for a given product. This command can be executed before IncaOpen. info = IncaGetInstalledAddOnInfo(product, productversion) info info.name info.version product productversio n Information on installed add-ons as MATLAB struct for each installation, consisting of the following entries: the name of the installed add-on the version string of the installed add-on the name of the product the product version as string. The whole version string is relevant. i = IncaGetInstalledAddOnInfo('INCA', 'V7.0.0'); i = IncaGetInstalledAddOnInfo('INCA', 'V7.1.0 Beta 42'); Note Make sure that you use for the input arguments product and productversion exactly the name and version of a product as returned by IncaGetInstalledProductInfo. Note This command only works reliably if INCA V7.1 or higher is installed. INCA-MIP V16.0 for INCA V7.1 - User s Guide 31

32 The API Functions ETAS Read INCA Version IncaGetVersion Returns the INCA version IncaGetVersion Read INCA Properties (INCA-MIP Extended) IncaGetProperties Reads properties of INCA p = IncaGetProperties p p = IncaGetProperties; Properties of INCA as MATLAB struct, consisting of the following entries: p.databasepath - Pathname of the open INCA database. If no INCA database is open an empty string is returned. p.datapath - Pathname of the INCA data directory. p.installationpath - Pathname of the INCA installation directory. p.temppath - Pathname of the directory which is used by ETAS applications for temporary files. 32 INCA-MIP V16.0 for INCA V7.1 - User s Guide

33 The API Functions 4.3 Initialization All measurement and calibration operations in INCA will be performed within the context of an experiment. Before opening an experiment, a workspace with a valid hardware configuration must first be created and assigned. To work with the INCA-MIP API, there must an empty experiment in the INCA database which is linked to a valid workspace and hardware configuration. The experiment can be opened from within MATLAB. The following API functions are available for initializing: INCA-MIP V16.0 for INCA V7.1 - User s Guide 33

34 The API Functions ETAS Open INCA IncaOpen Opens INCA and initialize the connection between MATLAB and INCA. IncaOpen IncaOpen( version ) version IncaOpen; IncaOpen('7.1'); INCA version to be opened (optional). : <MajorVersion>.<MinorVersion>. INCA-MIP for INCA x.y can only connect to INCA installations with the same major version x Close INCA (INCA-MIP Extended) IncaClose Closes INCA after having successfully connected to INCA with IncaOpen. IncaClose IncaClose; Open a Database IncaOpenDatabase Opens the database in the specified directory IncaOpenDatabase({path}) path The directory in which the database to be opened is stored. If you do not specify a directory, the current database is opened. IncaOpenDatabase;% open current database IncaOpenDatabase( c:\etasdata\mydatabase ); 34 INCA-MIP V16.0 for INCA V7.1 - User s Guide

35 The API Functions Import a Database (INCA-MIP Extended) IncaDatabaseImport Imports a database export file (*.exp) into INCA. Existing database items will always be overwritten. IncaDatabaseImport(path) name = IncaDatabaseImport(path) [name, type] = IncaDatabaseImport(path) name Array of the full path names of all imported database items type use deblank() when accessing an array element: name2 = deblank(name(2,:)) 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 path use deblank() when accessing an array element: type2 = deblank(type(2,:)) The full path of the *.exp file to be imported names = IncaDatabaseImport('D:\ ETASData\INCA7.1\export\Project0815.exp') Read Database Items (INCA-MIP Extended) IncaBrowseItemsInFolder Reads database items in the given database folder with a search pattern [name, type] = IncaBrowseItemsInFolder(pattern, folder) 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 INCA-MIP V16.0 for INCA V7.1 - User s Guide 35

36 The API Functions ETAS pattern folder Search pattern for database entries to look for. A * matches zero or any number of additional characters. A # matches exactly one character. All other characters have to match with the database items. There is no difference between lower and upper case. Database folder in which the database items are read. Folder hierarchies are separated by a \. An empty string is used for the upper most hierarchy level. [n,t]=incabrowseitemsinfolder( *, DEFAULT\MyProject ); [name,type]=incabrowseitemsin- Folder( Prj*_##, ); Assign Project and Dataset in Device (INCA-MIP Extended) IncaSetProjectAndDatasetInDevice Assigns a project and dataset to a device in a given workspace. This can only be done if no experiment is currently opened. IncaSetProjectAndDatasetInDevice(workspace, device,project,dataset) workspace database path of workspace device name of device project database path of project dataset database path of dataset IncaSetProjectAndDatasetInDevice('DEFAULT\ workspace','etk:1','default\prj0815','ds4711\ Ds4711_3') 36 INCA-MIP V16.0 for INCA V7.1 - User s Guide

37 The API Functions 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. IncaOpenExperiment Opens 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. IncaOpenExperiment({closeAllViewsFlag}) or IncaOpenExperiment(expFolder, experiment, workspacefolder, workspace {, closeallviewsflag}) expfolder experiment workspacefolder- workspace directory in which the experiment is stored name of the experiment directory in which the workspace is stored name of the workspace closeallviewsflag 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 ); INCA-MIP V16.0 for INCA V7.1 - User s Guide 37

38 The API Functions ETAS Reset an Experiment IncaResetExperiment Resets and closes the current experiment. You can use this function to remove all variables from an experiment. Removing individual variables is currently not supported. IncaResetExperiment 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 Read Devices (INCA-MIP Extended) IncaGetDevices Reads all devices in the experiment [name, type] = IncaGetDevices name List of names of the devices type List of device types: WorkbaseDevice: Device with datasets MeasurementDevice: Measurement device [name,type]=incagetdevices; 38 INCA-MIP V16.0 for INCA V7.1 - User s Guide

39 The API Functions Read Device Properties (INCA-MIP Extended) IncaGetDeviceProperties Reads properties of a device p = IncaGetDeviceProperties(device) p p.name p.descriptionfile p.binaryfile Device properties as MATLAB struct, consisting of the following entries: device name 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. 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.iswriteprotected 0: Device has no memory pages or current page is not write protected 1: Current page is write protected p.isactive 0: Device is not connected or not active 1: Device is connected and active p.isworkbasedevice 0: Device has no datasets 1: Device has datasets device name of the device p = IncaGetDeviceProperties( Device ); INCA-MIP V16.0 for INCA V7.1 - User s Guide 39