S6 Creating a Connector Editor for changing Device Parameters offline

This article demonstrates how to create a control that can be integrated within the CoDeSys device editor and which is able to alter some parameters of a device. Furthermore, the corresponding device description is also explained.

Why do you need a Connector Editor?

By default, the parameters of a device are displayed and edited in a large table which displays all parameters of a device. Although different parameters can be grouped within folders in that list, things will quickly become confusing when the device has got hundreds or even thousands of parameters. This is one of the main reasons why an Automation Platform customer might want to have his own configurator plug-in: the most important parameters can be displayed very user friendly, maybe with graphical content or special user interface gadgets that cannot be found in the table. Not to mention the possibility to realize some aspects of corporate design there. But nice representation is not everything: Connector Editors also allow to check the validity of parameters in a much more customizable way, and to programmatically define relationships between different parameters. Last but not least a Connector Editor can define additional parameters that are not part of the device description, delete existing ones, and change other things of a device configuration like the I/O mapping.

Task

Consider the following device description:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceDescription xmlns="http://www.3s-software.com/schemas/DeviceDescription-1.0.xsd">
  <Types namespace="localTypes">
  </Types>
  <Strings namespace="local">
  </Strings>
  <Device>
    <DeviceIdentification>
      <Type>123467</Type>
      <Id>0000 0001</Id>
      <Version>1.0.0.0</Version>
    </DeviceIdentification>
    <DeviceInfo>
      <Name name="local:typename">Sample Master</Name>
      <Description name="local:description">Sample Master</Description>
      <Vendor name="local:vender">Samples and More Inc.</Vendor>
      <OrderNumber>???</OrderNumber>
    </DeviceInfo>
    <Connector connectorId="1" explicit="false" hostpath="-1" interface="Common.PCI" moduleType="257" role="child">
      <InterfaceName name="local:interfacename1">PCI-Bus</InterfaceName>
      <Slot allowEmpty="false" count="1" />
    </Connector>
    <Connector connectorId="2" explicit="false" hostpath="1" interface="Common.Ethercat" moduleType="54321" role="parent">
      <InterfaceName name="local:interfacename2">Sample</InterfaceName>
      <Var max="125"/>
      <HostParameterSet>
         <Parameter ParameterId="1" type="std:DWORD">
           <Attributes offlineaccess="readwrite" download="true" functional="false"/>
           <Default>255</Default>
           <MinValue>0</MinValue>
           <MaxValue>512</MaxValue>
           <Name name="local:p1name">Sample parameter 1</Name>
           <Description name="local:p1desc">Sample parameter 1</Description>
         </Parameter>
         <Parameter ParameterId="2" type="std:STRING">
           <Attributes offlineaccess="readwrite" download="true" functional="false"/>
           <Default>Hello!</Default>
           <Name name="local:p2name">Sample parameter 2</Name>
           <Description name="local:p2desc">Sample parameter 2</Description>
         </Parameter>
         <Parameter ParameterId="3" type="std:BOOL">
           <Attributes offlineaccess="readwrite" download="true" functional="false"/>
           <Default>TRUE</Default>
           <Name name="local:p3name">Sample parameter 3</Name>
           <Description name="local:p3desc">Sample parameter 3</Description>
         </Parameter>
      </HostParameterSet>
    </Connector>
    <DeviceParameterSet>
    </DeviceParameterSet>
  </Device>
</DeviceDescription>

You can see that the device description contains a child connector with a host parameter set which contains three parameters, with the imaginative names Sample parameter 1, Sample parameter 2, and Sample parameter 3. Let's implement a configurator page contains an up-down control, a textbox, and a checkbox, according to the datatypes of the parameters, to allow the user the modification of those parameters.

Solution: Implement a Connector Editor!

Often in Automation Platform, when something like an object or a piece of user interface should be automatically created during runtime, there is a factory implementation that does the job. No exception here: Since an editor should be created that modifies the contents of a connector, the name of the interface is IConnectorEditorFactory.

[TypeGuid("{76F8F5FD-4C1B-420b-8822-72E9035DB51A}")]
public class EditorFactory : IConnectorEditorFactory
{
    public IConnectorEditor Create(IDeviceObject deviceObject, IConnector connector, HideParameterDelegate paramFilter)
    {
        return new Editor();
    }

