System¶
This chapter describes the System interface. It is responsible for discovering and managing top-controllers in a given network segment.
Initialization (using discovery)¶
The application can find any top-controller connected to a network by constructing a System instance with the appropriate address. The address consists of a host specification optionally followed by a port number. The host specification can be either a hostname (which is resolved to a network address), a network address, or a subnet network address. When the port is not specified, all top-controllers matching the host specification (i.e. regardless of port running on) are discovered. When the port is specified, only the top-controllers that match both the host specification and the port are discovered. During construction, a background discovery process is started: newly discovered top-controllers are automatically connected. For every top-controller found, all callbacks registered using SubscribeConnection are called. The discovery process keeps running during the lifetime of the system. The default interval of the discovery runs is 10 seconds. In case the application needs an immediate refresh, it can trigger a discovery using ISystem.Discover. The discovery mechanism uses a dedicated protocol independent of the normal Motion API functionality.
The discovery service is available in both operational and backup firmware.
The client must allow TCP/IP and UDP based traffic on:
Port 47779 (simulator service).
Port 47780 (discovery service).
Port 47781 and subsequent ports (top-controllers). The subsequent ports are used when multiple top-controllers share the same IP address, e.g. for simulated top-controllers.
The client and all Ethernet-based top-controllers within a system must reside in the same subnet.
Initialization example figure presents a typical sequence setting up the system and how user application may gain access to top-controllers.
Initialization example¶
Expiration¶
When discovery finds a top-controller a connection is automatically established. Top-controllers remember connections to hosts to keep resources (e.g. acquisition or parameter sets) active even when the connection might be lost. For additional information about the lost connection scenario see Lost connections. The top-controller has an expiration timer for each connection: when the expiration time after the connection was lost has passed, the top-controller removes this connection’s resources; they then become available for use again.
The default expiration time is 15 seconds.
Lifetime¶
When the system object goes out of scope, automatic discovery (and reconnection) functionality is discontinued. All ISystem interfaces continue to operate as before.
Version¶
The Prodrive motion platform uses a four-part version numbering system specified as follows:
Major.Minor.Patch.Build
The version numbers of the client library can be obtained using Version and, in the case of Windows binaries, also by inspecting the file properties of the .dll library file. The meaning of each part is described in the following table:
Part |
Description |
|---|---|
Major |
The major release number, when the major release number equals zero, an unreleased version of the platform is used, e.g. a nightly build. |
Minor |
The minor release number. |
Patch |
The patch release number. |
Build |
The Prodrive build number. |
Examples:
Nightly build:
Major: 0
Minor: 0
Patch: 0
Build: d776bc7d
92.1.3 release:
Major: 92
Minor: 1
Patch: 3
Build: 7356607c
Tree changes¶
Subscription is possible for changes in the tree of PMP objects: object property changes, the addition of new objects, and the removal of objects. When a tree of objects is added, only one callback is executed for the root object of the tree. The same holds for a tree that is deleted. The supported properties for which changed notifications are sent to the user are defined in the following table:
Property |
Description |
|---|---|
Property.Name |
The name of an object changed. |
Property.Source |
The source of an input changed. |