# GoPxL: Resource Reference

# /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 |  | Determines if the system will auto start or not. When enabled, the system will automatically start as soon as the instance is launched. This could happen either on PC, when starting an instance, or when the device hosting the instance is booted. This feature is currently not implemented, and is planned for a future release.
autoLiveSimEnabled | bool |  |

### 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 |
--- | ---
updated | Occurs whenever the system properties change (ie. sensor is started, stopped, etc.). 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

## /system/commands/stop

Resource Type: (Callable)

### Properties

none

### Methods

Method | Description
--- | ---
call | Stops the sensor system. Example:
    call /system/commands/stop

## /system/commands/upgrade

Resource Type: (Callable)

### Methods

Method | Description
--- | ---
call | Start the upgrade with the provided package. Payload:
Item | Type | Description
--- | --- | ---
package | binary | The upgrade package
Example:
    call /system/commands/upgrade {"skipValidation" : false, "package": <binary data>}
or
    call /system/commands/upgrade {"skipValidation" : false, "package": "upgradeFile.dat"}
A device restart may be required before using this resource to upgrade the device successfully. 1.0.x.x Use the Gocator Graphical User Interface to upgrade the device instead.

## /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 Resource Reference#/jobs resource for information about how to read jobs out before performing a factory restore. Example:
    call /system/commands/factoryRestore

## /system/commands/restart (this deprecates /system/commands/reset).

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 awhile 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"]}
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:
    call /system/commands/restore {"data":{binary data}, "contents" : ["global", "allWorkspaces", "allJobs", "replay"]}
To recreate what the GUI does during Replay > Upload:
    call /system/commands/restore {"data":{binary data}, "contents" : ["liveJob", "replay"]}

## /system/info

Resource Type : N/A

### 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 Standard Scanner Resources .

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
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 available (bytes). |  | 2005 | 0 - User 1 - System | StorageVolume/User/Used StorageVolume/System/Used
storageVolumes/n/capacity | k64s | integer |  | Amount of non-volatile storage used (bytes). |  | 2006 | 0 - User 1 - System | StorageVolume/User/Capacity StorageVolume/System/Capacity
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 | 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
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.
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
which for example, returns:
    {
      "payload": {
        "_links": {
          "self": {
            "href": "/system/metrics"
          }
        },
        "advanced": {
          "hostPorts": [
            {
              "commandCount": 0,
              "port": 3210,
              "replyCount": 0,
    		  "responseDataDropCount": 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

# /environ

## /environ/ipConfig

Resource Type: N/A

### Description

Contains information aboutnetwork interface configuration.

### Properties

Item | Type | Schema | Description
--- | --- | --- | ---
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.
interfaces/n/ipAddress | string | readOnly | IP address.
interfaces/n/subnetMask | string | readOnly | subnet mask.
interfaces/n/gatewayAddress | string | readOnly | Gateway IP
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"
            }
          },
          "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"
          }
        ]
      },
      "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
partNumber | string | readOnly | Model of the sensor. 1.0.x.x Added.
serialNumber | string | readOnly | Unique serial number of a sensor. 1.0.x.x Added.
version | string | readOnly | Version of the sensor firmware. 1.0.x.x Added.
model | string | readOnly | Model name of the sensor. 1.0.x.x Added.

### Methods

Method | Description
--- | ---
read |
    {
      "_links": {
        "self": {
          "href": "/api/environ/info"
        }
      },
      "_schema": {
        "properties": {
          "applicationType": {
            "readOnly": true,
            "sortOrder": 0,
            "title": "applicationType",
            "type": "integer"
          },
          "controllerType": {
            "readOnly": true,
            "sortOrder": 1,
            "title": "controllerType",
            "type": "integer"
          }
        },
        "sortOrder": 0,
        "title": "",
        "type": "object"
      },
      "applicationType": 2,
      "controllerType": 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 | IP Address of remote controller.
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 |
    {
      "_links": {
        "self": {
          "href": "/api/environ/remoteController"
        }
      },
      "_schema": {
        "properties": {
          "controlPort": {
            "readOnly": true,
            "sortOrder": 200,
            "title": "controlPort",
            "type": "integer"
          },
          "ipAddress": {
            "readOnly": true,
            "sortOrder": 100,
            "title": "ipAddress",
            "type": "string"
          },
          "remoteConnected": {
            "readOnly": true,
            "sortOrder": 0,
            "title": "remoteConnected",
            "type": "boolean"
          },
          "webPort": {
            "readOnly": true,
            "sortOrder": 300,
            "title": "webPort",
            "type": "integer"
          }
        },
        "sortOrder": 0,
        "title": "",
        "type": "object"
      },
      "controlPort": 0,
      "ipAddress": "",
      "remoteConnected": false,
      "webPort": 0
    }

# /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.

### 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

## /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.
engineId | string | readOnly | The ID of the scan engine, defined by scan engine plugin. e.g., " LMILaserLineProfiler ", "test".
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",
        "engineId": "test",
        "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 | int | 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 playback settings.
update | Updates the playback 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.

Item | Type | Schema | Description
--- | --- | --- | ---
data | binary | readOnly | The binary data for the dataSource.Data streamed to the client from this resource will be formatted according to the serialization structures documented on Message Serialization Not all fields documented on the Message Serialization page apply when streaming. Any exceptions are noted on that page.

### 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:
    { "eventType" : "updated", "path" : "/jobs",
      "payload" : {updated jobs properties} }

## /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 ".job" 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:
    { "eventType" : "updated", "path" : "/jobs/files",
      "payload" : {updated /jobs/files collection} }

## /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",
      "payload" : {new job properties} }
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:
    { "payload" : {updated job properties}, "eventType" : "updated", "path" : "/jobs/files/updatedJob"}
deleted | Occurs whenever a job file is deleted. The path indicates the job name that was deleted. Example:
    { "eventType" : "deleted", "path" : "/jobs/files/deletedJob"}

## / jobs/files/(id)/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/(id) -- Notifications .

# /problems

Resource Type: (Collection - Unordered)

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.

Problem messages will also be logged as a new Log entry in the /logs resource :