    public int GetMatch(IDeviceObject deviceObject, IConnector connector)
    {
        if (connector.ModuleType == 54321)
            return Match.Type;
        else
            return Match.None;
    }
}

When a device editor is opened, it traverses all currently installed connector editor factories and calls their GetMatch methods. There are several possible results:

  • Match.None: The editor created by this factory is not suitable for the specified device or connector. The Create method will not be called at all.
  • Match.Generic: The editor provides a generic view on the device or connector. As this is not used for specialized editors, the editor page will be displayed rather at the end of the tab page list because there is a good chance that there are "better" editors. And if the user does not want to see generic editors at all (see Tools :: Options :: Device editor for a checkbox to enable or disable generic editors), the Create method will not be called.
  • Match.Type: The editor is suitable for all devices or connectors of the same type. In the tab page order, those editors have a higher priority than those with Match.Generic.
  • Match.Device: The editor is suitable for all versions of the specified device or connector. In the tab page order, those editors have a higher priority than those with Match.Type.
  • Match.FullMatch: The editor is suitable for exactly the specified version of the device or connector. Those editors will appear at the very front in the tab page order.

After all, the CoDeSys device editor will call the Create methods of all factories that returned a match, and display the resulting pages in the order of their match quality, respectively.

The editor

The result of an IConnectorEditorFactory is an instance of IConnectorEditor. A connector editor is a group of tab pages that are displayed one after another. Furthermore, the connector editor knows about the hosting control (the connector editor frame), the connector ID identifying which connector of the device should be displayed (in our sample this ID can be used as a transparent handle), and the reload/save mechanism that is conceptually very similar to full-blown IEditorView implementations.

class Editor : IConnectorEditor
{
    private IConnectorEditorFrame _frame;
    private int _nConnectorId;
    private Page _page;

    public IConnectorEditorFrame ConnectorEditorFrame
    {
        get { return _frame; }
        set { _frame = value; }
    }

    public int ConnectorId
    {
        get { return _nConnectorId; }
        set { _nConnectorId = value; }
    }

    public HideParameterDelegate GetParameterFilter()
    {
        return null;
    }

    public bool HideGenericEditor
    {
        get { return false; }
    }

    public IEditorPage[] Pages
    {
        get
        {
            if (_page != null)
                return new IEditorPage[] { _page };
            else
                return new IEditorPage[] { };
        }
    }

    public void Reload()
    {
        if (_page == null)
        {
            _page = new Page();
            _page.SetEditor(this);
        }
        _page.Reload();
    }

    public void Save(bool bCommit)
    {
        if (_page != null)
            _page.Save(bCommit);
    }
}

Nothing exciting here: host and connector ID are simply remembered, the pages (in our case exactly one) are created and initialized on demand, the Reload and Save methods are delegated, and the remain is not interesting for us.

The editor page

Finally, the editor page - an implementation of the IEditorPage interface - is responsible for displaying the parameter values to the user and modifying the device object in turn when user edits them. This is the core code snippet of our sample, but nonetheless not very complicated.

public partial class Page : UserControl, IEditorPage, IEditorPageAppearance
{
    private IConnectorEditor _editor;
    private bool _bReload;

    private static readonly int PARAMETERID_1 = 1;
    private static readonly int PARAMETERID_2 = 2;
    private static readonly int PARAMETERID_3 = 3;
    
    public Page()
    {
        InitializeComponent();
    }

    public Control Control
    {
        get { return this; }
    }

    public Icon Icon
    {
        get { return null; }
    }

    public string PageName
    {
        get { return Resources.PageName; }
    }

    public string PageIdentifier
    {
        get { return "SamplePage"; }
    }

    internal void SetEditor(IConnectorEditor editor)
    {
        if (_editor != null)
            _editor.ConnectorEditorFrame.ParameterChanged -= new _3S.CoDeSys.DeviceObject.ParameterChangedEventHandler(OnParameterChanged);
        _editor = editor;
        if (_editor != null)
            _editor.ConnectorEditorFrame.ParameterChanged += new _3S.CoDeSys.DeviceObject.ParameterChangedEventHandler(OnParameterChanged);
    }

