INCA V7.0 Instrument Integration Development Kit. Tutorial

Transcription

1 INCA V7.0 Instrument Integration Development Kit Tutorial

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

3 Contents 1 Introduction Safety Notice How this tutorial is organized What you have learned after completing the tutorial Conventions in the tutorial Getting More Information What you need to know Lesson 1: Create the Instrument Objectives Tasks Create a new instrument Run through the Wizard Integrate the instrument in INCA Lesson 2: Customize the Instrument Objectives Tasks Change the instrument UI in Visual Studio Modify the Main Class Modify the instrument properties Lesson 3: Access Variable values Objectives Tasks Change properties in InstrumentType.xml Get value access Value Change Events Lesson 4: Add context menus Objectives Tasks Activate standard context menus Create your own context menus Lesson 5: Make it multilingual Introduction 3

4 7.1 Objectives Tasks Extend the.resx file Lesson 6: Implement Drag n Drop Objectives Tasks Realize Drag n Drop Lesson 7: Deploy instrument to other systems Objectives Tasks Port instruments to another system Troubleshooting INCA shows a red instrument in the Experiment Environment INCA does not show the Instrument Properties INCA does not take property modifications of InstrumentProperties.xml Further Documentation ETAS Contact Addresses Introduction

5 1 Introduction The Instrument Integration Development Kit allows the creation of customer specific instruments for the Experiment Environment of INCA. These instruments extend the existing library of instruments available today ( Measure Window, Calibration Window, Y-t oscilloscope, Table Editor ). You can implement a specific user interface according to your needs with high-performance value access to the measure or calibration variables. This tutorial shows the software developer steps to create and modify own instruments. 1.1 Safety Notice WARNING! A warning indicates information about critical points. Please notice these warnings to avoid problems. 1.2 How this tutorial is organized This INCA tutorial consists of the following chapters:! Chapter 1: " Introduction" Contains general information such as safety hints, notes on the target group and conventions used in this document.! Chapter 2: " What you need to know" Provides an overview about some basic concepts that are important for understanding.! Chapter 3: "Lesson 1: Create the Instrument" Learn how to create a new instrument with the help of the ETAS Instrument Wizard.! Chapter 4: "Lesson 2: Customize the Instrument" Learn how to change the instrument variables and properties in Visual Studio and INCA. You will learn how to add variables to the instrument and create layouts to visualize those variables.! Chapter 5: "Lesson 3: Access Variable values" Learn how you can get and modify value access. Furthermore, you will learn how to change the instrument properties in XML.! Chapter 6: "Lesson 4: Add context menus" Learn how to implement and activate context menus.! Chapter 7: "Lesson 5: Make it multilingual" Learn how to use resx files to make the instrument multilingual.! Chapter 8: "Lesson 6: Implement Drag n Drop" Learn how to implement Drag n Drop.! Chapter 9: "Lesson 7: Deploy instrument to other systems" Provides an overview of the portability of INCA instruments.! Chapter 10: "Troubleshooting" Provides an overview about problems you can have while using this tutorial.! Chapter 11: " Further Documentation" Provides a complete overview of the documentation items provided with the API.! Chapter 12: " ETAS Contact Addresses" Find contact information for the ETAS headquarters and the technical support. Introduction 5

6 1.3 What you have learned after completing the tutorial At end of the tutorial you will be able to create a new instrument and modify the properties of this instrument. This contains the implementation of custom functions such as implementing context menus with the programming language C# or defining variables with the markup language XML. Furthermore you will be in position to install instruments on other systems. 1.4 Conventions in the tutorial The following typographical conventions are used in this document: OCI_CANTxMessage msg0 = Choose File " Open. Click OK. Press <ENTER>. The "Open File" dialog box is displayed. Select the file setup.exe A distribution is always a onedimensional table of sample points. Code snippets are presented on a gray background and in the Courier font. Meaning and usage of each command are explained by means of comments. The comments are enclosed by the usual syntax for comments. Menu commands are shown in boldface. Buttons are shown in boldface. Keyboard commands are shown in angled brackets. Names of program windows, dialog boxes, fields, etc. are shown in quotation marks. Texts in drop-down lists on the screen, program codes, as well as path and file names are shown in the Courier font. General emphasis and new terms are set in italics. 1.5 Getting More Information A glossary explaining technical terms and abbreviations is included in the User's Guide. You can find a detailed overview of the complete documentation that is provided with the SDK in chapter 11, Further Documentation, on page Introduction

7 2 What you need to know This tutorial is aimed at software developers developing tools for electronic control units and calibration methods. Specialized knowledge in the areas of measurement, control unit technology and software development is required. Basic knowledge of Visual Studio is required. To implement instruments you need Visual Studio 2008 or Visual Studio 2008 Express. Furthermore you need knowledge about the.net Framework 3.5..Net provides more than 50 programming languages like Visual Basic, C#, F#, WPF and the markup language XML. In this tutorial we use C# to implement the instrument and the markup language XML to manipulate variables and properties. Specialized knowledge about INCA is required. Especially, you have to know the INCA MC concepts, INCA ASAP 2 Structure, the INCA two page calibration concept and the INCA wording. Note INCA currently does not support WPF. What you need to know 7