- "Potential" problems will be show up in the /logs historically as "Warning"
- "Blocking" problems will be show up in the /logs historically as "Errors"

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
    {
      "_links": {
        "self": {
          "href": "/api/problems"
        }
      },
      "_schema": {
        "properties": {
          "msg": {
            "type": "string"
          },
          "severity": {
            "type": "integer"
          },
          "source": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "items": [
        {
          "msg": "Data source required (at: ProfilePosition-0 tool[Profile Input]).",
          "severity": 0,
          "source": "Pipe"
        }
      ]
    }

### 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",
      "payload" : {updated /problems collection} }

# /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 Resource Reference#/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}

## /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

Edit

## /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

### Notifications

Event Type | Description
--- | ---
updated | Occurs whenever the log collection changes due to additions or deletions. Example:
    { "eventType" : "updated", "path" : "/logs/summary",
      "payload" : {updated /logs idStart and idEnd} }

/internal

For internal resources, see Internal Resources .

# 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. This information can be found on Standard Scanner Resources

# /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. 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.
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 | readOnly, minimum, used | integer | 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 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.
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

### 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. That information can be found through Standard Scanner Resources .

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)

### Description

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

### Methods

Method | Description
--- | ---
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. Arguments:
Item | Type | Description
--- | --- | ---
interactive | boolean | If true, the scanner will attempt to align interactively & request user parameters. If false, alignment will run on its own without any additional inputs. This is the default. Scanners may choose not to implement interactive alignment, in which case this parameter should be ignored.
Example request:
    call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/align {"interactive":false}
1.0.x.x Added

### Notifications

None.

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

Resource Type: (Callable)

### Description

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

### Methods

Method | Description
--- | ---
call | Cancels scanner alignment. Example request
    call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/cancelAlign
1.0.x.x Added

### Notifications

None.

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

Resource Type: (Callable)

### Description

Clears existing alignment. If alignment is running, cancels then clears.

### Methods

Method | Description
--- | ---
call | Clears scanner alignment. Example request
    call /scan/engines/LMILaserLineProfiler/scanners/scanner-0/commands/clearAlign
1.0.x.x Added

### Notifications

None.

## /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. That information can be found through Standard Scanner Resources .

Methods

Method | Description
--- | ---
read | Reads the latest sensor metrics. Example:
    read /scan/engines/LMILaserLineProfiler/scanners/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"
        }
      }
    }

### 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 given scan engine such as G2, see its resource reference under Standard Scanner Resources .

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 scanner speed (Hz). If scanner is not running, this metric is omitted. |  | 20001 | N/A | "Gocator/Maximum Speed"
maxSpeed | k64f | number |  | Maximum scanner speed (Hz); 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"
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
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 | k64u | integer |  | Current scanner encoder frequency (ticks/s). |  | 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
--- | --- | --- | ---
source | integer | enum | Trigger source. 0 - Time 1 - Encoder 2 - Digital input 3 - Software
maxFrameRateEnabled | bool | used | Enables maximum frame rate.
frameRate | number | minimum, maximum, actual, used | Frame rate for time trigger (Hz).
encoderSpacing | number | minimum, maximum, used | Encoder spacing (degrees) in rotational surface generation mode; (mm) in all other modes.
encoderTriggerMode | integer | enum, used | Encoder trigger mode. 0 - Track Backward 1 - Ignore Backward 2 - Bi-directional
externalInputIndex | integer | enum, used | External input index.
schedulingUnits | integer | enum, used | Scheduling units. 0 - Time 1 - Encoder
delay | number | minimum, maximum, used | Trigger delay (s or mm).
gateEnabled | bool | actual, used | Enables digital input gating.
reversalDistanceAutoEnabled | bool | used | Whether or not to use auto-calculated value of reversal distance.
reversalDistance | number | readOnly, used | Encoder reversal threshold (for jitter handling).
lightSleep | object | used | See Gocator Scanner - LightSleep below.
burstScan | object | used | 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
--- | --- | --- | ---
gapFilling | object |  | Gap filling filter
gapFilling/enableX | bool | used | Enable gap filling along X axis.
gapFilling/winX | number | minimum, maximum, used | X window size (mm).
gapFilling/enableY | bool | used | Enable gap filling along Y axis; applies in surface mode only.
gapFilling/winY | number | minimum, maximum, used | Y window size (mm); applies in surface mode only.
median | object |  | Median filter
median/enableX | bool | used | Enable median filtering along X axis.
median/winX | number | minimum, maximum, used | X window size (mm).
median/enableY | bool | used | Enable median filtering along Y axis.
median/winY | number | minimum, maximum, used | Y window size (mm).
smoothing | object |  | Smoothing filter
smoothing/enableX | bool | used | Enable smoothing along X axis.
smoothing/winX | number | minimum, maximum, used | X window size (mm).
smoothing/enableY | bool | used | Enable smoothing along Y axis.
smoothing/winY | number | minimum, maximum, used | Y window size (mm).
decimation | object |  | Decimation filter
decimation/enableX | bool | used | Enable decimation along X axis.
decimation/winX | number | minimum, maximum, used | X window size (mm).
decimation/enableY | bool | used | Enable decimation along Y axis.
decimation/winY | number | minimum, maximum, used | Y window size (mm).

## LightSleep (Property group)

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

Item | Type | Schema | Description
--- | --- | --- | ---
enabled | bool |  | Enables light sleep.
idleTime | integer |  | Idle time before light is turned off (s).
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, used | 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
--- | --- | --- | ---
enabled | bool |  | Enable multiplexing.
globalEnabled | bool |  | Enable global multiplexing.
globalDelay | integer |  | Global multiplexing delay.
globalPeriod | integer | minimum | Global multiplexing period.
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 G2, see its resource reference under Standard Scanner Resources .

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
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
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
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
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 |  | Amount of non-volatile storage available (bytes). |  | 2006 | 0 - User 1 - System | StorageVolume/User/Capacity StorageVolume/System/Capacity
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

## 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, used, 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, used, 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 | used | 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
--- | --- | --- | ---
analogGain | number | minimum, maximum, readOnly, actual, used | Analog gain.
digitalGain | number | minimum, maximum, readOnly, actual | Digital gain.
gammaType | integer | enum, minimum, maximum, readOnly, actual, used | Gamma type. 0 - None 1 - Low 2 - Medium 3 - High
enhancedSurfaceFlatness | object | visibility | Enhanced surface flatness feature parameters 1.1.x.x Parameter group created.
enhancedSurfaceFlatness\enabled | bool | readOnly | 0 -feature is disabled 1 - feature is enabled
enhancedSurfaceFlatness\coefficients | array<number> | readOnly, actual, visibility | Array of coefficients if filterType is not 0. ADVANCED
enhancedSurfaceFlatness\filterSize | enum | readOnly, visibility | Size of the filter if filterType is not 0. Allowed values3, 5, 7, 9, 11 and 13. ADVANCED
enhancedSurfaceFlatness\filterType | enum | readOnly, visibility | 0 = User specified coefficient values 1 = Box filter 2 = Gaussian filter ADVANCED
hdrMode | enum | readOnly, used | HDR mode 0 - disabled 1 - Gamma compression 1.1.x.x Added.
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
xOffset | number |  | Translation on the X axis (mm).
yOffset | number | used | Translation on the Y axis (mm).Not used by all scanners, in which case used=false.
zOffset | number |  | Translation on the Z axis (mm).
xAngle | number | used | Rotation around the X axis (degrees).Not used by all scanners, in which case used=false.
yAngle | number |  | Rotation around the Y axis (degrees).
zAngle | number | used | 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
--- | --- | --- | ---
columnCount | integer |  | Number of columns in the 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, do not use. Use Sensor displayName instead.

