Serialization Overview

MPX object configuration is saved to a file by creating a ConfigSaver object and calling its SaveToFile method. This will save the value of all of the objects properties into a file.

Example - Save Controller Configuration

Object configuration is loaded from a file by creating a ConfigLoader object and calling its LoadFromFile method. This operation sets all of the objects properties to the values stored in the file.

C# Sample Code:

// Save the entire Controller configuration, including child objects.
public void SaveController()
{
Mpx.Controller controller = new Mpx.Controller(0);
Mpx.ConfigSaver saver = new Mpx.ConfigSaver();

saver.SaveToFile(controller, "controllerConfig.xml");
}

Example - Load Controller Configuration

C# Sample Code:

// Load controller configuration.
public void LoadController()
{
Mpx. Controller controller = new Mpx. Controller(0);
Mpx. ConfigLoader loader = new Mpx. ConfigLoader();

loader. LoadFromFile( controller, "controllerConfig.xml");
}

Events

The ConfigSaver and ConfigLoader classes each have members that are callback functions (or delegates, in .NET speak). The user assigns these members to functions that handle particular events.

The following sections describe events that are generated by both the ConfigSaver and ConfigLoader classes.

PropertyStatus Events

The PropertyStatusEvent member is called immediately prior to processing a property. Various bits of information are passed to the PropertyStatusEvent function, including the following:

PercentageDone - the level of completion of the operation
PropertyPath - the path to the property currently being saved or loaded

The user can veto the operation by setting the SkipProperty member to true. In this way, certain properties (or entire objects) can be excluded from being saved or loaded.

Example - Handle PropertyStatus events

C# Sample Code:

// This method handles PropertyStatus events that occur while loading
// configuration to object.
public void OnSavePropertyStatus(Mpx.ConfigSaver saver,
Mpx.ConfigSavePropertyStatusEventArgs e)
{
string msg;

// Print the current property and the percentage done
// Example output:
// 25%: Controller.Axis[2].AmpDisableAction
// skipped
msg = e.PercentageDone
    + "%: "
    + e.PropertyPath
    + "\n";
System.Console.Write(msg);

// Don't save CAN or CAN Node objects
if (e.PropertyPath.StartsWith("Controller.Can"))
{
System.Console.Write(" skipped\n");
e.SkipProperty = true;
}
}

// Save the entire Controller configuration, including child objects.
//
// Handle ConfigSavePropertyStatus events in order to display
// progress and exclude Can and CanNode objects from being saved.
public void SaveController()
{
Mpx.Controller controller = new Mpx.Controller(0);
Mpx.ConfigSaver saver = new Mpx.ConfigSaver();

// Have the OnSavePropertyStatus method handle
// ConfigSavePropertyStatus events
saver.PropertyStatusEvent += OnSavePropertyStatus;

saver.SaveToFile(controller, "controllerConfig.xml");
}

For the ConfigLoader object, the PropertyStatusEvent member has access to additional bits of information:

CurrentValueText - The string representation of the current value of the property.
NewValueText - The string representation of the value that the property will be set to.

These values can be compared to determine which properties are actually being modified.

Example - Handle PropertyStatus events

C# Sample Code:

// This method handles PropertyStatus events that occur while loading
// configuration to an object.
public void OnLoadPropertyStatus(Mpx.ConfigLoader loader,
Mpx.ConfigLoadPropertyStatusEventArgs e)
{
string msg;

// Print the current property and the percentage done
// Example output:
// 25%: Controller.Axis[2].AmpDisableAction
//     Current Value: None
//     New Value: CmdEqAct
msg = e.PercentageDone
    + "%: "
    + e.PropertyPath
    + "\n";

if (e.NewValueText != e.CurrentValueText)
{
// The property value is going to change. Display the current value
// and the new value.
msg += " Current Value: "
    + e.CurrentValueText
    + "\n New Value: "
    + e.NewValueText
    + "\n";
}

System.Console.Write(msg);
}

// Load controller configuration.
// Handle PropertyStatus events in order to display progress.
public void LoadController()
{
Mpx.Controller controller = new Mpx.Controller(0);
Mpx.ConfigLoader loader = new Mpx.ConfigLoader();

    // Have the OnLoadPropertyStatus method handle PropertyStatus
    // events.
    loader.PropertyStatusEvent += OnLoadPropertyStatus;

loader.LoadFromFile(controller, "controllerConfig.xml");
}

The following classes define the PropertyStatus event handler delegate and associated arguments for both the ConfigSaver and ConfigLoader classes:

ConfigSaver	ConfigLoader
ConfigSaver.PropertyStatusEvent	ConfigLoader.PropertyStatusEvent
ConfigSaver.PropertyStatusEventHandler	ConfigLoader.PropertyStatusEventHandler
ConfigSavePropertyStatusEventArgs	ConfigLoadPropertyStatusEventArgs

PropertyError Events