8 3 Lesson 1: Create the Instrument 3.1 Objectives 3.2 Tasks In this lesson you will learn how to create a new instrument with the help of the INCA Instrument Wizard. In addition, you will learn how to integrate and start this instrument in INCA Create a new instrument The INCA Instrument Wizard is a Visual Studio plug in. In the following steps you will create a new instrument. To create the instrument:! Open Visual Studio 2008.! Select File " New " Project.! Select Visual C# " ETAS " INCA Custom Instrument.! Change the project name at the bottom to MyInstrument.! Click OK. If you use Visual Studio 2008 Express, you will not see the INCA Custom Instrument project template, see step 3 above. In this case you have to integrate the project template before you can use the Instrument Wizard. To integrate the project template into Visual Studio Express! Copy the INCA Custom Instrument.zip file from the following path: <ETAS>\INCA Instruments Integration SDK 1.0\VS2008Template\.! Paste it into "C:\Documents and Settings\<user>\My Documents\Visual Studio 2008\Templates\ ProjectTemplates\Visual C#". Note Do not extract the file, just copy the zip-file.! Restart Visual Studio 2008 Express.! Select File " New Project.! Select INCA Custom Instrument.! Change the project name at the bottom to MyInstrument.! Click OK. The Etas Instrument Wizard is displayed Run through the Wizard The Etas Instrument Wizard consists of the following parts:! Step 1: Welcome Screen The Welcome Screen is the introduction to the ETAS Instrument Wizard. The left-hand side of the wizard shows the navigation bar. At the top is a short introduction to this wizard and at the bottom are the navigation buttons. In each step you can close the wizard by clicking Cancel or step backward to the previous step.! Click Next. 8 Lesson 1: Create the Instrument

9 ! Step 2: General Fig 3-1: General Instrument Properties In the General Screen you have to declare general instrument properties. In this tutorial we use certain predefined settings. Instrument Name:! Fill in the following: My Instrument This is the visible name of your instrument in the INCA Experiment Environment. WARNING! The entry of the Type does not allow dots and blanks. Furthermore, no numbers at the beginning are supported. Type: mytype The instrument type is a unique identifier. It is necessary to distinguish the instruments. WARNING! The description of Provider does not allow dots and numbers at the End/Beginning and blanks between texts. But between words like in instrument.provider, dots are allowed. WARNING! Within the namespace you cannot create instruments with the same Instrument Name. Lesson 1: Create the Instrument 9

10 Provider: MyCompany The provider is a namespace which manages the instruments.! Step 3: Signal Types Fig 3-2: Signal Types The third step in the wizard is the declaration of the Signal Types. INCA will use your settings here to control the type and number of variables which can be assigned to your instrument in INCA s Variables Selection Dialog. Note All the settings here can be changed later on in the InstrumentType.xml, see chapter 4.! Use the following settings: Count of Variables: Single The Count of Variable specifies the number of variables which can be used in the instrument. There are three possible options: None, Single and Multiple. If you choose the Single option, you can assign only one variable. If you choose Multiple, you can assign more than one variable. The last option is None. If you choose this option, you cannot assign variables to your instrument.! Please choose Single. Variable Classes: Measurement/Calibration The Variable Class specifies the classes of variables which can be used in the instrument. The available Variable Classes are Measurement and Calibration.! Please activate both checkboxes so that Measurement or Calibration variables can be assigned to your instrument. 10 Lesson 1: Create the Instrument

11 Variable Types: Scalar INCA supports a number of different variable types: Scalar variables (single value), Vectors (a list of values) and Arrays (two-dimensional array). Here you specify which type(s) of variables can be assigned to your instrument.! Please choose Scalar here.! Step 4: Adding Properties Fig 3-3: Property Dialog Instrument properties consist of two parts, Name and Type. Name is the property identifier. For Type INCA offers seven standard types Boolean, Color, Directory, Enumeration, File, Numeric and String. The properties you specify here will be displayed in the Display Configuration tab of INCA s Variable Selection Dialog, so you will be able to edit the property values of your instrument in INCA. Note Note that the properties can be changed later on in InstrumentProperties.xml, see chapter 4. To add properties:! Click Add.! Rename the property to BackgroundColor.! Change the property Type to Color.! Create the property MyProperty2 with type Boolean in the same way(step 1-3).! Click Next.! Step 5: Summary The Summary is the last step of the Instrument Wizard. In this screen you will find all the entered information about the new instrument. Lesson 1: Create the Instrument 11

12 To finish the Wizard:! Check the instrument properties.! Click Finish. After finishing the wizard, Visual Studio creates a complete Visual Studio project containing all files you need to create the instrument. The selected user interface is InstrumentControl.cs[Design]. This controls the visual layout of the instrument and determines how it will look in the INCA Experiment Environment. The second part of the main user interface is the main class InstrumentControl.cs. The modification of this main class is explained in Lesson 2: Customize the Instrument. Finish the instrument with the following step:! Select Build " Build Solution. Note The reference folder of your Visual Studio project contains a reference to the Etas.OpenEE.dll. This is the DLL containing all interface classes for the communication to INCA. The reference to the OpenEE.dll is <ETAS>\INCA7.0\bin\ETAS.OpenEE.dll Integrate the instrument in INCA After you have finished the wizard, Visual Studio will copy the solution automatically into the INCA plug-in folder at <EtasData>\INCA7.0\Instruments. INCA will load the instrument from this folder.! Restart INCA.! Choose the instrument in the Variable Selection Dialog (see Screenshot below). Now you can add variables in the same way you do to a standard instrument. Note To integrate your instrument manually, see Lesson 7: Deploy instruments to other systems. Fig 3-4: Variable Selection Dialog 12 Lesson 1: Create the Instrument