# GoPxL: LMILaserLineProfiler Engine (Gocator Laser Profiler)

LMILaserLineProfiler scan engine documentation applies to the G2xxx sensor family.

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

See Scanner Resources#/scan/engines/(engineId) .

## /scan/engines/LMILaserLineProfiler/visibleSensors

See Scanner Resources#/scan/engines/(engineId)/visibleSensors .

### LMILaserLineProfiler -Specific SensorInfo:

Item | Type | Schema | Description
--- | --- | --- | ---
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.

# /scan/engines/LMILaserLineProfiler/scanners

See Scanner Resources#/scan/engines/(engineId)/scanners .

### LMILaserLineProfiler -Specific 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.

## /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 |  | Scanner parameters that vary depending on the scan engine.
engineId | string | readOnly | The identifier of the scanner's scan engine. 1.1.x.x Added.

### LMILaserLineProfiler -Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
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) .
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/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/disableOutputs | bool | visibility | Disable scanner outputs. Has DEBUG visibility. See Schema and Data Types . 1.0.x.x Moved to scanModeSettings, and reserved for internal use only. 1.1.x.x Replaced "used" keyword with "visibility" set to DEBUG.
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 .
parameters/scanModeSettings/reduceProfileRate | bool | visibility | In surface mode, reduces the profile rate to surface rate, defaults to true. 1.0.x.x Reserved for internal use only.
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/triggerSettings | object |  | See Gocator Scanner - Trigger Settings . LMILaserLineProfiler adds additional trigger settings. 1.0.x.x Renamed to triggerSettings.
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 |  | See Gocator Scanner - Multiplexing . 1.0.x.x Moved to triggerSettings
parameters/triggerSettings/preferMasterTimeEncoderEnabled | bool |  | Prefer master time and encoder. 1.0.x.x Moved to triggerSettings
parameters/filters | object |  | See Gocator Scanner - Filters. 1.0.x.x Added.
parameters/ advancedSettings | object | used | LMILaserLineProfiler advanced scanner parameters. 1.0.x.x Removed.

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

For metrics common across all Gocator scanners, see Gocator Property Groups - Scanner Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/metrics .

LMILaserLineProfiler scanners do not currently have any unique metrics.

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs .

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs/(outputId) .

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

### LMILaserLineProfiler -Specific 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.

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

### LMILaserLineProfiler -Specific 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. See Gocator Alignment - Transform . 1.0.x.x Reserved for future.

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/(contentId) .

### LMILaserLineProfiler -Specific 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. See Gocator Layout - Grid .

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions .

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions/(actionId) .

Software trigger.

Parameters: none

Outputs: none

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors .

### LMILaserLineProfiler -Specific 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.

## /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.
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.

### LMILaserLineProfiler -Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
parameters | object |  | LMILaserLineProfiler scan engine provided additional sensor information.
parameters/activeAreaSettings | object |  | LMILaserLineProfiler active area parameters.
parameters/activeAreaSettings/activeArea | object | extendedType | See GocatorSensor - Active Area Settings . extendedType = TransformedBoxRegion
parameters/activeAreaSettings/tracking | object | visibility | See parameters/Tracking below. 1.0.x.x Reserved for future.
parameters/activeAreaSettings/tracking | object |  | LMILaserLineProfiler active area tracking parameters. 1.0.x.x Parameter group created
parameters/activeAreaSettings/tracking/enabled | bool | readOnly |
parameters/activeAreaSettings/tracking/height | number | minimum, maximum, readOnly |
parameters/activeAreaSettings/tracking/searchThreshold | number |  |
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. This feature is not supported. 1.0.x.x Moved here from parameters/advancedSettings/advanced.
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 subsampling settings. 1.0.x.x Parameter group created, note casing of "subsampling".
parameters/subsamplingSettings/xSubsampling | integer | enum, readOnly, visibility | Decreases profile's X resolution. 1 - 1 2 - 1/2 4 - 1/4 1.1.x.x 'used' option added.
parameters/subsamplingSettings/zSubsampling | integer | enum, readOnly, visibility | Decreases profile's Z resolution. 1 - 1 2 - 1/2 4 - 1/4 (26xx series only) 8 - 1/8 (26xx series only) 1.0.x.x Updated with 1/4 and 1/8 subsampling for 26xx series. 1.1.x.x 'used' option added.
parameters/subsamplingSettings/xSubsamplingDefaultEnabled | bool | readOnly, visibility | Default X subsampling 0 - default is not used.xSubsampling parameter has used value. 1 -use default X subsampling if defined for the sensor model. 1.1.x.x Added.
parameters/subsamplingSettings/zSubsamplingDefaultEnabled | bool | readOnly, visibility | Default Z subsampling 0 - default is not used. zSubsampling parameter has used value. 1 -use default Z subsampling if defined for the sensor model. 1.1.x.x Added.
parameters/advancedSettings | object | visibility | LMILaserLineProfiler advanced settings. 1.0.x.x Added.
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/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> |  | See Gocator Sensor - Camera . 1.0.x.x gammaType does not apply, only analogGain and digitalGain.
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 .
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.

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

For metrics common across all Gocator sensors, see Gocator Property Groups - Sensor Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/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

LMILaserLineProfiler -Specific 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. See Gocator Alignment - Transform .

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions .

# 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

See Scanner Resources#/scan/engines/(engineId) .

## /scan/engines/LMIFringeSnapshot/visibleSensors

See Scanner Resources#/scan/engines/(engineId)/visibleSensors .

### LMIFringeSnapshot-Specific SensorInfo:

Item | Type | Schema | Description
--- | --- | --- | ---
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.

# /scan/engines/LMIFringeSnapshot/scanners

See Scanner Resources#/scan/engines/(engineId)/scanners .

### LMIFringeSnapshot-Specific 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.

## /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 |  | Scanner parameters that vary depending on the scan engine.
engineId | string | readOnly | The identifier of the scanner's scan engine. 1.1.x.x Added.

### LMIFringeSnapshot-Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
parameters | object |  | LMIFringeSnapshot scan engine provided additional scanner information.
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 |  | See Gocator Scanner - Filters. 1.0.x.x Added.

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

