INCA-MIP V7.0 User s Guide

Transcription

1 INCA-MIP V7.0 User s Guide

2 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 2010 ETAS GmbH, Stuttgart, Germany The names and designations used in this document are trademarks or brands belonging to the respective owners. Document AM R7.0.0 EN 2

3 Contents 1 fåíêççìåíáçå=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= T 1.1 ^Äçìí=íÜáë=j~åì~ä==K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= U 1.2 qóéçöê~éüáå=`çåîéåíáçåë==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= U 1.3 fk`^=däçëë~êó=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= V 2 fåëí~ääáåö=íüé=fk`^jjfm=^ççjçå =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NN 2.1 póëíéã=oéèìáêéãéåíë==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= NN 2.2 fåëí~ääáåö=fk`^jjfm=ñêçã=asa= =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NN 2.3 réç~íáåö=íüé=`~åüé=ñçê=j^qi^_=qççääçñ=çáêéåíçêáéë=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= NP 2.4 aáë~ääáåö=íüé=`~åüé=ñçê=j^qi^_=qççääçñ=aáêéåíçêáéë= =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NP 2.5 iáåéåëáåö=íüé=pçñíï~êé==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= NQ bq^p=iáåéåëé=jççéäë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NQ eçï=íç=öéí=~=iáåéåëé K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NR qüé=iáåéåëé=cáäé=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= NS dê~åé=jççé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NU qüé=?bñéáê~íáçå=t~êåáåö?=táåççï K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NU _çêêçïáåö=~=iáåéåëé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= NV `ìëíçãáòáåö=íüé=kéíïçêâ=fåëí~ää~íáçå =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= OM 3 qüé=^mf=cìååíáçåë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= ON 3.1 déííáåö=íç=âåçï=íüé=fk`^jjfm=^mf=íüêçìöü=p~ãéäé=cáäéë= =K=K=K=K=K=K=K=K=K=K=K=K=K=K= OQ 3.2 déåéê~ä=cìååíáçåë=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= OR iáëí=fk`^jjfm=fåíéêñ~åé=jéëë~öé=faë=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= OR püçï=jéëë~öéë=aìêáåö=påêáéí=bñéåìíáçå =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= OT püçï=ïüéíüéê=s~äáç=fk`^jjfm=iáåéåëé=éñáëíë= =Efk`^Jjfm=bñíÉåÇÉÇFOT oé~ç=fk`^=séêëáçå =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= OT oé~ç=fk`^=mêçééêíáéë =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFOT 3.3 fåáíá~äáò~íáçå= =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= OV lééå=fk`^=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= PM Contents 3