13 4 Lesson 2: Customize the Instrument 4.1 Objectives 4.2 Tasks This chapter provides information about the Visual Studio UI Developer, the instrument main classes and the property XML file Change the instrument UI in Visual Studio The UI Developer of Visual Studio is a plug-in which helps you to modify the instrument UI. There are two possible ways to change the layout of the instrument UI.! Modify the UI with the help of the Visual Studio UI Developer! Change the UI via programming the components in the source code In this tutorial we use the UI Developer of Visual Studio. If you open the InstrumentControl.cs class in the designer, you can use the Visual Studio Toolbox to add user controls to your user interface. To add components to the instrument! Open the file InstrumentControl.cs to display the UI.! Open the toolbox of Visual Studio.! Choose two buttons and two textboxes from the toolbox and place it at the instrument via Drag n Drop.! Save your layout.! Adapt the look of your instrument, according to the following picture. Fig 4-1: Instrument User Interface Modify the Main Class The instrument is organized in partial classes. One partial class is the Instrument.Desinger.cs where UI components are defined. The second partial class is the InstrumentControl.cs which handles all interaction between INCA and the instrument like actions, events and the communication. The WidgetHost class is the main access of your instrument to INCA. Initialize! Open the source code of the InstrumentControl.cs. Find the method Initialize, where the main interface class WidgetHost is passed to your instrument (see Fig 4-2). The method is called if the instrument is initialized by creating an instance of the instrument or initializing the Experiment Environment with an already existing instance. Lesson 2: Customize the Instrument 13

14 public void Intitialize(IWidgetHost host) _WidgetHost = host; this.initializevalueaccesses(initializedelementreferences, null); Fig 4-2: Initialize method The InitializeValueAccesses method handles all value accesses of every variable (see Fig 4-3). We will use and modify this method in Lesson 3: Access Variable values. private void InitializeValueAccesses(IList<IElementReference> addedelements, Fig 4-3: InititalizeValueAccess Event handler IList<IElementReference> removedelements) The method "InstrumentControl_AssignedElementsChanged" handles the event which is called (see Fig 4-4), if the user of INCA adds variables to or removes variables from this instrument. private void InstrumentControl_AssignedElementsChanged(object sender, AssignedElementsChangedEventArgs e) this.initializevalueaccesses(e.addedelements, e.removedelements); Fig 4-4: Element changed Event handler The method host_saveconfiguration handles the save configuration events initiated by the Widget Host. It is called every time you click on the Save button, open the Variable selection, Display configuration or Variable configuration window, close the Experiment Environment. In this case we want to save the configuration of the background color. To realize this, you have to implement the following command lines: void host_saveconfiguration(object sender, System.EventArgs e) // save the configuration of the background color. _WidgetHost.Configuration.Properties.SetProperty("BackgroundColor", BackColor); Fig 4-5: Save Configuration event handler The event handler host_loadconfiguration manages all load configuration events initiated by the Widget Host. The load configuration event is called every time the user creates a new instance of the instrument at INCA or opens the Experiment Environment with an already 14 Lesson 2: Customize the Instrument

15 existing instrument. In this event handler you have to describe which properties you want to load. In this case we want to load the background color and the property called MyProperty2. void host_loadconfiguration(object sender, System.EventArgs e) var properties = _WidgetHost.Configuration.Properties; Color bkcolor; // here we try to get the instrument property BackgroundColor if (properties.trygetproperty("backgroundcolor", out bkcolor)) // declares the backcolor of your instrument with the given property BackColor = bkcolor; /* if you want to display more properties in the Display Configuration *\ Dialog, you have to create them in xml (see chapter 4.2.3) and load them like above. Fig 4-6: Load Configuration event handler After rebuilding the solution and restarting INCA you can see the properties in the Display Configuration Dialog in INCA (see Fig 4-7). To change the properties! Check the instrument in the Display Configuration Dialog.! Change the backgroundcolor to green.! Click OK. Fig 4-7: Display Configuration Dialog Lesson 2: Customize the Instrument 15

16 Fig 4-8: Instrument with green background Color Modify the instrument properties In this part of the chapter you will add and change properties. The modification of the instrument properties is based on XML. Add properties in Properties.xml The properties are organized in a XML file. Within the XML you have to define the instrument properties. The Properties.xml file is referenced in the Type.xml. You will see the InstrumentType.xml file in the next lesson. To modify the properties of your instrument open the InstrumentProperties.xml file in Visual Studio. <PropertyDef Key="BackgroundColor" DisplayKey="Str_BackgroundColor"> <Color DefaultValue="#CCCCCC" /> <Description DisplayKey="Str_BackgroundColor_Description" /> </PropertyDef> <PropertyDef Key="MyProperty2" DisplayKey="Str_MyProperty2"> <Boolean BooleanFormat="TrueFalse" DefaultValue="false" /> <Description DisplayKey="Str_MyProperty2_Description" /> </PropertyDef> Fig 4-9: Instrument properties WARNING! If you use a displaykey twice, INCA will ignore all properties. To add properties to your instrument you have to define a new property definition within XML tags. Each property needs a unique Key, a DisplayKey and a DefaultValue. Take into account that the types Boolean and Numeric have more attributes than the default value (you can see these attributes in the example at the bottom). The DisplayKey will appear later in the resx files (Lesson 5: make it multilingual).! Please define a new property like in the picture below. <PropertyDef Key="MyProperty3" DisplayKey="Str_MyProperty3"> <Boolean BooleanFormat="TrueFalse" DefaultValue="False"/> <Description DisplayKey="Str_MyProperty3_Description"/> </PropertyDef> Fig 4-10: Added instrument property To adopt the modification you have to rebuild the solution and restart INCA. 16 Lesson 2: Customize the Instrument