    internal void Reload()
    {
        try
        {
            _bReload = true;

            if (_editor == null)
                return;
            
            IConnector connector = _editor.ConnectorEditorFrame.GetConnector(_editor.ConnectorId, false);
            Debug.Assert(connector != null);    // Should always be possible to get a readable copy.
            if (connector.HostParameterSet == null)
                return;

            _parameter1UpDown.Enabled = connector.HostParameterSet.Contains(PARAMETERID_1);
            IParameter parameter1 = connector.HostParameterSet.GetParameter(PARAMETERID_1);
            decimal value;
            decimal.TryParse(parameter1.Value, out value);
            _parameter1UpDown.Minimum = 0;
            _parameter1UpDown.Maximum = 512;
            _parameter1UpDown.Value = value > 512 ? 512 : value < 0 ? 0 : value;

            ...
        }
        finally
        {
            _bReload = false;
        }
    }

    internal void Save(bool bCommit)
    {
        // Modifications are immediately done while the controls are modified. The modifiable
        // copy of the device object will be automatically returned by the calling code.
    }

    void OnParameterChanged(object sender, ParameterChangedEventArgs e)
    {
        Reload();
    }

    private void _parameter1UpDown_ValueChanged(object sender, EventArgs e)
    {
        if (_bReload)
            return;
        if (_editor == null)
            return;

        IConnector connector = _editor.ConnectorEditorFrame.GetConnector(_editor.ConnectorId, true);
        if (connector != null)
        {
            if (connector.HostParameterSet.Contains(PARAMETERID_1))
            {
                IParameter parameter = connector.HostParameterSet.GetParameter(PARAMETERID_1);
                parameter.Value = _parameter1UpDown.Value.ToString(CultureInfo.InvariantCulture);
            }
        }
        else
        {
            // Could not get a modifiable copy of the device object (maybe the user does not
            // have write access to that object). Undo the changes so far.
            Reload();
        }
    }

    ...
}

Immediately after the connector editor creates the page, it calls SetEditor to "connect" the page.

Shortly before the page is displayed to the user, and at any time the underlying device object changes externally, the Reload method is called by the framework. It obtains an instance of the connector data itself, by calling GetConnector of the connector editor frame. The argument false is necessary here to indicate that the information should be accessed read-only. The connector itself provides access to the entire host parameter set, and the remaining method simply reads the parameter values and displays them in the page controls. By the way: a reentrance loop (_bReload here ) is always a good idea for Reload implementations...

Once the user starts to make modifications in the editor, our implementation will receive a corresponding event. In the code snippet above this can be found in the _parameter1UpDown_ValueChanged method. Again, we obtain the host parameter set over the connector editor frame, but this time with argument true because we attempt to modify the underlying device object. If we get that copy, we simply write the current value back. If not (maybe the user does not have write access to that device object), we undo the changes by calling Reload again. By the way: the usual transactions with Object Manager regarding read-only and modifiable copies are not necessary for configurator plug-ins, because all that bookkeeping is already done by the hosting device editor itself.

Now what if the user switches between the editor pages and modifies the same parameters in - say - the generic parameter page? That's why we attached to the ParameterChanged event during the initialization phase. Once we get that event, we update our contents by calling Reload again. Complicated constraint checks between parameters are also likely to displayed in that event handler.

Running the sample

  1. Download the attached source.
  2. If not already done, set the environment variable %APCOMMON% to the Common directory of your CoDeSys installation. (This is the directory where CoDeSys.exe, IPMCLI.exe, and IPM.exe are installed.)
  3. Start Visual Studio and open the solution DeviceEditorPage.sln.
  4. Depending on your installation, you must correct some references to interface components, so that they point into the Interface Binaries folder in your Automation Platform SDK installation.
  5. Build the sample. The plug-in will be automatically installed.
  6. Use IPM.exe in order to add the plug-in Sample: Device Editor Page to one of your version profiles.
  7. Start CoDeSys and ignore the message about the missing plug-in key.
  8. Take the Sample.devdesc.xml device description and install it to your device repository by clicking Tools :: Install device... or Tools :: Device Repository....
  9. Create a new project with a standard PLC and add the sample device below.

You will see the device editor containing several tabs, and one of the tabs is our "Sample page" where you can modify the parameters of the device. It is interesting to activate the generic editors in Tools :: Options :: Device editor. If they are displayed you can switch between our page and the generic page and see how they influence each other.

ConnectorEditor.zip

11 KB