For metrics common across all Gocator scanners, see Gocator Property Groups - Scanner Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/metrics .

Item | Internal Type | Type | Description
--- | --- | --- | ---
cudaInUse | bool | boolean | For internal use only. 0 - Cuda in use 1 - Cuda not in use (In Gocator 6.x: Platform Cuda Status, ID: 3007) 1.0.x.x Added.

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs .

## /scan/engines/LMIFringeSnapshot/scanners/(scannerId)/outputs/(outputId)

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs/(outputId) .

## /scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)/(contentId)

(WIP) See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/(contentId) .

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

### LMIFringeSnapshot-Specific 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. See Gocator Alignment - Transform . 1.0.x.x Reserved for future.

## /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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions .

## /scan/engines/LMIFringeSnapshot/scanners/(scannerId)/actions/(actionId)

(WIP) See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/(contentId) .

## /scan/engines/LMIFringeSnapshot/scanners/(scannerId)/actions/trigger

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions/(actionId) .

Software trigger.

Parameters: none

Outputs: none

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

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors .

### LMIFringeSnapshot-Specific 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.

## /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").
parameters | object | readonly | 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 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.

### LMIFringeSnapshot-Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
parameters | object |  | LMIFringeSnapshot scan engine provided additional sensor information.
parameters/activeAreaSettings | object | extendedType | See GocatorSensor - Active Area Settings . extendedType = TransformedBoxRegion 1.0.x.x Renamed toactiveAreaSettings
Exposure Settings |  |  |
parameters/exposureSettings | object |  | 1.0.x.x LMIFringeSnapshot Exposure settings 1.0.x.x Renamed toexposureSettings
parameters/exposureSettings/exposureMode | integer | enum, visibility, readOnly | Exposure mode. 0 - Single exposure 1 -Multipleexposure
parameters/exposureSettings/intensitySequenceIndex | integer | visibility, minimum, maximum, readOnly | 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 | Intensity type, by default combine left and right camera intensity images. 0 - COMBINE (combine both camera intensity images) 1 - LEFT (left camera intensity image) 2 - RIGHT (right camera intensity image)
parameters/ exposureSettings / videoPatternType |  | readOnly | Specifies a preview pattern during live view image capturing (parameters/scanMode = image mode). 0 -Default (white light) 2 - Focus pattern 3 - Scan Sequence (use one of the scan patterns specified by parameters/ videoPatternIndex) 4 -Projector Off (no light, black)
parameters/ exposureSettings / videoPatternIndex | integer | visibility, minimum, maximum, readOnly | Specifies which scan pattern to use when parameters/ exposureSettings/ videoPatternType = 3 (Scan Sequence)
parameters /exposureSettings /singleExposure | number | visibility, minimum, maximum, readOnly | Exposure value (microseconds).
parameters /exposureSettings /multipleExposures | array<number> | minItems, maxItems, 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. See Gocator Sensor - Camera . 1.0.x.x Moved to advancedSettings
Advanced Projector Settings |  |  |
parameters/ advancedSettings/ projectorSettings | object |  | LMIFringeSnapshot projector parameters. 1.0.x.x Moved to advancedSettings
parameters/ advancedSettings/ projectorSettings/ bitDepth | integer | visibility, minimum, maximum, readonly | Current projector pattern bit depth. (Usually 1 or 8 bits). For internal use only.
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 | Power supply voltage settings. 0 - 48 Volt 3 - 24 Volt 1.1.x.x
    powerSettings/cableLength
| number | minimum, maximum | 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, see Gocator Property Groups - Sensor Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/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.

## /scan/engines/LMIFringeSnapshot/scanners/(scannerId)/sensors/(sensorId)/actions

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions .

# 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

See Scanner Resources#/scan/engines/(engineId) .

## /scan/engines/LMIConfocalLineProfiler/visibleSensors

See Scanner Resources#/scan/engines/(engineId)/visibleSensors .

### LMIConfocalLineProfiler-Specific SensorInfo:

Item | Type | Schema | Description
--- | --- | --- | ---
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.

# /scan/engines/LMIConfocalLineProfiler/scanners

See Scanner Resources#/scan/engines/(engineId)/scanners .

### LMIConfocalLineProfiler-Specific 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.

## /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 |  | Scanner parameters that vary depending on the scan engine.
engineId | string | readOnly | The identifier of the scanner's scan engine. 1.1.x.x Added.

### LMIConfocalLineProfiler -Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
parameters | object |  | LMIConfocalLineProfiler scan engine provided additional scanner information.
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) .
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, an intensity value 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 |  | Parameter group containing settings which are relevant whenscanMode = Surface 1.0.x.x Parameter group created
parameters/scanModeSettings/disableOutputs | bool | visibility | Disable scanner outputs. For internal use only.
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
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/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/ 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 |  | See Gocator Scanner - Filters . 1.0.x.x Added.
parameters/advanced | object |  | 1.0.x.x Removed.

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/metrics

For metrics common across all Gocator scanners, see Gocator Property Groups - Scanner Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/metrics .

LMIConfocalLineProfiler scanners do not currently have any unique metrics.

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/outputs

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs .

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/outputs/(outputId)

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/outputs/(outputId) .

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/alignment

### LMIConfocalLineProfiler-Specific 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.

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/transform

### LMIConfocalLineProfiler-Specific 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. See Gocator Alignment - Transform . 1.0.x.x Reserved for future.

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/actions

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions .

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/actions/trigger

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/actions/(actionId) .

Software trigger.

Parameters: none

Outputs: none

# /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors .

### LMIConfocalLineProfiler-Specific 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.

## /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 | readonly | 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 | 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.

### LMIConfocalLineProfiler-Specific Properties

Item | Type | Schema | Description
--- | --- | --- | ---
parameters | object |  | LMIConfocalLineProfiler scan engine provided additional sensor information.
parameters/ activeAreaSettings | object | extendedType | See GocatorSensor - Active Area Settings . extendedType = TransformedBoxRegion 1.0.x.x Name changed from activeArea to activeAreaSettings
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/zSubsampling | integer | enum, readOnly | Decreases profile's Z resolution. 1 - 1 2 - 1/2
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 |  | SeeLMIConfocalLineProfiler Scanner - Layer Specific Params below. 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> | used | 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/clusteringParams | object | visibility | Short cluster removal. 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 .
parameters/advancedSettings/spotDetection/intensityWindow | integer | enum, readOnly, actual | Window size for spot intensity calculation (px).
parameters/advancedSettings/spotDetection/threshold | integer | minimum, maximum, actual, readOnly | Threshold to tell whether pixel is within spot.

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)/metrics