17 To rebuild the solution! Select Build " Build Solution.! Restart INCA. Note There exist seven different property types for an INCA instrument: Boolean, Color, Direction, Enumeration, File, Numeric and String. One example of an Enumeration: <PropertyDef Key="CalibrationColor" DisplayKey="Str_CalibrationColor"> <Enumeration DefaultValue="0"> <EnumerationItem DefaultValue="0" DisplayKey="red"> <EnumerationItem DefaultValue="1" DisplayKey="green"> <EnumerationItem DefaultValue="2" DisplayKey="blue"> </Enumeration> </PropertyDef> Fig 4-11: Example of an Enumeration property Lesson 2: Customize the Instrument 17

18 5 Lesson 3: Access Variable values 5.1 Objectives 5.2 Tasks Value Access is one of the essential parts of this tutorial. In this part of the tutorial you will learn how to get value access and how to pull out variables and their values from your instrument Change properties in InstrumentType.xml The instrument types are organized in XML like the Instrument Properties. In the InstrumenType.xml you can describe which types and classes of variables from INCA should be supported in this instrument. To modify the properties of your instrument! Open the InstrumentType.xml in Visual Studio. In the INCA Instrument Wizard at the beginning of this tutorial, we have chosen the Count of Variables option Single, the Variable Classes Measurement and Calibration and the Variable Type Scalar. In the following steps you will see how to change these options manually after finishing the wizard.! Step 1: Change count of variables The first part of the modification is to change the count of variables from Single to Multiple. Basically there are three different configurations which you can use: If you choose the option None in the INCA Instrument Wizard, Visual Studio sets the MinVariableCount and MaxVariableCount to the value 0. You can see this option in the following code snippet. <PossibleSignals MinVariableCount="0" MaxVariableCount="0"> Fig 5-1: Count of variables configuration None. The option Single is represented by the following code snippet. <PossibleSignals MinVariableCount="1" MaxVariableCount="1"> Fig 5-2: Count of variables configuration Single. The third option from the INCA Instrument Wizard is Multiple. This option is represented by the last code snippet. <PossibleSignals MinVariableCount="1" MaxVariableCount="1000"> Fig 5-3: Count of variables configuration Multiple. To change the count of variables you have to modify the MaxVariableCount to the count of variables that you need. Furthermore, you can change the MinVariableCount in the same way.! Please change the MaxVariableCount to 1000.! Step 2: Add Variable Classes At the beginning of this tutorial we chose the Variable Classes Measurement and Calibration. You can see these options in the following code snippet: 18 Lesson 3: Access Variable values

19 <VariableClasses> <VariableClass Value="Calibration"/> <VariableClass Value="Measurement"/> </VariableClasses> Fig 5-4: Variable Classes Within these XML tags, you can add or remove variable classes. You can choose from four different variable classes: Calibration, Measurement, Adaptive Calibration and Slewing.! Please add the following variable class. <VariableClass Value="AdaptiveCalibration"/> Fig 5-5: Added Variable Class! Step 3: Add Variable Types In this step you have to add Variable Types. INCA supports currently three different types. They are Scalar, Vector and Array. The Variable Type describes which type a variable could have. You can see the configuration from the beginning in the following lines: <VariableTypes> <VariableType Value="Scalar"/> </VariableTypes> Fig 5-6: Variable Types Within this XML tags you can add more Variable Types like Vector or Array. In this tutorial it is optional. WARNING! In this tutorial we only use values with type Scalar. If you add the following Variable Types you have to ensure that the given value is of type Scalar. <VariableType Value="Vector"/> <VariableType Value="Array"/> Fig 5-7: Added Variable Type! Step 4: Change Element Data Type The last step is to change the Element Data Types. There are three different types: Numeric, Boolean and ASCII. The Element Data Type describes which type a variable could have. If you choose the option Numeric, your variable supports numeric values. Boolean has the consequence that the variable could have the values true or false. The last option is ASCII. With this option the variables could contain strings as value. With these configurations you can define as stated above, which variables you can use in your instrument. Lesson 3: Access Variable values 19

