ADS Server Interface

The HMI Server's ADS Server

When the HMI server is started as a service, the service manager opens an ADS server on port 19800. This ADS server can be used to discover and get the state of HMI server instances that are managed by the service manager.

Index groups and index offsets

	Read-Write requests The "RW" value in the "Access" column indicates that only Read-Write requests are supported for this index group index offset combination. All index offsets of the `INDEXGROUP_SERVERSTATES` index group expect the name of the managed server instance as a write-value. It is analogous to a function parameter.

The following table contains all supported index groups:

Index Group	Name	Description	Remarks
0x00000001	INDEXGROUP_SERVERSTATES	Contains index offsets for the state of the managed server instances.
0x00000002	INDEXGROUP_INSTANCES	Contains index offsets that provide access to the names of the managed server instances.

The following table contains all supported index offsets for the INDEXGROUP_SERVERSTATES index group:

Index Group	Index Offset	Access	Data Type	Offset Name	Description
0x00000001	0x00000001	RW	W: STRING R: STRING	INDEXOFFSET_SERVERSTATE_JSON	The full state of a specific managed server instance as a JSON object.
0x0000001	0x00000002	RW	W: STRING R: STRING	INDEXOFFSET_SERVERSTATE_ARCHITECTURE	The name of the architecture that a specific managed server instance is running on.
0x00000001	0x00000003	RW	W: STRING R: BOOL	INDEXOFFSET_SERVERSTATE_CREATOR_MODE	True if the managed server instance is an engineering server (started with "--creator").
0x00000001	0x00000004	RW	W: STRING R: UINT64	INDEXOFFSET_SERVERSTATE_PID	The process ID of a specific managed server instance.
0x00000001	0x00000005	RW	W: STRING R: HMIVERSION	INDEXOFFSET_SERVERSTATE_PRODUCT_VERSION	The product version of a specific managed server instance.
0x00000001	0x00000006	RW	W: STRING R: STRING	INDEXOFFSET_SERVERSTATE_PROJECT_NAME	The configured project name of a specific managed server instance.
0x00000001	0x00000007	RW	W: STRING R: HMIVERSION	INDEXOFFSET_SERVERSTATE_PROJECT_VERSION	The configured project version of a specific managed server instance.
0x00000001	0x00000008	RW	W: STRING R: BOOL	INDEXOFFSET_SERVERSTATE_PUBLISH_IN_PROGRESS	True if a project is being published onto the specified managed server instance.
0x00000001	0x00000009	RW	W: STRING R: BOOL	INDEXOFFSET_SERVERSTATE_SERVICE_MODE	Always true, because all managed server instances are started by the service manager.
0x00000001	0x0000000A	RW	W: STRING R: STRING	INDEXOFFSET_SERVERSTATE_SERVICE_NAME	The unique instance name of a specific managed server instance. This is pretty useless because you need to know it to request it.
0x00000001	0x0000000B	RW	W: STRING R: INT32	INDEXOFFSET_SERVERSTATE_STATE	The running state of a specific managed server instance.
0x00000001	0x0000000C	RW	W: STRING R: HMIVERSION	INDEXOFFSET_SERVERSTATE_VERSION	The version of a specific managed server instance.
0x00000001	0x0000000D	RW	W: STRING R: UINT8[n]	INDEXOFFSET_SERVERSTATE_ENDPOINTS	The number of returned strings as a UINT32, followed by all configured endpoints of a specific managed server instance concatenated, each separated by a 0x00 byte.
0x00000001	0x0000000E	RW	W: STRING R: UINT8[n]	INDEXOFFSET_SERVERSTATE_FORCEAUTHENDPOINTS	The forced authentication endpoints of a specific managed server instance.
0x00000001	0x0000000F	RW	W: STRING R: STRING	INDEXOFFSET_SERVERSTATE_SERVERTIME	The current ISO-8601 timestamp of a specific managed server instance.
0x00000001	0x0000001F	RW	W: STRING R: INT64	INDEXOFFSET_SERVERSTATE_SERVERTIME_NS	The current timestamp of a specific managed server instance in nanoseconds since the Unix epoch.

The following table contains all supported index offsets for the INDEXGROUP_INSTANCES index group:

Index Group	Index Offset	Access	Data Type	Offset Name	Description
0x00000002	0x00000001	R	STRING	INDEXOFFSET_INSTANCE_NAMES_JSON	The names of the managed server instances as a JSON array of strings.
0x00000002	0x00000002	R	UINT8[n]	INDEXOFFSET_INSTANCE_NAMES	The number of returned strings as a UINT32, followed by the names of the managed server instances concatenated, each separated by a 0x00 byte.

The HMIVERSION type

Normally, ADS uses three-part version numbers consisting of a major version, a revision number and a build number. The TwinCAT HMI uses four-part version numbers instead. To solve this problem, the HMIVERSION type was introduced. It is returned by requests to the following index group index offset combinations:

INDEXGROUP_SERVERSTATES:INDEXOFFSET_SERVERSTATE_PRODUCT_VERSION
INDEXGROUP_SERVERSTATES:INDEXOFFSET_SERVERSTATE_VERSION
INDEXGROUP_SERVERSTATES:INDEXOFFSET_SERVERSTATE_PRODUCT_VERSION
INDEXGROUP_SERVERSTATES:INDEXOFFSET_SERVERSTATE_PROJECT_VERSION

Type definition in Structured Text (ST):

TYPE HMIVERSION  :STRUCT    one   : UDINT;
    two   : UDINT;
    three : UDINT;
    four  : UDINT;
END_STRUCTEND_TYPE

Type definition in C:

struct HMIVERSION
{
    uint32_t one;
    uint32_t two;
    uint32_t three;
uint32_t four;
};

xample of the JSON object returned by INDEXGROUP_SERVERSTATES:INDEXOFFSET_SERVERSTATE_JSON

{
   "architecture": "win-x64",
   "creatorMode": false,
   "endpoints": ["http://127.0.0.1:59150"],
   "forceAuthEndpoints": [],
   "pid": 31756,
   "productVersion": "0.0.0.0",
   "projectName": "",
   "projectVersion": "",
   "publishInProgress": false,
   "serviceMode": true,
   "serviceName": "ServerInstanceOne",
"state": 1,
"version": "0.0.0.0"
}

xample of the JSON array returned by INDEXGROUP_INSTANCES:INDEXOFFSET_INSTANCE_NAMES_JSON

["ServerInstanceOne", "ServerInstanceTwo"]