The PropertyErrorEvent member is called whenever an error occurs while processing a particular property. If the user does not set the PropertyErrorEvent member and an error occurs while saving or loading configuration, then the save and load operations will fail by throwing an exception. By setting the PropertyErrorEvent member, the user will make the operation more tolerant of borderline cases, such as missing elements in the configuration data.

Inside the PropertyErrorEvent event handler, the user can control how errors are displayed and whether or not to cancel the operation.

Example - Handle PropertyError events

C# Sample Code:

// This method handles PropertyError events that occur while loading
// configuration to an object.
public void OnLoadPropertyError(Mpx.ConfigLoader loader,
Mpx.ConfigLoadPropertyErrorEventArgs e)
{
string msg;

   if (e.ErrorCode == Mpx.ConfigLoadErrorCode.Missing)
   {
      if (e.PropertyPath.StartsWith("Controller.Can"))
      {
         // Ignore missing Can and CanNode objects
         return;
      }

      // A property is missing in the config file. Print a warning.
      msg = "Warning: ";
   }
   else
   {
      // For all other errors, print an error message and cancel the save.
      msg = "Error: ";

      // Cancel the save operation
      loader.Cancel();
   }

   // Print an informative message
   // Example output:
   // ERROR: Controller.Axis[2]: Axis is not enabled
   msg += e.PropertyPath
      + ": "
      + e.Message
      + "\n";
   System.Console.Write(msg);
}

// Load controller configuration.
// Handle PropertyError events in order to display errors and warnings.
// Handle PropertyStatus events in order to display progress.
public void LoadController()
{
Mpx.Controller controller = new Mpx.Controller(0);
Mpx.ConfigLoader loader = new Mpx.ConfigLoader();

// Have the OnLoadPropertyError method handle PropertyError events
loader.PropertyErrorEvent += OnLoadPropertyError;

loader.LoadFromFile(controller, "controllerConfig.xml");
}

The following classes define the PropertyError event handler delegate and associated arguments for both the ConfigSaver and ConfigLoader classes:

ConfigSaver	ConfigLoader
ConfigSaver.PropertyErrorEvent	ConfigLoader.PropertyErrorEvent
ConfigSaver.PropertyErrorEventHandler	ConfigLoader.PropertyErrorEventHandler
ConfigSavePropertyErrorEventArgs	ConfigLoadPropertyErrorEventArgs
ConfigSaveErrorCode	ConfigLoadErrorCode

Copying One Object to Another

The configuration files are designed to contain one object and its child objects. This allows an object to be copied to another object of the same type. For example, a file that contains Axis configuration can be loaded on any valid Axis object.

When saving an object, the user can specify whether or not to include child objects by setting the IncludeChildren member.

If child objects are included when saving, care must be taken that the object that is the target for loading has the same number of sub-objects as the original. Errors will be generated for objects that exist in the configuration data and not on the controller, and visa-versa.

Example - Save Axis Configuration

C# Sample Code:

// Save Axis configuration
public void SaveAxisOnly()
{
   Mpx.Controller controller = new Mpx.Controller(0);
   Mpx.Axis axis0 = controller.Axis[0];
   Mpx.ConfigSaver saver = new Mpx.ConfigSaver();

// Have the OnSavePropertyError method handle PropertyError events
saver.PropertyErrorEvent += OnSavePropertyError;

saver.SaveToFile(axis0, "axisOnlyConfig.xml");
}

// Load axis configuration onto 2 different axes
public void LoadAxes()
{
Mpx.Controller controller = new Mpx.Controller(0);
Mpx.ConfigLoader loader = new Mpx.ConfigLoader();

// Have the OnLoadPropertyError method handle PropertyError events
loader.PropertyErrorEvent += OnLoadPropertyError;

loader.LoadFromFile(controller.Axis[0], "axisOnlyConfig.xml");
loader.LoadFromFile(controller.Axis[1], "axisOnlyConfig.xml");
}

Topology Check

For the 2.0 release, the following features have been implemented in regards to topology:

SynqNet Object
For the SynqNet object, several read-only topology-related properties are saved. Currently, these properties are NOT used to confirm a topology match. They are saved for informational purposes only. The following properties are saved:
- TopologySaved
- TopologyType

SqNode Object
For the SqNode object, several read-only topology-related properties are saved. Currently, these properties are NOT used to confirm a topology match. They are saved for informational purposes only. The following properties are saved:
     - FpgaId
     - Option
     - ProductId
     - ManufacturerId

Axis Object
For the Axis object, several read-only topology-related properties are saved. These are the following:
- NodeName
- DriveFirmwareVersion
If the current value for the NodeName property does not match the value saved in the configuration data, then the DriveParams are not loaded and an error event is generated.

If the value of the NodeName property does match, but the value of the DriveFirmwareVersion property does not, then the DriveParams are loaded, but an error event is generated anyway.

Events

PropertyStatus Events

PropertyError Events

Copying One Object to Another

See Also

Topology Check