20 After finishing the Etas Instrument Wizard, Visual Studio creates the following default values: <ElementDataTypes> <ElementDataType Value="Numeric" /> <ElementDataType Value="Boolean" /> </ElementDataTypes> Fig 5-8: Element Data Types Within the XML tags you can add or remove the Element Data Types. In this tutorial it is optional. <ElementDataType Value="Ascii"/> Fig 5-9: Added Element Data Type To adopt the modification you have to rebuild the solution and restart INCA Get value access The first step to get value access is to declare a global object. There are different interfaces in the Etas.OpenEE library which you can use to get access. The possibilities are:! ISignalValueAccessScalar<T> This object type gives you access to a scalar element value.! ISignalValueAccessArray<T> An object which gives you access to an array element value.! ISignalValueAccessAscii<T> This object gives you access to an ascii element value.! Please open the InstrumentControl.cs. Note The interfaces we used above provides read and write value access. If you want to provide only read access, you instead have to use the IValueAccess interfaces. In this tutorial we will use an object from the ISignalValueAccessScalar interface with type double.! Please add the following global variable in the InstrumentControl.cs. // global declaration private ISignalValueAccessScalar<double> _valuescalaraccess; Fig 5-10: Global declaration of the value access 20 Lesson 3: Access Variable values

21 Change the InitializeValueAccess method The method InitializeValueAccesses manages the value access of every variable which is assigned to your instrument. This method is called every time you add or remove elements to your instrument. private void InitializeValueAccesses(IList<IElementReference> addedelements, IList<IElementReference> removedelements) Fig 5-11: InitializeValueAccess method With the following command lines you can get the type (Scalar, Array, Ascii, ) and the class (Measurement or Calibration) of the given element. You need the type and class of the reference if you have to differ between several types and classes to get the correct value. Here you can use the type and class to determine that the value is of type Scalar. // type of the element reference EElementType elementtype = addedelements[0].elementinfo.type; // class of the element reference EElementClass elementclass = addedelements[0].elementinfo.scalar.elementclass; Fig 5-12: Element type and element class of value access WARNING! In this case Visual Studio will throw a NullReferenceException if the type is not Scalar. The following command line instances the given ISignalValueAccessScalar object as double. Other types are also possible. Furthermore, this command line could throw a NullReferenceException if the type is not Scalar. _valuescalaraccess = addedelements[0].elementinfo.scalar.getvalueaccess<double>(eaccesstype.phys, EPageId.Current); Fig 5-13: Declaration of the value access The differences between the GetValueAccess() parameters are:! EAccessType.Phys defines the type of value access to Physical values.! EAccessType.Impl defines the type of value access to Implementation values.! If you specify EPageId.Current your value access object will provide access to the value of the currently selected page (working page, reference page).! If you specify EPageId.Reference, you will only have access to the value of the reference page. Lesson 3: Access Variable values 21

22 The next step is to create a new event handler and link it to the method which is called if the event appears. In this case we link it to the ExampleValueChangedEvent method. _valuescalaraccess.valuechangedevent += new Fig 5-14: Value access event handler Value Change Events EventHandler(exampleValueChangedEvent); In the part above, you created a new event handler for the ValueChangedEvent and linked it to the ExampleValueChangedEvent method. Here you will use the method GetValue() of the ISignalValueAccessScalar object to receive an actual value of your element. Furthermore, you have to assign a default value, in this case with type double. Note It is possible that measurement variables have no value at the beginning. private void ExampleValueChangedEvent(object sender, EventArgs e) double actualvalue = _valuescalaraccess.getvalue(0.0); // to display the actual value write it into a textbox textbox1.text = actualvalue.tostring(); Fig 5-15: Value changed event handler Another option to get the value is to use the TryGetValue() method. In this method the value will be written if the return value of the method is true. To visualize the current value, we use one of the buttons you created in chapter To display the value on the instrument UI, you have to write the actual value into one of the textboxes. private void button1_click(object sender, EventArgs e) textbox2.text = _valuescalaraccess.getvalue(0.0).tostring(); Fig 5-16: Button 1 routine The last step is to rebuild the solution and restart INCA. Set Values Another essential part of the value access is that you are able to change the values of Calibration variables. In this tutorial, we use the click event of the second button to read the string from the second textbox and write it into the value access object. The setvalue() method returns an object with type IRetVal. This object contains information about the success of the operation. 22 Lesson 3: Access Variable values

23 private void button2_click(object sender, EventArgs e) try // write the given value from the textbox into the value access object IRetVal val =_valuescalaraccess.setvalue<double> catch (Exception ex) (BoundaryModes.RespectAllBounds, Convert.ToDouble(textBox2.Text)); Logging.Log(ELoggingSeverity.Error, ex.tostring()); Fig 5-17: Button 2 routine WARNING! Be careful with the BoundaryModes option IgnoreAllBounds. The value will be written anyway. WARNING! The variable that you assigned to the instrument has to be from class Calibration. If you use the setvalue method with a Measurement variable you will get a return value which contains that the variable is not editable. WARNING! The conversion from string to double could throw an Exception. Therefore we use the try catch structure here. Lesson 3: Access Variable values 23

