Custom Transform Development

Many Transforms are provided when you purchase components of the MxSuite. In addition, you can write your own Transforms to perform custom signal manipulations, or connect to external devices or equipment that is not currently supported.  

hmtoggle_plus1Creating a New Custom Transform

This section guides you through building your first Custom Transform.  An MxTransIt Transform is a .NET (C#) class that implements the ITransform interface by inheriting BaseTransform and overriding various methods. Within the class are several methods to implement the Transform's behavior.  The methods are described below.  The Template Visual Studio project can be used to create a new Transform from scratch, or you can take the code of an existing Transform and modify it to fit your purpose. Use this procedure to create a Transform from scratch:

1.Select File->New->Custom Transform from the MxTransIt main menu:

NewCustomTransform

2.Create a new transform in this Location - Click 3dots_button to select a folder for the Transform's Visual Studio project files. The Transforms subfolder in the project folder is recommended.

3.Transform or Assembly Name - Enter a name for the Transform.  The name must be a valid C# identifier. Spaces and most special characters are not allowed. You can use the underline character.

4.Select Connector Transform or Signal Processing Transform.

5.Build/Output Location - Enter a location for the Visual Studio project output (the DLL). If you are using Windows 7, you cannot use Program Files or any of its subfolders.

6.Check Add the output location to the global transforms folders to add the Output Location to the Additional File Locations list. See Transform File Locations.

7.Click OK.
 
MxTransIt launches Visual Studio and performs a build. The new Transform is listed in the Toolbox.

To rebuild the solution, first close MxTransIt.

 
hmtoggle_plus1Transform Development Environment

It is recommended that you use the current or a recent release of Visual Studio to develop Custom Transforms.  You can use the Visual C# Express edition (downloadable free from the Microsoft web site). See Compatibility.

A Custom Transform builds into a .NET Assembly (a special windows DLL).  You cannot run and debug it standalone, it has to be invoked by some other program; in our case it is invoked by either MxVDev or MxTransIt. Typically, MxVDev is used for a complete test system, and MxTransIt is used for debugging the Custom Transform as a standalone.

There are two ways to configure Visual Studio to debug a .NET assembly (or in fact any DLL):

•Start External Program - In this case, configure the Visual Studio Custom Transform project to start MxVDev or MxTransIt when you click the Run button in Visual Studio.

oReview the Debug Properties for your Visual Studio Custom Transform project.  Ensure that the 'Start External Program' setting references the  (MxVDev or MxTransIt) executable located in the Bin subfolder of the MxSuite installation folder: C:\Program Files\MicroMax\...\bin\

oWhen you click the Run button in Visual Studio, your Transform is rebuilt, and MxVDev/MxTransIt is launched.

•Attach to Process - In this case, start MxVDev or MxTransIt manually, then cause Visual Studio to attach to that process.

oOpen the Visual Studio Custom Transform project.

oStart MxVDev or MxTransIt.

oIn Visual Studio, under the Debug menu item, select Attach to Process ...

oSelect the appropriate process (MxVGUI.exe or MxTransIt.exe) and click Attach.

Initially it may be simpler to use MxTransIt to test and debug your Transform.  You can also debug your Transform while it is in use with MxVDev.  This is how to test using MxTransIt.

•Start with very simple transform code and enhance it as you become more confident.

•Add your Transform to the MxTransIt model.  You should also add a Task‑>Periodic Interval Timer to the model to provide a clocking source.

•The standard main entry points in the Transform class are described in Execution Strategy.

oIn MxTransIt, when you click the RUN button, Arm() is called, then Start(), then Tick() is called periodically.

oWhen you click the Stop button, the Finish() method is called.

•You will be able to set breakpoints and step through your code, but only if you follow the steps described above under Using Visual Studio to debug a DLL.

Note that you cannot successfully re-build a Custom Transform project if its assembly is in use. The assembly will be in use if you have MxTransIt or MxVDev open; both load all available transforms and need to be closed in order to rebuild a transform assembly.
hmtoggle_plus1First Steps

•The Template Project is created by the New Custom Transform wizard.

•Before making any changes to the template project, verify that it builds in your environment without error.  When the project is built, it creates a Transform DLL (Transforms.YourTransformName.dll), and puts it in the specified output folder. Verify that this is the case.

•Once located in this folder, MxTransIt is "aware" of the Transform, and makes it available for selection from the Toolbox. If your Transform is not listed in the Toolbox, be sure it is in a properly configured Transform File Location.

•To use Visual Studio debugging tools, the .pdb file must be in the same folder as the DLL.

•Add the Transform to a new model in MxTransIt.

•Note that your Transform has one input and one output port.

•Once you can do this, close MxTransIt.  There is no need to save the model.

When you can reproduce the above steps, you are ready to make some changes.

The New‑>Custom Transform command inserts attributes similar to the following into the template code:

[Category("Custom Transforms")]

[DisplayName("MyTransformName")]

[Description("Custom Transform.")]

[Tags("Sample, Custom Transform, C#")]

The Category and Tags are displayed in the Tags column of the MxTransIt Toolbox. The DisplayName is the name used in the Toolbox. The Description is the text displayed at the bottom of the Toolbox when the transform is selected. You can change these values to make your transform easier to find and understand.

If you selected Connector Transform, the IsConnector attribute is also included.  It should not be changed.

[IsConnector(true)]

hmtoggle_plus1Basic Functionality

In this section we will add to basic functionality to the transform.  If this is your first transform, it would be worth following through these steps, to see if you can reproduce the behavior of the ABS Transform described below.

You can create the ports for a Transform in the Transform Constructor, or add them dynamically later after the Class has been created based on saved configuration or properties the user changes via MxTransIt.  For example:

•For a trivial Absolute Value Transform (that gives the absolute value of a number) with one input and one output, it would be fine to create the two Ports in the Class Constructor.

•For a transform that connects to some equipment, you may want to enumerate the hardware and dynamically configure the ports.

For now, add these two lines the default constructor:

this.AddPort(new InPort(this, new ContinuousFloatInfo("Value", SignalDataFlow.Input, -100.0, 100.0, 0.0)));

this.AddPort(new OutPort(this, new ContinuousFloatInfo("Abs", SignalDataFlow.Output, 0.0, 100.0, 0.0)));

Rebuild your transform and note that you now have a new Input Port named Value, and a new Output Port named Abs.

Notes:

•Currently, the Constructor (ctor) is called only when the transform is first created. If you add ports or make other changes to the Constructor, recreate your transform using the Toolbox. The original transform created with the New->Custom Transform wizard does not include changes you make to the Constructor.

•For message ports, see Example Code.

 

Use the methods described in Execution Strategy to give the execution engine access to your Transform.

See Example Code for examples of the following:

•Enumerations

•Properties

•Serializing properties

•Verbs

•Transitions and Persistent Transitions

Tick Method

The Tick method is called according to the Tick Order. There is a basic difference in the structure of the Tick method depending on whether the Transform is a Connector or not.  

The simpler case is if it is NOT a Connector.  Let's look at the Absolute Value Transform for both cases (even though we know it is not a connector).

Transform is NOT a Connector

The Tick method implementation is simple.

ITransition trans = null;

  foreach(InPort inport in this.myLivePorts)

  {

    while(inport.DequeTransition(out trans))

    {

double value = System.Math.Abs(((IContinuous)trans.Data).Value);

this.OutPortList[0].Transmit(new Transition(context.TickTime, new Continuous(value), context.WallClock.ElapsedTime));

    }

  }

  this.myLivePorts.Clear();

   

To explain briefly how this works:

•trans is a reference to an object of type ITransition.

•this.myLivePorts is a collection of inports that have received a transition since the last tick.

•DequeTransition - If a transition exists in the input port queue then DequeTransition will return True and set trans to reference (point to) that transition.

•Transitions only exist when a signal changes. So if you change the input Signal only once in a TestCase at say T=5 seconds then there will be one transition in the queue when the Tick is called and T=5s. There may also be a transition on the first Tick at T=0. In all the other periodic calls to Tick there will be no transitions in the queue.

Transform IS a Connector

Now, take a look at the Tick method for the IsConnector returns true case.  It gets called twice per model tick.  Once to deliver the stimuli from the Input Ports, and a second time to give you the opportunity to transmit updated values on the Output Ports. The template tick method has a default Switch statement, showing how to process the stimuli case and the responses.  In the sample below, in the Stimulus section, we read Transitions from the Input Port, find the absolute value, and save the value in this.myAbsoluteValue.  Then, in the Response section, we transmit the new value only when it changes on the output port. myLastAbsoluteValue is set to NaN in start to ensure the first comparison in the response tick always fails - so the initial state is always sent.

//Execution Fields

double myAbsoluteValue = 0.0;

double myLastAbsoluteValue = double.NaN;

public override void Start(StartContext context)

{

  base.Start(context);

  this.myLastAbsoluteValue = double.NaN;

}

public override void Tick(TickContext context)

{

  switch(context.TickType)

  {

    case TickContext.TickTypes.Stimulus:

        ITransition trans = null;

        foreach(InPort inport in this.myLivePorts)

        {

          while (inport.DequeTransition(out trans))

          {

              this.myAbsoluteValue = System.Math.Abs(((IContinuous)trans.Data).Value);

          }

        }

        this.myLivePorts.Clear();

        break;

    case TickContext.TickTypes.Response:

        if (this.myAbsoluteValue != this.myLastAbsoluteValue)

        {

          //Only send a transition when something changes

          this.OutPortList[0].Transmit(new Transition(trans.Time, new Continuous(this.myAbsoluteValue), context.WallClock.ElapsedTime));

          this.myLastAbsoluteValue = this.myAbsoluteValue;

        }

        break;

  }

}

 

Sending Transitions

A Transform must ONLY send transitions during the Tick function. The reason is that we perform other harness maintenance functions after ticking all the Transforms, and those Transforms should not produce transitions during that time. If the Transform needs to accumulate data outside of the ticking event, it must place that data in a queue and then pull the transitions out of the queue when the tick function for the Transform is executed.

Now that you have a transform you may want to test it by feeding in Stimuli and monitoring the output ports.  (See the section above for setting up the development environment for debugging).

•You can use standard waveform generators, such as a Pulse Train or Sine Wave, from the Toolbox, and connect them to your transform.

•The output from the Periodic Interval Timer can be used to simulate events or interrupts.

•Export the ports to MxVDev and use a TestCase to produce stimulus transitions or monitor response signals.

•Use Probes to monitor the transitions of any port.

There are several ways to make your completed Transform available for use on other PCs:

•Put the .dll file into a shared network folder. Use the procedure in Transform File Locations.

•Copy the .dll file to each PC. Use one of the recommended locations.

•If you prefer to write an install wizard or script, install the .dll in the folder indicated by the "MxVDefaultPath" registry key.

When the DLL file is present in a properly configured Transform File Location, your Custom Transform is available for selection from the Toolbox.

If the source code (.cs file) is stored in the Transforms subfolder of your project folder, it is compiled automatically each time the project is loaded into MxVDev. This is recommended if your Custom Transform is simple and small. Any time a new version of MxSuite is installed, your Custom Transforms must be recompiled.
hmtoggle_plus1Troubleshooting

Error:

1>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(3390,5): error MSB3021: Unable to copy file "obj\Debug\Transforms.NCT2.dll" to "C:\Users\paulm\Documents\+MxV Projects\NCT2\Transforms\NCT2\Debug\Transforms.NCT2.dll". The process cannot access the file 'C:\Users\paulm\Documents\+MxV Projects\NCT2\Transforms\NCT2\Debug\Transforms.NCT2.dll' because it is being used by another process.

Solution:

Close MxTransIt before building the Visual Studio solution.

Error:

Custom Transform project does not build after updating to a new version of the MxSuite.

Solution:

Update the references in the Visual Studio project. See Updating Custom Transforms for a New Version of MxSuite.

 

Related Topics:

User-Defined Transforms

Transform File Locations

Execution Strategy

MxTransIt Model–Tick Order

.NET API

Best Practices for Custom Transforms

Example Code

.NET Prerequisites for Custom Transform development

Updating Custom Transforms for a New Version of MxSuite