4 3.3.2 lééå=~=a~í~ä~ëék=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= PM fãéçêí=~=a~í~ä~ëék=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfpm oé~ç=a~í~ä~ëé=fíéãë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFPO ^ëëáöå=mêçàéåí=~åç=a~í~ëéí=áå=aéîáåé=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfpo lééå=~å=bñééêáãéåí=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= PP oéëéí=~å=bñééêáãéåí =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= PP oé~ç=aéîáåéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFPQ oé~ç=aéîáåé=mêçééêíáéë =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFPQ 3.4 jé~ëìêáåö=~åç=oéåçêçáåö= K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= PS oé~ç=jé~ëìêéãéåí=bäéãéåíëk=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfpt oé~ç=jé~ëìêé=o~ëíéêë=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfpt ^ÇÇ=jÉ~ëìêÉãÉåí=s~êá~ÄäÉ=íç=jÉ~ëìêÉ=o~ëíÉêK=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= PT pí~êí=jé~ëìêéãéåí=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= PV píçé=jé~ëìêéãéåí =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= PV oé~ç=oéåçêçáåö=mêçééêíáéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFPV péí=oéåçêçáåö=mêçééêíáéë=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfqn pí~êí=oéåçêçáåö=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= QP píçé=oéåçêçáåö=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= QP péí=a~í~=oé~çáåö=jççé=elåäáåé=l=lññäáåé=a~í~f =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= QQ oé~ç=jé~ëìêé=a~í~ K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= QQ oéëéí=oáåö=_ìññéêk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= QS oé~ç=e~êçï~êé=pí~íìë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFQS péí=qêáööéê==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfqt bñéåìíé=j~åì~ä=qêáööéê K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFQV oé~ç=oéåçêçáåö=pí~íé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFQV oé~ç=iáëí=çñ=jé~ëìêéãéåí=s~êá~ääéëk=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfqv 3.5 `~äáäê~íáåö==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= RN oé~ç=`~äáäê~íáçå=bäéãéåíëk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfro ^ÇÇ=`~äáÄê~íáçå=bäÉãÉåí=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= RO oé~ç=`~äáäê~íáçå=s~äìé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= RQ `Ü~åÖÉ=`~äáÄê~íáçå=s~äìÉ =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= RS ^ëëáöå=a~í~ëéí=íç=aéîáåé K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFRU iáëí=a~í~ëéíë=çñ=~=aéîáåé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFRU péí=`~äáäê~íáçå=jççék=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfru dêçìé=aéîáåéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFRV têáíé=a`j=cáäé=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=efk`^jjfm=bñíéåçéçfrv 3.6 jéãçêó=m~öé=j~å~öéê= =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SN ^Åíáî~íÉ=jÉãçêó=m~ÖÉK=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SO déí=`ìêêéåí=m~öé =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFSO `ÜÉÅâ=têáíÉJmêçíÉÅíáçå K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SO açïåäç~ç=jéãçêó=m~öé K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SP `çéó=jéãçêó=m~öé K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SP açïåäç~ç=aáññéêéååéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= SP réäç~ç=m~öéë =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=Efk`^Jjfm=bñíÉåÇÉÇFSQ 3.7 ^ééäáå~íáçå=bñ~ãéäéë==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= SR 4 `êé~íáçå=~åç=aáëíêáäìíáçå=çñ=pí~åçj~äçåé=bñéåìí~ääé=cáäéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= ST 4.1 `êé~íáçå=~åç=aáëíêáäìíáçå=çñ=pí~åçj~äçåé=bñéåìí~ääé=cáäéë=ìëáåö=íüé= j^qi^_ onp=`çãéáäéê= K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= ST 4 Contents

5 4.1.1 `çãéáä~íáçå=çñ=ãjcáäéëk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= ST aáëíêáäìíáçå=çñ=pí~åçj~äçåé=bñéåìí~ääé=cáäéëk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= SU 4.2 `êé~íáçå=~åç=aáëíêáäìíáçå=çñ=pí~åçj~äçåé=bñéåìí~ääé=cáäéë=ìëáåö=íüé= j^qi^_ onq=`çãéáäéê=çê=eáöüéê==k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= SV `çãéáä~íáçå=çñ=ãjcáäéëk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= SV aáëíêáäìíáçå=çñ=pí~åçj~äçåé=bñéåìí~ääé=cáäéëk=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k=k= SV 5 méêñçêã~ååé K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= TN 6 bq^p=`çåí~åí=^ççêéëëéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= TP q~ääéë K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= TR fåçéñ =K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K=K= TT Contents 5

6 6 Contents

7 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. Introduction 7

8 1.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. 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.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. 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}) Output : value Current value of the calibration variable; it must match the data types specified below: på~ä~êëw=~=eninf=ã~íêáñ `ìêîéëw=~å=eñinf=ã~íêáñ j~éëw=~å=eñióf=ã~íêáñ _êé~â=éçáåí=çáëíêáäìíáçåëw= ~å=eñinfjã~íêáñ : 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: vw=î~äìé xw=ñ=äêé~â=éçáåí=eåìêîéë=~åç=ã~éë yw=ó=äêé~â=éçáåí=eã~éëf 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 Introduction

9 1.3 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. 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 Introduction 9

10 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 Introduction

11 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 V7.0 requires the following program releases: INCA V7.0 or higher INCA V7.x version 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. 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. Installing the INCA-MIP Add-on 11

12 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: 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. 12 Installing the INCA-MIP Add-on

13 You would only like to run readily available MATLAB stand-alone executables created with MATLAB R13. kçíé 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 67). 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. Installing the INCA-MIP Add-on 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

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. kçíé 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. 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

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. kçíé 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. kçíé 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. 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

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). kçíé 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. 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