For metrics common across all Gocator sensors, see Gocator Property Groups - Sensor Metrics .

For details on how to read & stream these metrics, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/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

LMIConfocalLineProfiler-Specific 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. See Gocator Alignment - Transform .

## /scan/engines/LMIConfocalLineProfiler/scanners/(scannerId)/sensors/(sensorId)/actions

See Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions .

# 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
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. 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 | Tool ID. This id should never be parsed or interpreted by any client. Tool id's are picked by the application according to unpredictable mechanisms. Do not rely on the format.
type | 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).
batched | boolean | readOnly | Whether the tool is currently batched or not. 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. Basically a tool that can be batched can be unbatched. Technically isBatchable being false doesn't prevent the system from batching the tool. However the system will not start with a non-batchable tool being batched Clients should prevent the option of batching tools with isBatchable being false. 1.0.x.x Added
parameters | object |  | Custom parameters specific to the tool.
inputs | ToolInput[] |  | Array of tool inputs.
outputs | ToolOutput[] |  | Array of tool outputs.

### 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 |  | User configurable display name of the tool input.
extId | string |  | User configurable external id of the tool input.
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.
displayName | culture-specific string |  | User configurable display name of the tool output.
extId | string |  | User configurable external id of the tool output.
dataSourceId | string | readOnly | Id of the output (e.g., tools:Tool1:outputs:Output0)used for identifying outputs in the backend framework when the output is enabled. If the output is disabled, it will be an empty string.
enabled | bool |  | Whether or not the output is enabled.
recordingEnabled | bool |  | 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)

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%
<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. |  |  |  |
/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
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
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
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
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

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
          }
        },
        "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 |  | User configurable display name of the tool action.
extId | string |  | User configurable external id of the tool action.

### Methods

Method | Description
--- | ---
call | Calls the custom tool action. Path parameters: extId Arguments are currently not supported for custom tool actions. Example:
    call /tools/TestActions-0/actions/FlipBool
Call a tool action by path parameter extId:
    call /tools/TestActions-0/actions/extId=My%20Tool%20Action

### 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

GoPxL Data Protocol Service

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

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",
        "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

GoPxL Data Protocol Service 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, i.e., sensor stopped scanning
- All GDP outputs unselected.
- No GDP clients, i.e., 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

Outputs Map Resource

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.
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.

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"
          }
        ]
      },
      "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

Outputs Map 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

Outputs Map Add Command

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

Outputs Map AddAll Command

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.

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

Outputs Map CompactId Command

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

Outputs Map Remove Command

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 | Mandatory | The output id of the data source to remove from the outputs map

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}
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

Outputs Map RemoveAll Command

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

Outputs Map UpdateId Command

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

HMI Service

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 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"
            }
          ],
          "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

HMI Service 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

HMI Service Output Map

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/outputId | string |  | A unique text identifier for the data source.
map/n/source | string |  | Data source identifier.

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": []
      },
      "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

Outputs Map 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

Outputs Map Add Command

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.

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"}
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

Outputs Map AddAll Command

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

Outputs Map CompactId Command

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

Outputs Map Remove Command

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 | string | Mandatory | The output identifier of the data source to remove from the outputs map

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"}
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

Outputs Map RemoveAll Command

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

Outputs Map UpdateId Command

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

HMI Service 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 renamed the "actions" to "commands".

1.1.x.x added "discardWorkspace" command.

1.1.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

HMI Application Activate Command

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 removed the "deactivate" command.

# /controls/hmi/commands/createApp

HMI Application Create Application Command

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

HMI Application Remove Application Command

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

HMI Application Download Application Command

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

HMI Application Upload Application Command

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

HMI Application Discard Command

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 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

Modbus Service

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

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",
        "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

Modbus Service 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

Register Assemblies Resource

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

Register Assembly Resource Description

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.This is the name that a client should display to the user.
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 ).
displayName | string |  | Display name of the register assembly
id | string |  | Register assembly internal identifier
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 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/maxInstance | integer |  | Maximum number of instances of this register block type that this register assembly can have.
supportedBlockTypes/n/minInstance | 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/maxInstance | integer | readOnly | Value for each supported register block type internal identifier: "ControlInput": 1 "ControlOutput": 1 "Measurement": 950 "Scanner": 1 "Stamp": 167 "System": 1
supportedBlockTypes/n/minInstance | integer | readOnly | Value for each supported register block type internal identifier: "ControlInput": 1 "ControlOutput": 1 "Measurement": 0 "Scanner": 1 "Stamp": 0 "System": 1
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "ControlInput" "ControlOutput" "Measurement" "Scanner" "Stamp" "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/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/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"
          },
          {
            "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:PointCount",
            "displayName": "Profile Info 1 / Point Count",
            "outputId": 150,
            "scannerId": "",
            "type": "Measurement"
          }
        ],
        "displayName": "Register Assembly 0",
        "id": "registerAssembly-0",
        "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

Register Assembly 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/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

Register Assembly Add Command

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

Register Assembly Remove Command

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/compact

Register Assembly Compact Command

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

Register Assembly Update Command

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

Ethernet ASCII Service

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 |  | 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. 0.3.x.x added this parameter.
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 = 0, maximum = 65534 | 16-bit port number of TCP connection used to connect to the Ethernet ASCII service. 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

Ethernet 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

Register Assemblies Resource

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

Register Assembly Resource Description

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.This is the name that a client should display to the user.
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 ).
displayName | string |  | Display name of the register assembly
id | string |  | Register assembly internal identifier
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 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/maxInstance | integer |  | Maximum number of instances of this register block type that this register assembly can have.
supportedBlockTypes/n/minInstance | 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 4, 5, 6 are supported.
supportedBlockTypes/n/maxInstance | integer | readOnly | Value for each supported register block type internal identifier: "Measurement": 65534 "Scanner": 1 "Stamp": 65534
supportedBlockTypes/n/minInstance | integer | readOnly | Value for each supported register block type internal identifier:: "Measurement": 0 "Scanner": 0 "Stamp": 0
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "Measurement" "Scanner" "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/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/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": [],
        "displayName": "Register Assembly 0",
        "id": "registerAssembly-0",
        "supportedBlockTypes": [
          {
            "category": 4,
            "displayName": "Sensor Group State",
            "hasDataSource": false,
            "instanceCount": 0,
            "maxInstanceCount": 1,
            "minInstanceCount": 0,
            "registerCount": 18,
            "type": "Scanner"
          },
          {
            "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

Register Assembly 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/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

Register Assembly Add Command

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

Register Assembly Remove Command

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/compact

Register Assembly Compact Command

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

Register Assembly Update Command

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

EtherNet/IP Protocol

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

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",
        "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

EtherNet/IP Protocol 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

EtherNet/IP Register Assemblies

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)

Register Assembly Resource Description

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.This is the name that a client should display to the user.
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 ).
displayName | string |  | Display name of the register assembly
id | string |  | Register assembly internal identifier
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 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/maxInstance | integer |  | Maximum number of instances of this register block type that this register assembly can have.
supportedBlockTypes/n/minInstance | 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

