Top-controller¶

The TopController interface represents a top-level motion controller, that is: a controller that a client can directly connect to via a non-real-time Ethernet connection. A top-controller controls one or more sub-controllers via real-time interfaces. These sub-controllers might be incorporated in a single physical package together with the top-controller or they might be connected via external real-busses.

Client connection¶

New connections¶

When a new connection has been setup, the application might want to query relevant controller status information. See the following list, and Controller initialization sequence and Connection loss sequence for some hints:

Checking whether controller firmware is compatible with the used motion API using IsCompatible.
Checking whether controller firmware is up to date using IUpdatable.ProductNumber.
Checking the state of specific axes (in case of a recovered connection to a still running controller) by reading the axis control state, IsHomed, and IsAligned signals.

Controller initialization sequence¶

Lost connections¶

The connection between a client and a controller is based on the TCP protocol. Connection loss is detected in two ways:

Passively using TCP retransmission timeout:
- Connection loss is only detected when the connection is used, i.e. API calls to (or callbacks from) the controller are executing.
- Connection loss detection time is typically in the order of minutes, because of operating system timeout values which are often not configurable at all, or not configurable for a single connection.
- Not configurable using the Motion API. See the documentation of the operating system for details.
Actively using TCP keep-alive:
- Connection loss is also detected when the connection is idle, i.e. no API calls to (or callbacks from) the controller are executing, at the expense of sending empty TCP segments when the connection is idle.
- Connection loss detection time is configurable per connection, in a range from seconds to days.
- Configurable using the Motion API (see Keep-alive for details).

The application can register a function to be called when connection loss is detected, see ISystem.SubscribeConnectionLost and IController.SubscribeConnectionLost. See Connection loss sequence for a typical sequence to handle lost connections. When a connection to the controller is lost, most of the functions throw a ConnectionLostException.

Note

Resources, which were reserved (acquisition, subscriptions) are not released automatically, they keep being reserved by the client that initially received them for the duration of the configured 15 expiration time. For more information about the expiration time also see Expiration.

When the connection to a controller is lost, the background discovery process tries to reconnect to the controller (see Initialization (using discovery)). If the connection is reestablished, the callbacks are registered using ISystem.SubscribeConnection and IController.SubscribeConnection is called (with the same controller interface). The same interface that was used before the connection was lost is still valid, and therefore the same methods as shown in Controller initialization sequence and Connection loss sequence can be invoked on this interface.

Connection loss sequence¶

Keep-alive¶

TCP keep-alive can be used to:

Prevent disconnection due to network inactivity.
Detect connection loss (e.g. when power-cycling a hardware target).

The keep-alive mechanism works by sending a keep-alive probe (i.e. an empty TCP segment) when no data is sent for a certain amount of time. When the other side of the connection acknowledges, the connection is considered to be alive. When no acknowledgment is received within a certain timeout, another probe may be sent. This may be repeated several times. When no acknowledgment is received within a certain timeout, and the maximum number of probes is reached, the connection is considered to be lost. Configurable settings and their default value are shown in the following table:

Setting	Description	Default value
KeepAliveSettings.IdleTimeout	Timeout in seconds between the last data packet and the first keep-alive probe. Negative value means infinite.	1 second
KeepAliveSettings.ProbeInterval	Interval in seconds between subsequential keep-alive probes. Negative value means infinite.	1 second
KeepAliveSettings.ProbeCount	Maximum number of keep-alive probes to send. Zero means keep-alive is disabled.	2

Each side of the connection employs its own keep-alive mechanism and therefore has independent, keep-alive settings. When configuring the keep-alive settings, they can be applied for either side or both sides of the connection. This can be selected using the Endpoint enumeration specified in the following table:

Endpoint	Description
Endpoint.Client	Client side of the connection.
Endpoint.Controller	Controller side of the connection.
Endpoint.Both	Both sides of the connection.

Configurability of the keep-alive settings varies per operating system. Not all settings may be configurable, some settings may be limited to a specific granularity, and/or specific lower and upper bounds may apply. Consult operating system specific documentation for details, e.g. Microsoft Windows and Linux. The limitations for keep-alive settings of hardware controllers are specified in the following table:

Setting	Granularity	Lower bound	Upper bound
KeepAliveSettings.IdleTimeout	1 second	1 second	32767 seconds
KeepAliveSettings.ProbeInterval	1 second	1 second	32767 seconds
KeepAliveSettings.ProbeCount	1	1	127

When changing the keep-alive settings using SetKeepAliveSettings, values are rounded to the resolution supported by the operating system. Use GetKeepAliveSettings to verify the actual applied values.

Incompatible controllers¶

When the controller is incompatible with the used motion API (checked using the IsCompatible property on the Controller interface), most API calls will throw an IncompatibleException. The following calls are excluded from this rule and will work regardless of whether the controller is compatible or not.

IController.Address
IController.HardwareInterfaceProductNumber
IController.HardwareProductNumber
IController.HardwareSerialNumber
IController.Id
IController.IsBackupRunning
IController.IsCompatible
IController.IsConnected
IController.IsSimulated
IController.IsRebootRequired
IController.Updatables
INamed.Name of the top-controller
INamed.FullName of the top-controller
IController.Reboot() of the top-controller
Every IUpdatable call

C++

IController::GetAddress()
IController::GetHardwareInterfaceProductNumber()
IController::GetHardwareProductNumber()
IController::GetHardwareSerialNumber()
IController::GetId()
IController::IsBackupRunning()
IController::IsCompatible()
IController::IsConnected()
IController::IsSimulated()
IController::IsRebootRequired()
IController::GetUpdatable()
IController::GetUpdatableNames()
IController::GetUpdatables()
INamed::GetName() of the top-controller
INamed::SetName() of the top-controller
INamed::GetFullName() of the top-controller
IController::Reboot() of the top-controller
Every IUpdatable call

Furthermore, when a connection callback is subscribed using SubscribeConnection, the subscribed functions will be called appropriately regardless of whether the controller is compatible or not.

System time¶

The system time of the top-controller can be configured using the Time property on the TopController interface. The configured system time is, for example, used for the date and time in the Log buffer.

State machine¶

A top-controller is governed by the state-machine shown in Top controller state machine.

Top controller state machine¶

The states are described in the following table:

Name	Description
Stable states
Config	No real-time task running and only asynchronous communication possible. All configurations possible.
Run	Real-time task running and periodic and asynchronous communication possible. Most configurations are not possible.
Transitional states
Init	Connected slaves are being discovered/enumerated and sub-controllers are created for them.
ConfigToRun	Real-time tasks and periodic communication are configured before running the realtime task.
RunToConfig	Event and signal match queues are cleared. Pending callbacks for events, event responses, and signal matches are hence discarded. Queued commands are aborted.