21 3 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. kçíé 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.0. 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. 3-1 INCA-MIP API functions Function Base a Ext. b Category refer to IncaAddCalibrationElement x x Calibration page 52 IncaAddMeasureElement x x Measuring page 37 IncaBrowseCalibrationElements x Calibration page 52 IncaBrowseItemsInFolder x Initialization page 32 IncaBrowseMeasureElements x Measuring page 37 IncaCopyPageFromTo x x MemoryPageManager page 63 IncaDatabaseImport x Initialization page 30 IncaDownloadDifferences x x MemoryPageManager page 63 IncaDownloadPage x x MemoryPageManager page 63 IncaExecuteManualTrigger x Measuring page 49 IncaGetCalibrationValue x x Calibration page 54 IncaGetCurrentPage x MemoryPageManager page 62 IncaGetDatasetsForDevice x Calibration page 58 IncaGetDeviceProperties x Initialization page 34 IncaGetDevices x Initialization page 34 IncaGetHardwareStatus x Measuring page 46 The API Functions 21

22 Tab. 3-1 INCA-MIP API functions Function Base a Ext. b Category refer to IncaGetMeasureRatesForDevice x Measuring page 37 IncaGetProperties x General page 27 IncaGetRecordingProperties x Measuring page 39 IncaGetRecordingState x Measuring page 49 IncaGetRecords x x Measuring page 44 IncaGetRecordStruct x Measuring page 49 IncaGetVersion x x General page 27 IncaGroupDevices x Calibration page 59 IncaIsLicenseValid x General page 27 IncaMessageIds x x General page 25 IncaIsPageWriteProtected x x MemoryPageManager page 62 IncaOpen x x Initialization page 30 IncaOpenDatabase x x Initialization page 30 IncaOpenExperiment x x Initialization page 33 IncaResetExperiment x x Initialization page 33 IncaResetRecords x x Measuring page 46 IncaSetCalibrationMode x Calibration page 58 IncaSetCalibrationValue x x Calibration page 56 IncaSetDatasetInDevice x Calibration page 58 IncaSetMeasureReadMode x x Measuring page 44 IncaSetProjectAndDatasetInDevice x Initialization page 32 IncaSetRecordingProperties x Measuring page 41 IncaSetTrigger x Measuring page 47 IncaShowMessages x x General page 27 IncaStartMeasurement x x Measuring page 39 IncaStartRecording x x Measuring page 43 IncaStopMeasurement x x Measuring page 39 IncaStopRecording x x Measuring page 43 IncaSwitchPage x x MemoryPageManager page 62 IncaUploadPages x MemoryPageManager page 64 IncaWriteToFile x Calibration page 59 a Function is supported in INCA-MIP Base Package b Function is supported in INCA-MIP Extended Package 22 The API Functions

23 In this manual, the function descriptions are ordered according to their application area: "General Functions" on page 25 "Initialization" on page 29 "Measuring and Recording" on page 36 "Calibrating" on page 51 "Memory Page Manager" on page 61 Moreover, a number of sample files are provided. These are described under "Getting to know the INCA-MIP API through Sample Files" on page 24. Application examples are given under "Application " on page 65. kçíé 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. The API Functions 23

24 3.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 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 MAT- LAB. 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. 24 The API Functions

25 3.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 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 INCA:NaN 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 Any of the parameters contains a 'not a number' value The API Functions 25

26 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 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 26 The API Functions

27 3.2.2 Show Messages During Script Execution Output IncaShowMessages Enable/disable 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) Output IncaIsLicenseValid Return a status indicating whether a valid INCA-MIP license is available or not s = IncaIsLicenseValid s license status: 0W=åç=î~äáÇ=äáÅÉåëÉ 1W=î~äáÇ=äáÅÉåëÉ status = IncaIsLicenseValid Read INCA Version Output IncaGetVersion Return the INCA version IncaGetVersion Read INCA Properties (INCA-MIP Extended) IncaGetProperties Read properties of INCA p = IncaGetProperties The API Functions 27