24 6 Lesson 4: Add context menus 6.1 Objectives 6.2 Tasks This lesson consists of two different parts. The first part is about the implementation and activation of the INCA standard context menus. In the second part you will learn how to implement and add your own context menu Activate standard context menus After you have finished the Etas Instrument Wizard, Visual Studio creates the default method for initializing the default context menus. At the beginning the context menus are inactive. The next steps will show how you can activate them. The method Initialize contains the InitializeDefaultContextMenus call with the instrument as parameter. In this method INCA initializes the default context menus for the given system. public void Intitialize(IWidgetHost host) _WidgetHost.InitializeDefaultContextMenus(this); Fig 6-1: Initialize method To activate the standard context menus, your instrument has to derive from the IWidgetHostEventSink interface. public partial class InstrumentControl : UserControl, IWidget, IWidgetHostEventSink Fig 6-2: Class declaration To implement the Interface! Right-click on IWidgetHostEventSink.! Choose Implement Interface " Implement Interface. Visual Studio creates the following method stubs: public IWidgetHostEventSink WidgetHostEventSink // here, you can return the class which implements the // IWidgetHostEventSink interface. get return this; Fig 6-3: IWidgetHostEventSink constructor This method provides the information if the widget can compute the parameter identifier by the parameter description key. public bool CanComputeParameter(IParameterDescription parameterdescription) // returns true, if the widget can compute the paramter identifier 24 Lesson 4: Add context menus

25 return parameterdescription.key == ParameterIDs.ElementSelection parameterdescription.key == ParameterIDs.ValueSelection; Fig 6-4: IWidgetHostEventSink Interface method CanComputeParameter The method CanShowProperties provides the information if the context menu Properties will be active for your instrument. If you return true, you will need to implement the ShowProperties method below. public bool CanShowProperties() // return true to show properties of your Instrument. return true; Fig 6-5: IWidgetHostEventSink Interface method CanShowProperties The method ComputeParameter calculates the parameter identifier by the given parameter description. public bool ComputeParameter(IParameter parameter) switch (parameter.description.key) case ParameterIDs.ElementSelection: parameter.value = return true; _WidgetHost.Configuration.WidgetDatas[0].ElementReferences; case ParameterIDs.ValueSelection: return false; parameter.value = new[] new ValueSelection(_valueScalarAccess, return true; EValueFormat.Float) ; Fig 6-6: IWidgetHostEventSink Interface method CanComputeParameter The method GetOptimalWindowSize returns the optimal window size desired by the widget itself. In this case it is optional. public Size GetOptimalWindowSize() throw new NotImplementedException(); Fig 6-7: IWidgetHostEventSink Interface method GetOptimalWindowSize This method HasOptimalWindowSize is called to enable or disable the Optimize Window Size context menu. public bool HasOptimalWindowSize() // returns true, if the widget can provide an optimal window size. In this Lesson 4: Add context menus 25

26 // case we return false beacause the GetOptimalWindowSize method is not // implemented. return false; Fig 6-8: IWidgetHostEventSink Interface method HasOptimalWindowSize The method ShowProperties allows you to show the properties for the currently selected Instrument. In this case we choose a message box to display a new dialog. public void ShowProperties() MessageBox.Show("Enable UI updates?", "Properties", MessageBoxButtons.YesNoCancel); Fig 6-9: IWidgetHostEventSink Interface method ShowProperties Finish implementing the Interface with the following steps:! Rebuild the Solution.! Restart INCA. Now you can use the default context menu from INCA (see Fig 6-10). Fig 6-10: Instrument UI with default context menu Create your own context menus In this part of the tutorial you will learn how to implement and activate your own context menu items. In the next step you will create a new class, which represents the new context menu item. Finally, you will implement a new context menu and the related event handler. The BeepAction Class At first you have to create a new BeepAction class in Visual Studio. This class provides information about the new context menu item. The class is derived from the IActionDescription interface. This interface describes the actions which can be triggered by a context menu or a shortcut. public class BeepAction : IActionDescription // global variables private readonly int frequency; private readonly int length; private readonly Keys _shortcut; 26 Lesson 4: Add context menus

27 // constructor public BeepAction(int frequency, int length, Keys shortcut) this.frequency = frequency; this.length = length; this._shortcut = shortcut; // the description of the context menu item public string Text get return "Beep"; // the shortcut will be declared in the InstrumentControl.cs public Keys Shortcut get return _shortcut; public string ShortcutDisplayString get return String.Empty; // here, you can specify the icon public Icon Icon get return SystemIcons.Asterisk; public bool Checked get return false; // return true to enable the context menu item public bool Enabled get return true; // return true to activate the context menu item public bool Active get return true; internal void DoIt() Console.Beep(frequency, length); Lesson 4: Add context menus 27

28 Fig 6-11: Beep Action class Modification of the InstrumentControl.cs class After you have finished the implementation of the BeepAction class, you have to create a new global list with type IActionDesciption in your InstrumentControl.cs class. In the next step you will add the actions into this list. private readonly IList<IActionDescription> _Actions; Fig 6-12: Global declaration of the actions In the constructor of the InstrumentControl.cs you have to declare the new context menu strips. Please add the BeepAction as in the following command lines: public InstrumentControl() InitializeComponent(); // here, you can add actions to the context menu _Actions = new List<IActionDescription> ; new BeepAction(100, 50, Keys.Control Keys.B), new BeepAction(50, 50, Keys.Control Keys.N) Fig 6-13: Context menu structure The method GetActionDescriptions returns the actions of the instrument. In this case we return the list of the context menu actions. public IList<IActionDescription> GetActionsDescriptions() return _Actions; Fig 6-14: Getter of the Instrument actions The event handler ExcecuteAction reacts on the given event from the context menu. If there are different context menu items, you have to specify on which event you want to react. 28 Lesson 4: Add context menus