EtherNet/IP Protocol 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 67.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/commandInput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/commandInput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 67,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Control Input",
            "outputId": 0,
            "scannerId": "",
            "type": "ControlInput"
          }
        ],
        "displayName": "Command Input",
        "id": "commandInput",
        "supportedBlockTypes": [
          {
            "category": 1,
            "displayName": "Control 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

EtherNet/IP Protocol 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 3.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/commandOutput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/commandOutput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 3,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Control Output",
            "outputId": 0,
            "scannerId": "",
            "type": "ControlOutput"
          }
        ],
        "displayName": "Command Output",
        "id": "commandOutput",
        "supportedBlockTypes": [
          {
            "category": 2,
            "displayName": "Control 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

EtherNet/IP Protocol 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 67.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/implicitCommandInput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 67,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Control Input",
            "outputId": 0,
            "scannerId": "",
            "type": "ControlInput"
          }
        ],
        "displayName": "Implicit Command Input",
        "id": "implicitCommandInput",
        "supportedBlockTypes": [
          {
            "category": 1,
            "displayName": "Control 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

EtherNet/IP Protocol 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 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/maxInstance | integer | readOnly | Value for each supported register block type internal identifier: "MeasurementValue": 65534 "Stamp": 65534
supportedBlockTypes/n/minInstance | integer | readOnly | Value for each supported register block type internal identifier: "MeasurementValue": 0 "Stamp": 0
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "MeasurementValue" "Stamp" 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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/scanOutput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/scanOutput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 375,
          "outputIdMin": 0
        },
        "blocks": [],
        "displayName": "Scan Output",
        "id": "scanOutput",
        "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

EtherNet/IP Protocol 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 504.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/scannerState/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/scannerState"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 504,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Sensor Group State",
            "outputId": 0,
            "scannerId": "",
            "type": "Scanner"
          }
        ],
        "displayName": "Sensor Group State",
        "id": "scannerState",
        "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

EtherNet/IP Protocol 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 76.
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 4.
supportedBlockTypes/n/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/ethernetIp/registerAssemblies/systemState/commands/update"
            }
          ],
          "self": {
            "href": "/controls/ethernetIp/registerAssemblies/systemState"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 76,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "System State",
            "outputId": 0,
            "scannerId": "",
            "type": "System"
          }
        ],
        "displayName": "System State",
        "id": "systemState",
        "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

Register Assembly 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/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

Register Assembly Add Command

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

Register Assembly Remove Command

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/compact

Register Assembly Compact Command

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

Register Assembly Update Command

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

Profinet Protocol

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 "PROFINET"
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"
          }
        },
        "displayName": "PROFINET",
        "enabled": true,
        "id": "profinet",
        "parameters": {},
        "status": 0
      },
      "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

Profinet Protocol 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

Profinet Register Assemblies

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)

Register Assembly Resource Description

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.This is the name that a client should display to the user.
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 ).
displayName | string |  | Display name of the register assembly
id | string |  | Register assembly internal identifier
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 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/maxInstance | integer |  | Maximum number of instances of this register block type that this register assembly can have.
supportedBlockTypes/n/minInstance | 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

Profinet Protocol 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 67.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/commandInput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/commandInput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 67,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Command Input",
            "outputId": 0,
            "scannerId": "",
            "type": "ControlInput"
          }
        ],
        "displayName": "Command Input",
        "id": "commandInput",
        "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

Profinet Protocol 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 3.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/commandOutput/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/commandOutput"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 3,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Command Output",
            "outputId": 0,
            "scannerId": "",
            "type": "ControlOutput"
          }
        ],
        "displayName": "Command Output",
        "id": "commandOutput",
        "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

Profinet Protocol 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 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/maxInstance | integer | readOnly | Value is set to 65534.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to zero (0).
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/stamp/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/stamp"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 35,
          "outputIdMin": 0
        },
        "blocks": [],
        "displayName": "Stamp Scan Output",
        "id": "stamp",
        "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

Profinet Protocol 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 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/maxInstance | integer | readOnly | Value is set to 65534.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to zero (0).
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/measurement/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/measurement"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 799,
          "outputIdMin": 0
        },
        "blocks": [],
        "displayName": "Measurement Scan Output",
        "id": "measurement",
        "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

Profinet Protocol 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 18.
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/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/scannerState/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/scannerState"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 18,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "Sensor Group State",
            "outputId": 0,
            "scannerId": "",
            "type": "Scanner"
          }
        ],
        "displayName": "Sensor Group State",
        "id": "scannerState",
        "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

Profinet Protocol 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 76.
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 4.
supportedBlockTypes/n/maxInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/minInstance | integer | readOnly | Value is set to 1.
supportedBlockTypes/n/type | string | readOnly | Supported register block type internal identifier: "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/compact"
            },
            {
              "href": "/controls/profinet/registerAssemblies/systemState/commands/update"
            }
          ],
          "self": {
            "href": "/controls/profinet/registerAssemblies/systemState"
          }
        },
        "attributes": {
          "isGlobalAddressSpaceUsed": true,
          "outputIdMax": 76,
          "outputIdMin": 0
        },
        "blocks": [
          {
            "displayName": "System State",
            "outputId": 0,
            "scannerId": "",
            "type": "System"
          }
        ],
        "displayName": "System State",
        "id": "systemState",
        "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

Register Assembly 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/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

Register Assembly Add Command

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

Register Assembly Remove Command

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/compact

Register Assembly Compact Command

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

Register Assembly Update Command

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: 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

Contains a list of routine types available to the system.

For description of routine types available, see Routine Resources .

ToolType Schema:

Item | Type | Schema | Description
--- | --- | --- | ---
description | string | readOnly | Describes the function and purpose of the routine.
displayName | culture-specific string | readOnly | Name of the routine. e.g: "Simple test routine", "Alignment prototype routine".
helpHtml | string | readOnly | Html help string for this routine. If both helpURL and helpHtml is specifiedhelpURL will take precedence.
helpUrl | string | readOnly | Html help URL string for this routine. If both helpURL and helpHtml is specifiedhelpURL will take precedence.
type | string | readOnly | The name of this routine's type, e.g., "Simple", "Alignment".

Methods

