Controller¶

The Controller interface represents a motion controller. The controller with its sensors and actuators might be integrated into one physical package, or in case of multiple controllers they might be separate parts connected using a (real-time) bus.

In case the controller has an ID, the ID is automatically added as a suffix to the default name separated by a dash, e.g. “MyController-3”.

Reboot¶

A controller can be rebooted. Once rebooted, a “lost” connection is detected and the behavior is equal to Lost connections. However, after reconnecting none of the existing interfaces are valid anymore. All interfaces have to be retrieved again and any function call to an existing interface from prior to the reboot throws a exception. Rebooting (implicitly) releases all reserved resources.

Rebooting may be unsupported for specific controllers. In addition, rebooting can be disallowed in some top-controller states. When rebooting is not allowed, a forced reboot can be requested which is executed using the discovery mechanism and therefore ignores the top-controller state. It can be used to recover from a situation where a normal reboot is not possible. Forced reboot is only allowed for non-simulated top-controllers.

Initialization using XML¶

A controller can be initialized by means of the API methods or, in bulk, by feeding a buffer with XML data to LoadConfiguration. The complete XML data format is given in Configuration - Complete XML schema.

The entire XML tree is parsed before any configuration is applied to the controller. When the XML data is invalid, e.g. when the XML data is not schema compliant or contains read-only or nonexisting items, none of the configuration items in the XML data are applied. In case of invalid XML data a detailed error message, including line number, is returned in a string parameter.

Parameter sets: a parameter set is instantiated (and scoped) within an axis control. If a parameter set with the provided name already exists in the axis control where it is defined, then either:

if the exact same signals are listed, then the signal values are overwritten;
otherwise, initialization fails.

Axis control group: when an axis control group with the provided name already exists:

and it consists exactly of the axis controls listed in the XML file, then reconfigures that group
otherwise, initialization fails.

Ownership: parameter sets and axis control groups are dynamically created resources. When created through XML configuration, the controller keeps a reference. When the shared pointers to these resources go out of scope, they remain to exist in the controller. Only when a Destroy functionality is called on these objects, the resources are released.

Variants: any node in the xml tree can be surrounded by variant nodes. Variants can be selected and only selected variants are applied, allowing a single configuration file to be used in different use-cases. Variants have string name and value attributes. Selection is done by referencing a variant by name with a matching value. Variants with matching name but different value are not applied. Variants can be default selected in the XML tree itself inside the Variant node directly below the root controller. Selections by API call overrule the default selections defined in the XML tree.

It is not needed to reference every variant explicitly, unreferenced variants are not applied. Variants can be nested.

File paths: file paths can either be absolute paths or relative paths. Relative file paths in the XML configuration are resolved using the RelativeTo attribute as follows:

RelativeTo="CurrentWorkingDirectory": Relative to current working directory. This is the default value when the RelativeTo attribute is not specified.
RelativeTo="File": Relative to parent directory of the XML configuration file. This option may only be specified when loading an XML configuration from file.

Note

For multiple defined elements in the XML tree, it is not defined which element will be applied.

Note

The current working directory can be adjusted using language specific methods.

C++

std::filesystem::current_path

Directory.SetCurrentDirectory

Firmware update¶

Firmware updates are performed using the Updatable interface. A successful firmware upload sequence is depicted in Ethernet-based controller firmware upload.

Ethernet-based controller firmware upload¶

A firmware upload does not take effect immediately; a reboot is required for the new firmware to become active.

Event¶

A controller is also an event source. By default all controllers implement the events listed in the following table:

Name	Reset Value	Description
EventQueueOverrun	False	Event queue overrun, see Events - Overflow

Signals¶

All controllers, as well as sub-controllers with co-processor, contain the signals listed in the following table:

Name	Data type	R/W	Description
SampleCount	UInt32	R	Incremented every cycle of the sample loop and provides the basis for SampleTimestamp. The value is cleared on power-on reset. The application must handle possible counter overflows. For example when the sample rate of a motion controller is 4 kHz, the counter overflows in approximately 12 days.
SampleLoad	Float	R	Percentage of reserved controller time that has been spent.
SamplePeriod	Float	R/W	The interval at which signals in this controller are updated. Note that for some controllers the SamplePeriod is read-only.
SampleTimestamp	Double	R	Computed time in seconds which provides the basis for acquisition timestamps. The application must be able to handle timestamps wrapping back to zero when SampleCount overflows; hereby sampled time precision between separate samples is guaranteed. Exact reference point is product specific.

Destruction¶

A processing block is destroyed by calling Dispose (for C#) or Destroy (for C++).

When destroying a non-simulated controllers an UnsupportedException is thrown. If the request to the simulator service is not handled in time a TimeoutException is thrown. If another protocol error occurs during the disposal of the controller a CommunicationErrorException is thrown.

UnsupportedException
TimeoutException
CommunicationErrorException

C++

CUnsupportedException
CTimeoutException
CCommunicationErrorException