29 public void ExecuteAction(IActionDescription actiondescription) BeepAction beepaction = actiondescription as BeepAction; if (beepaction!= null) // calls the DoIt method in the BeepAction class beepaction.doit(); return; Fig 6-15: Action event handler As the final step you have to rebuild the solution and restart INCA. Now you can use your new context menu strips (see Fig 6-16). Fig 6-16: Instrument UI with custom context menu Lesson 4: Add context menus 29

30 7 Lesson 5: Make it multilingual 7.1 Objectives The aim of this lesson is to enable you to create and modify the language files. Note You have to create one file for every language. 7.2 Tasks Extend the.resx file In general the.resx is a XML based file, where objects and strings are specified by an entry in XML tags. To change the file you can use a text editor such as Notepad or Word. In this tutorial we use an alternative provided by Visual Studio. The entries are visualized in a table as shown in the picture. Fig 7-1: Resx file To create a new Resource file! Right-click on the file InstrumentResources.resx.! Select Copy.! Right-click on MyInstrument.! Select Paste.! Rename the file to InstrumentResources.de.resx.! Press <Return>. This is only one possible way to create a new Resource file. Furthermore, you can use a translation tool which automatically creates the resx files. WARNING! You have to use dots between the file name, the language code and the file ending. For example: InstrumentResources.en-us.resx. Further information about the language codes you can find in the msdn library at: To make it multilingual! Open the InstrumentRessources.de.resx file.! Translate text.! Save the file. Fig 7-2: Translated Resx file To finish this lesson you have to rebuild the solution. Visual Studio creates for every language a new folder, within you instrument main folder. The last step is to restart INCA. 30 Lesson 5: Make it multilingual

31 WARNING! If you later change the properties of your instrument you have to adapt the other resx files manually to the modification. Lesson 5: Make it multilingual 31

32 8 Lesson 6: Implement Drag n Drop 8.1 Objectives 8.2 Tasks In this lesson you will learn how to implement the Drag n Drop function for your instrument Realize Drag n Drop In INCA it is possible to drag and drop variables within the Experiment Environment from one window to another. INCA already provides dropping variables, so you only have to implement the drag function. The next steps will show you how to implement this function: Note The variable can only be dragged into the instrument when it supports the dragged variable type and the maximum of signals for the instrument is not exceeded. To implement Drag n Drop! Include the following global variables: private Rectangle m_dragboxfrommousedown = Rectangle.Empty; private readonly HashSet<InstrumentControl> _SelectedControl = new HashSet<InstrumentControl>(); Fig 8-1: Global declaration The first variable contains the point where you clicked on the instrument. In the second variable, we save the currently selected control, in this case the instrument itself.! Extend the InitializeValueAccess method. The extension consists of the event handler for the MouseDown and MouseMove event. It is called, every time you add or remove a variable. private void InitializeValueAccesses(IList<IElementReference> addedelements, IList<IElementReference> removedelements) // value access declaration (see lesson 3) if (addedelements!= null) foreach (IElementReference er in addedelements) // register the instrument events to the event handler this.mousedown += OnMouseDownControl; this.mousemove += OnMouseMoveControl; if (removedelements!= null) foreach (IElementReference er in removedelements) 32 Lesson 6: Implement Drag n Drop

33 // dispose the event handler this.mousedown -= OnMouseDownControl; this.mousemove -= OnMouseMoveControl; Fig 8-2: Extended InitializeValueAccess method The method OnMouseDownControl contains the reaction on the mouse click event. It is called every time you click into the instrument window.! Implement the reaction to the mouse down event private void OnMouseDownControl(object sender, MouseEventArgs e) if (e.button == MouseButtons.Left) else m_dragboxfrommousedown = GetDragBoxFromPoint(e.Location); m_dragboxfrommousedown = Rectangle.Empty; ChangeControlSelection(sender as InstrumentControl); Fig 8-3: Event handler of the mouse down event The method GetDragBoxFromPoint returns a rectangle which contains the point you have clicked at the beginning and the point where you drop the variable.! Implement the GetDragBoxFromPoint function private static Rectangle GetDragBoxFromPoint(Point p) Size dragsize = SystemInformation.DragSize; return new Rectangle(new Point(p.X - (dragsize.width / 2), p.y Fig 8-4: Compute drag box method (dragsize.height / 2)), dragsize); The method OnMouseMoveControl manages the reaction to the move event. The DoDragDropSelectedElements method call at the bottom of this method starts the drag and drop operation of the selected element reference.! Implement the reaction to the mouse move event private void OnMouseMoveControl(object sender, MouseEventArgs e) if ((e.button & MouseButtons.Left) == MouseButtons.Left) if (m_dragboxfrommousedown!= Rectangle.Empty &&!m_dragboxfrommousedown.contains(e.x, e.y)) Lesson 6: Implement Drag n Drop 33

34 // reset the dragbox rectangle m_dragboxfrommousedown = Rectangle.Empty; // start drag and drop _WidgetHost.EventSink.DoDragDropSelectedElements(); Fig 8-5: Mouse move event handler The method ChangeControlSelection manages the selection of the instrument windows. It is called if you drag a variable to another window.! Extend the instrument selection private void ChangeControlSelection(InstrumentControl newselection) if (newselection!= null && _SelectedControl.Count == 1 && _SelectedControl.Contains(newSelection)) return; if(newselection!= null) _SelectedControl.Add(newSelection); newselection.backcolor = Color.LightYellow; _WidgetHost.EventSink.SelectionChanged(); Fig 8-6: Control selection method Finish the lesson with the following steps:! Rebuild the instrument solution.! Restart INCA. Now you can use the Drag n Drop function of your instrument in the Experiment Environment. 34 Lesson 6: Implement Drag n Drop