Method | Description
--- | ---
read | Reads the list of routine types available. Example:
    read /routineTypes

# /routines

Resource Type:

A collection of routines.

Methods

Method | Description
--- | ---
read | Read all routines loaded in the system. Example:
    read /routines {"expandLevel": -1}
create | Adds a routine instance into the system. Arguments:
Item | Type | Description
--- | --- | ---
type | string | The routine type of interest to add. A list of tool types will be able to be obtained from the /routineTypes resource
Examples:
    create /routines {"type": "Alignment"}

### Notifications

Event Type | Description
--- | ---
updated | Occurs when all the routines are deleted at once using the wildcard (*)in the delete command Example:
    {"eventType": "updated", "path": "/routines"}

## /routines/(routineId)

Resource Type: (CollectionItem)

ID: auto generated when the routine is first added

NOTE: Each routine should share the following common properties, but the schema for each routine within the collection may be different due to different 'parameters'.
All items are read only except parameter items which can be modified prior to running of the routine's processing.

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, minimum | 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 the routine.
displayName | culture-specific string | readOnly | Display name of the routine.
helpHtml | string | readOnly | Help info (in html) about the tool.
id | string | readOnly | Id of the instance of the routine.
parameters | object |  | Modifiable parameters of the routine. Dependent on the specific routine type.
results | object | readOnly | Results returned after performing the routine. Dependent on the specific routine type.
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, minimum | Total steps in the alignment process.
type | string | readOnly | Type of the routine.

### Methods

Method | Description
--- | ---
read | Read a specific routine. Example:
    read /routines/routineId {"expandLevel": -1}
update | Update a specific routine's parameters. Arguments:
Item | Type | Description
--- | --- | ---
parameter | string | The routine parameters to alter.
Examples: Update routine's delay parameter:
    update /routines/routineId {"parameters": {"delay": 2000000}}
Update multiple routine properties at once:
    update /routines/routineId {"parameters": {"delay": 2000000, "delayMul": 200}}
delete | Deletes a routine from the system, typically when the routine is completed or aborted.The path to the routine instance must be provided. Examples: Delete a single routine:
    delete /routines/routineId
A special wildcard formapplies to this delete method. The path of this routines command can be wildcarded to delete all routines:
    delete /routines/*

### Notifications

Event Type | Description
--- | ---
created | Occurs when a new routine is added. The path indicates the new routine id. Example:
    {"eventType": "created", "path": "/routines/routineId"}
updated | Occurs whenever routine's parameters change. The path indicates the affected routine id. Example:
    {"eventType": "updated", "path": "/routines/routineId"}
deleted | Occurs whenever a routine is deleted, usually after the routine is completed or aborted. The path indicates the routine id that was deleted. Example:
    {"eventType": "deleted", "path": "/routines/routineId"}

## /routines/(routineId)/commands/continue

Resource Type: ( Callable )

### Methods

Method | Description
--- | ---
call | Command to continue with the actual processing of routine. Typically called after parameter(s) have all been set up and the routine can proceed with it's processing to completion. Example(s):
    call /routines/routineId/commands/continue

## /routines/(routineId)/commands/abort

Resource Type: ( Callable )

### Methods

Method | Description
--- | ---
call | Command to abort the processing of the routine. Example(s):
    call /routines/routineId/commands/abort

# 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 .

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" : "Alignment" }
update | Update the alignment routine with the scan engine and scanner id to use for alignment. If this command is skipped, it default to use the "LMILaserLineProfiler" scan engine and the first available scanner in the engine, usually "scanner-0". Example:
    update /routines/Alignment-0 {"parameters" : {"scannerEngineId" : "LMILaserLineProfiler", "scannerId" : "scanner-0"}}
call /routines/*id*/commands/continue | Proceed with the configuration or actual performing of the alignment once the routine target(s) has been configured. Example:
    call /routines/Alignment-0/commands/continue
call /routines/*id*/commands/abort | Abort the performing of the alignment process. Example:
    call /routines/Alignment-0/commands/abort
delete | Delete the alignment routine. 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
--- | --- | ---
Create an instance of the alignment routine |
    create /routines{"type" : "Alignment"}
| state = WAITING (2) currentStep = 1 currrentProgress = 0 result ={}
2. Update scanner engine id and scanner id to use for alignment - optional as "LMILaserLineProfiler" and "scanner-0" are the defaults. |
    update /routines/Alignment-0 {"parameters" : {"scannerEngineId" : "LMILaserLineProfiler", "scannerId" : "scanner-0"}}
| state = WAITING (2) currentStep = 1 currrentProgress = 0 result ={}
3. Continue to the next alignment routine step to set up the alignment target parameters. |
    call /routines/Alignment-0/commands/continue
| state = WAITING (2) currentStep = 2 currentProgress = 0 result ={}
4. Configure the routine's parameters for alignment (e.g., set alignment type to moving alignment) |
    update /routines/Alignment-0{ "parameters" : {"motionType" : {"alignmentType" : 1}}}
| state = WAITING (2) currentStep = 2 currentProgress = 0 result ={}
5. Configure moving alignment target to moving disk |
    update /routines/Alignment-0{ "parameters" : {"formatType" : {"movingTarget" : 1}}}
| state = WAITING (2) currentStep = 2 currentProgress = 0 result ={}
6. Configure moving disk parameters |
    update /routines/Alignment-0{ "parameters" : {"formatType" : {"movingDiskParams" :
       {"properties" : {"height" : 15.0, "diameter" : 40.0}}}}}
| state = WAITING (2) currentStep = 2 currentProgress = 0 result ={}
7. Start alignment process |
    call /routines/Alignment-0/commands/continue
| state = RUNNING (1) currentStep = 2 currentProgress = 0 result ={}
8. Wait for progress notification events |
    "updated", "path" : "/routines/Alignment-0"repeatedly every few seconds
| state = RUNNING (1) currentStep = 3 currentProgress = 0 - 100 in 5 steps of 20% result ={}
9. Wait for completion of alignment process |
    "updated", "path" : "/routines/Alignment-0"
| state = DONE (3) currentStep = 3 currentProgress = 100 result ={status, xOffset, yOffset, zOffset, xAngle, yAngle, zAngle}
10. Remove routine |
    delete /routines/Alignment-0

#

# GoPxL 1.0 - 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 ours API is currently not a true 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 (e.g., the relationship between "/tools" and its child "/tools/toolId") or in the form of a map ( e.g., 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 Resource Design and Request Methods#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 Gocator 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/LMILaserLineProfiler{}{"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.

