Custom Transform .NET API - Programmer's Reference

The Transform's fields are broken down into two important sets, Configuration Fields and Execution Fields.

The Configuration Fields consist of all the specific settings required to configure and connect the transform.

Execution Fields need to exist only while running the model.

The distinction is important as only the Configuration Fields should be handled in the methods and properties to save the transform to XML.

The execution fields should be recreated during the Set Up phase of model execution.

For example, a logging transform might have a string property for the folder which it should log to. This string should be saved and loaded from XML so this is a configuration field.

However, the actual file handle used to write the data to disk is an execution-only field.

Configuration Fields not only must be saved and loaded from XML but also must be copied in the copy constructor to properly implement the Clone method (this is required or else features such as Copy & Paste will delete data!).

Execution fields should not be saved to XML nor copied in the copy ctor.

MxTransIt leverages the .NET Property Grid and Code Attribute infrastructure for transform configuration.

The Property Grid for the VectorCANtech transform is shown below:

By default, all public properties are automatically shown on the Property Grid when the transform is selected in MxTransIt.

The behavior of the Property Grid is tweaked through the use of various code attributes; Category, DisplayName, Description, Browsable, ReadOnly, TypeConverter, & Editor are commonly used attributes related to the Property Grid.

Category

The category is a string attribute that sets which section the property is organized under in the Property Grid.

The bold sections in the grid shown above are the categories: Description, Editing, Internal, Testing, Vector CANtech Configuration, Vector CANtech Device Selection, and Vector CANtech Diagnostics.

DisplayName

By default, the name shown in the Property Grid is the code-name of the property. For example, "BitRate".

The display name attribute allows you to override this default to set a more appropriate name, for example, "Bit Rate (bps)".

Description

The text of the description attributes appears at the bottom of the Property Grid when that property is selected.

Unless this attribute is set, the default description is the property's display name.

Browsable

A public property can be hidden from the Property Grid by tagging it with the "Browsable" attribute set to false.

ReadOnly

A property can be marked as Read-Only in the Property Grid even if it has both a set & get by tagging it with the ReadOnly attribute set to true.

TypeConverter

Type converters are special classes that provide two-way conversion between one type of data and another. A common use is to provide a drop-down list of choices for a property.

First the user must derive a class from System.ComponentModel.TypeConverter and override a few methods (see example below). Then the property must be tagged with a TypeConverter attribute specifying the type-converter classes to use.

[Category("Vector CANtech Device Selection")]

[DisplayName("Selected Device")]

[TypeConverter(typeof(VectorDeviceUITypeEditor))]

public string DeviceString {}

public class VectorDeviceUITypeEditor : TypeConverter

{

   public override bool GetStandardValuesSupported(ITypeDescriptorContext context)

   {

      return true;

   }

  public override bool GetStandardValuesExclusive(ITypeDescriptorContext context)

   {

      return true;

   }

  public override TypeConverter.StandardValuesCollection GetStandardValues(ITypeDescriptorContext context)

   {

     List<string> choices = new List<string>();

      List<VectorCANtechDevice> devices = VectorCANtechDevice.ScanForDevices();

     foreach (VectorCANtechDevice device in devices)

       {

           choices.Add(device.ToString());

       }

     return new StandardValuesCollection(choices.ToArray());

   }

}

Editor

The Editor attribute is similar to the TypeConverter attribute but allows a customized form to be shown to edit the property. The editor class specified by this attribute must derive from System.Drawing.Design.UITypeEditor.

A common use for this attribute, is to allow the user to browse for a file or folder. We provide the MicroMax.Design.FilePathTypeEditor class to make this easy to do; the FilePathTypEditor defaults to *.* but the title-bar text, file types, etc.. can be customized by deriving a new class.

[DisplayName("Dictionary Path")]

[EditorAttribute(typeof(MicroMax.Design.CsvPathTypeEditor), typeof(System.Drawing.Design.UITypeEditor))]

public string DictionaryPath

{

   get { return myDictionaryPath; }

  set

  {

     IntegrityFailures failures = new IntegrityFailures();

      this.LoadDictionary(value, failures);

       failures.ThrowIfFailure(string.Format("Failed to read CSV file \"{0}\"", value));

     this.myDictionaryPath = value;

   }

}