28 Output p p = IncaGetProperties; Properties of INCA as MATLAB struct, consisting of the following entries: p.databasepath=j=m~íüå~ãé=çñ=íüé= çééå=fk`^=ç~í~ä~ëék=fñ=åç=fk`^=ç~í~j Ä~ëÉ=áë=çéÉå=~å=Éãéíó=ëíêáåÖ=áë=êÉíìêåÉÇK p.datapath=j=m~íüå~ãé=çñ=íüé=fk`^= Ç~í~=ÇáêÉÅíçêóK p.installationpath=j=m~íüå~ãé=çñ= íüé=fk`^=áåëí~ää~íáçå=çáêéåíçêók p.temppath=j=m~íüå~ãé=çñ=íüé=çáêéåj íçêó=ïüáåü=áë=ìëéç=äó=bq^p=~ééäáå~íáçåë= Ñçê=íÉãéçê~êó=ÑáäÉëK 28 The API Functions

29 3.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: The API Functions 29

30 3.3.1 Open INCA Output IncaOpen Open INCA and initialize the connection between MATLAB and INCA. IncaOpen Open a Database Output IncaOpenDatabase Open 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 ); Import a Database (INCA-MIP Extended) Output IncaDatabaseImport Import 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 use deblank() when accessing an array element: name2 = deblank(name(2,:)) 30 The API Functions

31 type Array of types of all imported database items Possible values are: FolderW=~=Ç~í~Ä~ëÉ=ÑçäÇÉê ExperimentW=~å=bñéÉêáãÉåí=båîáêçåJ ãéåí WorkspaceW=~=tçêâëé~ÅÉ Asap2ProjectW=~å=^p^mO=mêçàÉÅí MeasurementCatalogW=~å=^p^mO= jé~ëìêéãéåí=`~í~äçö CanDBW=~å=^p^mO=`^k=a_ 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.0\export\Project0815.exp') The API Functions 31

32 3.3.4 Read Database Items (INCA-MIP Extended) IncaBrowseItemsInFolder Read database items in the given database folder with a search pattern [name, type] = IncaBrowseItemsInFolder(pattern, folder) Output name List of names of the database items type List of types of the database items: FolderW=a~í~Ä~ëÉ=ÑçäÇÉê ExperimentW=bñéÉêáãÉåí WorkspaceW=tçêâëé~ÅÉ Asap2ProjectW=^p^mO=mêçàÉÅí 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) Output IncaSetProjectAndDatasetInDevice Assign 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') 32 The API Functions

33 3.3.6 Open an Experiment kçíé 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. Output IncaOpenExperiment 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. 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: 1W=ÅäçëÉë=~ää=ïáåÇçïë=EÇÉÑ~ìäíF 0W=äÉ~îÉë=íÜÉ=ïáåÇçïë=ìåÅÜ~åÖÉÇK IncaOpenExperiment( ExpFolder, MyExperiment, WorkspaceFolder, MyWorkspace ); Reset an Experiment IncaResetExperiment 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. IncaResetExperiment The API Functions 33

34 Output kçíé 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) Output IncaGetDevices Read all devices in the experiment [name, type] = IncaGetDevices name List of names of the devices type List of device types: WorkbaseDeviceW=aÉîáÅÉ=ïáíÜ= Ç~í~ëÉíë MeasurementDeviceW=jÉ~ëìêÉãÉåí= ÇÉîáÅÉ [name,type]=incagetdevices; Read Device Properties (INCA-MIP Extended) Output IncaGetDeviceProperties Read 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. 34 The API Functions