For more information, see REST API Update method now performs an internal patch for clients

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://cloud.google.com/apis/design/custom_methods

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. The properties exposed on a readable callable resource (and possibly the schema associated with these properties) represent the arguments (and their types) that can be provided to that resource when it is called. In this way, clients can dynamically query both the list of available callable resources (within an action collection) as well as the arguments accepted for each.

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 arguments supported for a particular callable resource
    READ /path/to/actions/callable1
    >> {
      "path" : "/path/to/actions/callable1",
      "payload": {
        "_links": {
          "self": {
            "href": "/path/to/actions/callable1"
          }
        },
        "_schema": {
          "properties": {
            "arg1": {
              "title": "Argument 1",
              "type": "boolean",
              "description": "This is the first argument."
            },
            "arg2": {
              "title": "Argument 2",
              "type": "string",
              "description": "This is the second argument."
            }
          },
          "type": "object"
        },
        "arg1": false,
        "arg2": "Default 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": true, "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/callable1
    >> {
      "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://cloud.google.com/apis/design/custom_methods

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://cloud.google.com/apis/design/custom_methods

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"` `:` `"[json.exception.type_error.302] type must be string, but is number"` `,` `` `"status"` `:` `0` `` `}` `` `]` `` `},` `` `"status"` `:` `0` `,` `` `"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:

Expand source

    /*! @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 (see Health Data ).

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:

Expand source

    ======== 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 the Streaming 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:

Expand source

    /**
     * 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 uniuqe 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

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).
reserved | 64u | Reserved.

### 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 (nm). X scale ( mm ).
zScale | 64f | Z scale (nm). Z scale ( mm ).
xOffset | 64f | X offset (m). X offset ( mm ).
zOffset | 64f | Z offset (m). 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 (nm). (scaled by 1000000) X scale (mm).
yScale | 64f | Y scale (nm). Y scale (mm).
zScale | 64f | Z scale (nm). Z scale (mm).
xOffset | 64f | X offset (m). (scaled by 1000) X offset (mm).
yOffset | 64f | Y offset (m). Y offset (mm).
zOffset | 64f | Z offset (m). 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 (e.g., 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 ( i.e., 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. Fo Table r 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 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://tools.ietf.org/html/rfc3986#section-3 )

For the purposes of discussion in Resource Reference , we use "path" as a looser term in line with its componentized meaning and in line with the term " Relative URI " discussed in the Resource Design .

## 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://tools.ietf.org/html/rfc6570#section-3.2.2 and https://swagger.io/docs/specification/serialization/#path .

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://tools.ietf.org/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.

## Method 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.

## Read Traits

### 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 /scanners/commands
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] }

### 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 Documentation Conventions#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 (e.g., 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 . 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:

- Does not support all standard validation keywords
- Does not support all standard annotation keywords
- No support for schema references (using the $ref keyword)
- No support for applying schemas conditionally
- No support for applying schemas logically
- Most format specifiers are not supported
  - In fact, GoPxL has defined a few non-standard format specifiers

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 Array contains a single type of the above list (e.g., ["object"]). This has no effect - an array containing a single type can be treated as a single type 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 (i.e., 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 will be converted into an object with the following form: { bytes: number[], subtype: number } Each byte of the original binary data will be converted into a number and the whole binary instance will be sent as a standard JSON array. Subtype is associated with msgPack's ext format which is not used by GoPxL. This field can be ignored. 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.
visibility | Annotation | integer | Replaces the 'used' keyword. Bitmask of discrete visibility types that indicate a property's visibility. If this keyword is absent, the associated property is assumed to be visible. Visibility bitflags: 0x01 - HIDDEN 0x02 - ADVANCED 0x04 - EXPERIMENTAL 0x08 - DEBUG 0x10 - DEPRECATED 0x20 - INTERNAL For example, to test if visibility is ADVANCED would involve bitwise operations such as `"isAdvanced = visibility & 0x02"` . Multiple visibility types can be in effect at once, for example, a property can be ADVANCED and DEBUG with a bitflag representation of `"0x0A"` ( `0x02 & 0x08).` 1.1.x.x Keyword a dded.
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.

### 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.

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.

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 are typically Group sbut not always. 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"
    }

### Group

Base type : object

Extended type: <empty string> or not specified

A group contains properties - it is a parent container for parameters.

All base keywords apply to groups. In particular, the "title" keyword contains a short description for the group, which can be used to name the group of controls in the UI.

A group is really just an "object" defined above in "container types" but it is defined here as a base for many (but not all) extended types.

Group Schema Document Example

    {
      "type": "object",
      "properties": {
        "propA": {
          "type": "number"
        },
      },
      "title": "My Group (which is just an object)"
    }

### 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 classes that are derived from BoxRegion such as ProfileRegion and SurfaceRegion2d but these classes are just the BoxRegion with defaults for optional params set differently.

### BaseBoxRegion

Base type: group

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

Derived 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

Derived 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 : Group

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"
        }
      }
    }

# 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 | kStatus | 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 ypically3196 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 (e.g., 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 (e.g., 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.

## 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. 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.

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. It is based on the Resource Request Protocol Design .

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.1.x.x removed payload from notifications.
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. Carrier Message Layer
3. Control Message Layer
4. Control Message Content

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:

    http://<IP Address>:<Web Port>/ws/controlAsync

Normally, the Web Port is 80, but it can vary to avoid conflicts.

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, e.g., "/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. Notification type messages
3. Stream type messages

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. 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"
    }

    {
      "path" : "/jobs/files/myJob/data",
      "payload": [binary data],
      "status": 1,
      "type": "binaryResponse" //future response type
    }

### 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

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:LMILaserLineProfiler:scanner-0:top:profile:uniform/data"

    {
      "path": "/dataSources/scan:LMILaserLineProfiler: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 or configuration implements an older version of the protocol than GoPxL .
- Backwards Compatibility: Where a client or configuration implements a newer version of the protocol than GoPxL .

## 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.

Here is an example of resource change documentation

And an example of property change documentation

# 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
--- | --- | --- | --- | --- | ---
0.2 | 0.2.1.53 | General Release (for G5 support) | 1.0.0 | 7.0.0.0 | n/a
0.3 | 0.3.5.24 | Evaluation Release | 2.0.0 | 8.0.0.0 | n/a
1.0 | 1.0.109.203 | Public Release 1.0 | 3.0.0 | 8.0.9.145 | 3.0.0
1.0 SR1 | 1.0.110.37 | Public Release 1.0 SR1 | 3.0.0 | 8.0.10.42 | 3.0.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.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.1 (2024-Apr) | 1.1.11.1 | Public Release 1.1 (2024-Apr) | 4.0.0 | 8.1.12.75 | 4.0.0

"Protocol Version" coincides with what is reported on the /version resource