35 9 Lesson 7: Deploy instrument to other systems 9.1 Objectives 9.2 Tasks This lesson provides information about deploying instruments on other systems Port instruments to another system After finishing the wizard, Visual Studio copies the instrument folders to the following path: <EtasData>\INCA7.0\Instruments. Note The INCA plug-in folders are: <EtasData>\INCA7.0\Instruments C:\Documents and Settings\All Users\Application Data\ETAS\INCA\7.0\Instruments C:\Documents and Settings\Current User\Application Data\ETAS\INCA\7.0\Instruments To port instruments to another system! Copy the complete MyInstrument folder to one of the Pluginfolders (see blue box).! Restart INCA. Lesson 7: Deploy instrument to other systems 35

36 10 Troubleshooting 10.1 INCA shows a red instrument in the Experiment Environment INCA could not load the instrument correctly because there is an error in the source code. Fig 10-1: Instrument error If you move the mouse over your instrument INCA will show you the error log of Visual Studio. This log contains the method, with line number, where the exception appears. To solve the problem: In critical situations, like type conversion, use the try-catch structure INCA does not show the Instrument Properties To load the properties successfully into INCA, the reference type in the InstrumentType.xml should be the same string as in the definition of the PropertyGroup in InstrumentProperties.xml. InstrumentType.xml: <Properties RefType="InstrumentProperties" /> <WidgetDataTypes > <WidgetData > Fig 10-2: Property reference in Type.xml InstrumentProperties.xml: <PropertyGroups > <PropertyGroup Type="InstrumentProperties" /> Fig 10-3: Property reference in Properties.xml 10.3 INCA does not take property modifications of InstrumentProperties.xml After changing the properties:! Close INCA.! Rebuild the solution.! Restart INCA. 36 Troubleshooting

37 11 Further Documentation Please find further documentation and samples for the Instrument Integration in your Windows Start Menu at "Start"Programs"ETAS"Development Kits" INCA Instrument Integration SDK 1.0. Further Documentation 37

38 Figures Fig 3-1: General Instrument Properties... 9 Fig 3-2: Signal Types Fig 3-3: Property Dialog Fig 3-4: Variable Selection Dialog Fig 4-1: Instrument User Interface Fig 4-2: Initialize method Fig 4-3: InititalizeValueAccess Fig 4-4: Element changed Event handler Fig 4-5: Save Configuration event handler Fig 4-6: Load Configuration event handler Fig 4-7: Display Configuration Dialog Fig 4-8: Instrument with green background Color Fig 4-9: Instrument properties Fig 4-10: Added instrument property Fig 4-11: Example of an Enumeration property Fig 5-1: Count of variables configuration None Fig 5-2: Count of variables configuration Single Fig 5-3: Count of variables configuration Multiple Fig 5-4: Variable Classes Fig 5-5: Added Variable Class Fig 5-6: Variable Types Fig 5-7: Added Variable Type Fig 5-8: Element Data Types Fig 5-9: Added Element Data Type Fig 5-10: Global declaration of the value access Fig 5-11: InitializeValueAccess method Fig 5-12: Element type and element class of value access Fig 5-13: Declaration of the value access Fig 5-14: Value access event handler Further Documentation

39 Fig 5-15: Value changed event handler Fig 5-16: Button 1 routine Fig 5-17: Button 2 routine Fig 6-1: Initialize method Fig 6-2: Class declaration Fig 6-3: IWidgetHostEventSink constructor Fig 6-4: IWidgetHostEventSink Interface method CanComputeParameter Fig 6-5: IWidgetHostEventSink Interface method CanShowProperties Fig 6-6: IWidgetHostEventSink Interface method CanComputeParameter Fig 6-7: IWidgetHostEventSink Interface method GetOptimalWindowSize Fig 6-8: IWidgetHostEventSink Interface method HasOptimalWindowSize Fig 6-9: IWidgetHostEventSink Interface method ShowProperties Fig 6-10: Instrument UI with default context menu Fig 6-11: Beep Action class Fig 6-12: Global declaration of the actions Fig 6-13: Context menu structure Fig 6-14: Getter of the Instrument actions Fig 6-15: Action event handler Fig 6-16: Instrument UI with custom context menu Fig 7-1: Resx file Fig 7-2: Translated Resx file Fig 8-1: Global declaration Fig 8-2: Extended InitializeValueAccess method Fig 8-3: Event handler of the mouse down event Fig 8-4: Compute drag box method Fig 8-5: Mouse move event handler Fig 8-6: Control selection method Fig 10-1: Instrument error Fig 10-2: Property reference in Type.xml Fig 10-3: Property reference in Properties.xml Further Documentation 39

40 12 ETAS Contact Addresses ETAS HQ ETAS GmbH Borsigstraße 14 Phone: Stuttgart Fax: Germany WWW: ETAS Subsidiaries and Technical Support For details of your local sales office as well as your local technical support team and product hotlines, take a look at the ETAS website: ETAS subsidiaries WWW: ETAS technical support WWW: 40 ETAS Contact Addresses