35 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 0W=aÉîáÅÉ=Ü~ë=åç=ãÉãçêó=é~ÖÉë=çê= ÅìêêÉåí=é~ÖÉ=áë=åçí=ïêáíÉ=éêçíÉÅíÉÇ= 1W=`ìêêÉåí=é~ÖÉ=áë=ïêáíÉ=éêçíÉÅíÉÇ p.isactive 0W=aÉîáÅÉ=áë=åçí=ÅçååÉÅíÉÇ=çê=åçí= ~ÅíáîÉ= 1W=aÉîáÅÉ=áë=ÅçååÉÅíÉÇ=~åÇ=~ÅíáîÉ p.isworkbasedevice 0W=aÉîáÅÉ=Ü~ë=åç=Ç~í~ëÉíë 1W=aÉîáÅÉ=Ü~ë=Ç~í~ëÉíë device name of the device p = IncaGetDeviceProperties( Device ); The API Functions 35

36 3.4 Measuring and Recording A signal or measurement variable is always captured as part of a measure raster for that particular measuring device. Each measurement variable may appear in one measure raster only. To configure an experiment, first assign the measurement variables to the individual measure rasters. kçíé Note that the names of elements, devices, signals, and measure rasters are case-sensitive. 36 The API Functions

37 3.4.1 Read Measurement Elements (INCA-MIP Extended) Output IncaBrowseMeasureElements Get measurement elements of the experiment with search pattern and optional device [name, type] = IncaBrowseMeasureElements (pattern, {device}) [name] = IncaBrowseMeasureElements(pattern, {device}) name type pattern device List of names of measurement elements List of types of the measurement elements: ScalarW=pÅ~ä~ê ArrayW=sÉÅíçê MatrixW=j~íêáñ Search pattern for the measurement elements 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 measurement element. There is no difference between lower and upper case. of the device [n,t]=incabrowsemeasureelements( ign*, Device ); [name,type]=incabrowsemeasureelements( * ); Read Measure Rasters (INCA-MIP Extended) Output IncaGetMeasureRatesForDevice Get all measure rasters of a device [name] = IncaGetMeasureRatesForDevice (device) name device List of names of the measure rasters of the device n=incagetmeasureratesfordevice( Device ); name=incagetmeasureratesfordevice( Dev ); Add Measurement Variable to Measure Raster IncaAddMeasureElement Add a measurement variable to a measure raster. IncaAddMeasureElement(device, group, signal {, displaymode}) The API Functions 37

38 Output device group signal displaymode name of the device 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, e.g. 10ms+100ms. name of the measurement signal. For scalars, just the name is sufficient; for vectors and matrices, the index in the format [n] or [n,m] has to be appended to the name. The first element has the index of zero. display mode for the element: 1W=ãÉ~ëìêÉãÉåí=î~êá~ÄäÉ=áë=Çáëéä~óÉÇ= EÇÉÑ~ìäíF 0W=åç=Çáëéä~ó IncaAddMeasureElement( Device, 10ms, Chan1, 0); IncaAddMeasureElement( Dev, 10ms, Matrix[2,1] ); kçíé If the measure raster is full, the measurement variable does not get added to the raster. 38 The API Functions

39 3.4.4 Start Measurement Output IncaStartMeasurement Start a measurement in INCA IncaStartMeasurement Stop Measurement Output IncaStopMeasurement Stop the current measurement and recording (if enabled) in INCA IncaStopMeasurement{(mdfFile)} mdffile name of the MDF file in which the recorded data are saved if recording is stopped together with the current measurement. Always specify the full access path to the file (e.g., c:\mydata\store1.dat ). IncaStopMeasurement( c:\mydata\store1.dat ); kçíé To avoid data loss due to ongoing measurements, be sure to stop the current recording with the IncaStopMeasurement(mdfFile) command if the data volume is high. Follow this up with the IncaGetRecords command to transfer the remaining data to MATLAB Read Recording Properties (INCA-MIP Extended) Output IncaGetRecordingProperties Read the properties used for the next recording properties = IncaGetRecordingProperties properties properties.file properties.directory Recording properties as MAT- LAB struct, consisting of the following entries: the recording file name the directory for the recording file The API Functions 39

40 properties.fileformat properties.comment properties.autoincrement properties.defaultcomment properties.company properties.project properties.user properties.vehicle the file format of the recording file; 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) Automatically increment the recording file name 0W=ÇçåDí=~ìíç=áåÅêÉãÉåí 1W=Çç=~ìíç=áåÅêÉãÉåí= The comment in the recording file header. It must not exceed 1024 characters minus number of characters used for the default comment. The default comment in the recording file header generated by INCA The company in the recording file header The project in the recording file header The user in the recording file header The vehicle in the recording file header properties = IncaGetRecordingProperties; 40 The API Functions

41 3.4.7 Set Recording Properties (INCA-MIP Extended) Output IncaSetRecordingProperties Set properties for the next measurement data recording IncaSetRecordingProperties(properties) properties recording properties as matlab struct containing any combination of the following field designators: properties.file the recording file name properties.directory the directory for the recording file properties.fileformat the file format of the recording file; 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.autoincrement recording file name Automatically increment the 0W=ÇçåDí=~ìíç=áåÅêÉãÉåí 1W=Çç=~ìíç=áåÅêÉãÉåí= properties.comment the recording file header comment must contain max characters minus the character count of the default comment properties.company the company in the recording file header company properties.project the project in the recording file header The API Functions 41