public class CsvPathTypeEditor

: MicroMax.Design.FilePathTypeEditor

{

   protected override string Title

   {

      get { return "Select CSV File"; }

   }

  protected override string Filters

   {

      get { return "CSV Files (.csv)|*.csv|All Files (*.*)|*.*"; }

   }

  protected override string DefaultFile

   {

      get { return System.IO.Path.Combine(System.IO.Directory.GetCurrentDirectory(), "*.csv"); }

   }

}

In the Template Transform you will find the ITransform region.  It has minimal implementations of six public methods.  The purpose served by these methods is described below.

public override void SetUp (SetUpContext context)

•This method is invoked when a Project is loaded. It may also be invoked when project settings are edited.  It may be called several times before Start is called.

•You should perform preparation work here that needs to be performed when the project is loaded.  Examples include:

oAllocate execution resources

oOpen files

oCreate threads

oOpen sockets

oLaunch other processes

oCreate COM/DOM proxy objects

•The transform should keep track of whether or not it is set-up and skip redundant set-ups; if a relevant property is changed it should fall-out of its "already set-up" state

public override void Arm (ArmContext context)

•This is called once when the Harness starts running. It should be used to prepare the Transform to run.

•All Transforms are armed (this method is called), before any Transform is started.

public override void Start (StartContext context)

•This method is invoked once every time that the Simulation is started

•Start data-acquisition - this function needs to be quick as it affects time-synchronization; perform lengthy initialization in SetUp.

public override void Tick (TickContext context)

This method is invoked periodically while the simulation executes.

•In this method, input Transitions should be processed and outputs of the Transform should be updated.

•When creating Transitions ensure that they are provided with the correct time stamp; there are two time-stamps on every transition, simulation time and wall-time. If the simulation runs in "real-time" then the simulation time matches wall-time.

•The simulation time stamp may be provided by an external entity, particularly for DAQ devices.

•The simulation clock may be used to time-stamp the transitions if no other time source is available and the provided wall-clock should be used to set the real-time time-stamp. For example, context.SimulationClock.ElapsedTime and context.WallClock.ElapsedTime.

•For a Signal Processing Transform this method is invoked once per Simulation Tick.

•For a Connector Transform (SUT Transform) it is invoked twice per Simulation Tick. First we process the Input Transitions during the stimulus invocation, and deliver output transitions in the response invocation.  This is achieved using switch statement as follows:

switch (context.TickType)

{

  case TickContext.TickTypes.Stimulus:

     //Your Code to process Input Transitions

     break;

  case TickContext.TickTypes.Response:

     //Your Code to enqueue Output Transitions

     break;

}

myLivePorts

This is a list of references to InPorts that have pending Transitions that need to be de-queued.

•Your transform code does not have to check every InPort to see if it has Transitions waiting to be processed.  myLivePorts is a list of the ports that actually have Transitions pending.

•Typically you will just loop through this list to read the Transitions that have been queued for processing by your Transform.  For example under the .Stimulus case above, you might write the code:

foreach (InPort inport in this.myLivePorts)

 {

    ITransition trans = null;

    while (inport.DequeTransition(out trans))

       {

          // Act on transition (trans)

       }

 }

public override void Finish (FinishContext context))

•This method is invoked once when the Simulation is stopped

•Execution has completed, stop DAQ

•Do not "throw-away" any data yet, just suspend execution.

public override void Reset (ResetContext context)

•This method is invoked when the Simulation is rewound ready for another run and may also be called at other times when the simulation should be reset to its initial state.

•Clear out timers, collections, & statistics in this method

public override void TearDown (TearDownContext context)

•This method is invoked after the project is closed. It may also be invoked when Project Settings are edited.

•Disconnect from most resources – close files, close handles

•You may continue to maintain connection to external programs that are time consuming to recreate, for example, keep connection to Matlab but close the model.  If it is simple/fast, such as an open network socket or open file, they should be closed here.

public override bool ToXML ()

public override bool FromXML ()

•A complete XML element can be stored and retrieved (providing an ordered hierarchy) via the ToXml and FromXml methods.

•An array of System.Xml.XmlElement must be created using a System.Xml.XmlDocument and then set to the Xml.Xml3.Transform's Any property (not this is not the same as AnyAttr that is used by the AnyAttributes property).