GoPxL: REST API Documentation and User Guide

Table of Contents

API Resources User Guide

GoPxL: API Resource Reference

General Resources

/version

Resource Type: N/A

Reports the API version. See Versioning and Compatibility for more information on how this version may change over time.

Item Type Schema Description
apiVersion string
The API version.

Methods

Method Description
read

Reads the version resource

Example: 

read /version

Example Response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/version"
      }
    },
    "apiVersion": "1.0.0"
  },
  "status": 1,
  "type": "response"
}

/system

Resource Type: N/A

Properties

Item Type Schema Description
runState integer readOnly, enum

Running state of the system. Acceptable values are:

0 - Ready,

1 - Running,

2 - Conflict

autostart bool

Autostart allows the sensor to automatically start running and resume operations after specific GoPxL launch events (such as power cycles and system restarts). When enabled, the system will automatically start as soon as the GoPxL instance is launched. This could happen either on PC, when starting a local instance, or when the device hosting the instance is booted. Note: F or autostart to be successful, the system must be in a state that allows it to start, with no issues or blocking problems present.

1.2.x.x Implemented.

autostartTimeout integer minimum

The time (after the GoPxL instance is launched) that autostart will attempt to start the system. After the timeout period has lapsed, the system will no longer attempt to autostart until the next instance launch. Timeout is in minutes, and a value of 0 denotes an infinite timeout (autostart will not timeout).

1.2.x.x Added.

quickEditEnabled bool

Quick edit is a mode where configuration changes can be made without applying the changes immediately to the set of tools in the current system. This means tool configuration changes are not applied to the saved scanned data from the last scan.

This mode is effective in reducing the time to make multiple configuration changes in a system with many tools configured.

Set to true to enable or enter in the Quick Edit mode.

Set to false to exit from the Quick Edit mode. Any configuration changes will now be applied to all configured tools immediately.

1.2.x.x Added.

Methods

Method Description
read

Reads the system properties.

Example: 

read /system
update

Method Trait: (WearsFlash)

Updates system properties.

Example : 

update /system {"autostart" : true }

Notifications

Notification Description
updated

Occurs whenever the system properties change (ie. sensor is started, stopped, etc.).

Include the payload in the notification as of 1.2.x.x

Example: 

{ "eventType" : "updated", "path" : "/system",
  "payload" : {system properties} }

/system/commands/start

Resource Type: (Callable)

Properties

none

Methods

Method Description
call

Starts the sensor system.

Example: 

call /system/commands/start

Example Response: 

{
  "path": "/system/commands/start",
  "payload": null  
  "type": "response"
  "status": 1,
}

A return status of 'Success' (1) implies that /system resource transitions the /system/#runState property to 1 - Running.

A failed /system/commands/start request means that /system/#runstate property may or may not have changed and the final state can not be assumed. Clients should read /system resource to determine the current value of the runstate property.

/system/commands/stop

Resource Type: (Callable)

Properties

none

Methods

Method Description
call

Stops the sensor system.

Example: 

call /system/commands/stop

Example Response: 

{
  "path": "/system/commands/stop",
  "payload": null  
  "type": "response"
  "status": 1,
}

A return status of 'Success' (1) implies that /system resource transitions the /system/#runState property to 0 - Ready.

A failed /system/commands/stop request means that /system/#runstate property may or may not have changed and the final state can not be assumed. Clients should read /system resource to determine the current value of the runstate property.

/system/commands/upgrade

Resource Type: (Callable)

Methods

/system/commands/factoryRestore

Resource Type: (Callable)

Properties

none

Methods

Method Description
call

Method Trait: (WearsFlash) ( NoRestart )

Factory restores the sensor configuration.
The job is set to factory defaults and all jobs within persistent storage are cleared. See the /jobs resource for information about how to read jobs out before performing a factory restore.

Example: 

call /system/commands/factoryRestore

/system/commands/restart

Resource Type: (Callable)

Properties

none

Methods

Method Description
call

Method Trait:( NoRestart )

Resets the sensor.

Example: 

call /system/commands/restart

/system/commands/snapshot

Resource Type : (Callable)

Properties

none

Methods

Method Description
call

Performs a snapshot with the scanner .

NOTE: This operation may take a while to execute because the the scanner and sensor(s) involved must accumulate data for a snapshot to be complete.

Example: 

call /system/commands/snapshot

/system/commands/simulate

Resource Type : (Callable)

Properties

none

Methods

Method Description
call

Performs a simulate with the scanner, which processes the last frame (if available) through the pipe.

Example: 

call /system/commands/simulate

/system/commands/archive

Resource Type : (Callable)

Properties

none

Methods

Method Description
call

Performs a backup operation based on the argument passed. If there is no argument, then get all the files ie Jobs, workspace, global, replay and support.

Payload:

Item Type Description
contents array<string>

[Optional] List of contents to include in the archive.When this property is omitted from the request, then all contents are included.

Acceptable values are:

"allWorkspaces" - Include all workspaces in the archive.

"currentJob" - Include the current job in the archive.

"replay" - Include the replay buffer in the archive.

"global" - Include global configuration in the archive.

"support" - Include support information in the archive.The support option additionally includes logs to aid in troubleshooting.

"liveJob" - Include the live job in the archive.

"allJobs" - Include all jobs in the archive.

The "currentJob" means the loaded job file which is also saved in the storage folder.

The "liveJob" means the latest job configuration in the sensor(may or may not saved in sensor storage folder)

description string [Optional] Provide a description for the archive.

Response:

The response for this transaction contains additional information besides the standard control message response fields .

Item Type Description
data binary The binary archive data


Examples:

To recreate what the GUI does during Maintenance > Backup: 

call /system/commands/archive {"contents" : ["global", "allWorkspaces", "alljobs", "replay", "liveJob"]}

To recreate what the GUI doesduring Support > Download: 

call /system/commands/archive {"contents" : ["global", "allWorkspaces", "alljobs", "replay", "support", "liveJob"]}

To recreate what the GUI doesduring Replay > Download: 

call /system/commands/archive {"contents" : ["liveJob", "replay"]}


 Example Response : 

{
  "status": 1,
  "payload": {
    "data": [ <binary data> ]
  }
}

/system/commands/restore

Resource Type : (Callable)

Methods

Method Description
call

Performs a restore operation based on the argument and the binary data passed. This will work only with both these fields present. Otherwise, it will return an error.

Validation of data is also part of these resources. It means the contents filed are verified with the binary data passed. If any of the content field data is missing then the command will report an error.

If contents are specified which are not in the provided archive, the request will fail.

Note: Support data can not be restored.

Payload:

Item Type Description
contents array<string>

List of contents to restore from the archive. Acceptable values are:

"allWorkspaces" - Restore all workspaces from the archive.

"currentJob" - Restore the current job from the archive.

"replay" - Restore the replay buffer from the archive.

"global" - Restore global configuration from the archive.

"liveJob" - Restore the live job in the archive.

"allJobs" - Include all jobs in the archive.

"convertRec" - Used to convert and load a classic .rec file. (Should be used alone as using with other arguments renders them useless)

data binary The archive to restore from.


Examples:

To recreate what the GUI does during Maintenance > Restore and SupportUpload & Apply: 

call /system/commands/restore {"data":{binary data}, "contents" : ["global", "allWorkspaces", "allJobs", "replay", "liveJob"]}

To recreate what the GUI does during Replay > Upload: 

call /system/commands/restore {"data":{binary data}, "contents" : ["liveJob", "replay"]}

/system/commands/login

Resource Type : (Callable)

1.2.x.x Added.

Methods

Method Description
call

Performs a system authentication operation. Authenticates the administrator with the provided login credentials.

Payload:

Item Type Description
userPassword string The administrator password.


Response:

The response for this transaction contains additional information besides the standard control message response fields .

Item Type Description
passwordMatch integer

The login operation status code with the flowing possible outcomes:

1 = password matched login successful

0 = incorrect password login failed


Example: 

call /system/commands/login {"userPassword": "MyPassword!123"}


 Example Response : 

{
  "path": "/system/commands/login",
  "payload": {
    "passwordMatch": 1
  },
  "status": 1,
  "type": "response"
}

/system/info

Resource Type : N/A

Provides information about the system itself. Properties on this resource are exclusively read only, and generally contain information such as version numbers and releaseType. These properties never change during run time, as a change would imply a change to the system itself (ie an upgrade or reboot/relaunch).

Properties

Item Type Schema Description
version string readOnly

Version of production build.This is based on the contents of AppInfo.xml. If there is no production build orAppInfo.xml file is missing then the default version is 0.0.0.0

firesyncVersion string readOnly

Version of underlying Firesync platform.

backendVersion string readOnly

Version of the Gocator Backend firmware.

releaseType string readOnly

Release type of production build. This is based on the contents of AppInfo.xml. Expected values are:

"Beta" - If the build was built as a beta, or if AppInfo.xml is missing.

"Release" - If the build was built as a release


If there is no production build or AppInfo.xml file is missing then the default release type is "Beta"

appId string readOnly

Application ID.

1.1.x.x Added.

Methods

Method Description
read

This resource provides various additional information about the GoPxL application system and state. All properties in this resource are readonly and therefore only the read method is acceptable.

Example: 

read /system/info

/system/metrics

This section does not describe the metrics that may be specific to standard scan engines, e.g. LMILaserLineProfiler . This information can be found on the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Resource Type: (Streamable)

Contains system metrics. Mapping to Gocator 6.x health indicators are provided where applicable.

Item Internal Type Type Schema Description
Classic IndicatorId Classic Instance Classic Name
upTime k64u integer

Time elapsed since node boot-up or reset (seconds).

This is how long the node has been running.

Note: On PC, it reflects how long the PC has been running.


2017 N/A Node/UpTime
appUpTime k64u integer

Time elapsed since application start.

This is how long the GoPxlService application has been running.














memUsed k64u integer

Amount of memory currently used (bytes).


2003 N/A Memory/TotalUsed
memCapacity k64u integer

Total amount of memory available (bytes).


2004 N/A Memory/TotalCapacity
memAvailable k64u integer
Amount of memory currently available (bytes).












bootCount k64s integer
Number of boot-ups.
2086
Node/BootCount









cpuCores Array array
List of CPU cores available to the sensor.



cpuCores/n Structure object
Single CPU core object.



cpuCores/n/used k64u integer

Individual CPU core utilization (percent).


2052 Cpu core index Node/Cpu<instance>Used
cpuCoresUsedMax k64u integer
Max CPU core utilization (percent).



cpuCoresUsedAvg k64u integer
Average CPU core utilization (percent).












storageVolumes Array array

List of available storage volumes.

There should only ever be two:
1st (index 0) - User
2nd (index 1) - System





storageVolumes/n Structure object

Storage volume object.

Entry 0 is User
Entry 1 is System





storageVolumes/n/used k64s integer

Amount of non-volatile storage used (bytes).


2005

0 - User
1 - System

StorageVolume/User/Used
StorageVolume/System/Used
storageVolumes/n/capacity k64s integer

Amount of non-volatile storage capacity (bytes).


2006 0 - User
1 - System 		StorageVolume/User/Capacity
StorageVolume/System/Capacity
storageVolumes/n/available k64s integer
Amount of non-volatile storage available (bytes).












pipeBacklogSize k64u integer
Number of bytes enqueued for processing.
2041 N/A Pipe/BacklogSize
pipeBacklogCount k64u integer
Number of messages enqueued for processing.
2050 N/A Pipe/BacklogCount









networkIfs Array array
List of available network interfaces.



networkIfs/n Structure object
Network interface object.



networkIfs/n/linkStatus k32s integer

Current Ethernet link status.

(0x0000) - No link, or speed unknown.
(0x0001) - 10 Mb/s, half duplex.
(0x0002) - 10 Mb/s, full duplex.
(0x0004) - 100 Mb/s, half-duplex.
(0x0008) - 100 Mb/s, full-duplex.
(0x0010) - 1000 Mb/s, half-duplex.
(0x0020) - 1000 Mb/s, full-duplex.
(0x8000) - Auto-negotiated.


2034 netInterface NetInterface/<netInterface>/LinkStatus
networkIfs/n/linkCapacity k64u integer

Total available outbound network throughput (bytes/s).


2009 netInterface

NetInterface/<netInterface>/LinkCapacity


networkIfs/n/txRate k64u integer

Network output transmission rate (bytes/s)


2076 netInterface NetInterface/<netInterface>/TxRate
networkIfs/n/rxRate k64u integer

Network output transmission rate (bytes/s)


2077 netInterface NetInterface/<netInterface>/RxRate
networkIfs/n/txBytes k64u integer

Total number of bytes sent on network.


2078 netInterface NetInterface/<netInterface>/TxBytes
networkIfs/n/rxBytes k64u integer

Total number of bytes received on network.


2079 netInterface NetInterface/<netInterface>/RxBytes









processingDrops k64u integer
Total number of scan processing pipe drops
21000 n/a No direct equivalent. Processing Drops in classic was an aggregate of several indicators.









replay/frameCount k64u integer
The number of frames currently recorded.



replay/memoryUsed k64u integer
The amount of memory used by the recorded data (bytes).



replay/memoryCapacity k64u integer
The total amount of memory available for recording (bytes).



replay/frameIndex k64u integer
The frame index of the current playback cursor.



replay/frameTime k64u integer
The frame timestamp at the current playback cursor. 0 if the index is invalid.












platformErrorLogs k64u integer

Number of platform error logs.

1.2.x.x Added.





platformWarnLogs k64u integer

Number of platform warn logs.

1.2.x.x Added.





platformInfoLogs k64u integer

Number of platform info logs.

1.2.x.x Added.





platformLogsSkipped k64u integer

Number of skipped platform logs.

1.2.x.x Added.





appErrorLogs k64u integer

Number of app error logs.

1.2.x.x Added.





appWarnLogs k64u integer

Number of app warn logs.

1.2.x.x Added.





appInfoLogs k64u integer

Number of app info logs.

1.2.x.x Added.





appLogsSkipped k64u integer

Number of user error logs.

1.2.x.x Added.





userErrorLogs k64u integer

Number of user error logs.

1.2.x.x Added.





userWarnLogs k64u integer

Number of user warn logs.

1.2.x.x Added.





userInfoLogs k64u integer

Number of user info logs.

1.2.x.x Added.





userLogsSkipped k64u integer

Number of skipped user logs.

1.2.x.x Added.





unknownLogsSkipped k64u integer

Number of skipped unknown logs.

1.2.x.x Added.





directLogs k64u integer

Number of direct logs.

1.2.x.x Added.





directLogsSkipped k64u integer

Number of skipped direct logs.

1.2.x.x Added.














advanced/hostPorts Array array
List of host ports.



advanced/hostPorts/n Structure object
Single host port object.



advanced/hostPorts/n/port k32u integer
Host port number (usually async server port 3600 by default)



Methods

Method Description
read

Reads the latest system metrics.

Example: 

read /system/metrics

Example response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/system/metrics"
      }
    },
    "advanced": {
      "hostPorts": [
        {
          "notificationCount": 0,
          "port": 3600,
          "queuedMetricsCount": 0,
          "queuedNotificationCount": 0,
          "queuedResponseCount": 0,
          "queuedStreamCount": 0,
          "requestCount": 0,
          "responseDataDropCount": 0,
          "sentMessageCount": 0,
          "streamDataDropCount": 0,
          "streamDataSkipCount": 0,
          "streamQueueSizeExceededCount": 0
        }
      ],
      "maxSafeInteger": 9007199254740991,
      "maxSafeIntegerPlus": 9007199254740992,
      "runCount": 0
    },
    "appUpTime": 6,
    "cpuCores": [
      {
        "used": 0
      },
      {
        "used": 0
      }
    ],
    "cpuCoresUsedAvg": 0,
    "cpuCoresUsedMax": 0,
    "memCapacity": 1053257728,
    "memUsed": 127340960,
    "networkIfs": [
      {
        "linkCapacity": 125000000,
        "linkStatus": 32,
        "rxBytes": 8038,
        "rxRate": 305,
        "txBytes": 43550,
        "txRate": 788
      }
    ],
    "pipeBacklogCount": -9223372036854775808,
    "pipeBacklogSize": -9223372036854775808,
    "processingDrops": 0,
    "processingLatencyLast": 0,
    "processingLatencyMax": 0,
    "storageVolumes": [
      {
        "capacity": 251133952,
        "used": 87003136
      },
      {
        "capacity": 6762496,
        "used": 2347008
      }
    ],
    "upTime": 24
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of system metrics.

Example: 

stream /system/metrics
cancelStream

Cancel continuous stream of system metrics.

Example: 

cancelStream /system/metrics

/system/auth

Resource Type : N/A

Provides information about the system authentication feature.

1.2.x.x Added.

Properties

Item Type Schema Description
username string readOnly

The administrator username. This value is a placeholder for future expansion and currently hard coded to admin. This value cannot be changed.

userPassword string

The admin password to restrict the usage of the UI.

Read always returns an empty string to prevent users from viewing the current password text.

The current password is not required to be able to set a new password in the API.

Passwords can only be reset by performing a Factory Restore (such as through the discovery protocol).

passwordSet bool readOnly

Determines if the password has been set.

authenticationEnabled bool

Determines if the system authentication feature is currently enabled.


Methods

Method Description
update

Method Trait: (WearsFlash)

Updates the properties of thesystem authentication feature.

Item Type Description
userPassword string

Specifies the administrator password.

authenticationEnabled bool

Enable/disable the system authentication feature.

Passwords are retained even if the authentication feature has been disabled.

Example: 

update /system/auth {"userPassword" : "MyPassword!123" , "authenticationEnabled" : true }
read

Reads the admin authentication properties. The return value of the password will always be an empty string.

Example : 

read /system/auth

Example Response: 

{
  "path": "/system/auth",
  "payload": {
    "_links": {
      "self": {
        "href": "/system/auth"
      }
    },
    "authenticationEnabled": false,
    "passwordSet": false,
    "userPassword": "",
    "username": "admin"
  },
  "status": 1,
  "type": "response"
}

/environ

/environ/ipConfig

Resource Type: N/A

Description

Contains information aboutnetwork interface configuration.

Properties

Item Type Schema Description
externallyControlled bool readOnly

False when the interfaces can be configured by GoPxl.
True when the interfaces are controlled by the operating system and not changeable by GoPxL. In those cases the interfaces will be marked as readOnly.

1.2.x.x Added.

interfaces array<interfacesInfo> readOnly An array of network interface objects. Will return readOnly if the interface cannot be updated.
interfaces/n/ object readOnly Network interface object
interfaces/n/ipVersion integer readOnly IP version. Only version IPv4 is supported.
interfaces/n/ipAddress string, format=ipv4 readOnly

IP address.

interfaces/n/subnetMask string, format=ipv4 readOnly subnet mask.
interfaces/n/gatewayAddress string, format=ipv4 readOnly

Gateway IP address.

interfaces/n/dhcp bool readOnly

IP auto configuration setting.

Methods

Method Description
read

Read the ipConfig properties.

Example: 

read /environ/ipConfig

Example Response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/environ/ipConfig"
      }
    },
    "_schema": {
      "properties": {
        "interfaces": {
          "items": [
            {
              "properties": {
                "dhcp": {
                  "type": "boolean"
                },
                "gatewayAddress": {
                  "type": "string"
                },
                "ipAddress": {
                  "type": "string"
                },
                "ipVersion": {
                  "type": "integer"
                },
                "subnetMask": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            {
              "properties": {
                "dhcp": {
                  "type": "boolean"
                },
                "gatewayAddress": {
                  "type": "string"
                },
                "ipAddress": {
                  "type": "string"
                },
                "ipVersion": {
                  "type": "integer"
                },
                "subnetMask": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            {
              "properties": {
                "dhcp": {
                  "type": "boolean"
                },
                "gatewayAddress": {
                  "type": "string"
                },
                "ipAddress": {
                  "type": "string"
                },
                "ipVersion": {
                  "type": "integer"
                },
                "subnetMask": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          ],
          "type": "array"
        },
        "externallyControlled": {
			"readOnly":true,
			"sortOrder":100,
			"title":"externallyControlled",
			"type":"boolean"
	    }
      },
      "type": "object"
    },
    "interfaces": [
      {
        "dhcp": true,
        "gatewayAddress": "0.0.0.0",
        "ipAddress": "192.168.208.78",
        "ipVersion": 4,
        "subnetMask": "255.255.255.255"
      },
      {
        "dhcp": true,
        "gatewayAddress": "0.0.0.0",
        "ipAddress": "10.0.0.178",
        "ipVersion": 4,
        "subnetMask": "255.255.255.0"
      },
      {
        "dhcp": true,
        "gatewayAddress": "0.0.0.0",
        "ipAddress": "127.0.0.1",
        "ipVersion": 4,
        "subnetMask": "255.0.0.0"
      }
    ],
  "externallyControlled": false
  },
  "status": 1,
  "type": "response"
}
update

Change the IP configuration of the system host (eg. Sensor or GoMax)

Example: 

update /environ/ipConfig {"interfaces":[{"dhcp": true, "gatewayAddress": "0.0.0.0", "ipAddress": "90.23.29.25", "ipVersion": 4, "subnetMask": "255.255.0.0"}]}

Note:- Only sensor and GoMax network configurations can be updated.

/environ/info

Resource Type: N/A

Description

Contains information aboutruntime (application) types and controller types so that clients can learn about platform specific abilities of the GoPxL application instance they are connecting to . Only allowable method is "read", however this resource remains readable at all times - including when sensor is remote connected.

1.0.x.x Added.

Properties

Item Type Schema Description
applicationType integer

enum,

readOnly

Enumeration of different application types:
  • 0: Gocator Sensor
  • 1: GoPxl on PC
  • 2: GoMax
  • 3: GoPxL Daemon
partNumber string readOnly

LMI part number for the device on which GoPxL is running.

1.0.x.x Added.

serialNumber string readOnly

Unique serial number of the device on which GoPxL is running.

1.0.x.x Added.

version string readOnly

Version of the device firmware.

1.0.x.x Added.

model string readOnly

Model name of the device on which GoPxL is running.

1.0.x.x Added.

Methods

Method Description
read

Example: 

read /environ/info

Example Response: 

{
  "payload": {
    "applicationType": 0,
    "controllerType": 4,
    "model": "2330",
    "partNumber": "312330C-2M-R-01-T",
    "serialNumber": "45045",
    "version": "1.2.30.45",
    "_schema": {
      "properties": {
      "applicationType": {
      "enum": [
        0,
        1,
        2,
        3
      ],
      "enumText": [
        "GoPxL Firmware",
        "GoPxL Service",
        "GoMax Firmware",
        "GoPxL Daemon"
      ],
      "readOnly": true,
      "sortOrder": 0,
      "title": "applicationType",
      "type": "integer"
    },
    "controllerType": {
      "enum": [],
      "enumText": [],
      "readOnly": true,
      "sortOrder": 100,
      "title": "controllerType",
      "type": "integer"
    },
    "model": {
      "readOnly": true,
      "sortOrder": 300,
      "title": "model",
      "type": "string"
    },
    "partNumber": {
      "readOnly": true,
      "sortOrder": 500,
      "title": "partNumber",
      "type": "string"
    },
    "serialNumber": {
      "readOnly": true,
      "sortOrder": 200,
      "title": "serialNumber",
      "type": "string"
    },
    "version": {
      "readOnly": true,
      "sortOrder": 400,
      "title": "version",
      "type": "string"
    }
  },
  "sortOrder": 0,
  "title": "",
  "type": "object"
  },
  "_links": {
    "self": {
      "href": "/environ/info"
      }
    }
  },
  "path": "/environ/info",
  "type": "response",
  "status": 1
}

/environ/remoteController

Resource Type: N/A

Description

Contains information about remote connection status as well as remote controller information including IP address, control port, and web port of the remote controller.

1.0.x.x Resource Added

Properties

Item Type Schema Description
remoteConnected boolean

readOnly

Boolean of whether sensor is remote connected or not.

ipAddress string

readOnly, format=ipv4

IP Address of remote controller. Only IP v4 is supported.

controlPort integer readOnly

Control Port of remote controller.

webPort integer readOnly

Web Port of remote controller.

appId string readOnly

Application ID.

1.1.x.x Added.

Methods

Method Description
read

Example: 

read /environ/remoteController


Example response: 

{
  "payload": {
    "appId": "",
    "controlPort": 0,
    "ipAddress": "",
    "remoteConnected": false,
    "webPort": 0,
    "_schema": {
      "properties": {
        "appId": {
          "readOnly": true,
          "sortOrder": 0,
          "title": "appId",
          "type": "string"
        },
        "controlPort": {
          "readOnly": true,
          "sortOrder": 300,
          "title": "controlPort",
          "type": "integer"
        },
        "ipAddress": {
          "format": "ipv4",
          "readOnly": true,
          "sortOrder": 200,
          "title": "ipAddress",
          "type": "string"
        },
        "remoteConnected": {
          "readOnly": true,
          "sortOrder": 100,
          "title": "remoteConnected",
          "type": "boolean"
        },
        "webPort": {
          "readOnly": true,
          "sortOrder": 400,
          "title": "webPort",
          "type": "integer"
        }
      },
      "sortOrder": 0,
      "title": "",
      "type": "object"
    },
    "_links": {
      "self": {
        "href": "/environ/remoteController"
      }
    }
  },
  "path": "/environ/remoteController",
  "type": "response",
  "status": 1
}


/scan

For scan resources, see Scanner Resources .

/replay

Resource Type: N/A

Contains replay settings and state.

Item Type Schema Description
frameCount integer readOnly, minimum The number of frames currently recorded.
memoryUsed integer readOnly, minimum The amount of memory used by the recorded data (bytes).
memoryCapacity integer readOnly, minimum The total amount of memory available for recording (bytes).
frameIndex integer readOnly, minimum The frame index of the current playback cursor.
frameTime integer readOnly, minimum

The frame timestamp at the current playback cursor. 0 if the index is invalid.

Units are in Firesync miscroseconds

Methods

Method Description
read

Reads the replay properties.


Notifications

Notification
updated

Occurs whenever the properties change, e.g. when the frame count or frame index changes. The server may throttle the update rate to avoid notification spam.
This is limited to a 10Hz rate

Includes the payload in the notification as of 1.2.x.x

/replay/buffer

Resource Type: N/A

Contains the properties of the buffer data.

Item Type Schema Description
displayName culture-specific string
User configurable display name of the replay buffer.

Methods

Method Description
read Reads the current replay buffer properties
update Updates the replay buffer properties

/replay/buffer/data

Resource Type: N/A

A binary resource that can be used to download and upload replay buffer data.

Item Type Schema Description
data binary
The replay buffer in binary form

Methods

Method Description
read Reads the current replay buffer to be downloaded
update Updates the replay buffer with a replay buffer provided by the client

/replay/tracks

Resource Type: (Collection - Unordered)

Description

A collection of replay tracks.
Each "track" typically represents a stream of synchronized data, captured from a single source (e.g. scanner).

Methods

Method Description
read

Read all tracks from the replay module.

Example: 

read /replay/tracks

Example Response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/1"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/replay/tracks"
      }
    }
  },
  "status": 1,
  "type": "response"

Notifications

None.

/replay/tracks/(trackId)

Resource Type: (CollectionItem)

ID: Auto generated.

Description

A track object.

Properties

Item

Type

Schema

Description

id string readOnly The ID within the collection (e.g. "0").
displayName culture-specific string readOnly Display name of the track.
scannerId string readOnly The scanner ID configured in scan engine.

Methods

Method

Description

read

Reads the resource.

Returns the properties of track.

Example: 

read  /replay/tracks/0


Example Response: 

{
  "payload": {
    "_embedded": {
      "channels": [
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/0/channels/0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/0/channels/1"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/replay/tracks/0"
      }
    },
    "displayName": "New Scanner 1",
    "scannerId": "0"
  },
  "status": 1,
  "type": "response"
}

Notifications

None.

/replay/tracks/(trackId)/channels

Resource Type: (Collection - Unordered)

A collection of replay channels. Channels usually represent the scanners and tool outputs, all associated to the same track.

Methods

Method Description
read

Read all channels from the corresponding track.

Example: 

read  /replay/tracks/0/channels


Example Response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/0/channels/0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/replay/tracks/0/channels/1"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/replay/tracks/0/channels"
      }
    }
  },
  "status": 1,
  "type": "response"
}

Notifications

None.

/replay/tracks/(trackId)/channels/(channelId)

Resource Type: (CollectionItem)

ID: Auto generated.

A channel object.

Properties

Item

Type

Schema

Description

id string readOnly The ID within the collection (e.g. "0").
dataSourceId string readOnly Pipe Id of added datasource.
displayName culture-specific string readOnly Display name of the added datasource.
priority integer readOnly

Priority of the recorded output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

Methods

Method

Description

read

Reads the resource.

Returns the properties of channel added to track.

Example: 

read  /replay/tracks/0/channels/0


Example Response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/replay/tracks/0/channels/1"
      }
    },
    "dataSourceId": "scan:test:0:Stamp",
    "displayName": "New Scanner 1: Stamp Output"
  },
  "status": 1,
  "type": "response"
}

Notifications

None.

/replay/playback

Resource Type: N/A

Contains playback settings.

Item Type Schema Description
enabled bool
Enables playback. When this is set to true, the system immediately disables scanner outputs and enables outputs from the replay system. When set to false, the outputs are reverted.
loopEnabled bool
Enables automatic looping of the data.
mode integer enum

Playback mode:

  • 0: continuous playback at the fastest speed.
  • 1: playback at the recorded speed.
  • 2: playback at a fixed speed (see frameRate).
  • 3: manual stepping only.
speedFactor number
A multiplier to the actual frame rate when using mode is 1. e.g. at 1.0, the playback is at the original speed, while with 10.0, the playback occurs 10 times faster, and 0.1, 10 times slower.
frameRate number
The fixed frame rate to use when mode is 2;

Methods

Method Description
read

Reads the playback settings.

update Updates the playback settings.

Notifications

Notification
updated

Occurs whenever the properties change.

/replay/recording

Resource Type: N/A

Contains recording settings.

Item Type Schema Description
enabled bool

Enables recording. When recording is enabled, live data is recorded into the buffer.

If playback is also enabled, recording is implicitly disabled.

Methods

Method Description
read

Reads the recording settings.

update Updates the recording settings.

Notifications

Notification
updated

Occurs whenever the properties change.

/replay/commands/seek

Resource Type: (Callable)

Seeks to a specified position in the buffer. The data at the position is emitted from the replay engine and makes its way into any receiving tools or output/control services.

Parameters:

Item Type Schema Description
positionDomain integer enum

The "domain" of the position parameter:

  • 0: frame index
  • 1: timestamp
position integer
The position to seek to. The meaning depends on positionDomain.

Methods

Method Description
call

Invokes the command.

/replay/commands/playTo

Resource Type: (Callable)

Starts playback and automatically stops at the specified position.

Parameters:

Item Type Schema Description
positionDomain integer enum

The "domain" of the position parameter:

  • 0: frame index
  • 1: timestamp
position integer
The position to play to. The meaning depends on positionDomain.

Methods

Method Description
call

Invokes the command.

/replay/commands/clear

Resource Type: (Callable)

Clears the replay buffer.

Methods

Method Description
call

Invokes the command.

/tools

For tool resources, see Tool Resources .

/dataSources

Resource Type: (Collection - Unordered)

ID : auto-generated

A collection of data sources, which may come from tools, scan engines or the replay engine.

Methods

Method Description
read

Returns the array of data sources.

Example: 

read /dataSources

Notifications

Notification Description
embeddedUpdated


Occurs whenever the dataSource collection changes due to additions, deletions, or moves/reorders during a job load.

Example: 

{ "eventType" : "embeddedUpdated", "path" : "/dataSources"

1.0.x.x Added

/dataSources/(id)

ID: auto generated when a data source is added (can be from an tool or scanner output or any other type of pipe output that might be added later).

All items have the following schema:

Item Type Schema Description
id string readOnly

An ID of the corresponding data source. Examples:

  • tools:0:outputs:10 (tool output)
  • scanners:0 (scanner)
  • scanners:0:sensors:3 (a specific sensor)

These (as with any ID) should be treated as opaque strings. For convenience, they are picked by the system to reflect their underlying scanner or tool output, but this should not be relied upon by clients. It is possible that the format of these ID's may change in later versions of the application. A client should never parse this (or any) ID.

dataFormat DataFormat readOnly

The data format of the output. See Common Types .
This is readonly as it reflects the capabilities of the underlying tool implementation.

displayName culture-specific string

The display name of the data source. It is the result of the concatenated display names of the scanner or tool, and its output. Examples:

  • Gocator 0/Top Profile
  • TestForward-0 tool/Output

Note all the above fields are read-only in the sense that clients can not change them by updating them on the dataSource resource directly. However, this does not mean they never change. For example, the display name may change if the underlying tool or scanner output's display name changes.

Methods

Method Description
read

Read a specific dataSource.

Example: 

read /dataSources/gocator:scanner-0:top:profile
read /dataSources/tools:TestForward-0:otuputs:Output0

Notifications

Event Type Description
created

Occurs whenever a datasource output (eg. from scanners or tools ) is added. The path indicates the new data source output id.
NOTE: Although there is no command to explicitly add/delete data sources, this may happen internally in the sensor system as tools are added/deleted or properties are changed, triggering this event notification.

Example: 

{ "eventType" : "created", "path" : "/dataSources/tools:TestForward-0:outputs:Output0",
  "payload" : {new display source output properties} }
updated

Occurs whenever a datasource output (eg. from scanners or tools ) is updated. The path indicates the data source output id that was deleted.

Example: 

{ "eventType" : "updated", "path" : "path" : "/dataSources/tools:TestForward-0:outputs:Output0",
  "payload" : {display source output properties} }
deleted

Occurs whenever a datasource (eg. scanner or tool output) is deleted or gets disabled.. The path indicates the data source output id that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "path" : "/dataSources/tools:TestForward-0:outputs:Output0" }

/dataSources/(id)/data

Resource Type: Non Standard , Streamable

Access the data for the dataSource. This resource can only be streamed - there is no support to read the resource directly.

Properties on this resource follow those documented for all Streamable resources here

Below, data is documented to specify that the "data" property is specifically a binary type.


Methods

Method Description
stream

Streams data from a specific dataSource.

Arguments:

Item Type Description
period integer

Period at which the data will be streamed at in milliseconds (ms)

Defaults to 250000ms or 4Hz.

streamLastFrame bool

Determines if the last (ie most recent) frame should be streamed upon establishing a new stream connection. If there is no last frame present, a signal message will be emitted.

Defaults to false.

Example: 

stream /dataSources/gocator:scanner-0:top:profile/data
stream /dataSources/tools:TestForward-0:otuputs:Output0/data {"period": 250000}
stream /dataSources/tools:TestForward-0:otuputs:Output0/data {"streamLastFrame":true}

/controls

For control resources, see Control Resources .

/routines

For routine resources, see Routine Resources .

/jobs

Resource Type: N/A

Represents some high-level job properties.

Item Type Schema Description
defaultJob string readOnly Job ID (name) of the default job.
loadedJob string readOnly Job ID (name) of the currently loaded job.
loadedJobDirty bool readOnly

Boolean value indicating whether the currently loaded job contains unsaved data.

Methods

Method Description
read

Read high-level job information from the system.

Examples:

Read the high-level job information, and expands any embedded information such as /jobs/files resource within it. 

read /jobs { "expandLevel" : -1 }

Notifications

Event Type Description
updated

Occurs whenever high-level job information changes, such as the default job, loaded job, and if the loaded job becomes dirty. The path indicates the /jobs resource.

Example Notification: 

{ "eventType" : "updated", "path" : "/jobs"}

/jobs/commands/load

Resource Type: (Callable)

Methods

Method Description
call

Loads the specified job. This becomes the loaded job, and is marked as clean to begin with.

Arguments:

Item Type Description
fromFactory bool [Optional] Set to true to initiate a job from factory defaults.

It DOES NOT clear scanners and sensor instances added underneath /scan resource. It only resets each of the existing scanner and sensor instance's parameters back to factory default values.

name string [Optional] Name of the job to load.

Example:

To initiate a job from factory defaults: 

call /jobs/commands/load { "fromFactory" : true }


To load a specific job: 

call /jobs/commands/load { "name" : "someJob" }

/jobs/commands/save

Resource Type: (Callable)

Methods

Method Description
call

Method Trait: (WearsFlash)

Saves the current job to the specified job name. If the job already exists it is overwritten.
Saving a job also updates the job to be loaded, and clears the job from being dirty.

Arguments:

Item Type Description
name string Name of the job to save. 144 characters max.

Example: 

call /jobs/commands/save { "name" : "newJob" }

/jobs/commands/copy

Resource Type: (Callable)


Methods

Method Description
call

Method Trait: (WearsFlash)

Copies a job file under a new name. If the target name already exists, it is overwritten.

Arguments:

Item Type Description
sourceName string Name of the job to rename.
destName string Name of the job to rename to. 144 characters max.

Example: 

call /jobs/commands/copy { "sourceName" : "job1", 
                           "destName" : "newJob1" }

A subsequent read upon /jobs/files will contain both /jobs/files/job1 and /jobs/files/newJob1 resources.

/jobs/commands/rename

Resource Type: (Callable)

Methods

Method Description
call

Method Trait: (WearsFlash)

Renames a job file to another name. If the target name already exists, it is overwritten.
If the job being renamed is either the loaded job or the default job, they are updated accordingly.

Arguments:

Item Type Description
sourceName string Name of the job to rename.
destName string Name of the job to rename to.144 characters max.

Example: 

call /jobs/commands/rename { "sourceName" : "job1",
                              "destName" : "renamedJob1" }

A subsequent read call on /jobs/files will no longer contain /jobs/files/job1 and will instead contain /jobs/files/renamedJob1 resource.

/jobs/commands/setDefault

Resource Type: (Callable)

Methods

Method Description
call

Sets a job as the default job, which is loaded during application start.

Arguments:

Item Type Description
name string Name of the job to load from.

Example: 

call /jobs/commands/setDefault { "name" : "defaultJob" }

/jobs/files

Resource Type: (Collection - Unordered)

A collection of jobs within the system. Note that job names omit the ".gpjob" extension.

Methods

Method Description
read Reads a list of job files.
create

Method Trait: (WearsFlash)

Create a new job file, from uploaded content.

Arguments:

Item Type Description
content binary Specify the raw binary content of the new job.
name string Name of the new job file.

Examples: 

create /jobs/files { "name": "newJob", "content" : **binary content** }

Notifications

Event Type Description
updated

Occurs whenever the jobs collection changes. Unary additions and deletions do not trigger this event.
This does occur however, if all jobs are cleared at once.

Example Notification: 

{ "eventType" : "updated", "path" : "/jobs/files" }

/jobs/files/(jobName)

Resource Type: (CollectionItem)

ID : User-defined name

Represents the collection of job files. The parent resource can be queried to obtain a list of job files and their information.

Information about the job file specified by the ID, which is just the job name. This resource does not contain the contents of the job file (see next section).

Schema:

Item Type Schema Description
jobName string readOnly Job name.
size integer readOnly Size of the job file, in bytes.

Methods

Method Description
read Reads a specific job's properties.
delete

Method Trait: (WearsFlash)

Deletes a job files from the system. The path to the job name must be provided.

If the job being deleted is the currently loaded job, then the loaded job is cleared and the job is set to dirty.

Example:

Delete a single job file: 

delete /jobs/files/myJob

A special wildcard form applies to this delete method.

The path of this jobs command can be wildcarded to delete all job files. 

delete /jobs/files/*

Notifications

Event Type Description
created

Occurs whenever a job is created. The path indicates the new job id.

Example: 

{ "eventType" : "created", "path" : "/jobs/files/newJob"}
updated

Occurs whenever a job is updated (ie. re-saved or overwritten with new content). The path indicates the job name that was updated.

Example Notification: 

{ "eventType" : "updated", "path" : "/jobs/files/updatedJob"}
deleted

Occurs whenever a job file is deleted. The path indicates the job name that was deleted.

Example Notification: 

{ "eventType" : "deleted", "path" : "/jobs/files/deletedJob"}

/ jobs/files/(jobName)/data

Resource Type: (CollectionItem)

Represents the actual binary contents of the job file as a binary string, which can be read and updated.

Item Type Description
content binary Contains the job data as raw binary.

Methods

Method Description
read

Reads a specific job's binary data.

update

Method Trait: (WearsFlash)

Updates a specific job's binary data.

If the job being updated is the currently loaded job, then the loaded job is cleared and the job is set to dirty, to reflect that the current job no longer matches.

Item Type Description
content Binary

Specifies the updated binary content of the job.

Examples: 

update /jobs/files/myJob/Data { "content" : **binary content** }

Notifications

Although this resource does not raise any event notifications of its own, changes to the binary data will raise event notifications on its parent see /jobs/files/(jobName) -- Notifications .

/problems

Resource Type: N/A

Contains a list of currently active problems that are updated on start/simulate of the sensor. Note that this isnot a collection resource ; it is a standard resource that contains an array.
Problems are defined as anything that prevents the sensor from running that the user is able to fix via configuration.

Each problem object follows the schema below:

Item Type Schema Description
msg string
A message string describing the problem.
severity integer

The severity of the problem that can be one of :

  • 0 - potential
  • 1 - blocking
source string

source of the problem. e.g. Pipe, Scanner, etc...

Methods

Method Description
read

Reads the current list of problems.

Example: 

read /problems

Example response: 

{
  "payload": {
	"items": [
	  {
		"msg": "This is a problem.",
		"severity": 0,
		"source": "Pipe"
	  }
	],
	"_links": {
	  "self": {
		"href": "/problems"
	  }
	}
  },
  "path": "/problems",
  "type": "response",
  "status": 1
}

Notifications

Event Type Description
updated

Occurs whenever the problems collection changes due to additions or deletions (or if all problems are resolved).

Example: 

{ "eventType" : "updated", "path" : "/problems" }

/logs

Resource Type: N/A

ID : Auto-generated

A list of public logs. Note that this isnot a collection resource ; it is a resource that contains an array.

See /logs/summary for the first log id ("idStart" - see /logs/summary) and last log id ("idEnd" - see /logs/summary) which should be used to read logs.

Each log message has has common scheme elements listed below:

Item Type Description
id integer ID of the log message. Unique.
level integer

Log level (warn, info, etc.)

  • 0 - Info
  • 1 - Warning
  • 2 - Error
timestamp integer Timestamp of the message. This is the time elapsed since uptime in microseconds.
text string Locale specific log message. This message will be translated based on the system language.


Methods

Method Description
read

Reads the /logs collection.

Payload:

Field Type Description
startId integer ID of the first log to return in logs array. Default: idStart (first log id - see /logs/summary)
endId integer ID of the last log to return in logs array. Default: idEnd (last log id - see /logs/summary)

If either of these are out of the range[ idStart , idEnd], kERROR_PARAMETER is thrown. If startId > endId, logs is empty.

Examples: 

read /logs
read /logs {"startId": 1, "endId": 3}

Example response: 

{
  "payload": {
	"logs": [
	  {
		"id": 1,
		"level": 0,
		"text": "This is a log.",
		"timestamp": 6222610417
	  },
	  {
		"id": 2,
		"level": 0,
		"text": "This is a log.",
		"timestamp": 6222610754
	  }
	],
	"_links": {
	  "self": {
		"href": "/logs"
	  }
	}
  },
  "path": "/logs",
  "type": "response",
  "status": 1
}

/logs/commands/clear

Resource Type: (Callable)

Methods

Method Description
call

Deletes all public logs. Afterwards, log ids are not reused.
The new idStart will begin at the "old idEnd + 1".

Example: 

call /logs/commands/clear

/logs/summary

Resource Type: N/A

Attribute Type Description

idStart

integer ID of the first available log

idEnd

integer ID of the last available log

Methods

Method Description
read

Reads the /logs/summary information.

Examples: 

read /logs/summary

Example response: 

{
  "payload": {
	"idEnd": 2,
	"idStart": 1,
	"_links": {
	  "self": {
		"href": "/logs/summary"
	  }
	}
  },
  "path": "/logs/summary",
  "type": "response",
  "status": 1
}

Notifications

Event Type Description
updated

Occurs whenever the log collection changes due to additions or deletions.

Example: 

{ "eventType" : "updated", "path" : "/logs/summary" }

GoPxL: Scanner Resources

This section describes the general protocol definition of the /scan resource, applying to all scan engines. This information can be used toimplement a generic client that works with any scanners, Gocator or 3rd party.

This section does not describe the specifics of the standard scan engines, e.g. LMILaserLineProfiler.

/scan/visibleSensors

Resource Type: N/A

Description

Contains information about sensors discovered across all scan engines. All properties on this resource are read-only.

Properties

Item Type Schema Description
sensors array readOnly Collection of visible sensor objects
sensors/n object readOnly Visible sensor object
sensors/n/connectionMessage culture-specific string readOnly

Describes some details about the error if the connection state is an error.

Can be empty. The scan engine is not obligated to provide this.

sensors/n/connectionStatus integer readonly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is in use (ie already connected to another application).
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
sensors/n/engineId string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMILaserLineProfiler".
sensors/n/isLocal bool readOnly True if the sensor is local to the application (e.g. running on the sensor). False if the sensor is remote.
sensors/n/model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
sensors/n/parameters object readOnly Additional parameters depending on the scan engine.
sensors/n/serialNumber string readOnly

A string that uniquely identifies the sensor for the given engineId. Serial numbers typically originate from within the sensor device itself, and are determined by the device manufacturers. Therefore, it is possible that serialNumbers might be shared across different engineId's, although in practice this is uncommon.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, the numeric serial number of the device is represented as a string.
sensors/n/version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

Methods

Method Description
read

Reads the list of visible sensors, across all scan engines.

Example response: 

{  
  "sensors": [
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMILaserLineProfiler",
      "isLocal": false,
      "model": "2330",
      "parameters": {
        "ipAddress": "90.23.50.45",
        "optionCode": 1
      },
      "serialNumber": "45045",
      "version": "1.0.0.0"
    },
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMIConfocalLineProfiler",
      "isLocal": false,
      "model": "5512",
      "parameters": {
        "ipAddress": "90.55.52.68",
        "optionCode": 1
      },
      "serialNumber": "55268",
      "version": "1.0.0.0"
    },
  ]
}

Notifications

Notification
updated

Occurs when the visible sensors for any scan engine changes. The path indicates the overall visible sensors list.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/visibleSensors" }


/scan/engines

Resource Type: (Collection - Unordered)

Description

A collection of scan engines.
NOTE: The list of scan engines is determined by the available scan engines loaded in the system.
Engines cannot be created or deleted directly via the protocol.

Methods

Method Description
read

Reads all scan engines, the list of scan engines are returned as embedded items.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIFringeSnapshot"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIConfocalLineProfiler"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/test"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines"
    }
  }
}

Notifications

None (as engines cannot be created or deleted directly via the protocol).

/scan/engines/(engineId)

Resource Type: (CollectionItem)

Description

A scan engine object.

Properties

Item Type Schema Description
displayName culture-specific string readOnly

Display name of the engine, e.g. "Gocator Laser Profiler".

id string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMILaserLineProfiler".
maxSensorCount integer

readOnly, minimum, used

Max sensor count.

1.0.x.x Added.

Methods

Method Description
read

Reads a specific scan engine.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler"
    }
  },
  "displayName": "Gocator Laser Profiler",
  "id": "LMILaserLineProfiler",
  "maxSensorCount" : 31
}

Notifications

None (as engines cannot be created or deleted directly via the protocol).

/scan/engines/(engineId)/visibleSensors

Resource Type: N/A

Description

Contains information about sensors discovered by a specific scan engine. All properties on this resource are read-only.

The format of this resource is identical to the format of /scan/visibleSensors except that it filters for only those sensors which are applicable to this scanEngine.

Properties

Item Type Schema Description
connectionMessage string readOnly

Describes some details about the error if the connection state is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus integer readonly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
engineId string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMILaserLineProfiler".
isLocal bool readOnly True if the sensor is local to the application (e.g. running on the sensor). False if the sensor is remote.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
parameters object readOnly Additional parameters depending on the scan engine.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.
version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

Methods

Method Description
read

Reads the list of visible sensors, for a specific scan engine.

Example response: 

{  
  "sensors": [
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMILaserLineProfiler",
      "isLocal": false,
      "model": "2330",
      "parameters": {
        "ipAddress": "90.23.50.45",
        "optionCode": 1
      },
      "serialNumber": "45045",
      "version": "1.0.0.0"
    },
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMILaserLineProfiler",
      "isLocal": false,
      "model": "2340",
      "parameters": {
        "ipAddress": "90.23.50.46",
        "optionCode": 1
      },
      "serialNumber": "45046",
      "version": "1.0.0.0"
    },
  ]
}

Notifications

Notification
updated

Occurs when the visible sensors for a specific scan engine changes. The path indicates the specific scan engine's visible sensors list.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/visibleSensors" }

/scan/engines/(engineId)/scanners

Resource Type: (Collection - Unordered)

Description

A collection of scanners under the engine.

Properties

Item Type Schema Description
creationParams object readOnly Custom scanner creation parameters, specific to the scan engine.

Methods

Method Description
read

Reads all scanners under the engine; the list of scanners are returned as embedded items.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners"
    }
  },
  "creationParams": {
    "defaultSerialNumber": 0
  }
}
create

Creates a scanner resource.
NOTE: A client should read the scanners resource to see if there are creationParams that can be supplied in the create method.

Example request: 

create /scan/engines/LMILaserLineProfiler/scanners {"defaultSerialNumber": 12345}

Notifications

Event Type Description
created

Occurs when a new scanner is added. The path indicates the new scanner id.

Example notification: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"}
updated

Occurs when a scanner's properties change. The path indicates the affected scanner id.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0" }
deleted

Occurs when a scanner is deleted. The path indicates the scanner id that was deleted.

Example notification: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0" }

/scan/engines/(engineId)/scanners/(scannerId)

Resource Type: (CollectionItem)

ID: Auto generated when scanners are added.

Description

A scanner object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the scanner.
id string readOnly The identifer of the scanner within the collection (e.g. "scanner-0").
parameters object
Scanner parameters that vary depending on the scan engine.
engineId string readOnly

The identifier of the scanner's engine

1.1.x.x Added.

parameterValidationMode enum visibility

Experimental flag used for determining parameter validation severity to prevent getting stuck on blocking problems for default parameters

  • 0 - None
  • 1 - Potential
  • 2 - Blocking

Methods

Method Description
read

Reads the scanner resource.
Returns child resources as embedded items.
Returns actions as links.

Example response: 

{
  "_embedded": {
    "go:content": [  // see /scan/engines/(engineId)/scanners/(scannerId)/(contentId)
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/alignment"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout"
          }
        }
      }
    ],
    "go:output": [  // see /scan/engines/(engineId)/scanners/(scannerId)/outputs
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/sensor-0:profile"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/stamp"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/top:profile"
          }
        }
      }
    ],
    "go:sensor": [  // see /scan/engines/(engineId)/scanners/(scannerId)/sensors
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-1"
          }
        }
      }
    ]
  },
  "_links": {
    "go:action": [  // see /scan/engines/(engineId)/scanners/(scannerId)/actions
      {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/actions/autoLayout"
      },
      {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/actions/trigger"
      }
    ],
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"
    }
  },
  "displayName": "Gocator 0",
  "id": "scanner-0",
  "parameters": {
    // scan-engine-specific scanner parameters
  }
}
update

Updates the scanner resource.

Arguments:

Item Type Description
parameters object Scanner parameters to update.

Example request: 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0 { "parameters" : { "uniformSpacingEnabled" : true } }
delete

Deletes the scanner resource.

Example request: 

delete /scan/engines/LMILaserLineProfiler/scanners/scanner-0

Notifications

Notification
created

Occurs when a scanner is created. The path indicates the affected scanner.

Example notification: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"}
updated

Occurs when a scanner's properties change. The path indicates the affected scanner.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"}
deleted

Occurs when a scanner resource has been deleted. The path indicates the affected scanner.

Example notification: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"}

/scan/engines/(engineId)/scanners/(scannerId)/alignment

Resource Type: (Collection - Unordered)

Description

The resource pertaining to alignment state & configuration.

Properties

Item Type Schema Description
alignState enum readOnly Alignment state of the scanner. 0 = Not Aligned, 1 = Aligned, 2 = Aligning.
alignConfig object
Alignment configuration. Configurations will vary between scanner types. See scanner-specific documentation for details.

Methods

Method Description
read

Returns the alignment state & config.

Example response: 

{
  "payload": {
    "alignState": 0,
    "alignConfig": {
      "timeout": 120
    }
  },
  "status": 1,
  "type": "response"
}
update

Update the alignment configuration. The state is read-only and cannot be updated. 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/alignment { "alignConfig" : { "timeout" : 90 } }

Notifications

Notification
updated

Occurs when the alignment configuration is updated or the alignment state changes. 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/alignment"}

/scan/engines/(engineId)/scanners/(scannerId)/transform

Resource Type: (Collection - Unordered)

Description

The resource pertaining to alignment transforms.

The contents of this resource are entirely up to the scanner type. Scanner-wide transforms will reside here. Sensor-specific transforms will reside in the sensor's transform resource.

See scanner-specific documentation for details.

Methods

Method Description
read

Returns the alignment transforms.

Example response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/transform"
      }
    },
    "encoderResolution": 1.0,
    "speed": 100.0,
    "transform": {
      "xAngle": 0.0,
      "xOffset": 0.0,
      "yAngle": 0.0,
      "yOffset": 0.0,
      "zAngle": 0.0,
      "zOffset": 0.0
    }
  },
  "status": 1,
  "type": "response"
}
update

Update the alignment transforms manually. This will not change the scanner's alignment state. 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/transform { "transform" : { "xAngle" : -2.1} }

Notifications

Notification
updated

Occurs when the alignment configuration is updated or the alignment state changes. 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/alignment"}

/scan/engines/(engineId)/scanners/(scannerId)/metrics

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given scanner. Each scanner type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine..

Methods

Method Description
read

Reads the latest scanner metrics.

Example: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics

which for example, returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics"
      }
    },
    "advanced": {
      "overSpeedJitterCount": -9223372036854775808,
      "overSpeedJitterMax": -1.7976931348623157e+308
    },
    "encoderFreq": 0,
    "encoderValue": 0,
    "g2Scanner": {},
    "maxSpeed": 208.55397148676172,
    "scanCount": -9223372036854775808,
    "scannerDrops": 0,
    "speed": -1.7976931348623157e+308,
    "triggerDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of scanner metrics.

Example: 

stream /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics
cancelStream

Cancel continuous stream of scanner metrics.

Example: 

cancelStream /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics

/scan/engines/(engineId)/scanners/(scannerId)/outputs

Resource Type: (Collection - Unordered)

Description

A collection of scanner outputs.

Methods

Method Description
read

Returns the list of scanner outputsas embedded resources.

Example response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/sensor-0:profile"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/top:profile"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs"
      }
    }
  },
  "status": 1,
  "type": "response"
}

/scan/engines/(engineId)/scanners/(scannerId)/outputs/(outputId)

Resource Type: (CollectionItem)

ID: Predefined by scan engine.

Description

A scanner output object.

Properties

Item Type Schema Description
dataFormat object readOnly Data format of the output
dataSourceId string readOnly The data source id ( i.e."scan:LMILaserLineProfiler:scanner-0:top:surface")
displayName culture-specific string
User configurable display name of the scanner output.
enabled bool
Whether the scanner output is enabled or not.
id string readOnly Identifier of the scanner output.
recordingEnabled bool
Whether the output should be recorded or not.
priority integer readOnly

Priority of the scanner output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

0.3.x.x Added

Methods

Method Description
read

Returns the output parameters described above.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/stamp"
    }
  },
  "dataFormat": {
    "arrayed": false,
    "type": 8
  },
  "dataSourceId": "scan:LMILaserLineProfiler:scanner-0:stamp",
  "displayName": "Stamp",
  "enabled": true,
  "id": "stamp",
  "recordingEnabled": true
}
Update updates the output resource.

Notifications

Event Type Description
created

Occurs when a new output is added. The path indicates the new scanner output.

Example: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface"}
updated

Occurs when a scanner output's properties change. The path indicates the affected scanner output.

Example: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/stamp" }
deleted

Occurs when a scanner output is deleted. The path indicates the scanner output that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface" }

/scan/engines/(engineId)/scanners/(scannerId)/(contentId)

Resource Type: (CollectionItem)

ID: Predefined by scan engine.

Description

Custom scanner content resource defined by the scan engine. The format is a ParamSet object.

Methods

Method Description
read

Reads scanner custom content.

Example request: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout"
    }
  },
  "grid": {
    // ...
  }
}
update

Updates the custom scanner content resource.

Example request: 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout {...}

Notifications

Notification Description
updated

Occurs when the custom scanner content resource changes.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/layout" }

/scan/engines/(engineId)/scanners/(scannerId)/commands/align

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Aligns the scanner according to configurations defined in the /alignment resource.

Check the specific scan engine and scanner documentation to see if this command is supported.

/scan/engines/(engineId)/scanners/(scannerId)/commands/cancelAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Cancels running scanner alignment. If alignment is not running, this command does nothing.

Check the specific scan engine and scanner documentation to see if this command is supported.

/scan/engines/(engineId)/scanners/(scannerId)/commands/clearAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands

Description

Clears existing alignment. If alignment is running, then the alignment operation is cancelled first, then the existing alignment is cleared.

Check the specific scan engine and scanner documentation to see if this command is supported.

/scan/engines/(engineId)/scanners/(scannerId)/actions

Resource Type: (CollectionItem)

Description

A collection of scanner actions defined by the scan engine.

Methods

Method

Description

read

Returns a list of custom scanner actions as embedded resources.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/engineId/scanners/scannerId/actions/sampleAction"
          }
        }
      }
    ]
  },

    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/engineId/scanners/scannerId/actions"
    }
  }
}

Notifications

None.

/scan/engines/(engineId)/scanners/(scannerId)/actions/(actionId)

Resource Type: (CollectionItem , Callable)

ID: Predefined by scan engine.

Description

A custom scanner callable action. It can also be read to obtain information about the action.

Properties

Item

Type

Schema

Description

parameters

object

readOnly

Describes the parameters that the custom scanner action takes.
The client should supply the parameters when calling the action.

Methods

Method

Description

read

Reads the scanner custom action resource.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions/sampleAction

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/engineId/scanners/scannerId/actions/sampleAction"
    }
  },
  "_schema": {
    "parameters": {
      "properties": {
        "arg1": {
          "type": "string",
          "title": "Argument 1"
        }
      }
    }
  },
  "id": "trigger",
  "parameters": {
    "arg1": "default value"
  }
}

call

Calls the action resource.

Example request: 

call /scan/engines/engineId/scanners/scannerId/actions/sampleAction {arg1: "user value"}

Notifications

None.

/scan/engines/(engineId)/scanners/(scannerId)/sensors

Resource Type: (Collection - Unordered)

Description

A collection of sensors under the scanner.

Properties

Item Type Schema Description
creationParams object readOnly Custom sensor creation parameters, specific to the scan engine.

Methods

Method Description
read

Reads all sensors under the scanner; the list of sensors are returned as embedded items. 

{
   "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-1"
            }
          }
        }
      ]    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors"
      }
    },
    "creationParams": {
      "serialNumber": 0
    }
  },
}
create

Method Trait: ( NoRestart ) System will not be restarted when adding sensors. This applies if a scanner already has sensors and is already running. After the addition of a sensor to the scanner, the system will remain in stopped state.

Creates a sensor resource underneath the scanner.
NOTE: A client should read the sensors resource to see if there are creationParams that can be supplied in the create method.

Example request: 

create /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors {"serialNumber": 12345}

Notifications

None.

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)

Resource Type: (CollectionItem)

ID: Auto generated when sensors are added.

Description

A sensor object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the sensor.
id string readOnly Identifier of the sensor within the collection (e.g. "sensor-0").
parameters object
Additional parameters depending on the scan engine.
connectionMessage string readonly

Describes some details about the error if the connection status is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus integer readonly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the typically-numeric serial number represented as a string.
version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

Methods

Method Description
read

Reads the sensor resource.
Returns child resources as embedded items.
Returns actions as links.

Example response: 

{
  "_embedded": {
    "go:content": [ // see /scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/content
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/alignment"
          }
        }
      }
    ],
  },
  "_links": {
    "go:actions": [ // see /scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions
      {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
      },
      {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
      },
      {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
      },
    ],
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0"
    }
  },
  "displayName": "Sensor 0",
  "id": "sensor-0",
  "parameters": {
    // scan-engine-specific sensor parameters
  }
  // SensorInfo properties
}
update

Updates the sensor resource.

Arguments:

Item Type Description
parameters object Sensor parameters to update.

Example request: 

update /scan/engines/test/scanners/0/sensors/sensor-0 {"parameters" : { "subsamplingSettings" : { "xSubsampling" : 1 } } }
delete

Deletes the sensor resource.

Example request: 

delete /scan/engines/test/scanners/0/sensors/sensor-0

Notifications

Event Type Description
created

Occurs when a sensor is added to the scanner. The path indicates the affected sensor.

Example notification: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0"}
updated

Occurs when a sensor's properties change. The path indicates the affected sensor.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0" }
deleted

Occurs when a sensor is removed from a scanner. The path indicates the affected sensor.

Example notification: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0" }

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/ transform

Resource Type: (Collection - Unordered)

Description

The resource pertaining to alignment transforms at the sensor-level.

The contents of this resource are entirely up to the scanner & sensor type. Sensor-specific transforms will reside here.

See scanner-specific documentation for details.

Methods

Method Description
read

Returns the alignment transforms.

Example response: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/transform"
      }
    },
    "encoderResolution": 1.0,
    "speed": 100.0,
    "transform": {
      "xAngle": 0.0,
      "xOffset": 0.0,
      "yAngle": 0.0,
      "yOffset": 0.0,
      "zAngle": 0.0,
      "zOffset": 0.0
    }
  },
  "status": 1,
  "type": "response"
}
update

Update the alignment transforms manually. This will not change the scanner's alignment state. 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/transform { "transform" : { "xAngle" : -2.1} }

Notifications

Notification
updated

Occurs when the alignment configuration is updated or the alignment state changes. 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/alignment"}

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/metrics

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given sensor. Each sensor type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. Please refer to the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method Description
read

Reads the latest sensor metrics.

Example: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics

which for example returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics"
      }
    },
    "cameraBufferDrops0": 0,
    "cameraBufferDrops1": -9223372036854775808,
    "cameraTemp0": -9223372036854775808,
    "cameraTemp1": -9223372036854775808,
    "connectAttempts": 1,
    "cpuCores": [
      {
        "used": 1
      },
      {
        "used": 3
      }
    ],
    "cpuCoresUsedAvg": 2,
    "cpuCoresUsedMax": 3,
    "cpuTemp": 40259,
    "expTimeTotal": 3298,
    "intTemp": 31250,
    "laserDriverTemp": 29812,
    "laserSafety": true,
    "masterConnected": false,
    "masterStatus": false,
    "maxSpots": 1256,
    "memCapacity": 1053257728,
    "memUsed": 128603264,
    "networkIfs": [
      {
        "linkCapacity": 125000000,
        "linkStatus": 32,
        "rxBytes": 658570,
        "rxRate": 3118,
        "txBytes": 16242729,
        "txRate": 61384
      }
    ],
    "storageVolumes": [
      {
        "capacity": 251133952,
        "used": 87003136
      },
      {
        "capacity": 6762496,
        "used": 2347008
      }
    ],
    "syncSource": 2,
    "triggerDrops": 0,
    "upTime": 817
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of sensor metrics.

Example: 

stream /scan/engines/LMILaserLineProfiler/scanners/0/sensors/sensor-0/metrics
cancelStream

Cancel continuous stream of sensor metrics.

Example: 

cancelStream /scan/engines/LMILaserLineProfiler/scanners/0/sensors/sensor-0/metrics

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/(contentId)

Resource Type: (CollectionItem)

ID: Predefined by the scan engine.

Description

Custom sensor content, specific to the scan engine. The format is a ParamSet object.

Methods

Method Description
read

Reads sensor custom content.

Example request: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/alignment

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/alignment"
    }
  },
  "targetParams": {
    "alignmentType": 0,
    "targetType": 0,
    "targetValues": [],
    "updateEncoderSpeedCalibration": false
  },
  "transform": {
    "xAngle": 0.0,
    "xOffset": 0.0,
    "yAngle": 0.0,
    "yOffset": 0.0,
    "zAngle": 1.0,
    "zOffset": 0.0
  }
}
update

Updates the custom sensor content resource.

Example request: 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/alignment {...}

Notifications

Notification
updated

Occurs when the custom sensor content resource changes.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/alignment" }

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions

Resource Type: (CollectionItem)

ID: Predefined by the scan engine.

Description

A collection of sensor actions defined by the scan engine.

Methods

Method Description
read

Returns a list of custom sensor actions as embedded resources.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
          }
        }
      }
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/shutdown"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions"
    }
  }
}

Notifications

None.

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions/(actionId)

Resource Type: (CollectionItem , Callable)

ID: Predefined by scan engine.

Description

A custom sensor callable action. It can also be read to obtain information about the action.

Properties

Item Type Schema Description
parameters object readOnly

Describes the parameters that the custom sensor action takes.
The client should supply the parameters when calling the action.

Methods

Method Description
read

Reads the sensor custom action resource.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
    }
  },
  "id": "setAddress",
  "parameters": {
    "address": "",
    "dhcpEnabled": false,
    "gateway": "",
    "subnet": ""
  }
}
call

Calls the sensor custom action resource.

Example request: 

call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress {"address": "90.23.50.45, "dhcpEnabled" : false, ...}

Notifications

None.

GoPxL: Gocator Property Groups

This page describes some commonly used property groups for Gocator scanners and sensors.

This section documents property groups, not resources. Nested items are nested as properties, e.g. "lightSleep" inside the "trigger" section means this: 

{
  "trigger: {
    "lightSleep": {
      // ...
    }
  }
}

It does not mean a "lightSleep" resource is embedded in a "trigger" resource. See Resource Design and Request Methods#Relationships Hierarchy and Discoverability for more information about embedded resources.

Gocator Scanner Property Groups

The following property groups commonly appear in Gocator scanner resources.

Scanner Metrics (Property group)

Scanner-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a scanner for a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see their specific resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

speed

k64f

number

Current trigger rate (Hz). If scanner is not running, this metric is omitted.

20001

N/A

"Gocator/Current Sensor Speed"

maxSpeed

k64f

number

Maximum theoretical trigger rate (Hz); Note this does not consider CPU load from data processing and output. This should match the value specified in the trigger settings in the scanner parameters.

20002

N/A

"Gocator/Maximum Speed"

scanCount

k64u

integer

Number of scanned outputs for the given mode:

  • i.e. Number of profiles in profile mode

  • i.e. Number of surfaces in surface mode

  • i.e. Number of video outputs in video mode


0 if sensor is not running.

Note this number may differ slightly from actual number of profiles/surfaces/video messages received and processed.

20005

N/A

"Gocator/Scan Count"

frameCount

k64u

integer

Number of frames output.

This will be the same as the number of camera frames obtained.

1.0.x.x Added

scannerDrops

k64u

integer

Total drops across all sensor cameras & projectors that don't fall under trigger drops. Value resets on scan start, not stop, so value will persist when scanning stops.

0.3.x.x

Added

triggerDrops

k64u

integer

Total trigger drops across all sensors.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors across all sensors.

21202

N/A

Gocator/CameraErrors

processingLatency

k64u

integer

Processing latency (microseconds) for the last frame from this scanner.

Resets when a new scan is started.

21001

N/A

Gocator/Processing Latency

processingLatencyMax

k64u

integer

Highest processing latency(microseconds) from the entire scan.

Resets when a new scan is started.

21002

N/A

Gocator/Processing Latency Max

processingLatencyAvg

k64u

integer

Simple moving average of processing latency(microsecond) for the last 50 samples collected.

Resets when a new scan is started.

N/A

N/A

N/A

encoderValue

k64s

integer

Current scanner encoder tick.

1003

N/A

Node/EncoderValue

encoderFreq

k64s

integer

Current scanner encoder frequency (ticks/s). The sign of this metric serves as an indicator of the direction in which motion is occurring. A positive value denotes movement in a forward direction, whereas a negative value signifies movement in a backward or reverse direction.

1005

N/A

Node/EncoderFrequency

currentSyncTime

64u

Current value of the clock used to generate the time stamp for a scan data message.

N/A

N/A

laserEnabled

bool

boolean

This metric is an aggregate of the laser enabled status of all sensors managed by the scanner.

0: all sensors' laser is disabled (laser cannot be turned on)
1: one or more sensors' laser is enabled (laser can be turned on)

Derived from the sensor laserSafety health indicator.

Scanner metric aggregates the laserSafety setting from all online sensors. Only if all the online sensors' laserSafety value is 0 (ie. all the online sensors' lasers cannot be turned on), is the scanner level laserEnabled value set to 0. If any online sensor can potentially be turned on, then the scanner level laserEnabled is set to 1, as a cautionary warning to the user.

This scanner metric is named "laserEnabled" instead of "laserSafety", even though it is based on the sensor Node/laserSafety metric, is because "laserEnabled" more accurately describes the value of this metric.

N/A

N/A

advanced/overSpeedJitterCount

k64u

integer

Number of times speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

advanced/overSpeedJitterMax

k64f

number

Maximum amount that speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

Trigger Settings (Property group)

Property group representing trigger parameters used in Gocator scanner resources.

Item

Type

Schema

Description

parameters/triggerSettings/source

integer

enum

Trigger source.

  • 0 - Time

  • 1 - Encoder

  • 2 - External input (Digital input)

  • 3 - Software

parameters/triggerSettings/maxFrameRateEnabled

bool

visibility

Enables maximum frame rate.

parameters/triggerSettings/frameRate

number

minimum, maximum, actual, visibility

Frame rate for time trigger (Hz).

parameters/triggerSettings/ encoderSpacing

number

minimum, maximum, visibility

Spacing of profiles in the Y direction. (degrees) in rotational surface generation mode; (mm) for all other modes

parameters/triggerSettings/encoderTriggerMode

integer

enum, visibility

Encoder trigger mode.

  • 0 - Track Backward

  • 1 - Ignore Backward

  • 2 - Bi-directional

parameters/triggerSettings/externalInputIndex

integer

enum, visibility

External input index.

parameters/triggerSettings/schedulingUnits

integer

enum, visibility

Scheduling units.

  • 0 - Time

  • 1 - Encoder

parameters/triggerSettings/delay

number

minimum, maximum, visibility

Trigger delay (s or mm).

parameters/triggerSettings/gateEnabled

bool

actual, visibility

Enables digital input gating.

parameters/triggerSettings/reversalDistanceAutoEnabled

bool

visibility

Whether or not to use auto-calculated value of reversal distance.

parameters/triggerSettings/reversalDistance

number

readOnly, visibility

Encoder reversal threshold (for jitter handling).

parameters/triggerSettings/lightSleep

object

visibility

See Gocator Scanner - LightSleep below.

parameters/triggerSettings/burstScan

object

visibility

See Gocator Scanner - BurstScan below.

Filters (Property group)

1.0.x.x Added.

Property group representing parameters for filters used in Gocator scanner resources.

Item

Type

Schema

Description

parameters/filters/gapFilling

object

Gap filling filter

parameters/filters/gapFilling/enableX

bool

visibility

Enable gap filling along X axis.

parameters/filters/gapFilling/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/gapFilling/enableY

bool

visibility

Enable gap filling along Y axis; applies in surface mode only.

parameters/filters/gapFilling/winY

number

minimum, maximum,visibility, actual

Y window size (mm); applies in surface mode only.

1.2.x.x Actual schema added.

parameters/filters/median

object

Median filter

parameters/filters/median/enableX

bool

visibility

Enable median filtering along X axis.

parameters/filters/median/winX

number

minimum, maximum,visibility

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/median/enableY

bool

visibility

Enable median filtering along Y axis.

parameters/filters/median/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing

object

Smoothing filter

parameters/filters/smoothing/enableX

bool

visibility

Enable smoothing along X axis.

parameters/filters/smoothing/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing/enableY

bool

visibility

Enable smoothing along Y axis.

parameters/filters/smoothing/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation

object

Decimation filter

parameters/filters/decimation/enableX

bool

visibility

Enable decimation along X axis.

parameters/filters/decimation/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation/enableY

bool

visibility

Enable decimation along Y axis.

parameters/filters/decimation/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

LightSleep (Property group)

Property group representing light sleep parameters used in Gocator scanner resources.

Item

Type

Schema

Description

parameters/triggerSettings/lightSleep/enabled

bool

Enables light sleep.

parameters/triggerSettings/lightSleep/idleTime

integer

Idle time before light is turned off (s).

parameters/triggerSettings/lightSleep/wakeupEncoderTravel

number

Minimum amount of encoder movement before light turns on (mm).

BurstScan (Property group)

Property group representing burst scan parameters used in Gocator scanner resources.

Item Type Schema Description
enabled bool
Enables burst triggering.
count integer minimum, maximum, actual,visibility Number of scans to take during burst triggering.

Multiplexing (Property group)

Property group representing multiplexing parameters used in Gocator scanner resources.

Item

Type

Schema

Description

parameters/triggerSettings/manualMultiplexing/enabled

bool

Enable multiplexing.

parameters/triggerSettings/manualMultiplexing/globalEnabled

bool

Enable global multiplexing.

parameters/triggerSettings/manualMultiplexing/globalDelay

integer

Global multiplexing delay.

parameters/triggerSettings/manualMultiplexing/globalPeriod

integer

minimum

Global multiplexing period.

parameters/triggerSettings/manualMultiplexing/globalDuration

integer

readOnly

Global multiplexing duration.

Gocator Sensor Property Groups

The following property groups commonly appear in Gocator sensor resources.

Sensor Metrics (Property group)

Sensor-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see its resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

While sensor either connected or disconnected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

connectAttempts

k64s

integer

Number of retry attempts to connect to sensor.
See connection state within Resource Reference#/scan/(engineId)/visibleSensors .

N/A

Once sensor is connected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

upTime

k64u

integer

Time elapsed since node boot-up or reset (seconds).

2017

N/A

Node/UpTime

bootCount

k64s

integer

Number of boot-ups.

2086

Node/BootCount

laserSafety

bool

boolean

Laser safety status.

Values have the following meaning:

0: laser is disabled (laser cannot be turned on)
1: laser is enabled (laser can be turned on)

1010

N/A

Node/LightSafety

expTimeTotal

k64u

integer

Total time the laser has been on since first use. (seconds)

1.0.x.x

Added

maxSpots

k64u

integer

Maximum avaialble spots across all cameras on sensor.

1.0.x.x

Added.

masterConnected

bool

boolean

Master connection status.
false: if not connected
true: if connected and syncSource is Master.

20006

0 for main
1 for buddy

Gocator/MasterConnected/%u

masterStatus

bool

boolean

Duplicate of masterConnected?
false: if not connected
true: if connected and syncSource is Master.

20010

0 for main
1 for buddy

Gocator/MasterStatus/%u

syncSource

bool

boolean

Node synchronization source
1 - Master device
2 - Sensor

2043

N/A

Node/SyncSource

intTemp

k64s

integer

Controller temperature (millidegrees C).

20009

N/A

Gocator/IntTemp/%u

cpuTemp

k64s

integer

CPU temperature. (millidegress C)

20011

N/A

Gocator/CpuTemp/%u

cameraTemp0

k64s

integer

Camera board temperature (millidegrees C).

20012

N/A

Gocator/CameraTemp0/%u

cameraTemp1

k64s

integer

Camera board temperature (millidegrees C).

20013

N/A

Gocator/CameraTemp1/%u

laserDriverTemp

k64s

integer

Laser driver control temperature (millidegrees C).

2026

LightDriver/0/Temp

cameraBufferDrops0

k64u

integer

Total buffer drops for the current scan on camera 0. Value resets on scan start, not stop, so value will persist when scanning stops.

cameraBufferDrops1

k64u

integer

Total buffer drops for the current scan on camera 1. Value resets on scan start, not stop, so value will persist when scanning stops.

If the sensor has only one camera, this metric is not provided.

triggerDrops

k64u

integer

Trigger drops for the sensor.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors for the sensor

21202

N/A

Gocator/CameraErrors

memUsed

k64u

integer

Amount of memory currently used (bytes).

2003

N/A

Memory/TotalUsed

memCapacity

k64u

integer

Total amount of memory available (bytes).

2004

N/A

Memory/TotalCapacity

cpuCores

Array

array

List of CPU cores available to the sensor.

cpuCores/n

Structure

object

Single CPU core object.

cpuCores/n/used

k64u

integer

Individual CPU core utilization (percent).

2052

Cpu core index

Node/Cpu<instance>Used

cpuCoresUsedMax

k64u

integer

Max CPU core utilization (percent).

cpuCoresUsedAvg

k64u

integer

Average CPU core utilization (percent).

storageVolumes

Array

array

List of available storage volumes.

There should only ever be two:
1st (index 0) - User
2nd (index 1) - System

storageVolumes/n

Structure

object

Storage volume object.

Entry 0 is User
Entry 1 is System

storageVolumes/n/used

k64s

integer

Total amount of non-volatile storage used (bytes).

2005

0 - User
1 - System

StorageVolume/User/Used
StorageVolume/System/Used

storageVolumes/n/capacity

k64s

integer

Total amount of non-volatile storage available (bytes).

2006

0 - User
1 - System

StorageVolume/User/Capacity
StorageVolume/System/Capacity

storageVolumes/n/available

k64s

integer

Amount of non-volatile storage available (capacity - used) (bytes).

networkIfs

Array

array

List of available network interfaces.

networkIfs/n

Structure

object

Network interface object.

networkIfs/n/linkStatus

kEthernetLink

integer

Current Ethernet link status.

(0x0000) - No link, or speed unknown.
(0x0001) - 10 Mb/s, half duplex.
(0x0002) - 10 Mb/s, full duplex.
(0x0004) - 100 Mb/s, half-duplex.
(0x0008) - 100 Mb/s, full-duplex.
(0x0010) - 1000 Mb/s, half-duplex.
(0x0020) - 1000 Mb/s, full-duplex.
(0x8000) - Auto-negotiated.

2034

netInterface

NetInterface/<netInterface>/LinkStatus

networkIfs/n/linkCapacity

k64u

integer

Total available outbound network throughput (bytes/s).

2009

netInterface

NetInterface/<netInterface>/LinkCapacity

networkIfs/n/txRate

k64u

integer

Network output transmission rate (bytes/s)

2076

netInterface

NetInterface/<netInterface>/TxRate

networkIfs/n/rxRate

k64u

integer

Network output transmission rate (bytes/s)

2077

netInterface

NetInterface/<netInterface>/RxRate

networkIfs/n/txBytes

k64u

integer

Total number of bytes sent on network.

2078

netInterface

NetInterface/<netInterface>/TxBytes

networkIfs/n/rxBytes

k64u

integer

Total number of bytes received on network.

2079

netInterface

NetInterface/<netInterface>/RxBytes

storageMediumEraseTotal

k64u

integer

Total number of storage medium erases.

1.2.x.x

Added.

2093

StorageMedium/EraseTotal

storageMediumReadTotal

k64u

integer

Total number of storage medium reads.

1.2.x.x

Added.

2091

StorageMedium/ReadTotal

storageMediumWriteTotal

k64u

integer

Total number of storage medium writes.

1.2.x.x

Added.

2092

StorageMedium/WriteTotal

storageMediumBadBlocks

k64u

integer

Storage medium number of bad blocks.

1.2.x.x

Added.

3115

StorageMedium/BadBlocks

batteryRemainingCharge

k64s

integer

Remaining battery charge left in percentage multiplied by 1000

3104

N/A

Battery/RemainingCharge

batteryOperatingTime

k64s

integer

Remaining operating time for battery in hours multiplied by 1000

3105

N/A

Battery/OperatingTime

batteryStateOfHealth

k64s

integer

How much charge can the battery hold relative to when it was brand new, as a percentage multiplied by 1000

3106

N/A

Battery/StateOfHealth

batteryAlarmStatus

k64u

integer

Represents battery-related alarm status:

0 - no alarm
1 - battery low charge remaining alarm (< 10%)
2 - battery low operating time remaining alarm (< 0.5 hours)

3107

N/A

Battery/AlarmStatus

flexSpotErrors

k64u

integer

Flexible spots pipeline errors.

1.1.x.x Added

flexSpotBufferOverflows

k64u

integer

Flexible spots pipeline buffer overflow value.

1.1.x.x Added

flexSpotOverflows

k64u

integer

Flexible spots pipeline spot overflow value.

1.1.x.x Added

flexSpotPixelOverflows

k64u

integer

Flexible spots pipeline pixel overflow value.

1.1.x.x Added

Active Area Settings (Property group)

This property group is also an ExtendedType , specifically it is a TransformedBoxRegion . Please read the documentation there for more information.

TransformedBoxRegions are very flexible - for example all child properties are optional. However, Active Area regions are much less flexible. Only certain child properties will ever be missing, and only in certain cases. Also, Active Area regions are always defined with units of mm. Below describes what can be expected for Active Area TransformedBoxRegions.

Item

Type

Schema

Description

x

number

minimum, maximum, readOnly

X center (mm). The limits of X (ie minimum and maximum) vary according to the current Width. As Width increases, the freedom of motion for X decreases.

y

number

minimum, maximum, visibility, readOnly

Ycenter (mm). The limits of Y (ie minimum and maximum) vary according to the current Length. AsLength increases, the freedom of motion for Y decreases.

Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

z

number

minimum, maximum, readOnly

Zcenter (mm).

width

number

minimum, maximum, readOnly

X extent (mm).

1.0.x.x Added readOnly.

length

number

minimum, maximum, visibility, readOnly

Y extent (mm). Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

height

number

minimum, maximum, readOnly

Z extent (mm).

1.0.x.x Added readOnly.

transformMatrix

array

visibility

The transformMatrix should not be rendered in UI clients because used=false, but its contents can toggle between being invalid (empty matrix, usually in Image scan mode) or having values (profile and surface modes).

Camera (Property group)

Item

Type

Schema

Description

parameters/advancedSettings/cameraSettings/cameras/analogGain

number

minimum, maximum, readOnly, actual,visibility

Analog gain.

parameters/advancedSettings/cameraSettings/cameras/digitalGain

number

minimum, maximum, readOnly, actual

Digital gain.

parameters/advancedSettings/cameraSettings/cameras/gammaType

integer

enum, minimum, maximum, readOnly, actual,visibility

Gamma type.

  • 0 - None

  • 1 - Low

  • 2 - Medium

    • 3 - High

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness

object

visibility

Enhanced surface flatness feature parameters

1.1.x.x Parameter group created.

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/enabled

bool

readOnly

0 -feature is disabled

1 - feature is enabled

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/coefficients

array<number>

readOnly, actual, visibility

Array of coefficients if filterType is not 0.

ADVANCED

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/filterSize

enum

readOnly, visibility

Size of the filter if filterType is not 0. Allowed values3, 5, 7, 9, 11 and 13.

ADVANCED

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness\filterType

enum

readOnly, visibility

0 = User specified coefficient values
1 = Box filter
2 = Gaussian filter
ADVANCED

parameters/advancedSettings/cameraSettings/cameras/hdrMode

enum

readOnly,visibility

HDR mode

0 - disabled

1 - Gamma compression

1.1.x.x Added.

parameters/advancedSettings/cameraSettings/cameras/hdrGamma

number

readOnly, minimum, maximum

HDR gamma compression

1.1.x.x Added.

Gocator Alignment and Layout Property Groups

The following property groups commonly appear in Gocator alignment and layout content resources.

Target (Property group)

Property group representing target parameters used in scanner and sensor alignment content resources.

Item Type Schema Description
alignmentType integer enum

Alignment type.

  • 0 - Stationary
  • 1 - Moving
targetType integer enum

Target type.

If alignmentType is Stationary:

  • 0 - Flat
  • 1 - Bar
  • 2 - Polygon
  • 3 - Plate

If alignmentType is Moving:

  • 0 - Moving Bar
  • 1 - Disk
targetValues array<number>
Target alignment values.
updateEncoderSpeedCalibration bool
Updates encoder speed calibration.

Transform (Property group)

Property group representing a transformation matrix used in scanner and sensor alignment content resources.

Item

Type

Schema

Description

transform/xOffset

number

Translation on the X axis (mm).

transform/yOffset

number

visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/zOffset

number

Translation on the Z axis (mm).

transform/xAngle

number

visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/yAngle

number

Rotation around the Y axis (degrees).

transform/zAngle

number

visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.

Grid (Property group)

Property group representing a sensor layout grid used in scanner layout content resources.

Item

Type

Schema

Description

grid/columnCount

integer

Number of columns in the grid.

grid/sensors

array<object>

Array of grid sensor objects.

GridSensor:

Item

Type

Schema

Description

sensorId

string

readOnly

Identifier of the sensor within the collection (e.g. "sensor-0").

orientation

integer

enum

Sensor orientation.

  • 0 - Forward

  • 1 - Reverse

row

integer

enum

Row index.

  • 0 - Top/Row A

  • 1 - Bottom/Row B

column

integer

Column index.

multiplexingBank

integer

Exposure multiplexing bank.

displayName

string

DEPRECATED

This item has been deprecated. Use Sensor displayName instead.


GoPxL: LMILaserLineProfiler Engine (Gocator Laser Profiler)

LMILaserLineProfiler scan engine documentation applies to the G2xxx and G6xxx sensor families.

For the sake of brevity and reducing duplication, this page focuses on documenting resources and properties specific to the LMILaserLineProfiler scan engine.
See Scanner Resources for general documentation of the "/scan" resource.

/scan/engines/LMILaserLineProfiler

Resource Type: (CollectionItem)

Description

A scan engine object.

Properties

Item
Type
Schema
Description
displayName culture-specific string readOnly

Display name of the engine, e.g. "Gocator Laser Profiler".

id string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMILaserLineProfiler".
maxSensorCount integer

readOnly, minimum, used

Max sensor count.

1.0.x.x Added.

Methods

Method
Description
read

Reads a specific scan engine.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler"
    }
  },
  "displayName": "Gocator Laser Profiler",
  "id": "LMILaserLineProfiler",
  "maxSensorCount" : 31
}

Notifications

None (as engines cannot be created or deleted directly via the protocol

/scan/engines/LMILaserLineProfiler/visibleSensors

Resource Type: N/A

Description

Contains information about sensors discovered by a specific scan engine. All properties on this resource are read-only.

The format of this resource is identical to the format of Scanner Resources#/scan/visibleSensors except that it filters for only those sensors which are applicable to this scanEngine.

Properties

Item
Type
Schema
Description
connectionMessage string readOnly

Describes some details about the error if the connection state is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus integer readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
engineId string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMILaserLineProfiler".
isLocal bool readOnly True if the sensor is local to the application (e.g. running on the sensor). False if the sensor is remote.
parameters object readOnly

LMILaserLineProfiler scan engine provided additional sensor information.

Example:

{
"parameters" : {
"ipAddress" : "90.23.50.45" ,
"optionCode" : 1
}
}
parameters/ipAddress string readOnly Sensor IP address.
parameters/optionCode integer readOnly License option code.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.
version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

Methods

Method
Description
read

Reads the list of visible sensors, for a specific scan engine.

Example response: 

{  
  "sensors": [
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMILaserLineProfiler",
      "isLocal": false,
      "model": "2330",
      "parameters": {
        "ipAddress": "90.23.50.45",
        "optionCode": 1
      },
      "serialNumber": "45045",
      "version": "1.0.0.0"
    },
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "LMILaserLineProfiler",
      "isLocal": false,
      "model": "2340",
      "parameters": {
        "ipAddress": "90.23.50.46",
        "optionCode": 1
      },
      "serialNumber": "45046",
      "version": "1.0.0.0"
    },
  ]
}

Notifications

Notification

updated

Occurs when the visible sensors for a specific scan engine changes. The path indicates the specific scan engine's visible sensors list.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/visibleSensors" }

/scan/engines/LMILaserLineProfiler/scanners

Resource Type: (Collection - Unordered)

Description

A collection of scanners under the engine.

Properties

Item
Type
Schema
Description
creationParams object readOnly LMILaserLineProfiler scan engine required scanner creation parameters.
creationParams/defaultSerialNumber string readOnly Serial number of a sensor to add to the scanner. If 0, the scanner is created without a sensor.

Methods

Method
Description
read

Reads all scanners under the engine; the list of scanners are returned as embedded items.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners"
    }
  },
  "creationParams": {
    "defaultSerialNumber": 0
  }
}
create

Creates a scanner resource.
NOTE: A client should read the scanners resource to see if there are creationParams that can be supplied in the create method.

Example request: 

create /scan/engines/LMILaserLineProfiler/scanners {"defaultSerialNumber": 12345}

Notifications

Event Type
Description
created

Occurs when a new scanner is added. The path indicates the new scanner id.

Example notification: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0"}
updated

Occurs when a scanner's properties change. The path indicates the affected scanner id.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0" }
deleted

Occurs when a scanner is deleted. The path indicates the scanner id that was deleted.

Example notification: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0" }

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)

Resource Type: (CollectionItem)

ID: Auto generated when scanners are added.

Description

A scanner object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the scanner.
id string readOnly The identifer of the scanner within the collection (e.g. "scanner-0").
parameters object
LMILaserLineProfiler scan engine provided additional scanner information.
parameters/family integer readOnly, used

Sensor family.

  • 2 - LMILaserLineProfiler (Gocator laser profiler)

1.0.x.x Removed.

parameters/runningState integer

readOnly, used, enum

Run state.

  • 0 - Ready
  • 1 - Running
  • 2 - Error

1.0.x.x Removed.

parameters/maxSensorCount integer

readOnly,

minimum, used

Max sensor count.

Supported maxSensorCount is 31.

1.0.x.x Moved to Scanner Resources#/scan/engines/(engineId) .

parameterValidationMode integer enum, visibility

Experimental flag used for determining parameter validation severity to prevent getting stuck on blocking problems for default parameters

  • 0 - None
  • 1 - Potential
  • 2 - Blocking

1.2.x.x Added





parameters/scanModeSettings

object

LMILaserLineProfiler scan mode settings.

1.0.x.x Parameter group created

parameters/scanModeSettings/scanMode integer enum

Scan mode.

  • 0 - Image
  • 2 - Profile
  • 3 - Surface

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/intensityEnabled bool visibility

When this option is en abled, an intensity value will be produced for each data point.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/uniformSpacingEnabled bool visibility
When this option is enabled, data points are resampled to a uniform spacing.
1.0.x.x Moved to scanModeSettings
parameters/scanModeSettings/spacingIntervalMode integer visibility, enum

Spacing interval mode.

  • 0 - Max resolution
  • 1 - Balanced
  • 2 - Max speed
  • 3 - Custom

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/spacingInterval number minimum, maximum, readOnly, visibility, actual

Spacing interval value.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/surface object visibility

See parameters/Surface below.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/tempSafetyEnabled bool visibility

Enables las er temperature safety contro l. Only applies to certain laser-based sensors.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/profileMergeAlgorithm integer enum, visibility

Profile combiner algorithm.

  • 0 -Choose sensor with most number of points.
  • 1 -Choose sensor by the order of the data received.
  • 2 -Do a weighted average based on the distance from the sensors.
  • 3 -Choose sensor by the closest available.

Has ADVANCED visibility. See Schema and Data Types .

1.0.x.x Moved to scanModeSettings and reserved for future.

1.1.x.x Replaced "used" keyword with "visibility" set to ADVANCED.

parameters/scanModeSettings/surfaceMemCheckOverride bool visibility

Enables overriding of the G2 surface memory check BLOCKING problem if occurring.

Has ADVANCED visibility. See Schema and Data Types .

When autoAdjustSurfaceParameters is also enabled at the same time as this, autoAdjustSurfaceParameters has priority.

1.2.x.x added.

parameters/scanModeSettings/autoAdjustSurfaceParameters bool visibility

Enables automatic adjustment of G2 surface generating parameter to prevent out of memory detection and subsequent BLOCKING by changing parameter limit when necessary.

In TIME trigger mode, it adjusts (lowers) the maximum frame rate allowed.
In ENCODER trigger mode, it adjusts (increases) the minimum encoder spacing allowed.

When surfaceMemCheckOverride is also enabled at the same time as this, autoAdjustSurfaceParameters has priority.

Has ADVANCED visibility. See Schema and Data Types .

1.2.x.x added.

parameters/scanModeSettings/arrayedOutputs bool visibility

If enabled, data is output in an array format, rather than through individual outputs.

1.0.x.x Moved to scanModeSettings.

parameters/scanModeSettings/enableSoleSensorRowWorldFoR bool visibility

When a top or bottom row contains only a sole sensor, use the world FoR instead of the sensor FoR. This follows the legacy behavior in Gocator Classic and applies only when there are two or more sensors.

Has DEBUG visibility. See Schema and Data Types .

1.2.x.x Added "visibility" set to DEBUG.





parameters/scanModeSettings/surface

object

LMILaserLineProfiler surface parameters. Applicable when parameters/scanMode = 2 (Surface)

parameters/scanModeSettings/surface/type integer enum, actual, visibility
  • 1 - Fixed length
  • 2 - Variable length
  • 3 - Rotational
  • 0 - Continuous

1.0.x.x Added.

1.1.x.x Actual schema added.

parameters/scanModeSettings/surface/fixedLength object visibility

Fixed length surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 1 (Fixed Length)

parameters/scanModeSettings/surface/fixedLength/startTrigger integer enum, actual, visibility
  • 0 - Sequential
  • 1 - Digital input
  • 2 - Software
parameters/scanModeSettings/surface/fixedLength/inputIndex integer enum, actual, visibility Input index.
parameters/scanModeSettings/surface/fixedLength/length number
Surface length (mm).
parameters/scanModeSettings/surface/variableLength object visibility

Variable length surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 2 (Variable Length)

parameters/scanModeSettings/surface/variableLength/maxLength number
Maximum surface length (mm).
parameters/scanModeSettings/surface/rotational object visibility

Rotational surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 3 (Rotational)

parameters/scanModeSettings/surface/rotational/circumference number

1.0.x.x Removed.

parameters/scanModeSettings/surface/rotational/ticksPerRev number readOnly

Ticks per revolution.

1.0.x.x Added.

parameters/scanModeSettings/surface/continuous object visibility

Continuous surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 0 (Continuous)

1.0.x.x Continuous surface parameters added.

parameters/scanModeSettings/surface/continuous/heightThreshold number
Height threshold (mm).
parameters/scanModeSettings/surface/continuous/thresholdDirection integer enum
  • 0 - Above
  • 1 - Below
parameters/scanModeSettings/surface/continuous/keepAllSingle bool

Include one-sided data option.

1.0.x.x Added.

parameters/scanModeSettings/surface/continuous/gapWidth number
Gap width (mm).
parameters/scanModeSettings/surface/continuous/gapLength number
Gap length (mm).
parameters/scanModeSettings/surface/continuous/paddingWidth number
Padding width(mm).
parameters/scanModeSettings/surface/continuous/paddingLength number
Padding length (mm).
parameters/scanModeSettings/surface/continuous/minArea number
Mininum area (mm 2 ).
parameters/scanModeSettings/surface/continuous/maxLength number
Maximum length (mm).
parameters/scanModeSettings/surface/continuous/edgeFiltering bool
Edge filtering option.
parameters/scanModeSettings/surface/continuous/edgeKeepInterior bool
Keep interior option for edge filtering.
parameters/scanModeSettings/surface/continuous/edgeWidth number
Edge filtering width (mm).
parameters/scanModeSettings/surface/continuous/edgeLength number
Edge filtering length(mm).




parameters/scanModeSettings/profileSort object
Reserved for future use.




parameters/triggerSettings

object

Property group representing trigger parameters used in Gocator scanner resources.

1.0.x.x Renamed to triggerSettings.

parameters/triggerSettings/source integer enum

Trigger source.

  • 0 - Time
  • 1 - Encoder
  • 2 - Digital input
  • 3 - Software
parameters/triggerSettings/maxFrameRateEnabled bool visibility Enables maximum frame rate.
parameters/triggerSettings/frameRate number minimum, maximum, actual, visibility Frame rate for time trigger (Hz).
parameters/triggerSettings/encoderSpacing number minimum, maximum, visibility Encoder spacing (degrees) in rotational surface generation mode; (mm) in all other modes.
parameters/triggerSettings/encoderTriggerMode integer enum, visibility

Encoder trigger mode.

  • 0 - Track Backward
  • 1 - Ignore Backward
  • 2 - Bi-directional
parameters/triggerSettings/externalInputIndex integer enum, visibility External input index.
parameters/triggerSettings/schedulingUnits integer enum, visibility

Scheduling units.

  • 0 - Time
  • 1 - Encoder
parameters/triggerSettings/delay number minimum, maximum, visibility Trigger delay (s or mm).
parameters/triggerSettings/gateEnabled bool actual, visibility Enables digital input gating.
parameters/triggerSettings/reversalDistanceAutoEnabled bool visibility Whether or not to use auto-calculated value of reversal distance.
parameters/triggerSettings/reversalDistance number readOnly, visibility Encoder reversal threshold (for jitter handling).
parameters/triggerSettings/lightSleep object visibility Property group representing light sleep parameters used in Gocator scanner resources.
parameters/triggerSettings/lightSleep/enabled bool
Enables light sleep.
parameters/triggerSettings/lightSleep/idleTime integer
Idle time before light is turned off (s).
parameters/triggerSettings/lightSleep/wakeupEncoderTravel number
Minimum amount of encoder movement before light turns on (mm).
parameters/triggerSettings/burstScan object visibility Property group representing burst scan parameters used in Gocator scanner resources.
parameters/triggerSettings/burstScan/enabled bool
Enables burst triggering.
parameters/triggerSettings/burstScan/count integer minimum, maximum, actual,visibility Number of scans to take during burst triggering.
parameters/triggerSettings/externalInputZPulseEnabled bool

Enables the External Input based encoder Z Pulse feature.

1.0.x.x Moved to triggerSettings

parameters/triggerSettings/externalInputZPulseIndex integer visibility

Input index to use for the input triggered z pulse feature.

1.0.x.x Moved to triggerSettings

parameters/triggerSettings/manualMultiplexing

object


Property group representing multiplexing parameters used in Gocator scanner resources.

1.0.x.x Moved to triggerSettings

parameters/triggerSettings/manualMultiplexing/enabled bool
Enable multiplexing.
parameters/triggerSettings/manualMultiplexing/globalEnabled bool
Enable global multiplexing.
parameters/triggerSettings/manualMultiplexing/globalDelay integer
Global multiplexing delay.
parameters/triggerSettings/manualMultiplexing/globalPeriod integer minimum Global multiplexing period.
parameters/triggerSettings/manualMultiplexing/globalDuration integer readOnly Global multiplexing duration.
parameters/triggerSettings/preferMasterTimeEncoderEnabled bool

Prefer master time and encoder.

1.0.x.x Moved to triggerSettings





parameters/filters

object

Property group representing parameters for filters used in Gocator scanner resources.

1.0.x.x Added.

parameters/filters/gapFilling object
Gap filling filter
parameters/filters/gapFilling/enableX bool visibility Enable gap filling along X axis.
parameters/filters/gapFilling/winX number minimum, maximum,visibility

, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/gapFilling/enableY bool visibility Enable gap filling along Y axis; applies in surface mode only.
parameters/filters/gapFilling/winY number minimum, maximum,visibility

, actual

Y window size (mm); applies in surface mode only.

1.2.x.x Actual schema added.

parameters/filters/median object
Median filter
parameters/filters/median/enableX bool visibility Enable median filtering along X axis.
parameters/filters/median/winX number minimum, maximum,visibility

, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/median/enableY bool visibility Enable median filtering along Y axis.
parameters/filters/median/winY number minimum, maximum,visibility

, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing object
Smoothing filter
parameters/filters/smoothing/enableX bool visibility Enable smoothing along X axis.
parameters/filters/smoothing/winX number minimum, maximum,visibility

, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing/enableY bool visibility Enable smoothing along Y axis.
parameters/filters/smoothing/winY number minimum, maximum,visibility

, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation object
Decimation filter
parameters/filters/decimation/enableX bool visibility Enable decimation along X axis.
parameters/filters/decimation/winX number minimum, maximum,visibility

, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation/enableY bool visibility Enable decimation along Y axis.
parameters/filters/decimation/winY number minimum, maximum,visibility

, actual

Y window size (mm).

1.2.x.x Actual schema added.





parameters/ advancedSettings

object used

LMILaserLineProfiler advanced scanner parameters.

1.0.x.x Removed.

engineId string readOnly The identifier of the scanner's scan engine.

1.1.x.x Added.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/commands/align

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Aligns the scanner according to configurations defined in the /alignment resource.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

parameters

object

read-only

parameters/interactive

boolean

Indicates if the alignment operation requires interaction from the user or not.

Call Command Arguments

Item

Type

Mandatory or Optional

Description

interactive

boolean

Optional

Default value: false.

If true, the scanner will attempt to align interactively & request user parameters.
If false, alignment will run on its own without any additional inputs.

Scanners may choose not to implement interactive alignment, in which case this parameter should be ignored.

Properties

Item
Type
Schema
Description
id string readOnly Identifier of this command.
parameters object readOnly
parameters/interactive boolean
Indicates if the alignment operation requires interaction from the user or not.

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command.

The value of parameters are equal to their default values.

Example Response: 

{
  "payload": {
    "id": "align",
    "parameters": {
      "interactive": false
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/align"
      }
    }
  },
  "path": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/align",
  "type": "response",
  "status": 1
}
call

Aligns the scanner. The response to calling this resource may be returned immediately, even if if alignment has not completed. In this case, clients can check for alignment completion by checking alignState on the parent scanner resource. More specific behavior information can be found within the scan engine specific documentation.

Example request: 

call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/align {"interactive":false}

Notifications

None.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/commands/cancelAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Cancels running scanner alignment. If alignment is not running, this command does nothing.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

Call Command Arguments

None

Properties

Item
Type
Schema
Description
id string readOnly Identifier of this command.

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command.

Example Response: 

{
  "payload": {
    "id": "cancelAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/cancelAlign"
      }
    }
  },
  "path": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/cancelAlign",
  "type": "response",
  "status": 1
}
call

Cancels scanner alignment.

Example request 

call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/cancelAlign

Notifications

None.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/commands/clearAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands

Description

Clears existing alignment. If alignment is running, then the alignment operation is cancelled first, then the existing alignment is cleared.

Properties

Item
Type
Schema
Description
id string readOnly Identifier of this command.

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command. 

{
  "payload": {
    "id": "clearAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/clearAlign"
      }
    }
  },
  "path": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/clearAlign",
  "type": "response",
  "status": 1
}
call

Clears scanner alignment.

Example request 

call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/clearAlign

Notifications

None.


/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/metrics

For metrics common across all Gocator scanners:

Scanner-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a scanner for a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see their specific resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

speed

k64f

number

Current trigger rate (Hz). If scanner is not running, this metric is omitted.

20001

N/A

"Gocator/Current Sensor Speed"

maxSpeed

k64f

number

Maximum theoretical trigger rate (Hz); Note this does not consider CPU load from data processing and output. This should match the value specified in the scanner parameters at Standard Scanner Resources#Trigger(Propertygroup) .

20002

N/A

"Gocator/Maximum Speed"

scanCount

k64u

integer

Number of scanned outputs for the given mode:

  • i.e. Number of profiles in profile mode

  • i.e. Number of surfaces in surface mode

  • i.e. Number of video outputs in video mode


0 if sensor is not running.

Note this number may differ slightly from actual number of profiles/surfaces/video messages received and processed.

20005

N/A

"Gocator/Scan Count"

frameCount

k64u

integer

Number of frames output.

This will be the same as the number of camera frames obtained.

1.0.x.x Added

scannerDrops

k64u

integer

Total drops across all sensor cameras & projectors that don't fall under trigger drops. Value resets on scan start, not stop, so value will persist when scanning stops.

0.3.x.x

Added

triggerDrops

k64u

integer

Total trigger drops across all sensors.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors across all sensors.

21202

N/A

Gocator/CameraErrors

processingLatency

k64u

integer

Processing latency (microseconds) for the last frame from this scanner.

Resets when a new scan is started.

21001

N/A

Gocator/Processing Latency

processingLatencyMax

k64u

integer

Highest processing latency(microseconds) from the entire scan.

Resets when a new scan is started.

21002

N/A

Gocator/Processing Latency Max

processingLatencyAvg

k64u

integer

Simple moving average of processing latency(microsecond) for the last 50 samples collected.

Resets when a new scan is started.

N/A

N/A

N/A

encoderValue

k64s

integer

Current scanner encoder tick.

1003

N/A

Node/EncoderValue

encoderFreq

k64s

integer

Current scanner encoder frequency (ticks/s). The sign of this metric serves as an indicator of the direction in which motion is occurring. A positive value denotes movement in a forward direction, whereas a negative value signifies movement in a backward or reverse direction.

1005

N/A

Node/EncoderFrequency

currentSyncTime

64u

Current value of the clock used to generate the time stamp for a scan data message.

N/A

N/A

laserEnabled

bool

boolean

This metric is an aggregate of the laser enabled status of all sensors managed by the scanner.

0: all sensors' laser is disabled (laser cannot be turned on)
1: one or more sensors' laser is enabled (laser can be turned on)

Derived from the sensor laserSafety health indicator.

Scanner metric aggregates the laserSafety setting from all online sensors. Only if all the online sensors' laserSafety value is 0 (ie. all the online sensors' lasers cannot be turned on), is the scanner level laserEnabled value set to 0. If any online sensor can potentially be turned on, then the scanner level laserEnabled is set to 1, as a cautionary warning to the user.

This scanner metric is named "laserEnabled" instead of "laserSafety", even though it is based on the sensor Node/laserSafety metric, is because "laserEnabled" more accurately describes the value of this metric.

N/A

N/A

advanced/overSpeedJitterCount

k64u

integer

Number of times speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

advanced/overSpeedJitterMax

k64f

number

Maximum amount that speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given scanner. Each scanner type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method
Description
read

Reads the latest scanner metrics.

Example: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics

which for example, returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics"
      }
    },
    "advanced": {
      "overSpeedJitterCount": -9223372036854775808,
      "overSpeedJitterMax": -1.7976931348623157e+308
    },
    "encoderFreq": 0,
    "encoderValue": 0,
    "g2Scanner": {},
    "maxSpeed": 208.55397148676172,
    "scanCount": -9223372036854775808,
    "scannerDrops": 0,
    "speed": -1.7976931348623157e+308,
    "triggerDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of scanner metrics.

Example: 

stream /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics
cancelStream

Cancel continuous stream of scanner metrics.

Example: 

cancelStream /scan/engines/LMILaserLineProfiler/scanners/scanner-0/metrics

LMILaserLineProfiler scanners do not currently have any unique metrics.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/outputs

Resource Type: (Collection - Unordered)

Description

A collection of scanner outputs.

Methods

Method
Description
read

Returns the list of scanner outputsas embedded resources.

Example response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/sensor-0:profile"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/top:profile"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs"
      }
    }
  },
  "status": 1,
  "type": "response"
}

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/outputs/(outputId)

Resource Type: (CollectionItem)

ID: Predefined by scan engine.

Description

A scanner output object.

Properties

Item
Type
Schema
Description
dataFormat object readOnly Data format of the output
dataSourceId string readOnly The data source id ( i.e."scan:LMILaserLineProfiler:scanner-0:top:surface")
displayName culture-specific string
User configurable display name of the scanner output.
enabled bool
Whether the scanner output is enabled or not.
id string readOnly Identifier of the scanner output.
recordingEnabled bool
Whether the output should be recorded or not.
priority integer readOnly

Priority of the scanner output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

0.3.x.x Added

Methods

Method
Description
read

Returns the output parameters described above.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/outputs/stamp"
    }
  },
  "dataFormat": {
    "arrayed": false,
    "type": 8
  },
  "dataSourceId": "scan:LMILaserLineProfiler:scanner-0:stamp",
  "displayName": "Stamp",
  "enabled": true,
  "id": "stamp",
  "recordingEnabled": true
}
Update updates the output resource.

Notifications

Event Type
Description
created

Occurs when a new output is added. The path indicates the new scanner output.

Example: 

{ "eventType" : "created", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface"}
updated

Occurs when a scanner output's properties change. The path indicates the affected scanner output.

Example: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/stamp" }
deleted

Occurs when a scanner output is deleted. The path indicates the scanner output that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface" }

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/alignment

Properties

LMILaserLineProfiler scan engine-specific alignment configuration, containing user alignment configurations that will be applied to the alignment process.

Item Type Schema Description
alignConfig/timeout integer

Maximum time non-interactive alignment can take. If this time is exceeded, alignment will be aborted.

If alignment is run interactively, timeout is infinite.

1.0.x.x Added.

alignState

enum


Current state of alignment:

0 - Not aligned.
1 - Aligned.
2 - Alignment in progress.

1.0.105.100 Added.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/transform

Properties

LMILaserLineProfiler scan engine-specific alignment transforms, containing user alignment transforms that will be applied to the scanner.

Item Type Schema Description
encoderResolution number exclusiveMinimum

Encoder resoluti on for encoder-based triggering (degrees/tick) in rotational surface generation mode, assuming one millimeter per degree; (mm/tick) in all other modes.

speed number exclusiveMinimum Travel Speed of the sensor used in time mode (mm/s).
transform object visibility

Transformation object, consisting of offsets and angles.

Property group representing a transformation matrix used in scanner and sensor alignment content resources.

1.0.x.x Reserved for future.

transform/

xOffset 		number

Translation on the X axis (mm).

transform/

yOffset 		number visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/

zOffset 		number
Translation on the Z axis (mm).

transform/

xAngle 		number visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/

yAngle 		number

Rotation around the Y axis (degrees).

transform/

zAngle 		number visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/layout

Resource Type: (CollectionItem)

ID: Predefined by scan engine.

Description

Scan engine layout.

Properties

LMILaserLineProfiler scan engine layout content. The layout needs to be updated with sensors with the corresponding sensor-id and position in the grid.

Item Type Schema Description
type integer

Layout type.

  • 0 - Grid
grid object

Grid Layout.

grid/columnCount integer
Number of columns in the grid.
grid/sensors array< GridSensor >
Array of grid sensor objects.

Methods

Method
Description
read

Reads scanner layout.

Example request: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout"
    }
  },
  "grid": {
    // ...
  }
}
update

Updates the scanner layout resource.

Example request: 

update /scan/engines/LMILaserLineProfiler/scanners/scanner-0/layout {...}

Notifications

Notification
Description
updated

Occurs when the scanner layout changes.

Example notification: 

{ "eventType" : "updated", "path" : "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/layout" }

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/actions

Resource Type: (CollectionItem)

Description

A collection of scanner actions defined by the scan engine.

Methods

Method

Description

read

Returns a list of custom scanner actions as embedded resources.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/engineId/scanners/scannerId/actions/sampleAction"
          }
        }
      }
    ]
  },

    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/engineId/scanners/scannerId/actions"
    }
  }
}

Notifications

None.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/actions/trigger

Resource Type: (CollectionItem , Callable)

ID: Predefined by scan engine.

Description

Software trigger.

Properties

Item
Type
Schema
Description
id string readOnly Identifier of this command.
message string readOnly Message component of the action if used.

Methods

Method
Description
read

Reads the software trigger.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions/trigger

Example response: 

{
  "payload": {
    "id": "trigger",
    "message": "",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/actions/trigger"
      }
    }
  },
  "path": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/actions/trigger",
  "type": "response",
  "status": 1
}
call

Calls the software trigger.

Example request: 

call /scan/engines/engineId/scanners/scannerId/actions/trigger

Notifications

None.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/sensors

Resource Type: (Collection - Unordered)

Description

A collection of sensors under the scanner.

Properties

Item
Type
Schema
Description
creationParams object readOnly LMILaserLineProfiler scan engine required sensor creation parameters.
creationParams/serialNumber string readOnly Serial number of a sensor to add to the scanner.

Methods

Method
Description
read

Reads all sensors under the scanner; the list of sensors are returned as embedded items. 

{
   "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-1"
            }
          }
        }
      ]    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors"
      }
    },
    "creationParams": {
      "serialNumber": 0
    }
  },
}
create

Method Trait: ( NoRestart ) System will not be restarted when adding sensors. This applies if a scanner already has sensors and is already running. After the addition of a sensor to the scanner, the system will remain in stopped state.

Creates a sensor resource underneath the scanner.
NOTE: A client should read the sensors resource to see if there are creationParams that can be supplied in the create method.

Example request: 

create /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors {"serialNumber": 12345}

Notifications

None.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/sensors/(sensorId)

Resource Type: (CollectionItem)

ID: Auto generated when sensors are added.

Description

A sensor object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the sensor.
id
readOnly Identifier of the sensor within the collection (e.g. "sensor-0").
parameters object readOnly Additional parameters depending on the scan engine.
parameters/firstCameraAlgorithm integer visibility, readOnly

Internal flag to indicate the current algorithm set for the first camera.

1.2.x.x Added.

parameters/activeAreaSettings

object extendedType

LMILaserLineProfiler active area parameters.

extendedType = TransformedBoxRegion


parameters/advancedSettings/materialType integer enum, readOnly
  • 1 - Diffuse
  • 0 - Custom

The readOnly state of many other parameters within advancedSettings depend on the value of materialType.
When materialType is "diffuse" many parameters are readOnly=true, but when materialType is "custom" these parameters are readOnly=false to allow adjustment.

1.0.x.x Corrected that Diffuse = 1, Custom = 0 (prior documented values were wrong).

parameters/advancedSettings/cameraHighSpeedMode bool visibility

Whether to force camera window speed mode.

0 - false.

1 - true.

Currently an experimental feature.

1.2.x.x Added.

parameters/advancedSettings/cameraSettings object readOnly

Settings associated w/ all cameras and control of individual cameras. Modifiable when materialType is Custom

1.0.x.x Added.

parameters/advancedSettings/cameraSettings/sensitivityCompensationEnabled bool visibility, actual, readOnly


parameters/advancedSettings/cameraSettings/cameras array<object>

1.0.x.x gammaType does not apply, only analogGain and digitalGain.

parameters/advancedSettings/cameraSettings/cameras/analogGain number minimum, maximum, readOnly, actual,visibility Analog gain.
parameters/advancedSettings/cameraSettings/cameras/digitalGain number minimum, maximum, readOnly, actual Digital gain.
parameters/advancedSettings/cameraSettings/cameras/gammaType integer enum, minimum, maximum, readOnly, actual,visibility

Gamma type.

  • 0 - None
  • 1 - Low
  • 2 - Medium
    • 3 - High
parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness object visibility

Enhanced surface flatness feature parameters

1.1.x.x Parameter group created.

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/enabled

bool

readOnly

0 -feature is disabled

1 - feature is enabled

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/coefficients array<number> readOnly, actual, visibility

Array of coefficients if filterType is not 0.

ADVANCED

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/filterSize enum

readOnly, visibility

Size of the filter if filterType is not 0. Allowed values3, 5, 7, 9, 11 and 13.

ADVANCED

parameters/advancedSettings/cameraSettings/cameras/enhancedSurfaceFlatness/filterType

enum

readOnly, visibility

0 = User specified coefficient values
1 = Box filter
2 = Gaussian filter

ADVANCED

parameters/advancedSettings/cameraSettings/cameras/hdrMode enum readOnly,visibility

HDR mode

0 - disabled

1 - Gamma compression

1.1.x.x Added.

parameters/advancedSettings/cameraSettings/cameras/hdrGamma

number readOnly, minimum, maximum

HDR gamma compression

1.1.x.x Added.

parameters/advancedSettings/dynamicExposure object

Dynamic exposure parameters.

1.0.x.x Added.

parameters/advancedSettings/dynamicExposure/sensitivity number minimum, maximum, actual, readOnly

Set to readOnly unless materialType is Custom.

1.0.x.x Moved under dynamicExposure, and renamed to just "sensitivity".

parameters/advancedSettings/dynamicExposure/threshold number minimum, maximum, actual, readOnly

Set to readOnly unless materialType is Custom.

1.0.x.x Moved under dynamicExposure, and renamed to just "threshold".

parameters/advancedSettings/advanced object

Higher level advanced features. Reserved for future.

parameters/advancedSettings/advanced/blackLevelAdjust integer readOnly

Reserved for future.

parameters/advancedSettings/advanced/dualCameraMergeType integer readOnly

Reserved for future.

parameters/advancedSettings/advanced/forceOnSensorResampling bool readOnly

By default the resampling processing is performed on the PC or GoMax NX when a sensor is remotely connected.
This flag can override such behavior so that resampling processing is performed on the actual sensor itself. This may be beneficial for sensors with more processing power.

parameters/advancedSettings/cameraBatchingSize integer readOnly

This enables camera batching mode. It allows more efficient camera data handling when using high frame rates.

parameters/advancedSettings/forceLocalSorter bool readOnly

By default, sorting is performed on the physical sensor, even when a sensor is remotely connected to a PC or GoMax NX.
This flag can override such behaviour so that sorting is performed on the PC or GoMax NX instead.

parameters/advancedSettings/enableRangeSlice bool readOnly

This enables the optional LMILaserLineProfiler range slice data when LMILaserLineProfiler scanner is running in profile range mode.
Note that enabling this flag uses more network resources.

parameters/advancedSettings/spotDetection

object

LMILaserLineProfiler spot detection parameters.

1.0.x.x Not changeable unless materialType is Custom

parameters/advancedSettings/spotDetection/selectionType integer enum, readOnly
  • 0 - None
  • 1 - Best (Intensity)
  • 2 - Top
  • 3 - Bottom
  • 4 - Continuity
parameters/advancedSettings/spotDetection/threshold integer actual, readOnly, minimum, maximum

The minimum increase in intensity level between neighbouring pixels for a pixel to be considered the start of a potential spot.

This setting can be used for filtering false spots.

parameters/advancedSettings/spotDetection/flexSpots


object visibility

Flexible spots.

Has ADVANCED visibility. See Schema and Data Types .

1.2.x.x Replaced "used" keyword with "visibility" set to ADVANCED.

parameters/advancedSettings/spotDetection/minWidth integer actual, readOnly, minimum, maximum

The minimum width of a detected spot in pixels.

Increasing this can reduce spots resulting from small noise but has the trade off of potentially eliminating valid points in dark areas.

parameters/advancedSettings/spotDetection/maxWidth integer actual, readOnly, minimum, maximum The maximum width of a detected spot in pixels.
Reducing this value can filter out very wide spots in bright areas.
parameters/advancedSettings/spotDetection/minSum integer actual, readOnly, minimum, maximum

Minimum sum of pixel intensity values over a spot. If the total of pixel values is below this value, the spot will be dropped.

Can be used to exclude weak spots, but this is typically undesirable so it is often set to 1.

parameters/advancedSettings/spotDetection/continuitySorting object

Continuity sorting parameters. Applicable only whenparameters/advancedSettings/spotDetection/selectionType = 4 (Continuity)

parameters/advancedSettings/spotDetection/continuitySorting/minSegmentSize integer

actual. readOnly, minimum, maximum

The minimum segment size in pixels.
parameters/advancedSettings/spotDetection/continuitySorting/searchWindowWidth integer actual, readOnly, minimum, maximum The width of the search window in pixels.
parameters/advancedSettings/spotDetection/continuitySorting/searchWindowLength integer actual, readOnly, minimum, maximum The length of the search window in pixels.
parameters/laserSafetyLock bool visibility

Laser safety lock state for the sensor.

0 - laser safety lock is off.

1 -laser safety lock is on.

For sensor that support this, can also change the state by updating this parameter to the desired state. Currently, only battery powered sensors support this.

1.2.x.x Added.

parameters/powerSaveMode bool visibility

Power save mode for the sensor.

0 - power save mode is off.

1 -power save mode is on.

For sensor that support this, changing the state of this parameter will update the state. Mainly useful for battery powered sensors.

1.2.x.x Added.

connectionMessage string readOnly

Describes some details about the error if the connection status is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus int readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.
version

string

readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

parameters/exposureSettings

object

LMILaserLineProfiler exposure settings.

1.0.x.x Parameter group created

parameters/exposureSettings/exposureMode integer enum, readOnly

Exposure mode.

  • 0 - Single exposure
  • 1 - Multiple exposures
  • 2 - Dynamic exposure
parameters/exposureSettings/singleExposure number

minimum, maximum, visibility, readOnly

The exposure value to use whenparameters /exposureSettings/ exposureMode = 0 (Single exposures)

parameters/exposureSettings/multipleExposures array<number> minItems, maxItems, visibility, readOnly

This contains a list of exposure values to use whenparameters /exposureSettings/ exposureMode = 1 (Multiple Exposures)

parameters/exposureSettings/enableUnmergedMultiExp bool readOnly

This is to enable the output of unmerged multiple exposure profile. Unmerged multi exposure output is only valid and available in profile mode.

1.0.x.x Moved here from parameters/advancedSettings/advanced.

parameters/exposureSettings/enableUnmergedMultiExpAllowed bool visibility, readOnly

Internal flag to indicate enableUnmergedMultiExp support is available.

1.2.x.x Added.

parameters/exposureSettings/dynamicExposureMin number visibiltiy, readOnly

User-defined minimum allowable exposure whenparameters/ exposureSettings/ exposureMode = 2 (dynamic)

parameters/exposureSettings/dynamicExposureMax number visibility, readOnly

User-defined maximum allowable exposurewhenparameters/ exposureSettings/ exposureMode = 2 (dynamic)

parameters/exposureSettings/intensityMode integer visibility, enum, readOnly

Controls how intensity data is selected.

  • 0 - Auto
  • 1 - Preserve legacy behavior
parameters/exposureSettings/intensityStep integer visibility,minimum, maximum, readOnly

Determines the specific index ofparameters/exposureSettings/multipleExposures to use for intensity data whenparameters /exposureSettings/ exposureMode = 1 (Multiple Exposures)

parameters/subsamplingSettings object

LMILaserLineProfiler internal subsampling settings.

1.0.x.x Parameter group created.

parameters/subsamplingSettings/xSubsampling integer

Subsampling along X-axis

  • 1 - No subsampling
  • 2 - Subsampling every second sample
  • 4 - Subsampling every fourth sample
parameters/subsamplingSettings/xSubsamplingDefaultEnabled bool
Flag indicating whether X subsampling is allowed.
parameters/subsamplingSettings/zSubsampling integer

Subsampling along Z-axis

  • 1 - No subsampling
  • 2 - Subsampling every second sample
  • 4 - Subsampling every fourth sample
parameters/subsamplingSettings/zSubsamplingDefaultEnabled bool
Flag indicating whether Z subsampling is allowed.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/sensors/(sensorId)/metrics

For metrics common across all Gocator sensors:

Sensor-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see its resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

While sensor either connected or disconnected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

connectAttempts

k64s

integer

Number of retry attempts to connect to sensor.
See connection state within Resource Reference#/scan/(engineId)/visibleSensors .

N/A

Once sensor is connected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

upTime

k64u

integer

Time elapsed since node boot-up or reset (seconds).

2017

N/A

Node/UpTime

bootCount

k64s

integer

Number of boot-ups.

2086

Node/BootCount

laserSafety

bool

boolean

Laser safety status.

Values have the following meaning:

0: laser is disabled (laser cannot be turned on)
1: laser is enabled (laser can be turned on)

1010

N/A

Node/LightSafety

expTimeTotal

k64u

integer

Total time the laser has been on since first use. (seconds)

1.0.x.x

Added

maxSpots

k64u

integer

Maximum avaialble spots across all cameras on sensor.

1.0.x.x

Added.

masterConnected

bool

boolean

Master connection status.
false: if not connected
true: if connected and syncSource is Master.

20006

0 for main
1 for buddy

Gocator/MasterConnected/%u

masterStatus

bool

boolean

Duplicate of masterConnected?
false: if not connected
true: if connected and syncSource is Master.

20010

0 for main
1 for buddy

Gocator/MasterStatus/%u

syncSource

bool

boolean

Node synchronization source
1 - Master device
2 - Sensor

2043

N/A

Node/SyncSource

intTemp

k64s

integer

Controller temperature (millidegrees C).

20009

N/A

Gocator/IntTemp/%u

cpuTemp

k64s

integer

CPU temperature. (millidegress C)

20011

N/A

Gocator/CpuTemp/%u

cameraTemp0

k64s

integer

Camera board temperature (millidegrees C).

20012

N/A

Gocator/CameraTemp0/%u

cameraTemp1

k64s

integer

Camera board temperature (millidegrees C).

20013

N/A

Gocator/CameraTemp1/%u

laserDriverTemp

k64s

integer

Laser driver control temperature (millidegrees C).

2026

LightDriver/0/Temp

cameraBufferDrops0

k64u

integer

Total buffer drops for the current scan on camera 0. Value resets on scan start, not stop, so value will persist when scanning stops.

cameraBufferDrops1

k64u

integer

Total buffer drops for the current scan on camera 1. Value resets on scan start, not stop, so value will persist when scanning stops.

If the sensor has only one camera, this metric is not provided.

triggerDrops

k64u

integer

Trigger drops for the sensor.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors for the sensor

21202

N/A

Gocator/CameraErrors

memUsed

k64u

integer

Amount of memory currently used (bytes).

2003

N/A

Memory/TotalUsed

memCapacity

k64u

integer

Total amount of memory available (bytes).

2004

N/A

Memory/TotalCapacity

cpuCores

Array

array

List of CPU cores available to the sensor.

cpuCores/n

Structure

object

Single CPU core object.

cpuCores/n/used

k64u

integer

Individual CPU core utilization (percent).

2052

Cpu core index

Node/Cpu<instance>Used

cpuCoresUsedMax

k64u

integer

Max CPU core utilization (percent).

cpuCoresUsedAvg

k64u

integer

Average CPU core utilization (percent).

storageVolumes

Array

array

List of available storage volumes.

There should only ever be two:
1st (index 0) - User
2nd (index 1) - System

storageVolumes/n

Structure

object

Storage volume object.

Entry 0 is User
Entry 1 is System

storageVolumes/n/used

k64s

integer

Total amount of non-volatile storage used (bytes).

2005

0 - User
1 - System

StorageVolume/User/Used
StorageVolume/System/Used

storageVolumes/n/capacity

k64s

integer

Total amount of non-volatile storage available (bytes).

2006

0 - User
1 - System

StorageVolume/User/Capacity
StorageVolume/System/Capacity

storageVolumes/n/available

k64s

integer

Amount of non-volatile storage available (capacity - used) (bytes).

networkIfs

Array

array

List of available network interfaces.

networkIfs/n

Structure

object

Network interface object.

networkIfs/n/linkStatus

kEthernetLink

integer

Current Ethernet link status.

(0x0000) - No link, or speed unknown.
(0x0001) - 10 Mb/s, half duplex.
(0x0002) - 10 Mb/s, full duplex.
(0x0004) - 100 Mb/s, half-duplex.
(0x0008) - 100 Mb/s, full-duplex.
(0x0010) - 1000 Mb/s, half-duplex.
(0x0020) - 1000 Mb/s, full-duplex.
(0x8000) - Auto-negotiated.

2034

netInterface

NetInterface/<netInterface>/LinkStatus

networkIfs/n/linkCapacity

k64u

integer

Total available outbound network throughput (bytes/s).

2009

netInterface

NetInterface/<netInterface>/LinkCapacity

networkIfs/n/txRate

k64u

integer

Network output transmission rate (bytes/s)

2076

netInterface

NetInterface/<netInterface>/TxRate

networkIfs/n/rxRate

k64u

integer

Network output transmission rate (bytes/s)

2077

netInterface

NetInterface/<netInterface>/RxRate

networkIfs/n/txBytes

k64u

integer

Total number of bytes sent on network.

2078

netInterface

NetInterface/<netInterface>/TxBytes

networkIfs/n/rxBytes

k64u

integer

Total number of bytes received on network.

2079

netInterface

NetInterface/<netInterface>/RxBytes

storageMediumEraseTotal

k64u

integer

Total number of storage medium erases.

1.2.x.x

Added.

2093

StorageMedium/EraseTotal

storageMediumReadTotal

k64u

integer

Total number of storage medium reads.

1.2.x.x

Added.

2091

StorageMedium/ReadTotal

storageMediumWriteTotal

k64u

integer

Total number of storage medium writes.

1.2.x.x

Added.

2092

StorageMedium/WriteTotal

storageMediumBadBlocks

k64u

integer

Storage medium number of bad blocks.

1.2.x.x

Added.

3115

StorageMedium/BadBlocks

batteryRemainingCharge

k64s

integer

Remaining battery charge left in percentage multiplied by 1000

3104

N/A

Battery/RemainingCharge

batteryOperatingTime

k64s

integer

Remaining operating time for battery in hours multiplied by 1000

3105

N/A

Battery/OperatingTime

batteryStateOfHealth

k64s

integer

How much charge can the battery hold relative to when it was brand new, as a percentage multiplied by 1000

3106

N/A

Battery/StateOfHealth

batteryAlarmStatus

k64u

integer

Represents battery-related alarm status:

0 - no alarm
1 - battery low charge remaining alarm (< 10%)
2 - battery low operating time remaining alarm (< 0.5 hours)

3107

N/A

Battery/AlarmStatus

flexSpotErrors

k64u

integer

Flexible spots pipeline errors.

1.1.x.x Added

flexSpotBufferOverflows

k64u

integer

Flexible spots pipeline buffer overflow value.

1.1.x.x Added

flexSpotOverflows

k64u

integer

Flexible spots pipeline spot overflow value.

1.1.x.x Added

flexSpotPixelOverflows

k64u

integer

Flexible spots pipeline pixel overflow value.

1.1.x.x Added

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given sensor. Each sensor type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method
Description
read

Reads the latest sensor metrics.

Example: 

read /scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics

which for example returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics"
      }
    },
    "cameraBufferDrops0": 0,
    "cameraBufferDrops1": -9223372036854775808,
    "cameraTemp0": -9223372036854775808,
    "cameraTemp1": -9223372036854775808,
    "connectAttempts": 1,
    "cpuCores": [
      {
        "used": 1
      },
      {
        "used": 3
      }
    ],
    "cpuCoresUsedAvg": 2,
    "cpuCoresUsedMax": 3,
    "cpuTemp": 40259,
    "expTimeTotal": 3298,
    "intTemp": 31250,
    "laserDriverTemp": 29812,
    "laserSafety": true,
    "masterConnected": false,
    "masterStatus": false,
    "maxSpots": 1256,
    "memCapacity": 1053257728,
    "memUsed": 128603264,
    "networkIfs": [
      {
        "linkCapacity": 125000000,
        "linkStatus": 32,
        "rxBytes": 658570,
        "rxRate": 3118,
        "txBytes": 16242729,
        "txRate": 61384
      }
    ],
    "storageVolumes": [
      {
        "capacity": 251133952,
        "used": 87003136
      },
      {
        "capacity": 6762496,
        "used": 2347008
      }
    ],
    "syncSource": 2,
    "triggerDrops": 0,
    "upTime": 817
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of sensor metrics.

Example: 

stream /scan/engines/LMILaserLineProfiler/scanners/0/sensors/sensor-0/metrics
cancelStream

Cancel continuous stream of sensor metrics.

Example: 

cancelStream /scan/engines/LMILaserLineProfiler/scanners/0/sensors/sensor-0/metrics

Per online LMILaserLineProfiler Sensor:

Item Internal Type Type Description
Classic IndicatorId Classic Instance Classic Name
laserDriverTemp k64s integer Laser driver control temperature (millidegrees C).
20014 Sensor index Gocator/LaserDriverTemp/%u
maxSpots k64u integer Maximum available spots, across all cameras.

20004

N/A

Gocator/RangeDetector/MaxSpotCount

expTimeTotal k64u integer

Total running time of LMILaserLineProfiler laser light (seconds).


21201 N/A Gocator/LightOperationTimeTotal

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/sensors/(sensorId)/transform

Properties

LMILaserLineProfiler scan engine alignment transforms, containing user alignment transforms that will be applied to the sensor.

Item Type Schema Description
transform object

Transformation object, consisting of offsets and angles.

transform/xOffset number

Translation on the X axis (mm).

transform/yOffset number visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/zOffset number
Translation on the Z axis (mm).
transform/xAngle number visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/yAngle number

Rotation around the Y axis (degrees).

transform/zAngle number visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.

/scan/engines/LMILaserLineProfiler/scanners/(scannerId)/sensors/(sensorId)/actions

Resource Type: (CollectionItem)

ID: Predefined by the scan engine.

Description

A collection of sensor actions defined by the scan engine.

Methods

Method
Description
read

Returns a list of custom sensor actions as embedded resources.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
          }
        }
      }
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/shutdown"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMILaserLineProfiler/scanners/scanner-0/sensors/sensor-0/actions"
    }
  }
}

Notifications

None.


GoPxL: LMIFringeSnapshot Engine (Gocator Snapshot)

LMIFringeSnapshot scan engine documentation applies to G3xxx sensor families.

For the sake of brevity and reducing duplication, this page focuses on documenting resources and properties specific to the LMIFringeSnapshot scan engine.
See Scanner Resources for general documentation of the "/scan" resource.

/scan/engines/LMIFringeSnapshot

Resource Type: (CollectionItem)

Description

A scan engine object.

Properties

Item
Type
Schema
Description
displayName culture-specific string readOnly

Display name of the engine, e.g. "Gocator Laser Profiler".

id string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMIFringeSnapshot".
maxSensorCount integer

readOnly, minimum, used

Max sensor count.

1.0.x.x Added.

Methods

Method
Description
read

Reads a specific scan engine.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMIFringeSnapshot"
    }
  },
  "displayName": "Gocator Laser Profiler",
  "id": "LMIFringeSnapshot",
  "maxSensorCount" : 31
}

Notifications

None (as engines cannot be created or deleted directly via the protocol).

/scan/engines/LMIFringeSnapshot/visibleSensors

Resource Type: N/A

Description

Contains information about sensors discovered by a specific scan engine. All properties on this resource are read-only.

The format of this resource is identical to the format of Scanner Resources#/scan/visibleSensors except that it filters for only those sensors which are applicable to this scanEngine.

Properties

Item Type Schema Description
connectionMessage string readOnly

Describes some details about the error if the connection state is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus integer readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
engineId string readOnly Identifier of the scan engine, defined by scan engine plugin. e.g. "LMIFringeSnapshot".
isLocal bool readOnly True if the sensor is local to the application (e.g. running on the sensor). False if the sensor is remote.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
parameters object readOnly

LMIFringeSnapshot scan engine provides the following additional sensor information:

Example:

{

"parameters": {

"ipAddress": "90.35.89.3",

"optionCode": 1

}

}

parameters/ipAddress string readOnly Sensor IP address.
parameters/optionCode integer readOnly License option code.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.
version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

Methods

Method Description
read

Reads the list of visible sensors, for a specific scan engine.

Example response:

{
"sensors" : [
{
"connectionMessage" : "" ,
"connectionStatus" : 0,
"engineId" : "LMIFringeSnapshot" ,
"isLocal" : false ,
"model" : "2330" ,
"parameters" : {
"ipAddress" : "90.23.50.45" ,
"optionCode" : 1
},
"serialNumber" : "45045" ,
"version" : "1.0.0.0"
},
{
"connectionMessage" : "" ,
"connectionStatus" : 0,
"engineId" : "LMIFringeSnapshot" ,
"isLocal" : false ,
"model" : "2340" ,
"parameters" : {
"ipAddress" : "90.23.50.46" ,
"optionCode" : 1
},
"serialNumber" : "45046" ,
"version" : "1.0.0.0"
},
]
}

Notifications

Notification
updated

Occurs when the visible sensors for a specific scan engine changes. The path indicates the specific scan engine's visible sensors list.

Example notification:

{ "eventType" : "updated" , "path" : "/scan/engines/LMIFringeSnapshot/visibleSensors" }

/scan/engines/LMIFringeSnapshot/scanners

Resource Type: (Collection - Unordered)

Description

A collection of scanners under the engine.

Properties

Item Type Schema Description
creationParams ParamSet readOnly LMIFringeSnapshot scan engine required scanner creation parameters.
creationParams/defaultSerialNumber string readonly

Serial number of a sensor to add to the scanner. If 0, the scanner is created without a sensor.

Methods

Method Description
read

Reads all scanners under the engine; the list of scanners are returned as embedded items.

Example response:

{
"_embedded" : {
"item" : [
{
"_links" : {
"self" : {
"href" : "/scan/engines/LMIFringeSnapshot/scanners/scanner-0"
}
}
}
]
},
"_links" : {
"self" : {
"href" : "/scan/engines/LMIFringeSnapshot/scanners"
}
},
"creationParams" : {
"defaultSerialNumber" : 0
}
}
create

Creates a scanner resource.
NOTE: A client should read the scanners resource to see if there are creationParams that can be supplied in the create method.

Example request:

create /scan/engines/LMIFringeSnapshot/scanners { "defaultSerialNumber" : 12345 }

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)

Resource Type: (CollectionItem)

ID: Auto generated when scanners are added.

Description

A scanner object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the scanner.
id string readOnly The identifer of the scanner within the collection (e.g. "scanner-0").

parameters

object

LMIFringeSnapshot scan engine provided additional scanner information.

engineId string readOnly

The identifier of the scanner's engine

e.g. "LMIFringeSnapshot"

1.1.x.x Added.

parameterValidationMode integer enum, visibility

Experimental flag used for determining parameter validation severity to prevent getting stuck on blocking problems for default parameters

  • 0 - None
  • 1 - Potential
  • 2 - Blocking

1.2.x.x Added

Scan Mode Settings




parameters/ scanModeSettings object

LMIFringeSnapshot scan mode settings.

1.0.x.x Parameter group created

parameters/scanModeSettings/scanMode integer enum

Scan mode.

  • 0 - Image
  • 3 - Surface

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/intensityEnabled bool visibility

When this option is en abled, an intensity value will be produced for each data point.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/tempSafetyEnabled bool visibility

Temperature safety support. If one of the scanner's sensors supports temperature safety this setting will show up. Defaults to false.

1.0.x.x Moved to scanModeSettings

parameters/scanModeSettings/uniformSpacingEnabled bool visibility
When this option is enabled, data points are resampled to a uniform spacing.
1.0.x.x Moved to scanModeSettings
parameters/scanModeSettings/reduceOcclusion integer enum, visibility

Current reduced occlusion mode.

  • 0 - Disabled
  • 1 -Standard
  • 2 -High quality

1.0.x.x Moved to scanModeSettings from sensor

parameters/scanModeSettings/spacingInterval number visibility, minimum, maximum,

Current point spacing. (millimeters)

1.0.x.x Moved to scanModeSettings from sensor

Trigger Settings




parameters/triggerSettings

object

LMIFringeSnapshot trigger parameters.

1.0.x.x Renamed to triggerSettings

parameters/triggerSettings/source integer enum

Trigger source.

  • 0 - Time
  • 2 - Digital input
  • 3 - Software
parameters/triggerSettings/maxFrameRateEnabled bool visibility Trigger at maximum frame rate.
parameters/triggerSettings/frameRate number minimum, maximum, actual, visibility Frame rate for time trigger (Hz).
parameters/triggerSettings/delay number minimum, maximum, visibility Trigger delay. (s)

Filter Settings




parameters/f ilters object

1.0.x.x Added.

parameters/f ilters/ gapFilling object
Gap filling filter
parameters/f ilters/ gapFilling/enableX bool
Enable gap filling along X axis.
parameters/f ilters/ gapFilling/winX number minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ gapFilling/enableY bool visibility Enable gap filling along Y axis; applies in surface mode only.
parameters/f ilters/ gapFilling/winY number minimum, maximum,visibility, actual

Y window size (mm); applies in surface mode only.

1.2.x.x Actual schema added.

parameters/f ilters/ median object
Median filter
parameters/f ilters/ median/enableX bool
Enable median filtering along X axis.
parameters/f ilters/ median/winX number minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ median/enableY bool visibility Enable median filtering along Y axis.
parameters/f ilters/ median/winY number minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ smoothing object
Smoothing filter
parameters/f ilters/ smoothing/enableX bool
Enable smoothing along X axis.
parameters/f ilters/ smoothing/winX number minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ smoothing/enableY bool visibility Enable smoothing along Y axis.
parameters/f ilters/ smoothing/winY number minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ decimation object
Decimation filter
parameters/f ilters/ decimation/enableX bool
Enable decimation along X axis.
parameters/f ilters/ decimation/winX number minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/f ilters/ decimation/enableY bool visibility Enable decimation along Y axis.
parameters/f ilters/ decimation/winY number minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/commands/align

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Aligns the scanner according to configurations defined in the /alignment resource.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

parameters

object

read-only

parameters/interactive

boolean

Indicates if the alignment operation requires interaction from the user or not.

Call Command Arguments

Item

Type

Mandatory or Optional

Description

interactive

boolean

Optional

Default value: false.

If true, the scanner will attempt to align interactively & request user parameters.
If false, alignment will run on its own without any additional inputs.

Scanners may choose not to implement interactive alignment, in which case this parameter should be ignored.

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command.

The value of parameters are equal to their default values.

Example Response: 

{
  "payload": {
    "id": "align",
    "parameters": {
      "interactive": false
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/align"
      }
    }
  },
  "path": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/align",
  "type": "response",
  "status": 1
}
call

Aligns the scanner. The response to calling this resource may be returned immediately, even if if alignment has not completed. In this case, clients can check for alignment completion by checking alignState on the parent scanner resource. More specific behavior information can be found within the scan engine specific documentation.

Example request: 

call /scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/align {"interactive":false}

Notifications

None.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/commands/cancelAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Cancels running scanner alignment. If alignment is not running, this command does nothing.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

Call Command Arguments

None

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command.

Example Response: 

{
  "payload": {
    "id": "cancelAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/cancelAlign"
      }
    }
  },
  "path": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/cancelAlign",
  "type": "response",
  "status": 1
}
call

Cancels scanner alignment.

Example request 

call /scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/cancelAlign

Notifications

None.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/commands/clearAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands

Description

Clears existing alignment. If alignment is running, then the alignment operation is cancelled first, then the existing alignment is cleared.

Methods

Method Description
read

Returns the command's name and the list of parameters, if any, supported by this command. 

{
  "payload": {
    "id": "clearAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/clearAlign"
      }
    }
  },
  "path": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/clearAlign",
  "type": "response",
  "status": 1
}
call

Clears scanner alignment.

Example request 

call /scan/engines/LMIFringeSnapshot/scanners/scanner-0/commands/clearAlign

Notifications

None.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/metrics

For metrics common across all Gocator scanners:

Scanner-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a scanner for a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see their specific resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

speed

k64f

number

Current trigger rate (Hz). If scanner is not running, this metric is omitted.

20001

N/A

"Gocator/Current Sensor Speed"

maxSpeed

k64f

number

Maximum theoretical trigger rate (Hz); Note this does not consider CPU load from data processing and output. This should match the value specified in the scanner parameters at Standard Scanner Resources#Trigger(Propertygroup) .

20002

N/A

"Gocator/Maximum Speed"

scanCount

k64u

integer

Number of scanned outputs for the given mode:

  • i.e. Number of profiles in profile mode

  • i.e. Number of surfaces in surface mode

  • i.e. Number of video outputs in video mode


0 if sensor is not running.

Note this number may differ slightly from actual number of profiles/surfaces/video messages received and processed.

20005

N/A

"Gocator/Scan Count"

frameCount

k64u

integer

Number of frames output.

This will be the same as the number of camera frames obtained.

1.0.x.x Added

scannerDrops

k64u

integer

Total drops across all sensor cameras & projectors that don't fall under trigger drops. Value resets on scan start, not stop, so value will persist when scanning stops.

0.3.x.x

Added

triggerDrops

k64u

integer

Total trigger drops across all sensors.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors across all sensors.

21202

N/A

Gocator/CameraErrors

processingLatency

k64u

integer

Processing latency (microseconds) for the last frame from this scanner.

Resets when a new scan is started.

21001

N/A

Gocator/Processing Latency

processingLatencyMax

k64u

integer

Highest processing latency(microseconds) from the entire scan.

Resets when a new scan is started.

21002

N/A

Gocator/Processing Latency Max

processingLatencyAvg

k64u

integer

Simple moving average of processing latency(microsecond) for the last 50 samples collected.

Resets when a new scan is started.

N/A

N/A

N/A

encoderValue

k64s

integer

Current scanner encoder tick.

1003

N/A

Node/EncoderValue

encoderFreq

k64s

integer

Current scanner encoder frequency (ticks/s). The sign of this metric serves as an indicator of the direction in which motion is occurring. A positive value denotes movement in a forward direction, whereas a negative value signifies movement in a backward or reverse direction.

1005

N/A

Node/EncoderFrequency

currentSyncTime

64u

Current value of the clock used to generate the time stamp for a scan data message.

N/A

N/A

laserEnabled

bool

boolean

This metric is an aggregate of the laser enabled status of all sensors managed by the scanner.

0: all sensors' laser is disabled (laser cannot be turned on)
1: one or more sensors' laser is enabled (laser can be turned on)

Derived from the sensor laserSafety health indicator.

Scanner metric aggregates the laserSafety setting from all online sensors. Only if all the online sensors' laserSafety value is 0 (ie. all the online sensors' lasers cannot be turned on), is the scanner level laserEnabled value set to 0. If any online sensor can potentially be turned on, then the scanner level laserEnabled is set to 1, as a cautionary warning to the user.

This scanner metric is named "laserEnabled" instead of "laserSafety", even though it is based on the sensor Node/laserSafety metric, is because "laserEnabled" more accurately describes the value of this metric.

N/A

N/A

advanced/overSpeedJitterCount

k64u

integer

Number of times speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

advanced/overSpeedJitterMax

k64f

number

Maximum amount that speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given scanner. Each scanner type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method
Description
read

Reads the latest scanner metrics.

Example: 

read /scan/engines/LMIFringeSnapshot/scanners/scanner-0/metrics

which for example, returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/metrics"
      }
    },
    "advanced": {
      "overSpeedJitterCount": -9223372036854775808,
      "overSpeedJitterMax": -1.7976931348623157e+308
    },
    "encoderFreq": 0,
    "encoderValue": 0,
    "g2Scanner": {},
    "maxSpeed": 208.55397148676172,
    "scanCount": -9223372036854775808,
    "scannerDrops": 0,
    "speed": -1.7976931348623157e+308,
    "triggerDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of scanner metrics.

Example: 

stream /scan/engines/LMIFringeSnapshot/scanners/scanner-0/metrics
cancelStream

Cancel continuous stream of scanner metrics.

Example: 

cancelStream /scan/engines/LMIFringeSnapshot/scanners/scanner-0/metrics

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/outputs

Resource Type: (Collection - Unordered)

Description

A collection of scanner outputs.

Methods

Method
Description
read

Returns the list of scanner outputsas embedded resources.

Example response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs/sensor-0:profile"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs/top:profile"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs"
      }
    }
  },
  "status": 1,
  "type": "response"
}

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/outputs/(outputId)

Resource Type: (Collection - Unordered)

Description

A scanner output object in the scanner outputs collection

Properties

Item Type Schema Dscription

dataFormat

DatFormat

readOnly

data format of the output

dataSourceId

string

readOnly

The data source id.

e.g. "scan:LMIFringeSnapshot:scanner-0:sensor-0UniformSurface"

displayName

culture-specific string


User configurable display name of the scanner output.

enabled

bool


Whether the scanner output is enabled or not.

id

string

readOnly

The identifer of the scanner output

recordingEnabled

bool


Whether the output should be recorded or not.

priority

integer

readOnly

Priority of the scanner output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

0.3.x.x Added

Methods

Method
Description
read

Returns properties of the corresponding scanner output

Example response: 

{
  "payload": {
	"dataFormat": {
	  "arrayed": false,
	  "type": 14
	},
	"dataSourceId": "scan:LMIFringeSnapshot:scanner-0:sensor-0UniformSurface",
	"displayName": "Uniform",
	"enabled": true,
	"id": "sensor-0UniformSurface",
	"priority": 0,
	"recordingEnabled": true,
	"_links": {
	  "self": {
	    "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs/sensor-0UniformSurface"
	  }
	}
  },
  "path": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/outputs/sensor-0UniformSurface",
  "type": "response",
  "status": 1
}

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/alignment

Properties

LMIFringeSnapshot scan engine-specific alignment configuration, containing user alignment configurations that will be applied to the alignment process.

Item Type Schema Description
alignConfig/timeout integer

Maximum time non-interactive alignment can take. If this time is exceeded, alignment will be aborted.

If alignment is run interactively, timeout is infinite.

1.0.x.x Added.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/transform

Scan engine-specific alignment transforms, containing user alignment transforms that will be applied to the scanner.

Item Type Schema Description
encoderResolution number exclusiveMinimum

Encoder resoluti on for encoder-based triggering (mm/tick).

Note: not used by LMIFringeSnapshot .

speed number exclusiveMinimum

Travel Speed of the sensor used in time mode (mm/s).

Note: not used by LMIFringeSnapshot .

transform object visibility

Transformation object, consisting of offsets and angles.

1.0.x.x Reserved for future.

transform/xOffset number

Translation on the X axis (mm).

transform/yOffset number visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/zOffset number
Translation on the Z axis (mm).
transform/xAngle number visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/yAngle number

Rotation around the Y axis (degrees).

transform/zAngle number visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/system

Scanner persistent parameters group.

A group root for storing autosaved persistent scanner parameters. (Does not affect jobs.)

1.1.x.x

Parameters: none

Outputs: none

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/actions

Resource Type: (CollectionItem)

Description

A collection of scanner actions defined by the scan engine.

Methods

Method

Description

read

Returns a list of custom scanner actions as embedded resources.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/engineId/scanners/scannerId/actions/sampleAction"
          }
        }
      }
    ]
  },

    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/engineId/scanners/scannerId/actions"
    }
  }
}

Notifications

None.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/actions/trigger

Resource Type: (CollectionItem , Callable)

ID: Predefined by scan engine.

Description

Software trigger.

Properties

None.

Methods

Method
Description
read

Reads the software trigger.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions/trigger

Example response: 

{
  "payload": {
    "id": "trigger",
    "message": "",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/actions/trigger"
      }
    }
  },
  "path": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/actions/trigger",
  "type": "response",
  "status": 1
}
call

Calls the software trigger.

Example request: 

call /scan/engines/engineId/scanners/scannerId/actions/trigger

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors

Resource Type: (Collection - Unordered)

Description

A collection of sensors under the scanner.

Properties

Item Type Schema Description

creationParams

ParamSet readonly

LMIFringeSnapshot scan engine required sensor creation parameters.

creationParams/serialNumber string readonly

Serial number of a sensor to add to the scanner.

Methods

Method Description
read

Reads all sensors under the scanner; the list of sensors are returned as embedded items.

{
"_embedded" : {
"item" : [
{
"_links" : {
"self" : {
"href" : "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0"
}
}
},
{
"_links" : {
"self" : {
"href" : "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-1"
}
}
}
] },
"_links" : {
"self" : {
"href" : "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors"
}
},
"creationParams" : {
"serialNumber" : 0
}
},
}
create

Method Trait: ( NoRestart ) System will not be restarted when adding sensors. This applies if a scanner already has sensors and is already running. After the addition of a sensor to the scanner, the system will remain in stopped state.

Creates a sensor resource underneath the scanner.
NOTE: A client should read the sensors resource to see if there are creationParams that can be supplied in the create method.

Example request:

create /scan/engines/LMIFringeSnapshot/scanners/scanner- 0 /sensors { "serialNumber" : 12345 }

Notifications

None.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)

Resource Type: (CollectionItem)

ID: Auto generated when sensors are added.

Description

A sensor object.

Properties

Item Type Schema Description
displayName culture-specific string
User configurable display name of the sensor.
id
readOnly Identifier of the sensor within the collection (e.g. "sensor-0").
connectionMessage string readOnly

Describes some details about the error if the connection status is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus integer readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.
  • 1 - Sensor is connecting.
  • 2 - Sensor is connected.
  • 3 - Sensor is already connected to another application.
  • -1 - Sensor is not connectable.
  • -2 - Sensor is offline.
model string readOnly Model of the sensor. Can be empty if the scan engine does not support discovering the model.
serialNumber string readOnly A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.
version string readOnly Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.

parameters

object

LMIFringeSnapshot scan engine provided additional sensor information.

parameters/laserSafetyLock bool visibility

Laser safety lock state for the sensor.

0 - laser safety lock is off.

1 -laser safety lock is on.

For sensor that support this, can also change the state by updating this parameter to the desired state. Currently, only battery powered sensors support this.

1.2.x.x Added.

parameters/powerSaveMode bool readOnly, visibility

Power save mode for the sensor.

0 - power save mode is off.

1 -power save mode is on.

For sensor that support this, changing the state of this parameter will update the state. Mainly useful for battery powered sensors.

1.2.x.x Added.

parameters/firstCameraAlgorithm integer readOnly, visibility

Internal parameter used to indicate the algorithm setting of the first camera for
generating sensor outputs.

1.2.x.x

Active Area settings


parameters/activeAreaSettings object extendedType

extendedType = TransformedBoxRegion

1.0.x.x Renamed toactiveAreaSettings

parameters/activeAreaSettings/x number minimum, maximum, readOnly

X center (mm). The limits of X (ie minimum and maximum) vary according to the current Width. As Width increases, the freedom of motion for X decreases.

parameters/activeAreaSettings/y number minimum, maximum, readOnly

Ycenter (mm). The limits of Y (ie minimum and maximum) vary according to the current Length. AsLength increases, the freedom of motion for Y decreases.

Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

parameters/activeAreaSettings/z number minimum, maximum, readOnly

Zcenter (mm).

parameters/activeAreaSettings/width number minimum, maximum, readOnly

X extent (mm).

1.0.x.x Added readOnly.

parameters/activeAreaSettings/length number minimum, maximum, readOnly

Y extent (mm). Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

parameters/activeAreaSettings/height number minimum, maximum, readOnly

Z extent (mm).

1.0.x.x Added readOnly.

parameters/activeAreaSettings/transformMatrix array<number> visibility, readOnly The transformMatrix should not be rendered in UI clients because used=false, but its contents can toggle between being invalid (empty matrix, usually in Image scan mode) or having values (profile and surface modes).

Exposure Settings




parameters/exposureSettings object

1.0.x.x LMIFringeSnapshot Exposure settings

1.0.x.x Renamed toexposureSettings

parameters/exposureSettings/exposureMode integer enum, readOnly

Exposure mode.

  • 0 - Single exposure
  • 1 -Multipleexposure
parameters/exposureSettings/intensitySequenceIndex integer minimum, maximum, readOnly, visibility

Multiple exposure intensity index.

Specifies which exposure in the parameters/ exposureSettings/ multipleExposures array to be used as an intensity image.

parameters/ exposureSettings/ intensityType integer enum, readOnly, visibility

Intensity type, by default combine left and right camera intensity images.

  • 0 - Auto(combine both camera intensity images)
  • 1 - Left camera(left camera intensity image)
  • 2 - Right camera (right camera intensity image)
parameters/ exposureSettings / videoPatternType
readOnly, visibility

Specifies a preview pattern during live view image capturing (parameters/scanMode = image mode).

  • 0 -Default (white light)
  • 3 - Scan Sequence (use one of the scan patterns specified by parameters/ videoPatternIndex)
  • 4 -Projector Off (no light, black)
parameters/ exposureSettings / videoPatternIndex integer minimum, maximum, readOnly, visibility

Specifies which scan pattern to use when parameters/ exposureSettings/ videoPatternType = 3 (Scan Sequence)

parameters /exposureSettings /singleExposure number

minimum, maximum, readOnly, visibility, scale

Exposure value (microseconds).

parameters /exposureSettings /multipleExposures array<number>

minItems, maxItems,

minimum, maximum, visibility, readOnly

This contains a list of exposure values to use whenparameters/exposureMode = 1 (Multiple Exposures).

(microseconds).

Advanced Settings




parameters/ advancedSettings object

LMIFringeSnapshot advanced settings.

1.0.x.x Renamed toadvancedSettings

parameters/advancedSettings/ contrastThreshold integer minimum, maximum, readOnly

Specifies minimal color difference to consider the pixel (point) valid for decoding and triangulation.

  • Default = 10 point intensity should vary by at least 10 counts [0, 255]
  • Min = 1
  • Max = 50
parameters/advancedSettings/materialType integer enum, readOnly

Material type, changes projector patterns and pattern decoding scheme:

  • 1 - Diffuse
  • 3 -Interreflective

parameters /advancedSettings /plSupportedEncoding

bool visibility, read-only

Flag determining if the current encoding (Diffuse, Interreflective) is supported by sensor hardware.

parameters/advancedSettings/materialType - determines current encoding type.

If encoding is not supported, the sensor will perform a software emulation which is much slower.

This is an information property. As such, it is designed to be read only.

1.0.x.x Added.

Advanced Camera Settings




parameters/advancedSettings/cameraSettings/

cameras 		array<object>

LMIFringeSnapshot has two camera objects; analogGain does not apply.

1.0.x.x Moved to advancedSettings

parameters/advancedSettings/cameraSettings/

cameras/ analogGain 		number minimum, maximum, readOnly, actual Analog gain. Not applicable to LMIFringeSnapshot sensors.

parameters/advancedSettings/cameraSettings/

cameras/ digitalGain 		number minimum, maximum, readOnly, actual Digital gain.

parameters/advancedSettings/cameraSettings/

cameras/ gammaType 		integer enum, readOnly, actual, visibility

Gamma type.

  • 0 - None
  • 1 - Low
  • 2 - Medium
  • 3 - High
parameters/advancedSettings/cameraSettings/leftCameraIndex integer minimum, readOnly, visibility Index of the left camera.
parameters/advancedSettings/cameraSettings/rightCameraIndex integer minimum, readOnly, visibility Index of the right camera.

Advanced Projector Settings




parameters/ advancedSettings/ projectorSettings object

LMIFringeSnapshot projector parameters.

1.0.x.x Moved to advancedSettings

parameters/ advancedSettings/ projectorSettings/ intensity number minimum, maximum, readOnly

Current projector intensity in percentages (%).

(The min/max of intensity is usually [0,100]%).

1.0.x.x Updated to use %.

parameters/ advancedSettings/ projectorSettings/ uniformity number minimum, maximum, readOnly

Pattern uniformity coefficient. Balances center and sides of the projected image by lowering center intensity.

  • Default = 1.0 no effect.
  • Min = 0.01 minimal center intensity
  • Max = 1.0 full center intensity

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)/system

Resource Type: (CollectionItem)

ID: Auto generated when sensors are added.

Description

Sensor persistent parameters group.A group root for storing autosaved persistent sensor parameters. (Does not affect jobs.)

Properties

Item Type Schema Description 
powerSettings
 object

LMIFringeSnapshot power supply parameters.

1.1.x.x 

powerSettings/voltage
 integer enum, readOnly, visibility

Power supply voltage settings.

  • 0 - 48 Volt
  • 3 - 24 Volt

1.1.x.x 

powerSettings/cableLength
 number

minimum, maximum, readOnly, visibility

Sensor power cable length.

  • Default = 5.0 meters
  • Min = 0.0 meters
  • Max = 25.0 meters (This can vary depending on sensor model)

1.1.x.x

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)/metrics

For metrics common across all Gocator sensors:

Sensor-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see its resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

While sensor either connected or disconnected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

connectAttempts

k64s

integer

Number of retry attempts to connect to sensor.
See connection state within Resource Reference#/scan/(engineId)/visibleSensors .

N/A

Once sensor is connected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

upTime

k64u

integer

Time elapsed since node boot-up or reset (seconds).

2017

N/A

Node/UpTime

bootCount

k64s

integer

Number of boot-ups.

2086

Node/BootCount

laserSafety

bool

boolean

Laser safety status.

Values have the following meaning:

0: laser is disabled (laser cannot be turned on)
1: laser is enabled (laser can be turned on)

1010

N/A

Node/LightSafety

expTimeTotal

k64u

integer

Total time the laser has been on since first use. (seconds)

1.0.x.x

Added

maxSpots

k64u

integer

Maximum avaialble spots across all cameras on sensor.

1.0.x.x

Added.

masterConnected

bool

boolean

Master connection status.
false: if not connected
true: if connected and syncSource is Master.

20006

0 for main
1 for buddy

Gocator/MasterConnected/%u

masterStatus

bool

boolean

Duplicate of masterConnected?
false: if not connected
true: if connected and syncSource is Master.

20010

0 for main
1 for buddy

Gocator/MasterStatus/%u

syncSource

bool

boolean

Node synchronization source
1 - Master device
2 - Sensor

2043

N/A

Node/SyncSource

intTemp

k64s

integer

Controller temperature (millidegrees C).

20009

N/A

Gocator/IntTemp/%u

cpuTemp

k64s

integer

CPU temperature. (millidegress C)

20011

N/A

Gocator/CpuTemp/%u

cameraTemp0

k64s

integer

Camera board temperature (millidegrees C).

20012

N/A

Gocator/CameraTemp0/%u

cameraTemp1

k64s

integer

Camera board temperature (millidegrees C).

20013

N/A

Gocator/CameraTemp1/%u

laserDriverTemp

k64s

integer

Laser driver control temperature (millidegrees C).

2026

LightDriver/0/Temp

cameraBufferDrops0

k64u

integer

Total buffer drops for the current scan on camera 0. Value resets on scan start, not stop, so value will persist when scanning stops.

cameraBufferDrops1

k64u

integer

Total buffer drops for the current scan on camera 1. Value resets on scan start, not stop, so value will persist when scanning stops.

If the sensor has only one camera, this metric is not provided.

triggerDrops

k64u

integer

Trigger drops for the sensor.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors for the sensor

21202

N/A

Gocator/CameraErrors

memUsed

k64u

integer

Amount of memory currently used (bytes).

2003

N/A

Memory/TotalUsed

memCapacity

k64u

integer

Total amount of memory available (bytes).

2004

N/A

Memory/TotalCapacity

cpuCores

Array

array

List of CPU cores available to the sensor.

cpuCores/n

Structure

object

Single CPU core object.

cpuCores/n/used

k64u

integer

Individual CPU core utilization (percent).

2052

Cpu core index

Node/Cpu<instance>Used

cpuCoresUsedMax

k64u

integer

Max CPU core utilization (percent).

cpuCoresUsedAvg

k64u

integer

Average CPU core utilization (percent).

storageVolumes

Array

array

List of available storage volumes.

There should only ever be two:
1st (index 0) - User
2nd (index 1) - System

storageVolumes/n

Structure

object

Storage volume object.

Entry 0 is User
Entry 1 is System

storageVolumes/n/used

k64s

integer

Total amount of non-volatile storage used (bytes).

2005

0 - User
1 - System

StorageVolume/User/Used
StorageVolume/System/Used

storageVolumes/n/capacity

k64s

integer

Total amount of non-volatile storage available (bytes).

2006

0 - User
1 - System

StorageVolume/User/Capacity
StorageVolume/System/Capacity

storageVolumes/n/available

k64s

integer

Amount of non-volatile storage available (capacity - used) (bytes).

networkIfs

Array

array

List of available network interfaces.

networkIfs/n

Structure

object

Network interface object.

networkIfs/n/linkStatus

kEthernetLink

integer

Current Ethernet link status.

(0x0000) - No link, or speed unknown.
(0x0001) - 10 Mb/s, half duplex.
(0x0002) - 10 Mb/s, full duplex.
(0x0004) - 100 Mb/s, half-duplex.
(0x0008) - 100 Mb/s, full-duplex.
(0x0010) - 1000 Mb/s, half-duplex.
(0x0020) - 1000 Mb/s, full-duplex.
(0x8000) - Auto-negotiated.

2034

netInterface

NetInterface/<netInterface>/LinkStatus

networkIfs/n/linkCapacity

k64u

integer

Total available outbound network throughput (bytes/s).

2009

netInterface

NetInterface/<netInterface>/LinkCapacity

networkIfs/n/txRate

k64u

integer

Network output transmission rate (bytes/s)

2076

netInterface

NetInterface/<netInterface>/TxRate

networkIfs/n/rxRate

k64u

integer

Network output transmission rate (bytes/s)

2077

netInterface

NetInterface/<netInterface>/RxRate

networkIfs/n/txBytes

k64u

integer

Total number of bytes sent on network.

2078

netInterface

NetInterface/<netInterface>/TxBytes

networkIfs/n/rxBytes

k64u

integer

Total number of bytes received on network.

2079

netInterface

NetInterface/<netInterface>/RxBytes

storageMediumEraseTotal

k64u

integer

Total number of storage medium erases.

1.2.x.x

Added.

2093

StorageMedium/EraseTotal

storageMediumReadTotal

k64u

integer

Total number of storage medium reads.

1.2.x.x

Added.

2091

StorageMedium/ReadTotal

storageMediumWriteTotal

k64u

integer

Total number of storage medium writes.

1.2.x.x

Added.

2092

StorageMedium/WriteTotal

storageMediumBadBlocks

k64u

integer

Storage medium number of bad blocks.

1.2.x.x

Added.

3115

StorageMedium/BadBlocks

batteryRemainingCharge

k64s

integer

Remaining battery charge left in percentage multiplied by 1000

3104

N/A

Battery/RemainingCharge

batteryOperatingTime

k64s

integer

Remaining operating time for battery in hours multiplied by 1000

3105

N/A

Battery/OperatingTime

batteryStateOfHealth

k64s

integer

How much charge can the battery hold relative to when it was brand new, as a percentage multiplied by 1000

3106

N/A

Battery/StateOfHealth

batteryAlarmStatus

k64u

integer

Represents battery-related alarm status:

0 - no alarm
1 - battery low charge remaining alarm (< 10%)
2 - battery low operating time remaining alarm (< 0.5 hours)

3107

N/A

Battery/AlarmStatus

flexSpotErrors

k64u

integer

Flexible spots pipeline errors.

1.1.x.x Added

flexSpotBufferOverflows

k64u

integer

Flexible spots pipeline buffer overflow value.

1.1.x.x Added

flexSpotOverflows

k64u

integer

Flexible spots pipeline spot overflow value.

1.1.x.x Added

flexSpotPixelOverflows

k64u

integer

Flexible spots pipeline pixel overflow value.

1.1.x.x Added

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given sensor. Each sensor type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method
Description
read

Reads the latest sensor metrics.

Example: 

read /scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/metrics

which for example returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/metrics"
      }
    },
    "cameraBufferDrops0": 0,
    "cameraBufferDrops1": -9223372036854775808,
    "cameraTemp0": -9223372036854775808,
    "cameraTemp1": -9223372036854775808,
    "connectAttempts": 1,
    "cpuCores": [
      {
        "used": 1
      },
      {
        "used": 3
      }
    ],
    "cpuCoresUsedAvg": 2,
    "cpuCoresUsedMax": 3,
    "cpuTemp": 40259,
    "expTimeTotal": 3298,
    "intTemp": 31250,
    "laserDriverTemp": 29812,
    "laserSafety": true,
    "masterConnected": false,
    "masterStatus": false,
    "maxSpots": 1256,
    "memCapacity": 1053257728,
    "memUsed": 128603264,
    "networkIfs": [
      {
        "linkCapacity": 125000000,
        "linkStatus": 32,
        "rxBytes": 658570,
        "rxRate": 3118,
        "txBytes": 16242729,
        "txRate": 61384
      }
    ],
    "storageVolumes": [
      {
        "capacity": 251133952,
        "used": 87003136
      },
      {
        "capacity": 6762496,
        "used": 2347008
      }
    ],
    "syncSource": 2,
    "triggerDrops": 0,
    "upTime": 817
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of sensor metrics.

Example: 

stream /scan/engines/LMIFringeSnapshot/scanners/0/sensors/sensor-0/metrics
cancelStream

Cancel continuous stream of sensor metrics.

Example: 

cancelStream /scan/engines/LMIFringeSnapshot/scanners/0/sensors/sensor-0/metrics

Per online LMIFringeSnapshot Sensor:

Item Internal Type Type Description

expTimeTotal

k64s integer

Total projector exposure time (seconds).

(In Gocator 6.x: Light Operation Time, ID: 21201)

1.0.x.x Added.

projectorTempPanel

k64s integer

Projector filter array temperature (millidegrees C).

1.0.x.x Added.

projectorTempLight

k64s integer

Projector illumination temperature (millidegrees C).

1.0.x.x Added.

projectorTempLightWarning bool bool

Warning state (true/false) of the Light.

1.1.x.x Added.

projectorTempPanelWarning bool bool

Warning state (true/false) of the Panel.

1.1.x.x Added.

projectorTempLightError bool bool

Error state (true/false) of the Light.

1.1.x.x Added.

projectorTempPanelError bool bool

Error state (true/false) of the Panel.

1.1.x.x Added.

projectorTempOverheatDuration k64u integer

The duration the projector has spent in an error (overheated) state (microseconds).

1.1.x.x Added.

/scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)/actions

Resource Type: (CollectionItem)

ID: Predefined by the scan engine.

Description

A collection of sensor actions defined by the scan engine.

Methods

Method
Description
read

Returns a list of custom sensor actions as embedded resources.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
          }
        }
      }
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/actions/shutdown"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMIFringeSnapshot/scanners/scanner-0/sensors/sensor-0/actions"
    }
  }
}

Notifications

None.



GoPxL: LMIConfocalLineProfiler Engine (Gocator Confocal Profiler)

LMIConfocalLineProfiler scan engine documentation applies to G4xxx and G5xxx sensor families.

For the sake of brevity and reducing duplication, this page focuses on documenting resources and properties specific to the LMIConfocalLineProfiler scan engine.
See Scanner Resources for general documentation of the "/scan" resource.

/scan/engines/LMIConfocalLineProfiler

Resource Type: (CollectionItem)

Description

A scan engine object.

Properties

Item

Type

Schema

Description

displayName

culture-specific string

readOnly

Display name of the engine, e.g. "Gocator Laser Profiler".

id

string

readOnly

Identifier of the scan engine, defined by scan engine plugin. e.g. "LMIConfocalLineProfiler".

maxSensorCount

integer

readOnly, minimum, used

Max sensor count.

1.0.x.x Added.

Methods

Method

Description

read

Reads a specific scan engine.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMIConfocalLineProfiler"
    }
  },
  "displayName": "Gocator Laser Profiler",
  "id": "LMIConfocalLineProfiler",
  "maxSensorCount" : 31
}

Notifications

None (as engines cannot be created or deleted directly via the protocol).

/scan/engines/LMIConfocalLineProfiler/visibleSensors

Resource Type: N/A

Description

Contains information about sensors discovered by a specific scan engine. All properties on this resource are read-only.

The format of this resource is identical to the format of Scanner Resources#/scan/visibleSensors except that it filters for only those sensors which are applicable to this scanEngine.

Properties


Item

Type

Schema

Description

connectionMessage

string

readOnly

Describes some details about the error if the connection state is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus

integer

readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.

  • 1 - Sensor is connecting.

  • 2 - Sensor is connected.

  • 3 - Sensor is already connected to another application.

  • -1 - Sensor is not connectable.

  • -2 - Sensor is offline.

engineId

string

readOnly

Identifier of the scan engine, defined by scan engine plugin. e.g. "LMIConfocalLineProfiler".

isLocal

bool

readOnly

True if the sensor is local to the application (e.g. running on the sensor). False if the sensor is remote.

model

string

readOnly

Model of the sensor. Can be empty if the scan engine does not support discovering the model.

parameters

object

readOnly

LMIConfocalLineProfiler scan engine provided additional sensor information.

Example:

{ "parameters": { "ipAddress": "90.55.52.68", "optionCode": 1 } }


parameters/ipAddress

string

readOnly

Sensor IP address.

parameters/optionCode

integer

readOnly

License option code.

serialNumber

string

readOnly

A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.

version

string

readOnly

Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.


Methods


Method

Description

read

Reads the list of visible sensors, for a specific scan engine.

Example response:


{

"sensors": [

{

"connectionMessage":"",

"connectionStatus": 0,

"engineId":"LMIConfocalLineProfiler",

"isLocal":false,

"model":"2330",

"parameters": {

"ipAddress":"90.23.50.45",

"optionCode": 1

},

"serialNumber":"45045",

"version":"1.0.0.0"

},

{

"connectionMessage":"",

"connectionStatus": 0,

"engineId":"LMIConfocalLineProfiler",

"isLocal":false,

"model":"2340",

"parameters": {

"ipAddress":"90.23.50.46",

"optionCode": 1

},

"serialNumber":"45046",

"version":"1.0.0.0"

},

]

}



Notifications


Notification


updated

Occurs when the visible sensors for a specific scan engine changes. The path indicates the specific scan engine's visible sensors list.

Example notification:


{"eventType" :"updated","path" :"/scan/engines/LMIConfocalLineProfiler/visibleSensors" }




/scan/engines/LMIConfocalLineProfiler/scanners

Resource Type: (Collection - Unordered)

Description

A collection of scanners under the engine.

Properties


Item

Type

Schema

Description

creationParams

object

readOnly

LMIConfocalLineProfiler scan engine required scanner creation parameters.

creationParams/defaultSerialNumber

string

readOnly

Serial number of a sensor to add to the scanner. If 0, the scanner is created without a sensor.


Methods


Method

Description

read

Reads all scanners under the engine; the list of scanners are returned as embedded items.

Example response:


{

"_embedded": {

"item": [

{

"_links": {

"self": {

"href":"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0"

}

}

}

]

},

"_links": {

"self": {

"href":"/scan/engines/LMIConfocalLineProfiler/scanners"

}

},

"creationParams": {

"defaultSerialNumber": 0

}

}


create

Creates a scanner resource.
NOTE: A client should read the scanners resource to see if there are creationParams that can be supplied in the create method.

Example request:


create /scan/engines/LMIConfocalLineProfiler/scanners {"defaultSerialNumber":12345}



Notifications


Event Type

Description

created

Occurs when a new scanner is added. The path indicates the new scanner id.

Example notification:


{"eventType" :"created","path" :"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0"}


updated

Occurs when a scanner's properties change. The path indicates the affected scanner id.

Example notification:


{"eventType" :"updated","path" :"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0" }


deleted

Occurs when a scanner is deleted. The path indicates the scanner id that was deleted.

Example notification:


{"eventType" :"deleted","path" :"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0" }



/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)

Resource Type: (CollectionItem)

ID: Auto generated when scanners are added.

Description

A scanner object.

Properties

Item

Type

Schema

Description

displayName

culture-specific string


User configurable display name of the scanner.

id

string

readOnly

The identifer of the scanner within the collection (e.g. "scanner-0").

parameters

object


LMIConfocalLineProfiler scan engine provided additional scanner information.

parameters/firstCameraAlgorithm

integer

visibility, readOnly

Internal flag to indicate the current algorithm set for the first camera.

1.2.25.157 Added.

parameters/family

integer

readOnly, used

Sensor family.

  • 5 - G5 (Gocator confocal profiler)

1.0.x.x Removed .

parameters/runningState

integer

readOnly, used

Run state.

  • 0 - Ready

  • 1 - Running

  • 2 - Error

1.0.x.x Removed.

parameters/maxSensorCount

integer

minimum, readOnly, used

Max sensor count.

0.3.x.x Supported maxSensorCount is 2.

1.0.x.x Moved to Scanner Resources#/scan/engines/(engineId) .

parameterValidationMode

integer

enum, visibility

Experimental flag used for determining parameter validation severity to prevent getting stuck on blocking problems for default parameters

  • 0 - None

  • 1 - Potential

  • 2 - Blocking

1.2.27.79 Added





parameters/scanModeSettings

object


LMIConfocalLineProfiler scan mode settings.

1.0.x.x Parameter group created

parameters/scanModeSettings/scanMode

integer

enum

The scan mode. Determines the primary data produced by the scanner.

  • 0 - Image

  • 2 - Profile

  • 3 - Surface

1.0.x.x Moved to scanModeSettings

parameters /scanModeSettings /intensityEnabled

bool

visibility

When this option is enabled, anintensityvalue w ill be produced for each data point.

parameters /scanModeSettings /uniformSpacingEnabled

bool

visibility

When this option is enabled, data points are resampled to a uniform spacing.

parameters /scanModeSettings /arrayedOutputs

bool

visibility

Combine top and bottom sensor outputs to array.

0.3.x.x Added

1.0.x.x Parameter renamed

parameters /scanModeSettings /individualLayersEnabled

bool

visibility

Separate layer outputs from arrayed output.

1.0.x.x Added.

parameters /scanModeSettings /spacingIntervalEnabled

bool

visibility

Enables custom spacing interval.

1.0.x.x Parameter renamed

parameters /scanModeSettings /spacingInterval

number

minimum, maximum, visibility , actual

Custom spacing interval value (m)

1.0.x.x Parameter renamed.

1.0.x.x Actual schema added.





parameters/scanModeSettings/surface

object


LMIConfocalLineProfiler surface parameters. Applicable when parameters/scanModeSettings/scanMode = 2 (Surface)

1.0.x.x Parameter group created

parameters/ scanModeSettings /surface/type

integer

enum, actual, visibility

  • 1 - Fixed length

  • 2 - Variable length 1.0.x.x Added.

  • 3 -Rotational 1.0.x.x Added.

  • 0 - Continuous 1.0.x.x Added.

1.1.x.x Actual schema added.

parameters/scanModeSettings/surface/fixedLength

object

visibility

Fixed length surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 1 (Fixed Length)

1.0.x.x Parameter path changed, moved under scanModeSettings.

parameters/scanModeSettings/surface/ fixedLength/startTrigger

integer

enum, visibility

Start trigger.

  • 0 - Sequential

  • 1 - Digital (external) input

  • 2 - Software trigger

parameters/scanModeSettings/surface/ fixedLength/inputIndex

integer

enum, actual, visibility, minimum

Input index.

  • 0 first digital input

  • 1 second digital input

  • 2 third digital input

  • 3 fourth digital input

Has ADVANCED visibility. See Schema and Data Types .

parameters/scanModeSettings/surface/ fixedLength/length

number


Surface length (mm).

parameters/scanModeSettings/surface/variableLength

object

visibility

Variable length surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 2 (Variable Length)

1.0.x.x Added.

parameters/ scanModeSettings/surface/ variableLength/maxLength

number

readOnly

Maximum surface length (mm).

parameters/scanModeSettings/surface/rotational


visibility

Rotational surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 3 (Rotational)

1.0.x.x Added.

parameters/scanModeSettings/surface/rotational/ ticksPerRev

number

readOnly

Ticks per revolution.

parameters/scanModeSettings/surface/continuous

object

visibility

Continuous surface generation parameters.Applicable when parameters/scanModeSettings/surface/type = 0 (Continuous)

1.0.x.x Added.

parameters /scanModeSettings/surface / continuous/heightThreshold

number


Height threshold (mm).

parameters /scanModeSettings/surface / continuous/thresholdDirection

integer


  • 0 - Above

  • 1 - Below

parameters/scanModeSettings/surface/continuous/keepAllSingle

bool

visibility

Include one-sided data option.

1.0.106.6 Added.

parameters /scanModeSettings/surface / continuous/gapWidth

number


Gap width (mm).

parameters /scanModeSettings/surface / continuous/gapLength

number


Gap length (mm).

parameters /scanModeSettings/surface / continuous/paddingWidth

number


Padding width (mm).

parameters /scanModeSettings/surface / continuous/paddingLength

number


Padding length (mm).

parameters /scanModeSettings/surface / continuous/minArea

number


Minimum area (mm 2 ).

parameters /scanModeSettings/surface / continuous/maxLength

number


Maximum length (mm).

parameters /scanModeSettings/surface / continuous/edgeFiltering

bool


Edge filtering option.

parameters /scanModeSettings/surface / continuous/edgeKeepInterior

bool


Keep interior option for edge filtering.

parameters /scanModeSettings/surface / continuous/edgeWidth

number


Edge filtering width (mm).

parameters /scanModeSettings/surface / continuous/edgeLength

number


Edge filtering length(mm).

parameters/scanModeSettings/profileSort

object

Reserved for future use.





parameters/triggerSettings

object


LMIConfocalLineProfiler trigger parameters.

1.0.x.x Renamed from trigger to triggerSettings.

parameters/trigger Settings /source

integer

enum

Trigger source.

  • 0 - Time

  • 1 - Encoder

  • 2 - Digital input

  • 3 - Software

parameters/trigger Settings /maxFrameRateEnabled

bool

visibility

Trigger at maximum frame rate.

parameters/trigger Settings /frameRate

number

minimum, maximum, actual, visibility

Frame rate for time trigger (Hz).

parameters/trigger Settings /encoderSpacing

number

minimum, maximum, visibility

Encoder spacing (mm, degrees for surface/rotational).

parameters/trigger Settings /encoderTriggerMode

integer

enum, visibility

Encoder trigger mode.

  • 0 - Forward track (track backward)

  • 1 - Forward only (ignore backward)

  • 2 - Bi-directional

parameters/trigger Settings /schedulingUnits

integer

enum, visibility

Scheduling units.

  • 0 - Time

  • 1 - Encoder

parameters/trigger Settings /delay

number

minimum, maximum, visibility

Trigger delay. s or mm depending onparameters/trigger/schedulingUnits = 0 (Time) or 1 (Encoder), respectively.

parameters/trigger Settings /gateEnabled

bool

actual, visibility

1.0.x.x Enables digital input gating.

parameters/trigger Settings /reversalDistanceAutoEnabled

bool

visibility

Whether or not to use auto-calculated value of reversal distance.

parameters/trigger Settings /reversalDistance

number

readOnly, visibility

Encoder reversal threshold (for jitter handling).





parameters/filters

object


1.0.x.x Added.

parameters/filters/gapFilling

object


Gap filling filter

parameters/filters/gapFilling/enableX

bool

visibility

Enable gap filling along X axis.

parameters/filters/gapFilling/winX

number

minimum, maximum, visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/gapFilling/enableY

bool

visibility

Enable gap filling along Y axis; applies in surface mode only.

parameters/filters/gapFilling/winY

number

minimum, maximum,visibility, actual

Y window size (mm); applies in surface mode only.

1.2.x.x Actual schema added.

parameters/filters/median

object


Median filter

parameters/filters/median/enableX

bool

visibility

Enable median filtering along X axis.

parameters/filters/median/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/median/enableY

bool

visibility

Enable median filtering along Y axis.

parameters/filters/median/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing

object


Smoothing filter

parameters/filters/smoothing/enableX

bool

visibility

Enable smoothing along X axis.

parameters/filters/smoothing/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/smoothing/enableY

bool

visibility

Enable smoothing along Y axis.

parameters/filters/smoothing/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation

object


Decimation filter

parameters/filters/decimation/enableX

bool

visibility

Enable decimation along X axis.

parameters/filters/decimation/winX

number

minimum, maximum,visibility, actual

X window size (mm).

1.2.x.x Actual schema added.

parameters/filters/decimation/enableY

bool

visibility

Enable decimation along Y axis.

parameters/filters/decimation/winY

number

minimum, maximum,visibility, actual

Y window size (mm).

1.2.x.x Actual schema added.





parameters/advanced

object


1.0.x.x Removed.

engineId

string

readOnly

The identifier of the scanner's scan engine.

1.1.2.77Added.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/commands/align

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Aligns the scanner according to configurations defined in the /alignment resource.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

parameters

object

read-only

parameters/interactive

boolean

Indicates if the alignment operation requires interaction from the user or not.

Call Command Arguments

Item

Type

Mandatory or Optional

Description

interactive

boolean

Optional

Default value: false.

If true, the scanner will attempt to align interactively & request user parameters.
If false, alignment will run on its own without any additional inputs.

Scanners may choose not to implement interactive alignment, in which case this parameter should be ignored.

Methods

Method

Description

read

Returns the command's name and the list of parameters, if any, supported by this command.

The value of parameters are equal to their default values.

Example Response: 

{
  "payload": {
    "id": "align",
    "parameters": {
      "interactive": false
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/align"
      }
    }
  },
  "path": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/align",
  "type": "response",
  "status": 1
}

call

Aligns the scanner. The response to calling this resource may be returned immediately, even if if alignment has not completed. In this case, clients can check for alignment completion by checking alignState on the parent scanner resource. More specific behavior information can be found within the scan engine specific documentation.

Example request: 

call /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/align {"interactive":false}

Notifications

None.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/commands/cancelAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands.

Description

Cancels running scanner alignment. If alignment is not running, this command does nothing.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command.

Call Command Arguments

None

Methods

Method

Description

read

Returns the command's name and the list of parameters, if any, supported by this command.

Example Response: 

{
  "payload": {
    "id": "cancelAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/cancelAlign"
      }
    }
  },
  "path": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/cancelAlign",
  "type": "response",
  "status": 1
}

call

Cancels scanner alignment.

Example request 

call /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/cancelAlign

Notifications

None.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/commands/clearAlign

Resource Type: (Callable)

1.0.x.x Added alignment commands

Description

Clears existing alignment. If alignment is running, then the alignment operation is cancelled first, then the existing alignment is cleared.

Properties

Item

Type

Schema

Description

id

string

read-only

Identifier of this command

Call Command Arguments

None

Methods

Method

Description

read

Returns the command's name and the list of parameters, if any, supported by this command. 

{
  "payload": {
    "id": "clearAlign",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/clearAlign"
      }
    }
  },
  "path": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/clearAlign",
  "type": "response",
  "status": 1
}

call

Clears scanner alignment.

Example request 

call /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/commands/clearAlign

Notifications

None.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/metrics

For metrics common across all Gocator scanners:

Scanner-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a scanner for a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see their specific resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

speed

k64f

number

Current trigger rate (Hz). If scanner is not running, this metric is omitted.

20001

N/A

"Gocator/Current Sensor Speed"

maxSpeed

k64f

number

Maximum theoretical trigger rate (Hz); Note this does not consider CPU load from data processing and output. This should match the value specified in the scanner parameters at Standard Scanner Resources#Trigger(Propertygroup) .

20002

N/A

"Gocator/Maximum Speed"

scanCount

k64u

integer

Number of scanned outputs for the given mode:

  • i.e. Number of profiles in profile mode

  • i.e. Number of surfaces in surface mode

  • i.e. Number of video outputs in video mode


0 if sensor is not running.

Note this number may differ slightly from actual number of profiles/surfaces/video messages received and processed.

20005

N/A

"Gocator/Scan Count"

frameCount

k64u

integer

Number of frames output.

This will be the same as the number of camera frames obtained.

1.0.x.x Added

scannerDrops

k64u

integer

Total drops across all sensor cameras & projectors that don't fall under trigger drops. Value resets on scan start, not stop, so value will persist when scanning stops.

0.3.x.x

Added

triggerDrops

k64u

integer

Total trigger drops across all sensors.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors across all sensors.

21202

N/A

Gocator/CameraErrors

processingLatency

k64u

integer

Processing latency (microseconds) for the last frame from this scanner.

Resets when a new scan is started.

21001

N/A

Gocator/Processing Latency

processingLatencyMax

k64u

integer

Highest processing latency(microseconds) from the entire scan.

Resets when a new scan is started.

21002

N/A

Gocator/Processing Latency Max

processingLatencyAvg

k64u

integer

Simple moving average of processing latency(microsecond) for the last 50 samples collected.

Resets when a new scan is started.

N/A

N/A

N/A

encoderValue

k64s

integer

Current scanner encoder tick.

1003

N/A

Node/EncoderValue

encoderFreq

k64s

integer

Current scanner encoder frequency (ticks/s). The sign of this metric serves as an indicator of the direction in which motion is occurring. A positive value denotes movement in a forward direction, whereas a negative value signifies movement in a backward or reverse direction.

1005

N/A

Node/EncoderFrequency

currentSyncTime

64u

Current value of the clock used to generate the time stamp for a scan data message.

N/A

N/A

laserEnabled

bool

boolean

This metric is an aggregate of the laser enabled status of all sensors managed by the scanner.

0: all sensors' laser is disabled (laser cannot be turned on)
1: one or more sensors' laser is enabled (laser can be turned on)

Derived from the sensor laserSafety health indicator.

Scanner metric aggregates the laserSafety setting from all online sensors. Only if all the online sensors' laserSafety value is 0 (ie. all the online sensors' lasers cannot be turned on), is the scanner level laserEnabled value set to 0. If any online sensor can potentially be turned on, then the scanner level laserEnabled is set to 1, as a cautionary warning to the user.

This scanner metric is named "laserEnabled" instead of "laserSafety", even though it is based on the sensor Node/laserSafety metric, is because "laserEnabled" more accurately describes the value of this metric.

N/A

N/A

advanced/overSpeedJitterCount

k64u

integer

Number of times speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

advanced/overSpeedJitterMax

k64f

number

Maximum amount that speed exceeded max speed.If scanner is not running or this condition has never occurred, this metric is omitted.

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given scanner. Each scanner type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method

Description

read

Reads the latest scanner metrics.

Example: 

read /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/metrics

which for example, returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/metrics"
      }
    },
    "advanced": {
      "overSpeedJitterCount": -9223372036854775808,
      "overSpeedJitterMax": -1.7976931348623157e+308
    },
    "encoderFreq": 0,
    "encoderValue": 0,
    "g2Scanner": {},
    "maxSpeed": 208.55397148676172,
    "scanCount": -9223372036854775808,
    "scannerDrops": 0,
    "speed": -1.7976931348623157e+308,
    "triggerDrops": 0
  },
  "status": 1,
  "type": "response"
}

stream

Receive continuous stream of scanner metrics.

Example: 

stream /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/metrics

cancelStream

Cancel continuous stream of scanner metrics.

Example: 

cancelStream /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/metrics


LMIConfocalLineProfiler scanners do not currently have any unique metrics.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/outputs

Resource Type: (Collection - Unordered)

Description

A collection of scanner outputs.

Methods

Method

Description

read

Returns the list of scanner outputsas embedded resources.

Example response: 

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/outputs/sensor-0:profile"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/outputs/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/outputs/top:profile"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/outputs"
      }
    }
  },
  "status": 1,
  "type": "response"
}


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/outputs/(outputId)

Resource Type: (CollectionItem)

ID: Predefined by scan engine.

Description

A scanner output object.

Properties

Item

Type

Schema

Description

dataFormat

DataFormat

readOnly

Data format of the output

dataSourceId

string

readOnly

The data source id ( i.e."scan:LMIConfocalLineProfiler:scanner-0:top:surface")

displayName

culture-specific string


User configurable display name of the scanner output.

enabled

bool


Whether the scanner output is enabled or not.

id

string

readOnly

Identifier of the scanner output.

priority

integer

readOnly

Priority of the scanner output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

0.3.x.x Added

recordingEnabled

bool

Whether the output should be recorded or not.

Methods

Method

Description

read

Returns the output parameters described above.

Example response: 

{
  "_links": {
    "self": {
      "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/outputs/stamp"
    }
  },
  "dataFormat": {
    "arrayed": false,
    "type": 8
  },
  "dataSourceId": "scan:LMIConfocalLineProfiler:scanner-0:stamp",
  "displayName": "Stamp",
  "enabled": true,
  "id": "stamp",
  "recordingEnabled": true
}

Update

updates the output resource.

Notifications

Event Type

Description

created

Occurs when a new output is added. The path indicates the new scanner output.

Example: 

{ "eventType" : "created", "path" : "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface"}

updated

Occurs when a scanner output's properties change. The path indicates the affected scanner output.

Example: 

{ "eventType" : "updated", "path" : "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/stamp" }

deleted

Occurs when a scanner output is deleted. The path indicates the scanner output that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/top:surface" }


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/alignment

Properties

LMIConfocalLineProfiler scan engine-specific alignConfig, containing user alignment configurations that will be applied to the alignment process.

Item

Type

Schema

Description

alignConfig/timeout

integer


Maximum time non-interactive alignment can take. If this time is exceeded, alignment will be aborted.

If alignment is run interactively, timeout is infinite.

1.0.x.x Added.

alignState

enum

Current state of alignment:

0 - Not aligned.
1 - Aligned.
2 - Alignment in progress.

1.0.x.x Added.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/transform

Properties

LMIConfocalLineProfiler scan engine-specific alignment transforms, containing user alignment transforms that will be applied to the scanner.

Item

Type

Schema

Description

encoderResolution

number

exclusiveMinimum

Encoder resoluti on for encoder-based triggering(degrees/tick) in rotational surface generation mode, assuming one millimeter per degree; (mm/tick) in all other modes.

speed

number

exclusiveMinimum

Travel Speed of the sensor used in time mode (mm/s).

transform

object

visibility

Transformation object, consisting of offsets and angles.

1.0.x.x Reserved for future.

transform/xOffset

number


Translation on the X axis (mm).

transform/yOffset

number

visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/zOffset

number


Translation on the Z axis (mm).

transform/xAngle

number

visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/yAngle

number


Rotation around the Y axis (degrees).

transform/zAngle

number

visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/actions

Resource Type: (CollectionItem)

Description

A collection of scanner actions defined by the scan engine.

Methods

Method

Description

read

Returns a list of custom scanner actions as embedded resources.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/engineId/scanners/scannerId/actions/sampleAction"
          }
        }
      }
    ]
  },

    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/engineId/scanners/scannerId/actions"
    }
  }
}

Notifications

None.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/actions/trigger

Resource Type: (CollectionItem , Callable)

ID: Predefined by scan engine.

Description

Software trigger.

Properties

Item

Type

Schema

Description

id

string

readOnly

Identifier of this command.

message

string

readOnly

Message component of the action if used.

Methods

Method

Description

read

Reads the software trigger.

Example request: 

read /scan/engines/engineId/scanners/scannerId/actions/trigger

Example response: 

{
  "payload": {
    "id": "trigger",
    "message": "",
    "parameters": {},
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/actions/trigger"
      }
    }
  },
  "path": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/actions/trigger",
  "type": "response",
  "status": 1
}

call

Calls the software trigger.

Example request: 

call /scan/engines/engineId/scanners/scannerId/actions/trigger

Notifications

None.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors

Resource Type: (Collection - Unordered)

Description

A collection of sensors under the scanner.


Properties

Item

Type

Schema

Description

creationParams

object

readOnly

LMIConfocalLineProfiler scan engine required sensor creation parameters.

creationParams/serialNumber

string

readOnly

Serial number of a sensor to add to the scanner.


Methods


Method

Description

read

Reads all sensors under the scanner; the list of sensors are returned as embedded items.


{

"_embedded": {

"item": [

{

"_links": {

"self": {

"href":"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0"

}

}

},

{

"_links": {

"self": {

"href":"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-1"

}

}

}

] },

"_links": {

"self": {

"href":"/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors"

}

},

"creationParams": {

"serialNumber":0

}

},

}


create

Method Trait: ( NoRestart ) System will not be restarted when adding sensors. This applies if a scanner already has sensors and is already running. After the addition of a sensor to the scanner, the system will remain in stopped state.

Creates a sensor resource underneath the scanner.
NOTE: A client should read the sensors resource to see if there are creationParams that can be supplied in the create method.

Example request:


create /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors {"serialNumber":12345}



Notifications

None.

/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)

Resource Type: (CollectionItem)

ID: Auto generated when sensors are added.

Description

A sensor object.

Properties

Item

Type

Schema

Description

displayName

culture-specific string


User configurable display name of the sensor.

id


readOnly

Identifier of the sensor within the collection (e.g. "sensor-0").

parameters

object


LMIConfocalLineProfiler scan engine provided additional sensor information.

parameters/ activeAreaSettings

object

extendedType

extendedType = TransformedBoxRegion

1.0.x.x Name changed from activeArea toactiveAreaSettings

parameters/ activeAreaSettings/activeArea/ x

number

minimum, maximum, readOnly

X center (mm). The limits of X (ie minimum and maximum) vary according to the current Width. As Width increases, the freedom of motion for X decreases.

parameters/ activeAreaSettings /activeArea / y

number

minimum, maximum, visibility, readOnly

Ycenter (mm). The limits of Y (ie minimum and maximum) vary according to the current Length. AsLength increases, the freedom of motion for Y decreases.

Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

parameters/ activeAreaSettings /activeArea / z

number

minimum, maximum, readOnly

Zcenter (mm).

parameters/ activeAreaSettings /activeArea / width

number

minimum, maximum, readOnly

X extent (mm).

1.0.x.x Added readOnly.

parameters/ activeAreaSettings /activeArea / length

number

minimum, maximum, visibility, readOnly

Y extent (mm). Not used by all scanners, in which case used=false.

1.0.x.x Added readOnly.

parameters/ activeAreaSettings/activeArea/ height

number

minimum, maximum, readOnly

Z extent (mm).

1.0.x.x Added readOnly.

parameters/ activeAreaSettings /activeArea / transformMatrix

array

visibility

The transformMatrix should not be rendered in UI clients because used=false, but its contents can toggle between being invalid (empty matrix, usually in Image scan mode) or having values (profile and surface modes).





parameters/exposureSettings

object


LMIConfocalLineProfiler exposureSettings

1.0.x.x Parameter group created; Exposure settings collected underneath one group.

parameters/exposureSettings/exposureMode

integer

enum, readOnly

Exposure mode.

  • 0 - Single exposure

  • 1 -Multipleexposure

  • 2 - Dynamic exposure

0.3.x.x Added multiple exposure.

0.3.x.x Added dynamic exposure.

parameters/exposureSettings/singleExposure

number

minimum, maximum, visibility, readOnly

Single exposure value (s).

parameters/ exposureSettings/ multipleExposures

array<number>

minItems, maxItems, visibility, readOnly

This contains a list of exposure values (s) to use when parameters/exposureMode = 1 (Multiple Exposures).

1.0.x.x Added.

parameters/ exposureSettings/ multiTargetIntensity

integer

minimum, maximum, visibility, readOnly

When using multiple exposures several spots can be detected at the same location. Among these, the spots closest to the user specified target intensity are selected.

0.3.x.x Added.

parameters/exposureSettings/ dynamicExposureMin

number

minimum, maximum, visiblity, readOnly

User-defined minimum allowable exposure (s) whenparameters/ exposureSettings/ exposureMode = 2 (dynamic)

0.3.x.x Added.

parameters/exposureSettings/ dynamicExposureMax

number

minimum, maximum, visibility, readOnly

User-defined maximum allowable exposure (s) whenparameters/ exposureSettings/ exposureMode = 2 (dynamic).
This is used also as a starting value for the control.

0.3.x.x Added.

parameters/exposureSettings/ dynamicTargetIntensity

number

minimum, maximum, visibility, readOnly

Exposure is continually adjusted such that the average intensity of the brightest profile layer matches user specified target intensity.

0.3.x.x Added.

parameters/ exposureSettings/ intensity

number

minimum, maxmum, visibility, readOnly

Intensity control value (%).

parameters/ exposureSettings/ intensityMinRange

integer

used, minimum

Min value for intensity.

1.0.x.x Parameter removed.

parameters/ exposureSettings/ intensityMaxRange

integer

used, minimum

Max value for intensity.

1.0.x.x Parameter removed.





parameters/subsamplingSettings

object


Subsampling settings.

1.0.x.x Parameter group created.

parameters/subsamplingSettings/xSubsampling

integer

enum, readOnly

Decreases profile's X resolution.

  • 1 - 1

  • 2 - 1/2

  • 4 - 1/4

parameters/subsamplingSettings/xSubsamplingDefaultEnabled

bool

Flag indicating whether X subsampling is allowed.

parameters/subsamplingSettings/zSubsampling

integer

enum, readOnly

Decreases profile's Z resolution.

  • 1 - 1

  • 2 - 1/2

parameters/subsamplingSettings/zSubsamplingDefaultEnabled

bool

visibility, readOnly

Use the default Z subsampling specified for the sensor.





parameters/ layerSettings

object


1.0.x.x Parameter group created.

parameters/ layerSettings /layerCount

integer

minimum, maximum, visibility, readOnly

Max number of layers to be detected (1-8). In image mode needed for detecting spot overlays.

1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/parameters)

parameters / layerSettings /layerSortingOrder

integer

enum, visibility, readOnly

Layer sorting order.

  • 0 - Top. Sort layers from top to bottom.

  • 1 - Bottom. Sort layers from bottom to top.

  • 3 - Sort first by intensity (highest first), then from top to bottom.

  • 4 - Sort first by intensity (highest first), then from bottom to top. 1.0.x.x Added new layer sorting order option.

1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/parameters)

parameters / layerSettings /layerSpecificParams

array<object>, used


Array of max 8 layers.

1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/parameters)

parameters/layerSettings/layerSpecificParams[8]

array<object>

visibility

Array of layer-specific parameter objects. There are always 8 objects in this array, even whenparameters/layerCount is less than 8.

1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/parameters)

1.0.x.x Moved under layerSettings group.

parameters / layerSettings /layerSpecificParams/n

object


Layers-specific parameter object

parameters / layerSettings /layerSpecificParams/n/intensityFilterType

integer

enum, readOnly, actual, visibility, readOnly

Intensity filter type.

  • 1 - Average intensity.

  • 2 - Signal detection.

Signal detection intensity is supported when per layer layer intensity is enabled.

parameters / layerSettings /layerSpecificParams/n/minThickness

number

minimum, maximum, visibility, readOnly

Minimum thickness of the layer (m).

parameters / layerSettings /layerSpecificParams/n/maxThickness

number

minimum, maximum, visibility, readOnly

Maximum thickness of the layer (m).

parameters / layerSettings /layerSpecificParams/n/refractiveIndex

number

minimum, visibility, readOnly

Effective refractive index of the material.

parameters / layerSettings /layerSpecificParams/n/detectMissingLayer

bool

visibility, readOnly

When enabled, missing points from the first layer are detected and considered as gaps. Method uses 'Min thickness' distance to separate layers. Disable for maximum performance. Parameter is supported only for the first layer (n=0).

0.3.x.x Added.

parameters / layerSettings /layerSpecificParams/n/detectMissingLayerGapX

number

minimum, maximum, visibility, readOnly

Maximum gap width (m) which is used for connecting points to the first layer. Parameter is supported for the first layer (n=0) when detectMissingLayer is enabled.

0.3.x.x Added.





parameters/advancedSettings

object


LMIConfocalLineProfiler advanced sensor parameters.

1.0.x.x Path changed toadvancedSettings.

parameters/advancedSettings/materialType

integer

enum, readOnly

  • 1 - Diffuse

  • 0 - Custom

The readOnly state of spot detection and camera gain parameters within advancedSettings depend on the value of materialType.
When materialType is "diffuse" many parameters are readOnly=true, but when materialType is "custom" these parameters are readOnly=false to allow adjustment.

1.0.x.x Moved under advancedSettings.
1.0.x.x Corrected that Diffuse = 1, Custom = 0 (prior documented values were wrong).

parameters/advancedSettings/highPowerEnabled

bool

visibility, readOnly

If enabled, intensity can be adjusted to greater than 100%.

1.0.x.x Added.

parameters/advancedSettings/intensityCalibration

bool

visibility, readOnly

If enabled, uneven illumination is corrected for intensity values.

1.0.x.x Added.

parameters/advancedSettings/perLayerIntensity

bool

readOnly

Allows the user to configure intensity output type on per layer basis. When enabled, affects performance.

1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/parameters/advanced)

parameters/advancedSettings/roughnessFilterEnabled

bool

visibility, readOnly

If enabled, noise reduction designed for roughness applications is used.

1.0.x.x Added.

parameters/advancedSettings/camera

object

visibility

Settings associated with camera. Modifiable when materialType is Custom.

parameters/advancedSettings/camera/digitalGain

number


Digital gain.

parameters/advancedSettings/camera/analogGain



1.0.x.x Removed.

parameters/advancedSettings/camera/gammaType



1.0.x.x Removed.

parameters/advancedSettings/camera/enhancedSurfaceFlatness/enabled

bool

readOnly

Enhanced surface flatness feature.

0 -feature is disabled

1 - feature is enabled

1.2.x.x Added.

parameters/advancedSettings/camera/enhancedSurfaceFlatness/coefficients

array<number>

readOnly, actual, visibility

Array of coefficients if filterType is not 0.

1.2.x.x Added.

ADVANCED

parameters/advancedSettings/camera/enhancedSurfaceFlatness/filterSize

enum

readOnly, visibility

Size of the filter if filterType is not 0. Allowed values3, 5, 7, 9, 11 and 13.

1.2.x.x Added.

ADVANCED

parameters/advancedSettings/camera/enhancedSurfaceFlatness/filterType

enum

readOnly, visibility

0 = User specified coefficient values
1 = Box filter
2 = Gaussian filter

1.2.x.x Added.

ADVANCED

parameters/advancedSettings/clusteringParams

object

visibility

Short cluster removal.

1.2.x.x Added

1.0.x.x Added.

parameters/advancedSettings/clusteringParams/removeShortClustersEnabled

bool

readOnly

When enabled, connects points to clusters and removes small clusters.

parameters/advancedSettings/clusteringParams/distanceX

number

minimum, maximum, visibility, readOnly

Maximum X distance (m) to the nearest point in a cluster.

parameters/advancedSettings/clusteringParams/distanceZ

number

minimum, maximum, visibility, readOnly

Maximum Z distance(m) to the nearest point in a cluster.

parameters/advancedSettings/clusteringParams/minWidth

number

minimum, maximum, visibility, readOnly

Minimum cluster width (m) which is not removed.

parameters/advancedSettings/spotDetection

object


LMIConfocalLineProfiler spot detection parameters.

1.0.x.x Path changed to advancedSettings

parameters/advancedSettings/spotDetection/edgeWindow

integer

enum, readOnly, actual

Gradient filter size (px).

parameters/advancedSettings/spotDetection/averageWindow

integer

enum, readOnly, actual

Moving average filter size (px).

parameters/advancedSettings/spotDetection/flexSpots

object

visibility

Flexible spots.

Has ADVANCED visibility. See Schema and Data Types .

1.2.1.147Replaced "used" keyword with "visibility" set to ADVANCED.

parameters/advancedSettings/spotDetection/intensityWindow

integer

enum, readOnly, actual

Window size for spot intensity calculation (px).

parameters/advancedSettings/spotDetection/multiExpWindow

integer

minimum, maximum, readOnly, actual,visibility

Window size (px) for merging multi exposure points.

1.1.x.x 1.2.x.x 1.2.x.x Added.

parameters/advancedSettings/spotDetection/threshold

integer

minimum, maximum, actual, readOnly

Threshold to tell whether pixel is within spot.

parameters/advancedSettings/spotDetection/maxSpotCount

integer

minimum, maximum, actual, readOnly, visibility

Maximum spot count.

1.2.x.x Added.

EXPERIMENTAL

parameters/advancedSettings/cameraHighSpeedMode

bool


If enabled and X Subsampling is not equal to 1, sensor will run in optimized speed mode.

1.2.x.x Added.

1.2.x.x Moved from experimental to public.


parameters/laserSafetyLock

bool

visibility

Laser safety lock state for the sensor.

0 - laser safety lock is off.

1 -laser safety lock is on.

For sensor that support this, can also change the state by updating this parameter to the desired state. Currently, only battery powered sensors support this.

1.2.2.10 Added.

parameters/powerSaveMode

bool

visibility

Power save mode for the sensor.

0 - power save mode is off.

1 -power save mode is on.

For sensor that support this, changing the state of this parameter will update the state. Mainly useful for battery powered sensors.

1.2.20.92 Added.

connectionMessage

string

readOnly

Describes some details about the error if the connection status is an error.

Can be empty. The scan engine is not obligated to provide this.

connectionStatus

int

readOnly

Connection state of the sensor.

  • 0 - Sensor is connectable.

  • 1 - Sensor is connecting.

  • 2 - Sensor is connected.

  • 3 - Sensor is already connected to another application.

  • -1 - Sensor is not connectable.

  • -2 - Sensor is offline.

model

string

readOnly

Model of the sensor. Can be empty if the scan engine does not support discovering the model.

serialNumber

string

readOnly

A string that uniquely identifies the sensor.

Serial numbers need not be strictly numerical. They may contain letters and and other typographic characters.

For a Gocator sensor, it is the serial number represented as a string.

version

string

readOnly

Version of the sensor firmware. Can be empty if the scan engine does not support discovering the version.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)/metrics

For metrics common across all Gocator sensors:

Sensor-level metrics that are common across all Gocator types. For details on the sensor metrics resource, see Scanner Resources .

To view metrics specific to a given scan engine such as LMILaserLineProfiler, LMIFringeSnapshot, or LMIConfocalLineProfiler, see its resource reference.

Mapping to Gocator 6.x health indicators are provided where applicable.

While sensor either connected or disconnected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

connectAttempts

k64s

integer

Number of retry attempts to connect to sensor.
See connection state within Resource Reference#/scan/(engineId)/visibleSensors .

N/A

Once sensor is connected:

Item

Internal Type

Type

Schema

Description

Classic IndicatorId

Classic Instance

Classic Name

upTime

k64u

integer

Time elapsed since node boot-up or reset (seconds).

2017

N/A

Node/UpTime

bootCount

k64s

integer

Number of boot-ups.

2086

Node/BootCount

laserSafety

bool

boolean

Laser safety status.

Values have the following meaning:

0: laser is disabled (laser cannot be turned on)
1: laser is enabled (laser can be turned on)

1010

N/A

Node/LightSafety

expTimeTotal

k64u

integer

Total time the laser has been on since first use. (seconds)

1.0.x.x

Added

maxSpots

k64u

integer

Maximum avaialble spots across all cameras on sensor.

1.0.x.x

Added.

masterConnected

bool

boolean

Master connection status.
false: if not connected
true: if connected and syncSource is Master.

20006

0 for main
1 for buddy

Gocator/MasterConnected/%u

masterStatus

bool

boolean

Duplicate of masterConnected?
false: if not connected
true: if connected and syncSource is Master.

20010

0 for main
1 for buddy

Gocator/MasterStatus/%u

syncSource

bool

boolean

Node synchronization source
1 - Master device
2 - Sensor

2043

N/A

Node/SyncSource

intTemp

k64s

integer

Controller temperature (millidegrees C).

20009

N/A

Gocator/IntTemp/%u

cpuTemp

k64s

integer

CPU temperature. (millidegress C)

20011

N/A

Gocator/CpuTemp/%u

cameraTemp0

k64s

integer

Camera board temperature (millidegrees C).

20012

N/A

Gocator/CameraTemp0/%u

cameraTemp1

k64s

integer

Camera board temperature (millidegrees C).

20013

N/A

Gocator/CameraTemp1/%u

laserDriverTemp

k64s

integer

Laser driver control temperature (millidegrees C).

2026

LightDriver/0/Temp

cameraBufferDrops0

k64u

integer

Total buffer drops for the current scan on camera 0. Value resets on scan start, not stop, so value will persist when scanning stops.

cameraBufferDrops1

k64u

integer

Total buffer drops for the current scan on camera 1. Value resets on scan start, not stop, so value will persist when scanning stops.

If the sensor has only one camera, this metric is not provided.

triggerDrops

k64u

integer

Trigger drops for the sensor.

21010

N/A

Gocator/TriggerDrops

cameraErrors

k64u

integer

Total camera errors for the sensor

21202

N/A

Gocator/CameraErrors

memUsed

k64u

integer

Amount of memory currently used (bytes).

2003

N/A

Memory/TotalUsed

memCapacity

k64u

integer

Total amount of memory available (bytes).

2004

N/A

Memory/TotalCapacity

cpuCores

Array

array

List of CPU cores available to the sensor.

cpuCores/n

Structure

object

Single CPU core object.

cpuCores/n/used

k64u

integer

Individual CPU core utilization (percent).

2052

Cpu core index

Node/Cpu<instance>Used

cpuCoresUsedMax

k64u

integer

Max CPU core utilization (percent).

cpuCoresUsedAvg

k64u

integer

Average CPU core utilization (percent).

storageVolumes

Array

array

List of available storage volumes.

There should only ever be two:
1st (index 0) - User
2nd (index 1) - System

storageVolumes/n

Structure

object

Storage volume object.

Entry 0 is User
Entry 1 is System

storageVolumes/n/used

k64s

integer

Total amount of non-volatile storage used (bytes).

2005

0 - User
1 - System

StorageVolume/User/Used
StorageVolume/System/Used

storageVolumes/n/capacity

k64s

integer

Total amount of non-volatile storage available (bytes).

2006

0 - User
1 - System

StorageVolume/User/Capacity
StorageVolume/System/Capacity

storageVolumes/n/available

k64s

integer

Amount of non-volatile storage available (capacity - used) (bytes).

networkIfs

Array

array

List of available network interfaces.

networkIfs/n

Structure

object

Network interface object.

networkIfs/n/linkStatus

kEthernetLink

integer

Current Ethernet link status.

(0x0000) - No link, or speed unknown.
(0x0001) - 10 Mb/s, half duplex.
(0x0002) - 10 Mb/s, full duplex.
(0x0004) - 100 Mb/s, half-duplex.
(0x0008) - 100 Mb/s, full-duplex.
(0x0010) - 1000 Mb/s, half-duplex.
(0x0020) - 1000 Mb/s, full-duplex.
(0x8000) - Auto-negotiated.

2034

netInterface

NetInterface/<netInterface>/LinkStatus

networkIfs/n/linkCapacity

k64u

integer

Total available outbound network throughput (bytes/s).

2009

netInterface

NetInterface/<netInterface>/LinkCapacity

networkIfs/n/txRate

k64u

integer

Network output transmission rate (bytes/s)

2076

netInterface

NetInterface/<netInterface>/TxRate

networkIfs/n/rxRate

k64u

integer

Network output transmission rate (bytes/s)

2077

netInterface

NetInterface/<netInterface>/RxRate

networkIfs/n/txBytes

k64u

integer

Total number of bytes sent on network.

2078

netInterface

NetInterface/<netInterface>/TxBytes

networkIfs/n/rxBytes

k64u

integer

Total number of bytes received on network.

2079

netInterface

NetInterface/<netInterface>/RxBytes

storageMediumEraseTotal

k64u

integer

Total number of storage medium erases.

1.2.x.x

Added.

2093

StorageMedium/EraseTotal

storageMediumReadTotal

k64u

integer

Total number of storage medium reads.

1.2.x.x

Added.

2091

StorageMedium/ReadTotal

storageMediumWriteTotal

k64u

integer

Total number of storage medium writes.

1.2.x.x

Added.

2092

StorageMedium/WriteTotal

storageMediumBadBlocks

k64u

integer

Storage medium number of bad blocks.

1.2.x.x

Added.

3115

StorageMedium/BadBlocks

batteryRemainingCharge

k64s

integer

Remaining battery charge left in percentage multiplied by 1000

3104

N/A

Battery/RemainingCharge

batteryOperatingTime

k64s

integer

Remaining operating time for battery in hours multiplied by 1000

3105

N/A

Battery/OperatingTime

batteryStateOfHealth

k64s

integer

How much charge can the battery hold relative to when it was brand new, as a percentage multiplied by 1000

3106

N/A

Battery/StateOfHealth

batteryAlarmStatus

k64u

integer

Represents battery-related alarm status:

0 - no alarm
1 - battery low charge remaining alarm (< 10%)
2 - battery low operating time remaining alarm (< 0.5 hours)

3107

N/A

Battery/AlarmStatus

flexSpotErrors

k64u

integer

Flexible spots pipeline errors.

1.1.x.x Added

flexSpotBufferOverflows

k64u

integer

Flexible spots pipeline buffer overflow value.

1.1.x.x Added

flexSpotOverflows

k64u

integer

Flexible spots pipeline spot overflow value.

1.1.x.x Added

flexSpotPixelOverflows

k64u

integer

Flexible spots pipeline pixel overflow value.

1.1.x.x Added

For details on how to read & stream these metrics:

Resource Type: (Collection - Unordered)

Resource Type: (Streamable)

Description

Metrics for a given sensor. Each sensor type will have its own set of metrics.

This section does not describe metrics unique to Gocator or any of its scan engines. That information can be found through the sections for the LMILaserLineProfiler engine, LMIFringeSnapshot engine, and LMIConfocalLineProfiler engine.

Methods

Method

Description

read

Reads the latest sensor metrics.

Example: 

read /scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics

which for example returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/metrics"
      }
    },
    "cameraBufferDrops0": 0,
    "cameraBufferDrops1": -9223372036854775808,
    "cameraTemp0": -9223372036854775808,
    "cameraTemp1": -9223372036854775808,
    "connectAttempts": 1,
    "cpuCores": [
      {
        "used": 1
      },
      {
        "used": 3
      }
    ],
    "cpuCoresUsedAvg": 2,
    "cpuCoresUsedMax": 3,
    "cpuTemp": 40259,
    "expTimeTotal": 3298,
    "intTemp": 31250,
    "laserDriverTemp": 29812,
    "laserSafety": true,
    "masterConnected": false,
    "masterStatus": false,
    "maxSpots": 1256,
    "memCapacity": 1053257728,
    "memUsed": 128603264,
    "networkIfs": [
      {
        "linkCapacity": 125000000,
        "linkStatus": 32,
        "rxBytes": 658570,
        "rxRate": 3118,
        "txBytes": 16242729,
        "txRate": 61384
      }
    ],
    "storageVolumes": [
      {
        "capacity": 251133952,
        "used": 87003136
      },
      {
        "capacity": 6762496,
        "used": 2347008
      }
    ],
    "syncSource": 2,
    "triggerDrops": 0,
    "upTime": 817
  },
  "status": 1,
  "type": "response"
}

stream

Receive continuous stream of sensor metrics.

Example: 

stream /scan/engines/LMIConfocalLineProfiler/scanners/0/sensors/sensor-0/metrics

cancelStream

Cancel continuous stream of sensor metrics.

Example: 

cancelStream /scan/engines/LMIConfocalLineProfiler/scanners/0/sensors/sensor-0/metrics


Per online LMIConfocalLineProfiler Sensor:

Item

Internal Type

Type

Description

lightDriverTemp

k64s

integer

Light driver control temperature (millidegrees C).

lightDriverLedTemp

k64s

integer

LED PCB temperature(millidegrees C).

lightDriverExtTemp

k64s

integer

External thermistor temperature(millidegrees C).

expTimeTotal

k64u

integer

Total running time of LMIConfocalLineProfiler light (seconds).


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)/transform

Properties

LMIConfocalLineProfilerscan engine alignment transforms, containing user alignment transforms that will be applied to the sensor.

Item

Type

Schema

Description

reverseX

boolean

visibility

Reverse X.

transform

object


Transformation matrix.

transform/xOffset

number


Translation on the X axis (mm).

transform/yOffset

number

visibility

Translation on the Y axis (mm).Not used by all scanners, in which case used=false.

transform/zOffset

number


Translation on the Z axis (mm).

transform/xAngle

number

visibility

Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.

transform/yAngle

number


Rotation around the Y axis (degrees).

transform/zAngle

number

visibility

Rotation around the Z axis (degrees).Not used by all scanners, in which case used=false.


/scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)/actions

Resource Type: (CollectionItem)

ID: Predefined by the scan engine.

Description

A collection of sensor actions defined by the scan engine.

Methods

Method

Description

read

Returns a list of custom sensor actions as embedded resources.

Example response: 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
          }
        }
      }
      {
        "_links": {
          "self": {
            "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/actions/shutdown"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/LMIConfocalLineProfiler/scanners/scanner-0/sensors/sensor-0/actions"
    }
  }
}

Notifications

None.


GoPxL: Tool Resources

/toolTypes

Resource Type: N/A

Contains a list of tool types available to be created in the system. Tool Types are obtained from the Tool Registry

ToolType Schema:

Item Type Schema Description
type string readOnly The type of the tool. e.g. TestAction, ProfileDemo
displayName culture-specific string readOnly Name of the tool. e.g: Test Action Tool, Profile Demo Tool
description culture-specific string readOnly

Describes the function and purpose of the tool

batchability bool readOnly

Batchability of the tool set by tool developers.

The default is set to true and that all tools are batchable (assuming that no outputs are arrayed).

If batchability is set to false, then the tool will be explicitly excluded from being batched even if it meets the requirements to be batched.

1.1.x.x

1.2.x.x

helpHtml string readOnly
Html help string for this tool. If both helpURL and helpHtml is specifiedhelpURL will take precedence.
helpUrl string readOnly Html help string for this tool If both helpURL and helpHtml is specifiedhelpURL will take precedence.
categories

array<string>

readOnly Categories of the tool.
A tool can be of multiple categories or no category
icon object readOnly

Icon data and file extension described below

Eventually this will be deprecated in favor of iconUrl

icon/mimeType string readOnly common image file format extensions. e.g. png, gif
icon/data binary readOnly

raw binary of the image.

Methods

Method Description
read

Reads the list of tool types.

Note: requires client to be in asynchronous mode, non-asynchronous mode is not yet supported.

Example: 

read /toolTypes

Response 

{
  "_links": {
    "self": {
      "href": "/api/toolTypes"
    }
  },
  "items": [
    {
      "categories": [
        "Sample"
      ],
      "description": "Example Tool with anchored region",
      "displayName": "Anchored Profile Region Tool",
      "helpHtml": "",
      "helpUrl": "",
      "icon": {
        "data": {
          "bytes": [],
          "subtype": null
        },
        "mimeType": ""
      },
      "type": "AnchoredProfileRegion"
    }
  ]
}

/tools

Resource Type: (Collection - Ordered)

A collection of tools.

Methods

Method Description
read

Read all tools from the system.

Example: 

read /tools {"expandLevel" : -1}

response 

{
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/api//tools/ToolType-0"
          }
        },
        "ordIndex": 0
      },
      {
        "_links": {
          "self": {
            "href": "/api//tools/ToolType-0"
          }
        },
        "ordIndex": 1
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/tools"
    }
  }
}
create

Adds a tool into the system.

Arguments:

Item Type Description
type string

The tool type of interest to add.

A list of tool types will be able to be obtained from the /tooltypes resource

position integer The position to insert the tool at (0 based index). Defaults to '-1' which inserts the new tool at the end of the collection.
autoConnect bool

Whether to automatically connect the tool after creation. Defaults to false.

0.3.x.x+ Added

Examples: 

create /tools { "type" : "TestForward" }
create /tools { "type" : "TestForward", "position" : 3 }
create /tools { "type" : "TestForward", "autoConnect" : true }

Notifications

Event Type Description
updated

Occurs whenever the ordered tool collection changes due to additions, deletions, or moves/reorders.

Example: 

{ "eventType" : "updated", "path" : "/tools",
  "content" : {list of tools} }
embeddedUpdated

Occurs whenever the ordered tool collection changes due to additions, deletions, or moves/reorders during a job load.

Example: 

{ "eventType" : "embeddedUpdated", "path" : "/tools" }

1.0.x.x Added

/tools/commands/clone

Resource Type: (Callable)

Command to clone a tool to the position specified.

Methods

Method Description
call

Arguments:

Item Type Description
toolId string

The id of the tool to make a copy of (tool to be cloned).

position integer

The position to insert the cloned to (zero based index). The index is optional and if not provided, the tool clone will be appended to the position right after where the cloned tool resides.

Example: 

call /tools/commands/clone{ "toolId" : "TestParams-1", "position": 2 }

/tools/commands/move

Resource Type: (Callable)

Command to move a tool to the position specified.

Methods

Method Description
call

Arguments:

Item Type Description
toolId string

The id of one of the tools to move.

position integer

The position to move the tool to (zero based index). The index must be a valid index ie. to move a tool to the end of a three item collection use position=2.

Example: 

call /tools/commands/move { "toolId" : "TestForward-0", "position": 2 }

/tools/commands/reorder

Resource Type: (Callable)

Command to reorder the tool list according to a provided list. The list of tools must contain the same number of tools and have no duplicates.

Methods

Method Description
call

Arguments:

Item Type Description
tools array<string>

The complete list of currently present tool ids in any order.

Example: 

call /tools/commands/reorder { "tools" : ["TestForward-2", "TestForward-1", "TestForward-0"] }

/tools/commands/resetMetrics

Resource Type: (Callable)

Command to reset all tool metrics (all metrics within each tool are reset to zero, NULL, or otherwise nominal values).

For more info on tool metrics, see Metrics Resources .

Methods

Method Description
call

Example: 

call /tools/commands/resetMetrics

/tools/(toolId)

Resource Type: (CollectionItem)

ID: auto generated when the tool is first added

Path parameters: by " extId", see Methods for which ones support path parameter expansion.

NOTE: Each tool should share the following common properties, but the schema for each tool within the collection may be different due to the ParamSet .

Item Type Schema Description
id string readOnly The Tool ID. This ID should never be parsed or interpreted by any client. Tool IDs are picked by the application according to unpredictable mechanisms. Do not rely on the format.
toolType string readOnly Type name of the tool.
displayName culture-specific string
User configurable display name of the tool.
extId string

User configurable external id of the tool. Once configured, this id will never change. This makes external id useful as a way of reliably referring to a tool from outside/external code (for example via the SDK). Additionally, external IDs can be used as an alternative to ID when querying tools on the collection (see the examples in the read method below).

This field must not be an empty string, and it must be a unique value compared to extId of other outputs.

batched boolean readOnly

Describeswhether or not the tool is currently batched.

1.0.x.x Added

isBatchable boolean readOnly

Describes whether the tool is batchable or not. Batchability is determined solely by outputs (tools containing arrayed outputs aren't batchable).

This property is only applicable to when a tool is going from unbatched batched. When batched is true, this property is not applicable anymore and shouldn't be used in determining if a tool can be unbatched or not. A tool that is currently batched can always be unbatched.

If isBatchable is false, you will not be prevented from batching the tool. However the system will not start if a non-batchable tool is batched. Clients should prevent batching tools when isBatchable is false.

1.0.x.x Added

parameters object
Custom parameters specific to the tool.
parametersVersion string
Optional version string of the tool.

Methods

Method Description
read

Read a specific tool.

Path parameters: extId

Example: 

read /tools/TestForward-0 { "expandLevel" : -1 }

Read tool by path parameter extId: 

read /tools/extId=My%20Tool%20Id
update

Update a specific tool's properties.

Path parameters: extId

Arguments:

Item Type Description
properties string The tool properties to alter.

Examples:

Update a tool's extId property: 

update /tools/TestForward-0 { "extId" : "My Tool Id" }

Update the tool's parameters property: 

update /tools/TestForward-0 { "parameters" : { "EnableAbsolute" : true } }

Update multiple tool properties at once: 

update /tools/TestForward-0 { "extIid" : "My Tool Id", 
                              "parameters" : { "EnableAbsolute" : true,
                                               "OutputCount" : 2 } }

Update tool by path parameter extId: 

update /tools/extId=My%20Tool%20Id { "parameters" : { "EnableAbsolute" : true } }
delete

Deletes tools from the system.The path to the tool must be provided.

Path parameters: extId

Examples:

Delete a single tool: 

delete /tools/TestForward-0

Delete tool by path parameter extId: 

delete /tools/extId=My%20Tool%20Id

A special wildcard form applies to this delete method .

The path of this tools command can be wildcarded to delete all tools: 

delete /tools/*

Notifications

Event Type Description
created

Occurs when a new tool is added. The path indicates the new tool id.

Example: 

{ "eventType" : "created", "path" : "/tools/TestForward-0",
  "content" : {new tool properties} }
updated

Occurs whenever tool's own properties, or its list of inputs and outputs change. The path indicates the affected tool id.

Example: 

{ "eventType" : "updated", "path" : "/tools/TestForward-0",
  "content" : {tool properties} }
deleted

Occurs whenever a tool is deleted. The path indicates the tool id that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/tools/TestForward-0" }

/tools/(toolId)/commands/batch

Resource Type: (Callable)

Command to batch a tool.

1.0.x.x Resource Added

Methods

Method Description
call

Example: 

call /tools/TestForward-0/commands/batch

/tools/(toolId)/commands/unbatch

Resource Type: (Callable)

Command to unbatch a tool.

1.0.x.x Resource Added

Methods

Method Description
call

Example: 

call /tools/TestForward-0/commands/unbatch

/tools/(toolId)/inputs

Resource Type: (Collection - Unordered)

A collection of tool inputs. This collection does not support creation and deletion via the protocol.

Methods

Method Description
read

Reads the current list of tool inputs.

Example(s): 

read /tools/TestForward-0/inputs

Notifications

Event Type Description
updated

Occurs whenever the tool input collection changes due to additions, or deletions. The path indicates the inputs collection, scoped to the tool.

Example: 

{ "eventType" : "updated", "path" : "/tools/TestForward-0/inputs",
  "content" : {updated tool inputs} }

/tools/(toolId)/inputs/(inputId)

Resource Type: (CollectionItem)

ID: Auto-generated by the tool

Path parameters: by "extId", see Methods for which ones support path parameter expansion.

Each tool input has the following common schema properties:

Item Type Schema Description
id string readOnly Input ID.
displayName culture-specific string readOnly Display name of the tool input.
extId string
DEPRECATED

acceptedDataFormats

DataFormat [] readOnly

List of acceptable data formats. See Common Types .
This is readOnly as it reflects the capabilities of the underlying tool implementation.

Arrayed implies Scalar

If DataFormat.arrayed is true, it is implied that the underlying tool still accepts scalar input of DataFormat.type.

For example, the following means that scalar and arrayed profiles are accepted, but only scalar surfaces: 

   "acceptedDataFormats": [
            {
              "arrayed": true,
              "type": 3 			(Uniform Profile)
            },
            {
              "arrayed": false,
              "type": 5				(Uniform Surface)
            }
          ],

Also, note that within acceptedDataFormats, there can only be one entry per DataFormat.type.

optional bool readOnly

Whether this is a required input or not.
This is readOnly as it reflects the capabilities of the underlying tool implementation.

This is specified as part of the tool definition, by the tool developer. Usually, most tool inputs are required by default,
and must be connected to an enabled output as its datasource in order for the tool processing to start.

dataSource string

ID of the data source to connect to the input. See /dataSources.

If "(none)", the input is not connected.

Methods

Method Description
read

Reads a specific tool input.

Path parameters: extId

Example: 

read /tools/TestForward-0/inputs/Input0

Read tool input by path parameter extId: 

read /tools/TestForward-0/inputs/extId=My%20Input%20Id
update

Updates a specific tool input.

Path parameters: extId

Arguments:

Item Type Description
properties string The tool input properties to alter.

Example:

Update a tool input extId: 

update /tools/TestForward-0/inputs/Input0 { "extId" : "My Input Id" }

Update tool input by path parameter extId: 

update /tools/TestForward-0/inputs/extId=My%20Input%20Id { "displayName" : "TestInput" }

Notifications

Event Type Description
created

Occurs whenever a tool input is added. The path indicates the new tool input id.
NOTE: Although there is no command to explicitly add/delete tool inputs, this may happen internally in the tool when tool properties are changed, triggering this event notification.

Example: 

{"eventType" : "created", "path" : "/tools/TestForward-0/inputs/Input1",
 "content" : {new tool input properties} }
updated

Occurs whenever a tool input is updated. The path indicates the tool input id that was updated.

Example: 

{"eventType" : "updated", "path" : "/tools/TestForward-0/inputs/Input1", 
 "content" : {tool input properties} }
deleted

Occurs whenever a tool input is deleted. The path indicates the tool input id that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/tools/TestForward-0/inputs/Input1" }

/tools/(toolId)/outputs

Resource Type: (Collection - Unordered)

A collection of tool outputs. This collection does not support creation and deletion via the protocol

Methods

Method Description
read

Reads the current list of tool outputs.

Example(s): 

read /tools/TestForward-0/outputs

Notifications

Event Type Description
updated

Occurs whenever the tool output collection changes due to additions, or deletions. The path indicates the inputs collection, scoped to the tool.

Example: 

{ "eventType" : "updated", "path" : "/tools/TestForward-0/outputs",
  "content" : {updated tool outputs} }


/tools/(toolId)/outputs/(outputId)

Resource Type: (CollectionItem)

ID: Auto-generated by the tool developer

Path parameters: by "extId", see Methods for which ones support path parameter expansion.

NOTE: Each tool output should share the following common properties, but the schema for each tool output within the collection may be different due to the ParamSet .

Item Type Schema Description
id string readOnly Output ID. This ID should never be parsed or interpreted by any client. Output IDs are picked by the application according to unpredictable mechanisms. Do not rely on the format.
displayName culture-specific string
User configurable display name of the tool output.
extId string

User configurable external ID of the tool output. Once configured, this id will never change. This makes external id useful as a way of reliably referring to an output from outside/external code (for example via the SDK). Additionally, external IDs can be used as an alternative to ID when querying outputs on the collection (see the examples in the read method below).

This field must not be an empty string, and it must be a unique value compared to extId of other outputs.

dataSourceId string readOnly dataSourceId of the output (e.g. tools:Tool1:outputs:Output0), used for identifying the related dataSource in the /dataSources resource. If the output is disabled, it will be an empty string.
enabled bool
Determines whether or not the output is enabled.
recordingEnabled bool
Determines whether or not the recording output is enabled.

dataFormat

DataFormat readOnly

The data format of the output. See Common Types .
This is readOnly as it reflects the capabilities of the underlying tool implementation.

Arrayed output format vs. scalar input data format

If a tool outputs arrayed data, it will no longer be connectable to tool inputs that only accept scalar data format.

To preserve the ability to be connectable to such tool inputs, define a separate tool output as scalar data format (for the data type of interest).

priority integer readOnly

Priority of the tool output as an unsigned 32-bit integer.

Highest priority being 1 and 0 being undefined priority which will always be last.

0.3.x.x Added

parameters object
Set of tool output parameters.

Methods

Method Description
read

Reads a specific tool output.

Path parameters: extId

Example: 

read /tools/TestForward-0/outputs/Output0

Read tool output by path parameter extId: 

read /tools/TestForward-0/outputs/extId=My%20Output%20Id
update

Updates a specific tool output.

Path parameters: extId

Arguments:

Item Type Description
properties string The tool output properties to alter.

Example:

Update a tool output extId: 

update /tools/TestForward-0/outputs/Output0 { "extId" : "My Output Id" }

Update a tool output parameters: 

update /tools/TestForward-0/outputs/Output0 {"parameters" : {decisionMax: 2, decisionMin: 0}}

Update a tool output by path parameter extId: 

update /tools/TestForward-0/outputs/extId=My%20Output%20Id { "enabled" : true}

Notifications

Event Type Description
created

Occurs whenever a tool output is added. The path indicates the new tool output id.
NOTE: Although there is no command to explicitly add/delete tool outputs, this may happen internally in the tool when tool properties are changed, triggering this event notification.

Example: 

{ "eventType" : "created", "path" : "/tools/TestForward-0/outputs/Output1",
  "content" : {new tool output properties} }
updated

Occurs whenever a tool output is updated. The path indicates the tool output id that was updated.

Example: 

{ "eventType" : "updated", "path" : "/tools/TestForward-0/outputs/Output1",
  "content" : {tool output properties} }
deleted

Occurs whenever a tool output is deleted. The path indicates the tool output id that was deleted.

Example: 

{ "eventType" : "deleted", "path" : "/tools/TestForward-0/outputs/Output1" }

/tools/(toolId)/metrics

Resource Type: (Streamable)

Contains tool metrics. Mapping to Gocator 6.x health indicators are provided where applicable.

Path parameters: by "extId ", see Methods for which ones support path parameter expansion.

The metrics available per tool are broken down into:

  • Tool execution statistics
  • Tool Type metrics (custom, provided by tool developers)
  • Tool measurement statistics (per tool output)
  • Tool feature statistics (per tool Output)

1.2.x.x Tool measurement & feature metrics can also come in arrays, in which case each metric will be an array of values pertaining to each individual item in the array.

Item Internal Type Type Schema Description
Classic IndicatorId Classic Instance Classic Name
toolStats/runTime k64u integer
The most recent time taken to execute the tool (microseconds) .
22004 tool id Tool-<tool id>/RunTime
toolStats/runTimeMin k64u integer
Minimum time spent for tool to process a sample (microseconds) .
22016 tool id Tool-<tool id>/MinRunTime
toolStats/runTimeMax k64u integer
Maximum time spent for tool to process a sample (microseconds) .
22017 tool id Tool-<tool id>/MaxRunTime
toolStats/runTimeAvg k64u integer
Average time for tool to process a sample (microseconds) .
22018 tool id Tool-<tool id>/AvgRunTime
toolStats/runTimeAvgPerc k64u integer
The average time to process a sample as a percentage of the total of all tool execution times (tenths of a percent).
22019 tool id Tool-<tool id>/AvgRun%
toolStats/skippedExecutionTime k64u integer
The time spent for a tool skipping data process due to the tool receiving unusable data.












<toolType>/... various N/A
Custom tool type specific metrics provided by the tool developer.
N/A N/A N/A
Measurement statistics are per tool output:







/outputsByExtId/(outputExtId)/value k64f number

Measurement Value.

Could be null if a scan hasn't been acquired yet or was invalid.


30000 Gocator Output Id Value
/outputsByExtId/(outputExtId)/passCount k64u integer

Number of pass decisions.


30001 Gocator Output Id PassCnt
/outputsByExtId/(outputExtId)/failCount k64u integer

Number of fail decisions.


30002 Gocator Output Id FailCnt
/outputsByExtId/(outputExtId)/lastDecision k8s integer

Most recent decision (pass/fail/invalid).

pass = 1
fail = 0
invalid = null


N/A N/A N/A
/outputsByExtId/(outputExtId)/max k64f number

Maximum measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30003 Gocator Output Id Max
/outputsByExtId/(outputExtId)/min k64f number

Minimum measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30004 Gocator Output Id Min
/outputsByExtId/(outputExtId)/range k64f number

Measurement range value.

Could be null if a scan hasn't been acquired yet or was invalid.


N/A N/A N/A
/outputsByExtId/(outputExtId)/avg k64f number

Average measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30005 Gocator Output Id Average
/outputsByExtId/(outputExtId)/stdDev k64f number

Measurement value standard deviation.

Could be null if a scan hasn't been acquired yet or was invalid.


30006 Gocator Output Id StdDev
/outputsByExtId/(outputExtId)/invalidCount k64u integer

Number of invalid values.


30007 Gocator Output Id InvalidCnt
/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "measurement" in this case.


N/A N/A N/A

Arrayed measurement statistics are per tool output:

1.2.x.x Added









/outputsByExtId/(outputExtId)/value std::vector array

Array of measurement values.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/value/n k64f number

Measurement Value.

Could be null if a scan hasn't been acquired yet or was invalid.


30000 Gocator Output Id Value
/outputsByExtId/(outputExtId)/passCount std::vector array

Array of pass decisions.





/outputsByExtId/(outputExtId)/passCount/n k64u integer

Number of pass decisions.


30001 Gocator Output Id PassCnt
/outputsByExtId/(outputExtId)/failCount std::vector array

Array of fail decisions.





/outputsByExtId/(outputExtId)/failCount/n k64u integer

Number of fail decisions.


30002 Gocator Output Id FailCnt
/outputsByExtId/(outputExtId)/lastDecision std::vector array

Array containing the most recent decision for each measurement.





/outputsByExtId/(outputExtId)/lastDecision/n k8s integer

Most recent decision (pass/fail/invalid).

pass = 1
fail = 0
invalid = null


N/A N/A N/A
/outputsByExtId/(outputExtId)/max std::vector array

Array of maximum measurement values.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/max/n k64f number

Maximum measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30003 Gocator Output Id Max
/outputsByExtId/(outputExtId)/min std::vector array

Array of minimum measurement values.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/min/n k64f number

Minimum measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30004 Gocator Output Id Min
/outputsByExtId/(outputExtId)/range std::vector array

Array of measurement range values.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/range/n k64f number

Measurement range value.

Could be null if a scan hasn't been acquired yet or was invalid.


N/A N/A N/A
/outputsByExtId/(outputExtId)/avg std::vector array

Array of average measurement values.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/avg/n k64f number

Average measurement value.

Could be null if a scan hasn't been acquired yet or was invalid.


30005 Gocator Output Id Average
/outputsByExtId/(outputExtId)/stdDev std::vector array

Array of measurement value standard deviations.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/stdDev/n k64f number

Measurement value standard deviation.

Could be null if a scan hasn't been acquired yet or was invalid.


30006 Gocator Output Id StdDev
/outputsByExtId/(outputExtId)/invalidCount std::vector array

Array of invalid values.





/outputsByExtId/(outputExtId)/invalidCount/n k64u integer

Number of invalid values.


30007 Gocator Output Id InvalidCnt
/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "measurementArray" in this case.


N/A N/A N/A
Point features are per tool output:







/outputsByExtId/(outputExtId)/posX k64f number

Point feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY k64f number

Point feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ k64f number

Point feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "pointFeature" in this case.


N/A N/A N/A

Arrayed point features are per tool output:

1.2.x.x Added









/outputsByExtId/(outputExtId)/posX std::vector array

Array containing each point feature's position X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posX/n k64f number

Point feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY std::vector array

Array containing each point feature's position Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY/n k64f number

Point feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ std::vector array

Array containing each point feature's position Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ/n k64f number

Point feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "pointFeatureArray" in this case.


N/A N/A N/A
Line features are per tool output:







/outputsByExtId/(outputExtId)/posX k64f number

Line feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY k64f number

Line feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ k64f number

Line feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirX k64f number

Line feature direction X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirY k64f number

Line feature direction Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirZ k64f number

Line feature direction Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "lineFeature" in this case.


N/A N/A N/A

Arrayed line features are per tool output:

1.2.x.x Added









/outputsByExtId/(outputExtId)/posX std::vector array

Array containing each line feature position X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posX/n k64f number

Line feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY std::vector array

Array containing each line feature position Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY/n k64f number

Line feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ std::vector array

Array containing each line feature position Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ/n k64f number

Line feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirX std::vector array

Array containing each line feature direction X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirX/n k64f number

Line feature direction X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirY std::vector array

Array containing each line feature direction Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirY/n k64f number

Line feature direction Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirZ std::vector array

Array containing each line feature direction Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/dirZ/n k64f number

Line feature direction Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "lineFeatureArray" in this case.


N/A N/A N/A
Plane features are per tool output:







/outputsByExtId/(outputExtId)/normalX k64f number

Plane feature normal X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY k64f number

Plane feature normal Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ k64f number

Plane feature normal Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/originDistance k64f number

Plane feature origin distance.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "planeFeature" in this case.


N/A N/A N/A

Arrayed plane features are per tool output:

1.2.x.x Added









/outputsByExtId/(outputExtId)/normalX std::vector array

Array containing each plane feature normal X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalX/n k64f number

Plane feature normal X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY std::vector array

Array containing each plane feature normal Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY/n k64f number

Plane feature normal Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ std::vector array

Array containing each plane feature normal Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ/n k64f number

Plane feature normal Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/originDistance std::vector array

Array containing each plane feature origin distance.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/originDistance/n k64f number

Plane feature origin distance.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "planeFeatureArray" in this case.


N/A N/A N/A
Circle features are per tool output:







/outputsByExtId/(outputExtId)/posX k64f number

Circle feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY k64f number

Circle feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ k64f number

Circle feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalX k64f number

Circle feature normal X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY k64f number

Circle feature normal Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ k64f number

Circle feature normal Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/radius k64f number

Circle feature radius.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "circleFeature" in this case.


N/A N/A N/A

Arrayed circle features are per tool output:

1.2.x.x Added









/outputsByExtId/(outputExtId)/posX std::vector array

Array containing each circle feature position X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posX/n k64f number

Circle feature position X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY std::vector array

Array containing each circle feature position Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posY/n k64f number

Circle feature position Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ std::vector array

Array containing each circle feature position Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/posZ/n k64f number

Circle feature position Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalX std::vector array

Array containing each circle feature normal X.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalX/n k64f number

Circle feature normal X.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY std::vector array

Array containing each circle feature normal Y.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalY/n k64f number

Circle feature normal Y.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ std::vector array

Array containing each circle feature normal Z.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/normalZ/n k64f number

Circle feature normal Z.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/radius std::vector array

Array containing each circle feature radius.

Could be empty if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/radius/n k64f number

Circle feature radius.

Could be null if a scan hasn't been acquired yet or was invalid.





/outputsByExtId/(outputExtId)/type std::string string

string denoting output type - "circleFeatureArray" in this case.


N/A N/A N/A

Methods

Method Description
read

Reads the latest tool metrics.

Path parameters: extId

Example: 

read /tools/ProfileLine-0/metrics
read /tools/extId=My%20Tool%20Id/metrics

which for example returns: 

{
  "payload": {
    "_links": {
      "self": {
        "href": "/tools/ProfileLine-0/metrics"
      }
    },
    "outputsByExtId": {
      "Angle": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "ArithmeticAverage": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "Line": {
        "dirX": null,
        "dirY": null,
        "dirZ": null,
        "posX": null,
        "posY": null,
        "posZ": null,
        "type": "lineFeature"
      },
      "MaxErrPoint": {
        "posX": null,
        "posY": null,
        "posZ": null,
        "type": "pointFeature"
      },
      "MaxError": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "MaxErrorX": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "MaxErrorZ": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "MinErrPoint": {
        "posX": null,
        "posY": null,
        "posZ": null,
        "type": "pointFeature"
      },
      "MinError": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "MinErrorX": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "MinErrorZ": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "Offset": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "Percentile": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "RZ": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "StdDev": {
        "avg": null,
        "failCount": 0,
        "invalidCount": 0,
        "lastDecision": null,
        "max": null,
        "min": null,
        "passCount": 0,
        "range": null,
        "stdDev": null,
        "type": "measurement",
        "value": null
      },
      "arrayedMeasurement": { // Profile Line doesn't actually have any arrayed measurements, but this shows what arrayed measurement looks like.
        "avg": [
          100.0,
          -100.0,
          null
        ],
        "failCount": [
          0,
          31,
          0
        ],
        "invalidCount": [
          0,
          0,
          31
        ],
        "lastDecision": [
          1,
          0,
          null
        ],
        "max": [
          100.0,
          -100.0,
          null
        ],
        "min": [
          100.0,
          -100.0,
          null
        ],
        "passCount": [
          31,
          0,
          0
        ],
        "range": [
          0.0,
          0.0,
          null
        ],
        "stdDev": [
          0.0,
          0.0,
          null
        ],
        "type": "measurementArray",
        "value": [
          100.0,
          -100.0,
          null
        ]
      }
    },
    "toolStats": {
      "runTime": 0,
      "runTimeAvg": 0,
      "runTimeAvgPerc": 0,
      "runTimeMax": 0,
      "runTimeMin": 0
    }
  },
  "status": 1,
  "type": "response"
}
stream

Receive continuous stream of tool metrics.

Path parameters: extId

Example: 

stream /tools/ProfileLine-0/metrics
stream /tools/extId=My%20Tool%20Id/metrics
cancelStream

Cancel continuous stream of tool metrics.

Path parameters: extId

Example: 

cancelStream /tools/ProfileLine-0/metrics
cancelStream /tools/extId=My%20Tool/metrics

/tools/(toolId)/actions

Resource Type: N/A

Array of callable custom actions provided by the tool developer. Note that this isnot a collection resource ; it is a resource that contains an array.

Methods

Method Description
read

Reading from /tools/(id)/actions will return an array of links to custom actions provided by the tool developer.

Example: 

read /tools/TestActions-0/actions

/tools/(toolId)/actions/(actionId)

Resource Type: (Callable)

ID: Named by the tool developer

Path parameters: by " extId", see methods table for which methods support path parameters.

To invoke the command through the protocol, do a call on the path given e.g call /tools/tool1/actions/reset

Each tool action has the following common schema properties:

Item Type Schema Description
id string readOnly

An ID of the Tool Action that uniquely identifies the registered action.

displayName culture-specific string readOnly Display name of the tool action.
parameters object
parameters object containing list of arguments the action accepts
message string readOnly Message component of the action if used.

Methods

Method Description
call

Calls the custom tool action.

As of build 1.2.1.245, actions with params are now supported

Example: 

call /tools/TestActions-0/actions/FlipBool
call /tools/TestActions-0/actions/IncrementIntByVal {"intVal":123}

Notifications

None. Although the action itself doesn't raise an event notification, the side effects of a custom action could result in event notifications upon the parent tool (see /tools/(id) -- Notifications ).

GoPxL: Control Resources


/controls

Resource Type: (Collection - Unordered)

A collection of control services. The list of control services is determined by the available control services loaded in the system. Control services in this unordered collection cannot be created or deleted .

Properties

None

Methods

Method Description
read

Return list of control services available in the system

Example :

Read Resource 
read /controls

Example Response :

Read Resource Response 
{
  "path": "/controls",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/modbus"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.



GoPxL: GoPxL Data Protocol (GDP) Resources

This page describes the control service resource called GoPxL Data Protocol (GDP) Service that is included with each LMI Gocator release.

/controls/gocator

Resource Type: (Standard)

GDP resource supports the following properties:

Properties

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "Gocator"

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "gocator".

parameters object

Parameter settings applicable to the service.

parameters/timeoutEnabled

boolean


When set to true, operation to send data to the client can timeout, which would then cause the connection to close automatically.
parameters/timeout number

minimum,

maximum

The timeout value in seconds.

Minimum value = 0 seconds.

Maximum value = 300 seconds.

status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

serverPort integer readOnly

Added in version 1.2.x.x .

The network port that GoPxL Data Protocol service uses.

Methods

Method Description
read

Return property information about the service resource.

Example :

Read Resource 
read /controls/gocator

Example Response :

Read Resource Response 
{
  "path": "/controls/gocator",
  "payload": {
    "_embedded": {
      "go:datasources": {
        "_links": {
          "self": {
            "href": "/controls/gocator/outputs"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/controls/gocator"
      }
    },
    "displayName": "Gocator",
    "enabled": true,
    "id": "gocator",
  	"serverPort": 3601,
    "parameters": {
      "timeout": 1.0,
      "timeoutEnabled": false
    },
    "status": 0
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/gocator

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/gocator",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/gocator

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/gocator",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/gocator {"enabled" : true}
update /controls/gocator {"enabled" : false}
update /controls/gocator {"enabled" : true, "parameters" : {"timeoutEnabled":true,"timeout":1.2}}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/gocator",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request:
update /controls/gocator {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/gocator",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/gocator/metrics

The GDP metrics resource supports these metrics:

Item Type Schema Description
controlDrops integer

0.3.x.x added this metric.

Number of dropped scan results.

ethernetOutput integer

Number of bytes sent out by the Gocator Data Protocol over the Ethernet interface via TCP.

ethernetOutputCount integer
Number of messages sent by the Gocator Data Protocol over the Ethernet interface via TCP.
ethernetRate integer
The rate of transmission out the Ethernet interface in bytes per second over the Ethernet interface via TCP.
inputBufferMsgCount integer
Current number of messages in Gocator Data Protocol's input buffer(s). This buffer is used to temporarily store the messages as they are received by the Gocator Data Protocol.
maxInputBufferMsgCount integer
Maximum number of messages that Gocator Data Protocol's input buffer(s) can contain.
outputBufferMsgCount integer
Current number of messages in Gocator Data Protocol's output buffer(s). This buffer is used to store messages destined to Gocator Data Protocol clients.
maxOutputBufferMsgCount integer
Maximum number of messages that Gocator Data Protocol's output buffer(s) can contain.

ethernetOutput will keep its last known value during the following scenarios:

  • Sensor group stops producing data, ie, sensor stopped scanning
  • All GDP outputs unselected.
  • No GDP clients, ie, last GDP client disconnects from the server.

ethernetOutput will reset to 0 when scanning starts again.

ethernetRate is calculated upon every metrics refresh/update trigger, currently at 4 times a second.

  • If no data is transferred during an update period, then the ethernetRate will be shown as 0 for that period.

controlDrops may happen for various reasons,

  • TCP/GDP client is not able to clear its received buffer, thus GDP cannot sent its data.
  • Sensor group is producing data too fast for the TCP stack or overall software to handle.

When controlDrops happens, it is likely for the same metric update period, the ethernetOutput does not increment (no additional data is sent), and ethernetRate is likely 0 (no additional data is sent in a given time).

Note that when GDP server is not able to handle the rate of incoming messages resulting in controlDrops, one or more of the following conditions may also occur:

  • Camera buffer drop.
  • Processing drop.
  • Other drops elsewhere

When inputBufferMsgCount reaches maxInputBufferMsgCount, controlDrops happen.

Both maxInputBufferMsgCount and maxOutputBufferMsgCount are dependent on the following,

  • number of GDP clients
  • number of GDP outputs

The number of GDP clients and outputs are multiplied with the number of results each buffer can contain to get the maximum number of messages. The one exception is that when there are no GDP outputs, the maximum number becomes the number of GDP clients multiplied by the number of results each buffer can contain.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/gocator/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/gocator/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/metrics"
      }
    },
    "controlDrops": 0,
    "ethernetOutput": 0,
    "ethernetOutputCount": 0,
    "ethernetRate": 0,
    "inputBufferMsgCount": 0,
    "maxInputBufferMsgCount": 0,
    "maxOutputBufferMsgCount": 0,
    "outputBufferMsgCount": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/gocator/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/gocator/metrics",
  "payload": {
    "path": "/controls/gocator/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/gocator/metrics",
  "payload": {
    "controlDrops": 0,
    "ethernetOutput": 0,
    "ethernetOutputCount": 0,
    "ethernetRate": 0,
    "inputBufferMsgCount": 0,
    "maxInputBufferMsgCount": 0,
    "maxOutputBufferMsgCount": 0,
    "outputBufferMsgCount": 0
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/gocator/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/gocator/metrics",
  "payload": {
    "path": "/controls/gocator/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/gocator/outputs

Resource Type: (Observable)

This resource contains a list of data source outputs whose data are to be outputted through the service to the control service client.

Properties

Item Type Schema Description
acceptedDataFormats array readOnly

Array of data formats accepted by the service's outputs map.

This service currently only supports one data format.

acceptedDataFormats/n/ DataFormat
A data format entry.
acceptedDataFormats/n/arrayed boolean
Value is set to false.
acceptedDataFormats/n/type integer
Value is set to 19 (Measurement).
attributes object

Attributes of this service's outputs map.

attributes/outputIdMin integer readOnly

0.3.x.x added this field.

The minimum output id value for a standard output item.

Value is set to zero (0).

attributes/outputIdMax integer readOnly

0.3.x.x added this field.

The maximum output id value for a standard output item.

Value is set to 2 16 -2.

Reserved Output Id Value

Value of 2 16 -1 is reserved for internal use.

Output Id Value Limit

If the client enters an output id value that is greater than 2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the 16-bit output id will be processed as 0x0001 which is equal to 1.

map array

Array of data source output items configured by the user.

map/n/ object
A data source output item.
map/n/outputId integer

A numeric id used to uniquely identify the data source for this outputs map.

Valid range is from attributes/outputIdMin to attributes/outputIdMax, inclusive.

map/n/source string
Data source identifier.
version string readOnly

1.2.x.x Outputs map version.

Methods

Method Description
read

Read the outputs map from the resource. The response includes the data sources current configured for this service.

The response also includes CALL command request resource paths to operate on this resource,

Example :

Read Outputs Map 
read /controls/gocator/outputs

Example Response:

Read Outputs Map Response 
{
  "path": "/controls/gocator/outputs",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/gocator/outputs/commands/add"
        },
        {
          "href": "/controls/gocator/outputs/commands/addAll"
        },
        {
          "href": "/controls/gocator/outputs/commands/remove"
        },
        {
          "href": "/controls/gocator/outputs/commands/removeAll"
        },
        {
          "href": "/controls/gocator/outputs/commands/compactId"
        },
        {
          "href": "/controls/gocator/outputs/commands/updateId"
        }
      ],
      "self": {
        "href": "/controls/gocator/outputs"
      }
    },
    "acceptedDataFormats": [
      {
        "arrayed": false,
        "type": 19
      }
    ],
    "attributes": {
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "map": [
      {
        "outputId": 0,
        "source": "scan:LMILaserLineProfiler:scanner-0:stamp"
      },
      {
        "outputId": 1,
        "source": "scan:LMILaserLineProfiler:scanner-0:topUniformProfile"
      },
      {
        "outputId": 2,
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      },
      {
        "outputId": 3,
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": 4,
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      }
    ],
    "version": "1.2",
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Outputs Map 
sub /controls/gocator/outputs

Example Response:

Subscribe Outputs Map Notification 
{
  "path": "/controls/gocator/outputs",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving outputs map resource updates.

Example:

Unsubscribe Outputs Map 
unSub /controls/gocator/outputs

Example Response:

Unsubscribe Outputs Map Response 
{
  "path": "/controls/gocator/outputs",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the outputs map resource has changed.

Example:

Outputs Map Notification 
Request:
call /controls/gocator/outputs/commands/add{"source": "scan:LMILaserLineProfiler:scanner-0:stamp", "outputId" : 0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/gocator/outputs",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/gocator/outputs/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's outputs map. These commands can be used to modify the data sources inside the outputs maps array of data sources called map.

Methods

Method Description
read

Returns a list of outputs map commands as embedded resources.

Example:

Read Outputs Map Commands 
read /controls/gocator/outputs/commands

Example Response:

Read Outputs Map Commands Response 
{
  "path": "/controls/gocator/outputs/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/addAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/remove"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/compactId"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs/commands/updateId"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one data source entry to the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

outputId

integer

Optional

The output id value to assign to the data source entry.

If not provided as an argument, the output identifier value is automatically set to the next value after the current highest output identifier value used.

Range of value is between attributes/outputIdMin and attributes/outputIdMax.

If not provided as an argument, then the data source is added after the data source.

source

string

Mandatory

The data source to add to the outputs map.

Methods

Method
read

Return the name of the command.

Example:

Read Outputs Map Command Add 
read /controls/gocator/outputs/commands/add

Example Response:

Read Outputs Map Command Add Response 
{
  "path": "/controls/gocator/outputs/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/add"
      }
    },
    "id": "add"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Add Data Source 
call /controls/gocator/outputs/commands/add {"source": "tools:ProfileInfo-0:outputs:MaxZ", "outputId":0}
call /controls/gocator/outputs/commands/add {"source": "tools:ProfileInfo-0:outputs:MinZ", "outputId":1}

call /controls/gocator/outputs/commands/add {"source": "tools:ProfileInfo-0:outputs:MaxZ", "outputId":0, "autoShift", true}
call /controls/gocator/outputs/commands/add {"source": "tools:ProfileInfo-0:outputs:MinZ", "outputId":1, "autoShift", false}

Example Response:

Add Data Source Response 
{
  "path": "/controls/gocator/outputs/commands/add",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/addAll

Resource Type: (CollectionItem , Callable)

Command to add multiple data source entries to the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

map

array

Mandatory

An array of data source items.

map/n/

object

An data source item.

Each item is appended to the end of the outputs map. The output identifier is auto-generated.

map/n/outputId

integer

n/a

This argument is ignored because the output identifiers are auto-generated for each entry.

map/n/source

string

Mandatory

The data source to add to the outputs map.

map/n/itemType

string

Optional

Describes whether this data source was added by SDK/GoPxL UI or GoHMI Designer.

When adding from SDK or GoPxL GUI, skip this field or set it to gopxl.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command AddAll 
read /controls/gocator/outputs/commands/addAll

Example Response:

Read Outputs Map Command AddAll Response 
{
  "path": "/controls/gocator/outputs/commands/addAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/addAll"
      }
    },
    "id": "addAll"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Add Multiple Data Sources 
call /controls/gocator/outputs/commands/addAll {"map": [ { "source": "tools:ProfileInfo-0:outputs:MaxZ" }, { "source": "tools:ProfileInfo-1:outputs:MinZ" }, { "source": "tools:ProfileInfo-1:outputs:PointCount" } ] }

Example Response:

Add Multiple Data Sources Response 
Request response
{
  "path": "/controls/gocator/outputs/commands/addAll ",
  "payload": null,
  "status": 1,
  "type": "response"
}

Example of adding multiple data sources, with the output identifier being auto-generated so that the entries are appended to the end of a previously empty outputs map:
     - call /controls/gocator/outputs/commands/addAll {"map": [ { "source": "tools:ProfileInfo-0:outputs:MaxZ" }, { "source": "tools:ProfileInfo-1:outputs:MinZ" }, { "source": "tools:ProfileInfo-1:outputs:PointCount" } ] }

{
  "path": "/controls/gocator/outputs",
...
    "map": [
      {
        "outputId": 0,
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": 1,
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": 2,
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/compactId

Resource Type: (CollectionItem , Callable)

Command to remove gaps in the outputs maps output identifiers so that the output identifiers are sequential and contiguous.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command CompactId 
read /controls/gocator/outputs/commands/compactId

Example Response:

Read Outputs Map Command CompactId Response 
{
  "path": "/controls/gocator/outputs/commands/compactId",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/compactId"
      }
    },
    "id": "compactId"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

The starting output identifier value for the compacting operation is always zero (0).

Example:

Compact Output Ids 
call /controls/gocator/outputs/commands/compactId

Example Response:

Compact Output Ids Response 
Request response:
{
  "path": "/controls/gocator/outputs/commands/compactId",
  "payload": null,
  "status": 1,
  "type": "response"
}

BEFORE compacting:
{
  "path": "/controls/gocator/outputs",
...
    "map": [
      {
        "outputId": 9,
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": 19,
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": 20,
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

AFTER compacting:
{
  "path": "/controls/gocator/outputs",
...
    "map": [
      {
        "outputId": 0,                   <-------------------------------
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": 1,                   <-------------------------------
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": 2,                   <-------------------------------
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one data source entry from the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputId

integer

Optional *

The output id of the data source to remove from the outputs map

outputIdList

list of integers

Optional *

A list of output ids of the data sources to remove from the outputs map.

* The remove command requires exactly one of the two command arguments to be included.

Methods

Method
read

Return the name of the command.

Example:

Read Outputs Map Command Remove 
read /controls/gocator/outputs/commands/remove

Example Response:

Read Outputs Map Command Remove Response 
{
  "path": "/controls/gocator/outputs/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/remove"
      }
    },
    "id": "remove"
  },
  "status": 1,
  "type": "response"
}

call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Remove Data Source 
call /controls/gocator/outputs/commands/remove {"outputId":0}
call /controls/gocator/outputs/commands/remove {"outputId":1}
call /controls/gocator/outputs/commands/remove {"outputIdList": [0, 1]}

Example Response:

Remove Data Source Response 
{
  "path": "/controls/gocator/outputs/commands/remove",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all data source entries from the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command RemoveAll 
read /controls/gocator/outputs/commands/removeAll

Example Response:

Read Outputs Map Command RemoveAll Response 
{
  "path": "/controls/gocator/outputs/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/removeAll"
      }
    },
    "id": "removeAll"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Examples:

Remove All Entries 
call controls/gocator/outputs/commands/removeAll

Example Response:

Remove All Response 
Request response:
{
  "path": "/controls/gocator/outputs/commands/removeAll",
  "payload": null,
  "status": 1,
  "type": "response"
}

BEFORE removal:
{
  "path": "/controls/gocator/outputs",
...
    "map": [
      {
        "outputId": 0,
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": 1,
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": 2,
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

AFTER removal:
{
  "path": "/controls/gocator/outputs",
...
    "map": []                <-------------------------------
...
}

Notifications

None generated for this resource.

/controls/gocator/outputs/commands/updateId

Resource Type: (CollectionItem , Callable)

Command to change the output id of a data source entry in the outputs map.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

map

array

Mandatory

An array of two integer output identifiers.

map/n/

integer

Output identifier integer

map/0/outputId

integer

The old output id to change

map/1/outputId

integer

The new value of the output id.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command UpdateId 
read /controls/gocator/outputs/commands/updateId

Example Response:

Read Outputs Map Command UpdateId Response 
{
  "path": "/controls/gocator/outputs/commands/updateId",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs/commands/updateId"
      }
    },
    "id": "updateId"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Update Data Source Output Id 
// Change entry with outputId 0 to outputId 1, only when no overlap condition is detected.
call /controls/gocator/outputs/commands/updateId {"map": [{"outputId": 0}, {"outputId": 1}]} 

// Change entry with outputId 0 to outputId 1, only when no overlap condition is detected.
call /controls/gocator/outputs/commands/updateId {"map": [{"outputId": 0}, {"outputId": 1}], "autoShift": false} 

// Change entry with outputId 0 to outputId 1, even when overlap condition is detected.
call /controls/gocator/outputs/commands/updateId {"map": [{"outputId": 0}, {"outputId": 1}], "autoShift": true}

Example Response:

Update Data Source Output Id Response 
{
  "path": "/controls/gocator/outputs/commands/updateId",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.




GoPxL: HMI Resources

This page describes the control service resource called HMI Service that is included with each LMI Gocator release.

/controls/hmi

Resource Type: (Standard)

HMI resource supports the following properties:

Properties:

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "HMI".

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "hmi".

parameters object readOnly Parameter settings applicable to the service.
parameters/appUrl string

The web URL used to connect to the HMI application. Defaults value is "Undefined".

This is updated automatically to a valid web URL when the HMI application is started.

parameters/appName string
The name of the HMI application. Defaults value is "GoHMI".
parameters/appState integer enum

The status of the HMI application.

Values are:

0 = Service Not Started:

  • HMI control service is not enabled (started).

1 = Ready:

  • HMI application is ready to use.

2 = Running:

  • HMI application is running (activated).

2 = Not Found:

  • HMI application was not found.

3 = Has Workspace:

  • HMI application has a workspace because the HMI Application has been loaded into the WebIQ Designer.

4 = Not Compatible:

  • HMI application was created with higher version of WebIQ Connect than the one that is being used by the GoPxL.

5 = Error:

  • Unexpected WebIQ Connect API call error.

6 = Connect Is Already Up:

  • WebIQ Connect is already running so this HMI control service cannot be started.The WebIQ Connect might have been started by another GoPxL instance (by enabling/starting HMI control service on that GoPxL instance).

7 = Service Is Launching:

  • HMI control service has been enabled and is starting up.

8 = Application Is Stopping:

  • HMI application is being stopped.

1.1.x.x 1.2.x.x Removed "Running" (value equal to 2) status and renumbered the status values.

parameters/connectVersion string
The version of the Smart HMI WebIQ Connect that is running on the same platform as the Gocator software.
status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

Methods

Method Description
read

Return property information about the service resource.

Example:

Read Resource 
read /controls/hmi

Example Response:

Read Resource Response 
{
  "path": "/controls/hmi",
  "payload": {
    "_embedded": {
      "go:datasources": {
        "_links": {
          "self": {
            "href": "/controls/hmi/outputs"
          }
        }
      }
    },
    "_links": {
      "go:command": [
        {
          "href": "/controls/hmi/commands/activate"
        },
        {
          "href": "/controls/hmi/commands/createApp"
        },
        {
          "href": "/controls/hmi/commands/removeApp"
        },
        {
          "href": "/controls/hmi/commands/downloadApp"
        },
        {
          "href": "/controls/hmi/commands/uploadApp"
        }, 
		{ 
		  "href": "/controls/hmi/commands/discardWorkspace" 
		}
      ],
      "self": {
        "href": "/controls/hmi"
      }
    },
    "displayName": "HMI",
    "enabled": true,
    "id": "hmi",
    "parameters": {
      "appId": "GoHMI",
      "appName": "GoHMI",
      "appState": 0,
      "appUrl": "Undefined",
      "connectVersion": "2.14.1"
    },
    "status": 2
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/hmi

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/hmi",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/hmi

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/hmi",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/hmi {"enabled" : true}
update /controls/hmi {"enabled" : false}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/hmi",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request:
update /controls/hmi {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/hmi",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/hmi/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/hmi/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/hmi/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/hmi/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/hmi/metrics",
  "payload": {
    "path": "/controls/hmi/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}


// Streamed metrics contents
{
  "path": "/controls/hmi/metrics",
  "payload": {
    "controlDrops": 0,
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/hmi/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/hmi/metrics",
  "payload": {
    "path": "/controls/hmi/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/outputs

Resource Type: (Observable)

This resource contains a list of data source outputs whose data are to be outputted through the service to the control service client.

Properties

Item Type Schema Description
acceptedDataFormats array readOnly

Array of data formats accepted by the service's outputs map.

This service currently only supports one data format.

acceptedDataFormats/n/ DataFormat
A data format entry.
acceptedDataFormats/n/type integer
Value is set to 19 (Measurement).
acceptedDataFormats/n/arrayed

boolean


Value is set to false.
map array
Array of data source output items configured by the user.
map/n/ object
A data source output item.
map/n/ itemType string readOnly

Added in 1.2.x.x

Indicates whether this data source was added using the GoPxL UI or SDK or the GoHMI Designer UI.

Values are one of the following:

  • "undefined"
    • either not added using either SDK or GoPxL / GoHMI Designer UI or was added before the introduction of this field.
  • "gopxl"
    • added using GoPxL UI or SDK
  • "designer"
    • added using GoHMI Designer UI
map/n/outputId string
A unique text identifier for the data source.
map/n/source string
Data source identifier.
version string readOnly 1.2.x.x Ouputs map version.

Methods

Method Description
read

Read the outputs map from the resource. The response includes the data sources current configured for this service.

The response also includes CALL command request resource paths to operate on this resource,

Example:

Read Outputs Map 
read /controls/hmi/outputs

Example Response:

Read Outputs Map Response 
{
  "path": "/controls/hmi/outputs",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/hmi/outputs/commands/add"
        },
        {
          "href": "/controls/hmi/outputs/commands/addAll"
        },
        {
          "href": "/controls/hmi/outputs/commands/remove"
        },
        {
          "href": "/controls/hmi/outputs/commands/removeAll"
        },
        {
          "href": "/controls/hmi/outputs/commands/compactId"
        },
        {
          "href": "/controls/hmi/outputs/commands/updateId"
        }
      ],
      "self": {
        "href": "/controls/hmi/outputs"
      }
    },
    "acceptedDataFormats": [
      {
        "arrayed": false,
        "type": 19
      }
    ],
    "map": [
      {
        "itemType": "designer",
        "outputId": "Application Type",
        "source": "/environ/info/#applicationType"
      },
      {
        "itemType": "designer",
        "outputId": "Application Uptime",
        "source": "/system/metrics/#appUpTime"
      },
      {
        "itemType": "gopxl",
        "outputId": "Profile Position 1/X.lastDecision",
        "source": "/tools/extId=ProfilePosition-2/metrics#/outputsByExtId/X/lastDecision"
      },
      {
        "itemType": "gopxl",
        "outputId": "Profile Position 1/X.value",
        "source": "/tools/extId=ProfilePosition-2/metrics#/outputsByExtId/X/value"
      },
      {
        "itemType": "designer",
        "outputId": "System Uptime",
        "source": "/system/metrics/#upTime"
      }
    ],
    "version": "1.2"
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Outputs Map 
sub /controls/hmi/outputs

Example Response:

Subscribe Outputs Map Notification 
{
  "path": "/controls/hmi/outputs",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving outputs map resource updates.

Example:

Unsubscribe Outputs Map 
unSub /controls/hmi/outputs

Example Response:

Unsubscribe Outputs Map Response 
{
  "path": "/controls/hmi/outputs",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the outputs map resource has changed.

Example:

Outputs Map Notification 
Request:
call /controls/hmi/outputs/commands/add{"source": "scan:LMILaserLineProfiler:scanner-0:stamp", "outputId" : 0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/hmi/outputs",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/hmi/outputs/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's outputs map. These commands can be used to modify the data sources inside the outputs maps array of data sources called map.

Methods

Method Description
read

Returns a list of outputs map commands as embedded resources.

Example:

Read Outputs Map Commands 
read /controls/hmi/outputs/commands

Example Response:

Read Outputs Map Commands Response 
{
  "path": "/controls/hmi/outputs/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/addAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/remove"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/compactId"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/outputs/commands/updateId"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one data source entry to the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

This argument is not supported by this service because the output identifier text cannot be shifted.

Therefore this argument is ignored by the service.

outputId

string

Optional

The text output id value to assign to the data source entry.

If not provided as an argument, the output identifier value is automatically set to be the data source source.

source

string

Mandatory

The data source to add to the outputs map.

itemType

string

Optional

Describes whether this data source was added by SDK/GoPxL UI or GoHMI Designer.

When adding from SDK or GoPxL GUI, skip this field or set it to gopxl.

Methods

Method
read

Return the name of the command.

Example:

Read Outputs Map Command Add 
read /controls/hmi/outputs/commands/add

Example Response:

Read Outputs Map Command Add Response 
{
  "path": "/controls/hmi/outputs/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/add"
      }
    },
    "id": "add"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Add Data Source 
call /controls/hmi/outputs/commands/add {"source":"tools:ProfileInfo-0:outputs:MaxZ", "outputId": "foo", "itemType": "gopxl"}

Example Response:

Add Data Source Response 
{
  "path": "/controls/hmi/outputs/commands/add",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/addAll

Resource Type: (CollectionItem , Callable)

Command to add multiple data source entries to the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

map

array

Mandatory

An array of data source items.

map/n/

object

An data source item.

Each item is appended to the end of the outputs map.

map/n/outputId

string

Optional

If this argument is not provided, then the data source text is used as the output identifier.

map/n/source

string

Mandatory

The data source to add to the outputs map.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command AddAll 
read /controls/hmi/outputs/commands/addAll

Example Response:

Read Outputs Map Command AddAll Response 
{
  "path": "/controls/hmi/outputs/commands/addAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/addAll"
      }
    },
    "id": "addAll"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

For the AddAll command, the output id arguments are optional. If they are missing, they will be auto-generated using the "source" string.
If it is present, then the client provided output identifier is used.

Example:

Add Multiple Data Sources 
// Specify the output identifier for each entry.
call /controls/hmi/outputs/commands/addAll {"map":[{"source":"tools:ProfileInfo-0:outputs:MaxZ", "outputId":"first"},{"source":"tools:ProfileInfo-0:outputs:MinZ", "outputId":"second"},{"source":"tools:ProfileInfo-0:outputs:PointCount", "outputId":"third"}]}

// Use the data source as the output identifier by explicitly not specifying an output identifier in the request.
call /controls/hmi/outputs/commands/addAll {"map":[{"source":"tools:ProfileInfo-0:outputs:MaxZ"},{"source":"tools:ProfileInfo-0:outputs:MinZ"},{"source":"tools:ProfileInfo-0:outputs:PointCount"}]}

Example Response:

Add Multiple Data Sources Response 
Request Response:
{
  "path": "/controls/hmi/outputs/commands/addAll ",
  "payload": null,
  "status": 1,
  "type": "response"
}

Example of adding multiple data sources with explicit output id:
{
  "path": "/controls/hmi/outputs",
...
    "map": [
      {
        "outputId": "first",
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": "second",
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": "third",
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

Example of adding multiple data sources without specifying the output identifier:
{
  "path": "/controls/hmi/outputs",
...
    "map": [
      {
        "outputId": "tools:ProfileInfo-0:outputs:MaxZ",
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": "tools:ProfileInfo-0:outputs:MinZ",
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": "tools:ProfileInfo-0:outputs:PointCount",
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/compactId

Resource Type: (CollectionItem , Callable)

This command to remove gaps in the outputs maps output identifiers so that the output identifiers are sequential and contiguous.
However, because the output identifiers for this resource are text strings, compacting is not meaningful, so this command is not applicable to this resource. The command request is accepted but does not do anything.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command CompactId 
read /controls/hmi/outputs/commands/compactId

Example Response:

Read Outputs Map Command CompactId Response 
{
  "path": "/controls/hmi/outputs/commands/compactId",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/compactId"
      }
    },
    "id": "compactId"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

For this service, this request does not do anything because the textual output identifiers cannot be compacted.

However, the request is still accepted as a valid request.


Example:

Compact Output Ids 
call /controls/hmi/outputs/commands/compactId

Example Response:

Compact Output Ids Response 
Request response:
{
  "path": "/controls/hmi/outputs/commands/compactId",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more data source entry/entries from the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputId

string

Optional *

The output identifier of the data source to remove from the outputs map

outputIdList

list of strings

Optional *

Added in version 1.2.x.x

A list of output ids of the data sources to remove from the outputs map.

* The remove command requires exactly one of the two command arguments to be included.

Methods

Method
read

Return the name of the command.

Example:

Read Outputs Map Command Remove 
read /controls/hmi/outputs/commands/remove

Example Response:

Read Outputs Map Command Remove Response 
{
  "path": "/controls/hmi/outputs/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/remove"
      }
    },
    "id": "remove"
  },
  "status": 1,
  "type": "response"
}

call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Remove Data Source 
call /controls/hmi/outputs/commands/remove {"outputId":"tools:ProfileInfo-0:outputs:MinZ"}
call /controls/hmi/outputs/commands/remove {"outputIdList": ["tools:ProfileInfo-0:outputs:MinZ", "tools:ProfileInfo-0:outputs:MinX"]}

Example Response:

Remove Data Source Response 
{
  "path": "/controls/hmi/outputs/commands/remove",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all data source entries from the outputs map.

Reading this resource returns the name of this command.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command RemoveAll 
read /controls/hmi/outputs/commands/removeAll

Example Response:

Read Outputs Map Command RemoveAll Response 
{
  "path": "/controls/hmi/outputs/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/removeAll"
      }
    },
    "id": "removeAll"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Examples:

Remove All Entries 
call controls/hmi/outputs/commands/removeAll

Example Response:

Remove All Response 
Request response:
{
  "path": "/controls/hmi/outputs/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/removeAll"
      }
    },
    "id": "removeAll"
  },
  "status": 1,
  "type": "response"
}

BEFORE removal:
{
  "path": "/controls/hmi/outputs",
...
    "map": [
      {
        "outputId": "first",
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": "second",
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": "third",
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

AFTER removal:
{
  "path": "/controls/hmi/outputs",
...
    "map": []                <-------------------------------
...
}

Notifications

None generated for this resource.

/controls/hmi/outputs/commands/updateId

Resource Type: (CollectionItem , Callable)

Command to change the output id of a data source entry in the outputs map.

Properties

Item

Type

Schema

Description

id

string

The identifier of this outputs map command.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

map

array

Mandatory

An array of two output identifiers.

map/n/

integer

Output identifier integer.

map/0/outputId

string

Mandatory

The old output identifier to change

map/1/outputId

string

Mandatory

The new output identifier value to which to change.

Methods

Method Description
read

Return the name of the command.

Example:

Read Outputs Map Command UpdateId 
read /controls/hmi/outputs/commands/updateId

Example Response:

Read Outputs Map Command UpdateId Response 
{
  "path": "/controls/hmi/outputs/commands/updateId",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/outputs/commands/updateId"
      }
    },
    "id": "updateId"
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the outputs map resource.

Example:

Update Data Source Output Id 
// Rename the output id for "second" to "MinZ".
call /controls/hmi/outputs/commands/updateId {"map":[{"outputId":"second"},{"outputId":"MinZ"}]}

Example Response:

Update Data Source Output Id Response 
{
  "path": "/controls/hmi/outputs/commands/updateId",
  "payload": null,
  "status": 1,
  "type": "response"
}

Before update:
{
  "path": "/controls/hmi/outputs/",
...
    "map": [
      {
        "outputId": "first",
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": "second",
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": "third",
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

After update:
{
  "path": "/controls/hmi/outputs/",
...
    "map": [
      {
        "outputId": "MinZ",                <-------------------------------
        "source": "tools:ProfileInfo-0:outputs:MinZ"
      },
      {
        "outputId": "first",
        "source": "tools:ProfileInfo-0:outputs:MaxZ"
      },
      {
        "outputId": "third",
        "source": "tools:ProfileInfo-0:outputs:PointCount"
      }
    ]
...
}

Notifications

None generated for this resource.

/controls/hmi/commands

Resource Type: ( Standard )

A collection of HMI applicationcommands defined by the HMI service. Thesecommands are applied to the HMI application.

1.1.x.x 1.2.x.x renamed the "actions" to "commands".

1.1.x.x 1.2.x.x added "discardWorkspace" command.

1.1.x.x 1.2.x.x removed "deactivate" command.

Methods

Method Description
read

Returns a list ofcommands for the HMI service as embedded resources.

Example:

HMI Service Commands Example 
read /controls/hmi/commands

Example Response:

HMI Service Commands Response 
{
  "path": "/controls/hmi/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/activate"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/createApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/removeApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/downloadApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/uploadApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/commands/discardWorkspace"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/hmi/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/hmi/commands/activate

Resource Type: (CollectionItem , Callable)

Command to ensure load the HMI Application is loaded.

This command must be called after WebIQ Designer has published the HMI Application (with or without changes to the HMI Application) to ensure the HMI Application is once again loaded. Otherwise, attempt to connect to the HMI Application will be unsuccessful, likely with a HTTP "404 page not found" type of error.

Reading this resource returns information about the call parameters for this command.

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

No parameters are required.

Methods

Method Description
read

Return the name of the command .

Example:

Read Activate Command 
read /controls/hmi/commands/activate

Example Response:

Read Activate Command Response 
{
  "path": "/controls/hmi/commands/activate",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/activate"
      }
    },
    "id": "activate",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command .

This could potentially generate an "updated" notification for the /controls/hmi resource.

Example:

Activate HMI App 
call /controls/hmi/commands/activate

Example Response:

Activate HMI App Response 
{
  "path": "/controls/hmi/commands/activate",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/commands/deactivate

1.1.x.x 1.2.x.x removed the "deactivate" command.

/controls/hmi/commands/createApp

Resource Type: (CollectionItem , Callable)

Command to create a default HMI Application. This is allowed only if there is no other HMI Application available to use.

Reading this resource returns information about the call parameters for this command .

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

No parameters are required.

Methods

Method Description
read

Return the name of the command .

Example:

Read Create Default App Command 
read /controls/hmi/commands/createApp

Example Response:

Read Create Default App Command Response 
{
  "path": "/controls/hmi/commands/createApp",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/createApp"
      }
    },
    "id": "createApp",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command .

This could potentially generate an "updated" notification for the /controls/hmi resource.

Example:

Activate HMI App 
call /controls/hmi/commands/createApp

Example Response:

Activate HMI App Response 
{
  "path": "/controls/hmi/commands/createApp",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/commands/removeApp

Resource Type: (CollectionItem , Callable)

Command to delete (remove) the current HMI Application. The HMI service always has a default HMI Application available the user can use, even after deleting the current HMI Application.

Reading this resource returns information about the call parameters for this command .

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

No parameters are required.

Methods

Method Description
read

Return the name of the command .

Example:

Read Remove Default App Command 
read /controls/hmi/commands/removeApp

Example Response:

Read Remove Default App Command Response 
{
  "path": "/controls/hmi/commands/removeApp",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/removeApp"
      }
    },
    "id": "removeApp",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command .

This could potentially generate an "updated" notification for the /controls/hmi resource.

Example:

Activate HMI App 
call /controls/hmi/commands/removeApp

Example Response:

Activate HMI App Response 
{
  "path": "/controls/hmi/commands/removeApp",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/commands/downloadApp

Resource Type: (CollectionItem , Callable)

Command to download (export) the HMI Application.

Reading this resource returns information about the call parameters for this command .

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

No parameters are required.

Methods

Method Description
read

Return the name of the command .

Example:

Read Download App Command 
read /controls/hmi/commands/downloadApp

Example Response:

Read Download App Command Response 
{
  "path": "/controls/hmi/commands/downloadApp",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/downloadApp"
      }
    },
    "id": "downloadApp",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command .

This command returns a binary byte stream containing the contents of the HMI Application ZIP file in the "payload", "data" field.

Example:

Download HMI App 
call /controls/hmi/commands/downloadApp

Example Response:

Download HMI App Response 
{
  "path": "/controls/hmi/commands/downloadApp",
  "payload": {
    "data": [             <------------------------------- HMI Application ZIP file content shown as decimal bytes.
      80,
      75,
      3,
      4,
      20,
      0,
      8,
      8,
      8,
...
    ]
  },
  "status": 1,
  "type": "response"
}

Hex dump of the HMI Application ZIP file used in the example:
   0x50, 0x4B, 0x3, 0x4, 0x14, 0, 0x8, 0x8, 0x8, ...

Notifications

None generated for this resource.

/controls/hmi/commands/uploadApp

Resource Type: (CollectionItem , Callable)

Command to upload (import) the HMI Application.

Reading this resource returns information about the call parameters for this command .

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

parameters/data binary

Binary byte stream of the HMI application ZIP file.

0.3.x.x changed the "data" array from array of bytes to a binary byte stream.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item Type Mandatory or Optional Argument Description
parameters object Mandatory Parameters for the call request for this command
parameters/data binary

Binary byte stream of the HMI application ZIP file.

0.3.x.x changed the "data" array from array of bytes to a binary byte stream.

Methods

Method Description
read

Return the name of the command .

Example:

Read Upload App Command 
read /controls/hmi/commands/uploadApp

Example Response:

Read Upload App Command Response 
{
  "path": "/controls/hmi/commands/uploadApp",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/uploadApp"
      }
    },
    "id": "uploadApp",
    "parameters": {
      "data": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command .

This could potentially generate an "updated" notification for the /controls/hmi resource.

Example:

Upload HMI App 
call /controls/hmi/commands/uploadApp {"parameters" : {"data" : [80, 75, 3, 4, 20, 0, 8, 8, 8, ...]}}

Example Response:

Upload HMI App Response 
{
  "path": "/controls/hmi/commands/uploadApp ",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/hmi/commands/discardWorkspace

Resource Type: (CollectionItem , Callable)

Command to remove (discard) a workspace for the HMI Application created by the Designer.

Reading this resource returns information about the call parameters for this command .

1.1.x.x 1.2.x.x added "discardWorkspace" command.

Properties

Item Type Schema Description
id string
The identifier of this command .
parameters object

Describes the parameters that the command accepts.

No parameters are required.

Methods

Method Description
read

Return the name of the command .

Example:

Read Discard HMI Workspace 
read /controls/hmi/commands/discardWorkspace

Example Response:

Read Discard HMI Workspace Response 
{
  "path": "/controls/hmi/commands/discardWorkspace",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/commands/discardWorkspace"
      }
    },
    "id": "discardWorkspace",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the /controls/hmi resource.

Example:

Discard HMI Workspace 
call /controls/hmi/commands/discardWorkspace

Example Response:

Discard HMI Workspace Response 
{
  "path": "/controls/hmi/commands/discardWorkspace",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.


GoPxL: Modbus Resources

This page describes the control service resource called Modbus Service that is included with each LMI Gocator release.

/controls/modbus

Resource Type: (Standard)

Modbus resource supports the following properties:

Properties

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "Modbus"

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "modbus".

parameters object

Parameter settings applicable to the service.

parameters/resultBufferEnabled boolean

Used to enable/disable buffering of scan outputs.

Buffering should be enabled when part detection is used and if multiple objects may be detected within a time frame shorter than the polling rate of the PLC. If buffering is enabled, the PLC must send the 'Buffer Advance' command to advance the queue before reading the measurement results.

status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

serverPort integer readOnly

Added in version 1.2.x.x .

The network port that Modbus service uses.

Methods

Method Description
read

Return property information about the service resource.

Example :

Read Resource 
read /controls/modbus

Example Response :

Read Resource Response 
{
  "path": "/controls/modbus",
  "payload": {
    "_embedded": {
      "go:registerAssembly": [
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/modbus"
      }
    },
    "displayName": "Modbus",
    "enabled": true,
    "id": "modbus",
  	"serverPort": 502,
    "parameters": {
      "resultBufferEnabled": false
    },
    "status": 0
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/modbus

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/modbus",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/modbus

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/modbus",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/modbus {"enabled" : true}
update /controls/modbus {"enabled" : false}
update /controls/modbus {"enabled" : true, "parameters" : {"resultBufferEnabled":true}}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/modbus",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request: 
update /controls/modbus {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/modbus",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/modbus/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/modbus/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/modbus/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/modbus/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/modbus/metrics",
  "payload": {
    "path": "/controls/modbus/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/modbus/metrics",
  "payload": {
    "controlDrops": 0
  },
  "status": 1,
  "streamId": 1,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/modbus/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/modbus/metrics",
  "payload": {
    "path": "/controls/modbus/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies

Resource Type: (Non Standard)

This resource is a parent to register assembly resources which are used to hold a list of data source outputs to send to a control service client.

1.0.x.x added support for registerAssemblies resource.

Reading the /controls/modbus/registerAssemblies resource returns a list of register assembly resources supported by the control service. For Modbus, it supports one register assembly resource whose internal identifier is "registerAssembly-0".

Register Assembly Display Name Register Assembly Internal Identifier Resource Path
"Register Assembly 0" "register-Assembly-0" /controls/modbus/registerAssemblies/registerAssembly-0

Methods

Method Description
read

Read this resource to find out what register assemblies are available for the resource.

Example:

Read Register Assembly 
read /controls/modbus/registerAssemblies

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/modbus/registerAssemblies",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications
None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0

Resource Type: (Observable)

This is a resource to specify information output to the control service client. The type of information and the information location in the output is maintained by this resource.

Properties

Item

Type

Schema

Description

attributes

object

readOnly

Attributes of the register assembly resource.

attributes/isGlobalAddressSpaceUsed

boolean

Indicates if each output entry occupies a range of addresses (output identifier) in the register assembly.

Value of true means each output entry/item occupies a range of addresses (output identifiers) in the register assembly, corresponding to the register count of the register block.

Value of false means each output entry/item takes up one output identifier value, regardless of the register count of the register block.

attributes/outputIdMax

integer

The maximum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMax to outputIdMax.

attributes/outputIdMin

integer

The minimum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMin to outputIdMin.

blocks

array

Array of register blocks added to this register assembly. Each register block has its own set of properties.

blocks/n/

object

A register block entry.

blocks/n/dataSource

string

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks.

This field is not applicable to the other register blocks

blocks/n/displayName

string

Culture-specific string to describe the register block.
For measurement and stamp blocks this field is the register block name not the displayName of the dataSource field. This is for information only, do not use this field.

blocks/n/outputId

integer

Identifier of the output item.

Valid range is 0..2 16 -1.

The output identifier must not lie outside the range of values specified by attributes/outputIdMin and attributes/outputIdMax.

If attributes/isGlobalAddressSpaceUsed is true:

The identifier corresponds to the register address location in which the data for this block appears in the control services output.

The maximum blocks/n/outputId value must satisfy the following relationship to ensure all the register block's outputs do not go past the the last register address specified byattributes/outputIdMax:

blocks/n/outputId +supportedBlockTypes/n/registerCount - 1 <= attributes/outputIdMax

If attributes/isGlobalAddressSpaceUsed is false:

The maximum blocks/n/outputId value must satisfy the following relationship:

blocks/n/outputId <= attributes/outputIdMax

blocks/n/scannerId

string

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

readOnly

Unique internal identifier of the register block type (see Register Assembly Register Block Types ).

blocks/n/version

string

readOnly

1.2.x.x Register block version.

displayName

string

readOnly

Display name of the register assembly

id

string

readOnly

Register assembly internal identifier

version

string

readOnly

1.2.x.x Register assembly version.

supportedBlockTypes

array

readOnly

Array of register block types properties for block types that are supported by the control services register assembly.

supportedBlockTypes/n/

object

A register block type entry.

supportedBlockTypes/n/category

enum

Categorizes the purpose of a register block type.

Enumerated values are:

0 = Unknown purpose

1 = Used for receiving control input from client

2 = Used for sending control output to client

3 = Used for providing system state information to client

4 = Used for providing sensor group state information to client

5 = Used for providing stamp information to client

6 = Used for providing measurement value and/or decision information to client

supportedBlockTypes/n/displayName

string

Culture-specific string that can be presented to the user to describe the register block.

supportedBlockTypes/n/hasDataSource

boolean

Indicates if this register block type contains a data source or not.

Value is

  • true for stamp and measurement register blocks

  • false for the other register blocks.

supportedBlockTypes/n/instanceCount

integer

Number of instances of this register block type that has been added by user.

Must be:

  • greater than or equal tosupportedBlockTypes/n/minInstance and

  • less than or equal tosupportedBlockTypes/n/maxInstance.

supportedBlockTypes/n/maxInstanceCount

integer

Maximum number of instances of this register block type that this register assembly can have.

supportedBlockTypes/n/minInstanceCount

integer

Minimum number of instances of this register block type that this register assembly can have.

A value of 0 means this register block type is optional for this register assembly.

A value N greater than 0 means N instances are created automatically on start up.

supportedBlockTypes/n/registerCount

integer

This value is meaningful only for register assemblies where attributes/isGlobalAddressSpaceUsed is true.

It is the number of address locations in the output that this register block takes up.

This number is determined by what output information are available for a register block and is constant for that register block type.

supportedBlockTypes/n/type

string

Internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).
Used by client to refer to this register block type for operations on the register assembly.

This register assembly customizes the register assembly properties as follows:

Item Type Schema Description
attributes/isGlobalAddressSpaceUsed

boolean

readOnly

Value is set to true.

attributes/outputIdMax

integer readOnly

Value is set to 2999.

attributes/outputIdMin

integer readOnly Value is set to zero (0).
displayName string readOnly "Register Assembly 0"
id string readOnly "registerAssembly-0"

supportedBlockTypes/n/category

integer readOnly Categories 1, 2, 3, 4, 5, 6 are supported.

supportedBlockTypes/n/maxInstanceCount

integer readOnly

Value for each supported register block type by category name:

  • Category 1 ("Control Input"): Value is set to 1.
  • Category 2 ("Control Output"): Value is set to 1.
  • Category 3 ("System"): Value is set to 1.
  • Category 4 ("Scanner"): Value is set to 1.
  • Category 5 ("Stamp"): Value is set to 167.
  • Category 6 ("Measurement"): Value is set to 950.

supportedBlockTypes/n/minInstanceCount

integer readOnly

Value for each supported register block type by category name:

  • Category 1 ("Control Input"): Value is set to 1.
  • Category 2 ("Control Output"): Value is set to 1.
  • Category 3("System"): Value is set to 1.
  • Category 4 ("Scanner"): Value is set to 1.
  • Category 5 ("Stamp"): Value is set to 0.
  • Category 6 ("Measurement"): Value is set to 0.
supportedBlockTypes/n/registerCount integer readOnly

Value for each supported register block type by category name:

  • Category 1 ("Control Input"): Value is set to 65.
  • Category 2 ("Control Output"): Value is set to 2.
  • Category 3 ("System"): Value is set to 72.
  • Category 4 ("Scanner"): Value is set to 10.
  • Category 5 ("Stamp"): Value is set to 17.
  • Category 6 ("Measurement"): Value is set to 3.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier by category:

  • Category 1: "ControlInput"
  • Category 2: "ControlOutput"
  • Category 3: "System"
  • Category 4: "Scanner"
  • Category 5: "Stamp"
  • Category 6: "Measurement"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/modbus/registerAssemblies/registerAssembly-0

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add"
        },
        {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove"
        },
		{
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll"
        },
        {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact"
        },
        {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update"
        }
      ],
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": true,
      "outputIdMax": 2999,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput"
        "version": "1.2"
      },
      {
        "displayName": "Command Output",
        "outputId": 66,
        "scannerId": "",
        "type": "ControlOutput"
        "version": "1.2"
      },
      {
        "displayName": "System State",
        "outputId": 68,
        "scannerId": "",
        "type": "System"
        "version": "1.2"
      },
      {
        "displayName": "Sensor Group State",
        "outputId": 140,
        "scannerId": "",
        "type": "Scanner"
        "version": "1.2"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
        "version": "1.2"
      }
    ],
    "displayName": "Register Assembly 0",
    "id": "registerAssembly-0",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 1,
        "displayName": "Command Input",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 66,
        "type": "ControlInput"
      },
      {
        "category": 2,
        "displayName": "Command Output",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 2,
        "type": "ControlOutput"
      },
      {
        "category": 3,
        "displayName": "System State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 72,
        "type": "System"
      },
      {
        "category": 4,
        "displayName": "Sensor Group State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 10,
        "type": "Scanner"
      },
      {
        "category": 5,
        "displayName": "Stamp",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 167,
        "minInstanceCount": 0,
        "registerCount": 17,
        "type": "Stamp"
      },
      {
        "category": 6,
        "displayName": "Measurement and Decision",
        "hasDataSource": true,
        "instanceCount": 1,
        "maxInstanceCount": 950,
        "minInstanceCount": 0,
        "registerCount": 3,
        "type": "Measurement"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/modbus/registerAssemblies/registerAssembly-0

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/modbus/registerAssemblies/registerAssembly-0

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {"blocks":[{"type": "Measurement", "dataSource":"tools:ProfileInfo-0:outputs:MinZ"}]}

Notification:
{
  "eventType": "updated",
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/modbus/registerAssemblies/registerAssembly-0/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's register assembly. These commands can be used to modify the register blocks inside the register assemblys array of register blocks called blocks. Depending on the characteristics of the supported block type, some commands may not be applicable.

For example, attempt to add a second instance of a supported block type that only allows one instance to be present is rejected.

Methods

Method Description
read

Returns a list of register assembly commands as embedded resources.

Example:

Read Register Assembly Commands 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands

Example Response:

Read Register Assembly Commands Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one or more register blocks to the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/blocks

array<object>

An array of register block information describing the registers blocks that are to be added to the register Tassembly

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

Value of true means the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

Value of false means overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

blocks

array

Array of register blocks to be added to the register assembly

blocks/n/

object

One entry of register block information.

blocks/n/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

blocks/n/displayName

string

Optional

Culture-specific string to describe the register block.This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

blocks/n/outputId

integer

Optional

Output identifier for this output item.

If not provided as an argument, then the register block is added after the last register block.

The valid range for the output id is0..2 16 -1. If the client enters an output id value that is greater than2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the output id will be processed as 0x0001 which is equal to 1.

blocks/n/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

Mandatory

Unique internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Add 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands/add

Example Response:

Read Register Assembly Command Add Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add"
      }
    },
    "id": "add",
    "parameters": {
      "autoShift": false,
      "blocks": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Add Register Block 
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
    "autoShift":true,
    "blocks":[{
        "type":"ControlInput",
        "outputId":100,
        "displayName":"New Block"}]}

call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
    "blocks":[
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MinZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MaxZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:PointCount"}]}

call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
    "blocks":[
        {"type":"ControlInput"},
        {"type":"ControlOutput"},
        {"type":"System"},
        {"type":"Scanner"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MinZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MaxZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:PointCount"},
        {"type":"Stamp","dataSource":"scan:LMILaserLineProfiler:scanner-0:stamp"}]}

Example Response:

Add Register Block Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/outputIdList

array<integer>

Array of one or more output identifiers to remove from the register assembly.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputIdList

array

Mandatory

Array of one or more output identifiers to remove from the register assembly.

outputIdList/n/

integer

One output identifier.

outputIdList/n/outputId

integer

The output id to remove from the register assembly.

At least one entry must be provided.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands/remove

Example Response:

Read Register Assembly Command Remove Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove"
      }
    },
    "id": "remove",
    "parameters": {
      "outputIdList": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove Register Block 
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0}]}

call /controls/modbus/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0},{"outputId":100},{"outputId":200}]}

Example Response:

Remove Register Block Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Minimum supported version 1.2.x.x .

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove All 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll

Example Response:

Read Register Assembly Command Remove All Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll"
      }
    },
    "id": "removeAll",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove All Register Block 
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll

Example Response:

Remove All Register Block Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/removeAll",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact

Resource Type: (CollectionItem , Callable)

Command to compact (remove gaps from) the register block output identifiers within the register assembly to eliminate unused space between register blocks.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/startingOutputId

integer

Output identifier to assign to the first register block during the compacting operation.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

startingOutputId

integer

Optional

Output identifier to assign to the first register block during the compacting operation.

Ifattributes/isGlobalAddressSpaceUsed is true, the minimum and maximum values is limited by the register assembly's minimum and maximum address value.

The maximum value allowed for the compact command is likely to be less than the register assembly's maximum address value to allow a register block to fit within the register assembly's address range.

If no startingAddress is provided, then the default value is the register assembly's attribute outputIdMin value.

Ifattributes/isGlobalAddressSpaceUsed is false, and if not provided as an argument, the value of zero (0) is used as the starting output identifier value.

If the client enters an output id value that is greater than2 16 -1 (65535), which is the largest value that 16-bits can represent, the output id will get truncated to a 16 bit value.

e.g. Client enters anoutput id equal to 65537. 65537 is equal to 0x10001. However, the output id will be truncated by the REST API and processed as 0x0001 which is equal to 1.

0.3.x.x added this field which was originally called startingAddress.

0.3.x.x renamed fromstartingAddress to startingOutputId.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Compact 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact

Example Response:

Read Register Assembly Command Compact Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact"
      }
    },
    "id": "compact",
    "parameters": {
      "startingOutputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Compact Register Block 
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact

call /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact {"startingOutputId":100}

Example Response:

Compact Register Block Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and after Compacting:

Compact Register Block Before And After 
Request:
   call /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact

The block list before compacting:
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput"
      },
      {
        "displayName": "Command Output",
        "outputId": 66,
        "scannerId": "",
        "type": "ControlOutput"
      },
      {
        "displayName": "System State",
        "outputId": 68,
        "scannerId": "",
        "type": "System"
      },
      {
        "displayName": "Sensor Group State",
        "outputId": 140,
        "scannerId": "",
        "type": "Scanner"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 156,
        "scannerId": "",
        "type": "Measurement"
      }
    ],

The block list after compacting with a starting output id ("startingOutputId") set to 0:
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput"
      },
      {
        "displayName": "Command Output",
        "outputId": 66,
        "scannerId": "",
        "type": "ControlOutput"
      },
      {
        "displayName": "System State",
        "outputId": 68,
        "scannerId": "",
        "type": "System"
      },
      {
        "displayName": "Sensor Group State",
        "outputId": 140,
        "scannerId": "",
        "type": "Scanner"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 153,      
        "scannerId": "",
        "type": "Measurement"
      }
    ],

Notifications

None generated for this resource.

/controls/modbus/registerAssemblies/registerAssembly-0/commands/update

Resource Type: (CollectionItem , Callable)

Command to update (modify) the register block characteristics.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/outputId

integer

The output id of the register block to update.

parameters/newParams

object

Parameters used to update the register block specified by the output identifier.

parameters/newParams/dataSource

string

New data source identifier for the register block.

parameters/newParams/displayName

string

New display name for the register block.

parameters/newParams/outputId

integer

New output identifier value to assign to the register block.

parameters/newParams/scannerId

string

New scanner identifier for the register block.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

newParams

object

The information to apply to the specified register block.

newParams/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

newParams/displayName

string

Optional

The updated culture-specific string for the register block display name.

This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

newParams/outputId

integer

Optional

The new output identifier to assign to the register block.

newParams/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

outputId

integer

Mandatory

The output identifier of the register block to which the new parameters are applied.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Update 
read /controls/modbus/registerAssemblies/registerAssembly-0/commands/update

Example Response:

Read Register Assembly Command Update Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update"
      }
    },
    "id": "update",
    "parameters": {
      "autoShift": false,
      "newParams": {
        "dataSource": "",
        "displayName": "",
        "outputId": null,
        "scannerId": ""
      },
      "outputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Update Register Block 
// This update request doesn't change anything but is still a valid request.
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/update {"outputId" : 153, "newParams" : {}}

call /controls/modbus/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Example Response:

Update Register Block Response 
{
  "path": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and After Updating:

Update Register Block Before And After 
Request:
   call /controls/modbus/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Before update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 153,
        "scannerId": "",
        "type": "Measurement"
      }
    ],

After update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "MyPointCount",      
        "outputId": 200,                    
        "scannerId": "",
        "type": "Measurement"
      }
    ],

Notifications

None generated for this resource.







GoPxL: Ethernet ASCII Resources

This page describes the control service resource called Ethernet ASCII Service that is included with each LMI Gocator release.

/controls/e-ascii

Resource Type: (Standard)

Ethernet ASCII resource supports the following properties:

Properties

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "Ethernet ASCII"

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "e-ascii".

parameters object
Parameter settings applicable to the service.
parameters/allowAsync

boolean


0.3.x.x added this parameter.

Indicates whether user has enabled Ethernet ASCII to send data to the client asynchronously.

When enabled, scan output data is sent to the Ethernet ASCII client without the client requesting the data. The format of the output depends on "asyncFormatMode" setting.

When disabled, data is sent only upon explicit request from the Ethernet ASCII client.

Regardless of the value of this setting, it is always possible to poll for scan output data.

Default value is "false".

parameters/asyncFormatMode integer

enum

User configured output format mode that the Ethernet ASCII service should use when sending data to the Ethernet ASCII client in asynchronous mode operation.

The enumerated values are:

0 = Standard: Standard formatting of output. The output format is "M<id><delim>V<value><delim>D<decision><delim>"

1 = Standard With Stamp: Standard formatting of output with encoder and frame index. The output format is "T<time><delim>E<encoder><delim>M<id><delim>V<value><delim>D<decision><delim>"

2 = Custom: Custom formatting (see "customFormat" setting).

Default value is 0 ("Standard")

parameters/commandDelimiter string

Determines the delimeter used to separate command fields and output fields.

Default value is the comma character (",").

parameters/controlPort integer

minimum,

maximum

16-bit port number of TCP connection used to connect to the Ethernet ASCII service.

Minimum value is 0.

Maximum value is 65534.

Default value is 8190.

parameters/customFormat string

This is the formatting of output data (stamp and/or measurement data) the user wants to sent to the Ethernet ASCII client.

Applicable to both:

  • Synchronous data, when polled by making a result request
  • Asynchronous data, when "allowAsync" is true and "asyncFormatMode" is set to 2 ("custom" formatting)

Default value is "%time, %value[0] %decision[0]"

parameters/delimeterTermination string

A string that the Ethernet ASCII service uses to terminate a line of output to the Ethernet ASCII client.

Default value is"%r%n".

parameters/invalidValue string

A string that the Ethernet ASCII service uses to indicate that a measurement value is invalid.

Default value is "INVALID".

status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

Methods

Method Description
read

Return property information about the service resource.

Example:

Read Resource 
read /controls/e-ascii

Example Response:

Read Resource Response 
{
  "path": "/controls/e-ascii",
  "payload": {
    "_embedded": {
      "go:registerAssembly": [
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/e-ascii"
      }
    },
    "displayName": "Ethernet ASCII",
    "enabled": true,
    "id": "e-ascii",
    "parameters": {
      "allowAsync": false,
      "asyncFormatMode": 0,
      "commandDelimiter": ",",
      "controlPort": 8190,
      "customFormat": "%time, %value[0] %decision[0]",
      "delimiterTermination": "%r%n",
      "invalidValue": "INVALID"
    },
    "status": 0
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/e-ascii

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/e-ascii",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/e-ascii

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/e-ascii",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/e-ascii {"enabled" : true}
update /controls/e-ascii {"enabled" : false}
update /controls/e-ascii {"enabled" : true, "parameters" : {"allowAsync":true}}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/e-ascii",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request: 
update /controls/e-ascii{"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/e-ascii",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/e-ascii/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/e-ascii/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/e-ascii/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/e-ascii/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/e-ascii/metrics",
  "payload": {
    "path": "/controls/e-ascii/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/e-ascii/metrics",
  "payload": {
    "controlDrops": 0
  },
  "status": 1,
  "streamId": 1,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/e-ascii/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/e-ascii/metrics",
  "payload": {
    "path": "/controls/e-ascii/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

/controls/e-ascii/registerAssemblies

Resource Type: (Non Standard)

This resource is a parent to register assembly resources which are used to hold a list of data source outputs to send to a control service client.

1.0.x.x added support for registerAssemblies resource.

Reading the /controls/e-ascii/registerAssemblies resource returns a list of register assembly resources supported by the control service. For Ethernet ASCII, it supports one register assembly resource whose internal identifier is "registerAssembly-0".

Register Assembly Display Name Register Assembly Internal Identifier Resource Path
"Register Assembly 0" "register-Assembly-0" /controls/e-ascii/registerAssemblies/registerAssembly-0

Methods

Method Description
read

Read this resource to find out what register assemblies are available for the resource.

Example:

Read Register Assembly 
read /controls/e-ascii/registerAssemblies

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/e-ascii/registerAssemblies",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0

Resource Type: (Observable)

This is a resource to specify information output to the control service client. The type of information and the information location in the output is maintained by this resource.

Properties

Item

Type

Schema

Description

attributes

object

readOnly

Attributes of the register assembly resource.

attributes/isGlobalAddressSpaceUsed

boolean

Indicates if each output entry occupies a range of addresses (output identifier) in the register assembly.

Value of true means each output entry/item occupies a range of addresses (output identifiers) in the register assembly, corresponding to the register count of the register block.

Value of false means each output entry/item takes up one output identifier value, regardless of the register count of the register block.

attributes/outputIdMax

integer

The maximum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMax to outputIdMax.

attributes/outputIdMin

integer

The minimum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMin to outputIdMin.

blocks

array

Array of register blocks added to this register assembly. Each register block has its own set of properties.

blocks/n/

object

A register block entry.

blocks/n/dataSource

string

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks.

This field is not applicable to the other register blocks

blocks/n/displayName

string

Culture-specific string to describe the register block.
For measurement and stamp blocks this field is the register block name not the displayName of the dataSource field. This is for information only, do not use this field.

blocks/n/outputId

integer

Identifier of the output item.

Valid range is 0..2 16 -1.

The output identifier must not lie outside the range of values specified by attributes/outputIdMin and attributes/outputIdMax.

If attributes/isGlobalAddressSpaceUsed is true:

The identifier corresponds to the register address location in which the data for this block appears in the control services output.

The maximum blocks/n/outputId value must satisfy the following relationship to ensure all the register block's outputs do not go past the the last register address specified byattributes/outputIdMax:

blocks/n/outputId +supportedBlockTypes/n/registerCount - 1 <= attributes/outputIdMax

If attributes/isGlobalAddressSpaceUsed is false:

The maximum blocks/n/outputId value must satisfy the following relationship:

blocks/n/outputId <= attributes/outputIdMax

blocks/n/scannerId

string

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

readOnly

Unique internal identifier of the register block type (see Register Assembly Register Block Types ).

blocks/n/version

string

readOnly

1.2.x.x Register block version.

displayName

string

readOnly

Display name of the register assembly

id

string

readOnly

Register assembly internal identifier

version

string

readOnly

1.2.x.x Register assembly version.

supportedBlockTypes

array

readOnly

Array of register block types properties for block types that are supported by the control services register assembly.

supportedBlockTypes/n/

object

A register block type entry.

supportedBlockTypes/n/category

enum

Categorizes the purpose of a register block type.

Enumerated values are:

0 = Unknown purpose

1 = Used for receiving control input from client

2 = Used for sending control output to client

3 = Used for providing system state information to client

4 = Used for providing sensor group state information to client

5 = Used for providing stamp information to client

6 = Used for providing measurement value and/or decision information to client

supportedBlockTypes/n/displayName

string

Culture-specific string that can be presented to the user to describe the register block.

supportedBlockTypes/n/hasDataSource

boolean

Indicates if this register block type contains a data source or not.

Value is

  • true for stamp and measurement register blocks

  • false for the other register blocks.

supportedBlockTypes/n/instanceCount

integer

Number of instances of this register block type that has been added by user.

Must be:

  • greater than or equal tosupportedBlockTypes/n/minInstance and

  • less than or equal tosupportedBlockTypes/n/maxInstance.

supportedBlockTypes/n/maxInstanceCount

integer

Maximum number of instances of this register block type that this register assembly can have.

supportedBlockTypes/n/minInstanceCount

integer

Minimum number of instances of this register block type that this register assembly can have.

A value of 0 means this register block type is optional for this register assembly.

A value N greater than 0 means N instances are created automatically on start up.

supportedBlockTypes/n/registerCount

integer

This value is meaningful only for register assemblies where attributes/isGlobalAddressSpaceUsed is true.

It is the number of address locations in the output that this register block takes up.

This number is determined by what output information are available for a register block and is constant for that register block type.

supportedBlockTypes/n/type

string

Internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).
Used by client to refer to this register block type for operations on the register assembly.

This register assembly customizes the register assembly properties as follows:

Item Type Schema Description
attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/outputIdMax integer readOnly Value is set to 65534.
attributes/outputIdMin integer readOnly Value is set to zero (0).
displayName string readOnly "Register Assembly 0"
id string readOnly "registerAssembly-0"
supportedBlockTypes/n/category integer readOnly

Categories 5 and 6 are supported.

1.2.x.x Support for category 4 ("Scanner') removed.

supportedBlockTypes/n/maxInstanceCount integer readOnly

Value for each supported register block type by category name:

  • Category 5 ("Stamp"): Value is set to 65534.
  • Category 6 ("Measurement"): Value is set to 65534.

1.2.x.x Support for category 4 ("Scanner') removed.

supportedBlockTypes/n/minInstanceCount integer readOnly

Value for each supported register block type by category name:

  • Category 5 ("Stamp"): Value is set to 0.
  • Category 6 ("Measurement"): Value is set to 0.

1.2.x.x Support for category 4 ("Scanner') removed.

supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier by category:

  • Category 5: "Stamp"
  • Category 6: "Measurement"

1.2.x.x Support for category 4 ("Scanner') removed.

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/e-ascii/registerAssemblies/registerAssembly-0

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add"
        },
        {
          "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove"
        },
		{
          "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll"
        },
        {
          "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact"
        },
        {
          "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update"
        }
      ],
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "dataSource": "tools:ProfilePosition-2:outputs:X",
        "displayName": "Measurement and Decision",
        "outputId": 0,
        "scannerId": "",
        "type": "Measurement",
        "version": "1.2"
      },
      {
        "dataSource": "tools:ProfilePosition-2:outputs:Z",
        "displayName": "Measurement and Decision",
        "outputId": 1,
        "scannerId": "",
        "type": "Measurement",
        "version": "1.2"
      }
    ],
    "displayName": "Register Assembly 0",
    "id": "registerAssembly-0",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 5,
        "displayName": "Stamp",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 33,
        "type": "Stamp"
      },
      {
        "category": 6,
        "displayName": "Measurement",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 5,
        "type": "Measurement"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/e-ascii/registerAssemblies/registerAssembly-0

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/e-ascii/registerAssemblies/registerAssembly-0

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add {"blocks":[{"type": "Measurement", "dataSource":"tools:ProfileInfo-0:outputs:MinZ"}]}

Notification:
{
  "eventType": "updated",
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's register assembly. These commands can be used to modify the register blocks inside the register assemblys array of register blocks called blocks. Depending on the characteristics of the supported block type, some commands may not be applicable.

For example, attempt to add a second instance of a supported block type that only allows one instance to be present is rejected.

Methods

Method Description
read

Returns a list of register assembly commands as embedded resources.

Example:

Read Register Assembly Commands 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands

Example Response:

Read Register Assembly Commands Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one or more register blocks to the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/blocks

array<object>

An array of register block information describing the registers blocks that are to be added to the register Tassembly

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

Value of true means the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

Value of false means overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

blocks

array

Array of register blocks to be added to the register assembly

blocks/n/

object

One entry of register block information.

blocks/n/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

blocks/n/displayName

string

Optional

Culture-specific string to describe the register block.This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

blocks/n/outputId

integer

Optional

Output identifier for this output item.

If not provided as an argument, then the register block is added after the last register block.

The valid range for the output id is0..2 16 -1. If the client enters an output id value that is greater than2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the output id will be processed as 0x0001 which is equal to 1.

blocks/n/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

Mandatory

Unique internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Add 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add

Example Response:

Read Register Assembly Command Add Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add"
      }
    },
    "id": "add",
    "parameters": {
      "autoShift": false,
      "blocks": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Add Register Block 
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add {
    "blocks":[
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MinZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MaxZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:PointCount"}]}

call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add {
    "blocks":[
        {"type":"Scanner"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MinZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MaxZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:PointCount"},
        {"type":"Stamp","dataSource":"scan:LMILaserLineProfiler:scanner-0:stamp"}]}

Example Response:

Add Register Block Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/outputIdList

array<integer>

Array of one or more output identifiers to remove from the register assembly.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputIdList

array

Mandatory

Array of one or more output identifiers to remove from the register assembly.

outputIdList/n/

integer

One output identifier.

outputIdList/n/outputId

integer

The output id to remove from the register assembly.

At least one entry must be provided.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove

Example Response:

Read Register Assembly Command Remove Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove"
      }
    },
    "id": "remove",
    "parameters": {
      "outputIdList": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove Register Block 
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0}]}

call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0},{"outputId":100},{"outputId":200}]}

Example Response:

Remove Register Block Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Minimum supported version 1.2.x.x .

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove All 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll

Example Response:

Read Register Assembly Command Remove All Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll"
      }
    },
    "id": "removeAll",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove All Register Block 
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll

Example Response:

Remove All Register Block Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/removeAll",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact

Resource Type: (CollectionItem , Callable)

Command to compact (remove gaps from) the register block output identifiers within the register assembly to eliminate unused space between register blocks.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/startingOutputId

integer

Output identifier to assign to the first register block during the compacting operation.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

startingOutputId

integer

Optional

Output identifier to assign to the first register block during the compacting operation.

Ifattributes/isGlobalAddressSpaceUsed is true, the minimum and maximum values is limited by the register assembly's minimum and maximum address value.

The maximum value allowed for the compact command is likely to be less than the register assembly's maximum address value to allow a register block to fit within the register assembly's address range.

If no startingAddress is provided, then the default value is the register assembly's attribute outputIdMin value.

Ifattributes/isGlobalAddressSpaceUsed is false, and if not provided as an argument, the value of zero (0) is used as the starting output identifier value.

If the client enters an output id value that is greater than2 16 -1 (65535), which is the largest value that 16-bits can represent, the output id will get truncated to a 16 bit value.

e.g. Client enters anoutput id equal to 65537. 65537 is equal to 0x10001. However, the output id will be truncated by the REST API and processed as 0x0001 which is equal to 1.

0.3.x.x added this field which was originally called startingAddress.

0.3.x.x renamed fromstartingAddress to startingOutputId.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Compact 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact

Example Response:

Read Register Assembly Command Compact Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact"
      }
    },
    "id": "compact",
    "parameters": {
      "startingOutputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Compact Register Block 
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact

call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact {"startingOutputId":100}

Example Response:

Compact Register Block Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and after Compacting:

Compact Register Block Before And After 
Request:
   call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/compact

The block list before compacting:
    "blocks": [
      {
        "displayName": "Sensor Group State",
        "outputId": 50,
        "scannerId": "",
        "type": "Scanner"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 51,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 52,
        "scannerId": "",
        "type": "Measurement"
      }
    ],

The block list after compacting with a starting output id ("startingOutputId") set to 0:
    "blocks": [
      {
        "displayName": "Sensor Group State",
        "outputId": 0,        <--------------------------------------------
        "scannerId": "",
        "type": "Scanner"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 1,        <--------------------------------------------
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 2,        <--------------------------------------------
        "scannerId": "",
        "type": "Measurement"
      }
    ],

Notifications

None generated for this resource.

/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update

Resource Type: (CollectionItem , Callable)

Command to update (modify) the register block characteristics.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/outputId

integer

The output id of the register block to update.

parameters/newParams

object

Parameters used to update the register block specified by the output identifier.

parameters/newParams/dataSource

string

New data source identifier for the register block.

parameters/newParams/displayName

string

New display name for the register block.

parameters/newParams/outputId

integer

New output identifier value to assign to the register block.

parameters/newParams/scannerId

string

New scanner identifier for the register block.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

newParams

object

The information to apply to the specified register block.

newParams/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

newParams/displayName

string

Optional

The updated culture-specific string for the register block display name.

This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

newParams/outputId

integer

Optional

The new output identifier to assign to the register block.

newParams/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

outputId

integer

Mandatory

The output identifier of the register block to which the new parameters are applied.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Update 
read /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update

Example Response:

Read Register Assembly Command Update Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update"
      }
    },
    "id": "update",
    "parameters": {
      "autoShift": false,
      "newParams": {
        "dataSource": "",
        "displayName": "",
        "outputId": null,
        "scannerId": ""
      },
      "outputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Update Register Block 
// This update request doesn't change anything but is still a valid request.
call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update {"outputId" : 153, "newParams" : {}}

call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Example Response:

Update Register Block Response 
{
  "path": "/controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and After Updating:

Update Register Block Before And After 
Request:
   call /controls/e-ascii/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Before update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 153,
        "scannerId": "",
        "type": "Measurement"
      }
    ],

After update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "MyPointCount",         <--------------------------------------------
        "outputId": 200,                       <--------------------------------------------
        "scannerId": "",
        "type": "Measurement"
      }
    ],

Notifications

None generated for this resource.


GoPxL: EtherNet/IP Resources

This page describes the control service resource called Ethernet/IP Service that is included with each LMI Gocator release.

/controls/ethernetIp

Resource Type: (Standard)

Ethernet/IP resource supports the following properties:

Properties:

Item

Type

Schema

Description

displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "EtherNet/IP".

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "ethernetIp".

parameters object
Parameter settings applicable to the service.
parameters/bufferEnabled

boolean


Used to enable/disable buffering of scan outputs.

Buffering should be enabled when part detection is used and if multiple objects may be detectedwithin a time frame shorter than the polling rate of the PLC.

parameters/isBigEndianOutput

boolean


Indicates if output is in Big Endian Format.
parameters/implicitTriggerOverride integer enum

Implicit Trigger Override.

Values are:

  • 0 (EIP_TRIGGER_OVERRIDE_OFF) = Implicit Trigger Override Off
  • 1 (EIP_TRIGGER_OVERRIDE_CYCLIC) =Implicit Trigger Override Cyclic
  • 2 (EIP_TRIGGER_OVERRIDE_STATE_CHANGE) =Implicit Trigger Override Change of State
status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop 

explicitServerPort
 integer readOnly

Added in version 1.2.x.x

The network port that explicit Ethernet/IP service uses. 

implicitServerPort
 integer readOnly

Added in version 1.2.x.x

The network port that implicit Ethernet/IP service uses.

Methods

Method Description
read

Return property information about the service resource.

Example:

Read Resource 
read /controls/ethernetIp

Example Response:

Read Resource Response 
{
  "path": "/controls/ethernetIp",
  "payload": {
    "_embedded": {
      "go:registerAssembly": [
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/commandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/commandOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scannerState"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/systemState"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/ethernetIp"
      }
    },
    "displayName": "EtherNet/IP",
    "enabled": true,
    "id": "ethernetIp",
    "explicitServerPort": 44818,
    "implicitServerPort": 2222,
    "parameters": {
      "bufferEnabled": false,
      "implicitTriggerOverride": 0,
      "isBigEndianOutput": true
    },
    "status": 0
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/ethernetIp

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/ethernetIp",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/ethernetIp

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/ethernetIp",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/ethernetIp {"enabled" : true}
update /controls/ethernetIp {"enabled" : false}
update /controls/ethernetIp {"enabled" : true, "parameters" : {"bufferEnabled":true}}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/ethernetIp",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request: 
update /controls/ethernetIp {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/ethernetIp/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/ethernetIp/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/ethernetIp/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/ethernetIp/metrics",
  "payload": {
    "path": "/controls/ethernetIp/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/ethernetIp/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/ethernetIp/metrics

Example Response:


Cancel Stream Response 
{
  "path": "/controls/ethernetIp/metrics",
  "payload": {
    "path": "/controls/ethernetIp/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/ethernetIp/ registerAssemblies

All register assemblies support the properties below. Individual register assemblies may customize the properties to suit its needs. The customizations are described in the sections for each specific register assembly supported by this control service.

Resource Type: (Non Standard)

This resource is a parent to register assembly resources which are used to hold a list of data source outputs to send to a control service client.

1.0.x.x added support for registerAssemblies resource.

Reading the /controls/ethernetIp/registerAssemblies resource returns a list of register assembly resources supported by the control service. For Ethernet/IP, it supports the following register assemblies:

Register Assembly Display Name Register Assembly Internal Identifier Resource Path
"CommandInput" "commandInput" /controls/ethernetIp/registerAssemblies/commandInput
"Command Output" "commandOutput" /controls/ethernetIp/registerAssemblies/commandOutput
"Implicit Command Input" "implicitCommandInput" /controls/ethernetIp/registerAssemblies/implicitCommandInput
"Scan Output" "scanOutput" /controls/ethernetIp/registerAssemblies/scanOutput
"Sensor Group State" "scannerState" /controls/ethernetIp/registerAssemblies/scannerState
"System State" "systemState" /controls/ethernetIp/registerAssemblies/systemState

NOTE: Each register assembly in EtherNet/IP service has an corresponding object in the EtherNet/IP protocol. However, the mandatory Ethernet/IP protocol objects don't have register assemblies in the EtherNet/IP service.

Methods

Method

Description

read

Read this resource to find out what register assemblies are available for the resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies

Example response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/commandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/commandOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scannerState"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/systemState"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications
None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)

Resource Type: (Observable)

This is a resource to specify information output to the control service client. The type of information and the information location in the output is maintained by this resource.

Properties

Item

Type

Schema

Description

attributes

object

readOnly

Attributes of the register assembly resource.

attributes/isGlobalAddressSpaceUsed

boolean

Indicates if each output entry occupies a range of addresses (output identifier) in the register assembly.

Value of true means each output entry/item occupies a range of addresses (output identifiers) in the register assembly, corresponding to the register count of the register block.

Value of false means each output entry/item takes up one output identifier value, regardless of the register count of the register block.

attributes/outputIdMax

integer

The maximum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMax to outputIdMax.

attributes/outputIdMin

integer

The minimum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMin to outputIdMin.

blocks

array

Array of register blocks added to this register assembly. Each register block has its own set of properties.

blocks/n/

object

A register block entry.

blocks/n/dataSource

string

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks.

This field is not applicable to the other register blocks

blocks/n/displayName

string

Culture-specific string to describe the register block.
For measurement and stamp blocks this field is the register block name not the displayName of the dataSource field. This is for information only, do not use this field.

blocks/n/outputId

integer

Identifier of the output item.

Valid range is 0..2 16 -1.

The output identifier must not lie outside the range of values specified by attributes/outputIdMin and attributes/outputIdMax.

If attributes/isGlobalAddressSpaceUsed is true:

The identifier corresponds to the register address location in which the data for this block appears in the control services output.

The maximum blocks/n/outputId value must satisfy the following relationship to ensure all the register block's outputs do not go past the the last register address specified byattributes/outputIdMax:

blocks/n/outputId +supportedBlockTypes/n/registerCount - 1 <= attributes/outputIdMax

If attributes/isGlobalAddressSpaceUsed is false:

The maximum blocks/n/outputId value must satisfy the following relationship:

blocks/n/outputId <= attributes/outputIdMax

blocks/n/scannerId

string

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

readOnly

Unique internal identifier of the register block type (see Register Assembly Register Block Types ).

blocks/n/version

string

readOnly

1.2.x.x Register block version.

displayName

string

readOnly

Display name of the register assembly

id

string

readOnly

Register assembly internal identifier

version

string

readOnly

1.2.x.x Register assembly version.

supportedBlockTypes

array

readOnly

Array of register block types properties for block types that are supported by the control services register assembly.

supportedBlockTypes/n/

object

A register block type entry.

supportedBlockTypes/n/category

enum

Categorizes the purpose of a register block type.

Enumerated values are:

0 = Unknown purpose

1 = Used for receiving control input from client

2 = Used for sending control output to client

3 = Used for providing system state information to client

4 = Used for providing sensor group state information to client

5 = Used for providing stamp information to client

6 = Used for providing measurement value and/or decision information to client

supportedBlockTypes/n/displayName

string

Culture-specific string that can be presented to the user to describe the register block.

supportedBlockTypes/n/hasDataSource

boolean

Indicates if this register block type contains a data source or not.

Value is

  • true for stamp and measurement register blocks

  • false for the other register blocks.

supportedBlockTypes/n/instanceCount

integer

Number of instances of this register block type that has been added by user.

Must be:

  • greater than or equal tosupportedBlockTypes/n/minInstance and

  • less than or equal tosupportedBlockTypes/n/maxInstance.

supportedBlockTypes/n/maxInstanceCount

integer

Maximum number of instances of this register block type that this register assembly can have.

supportedBlockTypes/n/minInstanceCount

integer

Minimum number of instances of this register block type that this register assembly can have.

A value of 0 means this register block type is optional for this register assembly.

A value N greater than 0 means N instances are created automatically on start up.

supportedBlockTypes/n/registerCount

integer

This value is meaningful only for register assemblies where attributes/isGlobalAddressSpaceUsed is true.

It is the number of address locations in the output that this register block takes up.

This number is determined by what output information are available for a register block and is constant for that register block type.

supportedBlockTypes/n/type

string

Internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).
Used by client to refer to this register block type for operations on the register assembly.

Each register assembly customizes the register assembly properties and are described in each specific register assembly.

Methods

Method Description
read

See the specific register assembly for more details.

sub

See the specific register assembly for more details.

unSub

See the specific register assembly for more details.

Notifications

Notification Description
updated

See the specific register assembly for more details.

/controls/ethernetIp/registerAssemblies/commandInput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly

Value is set to false.

attributes/ outputIdMax

integer

readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName string readOnly "Command Input"
id string readOnly "commandInput"
supportedBlockTypes/n/category integer readOnly Only supports category 1.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 1: "ControlInput"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/commandInput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandInput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/remove"
        },
		{
          "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/commandInput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput",
        "version": "1.2"
      }
    ],
    "displayName": "Command Input",
    "id": "commandInput",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 1,
        "displayName": "Command Input",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 67,
        "type": "ControlInput"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/commandInput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/commandInput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/commandInput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/registerAssemblies/commandOutput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.

attributes/ outputIdMax

integer

readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName string readOnly "Command Output"
id string readOnly "commandOutput"
supportedBlockTypes/n/category integer readOnly Only supports category 2.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 2 ("Control Output"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 2 ("Control Output"): Value is set to 1.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 2: "ControlOutput"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/commandOutput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandOutput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/remove"
        },
		{
          "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/commandOutput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Output",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlOutput",
        "version": "1.2"
      }
    ],
    "displayName": "Command Output",
    "id": "commandOutput",
	"version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 2,
        "displayName": "Command Output",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 3,
        "type": "ControlOutput"
      }
    ]
  },
  "status": 1,
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/commandOutput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/commandOutput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/commandOutput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/registerAssemblies/implicitCommandInput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName string readOnly "Implicit Command Input"
id string readOnly "implicitCommandInput"
supportedBlockTypes/n/ category integer readOnly Only supports category 1.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 1: "ControlInput"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/implicitCommandInput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/implicitCommandInput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/remove"
        },
 		{
          "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput",
        "version": "1.2"
      }
    ],
    "displayName": "Implicit Command Input",
    "id": "implicitCommandInput",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 1,
        "displayName": "Command Input",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 67,
        "type": "ControlInput"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/implicitCommandInput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/implicitCommandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/implicitCommandInput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/implicitCommandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/implicitCommandInput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/ controls/ethernetIp/registerAssemblies/scanOutput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to true.
attributes/ outputIdMax integer readOnly Value is set to 376.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Scan Output"

id string readOnly "scanOutput"
supportedBlockTypes/n/category integer readOnly Categories 5 and 6 are supported.
supportedBlockTypes/n/maxInstanceCount integer readOnly

Value for each supported register block type by category name:

  • Category 5 ("Stamp"): Value is set to 65534.
  • Category 6 ("Measurement"): Value is set to 65534.
supportedBlockTypes/n/minInstanceCount integer readOnly

Value for each supported register block type by category name:

  • Category 5 ("Stamp"): Value is set to 0.
  • Category 6 ("Measurement"): Value is set to 0.
supportedBlockTypes/n/registerCount integer readOnly

Value for each supported register block type by category name:

  • Category 5 ("Stamp"): Value is set to 36.
  • Category 6 ("Measurement"): Value is set to 4.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier by category:
  • Category 5: "Stamp"
  • Category 6: "MeasurementValue"

1.1.x.x The "MeasurementValue" register block is added as supported block type and removed "Measurement" block.

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/scanOutput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/remove"
        },
 		{
          "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": true,
      "outputIdMax": 375,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "dataSource": "tools:ProfilePosition-2:outputs:X",
        "displayName": "Measurement",
        "outputId": 0,
        "scannerId": "",
        "type": "MeasurementValue",
        "version": "1.2"
      }
    ],
    "displayName": "Scan Output",
    "id": "scanOutput",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 5,
        "displayName": "Stamp",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 36,
        "type": "Stamp"
      },
      {
        "category": 6,
        "displayName": "Measurement",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 4,
        "type": "MeasurementValue"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/scanOutput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/scanOutput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/registerAssemblies/scannerState

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Sensor Group State"
id string readOnly "scannerState"
supportedBlockTypes/n/category integer readOnly Only supports category 4.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 4 ("Scanner"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 4 ("Scanner"): Value is set to 1.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier:
  • Category 4: "Scanner"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/scannerState

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scannerState",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/remove"
        },
     	{
          "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scannerState"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Sensor Group State",
        "outputId": 0,
        "scannerId": "",
        "type": "Scanner",
        "version": "1.2"
      }
    ],
    "displayName": "Sensor Group State",
    "id": "scannerState",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 4,
        "displayName": "Sensor Group State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 18,
        "type": "Scanner"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/scannerState

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/scannerState

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/scannerState/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/registerAssemblies/systemState

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"System State"

id string readOnly "systemState"
supportedBlockTypes/n/category integer readOnly Only supports category 3.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 3 ("System"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 3 ("System"): Value is set to 1.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier:
  • Category 3: "System"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/ethernetIp/registerAssemblies/systemState

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/systemState",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/add"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/remove"
        },
   		{
          "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/removeAll"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/compact"
        },
        {
          "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/update"
        }
      ],
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/systemState"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "System State",
        "outputId": 0,
        "scannerId": "",
        "type": "System",
        "version": "1.2"
      }
    ],
    "displayName": "System State",
    "id": "systemState",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 3,
        "displayName": "System State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 76,
        "type": "System"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/ethernetIp/registerAssemblies/systemState

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/ethernetIp/registerAssemblies/systemState

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/ethernetIp/registerAssemblies/systemState/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/ethernetIp/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/ethernetIp/registerAssemblies/( registerAssemblyId )/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's register assembly. These commands can be used to modify the register blocks inside the register assemblys array of register blocks called blocks. Depending on the characteristics of the supported block type, some commands may not be applicable.

For example, attempt to add a second instance of a supported block type that only allows one instance to be present is rejected.

Methods

Method Description
read

Returns a list of register assembly commands as embedded resources.

Example:

Read Register Assembly Commands 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands

Example Response:

Read Register Assembly Commands Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/remove"
            }
          }
        },
  		{
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/compact"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one or more register blocks to the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/blocks

array<object>

An array of register block information describing the registers blocks that are to be added to the register Tassembly

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

Value of true means the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

Value of false means overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

blocks

array

Array of register blocks to be added to the register assembly

blocks/n/

object

One entry of register block information.

blocks/n/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

blocks/n/displayName

string

Optional

Culture-specific string to describe the register block.This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

blocks/n/outputId

integer

Optional

Output identifier for this output item.

If not provided as an argument, then the register block is added after the last register block.

The valid range for the output id is0..2 16 -1. If the client enters an output id value that is greater than2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the output id will be processed as 0x0001 which is equal to 1.

blocks/n/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

Mandatory

Unique internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Add 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands/add

Example Response:

Read Register Assembly Command Add Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/add"
      }
    },
    "id": "add",
    "parameters": {
      "autoShift": false,
      "blocks": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Add Register Block 
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/add {
    "blocks" : [{
        "type":"Measurement", 
        "dataSource" : "tools:ProfileInfo-0:outputs:MaxZ"}], 
    "autoShift" : false}

Example Response:

Add Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/add",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/outputIdList

array<integer>

Array of one or more output identifiers to remove from the register assembly.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputIdList

array

Mandatory

Array of one or more output identifiers to remove from the register assembly.

outputIdList/n/

integer

One output identifier.

outputIdList/n/outputId

integer

The output id to remove from the register assembly.

At least one entry must be provided.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands/remove

Example Response:

Read Register Assembly Command Remove Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/remove"
      }
    },
    "id": "remove",
    "parameters": {
      "outputIdList": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove Register Block 
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/remove {"outputIdList":[{"outputId":33}]}

Example Response:

Remove Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/remove",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Minimum supported version 1.2.x.x .

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove All 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll

Example Response:

Read Register Assembly Command Remove All Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll"
      }
    },
    "id": "removeAll",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove All Register Block 
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll

Example Response:

Remove All Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/removeAll",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)/commands/compact

Resource Type: (CollectionItem , Callable)

Command to compact (remove gaps from) the register block output identifiers within the register assembly to eliminate unused space between register blocks.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/startingOutputId

integer

Output identifier to assign to the first register block during the compacting operation.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

startingOutputId

integer

Optional

Output identifier to assign to the first register block during the compacting operation.

Ifattributes/isGlobalAddressSpaceUsed is true, the minimum and maximum values is limited by the register assembly's minimum and maximum address value.

The maximum value allowed for the compact command is likely to be less than the register assembly's maximum address value to allow a register block to fit within the register assembly's address range.

If no startingAddress is provided, then the default value is the register assembly's attribute outputIdMin value.

Ifattributes/isGlobalAddressSpaceUsed is false, and if not provided as an argument, the value of zero (0) is used as the starting output identifier value.

If the client enters an output id value that is greater than2 16 -1 (65535), which is the largest value that 16-bits can represent, the output id will get truncated to a 16 bit value.

e.g. Client enters anoutput id equal to 65537. 65537 is equal to 0x10001. However, the output id will be truncated by the REST API and processed as 0x0001 which is equal to 1.

0.3.x.x added this field which was originally called startingAddress.

0.3.x.x renamed fromstartingAddress to startingOutputId.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Compact 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands/compact

Example Response:

Read Register Assembly Command Compact Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/compact",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/compact"
      }
    },
    "id": "compact",
    "parameters": {
      "startingOutputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Compact Register Block 
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/compact {"startingOutputId":100}

Example Response:

Compact Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/compact",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and after Compacting:

Compact Register Block Before And After 
Request:
   call /controls/ethernetIp/registerAssemblies/scanOutput/commands/compact {"startingOutputId":100}

The block list before compacting:
    "blocks": [
      {
        "dataSource": "scan:LMILaserLineProfiler:scanner-0:stamp",
        "displayName": "bar",
        "outputId": 0,
        "scannerId": "",
        "type": "Stamp"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 38,
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

The block list after compacting with a starting output id ("startingOutputId") set to 100 (note: the stamp source register count (size) is 33 bytes in this example):
    "blocks": [
      {
        "dataSource": "scan:LMILaserLineProfiler:scanner-0:stamp",
        "displayName": "bar",
        "outputId": 100,       <--------------------------------------------
        "scannerId": "",
        "type": "Stamp"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 133,       <--------------------------------------------
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

Notifications

None generated for this resource.

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)/commands/update

Resource Type: (CollectionItem , Callable)

Command to update (modify) the register block characteristics.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/outputId

integer

The output id of the register block to update.

parameters/newParams

object

Parameters used to update the register block specified by the output identifier.

parameters/newParams/dataSource

string

New data source identifier for the register block.

parameters/newParams/displayName

string

New display name for the register block.

parameters/newParams/outputId

integer

New output identifier value to assign to the register block.

parameters/newParams/scannerId

string

New scanner identifier for the register block.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

newParams

object

The information to apply to the specified register block.

newParams/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

newParams/displayName

string

Optional

The updated culture-specific string for the register block display name.

This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

newParams/outputId

integer

Optional

The new output identifier to assign to the register block.

newParams/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

outputId

integer

Mandatory

The output identifier of the register block to which the new parameters are applied.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Update 
read /controls/ethernetIp/registerAssemblies/scanOutput/commands/update

Example Response:

Read Register Assembly Command Update Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update"
      }
    },
    "id": "update",
    "parameters": {
      "autoShift": false,
      "newParams": {
        "dataSource": "",
        "displayName": "",
        "outputId": null,
        "scannerId": ""
      },
      "outputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Update Register Block 
// This update request doesn't change anything but is still a valid request.
call /controls/ethernetIp/registerAssemblies/scanOutput/commands/update {"outputId":133, "newParams":{}}

call /controls/ethernetIp/registerAssemblies/scanOutput/commands/update {"outputId":133, "newParams":{"displayName":"MinZMeas", "outputId" : 150}}

Example Response:

Update Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and After Updating:

Update Register Block Before And After 
Request:
   call /controls/ethernetIp/registerAssemblies/scanOutput/commands/update {"outputId":133, "newParams":{"displayName":"MinZMeas", "outputId" : 150}}

Before update:
   "blocks": [
      {
        "dataSource": "scan:LMILaserLineProfiler:scanner-0:stamp",
        "displayName": "bar",
        "outputId": 100,
        "scannerId": "",
        "type": "Stamp"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 133,
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

After update:
    "blocks": [
      {
        "dataSource": "scan:LMILaserLineProfiler:scanner-0:stamp",
        "displayName": "bar",
        "outputId": 100,
        "scannerId": "",
        "type": "Stamp"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "MinZMeas",    <--------------------------------------------
        "outputId": 150,              <--------------------------------------------
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

Notifications

None generated for this resource.


GoPxL: Profinet Resources

This page describes the control service resource called Profinet Service that is included with each LMI Gocator release.

/controls/profinet

Resource Type: (Standard)

Profinet resource supports the following properties:

Properties:

Item Type Schema Description
deviceName string readOnly

1.2.x.x Device name of the Profinet service that is set to NULL string by default. The value is set through Profinet client and the REST interface has only read only permission.

displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "PROFINET"

gatewayAddress string readOnly

1.2.x.x Gateway address of the Profinet service is set to the gateway address of the GoPxl service started interface. The value is set through Profinet client and the REST interface has only read only permission.

ipAddress string readOnly

1.2.x.x IP address of the Profinet service is set to the IP address of the GoPxl service started interface. The value is set through Profinet client and the REST interface has only read only permission.

subnetMask string readOnly

1.2.x.x Subnet mask of the Profinet service is set to the Subnet mask of the GoPxl service started interface. The value is set through Profinet client and the REST interface has only read only permission.

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "profinet".

parameters object

Parameter settings applicable to the service.

This service currently has no user configurable parameters.

status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

Methods

Method Description
read

Return property information about the service resource.

Example:

Read Resource 
read /controls/profinet

Example Response:

Read Resource Response 
{
  "path": "/controls/profinet",
  "payload": {
    "_embedded": {
      "go:registerAssembly": [
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/commandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/commandOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/scannerState"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/systemState"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/profinet"
      }
    },
    "deviceName": "",
    "displayName": "PROFINET",
    "gatewayAddress": "0.0.0.0",
    "id": "profinet",
    "ipAddress": "90.0.0.4",
    "status": 0,
    "subnetMask": "0.0.0.0",
    "enabled": true,
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/profinet

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/profinet",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/profinet

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/profinet",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Property 
update /controls/profinet{"enabled" : true}
update /controls/profinet{"enabled" : false}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/profinet",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request: 
update /controls/profinet {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/profinet/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/profinet/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/profinet/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/profinet/metrics",
  "payload": {
    "path": "/controls/profinet/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/profinet/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/profinet/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/profinet/metrics",
  "payload": {
    "path": "/controls/profinet/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies

All register assemblies support the properties below. Individual register assemblies may customize the properties to suit its needs. The customizations are described in the sections for each specific register assembly supported by this control service.

Resource Type: (Non Standard)

This resource is a parent to register assembly resources which are used to hold a list of data source outputs to send to a control service client.

1.0.x.x added support for registerAssemblies resource.

Reading the /controls/profinet/registerAssemblies resource returns a list of register assembly resources supported by the control service. For Profinet, it supports the following register assemblies:

Register Assembly Display Name Register Assembly Internal Identifier Resource Path
"CommandInput" "commandInput" /controls/profinet/registerAssemblies/commandInput
"Command Output" "commandOutput" /controls/profinet/registerAssemblies/commandOutput
"Stamp Scan Output" "stamp" /controls/profinet/registerAssemblies/stamp
"Measurement Scan Output" "measurement" /controls/profinet/registerAssemblies/measurement
"Sensor Group State" "scannerState" /controls/profinet/registerAssemblies/scannerState
"System State" "systemState" /controls/profinet/registerAssemblies/systemState

Methods

Method

Description

read

Read this resource to find out what register assemblies are available for the resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies

Example response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/commandInput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/commandOutput"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/scannerState"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/systemState"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications
None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssembly)

Resource Type: (Observable)

This is a resource to specify information output to the control service client. The type of information and the information location in the output is maintained by this resource.

Properties

Item

Type

Schema

Description

attributes

object

readOnly

Attributes of the register assembly resource.

attributes/isGlobalAddressSpaceUsed

boolean

Indicates if each output entry occupies a range of addresses (output identifier) in the register assembly.

Value of true means each output entry/item occupies a range of addresses (output identifiers) in the register assembly, corresponding to the register count of the register block.

Value of false means each output entry/item takes up one output identifier value, regardless of the register count of the register block.

attributes/outputIdMax

integer

The maximum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMax to outputIdMax.

attributes/outputIdMin

integer

The minimum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMin to outputIdMin.

blocks

array

Array of register blocks added to this register assembly. Each register block has its own set of properties.

blocks/n/

object

A register block entry.

blocks/n/dataSource

string

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks.

This field is not applicable to the other register blocks

blocks/n/displayName

string

Culture-specific string to describe the register block.
For measurement and stamp blocks this field is the register block name not the displayName of the dataSource field. This is for information only, do not use this field.

blocks/n/outputId

integer

Identifier of the output item.

Valid range is 0..2 16 -1.

The output identifier must not lie outside the range of values specified by attributes/outputIdMin and attributes/outputIdMax.

If attributes/isGlobalAddressSpaceUsed is true:

The identifier corresponds to the register address location in which the data for this block appears in the control services output.

The maximum blocks/n/outputId value must satisfy the following relationship to ensure all the register block's outputs do not go past the the last register address specified byattributes/outputIdMax:

blocks/n/outputId +supportedBlockTypes/n/registerCount - 1 <= attributes/outputIdMax

If attributes/isGlobalAddressSpaceUsed is false:

The maximum blocks/n/outputId value must satisfy the following relationship:

blocks/n/outputId <= attributes/outputIdMax

blocks/n/scannerId

string

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

readOnly

Unique internal identifier of the register block type (see Register Assembly Register Block Types ).

blocks/n/version

string

readOnly

1.2.x.x Register block version.

displayName

string

readOnly

Display name of the register assembly

id

string

readOnly

Register assembly internal identifier

version

string

readOnly

1.2.x.x Register assembly version.

supportedBlockTypes

array

readOnly

Array of register block types properties for block types that are supported by the control services register assembly.

supportedBlockTypes/n/

object

A register block type entry.

supportedBlockTypes/n/category

enum

Categorizes the purpose of a register block type.

Enumerated values are:

0 = Unknown purpose

1 = Used for receiving control input from client

2 = Used for sending control output to client

3 = Used for providing system state information to client

4 = Used for providing sensor group state information to client

5 = Used for providing stamp information to client

6 = Used for providing measurement value and/or decision information to client

supportedBlockTypes/n/displayName

string

Culture-specific string that can be presented to the user to describe the register block.

supportedBlockTypes/n/hasDataSource

boolean

Indicates if this register block type contains a data source or not.

Value is

  • true for stamp and measurement register blocks

  • false for the other register blocks.

supportedBlockTypes/n/instanceCount

integer

Number of instances of this register block type that has been added by user.

Must be:

  • greater than or equal tosupportedBlockTypes/n/minInstance and

  • less than or equal tosupportedBlockTypes/n/maxInstance.

supportedBlockTypes/n/maxInstanceCount

integer

Maximum number of instances of this register block type that this register assembly can have.

supportedBlockTypes/n/minInstanceCount

integer

Minimum number of instances of this register block type that this register assembly can have.

A value of 0 means this register block type is optional for this register assembly.

A value N greater than 0 means N instances are created automatically on start up.

supportedBlockTypes/n/registerCount

integer

This value is meaningful only for register assemblies where attributes/isGlobalAddressSpaceUsed is true.

It is the number of address locations in the output that this register block takes up.

This number is determined by what output information are available for a register block and is constant for that register block type.

supportedBlockTypes/n/type

string

Internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).
Used by client to refer to this register block type for operations on the register assembly.

Each register assembly customizes the register assembly properties and are described in each specific register assembly.

Methods

Method Description
read

See the specific register assembly for more details.

sub

See the specific register assembly for more details.

unSub

See the specific register assembly for more details.

Notifications

Notification Description
updated

See the specific register assembly for more details.

/controls/profinet/registerAssemblies/commandInput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Command Input"
id string readOnly "commandInput"
supportedBlockTypes/n/category integer readOnly Only supports category 1.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 1 ("Control Input"): Value is set to 1.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 1: "ControlInput"

Methods

Method Descriptions
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/commandInput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandInput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/commandInput/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandInput/commands/remove"
        },
  		{
          "href": "/controls/profinet/registerAssemblies/commandInput/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandInput/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandInput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/commandInput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Input",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlInput",
        "version": "1.2"
      }
    ],
    "displayName": "Command Input",
    "id": "commandInput",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 1,
        "displayName": "Command Input",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 67,
        "type": "ControlInput"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/commandInput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/commandInput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/commandInput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/commandInput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/commandOutput

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Command Output"
id string readOnly

"commandOutput"

supportedBlockTypes/n/category integer readOnly Only supports category 2.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 2 ("Control Output"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 2 ("Control Output"): Value is set to 1.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 2: "ControlOutput"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/commandOutput

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandOutput",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/commandOutput/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandOutput/commands/remove"
        },
		{
          "href": "/controls/profinet/registerAssemblies/commandOutput/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandOutput/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/commandOutput/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/commandOutput"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Command Output",
        "outputId": 0,
        "scannerId": "",
        "type": "ControlOutput",
        "version": "1.2"
      }
    ],
    "displayName": "Command Output",
    "id": "commandOutput",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 2,
        "displayName": "Command Output",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 3,
        "type": "ControlOutput"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/commandOutput

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/commandOutput

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/commandOutput/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/commandOutput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/stamp

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to true.
attributes/ outputIdMax integer readOnly

Value is set to 35.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Stamp Scan Output"
id string readOnly

"stamp"

supportedBlockTypes/n/category integer readOnly Only supports category 5.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 5 ("Stamp"): Value is set to 65534.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 5 ("Stamp"): Value is set to zero (0).
supportedBlockTypes/n/registerCount integer readOnly Category 5 ("Stamp"): Value is set to 36.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

  • Category 5: "Stamp"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/stamp

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/stamp",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/stamp/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/stamp/commands/remove"
        },
		{
          "href": "/controls/profinet/registerAssemblies/stamp/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/stamp/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/stamp/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/stamp"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": true,
      "outputIdMax": 35,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "dataSource": "scan:LMIFringeSnapshot:scanner-0:stamp",
        "displayName": "Stamp",
        "outputId": 0,
        "scannerId": "",
        "type": "Stamp",
        "version": "1.2"
      }
    ],
    "displayName": "Stamp Scan Output",
    "id": "stamp",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 5,
        "displayName": "Stamp",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 36,
        "type": "Stamp"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/stamp

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/stamp",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/stamp

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/stamp",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/stamp/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/stamp",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/measurement

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to true.
attributes/ outputIdMax integer readOnly

Value is set to 800.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Measurement Scan Output"
id string readOnly "measurement"
supportedBlockTypes/n/category integer readOnly Only supports category 6.
supportedBlockTypes/n/maxInstanceCount integer readOnly

Category 6 ("Measurement"): Value is set to 65534.

supportedBlockTypes/n/minInstanceCount integer readOnly

Category 6 ("Measurement"): Value is set to zero (0).

supportedBlockTypes/n/registerCount integer readOnly Category 6 ("Measurement"): Value is set to 4.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier:
  • Category 6: "MeasurementValue"

1.1.x.x The "MeasurementValue" register block is added as supported block type and removed "Measurement" block.

Methods

Method Notification
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/measurement

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/measurement/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/measurement/commands/remove"
        },
		{
          "href": "/controls/profinet/registerAssemblies/measurement/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/measurement/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/measurement/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": true,
      "outputIdMax": 799,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "dataSource": "tools:ProfilePosition-2:outputs:X",
        "displayName": "Measurement",
        "outputId": 0,
        "scannerId": "",
        "type": "MeasurementValue",
        "version": "1.2"
      }
    ],
    "displayName": "Measurement Scan Output",
    "id": "measurement",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 6,
        "displayName": "Measurement",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 4,
        "type": "MeasurementValue"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/measurement

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/measurement

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/measurement/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/measurement",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/scannerState

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"Sensor Group State"
id string readOnly "scannerState"
supportedBlockTypes/n/category integer readOnly Only supports category 4.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 4 ("Scanner"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 4 ("Scanner"): Value is set to 1.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier:
  • Category 4: "Scanner"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/scannerState

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/scannerState",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/scannerState/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/scannerState/commands/remove"
        },
		{
          "href": "/controls/profinet/registerAssemblies/scannerState/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/scannerState/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/scannerState/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/scannerState"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "Sensor Group State",
        "outputId": 0,
        "scannerId": "",
        "type": "Scanner",
        "version": "1.2"
      }
    ],
    "displayName": "Sensor Group State",
    "id": "scannerState",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 4,
        "displayName": "Sensor Group State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 18,
        "type": "Scanner"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/scannerState

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/scannerState

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/scannerState/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/scannerState",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/systemState

This register assembly customizes the register assembly properties as follows:

Item

Type

Schema

Description

attributes/isGlobalAddressSpaceUsed

boolean

readOnly Value is set to false.
attributes/ outputIdMax integer readOnly

Value is set to 65534.

attributes/ outputIdMin

integer

readOnly

Value is set to zero (0).

displayName

string

readOnly

"System State"
id string readOnly "systemState"
supportedBlockTypes/n/category integer readOnly Only supports category 3.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 3 ("System"): Value is set to 1.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 3 ("System"): Value is set to 1.
supportedBlockTypes/n/type string readOnly Supported register block type internal identifier:
  • Category 3: "System"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/profinet/registerAssemblies/systemState

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/systemState",
  "payload": {
    "_links": {
      "go:command": [
        {
          "href": "/controls/profinet/registerAssemblies/systemState/commands/add"
        },
        {
          "href": "/controls/profinet/registerAssemblies/systemState/commands/remove"
        },
		{
          "href": "/controls/profinet/registerAssemblies/systemState/commands/removeAll"
        },
        {
          "href": "/controls/profinet/registerAssemblies/systemState/commands/compact"
        },
        {
          "href": "/controls/profinet/registerAssemblies/systemState/commands/update"
        }
      ],
      "self": {
        "href": "/controls/profinet/registerAssemblies/systemState"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "displayName": "System State",
        "outputId": 0,
        "scannerId": "",
        "type": "System",
        "version": "1.2"
      }
    ],
    "displayName": "System State",
    "id": "systemState",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 3,
        "displayName": "System State",
        "hasDataSource": false,
        "instanceCount": 1,
        "maxInstanceCount": 1,
        "minInstanceCount": 1,
        "registerCount": 76,
        "type": "System"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/profinet/registerAssemblies/systemState

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/profinet/registerAssemblies/systemState

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/profinet/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/profinet/registerAssemblies/systemState/commands/update {"newParams":{"displayName":"foo"}, "outputId":0}

Notification:
{
  "eventType": "updated",
  "path": "/controls/profinet/registerAssemblies/systemState",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's register assembly. These commands can be used to modify the register blocks inside the register assemblys array of register blocks called blocks. Depending on the characteristics of the supported block type, some commands may not be applicable.

For example, attempt to add a second instance of a supported block type that only allows one instance to be present is rejected.

Methods

Method Description
read

Returns a list of register assembly commands as embedded resources.

Example:

Read Register Assembly Commands 
read /controls/profinet/registerAssemblies/measurement/commands

Example Response:

Read Register Assembly Commands Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/remove"
            }
          }
        },
		{
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/removeAll"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/compact"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/update"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one or more register blocks to the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/blocks

array<object>

An array of register block information describing the registers blocks that are to be added to the register Tassembly

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

Value of true means the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

Value of false means overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

blocks

array

Array of register blocks to be added to the register assembly

blocks/n/

object

One entry of register block information.

blocks/n/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

blocks/n/displayName

string

Optional

Culture-specific string to describe the register block.This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

blocks/n/outputId

integer

Optional

Output identifier for this output item.

If not provided as an argument, then the register block is added after the last register block.

The valid range for the output id is0..2 16 -1. If the client enters an output id value that is greater than2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the output id will be processed as 0x0001 which is equal to 1.

blocks/n/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

Mandatory

Unique internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Add 
read /controls/profinet/registerAssemblies/measurement/commands/add

Example Response:

Read Register Assembly Command Add Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands/add"
      }
    },
    "id": "add",
    "parameters": {
      "autoShift": false,
      "blocks": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Add Register Block 
call /controls/profinet/registerAssemblies/measurement/commands/add {
    "blocks" : [{
        "type":"Measurement", 
        "dataSource" : "tools:ProfileInfo-0:outputs:MaxZ"}], 
    "autoShift" : false}

Example Response:

Add Register Block Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/add",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/outputIdList

array<integer>

Array of one or more output identifiers to remove from the register assembly.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputIdList

array

Mandatory

Array of one or more output identifiers to remove from the register assembly.

outputIdList/n/

integer

One output identifier.

outputIdList/n/outputId

integer

The output id to remove from the register assembly.

At least one entry must be provided.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove 
read /controls/profinet/registerAssemblies/measurement/commands/remove

Example Response:

Read Register Assembly Command Remove Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands/remove"
      }
    },
    "id": "remove",
    "parameters": {
      "outputIdList": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove Register Block 
call /controls/profinet/registerAssemblies/measurement/commands/remove {"outputIdList":[{"outputId":0}]}

Example Response:

Remove Register Block Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/remove",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands/removeAll

Resource Type: (CollectionItem , Callable)

Command to remove all register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Minimum supported version 1.2.x.x .

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

Call Command Arguments

No arguments required.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove All 
read /controls/profinet/registerAssemblies/measurement/commands/removeAll

Example Response:

Read Register Assembly Command Remove All Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/removeAll",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands/removeAll"
      }
    },
    "id": "removeAll",
    "parameters": {}
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove All Register Block 
call /controls/profinet/registerAssemblies/measurement/commands/removeAll

Example Response:

Remove All Register Block Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/removeAll",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands/compact

Resource Type: (CollectionItem , Callable)

Command to compact (remove gaps from) the register block output identifiers within the register assembly to eliminate unused space between register blocks.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/startingOutputId

integer

Output identifier to assign to the first register block during the compacting operation.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

startingOutputId

integer

Optional

Output identifier to assign to the first register block during the compacting operation.

Ifattributes/isGlobalAddressSpaceUsed is true, the minimum and maximum values is limited by the register assembly's minimum and maximum address value.

The maximum value allowed for the compact command is likely to be less than the register assembly's maximum address value to allow a register block to fit within the register assembly's address range.

If no startingAddress is provided, then the default value is the register assembly's attribute outputIdMin value.

Ifattributes/isGlobalAddressSpaceUsed is false, and if not provided as an argument, the value of zero (0) is used as the starting output identifier value.

If the client enters an output id value that is greater than2 16 -1 (65535), which is the largest value that 16-bits can represent, the output id will get truncated to a 16 bit value.

e.g. Client enters anoutput id equal to 65537. 65537 is equal to 0x10001. However, the output id will be truncated by the REST API and processed as 0x0001 which is equal to 1.

0.3.x.x added this field which was originally called startingAddress.

0.3.x.x renamed fromstartingAddress to startingOutputId.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Compact 
read /controls/profinet/registerAssemblies/scanOutput/commands/compact

Example Response:

Read Register Assembly Command Compact Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/compact",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands/compact"
      }
    },
    "id": "compact",
    "parameters": {
      "startingOutputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Compact Register Block 
call /controls/profinet/registerAssemblies/measurement/commands/compact {"startingOutputId":0}

Example Response:

Compact Register Block Response 
{
  "path": "/controls/profinet/registerAssemblies/scanOutput/commands/compact",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and after Compacting:

Compact Register Block Before And After 
Request:
   call /controls/profinet/registerAssemblies/measurement/commands/compact {"startingOutputId":0}

The block list before compacting:
    "blocks": [
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 5,
        "scannerId": "",
        "type": "MeasurementValue"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Measurement",
        "outputId": 10,
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

The block list after compacting with a starting output id ("startingOutputId") set to 0
    "blocks": [
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 0,      <--------------------------------------------
        "scannerId": "",
        "type": "MeasurementValue"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Measurement",
        "outputId": 5,      <--------------------------------------------
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

Notifications

None generated for this resource.

/controls/profinet/registerAssemblies/(registerAssemblyId)/commands/update

Resource Type: (CollectionItem , Callable)

Command to update (modify) the register block characteristics.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/outputId

integer

The output id of the register block to update.

parameters/newParams

object

Parameters used to update the register block specified by the output identifier.

parameters/newParams/dataSource

string

New data source identifier for the register block.

parameters/newParams/displayName

string

New display name for the register block.

parameters/newParams/outputId

integer

New output identifier value to assign to the register block.

parameters/newParams/scannerId

string

New scanner identifier for the register block.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

newParams

object

The information to apply to the specified register block.

newParams/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

newParams/displayName

string

Optional

The updated culture-specific string for the register block display name.

This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

newParams/outputId

integer

Optional

The new output identifier to assign to the register block.

newParams/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

outputId

integer

Mandatory

The output identifier of the register block to which the new parameters are applied.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Update 
read /controls/profinet/registerAssemblies/measurement/commands/update

Example Response:

Read Register Assembly Command Update Response 
{
  "path": "/controls/profinet/registerAssemblies/measurement/commands/update",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/profinet/registerAssemblies/measurement/commands/update"
      }
    },
    "id": "update",
    "parameters": {
      "autoShift": false,
      "newParams": {
        "dataSource": "",
        "displayName": "",
        "outputId": null,
        "scannerId": ""
      },
      "outputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Update Register Block 
// This update request doesn't change anything but is still a valid request.
call /controls/profinet/registerAssemblies/measurement/commands/update {"outputId":0, "newParams":{}}

call /controls/profinet/registerAssemblies/measurement/commands/update {"outputId":0, "newParams":{"displayName":"MinZMeas", "outputId" : 150}}

Example Response:

Update Register Block Response 
{
  "path": "/controls/ethernetIp/registerAssemblies/measurement/commands/update",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and After Updating:

Update Register Block Before And After 
Request:
   call /controls/profinet/registerAssemblies/measurement/commands/update {"outputId":0, "newParams":{"displayName":"MinZMeas", "outputId" : 150}}

Before update:
    "blocks": [
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "Measurement",
        "outputId": 0,
        "scannerId": "",
        "type": "MeasurementValue"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Measurement",
        "outputId": 5,
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],


After update:
    "blocks": [
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Measurement",
        "outputId": 5,
        "scannerId": "",
        "type": "MeasurementValue"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MinZ",
        "displayName": "MinZMeas",    <--------------------------------------------
        "outputId": 150,              <--------------------------------------------
        "scannerId": "",
        "type": "MeasurementValue"
      }
    ],

Notifications

None generated for this resource.


GoPxL: Digital Output Resources

This page describes the control service resource called Digital Output Service that is included with each LMI Gocator release.

1.2.x.x Initial release of digital output service.

/controls/digitalOutput

Resource Type: (Standard)

Digital output resource supports the following properties:

Properties:

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (ie. translatable). This is the name that a client should display to the user.

Value is set to "Digital Output"

enabled

boolean


Used to enable or disable the service.
id string readOnly

Identifier name of the service type. This identifier name is the one used in the REST URI to access this service.

Value is set to "digitalOutput".

parameters object

Parameter settings applicable to the service.

This service currently has no user configurable parameters.

status integer

enum,

readOnly

Status of the service.

0.3.x.x Added these enumerated values for this field:

0 = Running

1 = Stopped

2 = Starting

3 = Stopping

4 = Failed To Start

5 = Failed To Stop

Methods

Method Description
read

Return property information about the service resource.

Example:

Read Resource 
read /controls/digitalOutput

Example Response:

Read Resource Response 
{
"path": "/controls/digitalOutput",
"payload": {
"displayName": "Digital Output",
"id": "digitalOutput",
"status": 1,
"enabled": false,
"parameters": {},
"_links": {
"self": {
"href": "/controls/digitalOutput"
}
},
"_embedded": {
"go:availableIoDevices": {
"_links": {
"self": {
"href": "/controls/digitalOutput/availableDevices"
}
}
},
"go:ioDevices": {
"_links": {
"self": {
"href": "/controls/digitalOutput/devices"
}
}
}
}
},
"status": 1,
"type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe to Resource 
sub /controls/digitalOutput

Example Response:

Subscribe to Resource Response 
{
  "path": "/controls/digitalOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource changes.

Example:

Unsubscribe to Resource 
unSub /controls/digitalOutput

Example Response:

Unsubscribe to Resource Response 
{
  "path": "/controls/digitalOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}
update

Change property for the service such as enable/disable service.

Example:

Update Resource Properties 
update /controls/digitalOutput {"enabled" : true}
update /controls/digialOutput {"enabled" : false}

Example Response:

Update Resource Property Response 
{
  "path": "/controls/digitalOutput",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Sent when the resource property is changed.

Example:

Notification Example 
Request: 
update /controls/digitalOutput {"enabled": true}

Notification:
{
  "eventType": "updated",
  "path": "/controls/digitalOutput",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/digitalOuput/metrics

Resource Type: (Streamable)

This control service metrics resource contains the following metric which is common to all control services. However, this service currently does not update the metric.

Metrics

Item

Type

Schema

Description

controlDrops

integer

0.3.x.x added this metric.

Number of dropped scan results.

Not updated by this service currently.Value always set to zero.

Methods

Method Description
read

Read the metrics available in the service.

Example:

Read Metrics 
read /controls/digitalOutput/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/digitalOutput/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/metrics"
      }
    },
    "controlDrops": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the service periodically.

Example:

Stream Metrics 
stream /controls/digitalOutput/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/digitalOutput/metrics",
  "payload": {
    "path": "/controls/digitalOutput/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/digitalOutput/metrics",
  "payload": {
    "controlDrops": 0
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/digitalOutput/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/digitalOutput/metrics",
  "payload": {
    "path": "/controls/digitalOutput/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/ availableDevices

Resource Type: (Standard)

This is a resource that list all the devices capable and available for digital output service.

Properties:

Item Type Schema Description
devices array readOnly A list of available devices.
devices/n/

object

readOnly An available device entry.
devices/n/deviceStatus enum readOnly

Status of the device.

Values are:

0 = connected on the system network.

-1 = disconnected from the system network. Could also be caused by the device being powered off or rebooted.

devices/n/engineId string readOnly The internal scan engine id of the scan engine to which the device belongs.
devices/n/serialNumber string readOnly A string that uniquely identifies the device in string format.

Methods

Method Description
read

Gets a list of devices that can be used for digital output service.

Example:

Read Available Devices 
read /controls/digitalOutput/availableDevices

Example Response:

Read Available Devices Response 
{
  "path": "/controls/digitalOutput/availableDevices",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/availableDevices"
      }
    },
    "devices": [
      {
        "deviceStatus": 0,
        "engineId": "LMILaserLineProfiler",
        "serialNumber": "39410"
      },
      {
        "deviceStatus": 0,
        "engineId": "LMILaserLineProfiler",
        "serialNumber": "39500"
      }
    ]
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/ devices

Resource Type: (Collection)

This is the resource that lists all the output devices that had already been selected for digital output service.

Properties:

Item Type Schema Description
maxDeviceCount integer

readOnly

minimum

The number of devices that can be selected for digital output service at the same time.

The minimum value is zero (0).

creationParams object readOnly Creation parameters, used to create a new selected device instance.
creationParams/engineId string
The new selected device's engine id . Note that user should use the 'engineId' from one of the device found in the 'availableDevice' resource.
creationParams/serialNumber string
The new selected device's serial number. Note that user should use the 'serialNumber' from one of the device found in the 'availableDevice' resource.

Methods

Method Description
read

Read the list of all selected devices for digital output service.

Example:

Read Devices 
read /controls/digitalOutput/devices

Example Response:

Read Devices Response 
{
  "path": "/controls/digitalOutput/devices",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices"
      }
    },
    "creationParams": {
      "engineId": "",
      "serialNumber": ""
    },
    "maxDeviceCount": 1
  },
  "status": 1,
  "type": "response"
}
create

Create a new instance of selected device and add it to the existing devices list.

User should use the correct properties described by the 'creationParams' in this resource.

Note that the maximum number of selectable devices is limited by 'maxDeviceCount'.

Example:

Create Device 
create /controls/digitalOutput/devices {"engineId":"LMILaserLineProfiler","serialNumber":"42074"}

Example Response:

Create Device Response 
{
  "path": "/controls/digitalOutput/devices",
  "payload": {
    "id": "device-0",
    "path": "/controls/digitalOutput/devices/device-0"
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)

Resource Type: (Collection Item)

Output device supports the following properties:

Properties:

Item Type Schema Description
deviceStatus enum readOnly

Status of the device.

Values are:

0 = connected on the system network.

-1 = disconnected from the system network. Could also be caused by the device being powered off or rebooted.

displayName culture-specific string readOnly User configurable display name of the selected device.
engineId string readOnly The internal scan engine id of the scan engine to which the device belongs.
id string readOnly The internal device identifier of the selected device within the collection.
serialNumber string readOnly A string that uniquely identifies the device in string format.

Methods

Method Description
read

Read the properties of a selected device, including any embedded items.

Example:

Read Device 
read /controls/digitalOutput/devices/device-0

Example Response:

Read Device Response 
{
  "path": "/controls/digitalOutput/devices/device-0",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0"
      }
    },
    "deviceStatus": 0,
    "displayName": "device-0",
    "engineId": "LMILaserLineProfiler",
    "id": "device-0",
    "serialNumber": "43883"
  },
  "status": 1,
  "type": "response"
}
delete

Delete an existing selected device from the current selected devices list.

Example:

Delete Device 
delete /controls/digitalOutput/devices/device-0

Example Response:

Delete Device Response 
{
  "path": "/controls/digitalOutput/devices/device-0",
  "payload": null,
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when a specific device resource changes.

To receive notifications from any device, the wildcard "*" must be used.

To receive notifications from a specific device, then the device id must be specified.

Example:

Subscribe to Any Device Resource 
sub /controls/digitalOutput/devices/*

Example Response:

Response to Subscribe to Any Device Resource 
{
  "path": "/controls/digitalOutput/devices/*",
  "payload": null,
  "status": 1,
  "type": "response"
}

Example:

Subscribe to Specific Device Resource 
sub /controls/digitalOutput/devices/device-4

Example Response:

Response to Subscribe to Specific Device Resource 
{
  "path": "/controls/digitalOutput/devices/device-4",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to resource to stop receiving notifications for a specific device resource change.

Example:

Unsubscribe to Any Device Resource 
unSub /controls/digitalOutput/devices/*

Example Response:

Response to Unsubscribe to Any Device Resource 
{
  "path": "/controls/digitalOutput/devices/*",
  "payload": null,
  "status": 1,
  "type": "response"
}

Example:

Unsubscribe to Specific Device Resource 
unSub /controls/digitalOutput/devices/device-4

Example Response:

Response to Unsubscribe to Specific Device Resource 
{
  "path": "/controls/digitalOutput/devices/device-4",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
created

Occurs whenever a new selected device has been created.

Example:

Resource Created Notification 
{
  "eventType": "created",
  "path": "/controls/digitalOutput/devices/device-0",
  "payload": null,
  "status": 1,
  "type": "notification"
}
 
deleted

Occurs whenever a selected device has been deleted.

Example:

Resource Deleted Notification 
{
 "eventType": "deleted",
 "path": "/controls/digitalOutput/devices/device-0",
 "payload": null,
 "status": 1,
 "type": "notification"
}
updated

Occurs when a specific device resource has changed, such as the device status.

Resource Updated Notification 
{
  "eventType": "updated",
  "path": "/controls/digitalOutput/devices/device-4",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/digitalOutput/devices/(deviceId)/ports

Resource Type: (Collection)

This resource describes the port collections for each of the device user has selected for digital output service.

Methods

Method Description
read

Read the list of ports as embedded items for the selected device.

Example:

Read Device Ports 
read /controls/digitalOutput/devices/device-0/ports

Example Response:

Read Device Ports Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-1"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports"
      }
    }
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)

Resource Type: (Collection Item)

Output device port supports the following properties:

Properties :

Item Type Schema Description
displayName culture-specific string readOnly Display name of the selected device's port.
id string readOnly The internal port identifier of the selected device port within the collection.
portNumber integer

readOnly,

minimum

The numerical port number.

The minimum value is zero (0).

parameters object
The parameters used to configure the digital output service.
parameters/assertMode enum

The assertion mode which is only used for measurement trigger event.

The overall decision is based on all the selected measurements' individual decisions.

0 - The result is true, if every measurement decision is true.

1 - The result is true, if any measurement decision is false.

2 - The result is always true, regardless of any decision .

parameters/delay number

minimum, maximum,

units

The amount of delay in either time or encoder domain to the pulsed signal.

The delay is used to schedule the digital output signal at a later time or encoder position, thus allowing the user to program an expected delay, such as pipe or processing delay.

This is a 64-bit floating point number.

Minimum value: 0.0 in units of microseconds or millimeters.

Maximum value: 300,000,000.0 in units of microseconds or millimeters.

The units in microseconds (\u00b5s) in time domain, or in millimeters (mm) in encoder domain.

parameters/delayDomain enum

The type of delay, when pulsed signal is scheduled. See above on how delay can be used.

0 - Delay is in time mode.

1 - Delay is in encoder mode.

parameters/inverted bool

Whether the output signal should be inverted in polarity .

False - Digital output voltage is HIGH when output signal is active, and voltage is LOW when output signal is inactive.

True - Digital output voltage is LOW when output signal is active, and voltage is HIGH when output signal is inactive.

parameters/pulseWidth integer

minimum, maximum

units

The amount of time a pulsed signal stay activated.

Minimum value is 10 microseconds.

Maximum value is 2,000,000 microseconds.

The unit is in microseconds (\u00b5s).

parameters/scheduled bool

Whether the pulsed signal is triggered immediately , or delayed for future.

False - The current output signal is immediately set for the corresponding digital output port.

True - The current output signal is postponed until the future scheduled time or encoder position to be set.

parameters/signalType enum

The type of output.

0 - The output is a pulsed waveform that has a pulse width specified by the parameters/pulseWidth parameter .

1 - The output is a continuous waveform that maintain the last state until next transition occurs.

parameters/triggerEvent enum

The different kind of trigger events that drive the digital output signals.

1 - The output is tracking all measurements decisions for each frame . Digital output signal depends on the parameters/assertMode setting.

2 - The output is triggered by a software command. This is used for the port trigger command described below.

3 - The output is tracking the current alignment state. Digital output signal is active if the sensor group is aligned.

4 - The output is triggered by each scanner exposure begin event. Digital output signal is activated at the beginning of the exposure.

5 - The output is triggered by each scanner exposure end event. Digital output signal is activated at the end of the exposure.

6 - The output is tracking the current part detection state in surface mode. Digital output signal is active when a part is being tracked.

7 - The output is tracking the current system state, whether it is scanning or not. Digital output is active if the system is scanning.

Methods

Method Description
read

Read the selected device port resource and all its embedded items.

Example:

Read Device Port 
read /controls/digitalOutput/devices/device-0/ports/port-0

Example Response:

Read Device Port Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports/port-0"
      }
    },
    "displayName": "Digital 1",
    "id": "port-0",
    "parameters": {
      "assertMode": 0,
      "delay": 100000.0,
      "delayDomain": 0,
      "inverted": false,
      "pulseWidth": 100,
      "scheduled": false,
      "signalType": 1,
      "triggerEvent": 1
    },
    "portNumber": 0
  },
  "status": 1,
  "type": "response"
}
update

Change property for the selected device and port.

Example:

Update Digital Output Protocol Device Port 
update /controls/digitalOutput/devices/device-0/ports/port-0  {"parameters": {"assertMode": 0,"delay": 100000.0,"delayDomain": 0,"inverted": false,"pulseWidth": 100,"scheduled": false,"signal": 1,"triggerEvent": 4}}

Example Response:

Update Digital Output Protocol Device Port Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications


Notification Description
updated

Sent when the selected device port property is changed.

Example:

Port Notification 
{
  "eventType": "updated",
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/commands/trigger

Resource Type: (Callable)

Output device port command to trigger activation of the digital output signal on the specified output port.

The parameters/triggerEvent must be set to be triggered by a software command (value of 2).

The command supports the following command arguments :

Command Arguments:

Item Type Schema Description
value bool

The digital output signal value.

Use of this argument is described below.

target number

The time position.

When in time domain, it is in units of microseconds.

When in encoder domain, it is in units of millimeters.

The behaviour of this command depends on the value of parameters/signalType.

SignalType Scanning Required? Value Argument Value Target Argument Value Notes
Continuous

No.

The sensor can be either scanning or not scanning.

true active signal

false inactive signal

Not required.

Value is ignored.

If "value" is set to "true", then the digital output active count is incremented each time this command is invoked successfully.

If "value" is set to "false", then the digital output inactive count is incremented each time this command is invoked successfully.

Pulse

Yes.

Scanning must be started before issuing the trigger command.

Must be set to "true".

Not required.

Value is ignored.

The digital output active count is incremented each time this command is invoked successfully.

If command is not successful, then the digital output drop count is incremented but not the digital output active count.

If "value" is set to "true" and sensor is not scanning , then no output signal is generated each time this command is invoked.

  • Also, the digital output drop count is incremented.

If "value" is set to "false", then no output signal is generated each time this command is invoked.

  • Also, the digital output inactive count is incremented.
Scheduled Pulse

Yes.

Scanning must be started before issuing the trigger command.

Must be set to "true"

Required.
If not provided, then the default value of 0 is used.

The digital output active count is incremented each time this command is invoked successfully.

If command is not successful, then both the digital output drop count and digital output active count. are incremented.

The actual time or position target in the future of the scheduled pulse is calculated as follows:

actual target = target argument value + parameters/delay value.

In the time domain, the actual target is relative to the c urrent value of the clock used to generate the time stamp for a scan data message. To see this current clock time, read the scanner metrics resource (for example, /scan/engines/LMILaserLineProfiler/scanners/(scannerId)/metrics) and look for "currentSyncTime".

In the encoder domain, the actual target is relative to the current encoder value. For example, read the scanner metrics resource (eg. /scan/engines/LMILaserLineProfiler/scanners/(scannerId)/metrics) and look for the "encoderValue".

The actual target value must be greater than the current "currentSyncTime" (in time domain) or "encoderValue" (in encoder domain), indicating the actual target is in the future.

If the actual target is in the past, the the trigger request fails.

Example if using the trigger command manually instead of programmatically

  • currentSyncTime is 28,809,655,175
  • parameters/delay is 100,000 microseconds.
  • target argument value can be set to a value of 28,809,655,175 - 100,000 = 28,808,655,175 or a larger value (eg. 29,000,000,000).
  • Note: because this is done manually, the "currentSyncTime" continues to advance while the manual steps are carried out, so choose a fairly large "target" value.

The digital output trigger command with scheduled pulse is best done programmatically, such as with a SDK program.

The program can fetch the current time ("currentSyncTime") or encoder position ("encoderValue") and use that as the target argument.

Then the parameters/delay value can be adjusted manually to give the desired delay.


If "value" is set to "true", sensor is scanning but the target value is too small (eg. the calculated expected time/position to output the signal is in the past), then no output signal is generated each time this command is invoked.

  • Also, the digital output drop count and active count are incremented.

If "value" is set to "true" and sensor is not scanning , then no output signal is generated each time this command is invoked.

  • Also, the digital output drop count and active count are incremented.

If "value" is set to "false", then no output signal is generated each time this command is invoked.

  • Also, the digital output inactive count is incremented.


Methods

Method Description
call

Performs the trigger command on the selected device port resource.

Example:

Trigger Command 
call /controls/digitalOutput/devices/device-0/ports/port-0/commands/trigger {"parameter":{"target":0,"value":true}}

Example Response:

Trigger Command Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/commands/trigger",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/metrics

Resource Type: (Streamable)

Output device port metrics support the following metrics :

Item Type Schema Description
dropCount integer
The number of digital output events that failed to be set at the digital output port .
highCount integer
The number of digital output events that sets the signal high.
lowCount integer
The number of digital output events that sets the signal low.

Methods

Method Description
read

Read the metrics available for the current selected device and port in the digital output service .

Example:

Read Metrics 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/metrics

Example Response:

Read Metrics Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics"
      }
    },
    "dropCount": 0,
    "highCount": 0,
    "lowCount": 0
  },
  "status": 1,
  "type": "response"
}
stream

Stream metrics from the selected device and port of the digital output service periodically.

Example:

Stream Metrics 
stream /controls/digitalOutput/devices/(deviceId)/ports/(portId)/metrics

Example Response:

Stream Metrics Response 
// Response to stream metrics request
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
  "payload": {
    "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

// Streamed metrics contents
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
  "payload": {
    "dropCount": 0,
    "highCount": 0,
    "lowCount": 0
  },
  "status": 1,
  "streamId": 0,
  "streamStatus": "streaming",
  "type": "stream"
}
cancelStream

Stop streaming metrics from the service.

Example:

Cancel Streaming of Metrics 
cancelStream /controls/digitalOutput/devices/(deviceId)/ports/(portId)/metrics

Example Response:

Cancel Stream Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
  "payload": {
    "path": "/controls/digitalOutput/devices/device-0/ports/port-0/metrics",
    "streamId": 0
  },
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies

Resource Type: (Non Standard)

This resource is a parent to register assembly resources which are used to hold a list of data source outputs to send to a control service client.

1.0.x.x added support for registerAssemblies resource.

Resource Type: (Collection)

Output port register assemblies supports one register assembly resource whose internal identifier is "registerAssembly-0".

Register Assembly Display Name Register Assembly Internal Identifier Resource Path
"Register Assembly 0" "register-Assembly-0" /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies

Methods

Method Description
read

Read this resource to find out what register assemblies are available for the resource.

Example:

Read Register Assembly 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications
None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0

Resource Type: (Observable)

This is a resource to specify information output to the control service client. The type of information and the information location in the output is maintained by this resource.

Properties

Item

Type

Schema

Description

attributes

object

readOnly

Attributes of the register assembly resource.

attributes/isGlobalAddressSpaceUsed

boolean

Indicates if each output entry occupies a range of addresses (output identifier) in the register assembly.

Value of true means each output entry/item occupies a range of addresses (output identifiers) in the register assembly, corresponding to the register count of the register block.

Value of false means each output entry/item takes up one output identifier value, regardless of the register count of the register block.

attributes/outputIdMax

integer

The maximum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMax to outputIdMax.

attributes/outputIdMin

integer

The minimum register address value of the service register assembly.

0.3.x.x changed name from registerAddressMin to outputIdMin.

blocks

array

Array of register blocks added to this register assembly. Each register block has its own set of properties.

blocks/n/

object

A register block entry.

blocks/n/dataSource

string

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks.

This field is not applicable to the other register blocks

blocks/n/displayName

string

Culture-specific string to describe the register block.
For measurement and stamp blocks this field is the register block name not the displayName of the dataSource field. This is for information only, do not use this field.

blocks/n/outputId

integer

Identifier of the output item.

Valid range is 0..2 16 -1.

The output identifier must not lie outside the range of values specified by attributes/outputIdMin and attributes/outputIdMax.

If attributes/isGlobalAddressSpaceUsed is true:

The identifier corresponds to the register address location in which the data for this block appears in the control services output.

The maximum blocks/n/outputId value must satisfy the following relationship to ensure all the register block's outputs do not go past the the last register address specified byattributes/outputIdMax:

blocks/n/outputId +supportedBlockTypes/n/registerCount - 1 <= attributes/outputIdMax

If attributes/isGlobalAddressSpaceUsed is false:

The maximum blocks/n/outputId value must satisfy the following relationship:

blocks/n/outputId <= attributes/outputIdMax

blocks/n/scannerId

string

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

readOnly

Unique internal identifier of the register block type (see Register Assembly Register Block Types ).

blocks/n/version

string

readOnly

1.2.x.x Register block version.

displayName

string

readOnly

Display name of the register assembly

id

string

readOnly

Register assembly internal identifier

version

string

readOnly

1.2.x.x Register assembly version.

supportedBlockTypes

array

readOnly

Array of register block types properties for block types that are supported by the control services register assembly.

supportedBlockTypes/n/

object

A register block type entry.

supportedBlockTypes/n/category

enum

Categorizes the purpose of a register block type.

Enumerated values are:

0 = Unknown purpose

1 = Used for receiving control input from client

2 = Used for sending control output to client

3 = Used for providing system state information to client

4 = Used for providing sensor group state information to client

5 = Used for providing stamp information to client

6 = Used for providing measurement value and/or decision information to client

supportedBlockTypes/n/displayName

string

Culture-specific string that can be presented to the user to describe the register block.

supportedBlockTypes/n/hasDataSource

boolean

Indicates if this register block type contains a data source or not.

Value is

  • true for stamp and measurement register blocks

  • false for the other register blocks.

supportedBlockTypes/n/instanceCount

integer

Number of instances of this register block type that has been added by user.

Must be:

  • greater than or equal tosupportedBlockTypes/n/minInstance and

  • less than or equal tosupportedBlockTypes/n/maxInstance.

supportedBlockTypes/n/maxInstanceCount

integer

Maximum number of instances of this register block type that this register assembly can have.

supportedBlockTypes/n/minInstanceCount

integer

Minimum number of instances of this register block type that this register assembly can have.

A value of 0 means this register block type is optional for this register assembly.

A value N greater than 0 means N instances are created automatically on start up.

supportedBlockTypes/n/registerCount

integer

This value is meaningful only for register assemblies where attributes/isGlobalAddressSpaceUsed is true.

It is the number of address locations in the output that this register block takes up.

This number is determined by what output information are available for a register block and is constant for that register block type.

supportedBlockTypes/n/type

string

Internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).
Used by client to refer to this register block type for operations on the register assembly.

This register assembly customizes the register assembly properties as follows:

Item Type Schema Description
attributes/isGlobalAddressSpaceUsed

boolean

readOnly

Value is set to false.

attributes/outputIdMax

integer readOnly

Value is set to 65534.

attributes/outputIdMin

integer readOnly Value is set to zero (0).
displayName string readOnly "Register Assembly 0"
id string readOnly "registerAssembly-0"

supportedBlockTypes/n/category

integer readOnly Categories 6 is supported.
supportedBlockTypes/n/maxInstanceCount integer readOnly Category 6 ("Measurement"): Value is set to 65534.
supportedBlockTypes/n/minInstanceCount integer readOnly Category 6 ("Measurement"): Value is set to 0.
supportedBlockTypes/n/type string readOnly

Supported register block type internal identifier:

Category 6: "Measurement"

Methods

Method Description
read

Read the register assembly resource. It returns the register blocks added to the register assembly and the list of supported register blocks.

The response also includes CALL command request resource paths to operate on this resource.

Example:

Read Register Assembly 
read /controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0

Example Response:

Read Register Assembly Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0"
      }
    },
    "attributes": {
      "isGlobalAddressSpaceUsed": false,
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "blocks": [
      {
        "dataSource": "tools:ProfilePosition-2:outputs:X",
        "displayName": "Profile Position 1 / X",
        "outputId": 2,
        "scannerId": "",
        "type": "Measurement",
        "version": "1.2"
      }
    ],
    "displayName": "Register Assembly 0",
    "id": "registerAssembly-0",
    "version": "1.2",
    "supportedBlockTypes": [
      {
        "category": 6,
        "displayName": "Measurement and Decision",
        "hasDataSource": true,
        "instanceCount": 0,
        "maxInstanceCount": 65534,
        "minInstanceCount": 0,
        "registerCount": 5,
        "type": "Measurement"
      }
    ]
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Example:

Subscribe Register Assembly 
sub /controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0

Example Response:

Subscribe Register Assembly Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}
unSub

Unsubscribe to stop receiving register assembly resource updates.

Example:

Unsubscribe Register Assembly 
unsub /controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0

Example Response:

Unsubscribe Register Assembly Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "response"
}

Notifications

Notification Description
updated

Occurs whenever the register assembly resource has changed.

Example:

Register Assembly Notification 
Client request:
call /controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands/add {"blocks":[{"type": "Measurement", "dataSource":"tools:ProfileInfo-0:outputs:MinZ"}]}

Notification:
{
  "eventType": "updated",
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0",
  "payload": null,
  "status": 1,
  "type": "notification"
}

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands

Resource Type: ( Standard , Observable )

A collection of commands for the control service's register assembly. These commands can be used to modify the register blocks inside the register assemblys array of register blocks called blocks. Depending on the characteristics of the supported block type, some commands may not be applicable.

For example, attempt to add a second instance of a supported block type that only allows one instance to be present is rejected.

Methods

Method Description
read

Returns a list of register assembly commands as embedded resources for the selected device and port.

Example:

Read Register Assembly Commands 
read /controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands

Example Response:

Read Register Assembly Commands Response 
{
  "path": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands",
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands/add"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands/remove"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands/compact"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands/update"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/device-0/ports/port-0/registerAssemblies/registerAssembly-0/commands"
      }
    }
  },
  "status": 1,
  "type": "response"
}
sub

Subscribe to resource to receive notifications when this resource changes.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

unSub

Unsubscribe to this resource.

Because this resource cannot be updated, subscribing/unsubscribing to this resource is not useful because no notifications are ever generated for this resource path.

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add

Resource Type: (CollectionItem , Callable)

Command to add one or more register blocks to the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/blocks

array<object>

An array of register block information describing the registers blocks that are to be added to the register Tassembly

The arguments to pass in for the CALL method are described below.

Call Command Arguments:

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

Value of true means the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

Value of false means overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

blocks

array

Array of register blocks to be added to the register assembly

blocks/n/

object

One entry of register block information.

blocks/n/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

blocks/n/displayName

string

Optional

Culture-specific string to describe the register block.This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

blocks/n/outputId

integer

Optional

Output identifier for this output item.

If not provided as an argument, then the register block is added after the last register block.

The valid range for the output id is0..2 16 -1. If the client enters an output id value that is greater than2 16 (65535), the output id will get truncated to a 16 bit value.

e.g. Client enters output id equal to 65537. 65537 is equal to 0x10001. However, the output id will be processed as 0x0001 which is equal to 1.

blocks/n/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

blocks/n/type

string

Mandatory

Unique internal id that uniquely identifies the register block type (see Register Assembly Register Block Types ).

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Add 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add

Example Response:

Read Register Assembly Command Add Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add"
      }
    },
    "id": "add",
    "parameters": {
      "autoShift": false,
      "blocks": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Add Register Block 
call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add {
    "blocks":[
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MinZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:MaxZ"},
        {"type":"Measurement","dataSource":"tools:ProfileInfo-0:outputs:PointCount"}]}

Example Response:

Add Register Block Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/add",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove

Resource Type: (CollectionItem , Callable)

Command to remove one or more register blocks from the register assembly.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/outputIdList

array<integer>

Array of one or more output identifiers to remove from the register assembly.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

outputIdList

array

Mandatory

Array of one or more output identifiers to remove from the register assembly.

outputIdList/n/

integer

One output identifier.

outputIdList/n/outputId

integer

The output id to remove from the register assembly.

At least one entry must be provided.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Remove 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove

Example Response:

Read Register Assembly Command Remove Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove"
      }
    },
    "id": "remove",
    "parameters": {
      "outputIdList": []
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Remove Register Block 
call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0}]}

call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove {"outputIdList":[{"outputId":0},{"outputId":100},{"outputId":200}]}

Example Response:

Remove Register Block Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/remove",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact

Resource Type: (CollectionItem , Callable)

Command to compact (remove gaps from) the register block output identifiers within the register assembly to eliminate unused space between register blocks.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/startingOutputId

integer

Output identifier to assign to the first register block during the compacting operation.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

startingOutputId

integer

Optional

Output identifier to assign to the first register block during the compacting operation.

Ifattributes/isGlobalAddressSpaceUsed is true, the minimum and maximum values is limited by the register assembly's minimum and maximum address value.

The maximum value allowed for the compact command is likely to be less than the register assembly's maximum address value to allow a register block to fit within the register assembly's address range.

If no startingAddress is provided, then the default value is the register assembly's attribute outputIdMin value.

Ifattributes/isGlobalAddressSpaceUsed is false, and if not provided as an argument, the value of zero (0) is used as the starting output identifier value.

If the client enters an output id value that is greater than2 16 -1 (65535), which is the largest value that 16-bits can represent, the output id will get truncated to a 16 bit value.

e.g. Client enters anoutput id equal to 65537. 65537 is equal to 0x10001. However, the output id will be truncated by the REST API and processed as 0x0001 which is equal to 1.

0.3.x.x added this field which was originally called startingAddress.

0.3.x.x renamed fromstartingAddress to startingOutputId.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Compact 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact

Example Response:

Read Register Assembly Command Compact Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact"
      }
    },
    "id": "compact",
    "parameters": {
      "startingOutputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Compact Register Block 
call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact

call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact {"startingOutputId":100}

Example Response:

Compact Register Block Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and after Compacting:

Compact Register Block Before And After 
Request:
   call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/compact

Notifications

None generated for this resource.

/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update

Resource Type: (CollectionItem , Callable)

Command to update (modify) the register block characteristics.

Reading this resource returns information about the command parameters for this command operation.

Properties

Item

Type

Schema

Description

id

string

The identifier of this register assembly command.

parameters

object

Describes the parameters that theregister assembly command can take.

parameters/autoShift

boolean

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected. This is the default value.

parameters/outputId

integer

The output id of the register block to update.

parameters/newParams

object

Parameters used to update the register block specified by the output identifier.

parameters/newParams/dataSource

string

New data source identifier for the register block.

parameters/newParams/displayName

string

New display name for the register block.

parameters/newParams/outputId

integer

New output identifier value to assign to the register block.

parameters/newParams/scannerId

string

New scanner identifier for the register block.

The arguments to pass in for the CALL method are described below.

Call Command Arguments

Item

Type

Mandatory or Optional Argument

Description

autoShift

boolean

Optional

Specifies whether a new entry can be inserted in between existing entries, if the the new entry overlaps the existing entries.

True: the overlapping entries that follow the new entry are automatically shifted towards higher output identifier values.

False: overlap not allowed. Request is rejected if overlap is detected.

If not provided as an argument, the default value is "false".

newParams

object

The information to apply to the specified register block.

newParams/dataSource

string

Mandatory for Measurement or Stamp register blocks

Not applicable for other register blocks.

The data source identifier associated with the register block.

This is applicable only to Measurement or Stamp register blocks. This field is not applicable to the other register blocks.

newParams/displayName

string

Optional

The updated culture-specific string for the register block display name.

This is the name that a client should display to the user.

If not provided as an argument, the display name is set to the display name of the register block.

newParams/outputId

integer

Optional

The new output identifier to assign to the register block.

newParams/scannerId

string

Currently not supported

Name of sensor group.

Currently not supported and is always blank (empty string).

outputId

integer

Mandatory

The output identifier of the register block to which the new parameters are applied.

Methods

Method Description
read

Returns the command parameters used by the command.

Example:

Read Register Assembly Command Update 
read /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update

Example Response:

Read Register Assembly Command Update Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update"
      }
    },
    "id": "update",
    "parameters": {
      "autoShift": false,
      "newParams": {
        "dataSource": "",
        "displayName": "",
        "outputId": null
      },
      "outputId": null
    }
  },
  "status": 1,
  "type": "response"
}
call

Perform the command.

This could potentially generate an "updated" notification for the register assembly resource.

Example:

Update Register Block 
// This update request doesn't change anything but is still a valid request.
call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update {"outputId" : 153, "newParams" : {}}

call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Example Response:

Update Register Block Response 
{
  "path": "/controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update",
  "payload": {},
  "status": 1,
  "type": "response"
}

Example of Register Block List Before and After Updating:

Update Register Block Before And After 
Request:
   call /controls/digitalOutput/devices/(deviceId)/ports/(portId)/registerAssemblies/registerAssembly-0/commands/update {"outputId":153, "newParams":{"displayName":"MyPointCount", "outputId" : 200}}

Before update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "Profile Info 1 / Point Count",
        "outputId": 153,
        "scannerId": "",
        "type": "Measurement"
      }
    ],

After update:
    "blocks": [
...
      {
        "dataSource": "tools:ProfileInfo-0:outputs:MaxZ",
        "displayName": "Profile Info 1 / Max Z",
        "outputId": 150,
        "scannerId": "",
        "type": "Measurement"
      },
      {
        "dataSource": "tools:ProfileInfo-0:outputs:PointCount",
        "displayName": "MyPointCount",         
        "outputId": 200,                     
        "scannerId": "",
        "type": "Measurement"
      }
    ],

Notifications

None generated for this resource.


GoPxL: Metrics Resources

System Metrics

/system/metrics

For system metrics, see Resource Reference .

Scanner Metrics

/scan/engines/(engineId)/scanners/(scannerId)/metrics

For scanner metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/metrics .

/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/metrics

For sensor metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/metrics .

Tool Metrics

/tools/(toolId)/metrics

For tool metrics, see Tool Resources#/tools/(toolId)/metrics .

GoPxL: Routine Resources

/routineTypes

Resource Type: N/A

This resource lists the routine types available in the system. Routine types are the types of routines that can be created in the system.

Properties

Item Type Schema Description
description string readOnly Describes the function and purpose of the routine type.
displayName string readOnly

Culture-specific routine type name.

For example: "Alignment".

helpHtml string readOnly Html help string for this routine type. If both helpURL and helpHtml are specified, then helpURL will take precedence.
helpUrl string readOnly Html help URL string for this routine type. If both helpURL and helpHtml are specified, then helpURL will take precedence.
type string readOnly

The routine type name. This is the name used to create an instance of the routine.

For example: "G2Alignment".

Methods

Method Description
read

Reads the list of routine types available. The routine type is used to create an instance of a routine.

Example:

Read Resource 
read /routineTypes

Example Response:

Read Resource Response 
{
  "payload": {
    "routineTypes": [
      {
        "description": "Performs an alignment.",
        "displayName": "Alignment",
        "helpHtml": "",
        "helpUrl": "",
        "type": "G2Alignment"
      },
      {
        "description": "Performs an alignment.",
        "displayName": "Alignment",
        "helpHtml": "",
        "helpUrl": "",
        "type": "G3Alignment"
      },
      {
        "description": "Performs an alignment.",
        "displayName": "Alignment",
        "helpHtml": "",
        "helpUrl": "",
        "type": "G5Alignment"
      },
    ],
    "_links": {
      "self": {
        "href": "/routineTypes"
      }
    }
  },
  "path": "/routineTypes",
  "type": "response",
  "status": 1
}

/routines

Resource Type: (Collection - Unordered)

A collection of routines available in the system.

Create Method Arguments

Item Type Mandatory or Optional Description
type string Mandatory

The name of the routine type to create.

A list of routine types that can be created is available by reading the /routineTypes resource

Methods

Method Description
read

Reads a list of routines that have been created for use.

A routine may have to be created explicitly by the client before it is available for use.
The resource path to the routines are listed in the "_embedded" "item" list. The resource path is the path generated when the routine is successfully created using the CREATE method.

Example:

Read Resource 
read /routines

Example Response:

Read Resource Response 
{
  "payload": {
    "_links": {
      "self": {
        "href": "/routines"
      }
    },
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/routines/G2Alignment-0"   <<<<< resource path of a routine.
          }
        }
      }
    ]
  }
}
create

Creates a routine instance.

Upon successful routine creation, a resource path to the newly created routed is created. The resource path is returned in the "path" field of "payload" in the response message.

Example:

Create Resource 
create /routines {"type": "G2Alignment"}

Example Response:

Create Resource Response 
{
  "path": "/routines",
  "payload": {
    "id": "G2Alignment-0",               <<<< the "routineId" for the /routines/(routineId) resource path.
    "path": "/routines/G2Alignment-0"    <<<< resource path of the newly created routine.
  },
  "status": 1,
  "type": "response"
}

Notifications

Event Type Description
updated

This resource notification is generated when all the routines are deleted at once using the wildcard (*) in the delete command (eg. delete /routines/*)

Example:

Notification Example 
{
  "eventType": "updated",
  "path": "/routines",
  "payload": {},
  "status": 1,
  "type": "notification"
}

/routines/(routineId)

Resource Type: (CollectionItem)

Reads a specific routine resource. The "routineId", which identifies a specific routine resource, is auto generated when the routine is created. It can be obtained by reading the /routines resource, or checking the response from the routine create method.

Properties

Each routine has a common set of properties plus routine-specific properties.

Routine specific properties are the:

  • "navActions",
  • "parameters" and
  • "results"

property fields. Please refer to the documentation of specific routines for details of these routine-specific properties.

NOTE: the schema for the routine-specific properties may also differ between routines.

Item

Type

Schema

Description

currentProgress

integer

readOnly, minimum

Progress of the run task currently executing in a routine step. Value can range from 0 - 100 in units of percent.

currentStep

integer

readOnly, minumum

Value indicating current stage of the alignment process. Can range from 0 to 'totalSteps' parameter.

currentStepInfo

string

readOnly

Description of the step the routine is currently in.

description

string

readOnly

Culture-specific string which is a description of the routine.

displayName

string

readOnly

Display name of the routine which is a culture-specific string.

displayTitle

string

readOnly

Display title of the routine which is a culture-specific string. Used as the title of the routine window.

helpHtml

string

readOnly

Help info (in HTML) about the routine. This could vary from step to step in the routine.

helpUrl

string

readOnly

Help info URL about the routine.

id

string

readOnly

Id of the instance of the routine.

navActions

array

readOnly

An array of custom navigation actions for the routine.

Actual set of navigation actions, if any, is dependent on the specific routine type.

If no navActions are defined by the routine, then this field may be absent.

Added in: 1.2.x.x

navActions/n

Anchor

An action used for custom navigation.

The action will always have an "anchorType" (see the Anchor data type) property of "Callable".

parameters

object

Modifiable parameters of the routine.

Actual set of parameters, if any, is dependent on the specific routine type.

results

object

readOnly

Results returned after performing the routine.

Actual results information, if any, is dependent on the specific routine type.

state

integer

readOnly, enum

Current state of the routine. The values are have the following meaning:

0 = READY << Routine has been created but hasnt started yet.
1 = RUNNING << Routine is running.
2 = WAITING << Routine is waiting for user input.
3 = DONE << Routine has completed successfully.
4 = ABORTED << Routine has been aborted by the user.
5 = FAILED << Routine processing failed.

stateDetails

string

readOnly

Description details of the current state. Usually used to provide info for FAILED state but can be used for other states.

totalSteps

integer

readOnly, minimum

Total steps in the routine.

type

string

readOnly

Type of the routine.

Update Arguments

Item Type Mandatory or Optional Description
parameters object Mandatory One or more of the routine's property parameters to configure.

Methods

Method Description
read

Read a specific routine.

Example:

Read Resource 
read /routines/G2Alignment-0

Example Response:

Read Resource Response 
In this example, there is no "navActions" property defined and this property is absent from the payload.

{
  "payload": {
    "currentProgress": 0,
    "currentStep": 2,
    "currentStepInfo": "<b>Please select the desired alignment target and configure it</b><br>Once complete, click <b>Next</b> to proceed with alignment",
    "description": "Performs an alignment.",
    "displayName": "Alignment",
    "displayTitle": "Alignment",
    "helpHtml": "<p><b>Please select the desired alignment target and configure it</b><br>Once complete, click <b>Next</b> to proceed with alignment</p><p></p>",
    "helpUrl": "",
    "id": "G2Alignment-0",
    "state": 2,
    "stateDetails": "",
    "totalSteps": null,
    "type": "G2Alignment",
    "parameters": {
       ... routine specific parameters
    }
    "results": {
       ... routine specific results
    },
    "_links": {
      "self": {
        "href": "/routines/G2Alignment-0"
      }
    }
  },
  "path": "/routines/G2Alignment-0",
  "type": "response",
  "status": 1
}
update

Update a specific routine's parameters.

Examples:

Update routine's delay parameter:

Update Resource 
update /routines/G2Alignment-0 {"parameters": {"StationaryTarget": 1}}

Update multiple routine properties at once:

Update Resource 
update /routines/G2Alignment-0 {"parameters": {"StationaryParams" : {"BarHeight" : 10, "HoleDiameter": 5}}}

Example Response:

Update Resource Response 
{
  "path": "/routines/G2Alignment-0",
  "payload": {},
  "status": 1,
  "type": "response"
}
delete

Delete a routine from the system, typically when the routine is completed or aborted.

Examples:

Delete a single routine:

Delete Resource 
delete /routines/G2Alignment-0

A special wildcard formapplies to this delete method.

The path of this routines command can be wildcarded to delete all routines:

Delete Resource 
delete /routines/*

Example Response:

Delete Resource Response 
Deleting specific routine instance:
{
  "path": "/routines/G2Alignment-0",
  "payload": {},
  "status": 1,
  "type": "response"
}

Deleting all routines using the wildcarded delete:
{
  "path": "/routines/*",
  "payload": {},
  "status": 1,
  "type": "response"
}

Notifications

Event Type Description
created

This resource notification is generated when when a new routine is added. The path indicates the new routine id.

Example:

Example Create Notification 
{
  "eventType": "created",
  "path": "/routines/G2Alignment-0",
  "payload": {},
  "status": 1,
  "type": "notification"
}
updated

This resource notification is generated when a routine is created or deleted using the wildcard delete.

Example:

Example Updated Notfication 
{
  "eventType": "updated",
  "path": "/routines/G2Alignment-0",
  "payload": {},
  "status": 1,
  "type": "notification"
}
deleted

This notification is generated when a routine is deleted explicitly (without using the wildcard delete). The path indicates the routine id that was deleted.

Example:

Example Delete Notification 
{
  "eventType": "deleted",
  "path": "/routines/G2Alignment-0",
  "payload": {},
  "status": 1,
  "type": "notification"
}

/routines/(routineId)/actions

Please refer to the specific routine "routineId" documentation to find what actions are supported by the "routineId".

For more information about actions, and how they differentiate from commands, see Documentation Conventions#ActionAction

/routines/(routineId)/actions/(actionId)

Please refer to the specific routine "routineId" documentation to find the details of the action "actionId" supported by "routineId".

For more information about actions, and how they differentiate from commands, see Documentation Conventions#ActionAction

/routines/(routineId)/commands/continue

Resource Type: ( Callable )

Command to continue with the actual processing of routine after a routine paused itself. A routine may pause itself if it requires user action, such as to set up routine configuration parameter values.

All routines that can pause shall support this command.

Call Command Arguments

No arguments required.

Methods

Method Description
call

Perform the command.

Example:

Call Resource 
call /routines/G2Alignment-0/commands/continue

Example Response:

Call Resource Response 
{
  "path": "/routines/G2Alignment-0/commands/continue",
  "payload": {},
  "status": 1,
  "type": "response"
}

/routines/(routineId)/commands/abort

Resource Type: ( Callable )

Command to abort the processing of the routine. All routines shall support this command.

Call Command Arguments

No arguments required.

Methods

Method Description
call

Perform the command.

Example:

Call Resource 
call /routines/G2Alignment-0/commands/abort

Example Response:

Call Resource Response 
{
  "path": "/routines/G2Alignment-0/commands/abort",
  "payload": {},
  "status": 1,
  "type": "response"
}




GoPxL: Standard Routine Resources

Alignment Routine

Resource Type: N /A

Contains information on what an alignment routine contains and how it is designed to function.

Alignment can also be performed by calling the relevant command on the scanner .

Each type of sensor has a unique alignment routine.

  • Laser line profilers (G2 & G6) use G2Alignment.
  • Snapshot sensors (G3) use G3Alignment.
  • Confocal sensors (G4 & G5) use G5Alignment.

Examples in this page will reference G2Alignment, but the other two are very similar.


All parameters listed are read only except where specified as "modifiable".

Routine parameters Type Schema Description
currentProgress integer readOnly Progress of the run task currently executing in a routine step. Value can range from 0 - 100 in units of percent.
currentStep integer readOnly Value indicating current stage of the alignment process. Can range from 0 to 'totalSteps' parameter.
currentStepInfo string readOnly Description of the step the routine is currently in.
description culture-specific string readOnly

Description of this routine.

displayName culture-specific string readOnly Display name of the routine.
helpHtml string readOnly General info (in html) for this routine. Can be used anytime during the routine to convey current information about the routine.
id string readOnly Id of the instance of the routine.
parameters object
Modifiable parameters values for alignment routine - see Alignment Routine Parameters below
results object readOnly

Results after performing the alignment. Empty{} if no results or not yet available, otherwise alignment transformation values for each sensor:

xOffset
yOffset
zOffset
xAngle
yAngle
zAngle

state integer readOnly, enum Current state of the routine: 0 = READY, 1 = RUNNING, 2 = WAITING, 3 = DONE, 4 = ABORTED, 5 = FAILED.
stateDetails string readOnly Description details of the current state. Usually used to provide info for FAILED state but can be used for other states.
totalSteps integer readOnly

Total steps in the alignment process.

type string readOnly Type of routine.
parameters object
Modifiable parameters values for alignment routine
parameters/motionType object
Contains alignmentType (see below) and updateEncoderSpeedCalibration parameters.
parameters/formatType object
Contains the parameters for all alignment targets and their alignment target parameters - see below.
parameters/processingDelay integer

Time to delay while simulating aligning process in microseconds. CurrentProgress will range from 0 - 100% in 20% increments after each delay.

parameters/scannerEngineId string
Id of the scanner engine to use for alignment. If set to non-empty string, will bypass the first step of the alignment routine prompting for engine and scanner id.
parameters/scannerId string
Id of scanner instance to use for alignment

Alignment Parameters

All motionType and formatType parameter values are assumed to be of type integer unless specified in brackets, e.g. (number). Enumerations have their actual integer value shown in brackets, e.g (0).

Methods

Method Description
create

Create an alignment routine. The routine is ready to be configured with the scan engine and scanner ids to use for alignment.

Example: 

create /routines { "type" : "G2Alignment" }
update

Update the alignment routine with the alignment type (stationary or moving) and the stationary/moving target.
There will be additional parameters to modify depending on the alignment type & target.

Example: 

update /routines/G2Alignment-0 { "parameters" : { "AlignmentType" : 1, "MovingTarget" : 1 }}
call /routines/*id*/commands/continue

Proceed with the alignment once the routine target(s) has been configured.

Example: 

call /routines/G2Alignment-0/commands/continue
call /routines/*id*/commands/abort

Abort the alignment process.

Example: 

call /routines/Alignment-0/commands/abort
delete

Delete the alignment routine. This will automatically abort if the routine is running.

Example: 

delete /routines/Alignment-0

Notifications

EventType Description
create

When the alignment routine is created.

Example: 

eventType: created, path: /routines/Alignment-0
delete

When the alignment routine is deleted.

Example: 

eventType: deleted, path: /routines/Alignment-0
update

When the alignment routine parameters, status, currentStep or result has changed.

Example: 

eventType: updated, path: /routines/Alignment-0

Example Execution of Alignment Routine

Sequence REST Protocol Commands/Responses Description
  1. Create an instance of the alignment routine 
create /routines { "type" : "G2Alignment" }

state = WAITING (2)

currentStep = 2

currrentProgress = 0

result ={}

2. Configure the routine's parameters for alignment

(e.g. set alignment type to moving alignment) 

update /routines/G2Alignment-0 { "parameters" : { "AlignmentType" : 1 }}

state = WAITING (2)

currentStep = 2

currentProgress = 0

result ={}

3. Configure moving alignment target to moving disk 
update /routines/G2Alignment-0 { "parameters" : { "MovingTarget" : 1 }}

state = WAITING (2)

currentStep = 2

currentProgress = 0

result ={}

4. Configure moving disk parameters 
update /routines/G2Alignment-0 { "parameters" : { "MovingDiskParams" : 
   { "PresetDisk" : 2, "DiskThickness" : 15.0, "DiskDiameter" : 40.0 }}}

state = WAITING (2)

currentStep = 2

currentProgress = 0

result ={}

5. Start alignment process 
call /routines/G2Alignment-0/commands/continue

state = RUNNING (1)

currentStep = 3

currentProgress = 0

result ={}

6. Wait for progress notification events 
"updated", "path" : "/routines/G2Alignment-0" repeatedly every few seconds

state = RUNNING (1)

currentStep = 3

currentProgress = 0 - 100 in 5 steps of 20%

result ={}

7. Wait for completion of alignment process 
"updated", "path" : "/routines/G2Alignment-0"

state = DONE (3)

currentStep = 4

currentProgress = 100

result ={status, xOffset, yOffset, zOffset, xAngle, yAngle, zAngle}

8. Remove routine 
delete /routines/G2Alignment-0




GoPxL: REST API User Guide

GoPxL: Resource Design and Request Methods

This page defines the general design of resources in the abstract. The concrete design that map sensor functionality is defined in Resource Reference

The examples shown on this page are not reflective of actual implementation and should not be treated as such.

Some of this section is borrowed from the Google API guidelines , but adapted for our own specific use

Overview

The API is organized into a hierarchy of "resources", identified by URIs . A resource has content, and supports a number of methods that can be invoked on it.

Some resources embed child resources, and these parent resources fall into two categories: collection and map (discussed below). A collection contains an homogenous and ordered set of children in the form of a list, whereas a map contains a non-homogenous and unordered set of children. In both cases, children are identified by a string "ID". For simplicity, all resources are considered to be a Map unless explicitly stated to be a collection (sometimes, the term "simple resource" is used to emphasize that a resource is not a collection). A parent resource may have other parent resources as its children.

Examples of resources include:

  • /system, representing the system settings and states
  • /scanners, a collection resource representing the scanners
  • /tools, a collection resource representing the set of tools

The hierarchical structure of resources is discoverable at runtime, as this information is made available in the resource JSON content. This is discussed in further detail below.

Resource Naming

ID

A resource ID is any non-empty string which identifies a resource within its parent , which could be a simple resource or a collection resource.A resource ID should always be a noun, or otherwise an arbitrary sequence of characters. Collection resources should always be in plural. Exceptions are command resources, which must always be verbs.

For a resource under a simple resource, the resource ID is often hardcoded and have no special meaning. e.g. for an URI such as "/api/system", "system" is an ID in the context of "/api". It is simply hardcoded and documented as as part of the protocol reference. For a resource under a collection resource, the resource ID is dynamically generated or user-defined. e.g. a job resource might have the path "/api/jobs/opposite-volume-checker", where "opposite-volume-checker" is the user given ID.

IDs that begin with "$", e.g. "$schema", have special meaning in the system, and should not be used outside the designated use case.

In general, ID's should be treated as opaque strings. They should not be parsed by a client or interpreted in any way other than as a source of identification within the parent scope. ID's are not guaranteed to be globally unique (in the few cases that they are, this will be documented on the resource). Nor are they guaranteed to be predictable.

In general, a client should never parse any ID.

URI

A resource relative URI (or just URI within the context of this document) is a complete and unique identifier to a given resource within a given API service. It consists of a given resource'sID, plus the ID's of any parent resources all the way up to the root of the API.The term "relative" is important, as a full URI consists of a scheme and a DNS-compatible service name (including possible API version numbers). Since our API is currently not an HTTP REST API, and since there is no scheme or service name which applies, there is no way to refer to resources with a full URI. Hence, we will use the term "URI" to refer to "Relative URI" from here on.

For example, consider the Scanner and Sensors example above: 

#Here we have the URI to a "sensor" resource
/scanners/A/sensors/0

#This consists of the following:
#    "/scanners/A/sensors/0": this is the resource URI
#    "scanner": this is the resource ID 
#    "A": this is the collection ID for resource "scanner".
#    "sensors": this is the resource ID 
#    "0": this is the collection ID for the resource "sensors".

Content and JSON type

All resources have content that can be read, usually in the form of a JSON/MessagePack object. For example, a "scanner" resource contains a set of properties representing its settings. Note that a resource may contain a mixture of settings (e.g. exposure) and read-only values (e.g. current run state).

A "property" in the context of a resource refers to the properties in a JSON object. Property names must not start with "_", which is reserved for metadata that have special meaning at the system level. For example, schema is stored on the "_schema" property, and " _embedded " and "_links" are reserved properties as part of HAL (Hypertext Application Language), discussed below. Other metadata properties are described in their respective sections. Metadata are always read-only.

Relationships, Hierarchy, and Discoverability

Resource relationships generally fall into two categories:

  1. Embedded: this is where one resource contains another. This could be in the form of a collection (eg the relationship between "/tools" and its child "/tools/toolId") or in the form of a map ( eg the relationship between the "/scan" resource and its child "/scan/visibleSensors")
  2. Link: this is where one resource is somehowrelated to another. As an example, the relationship between "scanners/scanner-0/" and its actions "scanners/scanner-0/actions/upgrade"

While technically a relationship could be both a Link and an Embedded, within GoPxL API this never occurs.

Note that sometimes a resource relationships may indirectly fall into both categories. For example: 

ResourceA
	link[ResourceC]
	embedded[ResourceB]

ResourceB
	link[]
	embedded[ResourceC]

ResourceC
	link[]
	embedded[]

In this case, ResourceA islinkedto a ResourceC, but ResourceB embeds ResouuceC. ResourceC is both indirectly embedded into ResourceA as a grand-child and directly linked to it. This is considered acceptable

Circular relationships are not allowed (either directly or indirectly).

HAL (Hypertext Application Language)

GoPxL API resource design provides mechanisms for discovering both Embeds and Links, as well as differentiation between the types of each. It does so by implementing the JSON Hypertext Application Language .

Here is an example of a resource demonstrating the various forms of relationships. 

//Sample response when requesting a non-collection resource. _schema and data removed for brevity
{
    "_embedded": { 
      "go:content": [
        { 
            //This object represents an actual resource which is embedded into its parent.
            //In this example, the embedded resource has not been expanded with "expandLevel"
            "_links": {
            "self": {
              "href": "/api/resource/content"
            }
          }
        }
      ]
    },
    "_links": {
      "go:action": [
        {
          "href": "/api/resource/action/someAction"
        }
      ],
      "self": {
        "href": "/api/resource"
      }
    }

	//_schema and data removed
}

//Sample response when requesting a collection resource. _schema and data removed for brevity
{
    "_embedded": {
      "item": [
        //This is an array of objects representing a collection of actual resources which are embedded into its parent.
        //In this example, the embedded resources have not been expanded with "expandLevel"
        {
          "_links": {
            "self": {
              "href": "/api/collResource/child1"
            }
          }
        },{
          "_links": {
            "self": {
              "href": "/api/collResource/child2"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/collResource"
      }
    }

	//_schema and data removed
}

Embedded resources (ie those within the "_embedded" property) normally only show their minimal HAL metadata - they have a "_links" property their URI in "self" as required by JSON HAL specification. However, embedded resources can be expanded using the optional "expandLevel" argument as part of the "read" method. Resource expansion is discussed below later in this document.

Link Relation Types

While the aim of this section is not to repeat the details of JSON HAL standard, it is nevertheless worthwhile highlighting a few key aspects of how GoPxL API uses HAL. As part of HAL standard, the values for both "_links" and "_embedded" are always objects whose property names are link relation types (as defined by [RFC5988] ). The IETF maintains a registry of all accepted and standardized relation types here , however GoPxL API standardizes on just a few link relation types and sets guidelines on how plugins within GoPxL can expand on these further.

Not all Link Relation types listed below are standard. GoPxL API has defined a few of its own for its own purposes.

self

This is a standard link relation type.

It is required by HAL standard that every resource has a _link to itself 

"_links": {
  "self": {
    "href": "/api/collResource"
  }
}

item

This is a standard link relation type.

While not a link relation type included in the initial HAL specification, the "item" relation type was added later as part of RFC6573 . Quoting from RFC6573

When included in a resource that represents a collection, the 'item' link relation identifies a target resource that represents a member of that collection.

For example, if a resource represents a catalog of products, that same representation may include one or more links to resources that represent members of that catalog.

With GoPxL API, the "item" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": {
  "item": [
    //This is an array of objects representing a collection of actual resources which are embedded into its parent.
    //In this example, the embedded resources have not been expanded with "expandLevel"
    {
      "_links": {
        "self": {
          "href": "/api/collResource/child1"
        }
      }
    },{
      "_links": {
        "self": {
          "href": "/api/collResource/child2"
        }
      }
    }
  ]
},

go:action

This is a non-standard link relation type.

Represents a related resource which can be invoked with the "call" method below. When this resource is "called", it will affect the subject resource (ie the one which contains this Link Relation).

Actions are always associated to a subject JSON document as "_links". 

"_links": {
  "go:action": [
    {
      "href": "/api/resource/action/someAction"
    }
  ],
  "self": {
    "href": "/api/collResource/child2"
  }
}

go:command

This is a non-standard link relation type.

Representation and usage is similar to go:action.

Commands represent actions that are always available for this type of resource and do not vary with different instances or types of the resource, whereas supported actions may vary with different instances or types of the resource. 

"_links": {
  "go:command": [
    {
      "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add"
    },
    {
      "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove"
    },
    {
      "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact"
    },
    {
      "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/update"
    }
  ],
...
}

go:content

This is a non-standard link relation type.

Represents a related resource which is contained by the subject/parent.

With GoPxL API, the "go:content" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": { 
  "go:content": [
    { 
      "_links": {
        "self": {
          "href": "/api/resource/content"
        }
      }
    }
  ]
}

go:output

This is a non-standard link relation type.

An extension of "go:content". Represents a related resource which is an output of the subject/parent.

With GoPxL API, the "go:output" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": { 
  "go:output": [
    { 
      "_links": {
        "self": {
          "href": "/api/resource/content"
        }
      }
    }
  ]
}

go:sensor

This is a non-standard link relation type.

An extension of "go:content". Represents a related resource which is a sensor of the subject/parent.

With GoPxL API, the "go:sensor" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": { 
  "go:sensor": [
    { 
      "_links": {
        "self": {
          "href": "/api/resource/content"
        }
      }
    }
  ]
}

go:datasources

This is a non-standard link relation type.

Represents a resource which contains a map of scanner data sources for which the parent resource will receive. Currently only used by Gocator Data Protocol and HMI Protocol.

With GoPxL API, the "go:datasources" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": {
  "go:datasources": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs"
      }
    }
  }
},

go:registerAssembly

This is a non-standard link relation type.

Represents a resource which contains a map of scanner data sources for which the parent resource will receive. The map uses a register assembly object. Currently used by Modbus, Ethernet/IP and Profinet services.

With GoPxL API, the "go:registerAssembly" relation type is almost exclusively used within "_embedded", which means the content represents "Embedded Resources" and can be expanded via resource expansion. 

"_embedded": {
  "go:registerAssembly": [
    {
      "_links": {
        "self": {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0"
        }
      }
    }
  ]
},

go:***

This is a non-standard link relation type.

Additional GoPxL-API-specific and non-standardized link relations will always adhere to the format of being prefixed with "go:"

Schemas

Any resource that has JSON content usually has a corresponding schema, located at a related path. For example:

  • /tools/ProfileInfo-1234 is the resource
  • /tools/ProfileInfo-1234/#/_schema is the schema for the resource (using JSON Pointer syntax to refer to the specific property on the body the resource)

Schema is stored on the reserved "_schema' property, but only when requested. See the Read section below for more details on how to request schema, or not.

The format of the schema is documented on Schema and Data Types .

It should be noted that a schema does not stand on its own, especially when used with collections. It must always used in conjunction with real data. For example, if the data contains an array of unique objects, the schema does not have the information necessary to identify the data: 

//Sample response when requesting a resource. _links and _embedded removed for brevity
{
    //_links and _embedded removed

    // Schema. Starts at the document root which is always an object
    "_schema": {
        "type": "object",
        "properties": {
            "objects": {
                "type": "array",
                "items": [
                    {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "readOnly": true
                            }
                        }
                    },{
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "readOnly": true
                            }
                        }
                    }
                ]
            }
        }
    }

    // Data
    "objects": [
        {
            "id": "A"
        },{
            "id": "B"
        }
    ],
}

Methods

Create

Unlike with Classic (where config state was directly modified by the client), in GoPxL new objects in a collection must always be created using the Create method. This alleviates the client from having to construct the model of a new object. It also ensures the server is explicitly notified for all new objects. The server returns an identifier for the newly created object.

Examples: 

CREATE: config/tools, {"type": "ProfileArea"}
>> {"status": 1, "id": 2}

CREATE: config/toolOutputs, {"toolId": 1, "type": "Height"}
>> {"status": 1, "id": 3}

It should be emphasized that the arguments for the Create method are not a subset of the object properties. Ie. the user cannot specify a "name" property and expect it to be automatically applied to the newly created object. This is because method arguments and object properties are different things; mixing these result in collision and ambiguity. In some other environments (such as an RDBMS), this create-and-update behaviour is referred to as "upsert", implying both "update" and "Insert"

If we do support updating properties during creation these properties would be specified in a separate object in the arguments of the method: 

CREATE: config/tools, {"type": "ProfileArea", "insertAt": 0, "data": {"name": "Custom Tool Name"}}
>> {"status": 1, "id": 3}

Delete

Similarly, deleting an item must be done with the Delete method, rather than implicitly by sending a new parent model omitting the items to be deleted. 

// Delete a single item
DELETE: config/tools/2
>> {"status": 1}

// Bulk delete all items
DELETE: config/tools/*
>> {"status": 1}

Read

Read has a few special arguments specific to this method which include :

Argument Argument Type Description Example
includeSchema boolean

This is set to true by default in the framework. (GoPxL Console sets it to false)

Used to display the schema of the read properties.

NOTE: an empty list ("{}") must follow the resource path.

read /system{}{"includeSchema":false}
expandLevel int

This is set to 0 by default in the framework meaning do not expand. Special values include

  • -1 : expand all
  • 0 : don't expand (default)

int values 1 will indicate to expand 1 level and so on.

See

NOTE: an empty list ("{}") must follow the resource path.

read /scan/engines/g2xxx{}{"expandLevel":-1}
fields JSON

This field is used to read a specific property/properties from a resource.

A value must be provided for the field being read, just to fulfill the syntax requirements of the protocol.

The actual value is ignored when processing this method.

NOTE: an empty list ("{}") must follow the resource path.

read /system {} {"fields":{"autoStart":""}} 

Response:
{
  "payload": {
    "_links": {
      "self": {
        "href": "/system"
      }
    },
    "autoStart": false
  },
  "status": 1,
  "type": "response"
}

Calling Read on a resource returns its content: 

read /system {} {"expandLevel" : 0}
{
  "path": "/system",
  "payload": {
    "_links": {
      "self": {
        "href": "/system"
      }
    },
    "_schema": {
      "properties": {
        "autoLiveSimEnabled": {
          "sortOrder": 200,
          "title": "autoLiveSimEnabled",
          "type": "boolean"
        },
        "autoStart": {
          "sortOrder": 100,
          "title": "autoStart",
          "type": "boolean"
        },
        "runState": {
          "enum": [
            0,
            1,
            2
          ],
          "enumText": [
            "Ready",
            "Running",
            "Conflict"
          ],
          "readOnly": true,
          "sortOrder": 0,
          "title": "runState",
          "type": "integer"
        }
      },
      "sortOrder": 0,
      "title": "",
      "type": "object"
    },
    "autoLiveSimEnabled": true,
    "autoStart": false,
    "runState": 0
  },
  "status": 1,
  "type": "response"
}

Embedded Resource Expansion

As described earlier, a resource may contain embedded resources that are partially represented. These embedded resources can be expanded via a parameter, "expandLevel", which determines how many levels of embedded resources to expand. Note that this parameter is optional; omitting it is equivalent to setting it to 0.

For example, consider the following resources:

  • /tools
  • /tools/tool1
  • /tools/tool1/inputs/in0
  • /tools/tool1/outputs/output0
  • /tools/tool2
  • /tools/tool2/inputs/in0
  • /tools/tool2/outputs/output0
  • /tools/tool2/outputs/output1

The following behaviours are expected:

ExpandLevel Value Behavior
0 _embedded contains only partial representations of /tools/tool1 and /tools/tool2.
1 _embedded contains full representations of the tools, but only partial representations of the inputs and outputs.
2 _embedded contains full representations of all tools and their inputs and outputs.
-1 Expand all embedded resources. In this case, it is equivalent to expandLevel = 2, since inputs and outputs do not have subresources.

Here's an example of reading the /tools resource containing a single tool with an expandLevel of -1 

Command :
read /tools {} {"expandLevel":-1, "includeSchema":false}

======== read  /tools ========

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_embedded": {
            "go:toolInput": [
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/inputs/FixedInput0"
                  }
                },
                "acceptedDataFormats": [
                  {
                    "arrayed": false,
                    "type": 12
                  }
                ],
                "dataSource": "",
                "displayName": "Fixed Input",
                "extId": "FixedInput0",
                "id": "FixedInput0",
                "optional": false
              }
            ],
            "go:toolOutput": [
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/outputs/FixedOutput0"
                  }
                },
                "assocOutputs": [],
                "dataFormat": {
                  "arrayed": false,
                  "type": 19
                },
                "dataSourceId": "",
                "displayName": "Fixed Out 1",
                "enabled": false,
                "extId": "FixedOutput0",
                "id": "FixedOutput0",
                "parameters": {
                  "decisionMax": 0.0,
                  "decisionMin": 0.0
                },
                "priority": 0,
                "recordingEnabled": false
              },
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/outputs/FixedOutput1"
                  }
                },
                "assocOutputs": [],
                "dataFormat": {
                  "arrayed": false,
                  "type": 19
                },
                "dataSourceId": "",
                "displayName": "Fixed Out 2",
                "enabled": false,
                "extId": "FixedOutput1",
                "id": "FixedOutput1",
                "parameters": {
                  "decisionMax": 0.0,
                  "decisionMin": 0.0
                },
                "priority": 0,
                "recordingEnabled": false
              }
            ]
          },
          "_links": {
            "self": {
              "href": "/tools/TestDynamicIo-0"
            }
          },
          "batched": false,
          "displayName": "Test Dynamic IO 1",
          "extId": "TestDynamicIo-0",
          "id": "TestDynamicIo-0",
          "isBatchable": true,
          "ordIndex": 0,
          "parameters": {
            "ArrayOutputCount": 0,
            "EnableAuxInput": false,
            "OutputCount": 0
          },
          "parametersVersion": "1",
          "toolType": "TestDynamicIo"
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/tools"
      }
    }
  },
  "status": 1,
  "type": "response"
}

If for example we were only interested in the tools and not their inputs/outputs, we would use the expandLevel to the specific level we are interested in. 

Command:
read /tools {} {"expandLevel":1, "includeSchema":false}

======== read  /tools ========

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_embedded": {
            "go:toolInput": [
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/inputs/FixedInput0"
                  }
                }
              }
            ],
            "go:toolOutput": [
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/outputs/FixedOutput0"
                  }
                }
              },
              {
                "_links": {
                  "self": {
                    "href": "/tools/TestDynamicIo-0/outputs/FixedOutput1"
                  }
                }
              }
            ]
          },
          "_links": {
            "self": {
              "href": "/tools/TestDynamicIo-0"
            }
          },
          "batched": false,
          "displayName": "Test Dynamic IO 1",
          "extId": "TestDynamicIo-0",
          "id": "TestDynamicIo-0",
          "isBatchable": true,
          "ordIndex": 0,
          "parameters": {
            "ArrayOutputCount": 0,
            "EnableAuxInput": false,
            "OutputCount": 0
          },
          "parametersVersion": "1",
          "toolType": "TestDynamicIo"
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/tools"
      }
    }
  },
  "status": 1,
  "type": "response"
}


Update

This method updates a resource by overwriting it with a new object.Partial modification is allowed by sending only the properties to be modified: 

UPDATE: config/toolOutputs/0, {"content": {"name": "Pin Z Location", "enabled": false}}
>> {"status": 1}

Patch updates

Normally, a client is expected to provide the complete resource when performing an update. This is a confusing detail that is often overlooked in HTTP-based REST API's, and warrants its own section on wikipedia . This means all fields that are present on the resource and not indicated as readOnly in the schema (see Schema and Data Types ), should normally be provided back to the server for the update, even if they are not to be changed. In many cases, this behavior is inconvenient - especially when the client wants to only change a few fields. For this reason, the Update method by default supports "patch updates" which allows the client to signal only the changes that should be made to the resource.

To sum it up, we support patch by default and requires arguments to be passed to modify this behaviour, theses arguments are described below

Field Type Description
patch boolean

indicates whether a patch should be performed or not with the update.

Defaults to "true", if this field is omitted.

validatePatch boolean

indicates if validation on the given payload should be performed.

Validation removes any fields that aren't present in the resource being updated.

e.g. If a resource is updated and the payload contains a field not in that resource, it will remove it from the patch before merging the patch.

This is not really necessary but it ensures that the given patch being applied only contains fields present.

Defaults to "true", if this field is omitted.

An example of an update call : 

update /resource
{
  "payload": {
    "parameters": {
      "frameRate": 100.0
    }
  },
  "args": {
    "patch": true,  //defaults to true if not specified
    "validatePatch": true  //defaults to true if not specified
  }
}

Patching and Arrays

When replacing object properties that are simple values such as strings and numbers, patching is a straightforward process: the values in the patch are used to replace the values of the target resource at the specified object path. However, with arrays, things are a bit more complex. There are two different cases for arrays that are described here as well as their behaviour with patch.

  1. Arrays of simple values (strings, ints, etc...)
  2. Arrays of objects (other json objects, such as a region object containing height, width, x and z values).

Patching Arrays of Simple Values

With arrays of simple values, patching replaces the whole value of the array and does not patch each individual element in the array. For example, given a target JSON document containing an array of ints 

{
    numArray: [1,2,3,4]
}

performing an update such as this 

update /resource/path {
    numArray: [5,6]
}

would result in the numArray JSON document with this new value where the entire array is replaced, rather than just updating the first two entries. 

{
    numArray: [5,6]
}


Patching Arrays of Objects

For an array of objects, it behaves a bit differently. Arrays are not fully replaced, and instead the patch is able to specify which index of the array to update. For example, given a target JSON document containing an array of objects 

{
    regionArray: [{
        height: 0,
        width: 0,
        x: 0,
        z: 0
    },{
        height: 0,
        width: 0,
        x: 0,
        z: 0
    },{
        height: 0,
        width: 0,
        x: 0,
        z: 0
    }]
}

calling an patch update on the second region in the array can look like either of these options, where the second region is indicated by having a null or empty first region in the update request. 

update /resource/path
{
    regionArray : [
      {},           <<<<< indicates no change to first region
      {
        height : 123,
        width : 456,
        x : 7,
        z : 8
      }
    ]
}

update /resource/path
{
    regionArray : [
      null,         <<<<< indicates no change to first region
      {
        height : 123,
        width : 456,
        x : 7,
        z : 8
      }
    ]
}

The result of either of these patches will change the second region of regionArray[] too look like this: 

{
    regionArray: [{
        height: 0,
        width: 0,
        x: 0,
        z: 0
    },{
        height: 123,
        width: 456,
        x: 7,
        z: 8
    },{
        height: 0,
        width: 0,
        x: 0,
        z: 0
    }]
}

Note that updating this way DOES NOT remove the 3rd region in the array.

Patching is incapable of removing/adding elements for array of objects.

Call

The following methods don't map perfectly to any HTTP method. However, for possible future translation to an HTTP transport channel, it is considered acceptable for custom methods to be replaced with the HTTP "POST" verb, and encoded using the guidelines outlined by Google here: https://google.aip.dev/136

The Call method is used to support calling "Command" resources (see Documentation Conventions#ResourceTypes ). 

CALL /path/to/resource {"argument": "value}
>> {
  "path" : "/path/to/resource",
  "payload": null,
  "status": 1,
  "type": "response"
}

CALL /system/commands/start {}
>> {
  "path" : "/logs/summary",
  "payload": null,
  "status": 1,
  "type": "response"
}

Action lists vs Command lists

GoPxL uses the convention to group callable resources under a "commands" or "actions" collection resource. Callable resources within a "command list" collection represent a static command API - these resources do not change, they are a static part of the framework of the application.Callable resources within an "action lists" collection are dynamic - the list of available resources may change with application state, and the arguments they accept can vary. Clients are encouraged to read the list of available callable resources within the collection, and present the list to end users.

Callable resources are not exclusively callable. It is possible for a callable resource to also be readable. By convention, callable resources within an "action" collection will also be readable.

For more information on Action resources, read Documentation Conventions#ActionAction

If ever an attempt to read a callable resource within an action list results in an error status code such as -996 "unimplemented", the client should interpret this as the action not requiring any arguments. 

//First we get the list of callable resources within the action list
READ /path/to/actions
>> {
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/path/to/actions/callable1"
            }
          }
        },{
          "_links": {
            "self": {
              "href": "/path/to/actions/callable2"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/path/to/actions"
      }
    }
  },
  "status": 1,
  "type": "response",
  "path": "/path/to/actions"
}

//Then we get the information for a particular callable resource, such as the arguments it supports
READ /path/to/actions/callable1
>> {
  "path" : "/path/to/actions/callable1",
  "payload": {
    "_links": {
      "self": {
        "href": "/path/to/actions/callable1"
      }
    },
	"_schema": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties":{
            "arg1": {
              "type": "number",
              "title": "Argument 1" //the label for arg1
            },
            "arg2": {
              "type: "string",
              "title": "Argument 2", //the label for arg2
              "description": "argument details here" //additional description information for arg2
            }
          }
        }
      }
    }
	"id": "callable1",
    "displayName": "My Action", //This action's displayName. Useful for defining menu titles, button text, or prompt/window titles
    "message": "This action will do great things. Make sure you save." //If defined, the client should present this message to users before the action is invoked
    "parameters": { //these represent the arguments this callable resource accepts
      "arg1": 10,  //in this example arg1 is a number and has a default value of 10
      "arg2": "current value"  //in this example arg2 is a string and has a default value of "current value"
    }
  },
  "status": 1,
  "type": "response"
}

//Finally, we can call this resource. The client should prompt the user for the arguments based on the previous response.
CALL /path/to/actions/callable1 {"arg1": 42, "arg2":"Some user provided value"}
>> {
  "path" : "/path/to/actions/callable1",
  "payload": null,
  "status": 1,
  "type": "response"
}

//Sometimes, callable resources within an action list might not support being read
READ /path/to/actions/callable2
>> {
  "path" : "/path/to/actions/callable2",
  "payload": null,
  "status": -996,
  "type": "response"
}

//These resources can be called with no arguments
CALL /path/to/actions/callable2 {}
>> {
  "path" : "/path/to/actions/callable2",
  "payload": null,
  "status": 1,
  "type": "response"
}

Sub/Unsub/Listsub/Clearsub

The following methods don't map perfectly to any HTTP method. However, for possible future translation to an HTTP transport channel, it is considered acceptable for custom methods to be replaced with the HTTP "POST" verb, and encoded using the guidelines outlined by Google here: https://google.aip.dev/136

Observable resources offer the ability to asynchronously notify a client of events affecting the content and composition of resources.

Event notifications must be subscribed to within the context of the client connection/session, and leverages the "relative path'ing" nature of resources, and are not directly tied to a specific resource.

Unless otherwise stated, ALL resources within this Resource API are observable.. If a resource does not raise any event notifications however, the would be no point to subscribe to it however..

The Resource Reference documentation for any Resources that supports event notifications will list the event notifications supported for that Resource in a section called Notifications . If the section is missing from the Resource Reference documentation, it can be assumed that the particular resource DOES NOT raise any event notifications.

Subscription Notification Response Message

A notification will be delivered to the client as an object. See Notification Type Message for the fields in a notification response message.

Methods

Subscriptions must be issued upon the client connection, and are non-resource specific:

Method Description

sub path-expression


Subscribes to event notifications from the given path.

Examples:

Subscribe to event notifications from a single tool: 

sub /tools/TestForward-0

Subscribe to all tools within the tools collection (ie. /tools/(id)), as well as all inputs and outputs within each tool (ie. /tools/(id)/inputs, and /tools/(id)/outputs). 

sub /tools/*
unSub path-expression

Unsubscribes event notifications from the given path.

Examples: 

unSub /tools/TestForward-0
unSub /tools/*
listSub Lists all current subscriptions.
clearSub Clears all current subscriptions.

Subscription Path-Expressions

To subscribe to receive event notifications, a special wildcardable path-expression is used which can accept the following:

Match Intent Description
Specific Resource

Match a specific resource at the given path.

Example: 

sub /tools/TestFoward-0
sub /tools/ProfileTool-1/inputs/Input0
Sub-Resources

Match any resource or sub-resource at the given path.

Example: 

sub /tools/*
sub /scanners/*
Mix

Match either a specific or sub-resource, allowing for wildcarded sub-resources along the way.

Example:

Match specific resource, allowing for sub-resources along the way: 

sub /tools/Profile*/inputs/Input0


Match wildcard resources, allowing for sub-resources along the way: 

sub /tools/Profile*/inputs/*

Subscriptions using path-expressions are multiple and explicit:

Multiple path-expressions can subscribed to, and each is explicit even if they overlap by nature of wildcarding.

Also, duplicate subscriptions are automatically ignored.

Method Sequence listSub Response

sub /tools/TestForward-0
sub /tools/*
listSub 

{ "subscriptions" : [
  "/tools/*",
  "/tools/TestForward-0"
]}

sub /tools/TestForward-0
sub /toold/TestForward-0 (duplicate)
sub /tools/*
unsub /tools/*
listSub 

{ "subscriptions" : [
  "/tools/TestForward-0"
]}

Subscriptions using path-expressions are wholistic:

Even if multiple overlapping path-expressions are subscribed to, only one event notification will be send to the client's connection session.

For exaaple, given a single event notification from the /tools/TestForward-0 resource, the following sets of subscriptions are equivalent:

  • /tools/*

or

  • /tools/*
  • /tools/TestForward-0

Stream/CancelStream

The following methods don't map perfectly to any HTTP method. However, for possible future translation to an HTTP transport channel, it is considered acceptable for custom methods to be replaced with the HTTP "POST" verb, and encoded using the guidelines outlined by Google here: https://google.aip.dev/136

Streamable resources offer the ability to continuously deliver a "stream" of data to a client. See Streamable Resource Types .

Stream Response Message

See Stream Type Message for details of the message fields.

Methods

Streams must be initiated and canceled upon the client connection, and are resource specific. See Streamable Resource Types for description of the methods.

Error Handling

All methods are request/response based. That is, every method request will be responded by a single response. See Connection and Message Framing for more information about request and response structures.

{
"payload" : null ,
"status" : 1 ,
"type" : "response"
}

However, if the request was not successful (ie when the Control Message hasstatus!= OK), the payload will contain any errors that occurred. For potential status codes, see here :

{
"payload" : {
"errors" : [
{
"description" : "Request failed for a particular reason. Please change these things and try again." ,
"status" : -996
}
]
},
"status" : -996 ,
"type" : "response"
}

The errors property will only be present if status!= kOK. Each error object has its own status and message. Messages are translated according to the currently configured system locale. There may be multiple errors, although typically there will only be one. In the event that there are multiple errors, with different status codes, the body of the response will generally have status = ERROR. Clients may check each error object for specific details on the variety of different status codes.

GoPxL: Metrics

Overview

The equivalent of health indicators in Gocator Classic are called Metrics in GoPxL.

This is in and of itself, a better name, because the Gocator Classic health indicators evolved (over time) to mean much more than just "health" information. Although over-temperature information can be associated with sensor "health" tool execution statistics, and measurement pass/fail counts do not necessarily reflect the "health" of the sensor. The term "metrics" simply means to measure something and is more appropriate. Some of the metrics continue to be associated with health, while other metrics are associated with statistics (mininum, maximum, average, and standard deviation).

The subsequent sections describe the main areas that the Gocator Classic Health system was altered:

  • Gocator application metrics shall be divided into categories and sent according to interest expressed by clients.
  • Gocator application metrics shall support multiple data types.
  • Gocator application metrics shall be retrievable by clients via the REST API.
  • Gocator application metrics shall be retrievable by GoPxLSdk clients using human-readable identifiers.

Metrics Groups

The health channel in Classic provides indicators for all entities in the system, all the time. Clients cannot choose to express interest in only a subset of health indicators.
For GoPxL, the metrics system is more scalable, by allowing client to explicitly express interest in only the metrics they are interested in.

Part of this means dividing up metrics into different metrics groupings, so that interest for specific groups can be indicated. The metrics groupings also serve to uniquely scope and identify a metric, so that Gocator Classic's Indicator Id is no longer required.

At the highest level, the following metrics groupings exist for GoPxLMetrics:

Metrics Path Description Gocator Classic example indicator
/system System level metrics.

(2007) GC_INDICATOR_CPU_USAGE
(2017) GC_INDICATOR_UPTIME

/scan

Scan metrics.

This may be sub-divided further into metrics per instance of scan engines, scanners, and scan sensors.

(2211) GC_INDICATOR_CAMERA_RATE
(20001) GC_INDICATOR_CURRENT_SPEED

/tools Tool execution, measurement and feature metrics. These may be further sub-divided into metrics that are per tool.

(22004) GV_INDICATOR_RUNTIME

(30000) GC_INDICATOR_MEASUREMENT_PASS_COUNT
(30000) GC_INDICATOR_MEASUREMENT_FAIL_COUNT

/controls Industrical protocol metrics. These may be further sub-divided into metrics per industrical protocol type (ie. Gocator, Ascii, EtherIp, Modbus, Profinet, Hardware, etc.).

(21003) GC_INDICATOR_ETHERNET_OUTPUT

(21014) GC_INDICATOR_ANALOG_OUTPUT_DROP_V2
(21015) GC_INDICATOR_DIGITAL_OUTPUT_DROP_V2

(21006) GC_INDICATOR_DIGITAL_OUTPUT_HIGH_COUNT

(21007) GC_INDICATOR_DIGITAL_OUTPUT_LOW_COUNT

A full listing of metrics (and mappings back to legacy health indicators) will be populated and maintained for GoPxL on the Metrics Resources page.

Metrics Reset

Resetting of health indicators in Gocator Classic was a global operation (resetting ALL indicators at once).

In GoPxL, the resetting of metrics will be be grouping specific. In some cases, a reset operation will apply to multiple instances within a metrics group. For example:

Metrics Path Description
/system/commands/resetMerics Resets system level metrics.
/tools/commands/resetMetrics Resets all metrics for EACH tool.

Metrics for Tool Developers

In Gocator Classic, adding a metric in the tool system required supporting changes in the GoSensor library (specifically GsHealth) in order to output the metric. In GoPxL, this is no longer the case and offers tool developers the advantages of the open-closed principle with respect to metrics. This added convenience should be of increased importance as we attempt to grant more independence to tool development.

The tool developer is able to expose custom metrics within their own tool type implementation (usually based upon CommonTool) via the ITool and CommonTool base classes: 

/*! @class ITool ITool.h
 *  @brief Main tool interface class
 *  @ingroup GoPipe-Tools
 */
class ITool
{
public:
    //...
    /**
     * Returns metrics specific to the tool implementation.
     *
     * @return              Reference to tool implementation specific metrics.
     */
    virtual MetricsGroup& Metrics() = 0;

    /**
     * Resets metrics specific to the tool implementation.
     */
    virtual void ResetMetrics() = 0;
    //...
};

/*! @class CommonTool 
 *   @brief base class for user defined tools that has to be derived from to create tools
 *   @ingroup GoPipe-Tools
 */
class GoPipeClass CommonTool : public ITool
{
protected:
    //...
    /**
     * Initializes the tool.
     *
     * @param host 
     * @param params        A property object containing params to initialize the tool with.
     * @param metrics       A metrics object containing metrics to initialize the tool with.
     */
    void Init(IToolHost& host, Go::Properties::Node& params, MetricsGroup& metrics);

    /**
     * Returns common tool specific metrics, defined by the tool developer.
     *
     * @return              Reference to common tool specific metrics.
     */
    MetricsGroup& Metrics() override;

    /**
     * Resets metrics specific to the tool implementation.
     *
     * @remarks             Throws kERROR_UNIMPLEMENTED if tool developer 
     *                      is using custom metrics and does not override this.
     */
    void ResetMetrics() override;
    //...
};

Classic Health Probe System

GoPxLmetrics originate from the domain module that hosts the calculation. This is contrast to the approach in Classic, where all health indicators were "routed" through the Firesync health probe system.

For lower-level hardware probes that are only available from Firesync, there may still be a singleton health class inGoPxL to bridge and provide such metrics to modules that require it (such as certain system or scanner metrics).

Visibility of metrics will be via the REST protocol, which will mostly replace the multiple alternative mechanisms in Classic for viewing health such as:

  • health.cgi
  • kGoPxL debug viewing of health metrics
  • tool_showhealth.py

If there is a need to restore some of these mechanisms for GoPxL, we will revisit them after the initial availability of metrics through the REST protocol is completed.

Data Types

The Gocator Classic Health system was limited to outputting data as integer values.

GoPxL Metrics are intended to support more output data types, by leveraging the designs associated with flexible parameters and Schema and Data Types .

Metrics resources can be read from to learn about the schema: 

read /system/metrics

the response contains the schema: 

======== read  /system/metrics ========

{
  "payload": {    "_links": {
      "self": {  "href": "/system/metrics"    }
    },
    "_schema": {
      "properties": {
        "fault": {
          "properties": {
            "overheat": { "type": "boolean" },
            "overheatDuration": { "type": "integer" }
          },
          "type": "object"
        },
        "performance": {
          "properties": {
            "cpuTotalUsed": { "type": "integer" },
            "memCapacity": { "type": "integer" },
            "memUsed": { "type": "integer" },
          "type": "object"
        },
        "status": {
          "properties": {
            "encoderFreq": { "type": "integer" },
            "encoderValue": { "type": "integer" },
            "upTime": { "type": "integer" }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "fault": {
      "overheat": false,
      "overheatDuration": 0
    },
    "performance": {
      "cpuTotalUsed": 2,
      "memCapacity": 17003671552,
      "memUsed": 9180221440,
    },
    "status": {
      "encoderFreq": 0,
      "encoderValue": 0,
      "upTime": 8738
    }
  },
  "status": 1,
  "type": "response"
}

REST API

GoPxLMetrics will leverage theStreaming system. To start and cancel streaming of metrics resources, the usual methods will be used: 

stream /system/metrics
cancelStream /system/metrics

A streaming API for metrics reporting within GoPxL is: 

/**
 * Interface of a metrics reporter.
 */
template <typename... KeyArgs>
class IMetricsReporter
{
public:
    virtual ~IMetricsReporter()
    {
    }

    /**
     * Retrieves the last metrics report. 
     *
     * @param reportKey             Key for resolving the metrics report.
     * @return                      An @ref IMetricsSource that hosts the metrics report.
     *
     * @remarks The @ref IMetricsSource provides an interface to retrieve the resolved metrics
     *          via @ref GoCommon::MetricsGroup.
     */
    virtual const IMetricsSource& LastReport(KeyArgs... reportKey) = 0;

    /**
     * Adds a metrics report handler. 
     *
     * @param fx                    A callback function.
     * @param reportKey             Key for resolving the metrics report.
     * @return                      A callbackId used to remove the report handler.
     *
     * @remarks The @ref IMetricsSource provides an interface to retrieve the resolved metrics
     *          via @ref GoCommon::MetricsGroup.
     */
    virtual Go::Event<const IMetricsSource&>::CallbackId AddReportHandler(std::function<void(const IMetricsSource&)> fx,
        KeyArgs... reportKey) = 0;

    /**
     * Removes a metrics report handler from the map.
     * The event in the map will only be removed when all handlers are removed.
     *
     * @param callbackId            The callbackId of the callback to remove.
     * @param reportKey             An optional key provided to resolve the metrics report.
     *
     * @remarks The @ref IMetricsSource provides an interface to retrieve the resolved metrics
     *          via @ref GoCommon::MetricsGroup.
     */
    virtual void RemoveReportHandler(Go::Event<const IMetricsSource&>::CallbackId callbackId,
        KeyArgs... reportKey) = 0;
};

Accessing Metrics From GoPxLSdk

Access to metrics from GoPxLSdk clients (including access for GoHMI) will be accomplished via the REST API discussed previously on this design page.

Path Parameters

When jobs are being switched on theGoPxL sensor, ephemeral ids (eg. /tools/TestForward-12) could fluctuate, causing issues with resource paths declared within third party products such as (SmartHMI WebIQ Designer).

To avoid this issue, URI path parameters are employed : 

stream /tools/extId=My%20Tool/metrics
cancelStream /tools/extId=My%20Tool/metrics

The "extId" of the resource is under the control of the user and can be made non-changing even as different jobs are loaded.

Conventional (ie. non HMI) GoPxLSdk clients should also be able to use the same strategy to address resource paths in a more stable manner.

JSON Pointer

The GoPxLSdk includes support for JSON Pointer (rfc6901) . This makes it easy to declaratively specify an individual metric from a streamed metrics report.

Some examples, given the following metrics json: 

======== read  /system/metrics ========

{
  "payload": {    "_links": {
      "self": {  "href": "/system/metrics"    }
    },
    "fault": {
      "overheat": false,
      "overheatDuration": 0
    },
    "performance": {
      "cpuTotalUsed": 2,
      "memCapacity": 17003671552,
      "memUsed": 9180221440,
    },
    "status": {
      "encoderFreq": 0,
      "encoderValue": 0,
      "upTime": 8738
    }
  },
  "status": 1,
  "type": "response"
}

The following json pointers can be specified: 

/fault/overheat
/fault/overheatDuration
/performance/cpuTotalUsed
/performance/memCapacity

GoPxL: GoPxL Data Protocol (GDP)


Overview

GoPxL Data Protocol (GDP) is intended for rapid delivery of the dataSource content to SDK users. The implementation of the server is such that it is optimized for rapid transmission of many messages. As such, messages are serialized using proprietary formats, documented on the Message Serialization page.

Connections are typically long running. A client will establish a connection for as long as they are ever interested in receiving data. The data which is to be delivered is stored as configuration, which is exposed on the REST API and documented on the GoPxL Data Protocol (GDP) Resources page. This configuration, like most other configuration, can be saved in and loaded from a job. As a result, the types of data that are sent over the long running connection can vary over time, as jobs are loaded or unloaded.

The protocol is designed to be relatively stateless, however there are some stateful aspects if the client intends to recover the various types of grouping/collections which are represented in the message structure. These are discussed further in the Message Grouping section below.

Connection and Framing

Message Structure

Backward Compatibility

See Versioning and Compatibility for more information about the standards and practices which are adhered to in maintaining compatibility.

Most of the GDP protocol's flexibility comes through the use of attribute sections, mentioned in the section below.

Attribute Sections

When flexibility is required, structures within messages (referred to as field "Sections") shall be described with a count of bytes. This allows optional fields to be added to the end of section structures without necessitating a breaking change. Many messages contain an attribute size that a parser can use to skip past any unparsed attributes and continue reading. This means the attributeSize field describes the size of the attributes in the respective section. This allows the client to be able to read as much as it knows, and then skip all unreadable attributes to the start of the next section if available. New fields to any message, in future updates to the protocol format, will be added to the end of attribute sections and before subsequent sections.

Unless stated otherwise, attributeSize fields are considered part of the section they measure. This means attributeSize fields include themselves.

Common Attribute Section (CAS)

The Command Attribute Section (CAS) is common to every single message sent. It is it's own section and immediately follows the header. The CAS contains fields that allow clients to recover common information which is present on all messages. Some of these fields are focused on connections and message grouping (discussed below), while other fields are data-specific and provide important information for correct interpretation of the data itself (such as the transform and bounding box fields). In some cases, these fields are, themselves, optional. Clients should only read these optional fields when it is correct to do so, as documented.

Message Grouping

For the purposes of being able to compare messages, the protocol supports supports two formal types of grouping:

  1. Arrayed Messages, hereon referred to as "Arrays"
  2. Message Sets, hereon referred to as "Sets"

Arrays are potentially emitted from a single output on given data source (ie tool or scanner) for a given frame. They are a way of representing multiple objects within a given instant in time. Arrays can not contain Arrays

Sets are similar to Arrays, however they apply across all outputs from all data sources. Since a tree of tools typically descends from a single data source, the rate of data produced by that tree is determined by the rate of data produced by the source. Every message from every node in the tree contains the same "stamp" message, and this is used by the system to collect all messages into a Set. All messages from a given Set are sent to the client with appropriate meta data to recover the Set on the client. It is possible for many Arrays to be contained within a single Set. Sets can not contain Sets.

The information to collect both Arrays and Sets is found in the common attribute section (CAS).



GoPxL: Message Serialization

Overview

This page describes the serialization format of messages for scan data messages sent to external clients such as the GUI or SDK.

Message Header (Header)

All messages will contain a message header section

Header

Field

Type

Offset

Description

size

32u

0

Count of bytes in message (including this field), (min: 6, current: 6).

type 16u 4 Message Type identifier

Common Attributes (CommonAttrs)

A common attribute section to describe attributes common to all messages. All messages will contain this section

This section (like any other) is subject to change - fields can be added at any time. This is permissible by the section growth rules outlined in GoPxL Data Protocol (GDP)#BackwardCompatibility

Field

Type

Offset

Description

commonAttrSize

32u

0

Common attribute section size (bytes). This has the same use as "attributeSize" in all messages - it describes the size of the attributes section below (including itself)so a client can read only to a certain point and know where to move on to start reading the next section. It is important that clients use this field during deserialization. As stated above, fields can be added in susbequent versions of the protocol and these additions are not considered breaking changes. It is the responsibility of the client to use the size field to ensure deserialization of later sections and data happens at the correct buffer offset.

Includes itself (will always be greater than 4).

spaceType 8u 4

Determines the data space type for this data message. Can be one of

0 None or Null space. Represents a non-existent data space. In this space, the transform field doesn't apply. Usually reserved for signal-type messages or custom data types, but also applies to the Stamp message.

1 Data space. Data exists within a 3DEuclidean spacewith units of length defined in mm.

2 Image Space. Data exists within a 2DEuclidean space withunits of length defined in pixels (px).

hasTransform

8u 5

Determines if this data message has a transform.

0 transform is not present and not sent. Clients should interpret the transform as identity.

1 transform for data message is present and sent.

transform Transform3d 32f 6

Optional: only sent if hasTransform=1. IfhasTransform=0, transform is identity.

Transformation matrix (3x4) of 32-bit floating point values:

  • xx, xy, xz, xt
  • yx, yy, yz, yt
  • zx, zy, zz, zt

Applying this transform to the associated data results in the data being put into the common frame of reference. This is typically true when spaceType = 1 (Data Space), but transform can also apply when spaceType = 2 (Image space). Transform does not apply when spaceType = 0 (None or Null Space)

The order in which values are serialized is as follows:

xx, xy, xz, xt, yx, yy, yz, yt, zx, zy, zz, zt

Number of bytes for transform data = 12 * 4 (4 bytes per 32-bit floating point value) = 48 bytes.

hasBoundingBox 8u

6 if hasTransform= 0

or

54 ifhasTransform= 1

Determines if this data message has a bounding box or not.

0 no bounding box sent.

1 bounding box sent.

boundingBox Rectangle3d 32f

7 if hasTransform= 0

or

55 ifhasTransform= 1


Optional: only sent if hasBoundingBox is 1.

Bounding box fields are represented as 32-bit floating point numbers sent in the following order:

  • X - X-coordinate of the center (m m ).
  • Y - Y-coordinate of the center (m m ).
  • Z - Z-coordinate of the center(m m ).
  • Width - Width is the size along the x-axis (m m ).
  • Length - Length is the size along the y-axis (m m ).
  • Height - Height is the size along the z-axis (m m ).

Number of bytes for bounding box data = 6 * 4 (4 bytes for each 32-bit floating point value) = 24 bytes.

arrayCount 32u

7 if hasTransform= 0 and hasBoundingBox = 0

or

55 if hasTransform= 1 and hasBoundingBox = 0

or

31 if hasTransform= 0 and hasBoundingBox = 1

or

79 if hasTransform= 1 and hasBoundingBox = 1

Any message could be a member of an arrayed output. If this is the case, this field indicates the count of messages in the array.

If the message is not in an array (ie it is associated with a non-arrayed dataSource) the value of this field will be 0.

arrayIndex 32u

arrayCount offset + 4

This field only applies if arrayCount is >= 1 and refers to the index or position of this message within the array.

If arrayCount is 0, this field can be ignored.

dataSourceIdLength (DSIL)

16u

arrayIndex offset + 4

Length of thedataSource id in bytes.

dataSourceId char[] dataSourceIdLength offset + 2

Used to identify the source of the message and distinguish messages which belong in different/distinct arrays.
Null terminator is ABSENT.

stampSourceIdLength (SSIL)

16u

dataSourceId offset + DSIL Length of the scanner Id in bytes.
stampSourceId char[]

stampSourceIdLength offset + 2


Unique Id string used to identify the set that this message belongs to. As of writing, this is the "ScannerId", however in the future this will change to either the dataSourceId for the stamp output associated with this data or perhaps a more opaque unique ID. Regardless, clients should treat this as an opaque ID, used solely for collecting many messages into a collection that describes a set.

Null terminator is ABSENT.

dataSetId


64u

stampSourceId offset + SSIL

Unique id for the data set that this message belongs to. This field could be based on the frameIndex of the message's associated stamp message (ie a monotonically increasing unsigned integer which counts the total number of stamps/frames generated by the stamp source), however this is not strictly necessary. This field's primary purpose is to allow clients to group all messages that belong to the same frame, including the stamp . It is particularly useful when receiving messages asynchronously such as when streaming dataSources via the REST API .While dataSetId is often equal to frameIndex, clients should retrieve frameIndex from the stamp message and not from this field directly.

Note this field is for internal LMI use only. Behavior of this field may change without notice.

isLastMsg 8u dataSetId offset + 8

Boolean indicator. When it is set to true, the current message is the last message within the current dataSet. All messages in a given dataSet should have equal dataSetId's, but isLastMsg makes for more convenient logic on the client side. When clients are connected via GDP protocol, messages are always sent as a set. Recollecting messages into a dataSet is done by waiting until the isLastMsg arrives, starting a new dataSet, and collecting messages again until the next isLastMsg.

0 not the last messagein the dataSet.

1 this is the last message in the dataSet.

Note this field is only applicable to serialization via GDP for SDK clients. When obtaining these messages via Resource Streaming the /dataSources/(id)/data resource, this field is undefined and should not be used.

gdpId

16u isLastMsg offset + 1

Gocator data protocol Identifier. This value corresponds to the 'output id' the 'dataSourceId' was assigned to in the 'Gocator Connection' panel on the UI, thus it identifies which data source the current msg belongs to.

This is only used for Gocator data protocol serialization, and defaults to (65535U) when not used.

Note 0 is a valid Gocator data protocol ID.

0.3.x.x Attribute added.

Message Types

Message Types

Name

Type

Signal

1

Null

10

Stamp

11

Uniform Profile

12

Profile Point Cloud 13

Uniform Surface

14

Surface Point Cloud

15

Image 16
Spots 17
Mesh 18
Measurement 19
Rendering 70
Point Feature 71
Line Feature 72
Plane Feature 73
Circle Feature 74
Health 100


Signal

Informs clients that all prior scan data messages on a stream are invalidated.

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

attributeSize

16u

Size of attributes, in bytes, including this field .

Null

Informs clients that the message contains no scan data, but could contain some error status information about why scan data is absent or could not be produced.

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

nullAttrs

NullAttrs

Null Attribute Section (see below)

NullAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

errorStatus

32s

Error status related to the message. Value is a status code, as documented in Common Types

Stamp

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

stampAttrs

StampAttrs

Stamp Attribute Section (see below)

StampAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

frameIndex

64u

Frame index (counts up from zero).

timetick

64u

The timetick is a 64-bit positive integer that is guaranteed to increase monotonically starting from zero.
It is guaranteed to be unique for every scan from a given scanner.
Interpretation of this number is scanner specific. See below in "Timetick Interpretation" for more information.

encoder

64s

Current encoder value (ticks).

encoderAtZ

64s

Encoder value latched at z/index mark (ticks).

status

64u

Bit field containing various frame information:

Bit 0: sensor digital input state

Bit 4: master digital input state

Bit 8-9: inter-frame digital pulse trigger (Master digital input if master is connected, otherwise sensor digital input. Value is cleared after each frame and clamped at 3 if more than 3 pulses are received).

systemTimeSec

64u

Seconds component of the system time on a PTP-supported device. When available, it represents UTC time in one of two timescales:

  1. the default PTP timescale (relative to epoch January 1, 1970) or
  2. an ARB (arbitrary) timescale (relative to some other predetermined epoch).

Defaults to 0 if the system time is not available.

systemTimeNsec 64u

Fractional seconds component of the system timeas described in the systemTimeSec field above. This is the nanoseconds portion of the system time which, when combined with the seconds component above, will provide the full system time with nanosecond precision.
Defaults to 0 if the system time is not available.

To calculate the full system time including this nanoseconds component, divide this systemTimeNsec value by 1 billion (1,000,000,000) and add it to the systemTimeSec value: 

systemTime = systemTimeSec + (systemTimeNsec / 1000000000);

Timetick Interpretation

Sensor Group Product Timetick Interpretation
Gocator

The timetick is a 64-bit positive integer that can be converted to microseconds by the following calculation:

Time in microseconds = timetick / 1.024

AVT 2-D Camera The timetick is a 64-bit positive integer that represents nanoseconds.

Uniform Profile (Resampled Profile)

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

profileAttrs

ProfileAttrs

Profile Attribute Section (see below).

ranges[W]

16s

Profile ranges.

Width (W) is from ProfileAttrs.

intensity[iW] 8u

Intensity arrays.

Width (iW) is from ProfileAttrs.

ProfileAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

width (W)

32u

Number of points per profile array.

intensity width (iW) 32u Number of intensity values per intensity array.

xScale

64f

X scale ( mm ).

zScale

64f

Z scale (mm).

xOffset

64f

X offset (mm).

zOffset

64f

Z offset (mm).

exposure

32f

Exposure in microseconds (us).

1.1.x.x -1 if exposure is not available.

Point Cloud Profile ( Raw Profile )

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

profileAttrs

ProfileAttrs

Profile Attribute Section (same as for Uniform Profile. See above.).

ranges[W]

Point16s

Profile ranges.

A Point16s is made up of two k16s fields: X-value and Z-value.

Point16s range =ranges[L][W];
float xPos = (range[0] * xScale) + xOffset;
float zPos = (range[1] * zScale) + zOffset;

Width (W) is from ProfileAttrs.

intensity[iW] 8u

Intensity arrays.

Width (iW) is from ProfileAttrs.

Uniform Surface (Resampled Surface)

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

surfaceAttrs

SurfaceAttrs

Surface Attribute Section (see below).

NOTE: the isAdjacent field in SurfaceAttrs is NOT applicable to Uniform Surface and is therefore ABSENT from the SurfaceAttrs for Uniform Surface.

ranges[L][W]

16s

Surface ranges.

Length (L) and Width (W) are from SurfaceAttrs.

intensities[iL][iW] 8u

Surface intensities.

Length (iL) and Width (iW) are from SurfaceAttrs.

SurfaceAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

length (L)

32u

Surface length (rows).

width (W)

32u

Surface width (columns).

intensity length (iL) 32u Surface intensity length.
intensity width (iW) 32u Surface intensity width.

xScale

64f

X scale (mm).

yScale

64f

Y scale (mm).

zScale

64f

Z scale (mm).

xOffset

64f

X offset (mm).

yOffset

64f

Y offset (mm).

zOffset

64f

Z offset (mm).

surfaceId

32u

Surface Id of the message (used to identify messages with unchanged data)

The value is calculated based on the surface and intensity data, it's scale and offset values and the transform applied to it.

exposure

32f

Exposure in microseconds (us).

1.1.x.x The value of this field will be -1 if exposure is not available.

isAdjacent

8u


NOTE: This field is present ONLY for Surface Point Cloud. For Uniform Surface, this field is ABSENT.

Is the data Adjacent/Sorted (ie is it graphable)

0 = not adjacent.

1 = adjacent.

How a client should interpret this property:

  • isAdjacent means that points in neighbouring cells in the "ranges" array have edges connecting them.
  • Adjacency does not imply sorting. It's possible for points ABC to be adjacent (ie A adjacent to B, B adjacent to C, A is not adjacent to C), with a positional sort like ACB (eg A.x < C.x < B.x).
  • Adjacent data implies continuity between points - imagine a skin or surface which is stretched from point to point. Non-adjacent data does not have this implication.
  • The practical difference between adjacent and non-adjacent surface data is that adjacent data can be presented as a mesh with lines connecting the points, but non-adjacent data can only be presented as a point cloud.

Point Cloud Surface (Raw Surface)

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

surfaceAttrs

SurfaceAttrs

Surface Attribute Section (see above under Uniform Surface).

NOTE: the isAdjacent field in SurfaceAttrs applies to Surface Point Cloud and is therefore PRESENT in the SurfaceAttrs for Surface Point Cloud.

ranges[L][W]

Point3d16s

Surface ranges, sent as a tuple of 3 16-bit signed integer values.

Each 16-bit value should be scaled and offset with the respective values from SurfaceAtts. For example 

Point3d16s range =ranges[L][W];
float xPos = (range[0] * xScale) + xOffset;
float yPos = (range[1] * yScale) + yOffset;
float zPos = (range[2] * zScale) + zOffset;

Length (L) and Width (W) are from SurfaceAttrs.

intensities[iL][iW] 8u

Surface intensities.

Length (iL) and Width (iW) are from SurfaceAttrs.

Image

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)
imageAttrs

ImageAttrs

Image Attributes section (see below).

pixels[H][W]

(variable)

Array of image pixels, where the size of each pixel depends on the pixelSize attr.

Height, H, is from ImageAttrs.

Width, W, is from ImageAttrs.

ImageAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field

height (H)

32u

Image height, in pixels.

width (W)

32u

Image width, in pixels.

pixelSize

32u

Pixel size, in bytes.
In case of GenICam formats, pixelSize is set to 0 (see below).

pixelFormat

32s

[0x0000, 0x0FFF]: kPixelFormat

1 8-bit greyscale

2 8-bit color filter

3 8-bits-per-channel color (B, G, R, X)

4 1-bit greyscale, 8 packed pixels per image element

5 16-bit greyscale

6 8-bits-per-channel color with 3 channels (B, G, R)

[0x1000, 0x2FFF]: GenICam Formats

E.g.,
0x01080001 (Mono8)

0x01100003 (Mono10)

colorFilter

32s

Color filter array alignment:

0 None*

1 Bayer BG/GR

2 Bayer GB/RG

3 Bayer RG/GB

4 Bayer GR/BG

*In case of GenICam formats, colorFilter is set to 0 (see above).

reserved

16u

Reserved

exposure

32f

Exposure in microseconds (us).

1.1.x.x -1 if exposure is not available.

flippedX

8u

0 = Indicates whether the pixels should NOT be flipped horizontally.

1 = Indicates whether the pixels should be flipped horizontally.

flippedY

8u

0 = Indicates whether the pixels should NOT be flipped vertically.

1 = Indicates whether the pixels should be flipped vertically.

transposed

8u

0 = Indicates whether the pixels should NOT be transposed.

1 = Indicates whether the pixels should be transposed.

Note: transposed should always be applied after flippedX and flippedY.

Spots

Field

Type

Description

header

Header

Message header (see above)

commonAttrs CommonAttrs Common Attribute Section (see above)

spotAttrs

SpotAttrs

Spot Attribute Section (see below)

spots

Array of (C) Spot Objects described below

Pair of values (slice, center) to determine location of each spot depending on value of "columnBased" flag.

If columnBased flag is true (1) :

  • x position = slice * sliceScale + sliceOffset
  • y position = center * centerScale + centerOffset

If columnBased flag is false (0) :

  • x position =center * centerScale + centerOffset
  • y position =slice * sliceScale + sliceOffset

Spots may be flipped horizontally (FlippedX) or vertically (FlippedY) depending on whether the scale values (centerScale, sliceScale) are positive or negative. Negative scale values indicate the position of the spots are to be flipped horizontally (X) and/or vertically (Y) while positive scale values do not flip the spots.

For reference, the following illustrates the results of flipping the spots.

SpotAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

spotCount (C) 32u Number of spots
exposure

32f

Exposure in microseconds (us).

1.1.x.x -1 if exposure is not available.

columnBased 8u

Determines if the spots data is column-based or row-based.

0 = row-based slices,

1 = column-based slices

sliceScale 32f Scale applied to the slice value to obtain its pixel position from origin.
sliceOffset 32f Offset applied to the slice value to obtain its pixel position from origin.
centerScale 32f Scale applied to the center value to obtain its pixel position from origin.
centerOffset 32f Offset applied to the slice value to obtain its pixel position from origin.
maxSliceCount 32u

If row based, this value is the image height.

if column based, his value is the image width.

0.3.x.x Attribute added.

spotCenterMin 32u

Minimum allowable raw value of a spot's center.

This is not the minimum of the actual spot center values, it is the minimum allowable raw value for spots in this message. There may not actually be a spot with a center value equal to spotCenterMin.

0.3.x.x Attribute added.

spotCenterMax 32u

Maximum allowable raw value of a spot's center.

if row based, this value is typically the originating image width.

if column based, thisvalue is typically the originating image height.

This is not the maximum of the actual spot center values, it is themaximum allowable raw value for spots in this message. There may not actually be a spot with a center value equal to spotCenterMax.

0.3.x.x Attribute added.

Spot

Field

Type

Description

slice 16u Raw slice value of spot

center

32u

Raw center value of spot within a slice.

Mesh

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

meshAttrs

MeshAttrs

Mesh Attribute Section (see below)

channels[channelCount] MeshChannel

Array of mesh channel data.

Channel count (channelCount) is from MeshAttrs.

MeshAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field .

hasData

8u

0 = No data has been allocated

1 = data has been allocated

systemChannelCount 32u Number of system channels (currently 6)
maxUserChannelCount 32u Maximum number of user channels supported (currently 5)
userChannelCount 32u Number of currently active user channels
channelCount 32u Number of all channels, including all system and active user channels
offset Point3d64f Offset of mesh data
range Point3d64f Range of mesh data

MeshChannel

Field

Type

Description

meshChannelAttrs

MeshChannelAttrs

Mesh Channel Attribute Section (see below).

buffer[allocateCount]

various

Data buffer of various types depending on channel ID.

Channel ID.

  • 0 Point3d32f
  • 1 Facet3d32u
  • 2 Point3d32f
  • 3 Point3d32f
  • 4 8u
  • 5 32f
  • 6 or higher 8u. User is responsible to use channel type and/or channel flag to properly deserialize buffer into appropriate buffer item type.

Allocate Count (allocateCount) is from MeshChannelAttrs.

MeshChannelAttrs

Field

Type

Description

attributesSize

16u

Size of attributes, in bytes, including this field .

id

32u

Channel ID.

  • 0 Vertex channel
  • 1 Facet channel
  • 2 Facet normal channel
  • 3 Vertex normal channel
  • 4 Vertex texture channel
  • 5 Vertex curvature channel

type

32u

Channel type.

  • 0 Invalid type
  • 1 Vertex type
  • 2 Facet type
  • 3 Facet normal type
  • 4 Vertex normal type
  • 5 Vertex texture type
  • 6 Vertex curvature type

state

32s

Channel state.

  • -1 Error state
  • 0 Unallocated state
  • 1 Allocated state
  • 2 Empty state
  • 3 Partial used state
  • 4 Full state

flag

32u

Channel flag is an user specified field. It can be used to send any optional data to determine how to deserialize user channel data.

allocateCount

32u

Number of allocated channel data items.

System channels (channel id from 0 to 5) Equal to number of items ( ie, allocateCount for vertex channel is number of Point3d32f allocated).

User channels (channel id 6 or higher) Equal to number of bytes (8u) of entire buffer.

usedCount

32u

Number of used channel data items.

Measurement

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

value

64f

Measurement value.

decision

8u

Measurement decision.

0 = the measurement passed.

1 = the measurement failed because it is outside of the acceptable range.

Rendering (Graphics Message)

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)

renderingAttrs

RenderingAttrs

Rendering Attribute Section (see below)


0.3.x.x All counts of each graphic primitive were moved into this attribute section.
pointSets[pointSetCount] PointSet Array

List of PointSet primitive objects - described below.

Number of PointSet items is given by pointSetCount.

lineSets[lineSetCount] LineSet Array

List of LineSet primitive objects - described below.

Number of LineSet items is given by lineSetCount.

regions[regionCount] Region Array

List of Region primitive objects - described below.

Number of Region items is given by regionCount.

planes[planeCount] Plane Array

List of Plane primitive object- described below.

Number of Plane items is given by planeCount.

rays[rayCount] Ray Array

List of Ray primitive object - described below.

Number of Ray items is given by rayCount.

labels[labelCount] Label Array

List of Label primitive object - described below.

Number of Label items is given by labelCount.

positions[positionCount] Position Array

List of Position primitive object - described below.

Number of Position items is given by positionCount.

RenderingAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

pointSetCount 16u

0.3.x.x added number of point sets (PointSet) contained in the graphics object.

lineSetCount 16u

0.3.x.x addednumber of line sets (LineSet)contained in the graphics object.

regionCount 16u

0.3.x.x addednumber of regions (Region)contained in the graphics object.

planeCount 16u

0.3.x.x addednumber of planes (Plane)contained in the graphics object.

rayCount 16u

0.3.x.x addednumber of rays (Ray)contained in the graphics object.

labelCount 16u

0.3.x.x addednumber of labels (Label)contained in the graphics object.

positionCount 16u

0.3.x.x addednumber of positions (Position)contained in the graphics object.

PointSet

Field

Type

Description

pointSetAttrs PointSetAttrs PointSet Attributes section. See below.
points[C]

Point32f

Array of points where the count, C, is from PointSetAttrs "PointCount".

PointSetAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

size

32f

size of points in the point set.

color 32u

color of points in the point set (0xAARRGGBB) where:
AA - alpha value

RR - red value

GG - green value

BB - blue value

shape 32s shape of points in the point set
pointCount (C)

16u

number of points in the point set

Point32f

Field

Type

Description

x

32f

x coordinate of point.
y 32f y coordinate of point.
z 32f z coordinate of point.

LineSet

Field

Type

Description

linesetAttrs

LineSetAttrs

LineSet Attributes section. See below.

points[C]

Point32f

Array of points where the count, C, is from LineSetAttrs "lineSetPointCount".

LineSetAttrs

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

width

32f

Width of the lines in the line set.

color 32u

Color of the lines in the line set.

hasStartPointArrow 8u

whether each line of the line set should have start point arrow or not.

0 = does not have start point arrow.

1 = has start point arrow.

hasEndPointArrow 8u

whethereach line of the line set should have end point arrow or not.

0 = does not have end point arrow.

1 = has end point arrow arrow.

lineSetPointCount (C)

16u

number of points in the line set (every line in the set has a start point and an end point)

Region

A region can be one of the following type of regions:

  • Region2d
  • SurfaceRegion3d

Region2d

Field

Type

Description

type

8u

Type of region.

Value is always zero (0).

attributeSize

16u

Size of attributes, in bytes, including this field.

x

64f

X component of the center of the region.

z

64f

Z component of thecenter of the region.

width

64f

Width of the region along X axis.

height

64f

Height of the region along Z axis.

y angle

64f

Y angle rotation of the region.

SurfaceRegion3d

Field

Type

Description

type

8u

Type of region.

Value is always 1.

attributeSize

16u

Size of attributes, in bytes, including this field.

x

64f

Xcomponent of thecenter of the region.

y

64f

Ycomponent of the center of the region.

z

64f

Zcomponent of the center of the region.

width

64f

Width of the region along X axis.

length

64f

Length of the region along Y axis.

height

64f

Height of the region along Z axis.

z angle

64f

Z angle rotation of the region.

Plane

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

distance

32f

Distance from origin to the plane.

xNormal

32f

Xcomponent of the normal vector.

yNormal

32f

Ycomponent of the Normal vector.

zNormal

32f

Zcomponent of the normal vector.

Ray

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

xPosition

32f

xcomponent of the position.

yPosition

32f

ycomponent of the position.

zPosition

32f

zcomponent of the position.

xDirection

32f

x component of the direction.

yDirection

32f

ycomponent of the direction.

zDirection

32f

zcomponent of the direction.

width

32f

width of the ray.

color 32u

color of the ray.

Label

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

labelLength (L)

16u

Length of the label text.

label

char[L]

label text. Text has no null terminator.

x

64f

x positioncomponent of the label.

y

64f

y positioncomponent of the label.

z

64f

z positioncomponent of the label.

Position

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

x

64f

x component of the position of the label.

y

64f

y component of the position of the label.

z

64f

z componentof the position of the label.

type 8u

type of position

Can be one of :

  • 0 - No graphic position.
  • 1 - Graphic position X.
  • 2 - Graphic position Y.
  • 3 - Graphic position Z.

Point Feature

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)
xPoint

64f

Xcomponent of the position of the point.

yPoint

64f

Ycomponent of the position of the point.

zPoint

64f

Zcomponent of the position of the point.

Line Feature

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)
xPoint

64f

Xcomponent of the position of the point.

yPoint

64f

Ycomponent of the position of the point.

zPoint

64f

Zcomponent of the position of the point.

xDirection

64f

Xcomponent of direction vector.

yDirection

64f

Ycomponent of direction vector.

zDirection

64f

Zcomponent of direction vector.

Plane Feature

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)
xNormal

64f

Xcomponent of the normal vector.

yNormal

64f

Ycomponent of the normal vector.

zNormal

64f

Zcomponent of the normal vector.

originDistance

64f

Distance to origin.

Circle Feature

Field

Type

Description

header

Header

Message header (see above).

commonAttrs CommonAttrs Common Attribute Section (see above)
xPoint

64f

Xcomponent of the center point of the circle.

yPoint

64f

Ycomponent of the center point of the circle.

zPoint

64f

Zcomponent of the center point of the circle.

xNormal

64f

Xcomponent of normal vector of the plane the circle is lying in.

yNormal

64f

Ycomponent of normalvector of the plane the circle is lying in.

zNormal

64f

Zcomponent of normalvector of the plane the circle is lying in.

radius

64f

Radius of the circle.

Revison History




GoPxL: Common Types

This pages focuses on Data Types as described in the Back End, none of this information should be used by clients. For message serialization information, see Message Serialization Format

Data Types

The types here are used in a few places including the Message Serialization message header

Name Value Notes
Signal 1 Used to signal the GUI to clear the visualizer
Null 10 Null Message carrying a status message from tool developers
Stamp 11 Represents the stamp message, which contains the time and encoder values for the data the moment the data was collected. Stamps are always in "None" spaceType.
Uniform Profile 12 A uniform (aka "resampled) profile. Primary data structure is a 1-dimensional array of Z values. X values are implied by array index.Profiles are always in "Data" spaceType, and have XZ values with units of mm.
Profile Point Cloud 13 A non-uniform (aka "raw") profile.Primary data structure is a 2-dimensional array of XZ values.Profiles are always in "Data" spaceType, and have XZ values with units of mm.
Uniform Surface 14 A uniform (aka "resampled) surface. Primary data structure is a 2-dimensional array of Z values. X and Y values are implied by array indices. Surfaces are always in "Data" spaceType, and have XYZ values with units of mm.
Surface Point Cloud 15 A non-uniform (aka "raw") surface.Primary data structure is a 1-dimensional array of XYZ values.Surfaces are always in "Data" spaceType, and have XYZ values with units of mm.
Image 16 A 2-dimensional image object. Numerous pixel formats are supported. Images are always in "Image" spaceType, and have XY values with units of pixels.
Spots 17 A non-uniform (aka "raw") array of spots.Primary data structure is a 2-dimensional array of XY values.Spots are always in "Image" spaceType, and have XY values with units of pixels.
Mesh 18 A non-uniform (aka "raw") surface.Primary data structure is a 1-dimensional array of XYZ values (vertices), with additional information about vertex connections (edges). Meshes are always in "Data" spaceType, and have XYZ values with units of mm.
Measurement 19 A simple message, which contains a scalar value and a decision. Measurements can be in either "Data" or "Image" spaceType.
Rendering 70 A complex message, which represents graphics to be displayed for visualization. Primary data structure is an array of "graphics" objects, each representing a primitive drawing of some form.Graphics can be in either "Data" or "Image" spaceType, so their units could be mm or pixels, respectively.
Point Feature 71 A structure representing an XYZ point. Point Features can be in either "Data" or "Image" spaceType, so their units could be mm or pixels, respectively.
Line Feature 72 A structure representing a Line, consisting of a position and a direction along the line's axis. Line Features can be in either "Data" or "Image" spaceType, so their units could be mm or pixels, respectively.
Plane Feature 73 A structure representing a Plane, consisting of a position and a normal to the plane. Plane Features can be in either "Data" or "Image" spaceType, so their units could be mm or pixels, respectively.
Circle Feature 74 A structure representing a Circle, consisting of a position, a normal to the circle's plane, and a radius.Circle Features can be in either "Data" or "Image" spaceType, so their units could be mm or pixels, respectively.

Data Format

Item Type Schema Keywords Description
type integer readOnly
The type of data. See above Data Types
arrayed bool readOnly

Whether the data can be arrayed or not.

Status Codes

A common set of status codes is used throughout numerous protocols. These could be in response to API methods (ie read, update, delete, create, call), or they could be more application specific. Generally, statuses will be represented numerically, and any time programming flow needs to alter depending on statuses, numeric representation should be used. However, it's sometimes convenient to format statuses as a string, hence string forms are defined as well.

Name Numeric value String value Description
OK 1 "ok" Operation successful.
ERROR 0 "error" General error.
ERROR_STATE -1000 "state" Operation cannot be completed in the current state.
ERROR_NOT_FOUND -999 "notFound" Item was not found.
ERROR_COMMAND -998 "command" Command was not recognized.
ERROR_PARAMETER -997 "parameter" Parameter was not valid.
ERROR_UNIMPLEMENTED -996 "unimplemented" Feature is not implemented.
ERROR_MEMORY -994 "memory" Out of memory.
ERROR_TIMEOUT -993 "timeout" Action timed out.
ERROR_INCOMPLETE -992 "incomplete" Data incomplete (e.g., buffer insufficient for results).
ERROR_STREAM -991 "stream" Error in communication stream (e.g., network, file).
ERROR_CLOSED -990 "closed" Resource is no longer available.
ERROR_VERSION -989 "version" Incompatible version.
ERROR_ABORT -988 "abort" Operation aborted.
ERROR_ALREADY_EXISTS -987 "alreadyExists" Request conflicts with existing item.
ERROR_NETWORK -986 "network" Network setup/resource error.
ERROR_HEAP -985 "heap" Heap error (leak/double-free).
ERROR_FORMAT -984 "format" Data parsing/formatting error.
ERROR_READ_ONLY -983 "readOnly" Object is read-only (cannot be written).
ERROR_WRITE_ONLY -982 "writeOnly" Object is write-only (cannot be read).
ERROR_BUSY -981 "busy" Agent is busy (cannot service request).
ERROR_CONFLICT -980 "conflict" Current state has one or more configuration or resource conflicts.
ERROR_OS -979 "os" Generic error reported by underlying OS.
ERROR_DEVICE -978 "device" Hardware device error.
ERROR_FULL -977 "full" Resource is already fully utilized.
ERROR_IN_PROGRESS -976 "inProgress" Operation is in progress, but not yet complete.

More status codes may be added over time. Client applications can interpret any unknown negative status codes as ERROR.

ParamSet or "Group"

A general JSON representation of parameters. The parameters are provided by the application dynamically and varies from case to case.

A paramSet is an object container type used to store custom parameters for scanners, routines, tools, and many more things. ParamSets always have a Schema and clients are expected to use the schema for validation and annotation - paramSets form the foundation for which the client can generate a dynamic parameters list. ParamSets are used abundantly throughout GoPxL application and can consist of any number of data type objects listed in Schema and Data Types including primitive types, container types and extended types. ParamSet is an alias for the Group extendedType. A ParamSet is typically used as the top-level container group for parameters within the aforementioned classes.

Nesting - note that there are no explicit limits placed on the number of nested groups in the ParamSet. This may be an issue for some clients - for example, the GoPxL GUI client will only show 3 levels of nesting before additional nesting levels will be combined into a single level.

The "parameters" property shown below is an example of a paramSet for a simple tool: 

read /tools/SomeToolId

{  
  ...
  "_schema": {
    "properties": {
      ...
      "parameters": {
        "properties": {
		  "float": {
            "sortOrder": 2,
            "title": "Float",
            "type": "number"
          },
          "int": {
            "sortOrder": 0,
            "title": "Int",
            "type": "integer"
          },
          "changeInputFormat": {
            "sortOrder": 8,
            "title": "Change Input Format",
            "type": "boolean"
          },
        },
        "sortOrder": 0,
        "title": "",
        "type": "object"
      },
      ...
    },
    "type": "object"
  },
  ...
  "parameters": {
    "float": 3.14,
    "int": -100,
    "changeInputFormat": false,
  },
  ...
}

Some content has been removed from the response for brevity. In this case, the "parameters" property/field is the paramSet, and the associated schema applies.

Units

Units are available in multiple different places throughout the protocol. The most common location units exist is in Resource Schema , however units may be available in binary form as well. Where possible, string forms follow SI unit symbol form, however some provisions are made to keep unit string values shorter and easier to type (for example "m/s" instead of "m s -1 " or "C" instead of "C"). Also, some units are not defined by SI units, and so GoPxL defines it's own conventions (for example "ticks"). Some units string values contain non-ASCII characters (like "m"). In some areas of the protocol, units are provided as a string and it may be possible in those cases for the string to not match one of the listed items below. In this case, clients should treat this as "unitless", while still displaying the string unit value where appropriate. Unitless values have no intrinsic meaning - any meaning is therefore application-specific.

Name String value Numeric value
<unitless> "" 0
Length

meters "m" 3
millimeters "mm" 4
micrometers "m" 5
nanometers "nm" 6
yard "yd" 12
feet "ft" 13
inch "in" 14
thou "thou" 15
Area

square meters "m " 163
square millimeters "mm " 164
square micrometers "m " 165
square inch "in " 174
Volume

cubic meters "m " 183
cubic millimeters "mm " 184
cubic micrometers "m " 185
cubic inch "in " 194
Speed

meters per second "m/s" 23
millimeters per second "mm/s" 24
micrometers per second "m/s" 25
nanometers per second "nm/s" 26
yard per second "yd/s" 32
feet per second "ft/s" 33
inch per second "in/s" 34
thou per second "thou/s" 35
Time

years "y" 41
days "d" 42
hours "h" 43
minutes "min" 44
seconds "s" 45
milliseconds "ms" 46
microseconds "s" 47
nanoseconds "ns" 48
Counts

ticks "tick" 51
cycles "cycle" 52
Frequency

ticks per second "tick/s" 61
hertz (cycles per second) "Hz" 62
Angle

degrees "deg" 72
millidegree "mdeg" 73
Angular Speed

degrees per second "deg/s" 82
millidegrees per second "mdeg/s" 83
Magnitude

celcius "C" 91
fahrenheit "F" 92
voltage "V" 93
Rate of Change

celcius per second "C/s" 101
fahrenheit per second "F/s" 102
volts per second "V/s" 103
Byte

gigabytes "GB" 112
megabytes "MB" 113
kilobytes "kB" 114
bytes "B" 115
Byte Rate

gigabytes per second "GB/s" 122
megabytes per second "MB/s" 123
kilobytes per second "kB/s" 124
bytes per second "B/s" 125
Bit

gigabits "Gb" 132
megabits "Mb" 133
kilobits "kb" 134
bits "b" 135
Bit Rate

gigabits per second "Gb/s" 142
megabits per second "Mb/s" 143
kilobits per second "kb/s" 144
bits per second "b/s" 145
Graphics

pixels "px" 151
points "pts" 152
dots per inch "dpi" 153

Register Assembly Register Block Types

The Register Block types that may be used by a Register Assembly are listed below

1.1.x.x The measurement value only block is added and display name of measurement value and decision block is changed.

Block Type Default Display Name Internal Identifier
Control Input (for client to send commands to device) "Control Input" "ControlInput"
Control Output (for device to send back command status) "Control Output" "ControlOutput"
System (for system related information) "System State" "System"
Scanner (for sensor group related information) "Sensor Group State" "Scanner"
Stamp (for scan message stamp information) "Stamp" "Stamp"
Measurement (for scan measurement value and decision information) "Measurement and Decision" "Measurement"
Measurement (for scan measurement value only information) "Measurement" "MeasurementValue"

Extended Types

See Schema and Data Types

GoPxL: Documentation Conventions

Paths and Relative URIs

Every resource is identified by an URI relative to the "model root".

For example, a resource at "/scan/engines" may have a physical path of " http://192.168.1.10/api/scan/engines " on a RESTful server.

NOTE: URI implies a more formally structured and fully-specified definition of with distinct components, of which path is one of them:

(see https://datatracker.ietf.org/doc/html/rfc3986#section-3 )

Path Parameters

GoPxL implements scheme specific functionality for path parameters.

This is within the guidelines laid out in Uniform Resource Identifier (URI): Generic Syntax http://tools.ietf.org/html/rfc3986#section-3.3 .

When indicated in the REST API Reference (via parentheses), Gocator follows the "Simple String Expansion" as described in https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.2 and https://swagger.io/docs/specification/v3_0/serialization/#path-parameters .

Examples of the path parameter expansion of the basic URI template are as follows. The expansion of the "(id)" can be done as a primitive value id or by external id. In the primitive value id expansion, "TestForward-0" is substituted for the generic "(id)". In the external id expansion, an external id is specified using the syntax "extId=<external id value.". In the example, "(id)" is replaced with "My Tool" expressed as an external id "extdId=My%20Tool".

URI Template Primitive value id By external id
/tools/(id)

/tools/TestForward-0
/tools/TestForward-0/outputs/Output0

/tools/extId=My%20Tool
/tools/extId=My%20Tool/outputs/extId=My%20Output

When looking up by extIds, the extId parameter needs to be url-encoded according to https://datatracker.ietf.org/doc/html/rfc3986#section-2.1 . Typically this means percent-encoding spaces as "%20", but it also means that any of the URI reserved characters should also be percent encoded.

space ! # $ % & ' ( ) * + , / : ; = ? @ [ ]
%20 %21 %23 %24 %25 %26 %27 %28 %29 %2A %2B %2C %2F %3A %3B %3D %3F %40 %5B %5D

JSON Pointer

Throughout the Resource Reference , the properties of the respective resources are documented in table form. This is easy to read, but it presents some challenges when dealing with the typically nested and hierarchical nature of JSON documents. For this reason, JSON Pointer syntax ( rfc6901 ) is used as a convenient way of flattening documents for the purposes of documentation

Given a JSON document like this 

{
	"prop1": 42,
	"prop2": {
		"prop3": true
	},
	"prop4": [{
		"prop5": "inner"
	}]
}

You can expect to see a table documenting this document like this

Item Type Schema Description
prop1 number

Prop 1 Description

prop2 object

Prop 2 Description

prop2/prop3 boolean
Prop 3 Description
prop4 array

Prop 4 Description

prop4/n object
Prop 4 contents Description
prop4/n/prop5 string

Prop 5 Description

The "schema" column refers to the Schema Keywords you can expect to find for the given property (see next section).

This approach works well assuming that JSON arrays are homogenous and contain collections of like-types. As a general rule, in GoPxL API, the contents of JSON arrays are always homogenous. That is to say, their schema will always be of the same type and extendedType .

Schema Keywords

In general, a property may have any of the standard schema keywords defined in Schema and Data Types . For example, a client should in theory expect that any field may be "not used" (used = 0) and act accordingly.

However in practice only some of the properties will ever set "used" to 0. Throughout the Resource Reference , any "Schema" column lists the relevant keywords for each property, as a hint to aid in the implementation of any clients. It should be emphasized that this is only a hint, not an exhaustive reference. Well written clients are encouraged to support all documented schema keywords, and implement client-side "Assertions" or "Annotations" accordingly.

Resource Types and Traits

In a RESTful API model, patterns that occur across multiple resources and methods and are often re-used to encourage consistency and to reduce complexity. Such patterns can be referred to as Resource Types and Traits and aids in the discussion of Resources here.

Throughout the Resource Reference , links such as (Callable) indicate the applicability of the patterns associated with a certain resource type or trait.

Traits

WearsFlash


Certain resource methods inherently write to persistent storage. Consequently, regularly calling such methods on platforms where the persistent storage is backed by flash memory can lead to premature flash memory wear over time.
Please take this into consideration when working with the Gocator application, or when designing Gocator applicaiton clients, especially when running on embedded platforms.

For example many methods within the /jobs resource write to persistent storage.

NoRestart

Usually, when a resource modification occurs (update/create/delete/call), the system restarts (ie stops and starts) automatically if the system is running/started when the modification occurs. If this trait is not specified, it can be assumed that any update to the respective resource, while the system is running, will trigger a restart sequence.
There are, however, some resources where this does not apply such as reset, factory restore and sensor creation (buddying) as noted in the respective resource reference.

ExpandLevel Argument

In read methods, resources may return embedded resources that are partially represented, and can be expanded further using an argument.

Unless otherwise stated, ALL read methods within the Resource Reference support the expandLevel argument. For resources with no sub-resources, the expandLevel has no effect.

Item Type Description
expandLevel int

0, 1, 2.. n: Levels of sub resources to recursively expand.

-1: To expand all child resources.

Default Value: 0

Examples: 

read /tools {} { "expandLevel" : 2 }
read /tools {} { "expandLevel" : -1 }

IncludeSchema Argument

In read methods, schema information is made available automatically in the resource response. To turn this off, use the includeSchema argument by setting this argument to false.

Unless otherwise stated, ALL read methods within this Resource API supports the includeSchema argument.

Item Type Description
includeSchema bool

Whether to include schema information in the read response.

Default Value: true

Examples:

To disable sending back the schema for this read request. 

read /tools {} { "includeSchema" : false }

Fields Argument

In read methods, specific fields may be selectively requested instead of all properties. To selectively narrow down a read request, use the fields argument.

Unless otherwise stated, ALL read methods within the Resource Reference supports the fields argument.

Item Type Description
fields fields-array

Read only specific fields instead of all properties

Examples: 

read /tools {} { "fields" : {"displayName" : ""}}
read /tools {} { "fields" : {"id" : "", "displayName" : ""} }

Resource Types

Standard

Standard resources contain purely JSON properties and the typical read and update methods apply to be able to retrieve the current state and modify it. Not all properties are always modifiable, and readOnly state is documented in the _schema.

Standard Resources have a "_schema" keyword, which is documented more on the Schema and Data Types page.

Most resources fall into this type. Unless stated otherwise, resources should be assumed to be Standard.


Properties

Standard resource properties apply to both read and update methods. The structure of the read response and the update request should follow the documented property structure. Complex property structures are documented using JSON Pointer convention.

Example: The string property called "exampleProp" is a JSON pointer into the Standard Resource's JSON structure.

Item Type Schema Description
exampleProp string

Description of the property. The description includes the set of possible values if values are limited and pre-determined.


Methods

This lists the applicable REST methods for the resource. For example, if the resource supports both the READ and UPDATE methods, the methods would be documented as follows.

Method Description
read

Reads the resource. The response will contain properties documented above in the Properties section for the resource.

Examples: 

read /path/to/resource
update

Updates (modifies) the resource. The request should contain properties documented in the Properties section above for the resource.

Examples: 

update /path/to/resource { "exampleProp": value }

Non Standard

This resource type exists primarily to explicitly distinguish from Standard Resource types. Since Standard Resources are so prevalent in this API, the Standard Resource type is implied unless stated otherwise. The NonStandard Resource Type is used to explicitly document when a resource does not follow typical conventions.

Non Standard Resource payload/documents may be binary, strings, or any other JSON value type, as defined by "payload" in the Request Response Type Message .

No method support or behavior is implied for Non Standard Resources. Each supported method will be documented explicitly.

Callable

RESTful APIs are typically designed to facilitate mapping of methods to HTML primitives (ie. read to GET and update to POST). More involved, domain-specific operations however, may not easily fit into HTML patterns, so a callable Resource Type pattern is used to represent such custom operations.

A callable resource may have properties like a Standard resource. If it does, then the properties are documented in a Properties section just like Standard resources.

Methods

This lists the applicable REST methods for the resource. The CALL method must be supported because this is a Callable resource. Some Callable resources may also be read-able.

Method Description
read

Reads the schema of the callable resource, perhaps providing information about the arguments that the callable resource supports.

The output may also contain a list of supported operations that can be called.

Examples: 

read /my/path/commands/myCommand
call

Invokes the operation. Arguments may need to be provided depending on the resource.

Examples:

Invocation of a callable resource with no arguments: 

call /system/commands/start

Invocation of a callable resource with arguments: 

call /tools/commands/reorder { "tools": ["TestForward-2, TestForward-1, TestForward-0] }

Action

An action is a special form of a callable resource type. An action resource is always readable, and when read, there are certain properties that can be expected. The properties exposed on an action provide information to the client about the callable resource. This information is intended to allowed clients to dynamically query both the list of available actions (within an collection) as well as the arguments accepted for each.

By convention, actions are contained within a collection named "actions". For more information on working with action collections, and actions in general, see here: Resource Design and Request Methods#ActionlistsvsCommandlists

Properties

The following are the properties you can expect on the payload when reading an Action resource. Theseproperties are in addition to theproperties one would normally expect when reading a standard resource (ieproperties such as "_schema" and "_links")

Item Type Description
displayName localized string

The display name of the action.

message localized string

A message which explains the effect of calling the callable resource, useful for informing users of what to expect when the resource is called

parameters object

The arguments (and their types) that can be provided to that resource when it is called. The values of these parameters represent the default value of the arguments, which should be displayed to the user prior to calling the resource. Well-implemented clients should allow users to change these default values before invoking the action.

Methods

This lists the applicable REST methods for the resource. The CALL method must be supported because this is a Callable resource. Some Callable resources may also be read-able.

Method Description
read

Reads the schema of the action resource, including information about the resource itself.

Examples: 

read /my/path/actions/myAction

>> {
  "path" : "/my/path/actions/myAction",
  "payload": {
    "_links": {
      "self": {
        "href": "/my/path/actions/myAction"
      }
    },
    "_schema": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties":{
            "arg1": {
              "type": "number",
              "title": "Argument 1" //the label for arg1
            },
            "arg2": {
              "type: "string",
              "title": "Argument 2", //the label for arg2
              "description": "argument details here" //additional description information for arg2
            }
          }
        }
      }
    }
    "id": "myAction",
    "displayName": "My Action", //This action's displayName. Useful for defining menu titles, button text, or prompt/window titles
    "message": "This action will do great things. Make sure you save." //If defined, the client should present this message to users before the action is invoked
    "parameters": { //these represent the arguments this callable resource accepts
      "arg1": 10,  //in this example arg1 is a number and has a default value of 10
      "arg2": "current value"  //in this example arg2 is a string and has a default value of "current value"
    }
  },
  "status": 1,
  "type": "response"
}
call

Invokes the operation. Arguments may need to be provided depending on the resource.

Examples:

Invocation of an Action resource with no arguments: 

call /my/path/actions/myAction

Invocation of an Action resource with arguments: 

call /my/path/actions/myAction { "arg1":42, "arg2": "my user value" }

Observable

Observable resources offer the ability to asynchronously notify a client of events affecting the content and composition of resources.

Clients must subscribe to a resource to receive event notifications from the resource.The resource path to subscribe to can be specified with a special wild-cardable path-expression using the wild card character "*".

Unless otherwise stated, ALL resources within this Resource API are observable.. If a resource does not raise any event notifications however, the would be no point to subscribe to it however..

Resource Path-Expressions for subscription

Different ways of expression the subscribed resource is shown below:

Match Intent Description
Specific Resource

Match a specific resource at the given path.

Example: 

sub /tools/TestFoward-0
sub /tools/ProfileTool-1/inputs/Input0
Sub-Resources

Match any resource or sub-resource at the given path using a wild card "*".

Example: 

sub /tools/*
sub /scanners/*
Mix

Match either a specific or sub-resource, allowing for wildcarded sub-resources along the way.

Example:

Match specific resource, allowing for sub-resources along the way: 

sub /tools/Profile*/inputs/Input0


Match wildcard resources, allowing for sub-resources along the way: 

sub /tools/Profile*/inputs/*

Methods

Observable resources all support the following methods.

Method Description

sub path-expression


Subscribes to event notifications from the given path.

Examples:

Subscribe to event notifications from a single tool: 

sub /tools/TestForward-0

Subscribe to all tools within the tools collection (ie. /tools/(id)), as well as all inputs and outputs within each tool (ie. /tools/(id)/inputs, and /tools/(id)/outputs). 

sub /tools/*
unSub path-expression

Unsubscribes event notifications from the given path.

Examples: 

unSub /tools/TestForward-0
unSub /tools/*
listSub Lists all current subscriptions.
clearSub Clears all current subscriptions.


Subscriptions using path-expressions are multiple and explicit:

Multiple path-expressions can subscribed to, and each is explicit even if they overlap by nature of wildcarding.

Duplicate subscriptions are automatically ignored.

Method Sequence listSub Response

sub /tools/TestForward-0
sub /tools/*
listSub 

{ "subscriptions" : [
  "/tools/*",
  "/tools/TestForward-0"
]}

sub /tools/TestForward-0
sub /tools/TestForward-0 (duplicate request)
sub /tools/*
unsub /tools/*
listSub 

{ "subscriptions" : [
  "/tools/TestForward-0"
]}


Subscriptions using path-expressions are wholistic:

Even if multiple overlapping path-expressions are subscribed to, only one event notification will be send to the client's connection session.

For example, given a single event notification from the /tools/TestForward-0 resource, the following sets of subscriptions are equivalent and will result in one event notification sent to the subscribing client.

  • /tools/*

or

  • /tools/*
  • /tools/TestForward-0


Event Notifications Content

Resources that support event notifications will list the event notifications that they raise underneath a section called Notifications (see Notification Type Response Message ).

If the section is missing, it can be assumed that the particular resource DOES NOT raise any event notifications.

Collection

Collection resources often support the ability to:

  • read,
  • create new items,
  • generate notifications.

Collection resources all contain an embedded "item", which is the collection of the child items.

Note that child items may or may not share the same schema. For example, each tool within the /tools collection could hold a different schema from one another.

Unordered Collections

Unless explicitly indicated, collection resources are unordered, and may be returned in alphabetical order, or the order in which resources were added to the collection. This order should not be relied upon by clients.

Ordered Collections

If a collection is ordered, it will be indicated as:

Resource Type: (Collection - Ordered)

  • Ordered collections return an explicit zero-based "ordIndex" property when the resource is read.

  • Ordered collections often support ordering methods such as "Move" and "Reorder"


Methods

Collection resources commonly support the following methods:

Method Description
read

Returns an embedded "item", which is the collection of all the child items within the collection.

The embedded "item" property is omitted from the documentation, and can be assumed to exist for all collection resources.

Example: 

{
  "_links": {
    "self": {
      "href": "/tools"
    }
  },
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "/tools/id1"
          }
        },
        "ordIndex": 0
      },
      {
        "_links": {
          "self": {
            "href": "/tools/id2"
          }
        },
        "ordIndex": 1
      }
    ]
  }
}
create

Adds a new item to the collection. The arguments for adding items to the collection are resource-specific.

Example: 

create /tools {"type" : "TestForward" }

call

This method applies only to an Ordered Collection which has Callable resource characteristics. The operations supported are:

  • move
Sub-Resource Description
/commands/move

Provides ability to move an item to a specific position (zero-index-based).

Call arguments:

Item Type Description
id resource-specific

The id of one of the collection items to move.

Item name and type is resource-specific.

position signed integer The position to move the item to (zero-based index).

Example: 

call /tools/commands/move {"toolId" : "TestForward-0", "position": 2}
  • reorder
Sub-Resource Description
/commands/reorder

Provides ability to reorder multiple items within a collection

Call arguments:

Item Type Description
id array of collection item ids.

The id of an array of collection items ids, given in the desired order.

Collection item id name and type are resource specific.

Example: 

call /tools/commands/reorder { "tools" : [ "TestForward-2", "TestForward-1", "TestForward-0" ] }


Notifications

Event Type Description
updated

For an unordered collection, this is rarely raised, except if the collection supports operations that affect large sections of the collection, for example a clear all function. Unary additions and deletions to a collection are raised upon the collection item's resource and are sufficient for unordered collections.

For ordered collections, this event is raised whenever there are additions, deletions, or re-orderings of the collection since the "order" of the collection may have changed.


Examples:

Example output is abbreviated for clarity. 

{
  "eventType" : "updated", 
  "path" : "/tools", 
  "payload": {list of tools} 
}
{
  "eventType" : "updated", 
  "path" : "/jobs/files",
  "payload": {list of job files} 
}

Collection Item

Resources within a collection often support a method for deletion if the collection can be modified. Unless explicitly indicated, collection resources are unordered, and may be returned in alphabetical order, or the order in which resources were added to the collection. This order should not be relied upon by clients.


Methods

Method Description
read Reads a specific item within the collection.
delete Deletes a specific item from within the collection.


Notifications

Event Type
created

Occurs whenever an item is added to the collection which can happen indirectly via another request.

Example: 

{ "eventType" : "created", "path" : "/tools/TestForward-0",
  "content" : {new tool properties} }
deleted

Occurs whenever an item is removed from the collection.

Example: 

{ "eventType" : "deleted", "path" : "/tools/TestForward-0"}

Streamable

Streamable resources offer the ability to continuously deliver a "stream" of data to a client. The information may be:

  • continuous (such as data from a scanner, or statistics) ,
  • finite (large piece of information that is delivered in smaller several small pieces).

Methods

Streams must be initiated and canceled upon the client connection, and are resource specific:

Method Argument Description

stream


resource

Streams data from the given resource.

Examples:

Stream data from a scanner output or tool output: 

stream /dataSources/scan:test:0:Output/data
stream /dataSources/tools:ProfileInfo-0:outputs:PointCount/data

Stream metrics from a tool: 

stream /tools/extId=My%20Tool%20Id/metrics
cancelStream resource

Cancels streaming from the given resource. Use the same resource path as the one used for the stream request.

Examples: 

cancelStream /dataSources/scan:test:0:Output/data
cancelStream /dataSources/tools:ProfileInfo-0:outputs:PointCount/data
cancelStream /tools/extId=My%20Tool%20Id/metrics
listStream
Lists all current streams that have been request by the client


Stream Responses

See Stream Type Response Message .

Examples

Data received from a stream.

Data Received From A Stream 
{ "streamStatus": "streaming", 
  "streamId" : 1, 
  "path" : "/dataSources/scan:test:0:Output/data",
  "data" : {stream data} 
}

Indication that streaming has completed for a finite (non-continuous) stream.

Streaming Has Finished 
{ "streamStatus": "complete", 
  "streamId" : 1, 
  "path" : "/someFiniteStream/data" 
}

Indication that streaming terminated abnormally.

Streaming Terminated Abnormally 
{ "streamStatus": "abort", 
  "streamId" : 1, 
  "path" : "/tools/TestForward=0/metrics" 
}

GoPxL: Schema and Data Types

Overview

A client must know the "shape" of an object to be able to use it. The "shape" in this case refers to the structure of the object, the types of each of its members, and other meta data describing the object and its fields. Traditionally, the shape is defined as a part of the protocol. However there are times where a client must discover this shape at runtime, without prior knowledge.

Some notable examples that require this dynamic discovery:

  1. Client-Side validation: In some cases the client (eg the GUI) needs to know the validation data about a given property on a resource. Simple examples include min/max for numeric inputs, and options for enum/list inputs.
  2. Dynamic client generation: In some cases the GUI needs to dynamically generate its views based on the shape of the resources. This is the case for tools, where the tool developer specifies the parameters available for a given tool type, but the GUI does not know about this in advance.

The schema system allows the shape of an object to be expressed through a standardized format. It designed to be extensible so that meta data can be added over time without breaking compatibility. A client can simply choose to ignore meta data that it does not understand.

JSON Schema non-compliance

The design of GoPxL's JSON schema system is based on JSON Schema Draft 2019-09 . Many of the concepts and terminologies are borrowed from this spec, so as to minimize the possibility of confusion caused by inconsistency. Developers familiar with JSON schema should find themselves at home working with GoPxL's schema format. The approach is generally compliant with JSON Schema Validation standard , at which point many existing 3rd party tools and libraries may become usable.

GoPxL's implementation has the following non-inclusive set of limitations from the official JSON schema spec:

This list may change over time.

Additionally, GoPxL adds the following concepts and keywords

  • Base Type Custom Keywords:
    • extendedType
    • visibility
    • used
    • actual
    • unit
    • Number Type Custom Keywords:
    • scale
  • Base Type "type" Keyword: add support for "binary" type option

The custom keywords listed here are not prefixed with "x-" as has been recently recommended by maintainers of the JSON Schema standard. Custom keywords which are not prefixed with "x-" is now no longer supported by the latest JSON Schema standard. This is because JSON Schema standard changed throughout the development of GoPxL. In future versions of GoPxL REST API, these custom keywords are likely to change to include this "x-" prefix, to remain compliant with up-to-date standards. Such a change would constitute a breaking protocol change (and a Major digit increment to our protocol version, as per our Versioning and Compatibility guidelines)

Schema Document

The schema of a document can be optionally sent inline with the document, as a special "_schema" field. A protocol client must request the document when they Read a resource. A simple example of a resource response, when the schema has been requested is as follows:

Resource Example With Schema Document 
{
	source: 0,
	maxFrameRateEnabled: true,
	frameRate: 300,
	BurstScan: {
		enabled: true,
		count: 300
	},
    _schema: {
        type: object,
	    properties: {
		    source: {
			    type: integer,
    			enum: [0,1,2]
	    	}
			maxFrameRateEnabled: {
				type: boolean
			},
			frameRate: {
				type: number,
				used: true
			},
			// ...
		}
    }
}

It is also possible to read the document without the schema .

If the data described is an object or array, then each of its children also has a schema value. A schema value is always read-only, and is essentially a JSON object containing a set of properties. Within the context of a schema document, these properties are referred to as " keywords ".

A keyword falls into one or both of these categories:

  • assertions : Produce a boolean result when applied to an instance
  • annotations : Attaches additional information to an instance for application use

The list of acceptable keywords depends on the type of the data being described. Keywords that are not known to a client should simply be ignored.

The type of an object falls into one of two categories:

  • Primitive types: these are the native types supported by the JSON/Msgpack standard
  • Extended types: application-defined types that have special meaning. For example, a "TransformedBoxRegion" has type keyword = "object", but has special meaning to the application.

These types and extended types are described in more detail later.

Validation Logic

Validation is a process of checking a complete instance for assertions. Each assertion works independently of any other keyword and adds constraints that an instance must satisfy in order to successfully validate. Assertion keywords that are absent never result in more restrictive validation. In some cases, this no-op behavior is identical to a keyword that exists with certain values.

Validation assertions only constrain values within a certain primitive type. When the type of the instance is not of the type targeted by the keyword, the instance is considered to conform to the assertion. For example, the "maxLength" keyword will only restrict certain strings (that are too long) from being valid. If the instance is a number, boolean, null, array, or object, then it is valid against this assertion. However in practice, this is irrelevant because overloading a property with generally incompatible types should typically be avoided.

Keywords and Type Reference

Type Base

This is the base of all other data types. K eywords defined here are applicable to to all types.

Keyword Category Type Description
type Assertion string or array of strings

Enumerates the possible JSON types of the field. Available types are object, array, number, "integer", boolean, string, "binary", and null. An instance validates if and only if the instance is in any of the sets listed for this keyword.

Type can be an array of strings. For example["object"] or even["object,"string"]. However GoPxL's use of JSON schema makes very limited use of this capability. Arrays will only be used on one of the following 2 ways

  1. Array contains a single type of the above list (eg ["object"]). This has no effect - an array containing a single type can be treated as a single type
  2. Array contains a single type of the above list and null (eg["object", "null"]. This is used as a way of declaring whether an instance supports null or not (ie, is nullable).

Official JSON Schema spec does not support "binary", butGoPxL's spec does. This is becauseGoPxL's protocol supports both JSON and MsgPack resource serialization methods. For JSON-serialized resources,a schema document instance which is defined as type=binary implies that the instance is converted into a base64 encoded string.

GoPxL doesn't support the contentEncoding keyword, since its needs are met by the custom type=binary. For more information on the contentEncoding keyword, see here

extendedType Annotation string

Augments the type with a more specific type name, for clients that are able to use this information. Using the extendedType, assumptions can be made about the structure and meaning of a value. Note that the use of extendedType is optional; the schema should be fully intepretable even when the extendedType is ignored.

For example, a field with a type="object" and extendedType="ProfileRegion" can be treated as a generic object. However for clients that understand the extended type "ProfileRegion", it can choose to represent the value specifically as a "region" rather than a simple map of values. This permits a mechanism of type inheritance, but should be used carefully - we do not intend to capture the complete inheritance chain in the schema. For instance, consider if ProfileRegion extends from Region which extends from Object: in this case, extendedType=ProfileRegion and type=Object. The fact that ProfileRegion extends from Region is not represented in schema.

readOnly Both boolean

If "readOnly" has a value of boolean true, it indicates that the value of the instance is managed exclusively by GoPxL and not the client, and attempts by a client to modify the value of this property are expected to be ignored or rejected, at GoPxL's discretion.

This keyword can apply both to single-value instances (number, integer, boolean, string, binary, null) as well as multi-value instances (object, array). For multi-value instances, the entire instance is considered readOnly, including any children.

used

Annotation boolean

DEPRECATED

Indicates if a property is used or not. If this keyword is absent, the associated property is assumed to be used. An unused property is one where the associated feature is disabled and the current value has no effect on operation. When 'used' is false, the client should strive to remove all visual representation of the property from the display

1.1.x.x This keyword has been deprecated, it's functionality has been replaced by the "visibility" keyword with a "hidden" value.

actual Annotation (ValueType)

Sometimes the actual value of a property is overriden by a system-calculated one. For example, if a user specifies 100.0 for the "frameRate", but "enableMaxFrameRate" is enabled, the actual frame rate used is the system-calculated max, which might be something like 203.6 Hz. In this case, the property value is still 100.0, but it's "actual" schema value is 203.6.

title Annotation culture-specific string This keyword is used to decorate (typically graphically) a client interface with information about this instance. A title will preferably be short, and is often used as the "label" in dynamically generated forms.
unit Annotation string Specifies the unit of a value, e.g. "mm" or "s". Generally, values will follow the "string format" of one of the options defined here . However, in special cases, units may not match a predefined string format. Clients are advised to treat these as unitless values (no implied numerical meaning) while still displaying the string-form unit value to end users.
description Annotation culture-specific string This keyword is used to decorate (typically graphically) a client interface with information about this instance. A description could be long, as it is intended to provide an explanation about the purpose and correct use of the instance described by this schema.

Primitive Types

A primitive type is a simple value, described by a set of keywords. All primitive types use the keywords from the common base type, and may add their own.

Primative Type Schema Document Example 
// Data
"enableAutoSide": true

// Schema Document
"enableAutoSide": {
  "title": "Enable Auto Side",
  "type": "boolean",
  "unit": "",
  "readOnly": true,
  "used": true
}

boolean

A boolean has no additional keywords.

number

Keyword Category Type Description
minimum Assertion (ValueType) If the instance is a number, then and instance only validates against this keyword if the instance is greater than or exactly equal to this keyword's value.
maximum Assertion (ValueType) If the instance is a number, then this keyword validates only if the instance is less than or exactly equal to this keyword's value.
exclusiveMinimum Assertion (ValueType) If the instance is a number, then the instance is valid only if it has a value strictly greater than (not equal to) this keyword's value.
exclusiveMaximum Assertion (ValueType) If the instance is a number, then the instance is valid only if it has a value strictly less than (not equal to) this keyword's value.
multipleOf Assertion (ValueType) A numeric instance is valid only if division by this keyword's value results in an integer (possibly negative). Put another way, this is equal to saying propVal % keywordVal == 0
scale Annotation integer

Determines how the user should interpret a change in this number's magnitude. When this schema keyword is absent, it is expected that clients will assume the scale is linear.

Options are:

  • 1 = scaling is not applicable to the number.
    • When a number has no scale, clients can not represent the number along a path or slider bar.
  • 2 = linear scaling
    • When a number behaves linearly, the significance of a numeric difference is constant regardless of the number's magnitude.
  • 3 = logarithmic scaling
    • When a number behaves logarithmically, the significance of a numeric difference decreases as the numbers increase in magnitude. For example, decibels or camera exposure time.

integer

Same validation keywords as number .

string

Keyword

Category

Type

Description

minLength

Assertion

integer

A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.

The value of this keyword MUST be a non-negative integer.

maxLength

Assertion

integer

A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword.

The value of this keyword MUST be a non-negative integer.

format

Annotation

string

This keyword describes the format a string can take and will only be applied to string parameters. The list of formats follow the standard and can be found at the json schema standard

Some extra formats not described in the standard that we support include :

"code" and "code-python"

1.1.x.x Added.

binary

Keyword

Category

Type

Description

contentMediaType

Annotation

string

The contentMediaType keyword specifies the MIME type for the contents of binary data, as described in RFC 2046 . There is a list of MIME types officially registered by the IANA , but the set of types supported will be application and operating system dependent. Mozilla Developer Network also maintains a shorter list of MIME types that are important for the web.

Binary data is only natively supported when accessing resources by Message Pack format. When accessing resources with JSON serialization, binary properties are converted into strings following the format documented at the top of this page. The schema "type" of this string-converted binary data will still be "binary". In this way, contentMediaType provides information about binary data regardless of whether it is natively in binary format (message pack) or if it has been converted to a string (JSON).

1.2.x.x Added.

enums

Keyword

Category

Type

Description

enum

Both

(ValueType)

An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. Elements in the array might be of any value, including null.

enumText

Both

culture-specific string[]

Provides a text description for each of the values in "enum". It should have the same length as enum, and all items should be in the same order. The value of this string may change as the user selects a different system language, so clients should not depend on enumText value for runtime behavior.

Enum Schema Document Example 
"selectedSide": {
  "enum": [
    0,
    1,
    2
  ],
  "enumText": [
    "Left",
    "Right",
    "Auto"
  ],
  "title": "Selected Side",
  "type": "integer",
  "unit": "",
  "used": true,
  "visible": true
}

Container Types

object

An object contains child properties, which may be objects themselves.

Keyword Category Type Description
properties Assertion Schema

This keyword determines how child instances validate for objects, and does not directly validate the immediate instance itself. This is similar to the "items" keyword for arrays.

Validation succeeds if, for each name that appears in both the instance and as a name within this keyword's value, the child instance for that name successfully validates against the corresponding schema. Name's within this keyword's value which do not match to names in the instance are ignored.

required Assertion string[]

An object instance is valid against this keyword if every item in the array is the name of a property in the instance.

The value of this keyword MUST be an array. Elements of this array, if any, MUST be strings, and MUST be unique.

x-meta Annotation string Supported values are:

"groupState' which may be "open" or "closed". This represents the default open state of the property grid group. "groupState=closed" would indicate a group closed by default whereas "groupState=open" would indicate a group open by default.

An object can be decorated with an "extendedType", which means it follows a predefined shape. See "extendedType" in the Type Base section for more information. The actual extended types are described later.

An object is sometimes referred to as a "Property Group" or "Group". Later in this document, "Group" is defined in a bit more detail, with a specific example. However, it's worth reiterating that a Group is really just an object, from the perspective of the protocol and the schema system.

array

An array can contain either primitive items or objects (which may or may not have extended types).

Keyword Category Type Description
items Assertion Schema[]

This keyword determines how child instances validate for arrays, and does not directly validate the immediate instance itself. This is similar to the "properties" keyword for objects.

If "items" is a schema, validation succeeds if all elements in the array successfully validate against that schema.

If "items" is an array of schemas, validation succeeds if each element of the instance validates against the schema at the same position, if any.

The current GoPxL GUI implementation assumes there is only ever a single schema for arrays of value types (ienumber, "integer", boolean, string, "binary", and null). In practice, this assumption is always true.
minItems Assertion integer

An array instance is valid against "minItems" if its size is greater than, or equal to, the value of this keyword.

The value of this keyword MUST be a non-negative integer.

maxItems Assertion integer

An array instance is valid against "maxItems" if its size is less than, or equal to, the value of this keyword.

The value of this keyword MUST be a non-negative integer.

x-meta Annotation string Supported values are:

"groupState' which may be "open" or "closed". This represents the default open state of the property grid group. "groupState=closed" would indicate a group closed by default whereas "groupState=open" would indicate a group open by default.

"renderInRow" which renders property grid actions in a row. "renderInRow=true" represents a row whereas "renderInRow=false" represents a column. False is the default.
Value Array Schema Document Example 
// Data
"intArray": [
  1,
  2,
  3
]

// Schema
"intArray": {
  "items": {
    "type": "integer"
  },
  "title": "Int Array",
  "type": "array",
  "unit": "",
  "used": true,
  "visible": true
}
Object Array Schema Document Example 
// Data
"regions": [
  {
    "height": 0.0,
    "width": 0.0,
    "x": 1000.0,
    "z": 0.0
  },
  {
    "height": 0.0,
    "width": 0.0,
    "x": 1000.1,
    "z": 0.0
  },
  {
    "height": 0.0,
    "width": 0.0,
    "x": 1000.2,
    "z": 0.0
  }
]

// Schema
"regions": {
  "items": [
    {
      "extendedType": "",
      "properties": {
        "width": {
          "type": "number",
        },
        "height": {
          "type": "number",
        },
        "x": {
          "type": "number",
        },
        "y": {
          "type": "number",
        },
		"zAngle": {
		  "type": "number",
		}
      },
      "title": "",
      "type": "object",
      "visible": true
    },
    {
    // ...
    },
    {
    // ...
    }
  ],
  "type": "array"
}

Extended Types

Extended types typically contain no extra keywords, and are defined by the set of contained fields. They typically expand upon type=objectbut not always (for example, "Transform3d" extends a type=array). Every extended type has a unique extendedType keyword so they can be specially handled beyond the regular types.

Extended Type Schema Document Examples 
// Schema document for an extended object
{
  "type": "object",
  "extendedType": "MyExtendedObjectType",
  "properties": {
    "propA": {
      "type": "number"
    },
  },
  "title": "My Extended Object Type"
}

// Schema document for an extended array of a value type (number)
{
  "type": "array",
  "extendedType": "MyExtendedArrayType",
  "items": {
    "type": "number"
  },
  "title": "My Extended Array Type"
}

// Schema document for an extended string array
{
  "type": "string",
  "extendedType": "MyExtendedStringType",
  "title": "My Extended String Type"
}

Transform3d

Base type : "array"

Extended type: "Transform3d"

A 16 element array representing a 4 x 4 3D affine transformation matrix as shown below. If the transform is invalid, the array will be empty (ie it will have count=0 and have no elements in it).

This transform is primarily intended for transforming anchored regions by supporting translation and rotation only. Use of this transform for scaling and skewing regions is neither recommended nor supported. 

[xx, xy, xz, xt,
 yx, yy, yz, yt,
 zx, zy, zz, zt,
  0, 0, 0, 1]


Index Type Description
0 number xx component of the 3D transformation matrix
1 number xy component of the 3D transformation matrix
2 number xz component of the 3D transformation matrix
3 number xt component of the 3D transformation matrix
4 number yx component of the 3D transformation matrix
5 number yy component of the 3D transformation matrix
6 number yz component of the 3D transformation matrix
7 number yt component of the 3D transformation matrix
8 number zx component of the 3D transformation matrix
9 number zy component of the 3D transformation matrix
10 number zz component of the 3D transformation matrix
11 number zt component of the 3D transformation matrix
12 number 0
13 number 0
14 number 0
15 number 1


Transform3d Schema Document Example 
{
  "type": "array",
  "extendedType": "Transform3d",
  "items": {
    "type": "number"
  },
  "title": "Transform Matrix",
  ...
}

Current inheritance diagram of region params.

There are a bunch of other extendedTypes that are derived from BoxRegion such as ProfileRegion and SurfaceRegion2d but these are just the BoxRegion with defaults for optional params set differently.

BaseBoxRegion

Base type: " object"

Extended type: "BaseBoxRegion"

Base box region containing the common parameters of a 3d region and is fully customizable for the user.

Field Type (ext type) Description
x number Optional . The x coordinate of the region center.
y number Optional . The y coordinate of the region center.
z number Optional . The z coordinate of the region center.
width number Optional . The width of the region.
length number Optional . The length of the region.
height number Optional . The height of the region.
xAngle number Optional . Angle of rotation around the x axis.
yAngle number Optional . Angle of rotation around the y axis.
zAngle number Optional . Angle of rotation around the z axis.

BoxRegion

Base type: " object"

Derives from: "BaseBoxRegion"

Extended type: "TransformedBoxRegion"

BoxRegion that is the most common uses of these fields and registers, sorts and labels them. Contains all the fields from BaseBoxRegion.

TransformedBoxRegion

Base type: " object"

Derives from: " BoxRegion"

Extended type: "TransformedBoxRegion"

Field Type (ext type) Description
x number Optional . The x coordinate of the region center.
y number Optional . The y coordinate of the region center.
z number Optional . The z coordinate of the region center.
width number Optional . The width of the region (x).
length number Optional . The length of the region (y).
height number Optional . The height of the region (z).
xAngle number Optional . Angle of rotation around the x axis.
yAngle number Optional . Angle of rotation around the y axis.
zAngle number Optional . Angle of rotation around the z axis.
transformMatrix

array

(Transform3d)

Optional . Transform3d array which defines the transform that applies to the region. If this field is missing, clients should assume the region is not transformed. This is effectively the same as having an identity matrix.

Optional - any of these fields may or may not be present for this extendedType. Clients must handle the case where any or all of these fields may not exist.

TransformBoxRegion Schema Document Example 
{
  "type": "object",
  "extendedType": "TransformedBoxRegion",
  "title": "My Region",
  "properties": {
    "height": {
      "sortOrder": 5,
      "title": "Height (Z)",
      "type": "number"
    },
    "transformMatrix": {
      "items": {
        "type": "number"
      },
      "readOnly": true,
      "sortOrder": 9,
      "title": "Transform Matrix",
      "type": "array",
	  "extendedType": "Transform3d"
    },
    "width": {
      "sortOrder": 3,
      "title": "Width (X)",
      "type": "number"
    },
    "x": {
      "sortOrder": 0,
      "title": "X",
      "type": "number"
    },
    "yAngle": {
      "sortOrder": 7,
      "title": "Y Angle",
      "type": "number",
      "used": false
    },
    "z": {
      "sortOrder": 2,
      "title": "Z",
      "type": "number"
    }
  },
  ...
}

ScanMode

Base type : "enum"

Extended type: "ScanMode"

A value representing different scan modes:

Added in 1.1.x.x

ScanModeType Description
0 Image scan mode.
1 Range scan mode.
2 Profile scan mode.
3 Surface scan mode. 
"scanMode": {
  "enum": [
     2,
     3
   ],
   "enumText": [
     "Profile",
     "Surface"
   ],
   "extendedType": "ScanMode",
   "sortOrder": 100,
   "title": "Scan Mode",
   "type": "integer"
 }

CodeArea

Base Type : " object"

Extended type : " CodeArea"

A group representing an area of code

Added in 1.1.x.x

Field Type Description
code string String containing the code.
errors array Array of error objects.
errors/n/ object An error object.
errors/n/message string The error message.
errors/n/severity string

The error severity. Will be one of either: "error", "warning", "info"

errors/n/line integer Optional. The line number where the error occurs.
errors/n/start integer Optional. The start character position in the code where the error occurs.
errors/n/end integer Optional. The end character position in the code where the error occurs. End is exclusive, meaning the character at the location indicated by end is not considered part of the error.

Example Data 

{
  "code": "This is my code string",
  "errors": [
	{
	  "message": "an error string",
	  "severity": "error",
	  "line": 100,
	  "start: 1000,
	  "end": 1020
	}
  ]
}

Schema 

{
  "type": "object",
  "extendedType": "CodeArea",
  "properties": {
    "code": {
      "format": "code-python",
      "title": "code",
      "type": "string"
    },
    "errors": {
      "items": {
        "type": "object"
      },
      "title": "errors",
      "type": "array"
    }
  }
}

Anchor

Base type : " object"

Extended type : " Anchor"

A group representing an anchor.

This extendedType represents URI relative reference to a callable resource.

In the future, we may add other anchorTypes, such as file (which would link to a file resource and trigger a download in the browser) or external (which would link to some HTTP(S) page outside of the GoPxL GUI, and would be opened in a new browser tab). Each of these other anchor types would have slightly different look and feel in the GUI, and would be handled in a unique way.

Added in 1.2.x.x

Field Type Description
anchorType string

Type of the anchor.

Currently is just "callable" but as noted above we may add other anchor types.

url string URL of the callable resource to invoke.
text string Display text of the button.
icon string Icon to display for the button. Icon is not a URL, but rather a special icon id which indicates to the client which icon to display .

Example Data 

 
 
 
  Schema  
 
 
 
// Schema
{
  "type": "object",
  "properties":
  {
   	"myActionButton": 
	{
      "type": "object",
	  "readOnly": true,
      "extendedType": "Anchor",
      "title": "Button label", //optional
      "description": "My button tooltip"
    }
  }
}
 
 
 
 File 
 
  Base type : "  object" 
 
  Extended type : "  File" 
 
 A group representing binary data. Encapsulates binary data for tool action file transfers.  Actions with upload/download functionality can provide File objects as action parameters to facilitate the transfer process.  
 
   Added in       1.2.x.x     
 
 
       
   Field    Type   Description  
 
  filename   string   
  Optional.  Filename for the binary data. Filenames can be omitted for the actions associated with download functionality. 
 		 
 
  extensions   array of strings   
 
  Optional.  Contains a list of the allowable file type extensions to p  rovide a   hint of types that are supported by the action. For example, t  his can be used in a file picker dialog to suggest/filter for specific file types.   
 
   
 
 The  convention to specify a wildcard file extension (  any file type is accepted) is  to provide an empty extensions array.  
 
 
 
 		 
 
  data   binary   The binary data (stored as an array of unsigned chars).  
  
 
 
 
  Schema  
 
 
// Schema
{
	"type": "object",
	"extendedType": "File",
	"properties":{
		"filename":{
			"type": "string"
		}, 
		"extensions":{
			"type": "array",
			"items": {"type": "string"} 
		}, 
		"data":{
			"type: "binary"
		}
	}
}

 
 
 
 The following examples demonstrates how a tool can use the File extended type to support binary upload and downloads: 
 
 
  UploadExample  
 
 
// Request
{
  "path" : "/path/to/upload",
  "method": "call",
  "payload": {filename:"myFile.ext", extensions:[".ext",".bin"], data:[0,1,2,3,4,5,6,7,8,9]},
}

// Response
{
  "path" : "/path/to/upload",
  "payload": {
    "message": "Upload action was executed successfully. Bytes received: xxx"
  },
  "status": 1,
  "type": "response"
}


 
 
 
 
  Download Example  
 
 
// Request
{
  "path" : "/path/to/download",
  "method": "call"
}

// Response
{
  "path": "/path/to/download",
  "payload": {
    "data": [0,1,2,3,4,5,6,7,8,9],
    "extensions": [
      ".ext",
      ".bin"
    ],
    "filename": "myFile.ext"
  },
  "status": 1,
  "type": "response"
}


 
 
 
 Image 
 
  Base type : "  object" 
 
  Extended type : "  Image" 
 
 A group representing image data. Encapsulates image data forJSON and Property Grid components (including in table columns). 
 
  Added in      1.2.x.x     
 
 
       
   Field    Type   Description  
 
  data   binary   The image data (stored as an array of unsigned chars).  
 
  displayWidth   integer   
  Optional.  Suggested image display width. This field may not be present, in which case the image's native width will be used. 
 		 
 
  displayHeight   integer    Optional.  Suggested image display height. This field may not be present, in which case the image's native height will be used.  
  
 
 
 
  Schema  
 
 
// Schema
{
	"type": "object",
	"properties": {
		"myImage": {
			"readOnly": true,
			"title": "Sample PNG image",
			"type": "object",
			"properties": {
				"data": {
					"contentMediaType": "image/png",
					"type": "binary",
					"title": "data"
				},
				"displayHeight": {
					"title": "displayHeight",
					"type": "integer"
				},
				"displayWidth": {
					"title": "displayWidth",
					"type": "integer"
				}
			}
		}
	}
}

// Data
{
    "myImage": {
        "data": [binary data] ,
        "displayWidth" : 48,
        "displayHeight" : 64 
    }
}
 
 
 
 TabularCollection 
 
  Base type :  "object" 
 
  Extended type : "  TabularCollection" 
 
 A group representing a table. 
 
   Added in       1.2.x.x     
 
 
       
   Field    Type   Description  
 
  activeRow   integer   
 Defines the active row to display the data from 
 
 -1 denotes that the activeRow is none. 
 		 
 
  actions   array   Array of Anchors for the entire table  
 
  actions/n   Anchor   A table Anchor. Table Anchors will always beanchorType=Callable.  
 
  data   array   
 Array of data objects. 
 
 Below is a list of properties that are common to all data objects, however objects can contain more params. 
 
 All rows of data will have the same properties. The schema for these properties, such as "Title" determines the header row for the table. 
 		 
 
  data/n/   object   A data object in the table  
 
  data/n/isSelected   bool   Optional common parameter that indicates whether an object in the array is selected or not.  
 
  data/n/actions   array   
 Array of Anchors for the data object. 
 		 
 
  data/n/actions/m   Anchor   A data Anchor. Data Anchors will always beanchorType=Callable.  
  
 
 
  Example Data  
 
 
 
//data
{
  actions: [
    {
      anchorType: "callable",
      url: "/routines/routineId/actions/save",
      icon: "save"
    },{
      anchorType: "callable",
      url: "/routines/routineId/actions/deleteSelected",
      icon: "delete"
    }
  ],
  activeRow: 0,
  data: [
    {
      isSelected: false,
      actions: [
        {
          anchorType: "callable",
          url: "/routines/routineId/actions/deleteRow?index=0", //note the predetermined value here
          icon: "delete"
        }
      ]
    },{
      isSelected: false,
      actions: [
        {
          anchorType: "callable",
          url: "/routines/routineId/actions/deleteRow?index=1", //note the predetermined value here
          icon: "delete"
        }
      ]
    }
  ]
}


 
 
 
  Schema  
 
 
 
{
  "type": "object",
  "extendedType": "TabularCollection",
  "properties": {
    "actions": [
      {
		"items" [
		  {
        	"type": "object",
	    	"readOnly": true,
        	"extendedType": "Anchor",
        	"title": "Save", //optional
        	"description": "My button tooltip"
      	  },{
        	"type": "object",
	    	"readOnly": true,
        	"extendedType": "Anchor",
        	"title": "Delete Selected", //optional
        	"description": "My button tooltip"
      	  }
		]
	}
    "activeRow": {
	  "title": "activeRow",
	  "type": "integer"
	}
    "data": {
	  "items": [
		{
		  "properties": {
      		"actions": [
      		{
			  "items" [
		  	    {
        		  "type": "object",
	    		  "readOnly": true,
        		  "extendedType": "Anchor",
        		  "title": "Save", //optional
        		  "description": "My button tooltip"
      	  	    },{
        		  "type": "object",
	    		  "readOnly": true,
        		  "extendedType": "Anchor",
        		  "title": "Delete Selected", //optional
        		  "description": "My button tooltip"
      	  	    }
			  ]
			}
		  ]
		  "isSelected":{
		    "title": "isSelected",
			"type": boolean
		  }
		}
      },
	  {
		"properties": {
      		"actions": [
      		{
			  "items" [
		  	    {
        		  "type": "object",
	    		  "readOnly": true,
        		  "extendedType": "Anchor",
        		  "title": "Save", //optional
        		  "description": "My button tooltip"
      	  	    },{
        		  "type": "object",
	    		  "readOnly": true,
        		  "extendedType": "Anchor",
        		  "title": "Delete Selected", //optional
        		  "description": "My button tooltip"
      	  	    }
			  ]
			}
		  ]
		  "isSelected":{
		    "title": "isSelected",
			"type": boolean
		  }
		}
	  }
	]
  }
}
 
 
 
   
 
 
 
 
 
 
 
  
 
 
 
 
  GoPxL: GoPxL Discovery Protocol  
 
 
 
 
   The term "client" refers to the station issuing the request, wishing to discover available GoPxL application servers on the network. For example, the LMI SDK is an example of a discovery protocol client.   The term "server" refers to the station issuing the response, in this case this is the GoPxL application, running on a sensor, a GoMax, or on a Windows/Linux computer/platform.  
 
  The protocol uses UDP.   GoPxL discovery server listens for any client requests on UDP destination (dst) port = 3320 (by default). The client may choose any source (src) port it wishes to send the request from.   GoPxL discovery server may emit it's own messages, also with dst port = 3320. This is illustrated as such:  
 
   
 
 
 
  
 
 
 
  This means that clients will "see" other client requests. This is intended by the protocol design, and clients should use message id's to ignore other client requests (see below).  
 
 Discover Message 
 
 The discovery client broadcasts the following  message to any network it wishes to discover GoPxL servers:  
 
   Broadcast Message 
   
 
 
              
  
   Field   
 		  
   Type   
 		  
   Offset   
 		  
   Description   
 		 
 
  
  Length  
 		  unsigned int64   
  0  
 		  
  24  
 		 
 
  
  Message Id  
 		  
  unsigned int64  
 		  
  8  
 		  
  0x0001  
 		 
 
  
  Signature  
 		  
  unsigned int64  
 		  
  16  
 		  
  0x4C58504F47494D4C // "LMIGOPXL"  
 		 
  
 
 
  Typically, clients will iterate over every interface and issue the above network-directed broadcast appropriately on each interface.  
 
  A wireshark trace of the Discover Message is shown below where the client sending the message is running on a Windows PC (Intel processor) and the server is running on the physical sensor.  
 
     
 
  Announce Message 
  
 
  The application discovery server on the sensor/GoMax/PC GoPxL application typically responds to a discover message    with the following announce message to the clients.  Clients should not treat the announce message as a "reply", as any other client may have issued a discover message as well. Announcements can happen at any time - in the future, the application could even be configured to announce periodically based on a timer, without the need for discover messages:  
 
   Reply Message 
   
 
 
              
  
   Field   
 		  
   Type   
 		  
   Offset   
 		  
   Description   
 		 
 
  
  Length  
 		  unsigned int64   
  0  
 		  32 + payload length  
 
  
  Message Id  
 		  
  unsigned int64  
 		  
  8  
 		  
  0x1001  
 		 
 
  
  Signature  
 		  
  unsigned int64  
 		  
  16  
 		  
  0x4C58504F47494D4C // "LMIGOPXL"  
 		 
 
  MsgStatus     See Common Types -> Status Codes     24   
 Status of the message, the values used: 
 
 
  
  Value   Description  
 
  1   Operation successful.  
 
  -992   Data incomplete.  
  
 
 		 
 
  Message Payload   string   32   JSON String  
  
 
 
 The message payload is coded in JSON, which containsstring key - value pairs. The message contains only the  key - value pairs that are valid for the message.  
 
 The possible keys are: 
 
 
       
  Key Name   Type   Description  
 
  SerialNumber   string    If discovered GoPxL is running on LMI device, this is the device serial number   
 
  DeviceModel   string   If discovered GoPxL is running on LMI device, this is the device model number  
 
  AppName   string   Name of the application instance. Empty when device is remoted.  
 
  AppId   string   Unique ID of the application instance. AppId of the remote controller when device is remoted.  
 
  AppVersion   string   Version of the application instance  
 
  ControlPort    number     Raw socket REST API port. Typically 3600 but can vary to avoid port conflicts. 0 when device is remoted.   
 
  WebPort   number   HTTP server port, typically 80 but can vary to avoid port conflicts. This port is used both for browsers to retrieve the Web GUI, but also for WebSocket connections to the REST API (at path /ws/controlAsync). 0 when device is remoted.  
 
  GdpPort   number   Gocator Data Protocol port. T  ypically3601 but can vary to avoid port conflicts. 0 when device is remoted. 
  		 
 
  IsRemote   boolean   True if LMI device is remotely connected/controlled from another GoPxL instance. Remote sensors should generally not to be connected to via the control API. This includes websocket connections on path /ws/controlAsync, as well as raw socket connections on ControlPort.  
 
  Address   string   Configured host address. When GoPxL is running on PC, this could be the address of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).  
 
  Mask   string   Configured host subnet mask. When GoPxL is running on PC, this could be the subnet mask of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).  
 
  Gateway   string   Configured host gateway. When GoPxL is running on PC, this could be the gateway of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).  
 
  Dhcp   boolean   True if DHCP is enabled. When GoPxL is running on PC, this could be the DHCP state of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).  
 
  AddressConflict   boolean   The IP address may have been automatically assigned due to an address conflict.  
  
 
 
  An example of the reply message payload from the sensor:  
 
 
 
'{"SerialNumber":"DeviceModel","45045":"2330"}'
 
 
 
 The client, upon receiving the reply, verifies the header fields (Length, Message Id and Signature). Then the remaining bytes in the stream of bytes starting at location for Message Payload is to be treated as a string, and parsed using a JSON parser. 
 
  Connection Details of GoPxl Discovery Server and Client  
 
 
 
 
 When both the server and client are on the same subnet, the discovery client can detect the GoPxl application, and the application can successfully connect. 
 
     
 
 
 
  
 
 
 
 
 
 
 When the server and client are on different subnets, the discovery client can detect the GoPxl application, but the application cannot connect. 
 
         
 
 
 
  
 
 
 
  SetIp  Message 
 
 The discovery client can send the SetIp message to the server using a direct address. If the server is out of reach e.g. after the factory default, the message can be sent also using broadcasting. 
 
 The discovery client sends the following message to the GoPxL server to set a new IP address to the device: 
 
   Message 
   
 
 
              
  
   Field   
 		  
   Type   
 		  
   Offset   
 		  
   Description   
 		 
 
  
  Length  
 		  unsigned int64   
  0  
 		  
  24 + payload length  
 		 
 
  
  Message Id  
 		  
  unsigned int64  
 		  
  8  
 		  
  0x0003  
 		 
 
  
  Signature  
 		  
  unsigned int64  
 		  
  16  
 		  
  0x4C58504F47494D4C // "LMIGOPXL"  
 		 
 
  Message Payload   string   24   JSON String  
  
 
 
 The message payload is coded in JSON, which containsstring key - value pairs. The possible keys are: 
 
 
       
  Key Name   Type   Description  
 
  AppId   string   Unique ID of the application instance. Mandatory.  
  
 
 
 There is no response message sent for this request, as typically devices reboot immediately upon changing their IP address. Clients are required to do a new discover message after the SetIp request to update their statuses. 
 
 
 
 
 
  
 
 
 
 
  GoPxL: Notification and Streaming  
 
 
 
 
   
 
  
 
 
 
 A common problem in a resource-based API is providing clients with timely updates when resources change. There are two possible solutions to notify clients of resource state changes 
 
     
  1.  Change feedback: list changes in the response to method invocations. 
    2.  
  2.  Change notification: implement a "notification" channel, which informs the client asynchronously about any state change 
       
    1.  From  1.1.x.x  , the notification message "payload" field no longer contain information about what resources have changed. Only the "path" variable shows the resource that generated the notification. The client should re-read the resource(s) it is interested in that may be affected by the resource change in the resource indicated in the "path" field. 
      2.  
     
    3.  
 
 The GoPxL Control protocol implements both approaches. Feedback is implemented so that clients can synchronously process side effects from method invocations. Notifications are also implemented so that a client can respond to changes due to another client acting on the same sensor. 
 
 A related feature is "streaming" content from a resource. This is closely related to asynchronous notification, and will also be discussed. 
 
 Change Feedback To Clients 
 
 Any method invocation aside from READ can have side effects. These are: 
 
     
  •  CREATE 
    •  
  •  DELETE 
    •  
  •  UPDATE 
    •  
  •  CALL 
    •  
 
 The response to each of these methods contains a list of changes. Each change in this case is a simply an URI to the resource that has changed, and the client is expected to make a separate query if they are interested in the new state. Example: 
 
 
 
UPDATE: tools/0/outputs/1, {"enabled": false}
>> {"status": 1, "changes": ["dataOutputs"]}
 
 
 
 A change notification is always emitted for the  most specific resource  , and not its parent resources. For collection resources, e.g. /tools, a change is defined to be the addition or removal of items. 
 
 The resource being modified may also appear in the change list, to indicate that the client should read it again, because fields other than those directly modified have also changed. To simplify implementation, a resource can always dispatch a change event whenever any property has changed; there's usually no need to explicitly check if other properties has changed, since this is likely complicated, and in most cases there are other affected properties. 
 
  Example  
 
 Consider a system with the following resources: 
 
     
  •  /tools 
    •  
  •  /tools/0 
    •  
  •  /tools/0/inputs/0 
    •  
  •  /tools/0/outputs/0 
    •  
  •  /tools/0/outputs/1 
    •  
 
 If /tools/0/inputs/0 is changed, then the change list contains only "/tools/0/inputs/0". If the user adds a new tool, /tools/1, then the change is dispatched for "/tools" and "/dataSoruces". 
 
 This solution has the following characteristics: 
 
     
  •  Simplicity in the protocol and in the technical implementation 
    •  
  •  Reduced network traffic 
    •  
  •  Offers the client the option to only get the data that they actually need 
    •  
  •  Adds an extra roundtrip (or possibly multiple) with the backend to retrieve the updated state. This can cause race conditions or other timing oddities on the client, especially for complicated multi-step transactions (which need to be presented to the user as an atomic transaction even if they are actually implemented as a set of transactions with the backend) 
    •  
 
 Asynchronous and Synchronous Delivery of Messages 
 
 The Control Protocol supports asynchronous delivery of messages for change notification and resource streaming. 
 
 Every method call has a reply that is delivered synchronously. If the caller waits for the reply, it looks no different from a synchronous request channel: 
 
 
 
Sub /scanners/0
>> {"type": "response", "status": 1, ...}

Unsub /system
>> {"type": "response", "status": 1, ...}
 
 
 
 However, because the channel is behaving asynchronously, unrelated messages may come between a request and its response, or any time after: 
 
 
 
Sub /scanners/0
>> {"eventType":"updated", "path": "/some/path", "status": 1, "type": "notification", ...}
>> {"type": "response", "status": 1, ...}
>> {"eventType":"created", "path": "/other/path", "status": 1, "type": "notification", ...}
 
 
 
 A client must be able to handle this scenario, by looking at the "type" field of the messages coming from the server. 
 
 Receiving Change Notifications 
 
 Change notification works by "subscribing" to a list of resources. Whenever a change is observed on any of the subscribed resources, a notification is dispatched asynchronously over the connection. Subscriptions can be added and removed at run time. Each client connection maintains its own list of subscriptions.  When occurring as the consequence of a request, change notifications are guaranteed by the server to arrive AFTER the response.  
   
 
   Outside of a request/response, clients should assume that notifications can also arrive at any time. This is because notifications can be dispatched as a result of changes from  other  clients.   
 
 Methods 
 
 Change notification are enabled by using these methods: 
 
 
           
  
 Method 
 		  
 Arguments 
 		  
 Description 
 		 
   
  Sub   Resource path   
 
 Adds the path for monitoring. Whenever any of the monitored resources change, a message is dispatched describing the change. 
 

 
 		 
 
  Unsub   Resource path   
 
 Removes the path for monitoring.Pass in "*" for the path to unsubscribe from all. 
 
 Due to the asynchronous nature of the channel, it is possible to receive a notification for a resource for a short time even after it is unsubscribed. 
 
 		 
  
 
 
 
 
 
 
  Examples  
 
 
Sub /scanners/0
>> {"type":"response","status":1}

Unsub /system
>> {"type":"response","status":1}
 
 
 
 Notification Types 
 
 Whenever a subscribed resource changes, one of the following notification messages is sent: 
 
 
       
  
 Event Type 
 		  
 Fields 
 		  
 Description 
 		 
   
  created   path   
 
 This notification informs the client that a new resource has been created under a collection. 
 
  1.1.x.x  removed payload from notifications. 
 
 		 
 
  deleted   path   This notification informs the client that a resource has been deleted from a collection.  
 
  updated   path   
 
 This notification informs the client that a resource has been updated. 
 
  1.2.x.x  payload has been added back to notifications for specific resources. Currently only for /system and /replay, but check the  Resource Reference  for the specific resource. 
 
 		 
 
  embeddedUpdated   path   
 
 This notification informs the client that the subscribed "parent" resource has one or more embedded "child" resources (or descendent resources embedded in those "children") which been updated. 
 
 Notes: 
 
     
  •  this event will only be emitted by resources that have embedded or "descendent" resources 
    •  
  •   embeddedUpdated    encompasses all embedded resources recursively 
       
    •   (eg. an    embeddedUpdated    event on the    /tools   resource  covers    /tools/(toolId)    as well as /  tools/(toolId)/outputs/(outputId)    and  /tools/(toolId)/inputs/(inputId) etc.   
      •  
     
    •  
  •   Example of resources that contain embedded items are    /tools  ,    /dataSources,  etc.  
    •  
  •   Clients responding to embeddedUpdatedEvent can take advantage of Read Trait's like  ExpandLevel  to re-read all the resources underneath recursively.  
    •  
  •   Not all parents with embedded children necessarily support the embeddedUpdated notification type. Supported notifications types are documented in the  resource reference.   
    •  
 
   1.0.x.x  Added this notification type.  
 
 		 
  
 
 
 
 
 
 
  Examples  
 
 
# Resource created
>> {"eventType":"created","path":"/tools/ProfileInfo-10","status": 1, "type": "notification"}

# Resource deleted
>> {"eventType":"deleted","path":"/tools/ProfileInfo-5","status": 1, "type": "notification"}

# Resource updated
>> {"eventType":"updated","path":"/system","status": 1, "type": "notification"}

# Resource embeddedUpdated
>> {"eventType":"embeddedUpdated","path":"/tools","status": 1, "type": "notification"}
 
 
 
 Collection Resources 
 
 There are some subtleties involved for a collection resource like /tools. 
 
 When subscribing to the collection itself (e.g. /tools), the various events are described in this table: 
 
 
      
  
 Event 
 		  
 Notification 
 		 
   
  Subresource Created   "create" for new resource, e.g. /tools/ProfilePosition-0.  
 
  Subresource Deleted   "delete" for deleted resource.  
 
  Subresource Updated   "updated" for updated resources.  
 
  Content Updated   "updated" for the collection itself, e.g. /tools. This only applies if the collection resource itself has content distinct from its subresources.  
  
 
 
 It is also possible to subscribe to a subresource directly, e.g. /tools/ProfilePosition-0. In this case, "updated" and "deleted" are for the subscribed resource itself. It is not possible to receive "created" in this way because there's no path to subscribe to at the time of resource creation. 
 
 It is not possible to receive embeddedUpdated notifications on a subresource as the event will always be raised with the parent resource path. 
 
 Resource Streaming 
 
 Some resources are "streamable", in that they are able to deliver a continuous stream of data. It can be used for these features: 
 
     
  •  Data streaming (for rendering). See  here  for API details. 
    •  
  •  CSV export 
    •  
  •  Streaming replay download 
    •  
 
 Similar to change notification, streaming will be controlled via two methods: 
 
 
           
  
 Method 
 		  
 Arguments 
 		  
 Description 
 		 
   
  Stream   Resource path   
 
 Starts streaming data from the resource 
 

 
 		 
 
  CancelStream   Resource path   
 
 Removes the path for monitoring. Pass in "*" for the path to cancel all streams. 
 
 Similarly, it is possible to still receive data from a stream shortly after it's cancelled. 
 
 		 
  
 
 
 After subscribing to a streamable resource, data will start arriving from it: 
 
 
  Examples  
 
 
Stream /dataSources/tool1-output/data
>> {"type":"response","status":1}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {...}}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {...}}

Stream /dataSources/tool999-output/data
>> {"type":"response","status":1}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {...}}
>> {"type":"stream","path":"/dataSources/tool999-output/output","payload": {...}}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {...}}
>> {"type":"stream","path":"/dataSources/tool999-output/output","payload": {...}}
 
 
 
 By default, a stream has no end and no built-in measure of progress. 
 
 If these concepts are applicable to a resource, they should be implemented by that resource. A CSV export stream, for example, indicates the total number frames available, and the frame of each stream message, to let the client know how many more streams to expect. 
 
 
  Examples  
 
 
Stream /csvExport/output
>> {"type":"response","status":1}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {"isLast":false,"frame":0,"totalFrames":1000,"segment": [...]}}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {"isLast":false,"frame":10,"totalFrames":1000,"segment": [...]}}
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {"isLast":false,"frame":20,"totalFrames":1000,"segment": [...]}}
...
>> {"type":"stream","path":"/dataSources/tool1-output/output","payload": {"isLast":true,"frame":999,"totalFrames":1000,"segment": [...]}}
 
 
 
 This is not a general stream feature, and will be implemented by resources on a case-by-case basis.   However these implementations should stick to a common convention, similar to the above example. 
 
 Rate Limiting & Synchronization 
 
 There is no concept of rate limiting inherent to the streaming commands and protocol.   However the resources implementing streaming may implement their own concept of flow control. Here is an example of a resource allowing a streaming rate to be specified: 
 
 
 
# Stream data at4Hz
Stream /dataSources/tool1-output/data {"rate":4.0}
>> {"type":"response","status":1}
>> {"type":"stream","path":"/dataSources/tool1-output/data","payload": {...}}
 
 
 
  If synchronization is required between multiple resources,     their implementations should ensure synchronization "behind the scenes".  
 
 
 
 
 
  
 
 
 
 
  GoPxL: Connection and Message Framing  
 
 
 
 
  
  
 
 
 Overview 
 
 The Control Protocol consists of four significant concepts: 
 
     
  1.  Websocket/Socket connection 
    2.  
  2.  Carrier Message Layer 
    3.  
  3.  Control Message Layer 
    4.  
  4.  Control Message Content 
    5.  
 
 This document describes the correct use of the socket connections and the Carrier and Control messaging layer, as well as the structure of the messages allowed on these layers. The Control Messages Content forms the basis of the GoPxL REST API and is described in  Resource Reference  . 
 
 WebSocket/Raw Socket Connections 
 
 Connections to the Control Protocol can be made either by websocket or raw socket. Data can arrive both synchronously (ie in response to a request) or asynchronously (ie without request, as a result of prior subscriptions). As a result, these connections are generally intended to be long-lasting. Rather than establishing a connection, issuing a request, receiving the response, and then disconnecting, clients are encouraged to maintain a connection for the life time of the application, disconnecting and reconnecting only occasionally. 
 
   
 
 Mentioned below, the IP address, Control Port, and Web Port are dynamic. GoPxL can be run multiple times on a given machine,in which case Ports have to be selected by the application dynamically to avoid conflict. The selected ports are available in the discovery messages, the format is described in  GoPxL Discovery Protocol  . 
 
 The GUI client is also hosted from the Web Port. 
 
 
 
 Socket 
 
 A raw socket connection can be made to the following IP and ports: 
 
 
 
IP address:<IP Address>, Port: <Control Port>
 
 
 
  By default, the Control Port is set 3600, but it can vary to avoid conflicts.  
 
 WebSocket 
 
 A websocket connection can be made to the following URLs: 
 
 
 
ws://<IP Address>:<Web Port>/ws/controlAsync
 
 
 
 
 Normally, the Web Port is 80, but it can vary to avoid conflicts. 
 
 Websocket client should use 'binary' as the sub protocol.  As an example, in javascript/node environments this looks like:  
 
 
 
// create the WebSocket with the binary protocol
const ws = new WebSocket("ws://192.168.1.10:80/ws/controlAsync","binary");

// Specify that data is returned as an ArrayBuffer. Optionally could use "blob" here
ws.binaryType = "arraybuffer";
 
 
 
 
 
 
 In this version of the protocol, the Web Socket behaves like a stream (as it is a thin wrapper around a raw socket). Data events received by the client are not guaranteed to be complete Carrier Messages (see below) and/or may have more than a single Carrier Message. Well written websocket clients must buffer the event.data and conservatively attempt to deserialize carrier messages off the buffer. If a given data event does not provide enough bytes to satisfy the length, it must be saved and future data events appended until totalBytes > length. It is not guaranteed that future data events will ever result in the buffer reaching 0. For example, the most recent data event may contain data which complete the current carrier message, and also begins a new one. 
 
 Overall Protocol Message Framing 
 
 Request 
 
 
 
 
  
 
 
 Response 
 
 
 
 
  
 
 
 Carrier Message Layer 
 
 All JSON control messages are relayed between server and client through a    binary-based message  transfer mechanism, referred to as carrier messages. In other words, all control messages are contained within the payload of carrier messages. 
 
 The carrier messages have the concept of "Requests" or "Responses", but only as a way of informing the user agent (either client or server) about serialization concerns. 
 
 In the event of a malformed carrier message (ie one that can't be deserialized) the server will respond with an empty message (ie one with no data) and an error status (ie carrier status != OK). The connection may also be closed by the server, however this behavior is not mandatory. In practice, Carrier Status!= OK should almost never happen. 
 
 MessageType 
 
  In the header, the MessageType field has the following values, where each value corresponds to a message format that is supported:  
 
 
      
  Value   Description  
 
  MessagePack   The request/response is a message pack request/response  
 
  JSON   Therequest/response is a plain JSON request/response  
  
 
 
 MessagePack Request Message 
 
 
       
  Field   Type   Description  
 
  Length   32u   Entire message size (including this field).  
 
  MessageType   16u   The request message type (format). Must be 0xB000 (Msgpack binary format)  
 
  DataLength   32u   Size of the data field in bytes.  
 
  Data   byte[]   Msgpack binary encoded payload of length DataLength.  
  
 
 
 MessagePack Response Message 
 
 
       
  Field   Type   Description  
 
  Length   32u   Entire message size (including this field).  
 
   MessageType    16u    The command message type  (repeated from request).  
 
  Status   32s   Request result as  Status  . Will always be kOK unless there was a data communication or data formatting/parsing error.  
 
  DataLength   32u   Size of data field in bytes.  
 
  Data    byte[]    Msgpack binary encoded payload of length DataLength.  
  
 
 
 JSON Request 
 
 
       
  Field   Type   Description  
 
  Length   32u   Request size (including this field).  
 
   MessageType    16u    The request message type (format)  . Must be 0xB001 (JSON format).  
 
   DataLength    32u   Size of the data field in bytes.  
 
  Data   char[]   JSON-encoded (string) payload of length DataLength.  
  
 
 
 JSON Response 
 
 
       
  Field   Type   Description  
 
   Length    32u   Response size (including this field).  
 
   MessageType    16u    The message type  (repeated from request).  
 
  Status   32s    Request result as  Status  . Will always be kOK unless there was a data communication or data formatting/parsing error.   
 
   DataLength    32u   Size of data field in bytes.  
 
  Data   char[]    JSON-encoded (string) payload of length DataLength.   
  
 
 
      Control Message Layer  
 
  Throughout the documentation you will see "JSON" used in reference to the value of a potential property type. The terms "JSON" and "MessagePack" (or "MsgPack") are used interchangeably for the purposes of documentation, since they have the same abstract format. Both JSON and MessagePack can serialize complex objects and properties of the same type (although MessagePack has native support for binary data). A list of all possible JSON/MessagePack value types is documented   here   .  
 
 GoPxL overloads JSON standard to include binary data. For MessagePack serialized REST connections, this is supported natively. For JSON serialized REST connections, binary data is converted into a standard number array. For example, a property defined as binary which contains the string "hello\0" would look like 
 
 
 
[104, 101, 108, 108, 111, 0]
 
 
 
   
 
 The order of fields in any JSON object returned by the protocol is not guaranteed. 
 
 
 
   Request Messages   
 
   A JSON/msgpack request message has the following fields:   
 
 
              
  Field   Type   Required   Description  
 
  method    string    Yes   
 Must be one of the following method strings: 
 
     
  •  "create" 
    •  
  •  "delete" 
    •  
  •  "read" 
    •  
  •  "update" 
    •  
  •  "call" 
    •  
  •  "sub" 
    •  
  •  "unsub" 
    •  
  •  "listSub" 
    •  
  •  "clearSub" 
    •  
  •  "stream" 
    •  
  •  "cancelStream" 
    •  
  •  "listStream" 
    •  
 
 Each method is described in detail in  Resource Design and Request Methods  
 
 Over time, as the protocol evolves and changes, this list may grow. Methods will rarely, if ever, be removed. Such an act would be a  breaking protocol change  . 
 		 
 
   path     string     Yes    the path of the resource, eg "/system/commands"  
 
  payload   JSON    No    
  If the resource requires request data (sometimes called "arguments", but not to be confused with "args" below), they should be in the payload object.  
 
 If no request data is required the payload should be an empty object "{}" or null (as specified in the  Resource Reference  ). 
 		 
 
  args   JSON   No   
 Additional method arguments passed to the request handler. Args modify the way the method is processed, and are not typically handled by the resource request. These are defined within the context of application logic, rather than the protocol. 
 See for example:  Documentation Conventions#ExpandLevelArgumentExpandLevel  and  Documentation Conventions#IncludeSchemaArgumentIncludeSchema  
 
 If no argument data is required the "args" field should be an empty object "{}" or null. 
 		 
  
 
 
  Examples:  
 
 
  Request message  
 
 
{
  "method": "read",
  "path": "/system/info",
  "payload": {},
  "args" : {}
}

{
  "method": "read",
  "path": "/tools",
  "payload": {},
  "args" : {"expandLevel": -1}
}

{
  "method": "create",
  "path": "/tools",
  "payload": {"type": "TestForward", "position": 3, "autoConnect": true},
  "args" : {}
}
 
 
 
 Response Messages 
 
 There are generally three types of response messages: 
 
     
  1.  Request response type messages 
    2.  
  2.  Notification type messages 
    3.  
  3.  Stream type messages 
    4.  
 
 
 
 
 Response messages all contain the following fields. Some response type messages (eg. notification) can have additional fields. These additional fields are described in more detail in the sections on the specific response type messages. 
 
 
 
 
 
              
  Field   Type   Required   Description  
 
  path   string   No   
 
 The "path" field is the resource path in the request message. 
 
 This value is sometimes duplicated inside the "payload" field. 
 
 For example, in the following example: 
 
     
  •  the "path" field value is also present in the "payload/_links/self/href" field. 
    •  
 
  1.0.x.x  Field added 
 
 		 
 
  payload   JSON   No   
 When applicable  (as specified in the   Resource Reference   ),  contains the response of the request. This can be any valid JSON/MsgPack value, including null but also including string, array, or even binary data. 
 
 If no payload is available, it can be a JSON null, especially for the last message in a streamed sequence. 
 
 When the type is "response", the payload contains the content relevant to the request. 
 
 When the type is "notification", the payload contains the content pertaining to the relative URI path raising the event notification. 
 		 
 
  status   signed integer   Yes   
 Status of the request. See   here  for a list of possible status codes  . 
 
  This status code  is not  related to the carrier message layer. For example, a request for a resource which doesn't exist would return status == OK in the carrier message and status!= OK in the Control message.  
 
  Think of the carrier message status = OK as meaning "message received" and the control message status!= OK as meaning "request failed".  
 
  When response status is not OK, there may be errors in the payload to help explain the failure. See  Error Handling  for more detail about how error messages are provided in this case.  
 		 
 
  type   string   Yes   
 This field indicates the type of response message. 
 
 There are three response message types: 
 
 
  
  Message Type   Description  
 
  "response"   Response type messages are the logical/semantic reply to a request.  
 
  "notification"   
 Notification type messages are asynchronously provided to the client for a particular resource. 
 
 These are usually generated in response to a request to report resources affected by the request. 
 
 Notification messages for a resource is sent to a client if the client has subscribed to that resource. 
 		 
 
  "stream"   
 Stream type messages are asynchronously sent to the client if the client has subscribed to a streamable resource. 
 		 
  
 
 		 
  
 
 
 Request Response Type Message       
 
 Request response type of response message are response messages from the server for the client's request. This type of response message has all the fields for a basic response message described above. 
 
 Example  :  read request to the resource "/logs/summary". In this example,  the "path" field value is also present in the "payload/_links/self/href" field.  
 
 
  Response message  
 
 
{
  "path" : "/logs/summary",
  "payload": {
    "_links": {
      "self": {
        "href": "/logs/summary"
      }
    },
    "idEnd": 3,
    "idStart": 1
  },
  "status": 1,
  "type": "response"
}
 
 
 
 Notification Type Message       
 
 Notification type response messages are messages from the server sent asynchronously to the client, that is not a response to an explicit client request. For notification type messages, an "eventType" field is present at the top level, in addition to the basic response message fields. 
 
 
              
  Field   Type   Required   Description  
 
  eventType   string   Yes   
 
 Additional field specifically for notification type messages. 
 
 A string that Indicates the reason why the notification message was generated. Possible values are: 
 
     
  •  "created" 
    •  
  •  "updated" 
    •  
  •  "deleted" 
    •  
  •  "embeddedUpdated" 
    •  
 
  1.0.x.x  Field added 
 
 		 
 
  path   string   Yes   
 
 The path is the resource that generated the notification. 
 
  1.0.x.x  Field added 
 
 		 
 
  payload   json   No   
 Content associated with the event notification. This is usually all the properties normally provided via a read of the same resource. This can be any valid JSON/MsgPack value, including null. 
 
 
  1.2.x.x  Notifications may have payload contained in it, it is up to the client to check if the payload is not null, if not the resource should be explicitly read.. 
 
 		 
  
 
 
 Example  :  This shows a notification from the "/system" resource to which client has subscribed. 
 
 
  Notification Message  
 
 
Commands used for this example:
  sub /system/*
  call /system/commands/start

{
  "eventType": "updated",
  "path": "/system",
  "payload": {
    "_links": {
      "self": {
        "href": "/system"
      }
    },
    "_schema": {
      "properties": {
        "autoLiveSimEnabled": {
          "sortOrder": 200,
          "title": "autoLiveSimEnabled",
          "type": "boolean"
        },
        "autoStart": {
          "sortOrder": 100,
          "title": "autoStart",
          "type": "boolean"
        },
        "runState": {
          "enum": [
            0,
            1,
            2
          ],
          "enumText": [
            "Ready",
            "Running",
            "Conflict"
          ],
          "readOnly": true,
          "sortOrder": 0,
          "title": "runState",
          "type": "integer"
        }
      },
      "sortOrder": 0,
      "title": "",
      "type": "object"
    },
    "autoLiveSimEnabled": true,
    "autoStart": false,
    "runState": 1
  },
  "status": 1,
  "type": "notification"
}


 
 
 
 Stream Type Message     
 
 Some resources can be "streamed", see  Notification and Streaming  . These streamable resources send data asynchronously from the server to the client when the data is available, without needing the client to explicit ask for the new data. 
 
 Two additional fields are present in this type of response message: "streamId" and "streamStatus". 
 
 
        
  Field   Type   Required   Description  
 
  path   string   Yes   
 
 The "path" field is the streamable resource path that generated the stream data. 
 
 Typically this is the value as the original stream request resource path. 
 
  1.0.x.x  Field added 
 
 		 
 
  streamId   unsigned integer   Yes   
 
 Additional field specifically for stream type messages. 
 
 Internally generated identifier for this particular data stream. This value is returned by the stream request response message. 
 
  1.0.x.x  Field added 
 
 		 
 
  streamStatus   string   Yes   
 
 Additional field specifically for stream type messages. 
 
 Possible values are: 
 
     
  •  "streaming" - streaming in progress. Applies to both continuous and finite (non-continuous) streams. 
    •  
  •  "complete" - streaming finished. Applies only to finite streams. 
    •  
  •  "abort" - streaming aborted. Applies to both continuous and finite streams when the stream terminates abnormally. 
    •  
 
  1.0.x.x  Field added 
 
 		 
  
 
 
 Example: 
 
 
 
Commands used for this example:
   stream "/dataSources/scan:g2xxx:scanner-0:top:profile:uniform/data"

{
  "path": "/dataSources/scan:g2xxx:scanner-0:top:profile:uniform/data",
  "payload": {
    "type": 12,
    "commonAttrSize": 151,
    "hasTransform": true,
    ...
    "xOffset": -16.25,
    "zOffset": 0.0004,
    "exposure": 100.09765625
  },
  "status": 1,
  "streamId": 1,
  "streamStatus": "streaming"
  "type": "stream"
}
 
 
 
 Not all resources support streaming, and some resources may  only  support streaming. Error is returned when trying to access these resources in an unsupported manner. 
 
 Payload could be a binary or it could be JSON data. This is specified in the documentation of the respective resource. 
 
 Documentation Shorthand 
 
 For brevity, the documentation adopts a shorthand when providing examples of requests. The shorthand follows the following general syntax 
 
 
 
METHOD PATH [{PAYLOAD}] [{ARGUMENTS}]
 
 
 
 Payload and Arguments are optional, and are therefore only documented where appropriate. In cases where Arguments are needed but not Payload (for example "read /scanners/profile-scanner-0" below), an empty object "{}" is used. 
 
 Some examples of this in use are as follows 
 
 
 
read /logs {"startId": 1, "endId": 3}
read /scanners/profile-scanner-0 {} {"expandLevel":0}
delete /jobs/files/myJob
create /jobs/files {"name": "newJob", "content": [binary data]}
call /system/commands/restore {"data":[binary data], "contents": ["currentJob", "replay"]}
stream /dataSources/tools:TestForward-0:otuputs:Output0/data {"period": 250000}
sub /tools/Profile*/inputs/*
 
 
 
 Additionally, most response examples only include the "payload" portion of the response format, since the "status". "type", and "stream" components are either implied, redundant, or irrelevant. Where additional clarification is needed, these sections may be included. 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
  GoPxL: Versioning and Compatibility  
 
 
 
 
   
  
  
 
   
 
  The version and compatibility standards referred to on this page cover the protocol, documents, and persistent files used to communicate and interact with GoPxL. The GoPxL application release package, and other binaries included within it, may have their own version numbers - typically 4-digits, for example "1.0.109.27" - but the rules outlined in the sections below to not apply.  
 
 
 
  Versioning  
 
  The protocol has three version numbers in the form of a.b.c, where a is the major version, and b is the minor version, and "c" is the patch version. This follows conventions defined by  SemVer  . Major protocol version changes represent breaking changes, while minor and patch protocol version changes represent non-breaking changes.  
 
  A protocol change is considered non-breaking if:  
 
     
  •   A well-written client for a previous protocol version can successfully connect to and interact with GoPxL running a newer  protocol  version.  
       
    •   This is defined as "forwards compatibility". See below for more information.  
      •  
     
    •  
  •   A well-written client for a newer protocol version can  successfully connect to and interact with  GoPxL  running an  older protocolversion.  
       
    •   This is defined as "backwards compatibility". See below for more information.  
      •  
     
    •  
 
    A well-written client should allow for small non-breaking changes such as:  
 
     
  •   Addition of optional fields in resource documents  
    •  
  •   Addition of fields to expandable sections of data (GDP) messages  
    •  
  •   Compatible type changes (e.g. integer to decimal)  
    •  
 
  Changes that break compatibility with a well-written client (as defined above) are considered breaking.  
 
   
 
 Plugins are responsible for implementing compatibility with the API's and persistent files they create. They are not in scope for this document. This includes 3rd party Tools, Scanners, Routines, and Control Services. 
 
 
 
 Major Version Increase 
 
 The following is a non-exhaustive list of examples of the types of changes that result in a major version increase 
 
     
  •   Removal of fields from a resource document  
    •  
  •   Changing a field type to an incompatible type (e.g. integer to string)  
    •  
  •   Changes in data message structures beyond additions to expandable sections  
    •  
  •   Additional  non-optional  command argument (if the new argument is optional, the addition is non-breaking)  
    •  
  •   Changing the key of a map-structure element (for example in a JSON document object) such that a different key is needed.  
    •  
 
 Minor Version Increase 
 
 Any change that doesn't satisfy the conditions of a Major Version increase is considered a Minor Version increase. Some examples include 
 
     
  •  Adding a new optional field to a resource document 
    •  
  •  Adding a new optional argument to a callable resource 
    •  
  •  Adding a new field in a GDP message, where that field is contained in an expandable section 
    •  
  •  making breaking changes to "internal" API's. See detail on Internal API's below. 
    •  
 
  Persistent file forwards compatibility shall be supported across a single major protocol version increment. Backwards compatibility and support across multiple major protocol revisions are not guaranteed.  
 
 Patch Version Increase 
 
 Patch version is identical to a minor version in its logic, but increases only whenever  GoPxL  needs a service release and such service release requires a protocol change. Patch versions (and service releases in general) are primarily intended for bug fixes, so in many cases a protocol version change is not needed. 
 
  Backwards and Forwards Compatibility  
 
  The versioning system is designed to reflect a scheme for how to handle forwards and backwards compatibility. Respectively, these are defined as:  
 
     
  •    Forwards Compatibility:    Where a client/receiver implements an older version of protocol than  what is provided by the server/source  .  
       
    •   Example 1: Version 2 SDK connects to a Version 3 application  
      •  
    •   Example 2: Version 2 application loads a Version 3 configuration/Job file  
      •  
     
    •  
  •    Backwards Compatibility:    Where a client/receiver implements a newer version of protocol  than  what is provided by the server/source   .  
       
    •   Example 1: Version 3 SDK connects to a Version 2 application  
      •  
    •   Example 2: Version 3 application loads a Version 2 configuration/Job file  
      •  
     
    •  
 
  Minor Protocol Changes  
 
   Forwards Compatibility     
 
  Where a Minor change is made,  GoPxL  implements forwards compatibility which will permit out-of-date (ie older/smaller version) client and SDK user application implementations to continue to connect and interact with the sensor. Any resource document format created by these older clients and user apps will be handled by  GoPxL  (missing fields will be assumed a default value).  
 
  Additionally, older-format persistent files (ie jobs, workspace, replay files, backups, etc) will be opened and read by  GoPxL, and missing fields/information will assume a default value  . Upon saving, these files will be   rewritten   to the current GoPxL version.  
 
   Backwards Compatibility   
 
  Backwards compatibility for minor changes relies on support from the client, as it must be designed to deal with missing information in the structures represented by the protocol. Responsibility of implementing backwards compatibility falls on the  SDK user application  . Data messages and responses received may have missing fields and resource documents may have missing fields. The SDK implements this support in its GDP implementation, however the REST API exposes some of these changes on the user, and it is the user's responsibility to build their application to be resilient to them. However,  GoPxL  does handle backwards compatible Callable resource requests; parameters/arguments added to the protocol will be considered optional (guaranteed by the definition of a minor change).  
 
  Additionally, newer-format persistent files (  ie jobs, workspace, replay files, backups, etc  ) will be opened and read by  GoPxL  and extraneous fields/information will be ignored.  Upon saving, these files will be rewritten to the current GoPxL version.   
 
  Major Protocol Changes  
 
  Major protocol changes represent a more difficult situation to handle. Entire structures in the protocol may no longer exist or may exist in dramatically different forms. In general,  there is no support  for forwards or backwards compatibility across major protocol changes, however special handling does exist with regards to the persistent files.  
 
  The Application implements forwards compatibility for Jobs and Workspaces only, and is designed to handle changes that are no more than  one major protocol version out-of-date  . A best effort approach is taken, which may allow for the persistent file to be more than a single version out-of-date, however this is not guaranteed. Additionally, forwards compatibility of replay and backup files is not guaranteed.  
 
  Change Documentation  
 
  Any time an API is changed, the change will be summarized in the release notes for the application release. These release notes will also note what is the new version of the protocol. Note that protocol version is not the same as application version.  
 
  In addition, the API documentation itself will keep track of changes on the entities (eg fields/properties or resources themselves). This inline change documentation will note the specific application version where the change was made, and a brief description of the change.  
 
 
  Deprecation  
 
  Soft Deprecation  
 
  There is sometimes the need to remove a field from a resource document, remove an entire resource document, or remove a field from a binary message (such as GDP structures). To preserve serialization compatibility, the following guidelines apply:  
 
     
  •   All writers should still write the field, but its content is unimportant. For binary messages, this MUST be done to maintain message byte alignment. For documents, this SHOULD be done.  
    •  
  •   Readers should ignore the field.  For binary messages, the deprecated field can be skipped or read and discarded.   
    •  
  •   GoPxL will add a  deprecated schema attribute (to documents, where applicable), purely as a reminder. 
    •  
  •  Documentation will be updated to reflect that the field is deprecated. The original description of the field will be removed to discourage continued use. 
    •  
 
 Such changes are considered as minor protocol changes. As documented above in the forwards compatibility section, minor changes imply that it is still acceptable to connect to the service with an older version client (assuming major versions match). 
 
 All soft deprecations will be accompanied by anotice included in the release notes to indicate which fields or resources are affected. Eventually, deprecated fields will be removed. The period between the notice and the removal (see Hard Deprecation below) is referred to as the Deprecation Period. 
 
  Deprecated API's will always be clearly documented as  DEPRECATED  . Users are strongly discouraged from using them.  
 
  Hard Deprecation  
 
  Hard deprecation occurs at some point after the Deprecation Period. It occurs when the field or resource which was previously documented as deprecated is  actually  removed.  
 
  Such changes are still considered as major protocol changes. As a result, soft deprecated fields often remain so for extended periods of time, until a major protocol change is unavoidable for other reasons.  
 
  Internal APIs  
 
  The same API which is documented for public use is also used by the SDK's and GUI in ways that are not intended for public consumption. Since the REST API is self-descriptive, it's possible that protocol users may come across these API's. This is not a security issue - these API's are well tested and supported, and do not expose secure details about the application or user-specific details. However, since these API's are not intended to be used by external users, changes to these API's may not follow the usual Major/Minor/Patch versioning guidelines as stated above. Internal API's may disappear, or change substantially, and these may not be considered a breaking change.  
 
  Internal API's will always be clearly documented as  INTERNAL  . Users are strongly discouraged from using them. In binary structures, Internal fields will still need to be parsed to maintain byte alignment (as with deprecated fields). In documents, internal fields should be ignored.  
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
  GoPxL: Versions and Releases  
 
 
 
 
 
 
 
            
  
  Name  
 		  
  Build  
 		  
  Description  
 		  
  Protocol Version  
 		  
  SDK Build Version  
 		  
  SDK API (REST protocol) Version  
 		  
  Ethernet IP  
 		  
  PROFINET  
 		 
 
  
 0.2 
 		  
 0.2.1.53 
 		  
 General Release (for G5 support) 
 		  
 1.0.0 
 		  
 7.0.0.0 
 		  
 n/a 
 		  
 n/a 
 		  
 n/a 
 		 
 
  
 0.3 
 		  
 0.3.5.24 
 		  
 Evaluation Release 
 		  
 2.0.0 
 		  
 8.0.0.0 
 		  
 n/a 
 		  
 n/a 
 		  
 n/a 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
 
  
 1.0 
 		  
 1.0.109.203 
 		  
 Public Release 1.0 
 		  
 3.0.0 
 		  
  8.0.9.145  
 		  
 3.0.0 
 		  
 1.2 
 		  
 1.0 
 		 
 
  
 1.0 SR1 
 		  
 1.0.110.37 
 		  
 Public Release 1.0 SR1 
 		  
 3.0.0 
 		  
 8.0.10.42 
 		  
 3.0.0 
 		  
 1.2 
 		  
 1.0 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
 
  
 1.1 Beta (2023-Dec) 
 		  
 1.1.9.54 
 		  
 Beta Evaluation Release 1.1 
  (2023-12-20)  
 		  
 4.0.0 
 		  
 8.1.11.62 
 		  
 4.0.0 
 		  
 1.3 
 		  
 1.0 
 		 
 
  
 1.1 Beta (2024-Feb) 
 		  
 1.1.10.125 
 		  
 Beta Evaluation Release 1.1 
  (2024-02-28)  
 		  
 4.0.0 
 		  
 8.1.12.49 
 		  
 4.0.0 
 		  
 1.3 
 		  
 1.0 
 		 
 
  
 1.1 Beta (2024-Apr) 
 		  
 1.1.10.143 
 		  
 Beta Evaluation Release 1.1 
  (2024-04-02)  
 		  
 4.0.0 
 		  
 8.1.12.62 
 		  
 4.0.0 
 		  
 1.3 
 		  
 1.0 
 		 
 
  
 1.1 (2024-Apr) 
 		  
 1.1.11.1 
 		  
 Public Release 1.1 
 		  
 4.0.0 
 		  
 8.1.13.1 
 		  
 4.0.0 
 		  
 1.3 
 		  
 1.0 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
 
  
 1.1 AD (2024-Dec) 
 		  
 1.1.52.14 
 		  
 Public Release of 1.1 Anomaly Detector 
 		  
 5.0.0 
 		  
 8.2.9.5 
 		  
 5.0.0 
 		  
 1.3 
 		  
 1.0 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
 
  
 1.2 (2025-Feb) 
 		  
 1.2.27.47 
 		  
 1.2 Beta 1 Evaluation Release 
  (2025-02-06)  
 		  
 5.0.0 
 		  
 8.2.33.57 
 		  
 5.0.0 
 		  
 1.3 
 		  
 1.2 
 		 
 
  
 1.2 (2025-Feb) 
 		  
 1.2.27.128 
 		  
 1.2 Beta 2 Evaluation Release 
  (2025-02-26)  
 		  
 5.0.0 
 		  
 8.2.33.115 
 		  
 5.0.0 
 		  
 1.3 
 		  
 1.2 
 		 
 
  
 1.2 (2025-Mar) 
 		  
 1.2.27.146 
 		  
 1.2 Beta 3 Evaluation Release 
  (2025-03-04)  
 		  
 5.0.0 
 		  
 8.2.33.121 
 		  
 5.0.0 
 		  
 1.3 
 		  
 1.2 
 		 
 
  
 1.2 (2025-May) 
 		  
 1.2.30.5 
 		  
 1.2 Beta 4 Evaluation Release 
  (2025-05-07)  
 		  
 5.0.0 
 		  
 8.2.41.7 
 		  
 5.0.0 
 		  
 1.3 
 		  
 1.2 
 		 
 
  
 1.2 (2025-May) 
 		  
 1.2.30.34 
 		  
 1.2 Beta 5 Evaluation Release 
  (2025-05-21)  
 		  
 5.0.0 
 		  
 8.2.41.24 
 		  
 5.0.0. 
 		  
 1.3 
 		  
 1.2 
 		 
 
  
 1.2 (2025-Jun) 
 		  
 1.2.30.56 
 		  
 Public Release 1.2 
 		  
 6.0.0 
 		  
 8.2.41.38 
 		  
 6.0.0 
 		  
 2.1 
 		  
 1.2 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
 
  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		  
 
 		 
  
 
 
 "Protocol Version" coincides with what is reported on the  /version resource