GoPxL 1.0 - REST API Resources and User Guide

Table of Contents

Resource Reference User Guide

System Resources

/version

Resource Type: N/A

Reports 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 (i.e., sensor is started, stopped, etc.)

Example:

{ "eventType": "updated", "path": "/system",
  "content": {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.

Arguments:

Item Type Description
skipValidation bool Whether to skip upgrade validation or not. Default value is "false".
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.

Changed in 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 System Resources#/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.

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)

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 does during Support > Download:

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

To recreate what the GUI does during 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 or AppInfo.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"

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. g2xxx. 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/maxSafeInteger k64s integer

Should be value of

9007199254740991 // (2^53)-1;

Allows us to test for max safe integer pass through in JSON and javascript see https://developers.google.com/discovery/v1/type-format




advanced/maxSafeIntegerPlus k64s integer

Should be value of

9007199254740992 // (2^53);

Allows us to test for max safe integer pass through in JSON and javascript see https://developers.google.com/discovery/v1/type-format




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 3210 by default)


advanced/hostPorts/n/streamQueueCount k64u integer

stream queue count.

This metric tracks the current queue count of the stream queue.


advanced/hostPorts/n/responseQueueCount k64u integer

response queue count.

This metric tracks the current queue count of the response queue.


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 about network 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 network configuration can be updated.

/environ/info

Resource Type: N/A

Description

Contains information about runtime (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. 

Changed in 1.0.x.x  Resource added.

Properties

Item Type Schema Description
applicationType integer

enum,

readOnly
Enumeration of different application types:
  • 0: Gocator Sensor
  • 1: GoPxl on PC
  • 2: GoMax

Changed in 1.0.x.x Added.

controllerType integer

enum,

readOnly
Enumeration of different controller types:
  • 0: Unknown Controller
  • 1: Virtual Controller
  • 2: M2 Controller
  • 3: M3 Controller
  • 4: M1 Controller
  • 5: M50 Controller
  • 6: M3 UC Controller
  • 7: TX2 Controller
  • 8: Xavier NX Controller
  • 9: M4 Controller
  • 10: M5 Controller

Changed in 1.0.x.x Added.

partNumber string readOnly

Model of the sensor. 

Changed in 1.0.x.x Added.
serialNumber string readOnly

Unique serial number of a sensor. 

Changed in 1.0.x.x Added.
version string readOnly

Version of the sensor firmware.

Changed in 1.0.x.x Added.
model string readOnly

Model name of the sensor.

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

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

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
}

/problems

Resource Type: (Collection - Unordered)

Contains a list of currently active problems that are updated on start/simulate of the sensor.  Note that this is not 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",
  "content": {updated /problems collection} }

/logs

Resource Type: N/A

ID: Auto-generated

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

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

Each log message has has common scheme elements listed below:

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

Log level (warn, info, etc.)

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


Methods

Method Description
read

Reads the /logs collection.

Payload:

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

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

Examples:

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

/logs/commands/clear

Resource Type: (Callable)

Methods

Method Description
call

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

Example:

call /logs/commands/clear

/logs/summary

Resource Type:  N/A

Attribute Type Description

idStart

integer ID of the first available log

idEnd

 integer ID of the last available log

Methods

Method Description
read

Reads the /logs/summary information.

Examples:

read /logs/summary

Notifications

Event Type Description
updated

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

Example:

{ "eventType": "updated", "path": "/logs/summary",
  "content": {updated /logs idStart and idEnd} }

Job 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",
  "content": {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
name string Name of the new job file.
content binary Specify the raw binary content of the new job.

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",
  "content": {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", 
  "content": {new job properties} }
updated

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

Example:

{ "content": {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.

Data 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, most of the common buffer info is contained within /replay and some discussion should be had on whether to move some of the properties here.

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 streamable 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., "g2xxx", "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.
filtering ReplayFiltering Replay filtering settings. This is work in progress and should not be used.

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

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

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

Changed in 1.0.x.x

Example:

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

/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 Keywords 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:output: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",
  "content": {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",
  "content": {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: N/A

Access the data for the dataSource. This resource can only be streamed.

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:outputs:Output0/data {"period": 250000}
stream /dataSources/tools:TestForward-0:outputs:Output0/data {"streamLastFrame":true}

Scan Resources

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

/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 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., "g2xxx".
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": "g2xxx",
      "isLocal": false,
      "model": "2330",
      "parameters": {
        "ipAddress": "90.23.50.45",
        "optionCode": 1
      },
      "serialNumber": "45045",
      "version": "1.0.0.0"
    },
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "g5xxx",
      "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/g2xxx"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g3xxx"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g5xxx"
          }
        }
      },
      {
        "_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. "g2xxx".
maxSensorCount readOnly, minimum, used integer

Max sensor count.

Changed in 1.0.x.x Added.

Methods

Method Description
read

Reads a specific scan engine.

Example response:

{
  "_links": {
    "self": {
      "href": "/scan/engines/g2xxx"
    }
  },
  "displayName": "Gocator Laser Profiler",
  "id": "g2xxx",
  "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., "g2xxx".
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": "g2xxx",
      "isLocal": false,
      "model": "2330",
      "parameters": {
        "ipAddress": "90.23.50.45",
        "optionCode": 1
      },
      "serialNumber": "45045",
      "version": "1.0.0.0"
    },
    {
      "connectionMessage": "",
      "connectionStatus": 0,
      "engineId": "g2xxx",
      "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/g2xxx/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/g2xxx/scanners/scanner-0"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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 identifier of the scanner within the collection (e.g., "scanner-0").
parameters object Scanner parameters that vary depending on the scan 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/g2xxx/scanners/scanner-0/alignment"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/layout"
          }
        }
      }
    ],
    "go:output": [  // see /scan/engines/(engineId)/scanners/(scannerId)/outputs
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/sensor-0:profile"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/stamp"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/top:profile"
          }
        }
      }
    ],
    "go:sensor": [  // see /scan/engines/(engineId)/scanners/(scannerId)/sensors
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-1"
          }
        }
      }
    ]
  },
  "_links": {
    "go:action": [  // see /scan/engines/(engineId)/scanners/(scannerId)/actions
      {
        "href": "/scan/engines/g2xxx/scanners/scanner-0/actions/autoLayout"
      },
      {
        "href": "/scan/engines/g2xxx/scanners/scanner-0/actions/trigger"
      }
    ],
    "self": {
      "href": "/scan/engines/g2xxx/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/g2xxx/scanners/scanner-0 { "parameters": { "uniformSpacingEnabled": true } }
delete

Deletes the scanner resource.

Example request: 

delete /scan/engines/g2xxx/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/g2xxx/scanners/scanner-0"}
updated

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

Example notification:

{ "eventType": "updated", "path": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/scanners/scanner-0/metrics

which for example, returns:

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/g2xxx/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/g2xxx/scanners/scanner-0/metrics
cancelStream

Cancel continuous stream of scanner metrics.

Example:

cancelStream /scan/engines/g2xxx/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 outputs as embedded resources.

Example response:

{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/sensor-0:profile"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/stamp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/top:profile"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/scan/engines/g2xxx/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:g2xxx: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.

Changed in 0.3.x.x

Methods

Method Description
read

Returns the output parameters described above.

Example response:

{
  "_links": {
    "self": {
      "href": "/scan/engines/g2xxx/scanners/scanner-0/outputs/stamp"
    }
  },
  "dataFormat": {
    "arrayed": false,
    "type": 8
  },
  "dataSourceId": "scan:g2xxx: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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/scanners/scanner-0/layout

Example response:

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

Updates the custom scanner content resource.

Example request:

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

Notifications

Notification Description
updated

Occurs when the custom scanner content resource changes.

Example notification:

{ "eventType": "updated", "path": "/scan/engines/g2xxx/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

Changed in 1.0.x.x Aligns the scanner. 

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/g2xxx/scanners/scanner-0/commands/align {"interactive":false}

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

Changed in 1.0.x.x Cancels scanner alignment.

Example request

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

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/g2xxx/scanners/scanner-0/commands/clearAlign

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/g2xxx/scanners/scanner-0/sensors/sensor-0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-1"
            }
          }
        }
      ]    },
    "_links": {
      "self": {
        "href": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/scanners/scanner-0/sensors/sensor-0/alignment"
          }
        }
      }
    ],
  },
  "_links": {
    "go:actions": [ // see /scan/engines/(engineId)/scanners/(scannerId)/sensors/(sensorId)/actions
      {
        "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
      },
      {
        "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
      },
      {
        "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
      },
    ],
    "self": {
      "href": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/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, but the Gocator-specific ones will be listed here.

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/g2xxx/scanners/0/sensors/sensor-0/metrics

which for example returns:

{
  "payload": {
    "_links": {
      "self": {
        "href": "/scan/engines/g2xxx/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/g2xxx/scanners/0/sensors/sensor-0/metrics
cancelStream

Cancel continuous stream of sensor metrics.

Example:

cancelStream /scan/engines/g2xxx/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/g2xxx/scanners/scanner-0/sensors/sensor-0/alignment

Example response:

{
  "_links": {
    "self": {
      "href": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/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/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/setAddress"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/upgrade"
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/resetActiveArea"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/scan/engines/g2xxx/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/g2xxx/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/g2xxx/scanners/scanner-0/sensors/sensor-0/actions/setAddress {"address": "90.23.50.45, "dhcpEnabled": false, ...}

Notifications

None.

Property groups

This section 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 "trigger/lightSleep" resource.

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.3.10 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 (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)

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

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

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

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

Changed in 1.0.x.x Added readOnly.
z number minimum, maximum, readOnly

Z center (mm).
width number minimum, maximum, readOnly

X extent (mm).

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

Changed in 1.0.x.x Added readOnly.
height number minimum, maximum, readOnly

Z extent (mm).

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

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.

G2 Scan Engine - Gocator Laser Profiler

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

/scan/engines/g2xxx

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

/scan/engines/g2xxx/visibleSensors

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

G2-Specific SensorInfo:

Item Type Schema Description
parameters object readOnly

G2 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/g2xxx/scanners

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

G2-Specific Properties

Item Type Schema Description

creationParams

 object readOnly

G2 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/g2xxx/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 identifier of the scanner within the collection (e.g., "scanner-0").
parameters object
Scanner parameters that vary depending on the scan engine.

G2-Specific Properties (scanner)

Item Type Schema Description

parameters

 object

G2 scan engine provided additional scanner information.
parameters/family integer readOnly, used

Sensor family.

  • 2 - G2 (Gocator laser profiler)

Changed in 1.0.x.x Removed.
parameters/runningState integer

readOnly, used, enum

Run state.

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

Changed in 1.0.x.x Removed.
parameters/maxSensorCount integer

readOnly,

minimum, used

Max sensor count.

 Supported maxSensorCount is 31.

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

parameters/scanModeSettings

object

G2 scan mode settings.

Changed in 1.0.x.xParameter group created.
parameters/scanModeSettings/scanMode integer enum

Scan mode.

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

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/intensityEnabled bool used

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

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/uniformSpacingEnabled bool used
When this option is enabled, data points are resampled to a uniform spacing.

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/spacingIntervalMode integer used, enum

Spacing interval mode.

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

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/spacingInterval number minimum, maximum, readOnly, used, actual Spacing interval value.
parameters/scanModeSettings/surface object

See parameters/Surface below.

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/tempSafetyEnabled bool used

Enables laser temperature safety control. Only applies to certain laser-based sensors.

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/profileMergeAlgorithm integer enum, used

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

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.
parameters/scanModeSettings/arrayedOutputs bool

Changed in 1.0.x.x Moved to scanModeSettings.

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

parameters/scanModeSettings/disableOutputs bool used

Changed in 1.0.x.x Moved to scanModeSettings, and reserved for internal use only.

Disable scanner outputs.
parameters/scanModeSettings/reduceProfileRate bool used

Changed in 1.0.x.x Reserved for internal use only.

In surface mode, reduces the profile rate to surface rate, defaults to true.




parameters/scanModeSettings/surface

object

G2 surface parameters. Applicable when parameters/scanMode = 2 (Surface)
parameters/scanModeSettings/surface/type integer enum, used
  • 1 - Fixed length
  • 2 - Variable length
  • 3 - Rotational
  • 0 - Continuous Changed in 1.0.x.x Changed value.
parameters/scanModeSettings/surface/fixedLength object used

Fixed length surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 1 (Fixed Length)
parameters/scanModeSettings/surface/fixedLength/startTrigger integer enum, actual, used
  • 0 - Sequential
  • 1 - Digital input
  • 2 - Software
parameters/scanModeSettings/surface/fixedLength/inputIndex integer enum, actual, used Input index.
parameters/scanModeSettings/surface/fixedLength/length number
Surface length (mm).
parameters/scanModeSettings/surface/variableLength object used

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 used

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

Changed in 1.0.x.x Parameter removed.
parameters/scanModeSettings/surface/rotational/ticksPerRev number readOnly

 Ticks per revolution.

Changed in 1.0.x.x Added.
parameters/scanModeSettings/surface/continuous object used

Changed in 1.0.x.x Continuous surface parameters added.

Continuous surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 0 (Continuous)
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

Changed in 1.0.x.x Added.

Include one-sided data option.
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 (mm2).
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

Changed in 1.0.x.x Renamed to triggerSettings.

See Gocator Scanner - Trigger.  G2 adds additional trigger settings.
parameters/triggerSettings/externalInputZPulseEnabled bool

Changed in 1.0.x.x Moved to triggerSettings

Enables the External Input based encoder Z Pulse feature.
parameters/triggerSettings/externalInputZPulseIndex integer used

Changed in 1.0.x.x Moved to triggerSettings

Input index to use for the input triggered z pulse feature.
parameters/triggerSettings/manualMultiplexing

object

Changed in 1.0.x.x Moved to triggerSettings

See Gocator Scanner - Multiplexing.
parameters/triggerSettings/preferMasterTimeEncoderEnabled bool

Changed in 1.0.x.x Moved to triggerSettings

Prefer master time and encoder.




parameters/filters

 object

 Changed in 1.0.x.x Added,

See Gocator Scanner - Filters.




parameters/advancedSettings

 object used

Changed in 1.0.x.x Removed.

G2 advanced scanner parameters.

/scan/engines/g2xxx/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.

G2 scanners do not currently have any unique metrics.

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

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

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

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

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

G2-Specific Properties

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

Item Type Schema Description
alignConfig/timeout integer

Changed in 1.0.x.x Added.

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

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

G2-Specific Properties

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

Item Type Schema Description
encoderResolution number exclusiveMinimum

Encoder resolution 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 used

Changed in 1.0.x.x Reserved for future.

Transformation object, consisting of offsets and angles. 

See Gocator Alignment - Transform.

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

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

G2-Specific Properties

G2 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/g2xxx/scanners/(scannerId)/actions

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

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

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

Software trigger.

Parameters: none

Outputs: none

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

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

G2-Specific Properties

Item Type Schema Description

creationParams

 object readOnly

G2 scan engine required sensor creation parameters.
creationParams/serialNumber string readOnly

Serial number of a sensor to add to the scanner.

/scan/engines/g2xxx/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.

G2-Specific Properties (sensor)

Item Type Schema Description

parameters

 object

G2 scan engine provided additional sensor information.




parameters/activeAreaSettings

object
G2 active area parameters.
parameters/activeAreaSettings/activeArea

object

 extendedType
parameters/activeAreaSettings/tracking object used

Changed in 1.0.x.x Reserved for future.

See parameters/Tracking below.




parameters/activeAreaSettings/tracking

object

Changed in 1.0.x.x Parameter group created

G2 active area tracking parameters.
parameters/activeAreaSettings/tracking/enabled bool readOnly
parameters/activeAreaSettings/tracking/height number minimum, maximum, readOnly
parameters/activeAreaSettings/tracking/searchThreshold number





parameters/exposureSettings

 object

Changed in 1.0.x.x Parameter group created

G2 exposure settings.
parameters/exposureSettings/exposureMode integer enum, readOnly

Exposure mode.

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

minimum, maximum, used, readOnly

The exposure value to use when parameters/exposureSettings/exposureMode = 0 (Single exposures)
parameters/exposureSettings/multipleExposures array<number> minItems, maxItems, used, readOnly

This contains a list of exposure values to use when parameters/exposureSettings/exposureMode = 1 (Multiple Exposures)
parameters/exposureSettings/enableUnmergedMultiExp bool readOnly

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

This is to enable the output of unmerged multiple exposure profile. This feature is not supported.
parameters/exposureSettings/dynamicExposureMin number used, readOnly

User-defined minimum allowable exposure when parameters/exposureSettings/exposureMode = 2 (dynamic)
parameters/exposureSettings/dynamicExposureMax number used, readOnly

User-defined maximum allowable exposure when parameters/exposureSettings/exposureMode = 2 (dynamic)
parameters/exposureSettings/intensityMode integer used, enum, readOnly

Controls how intensity data is selected.

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

Determines the specific index of parameters/exposureSettings/multipleExposures to use for intensity data when parameters/exposureSettings/exposureMode = 1 (Multiple Exposures)




parameters/subsamplingSettings

object

Changed in 1.0.x.x Parameter group created, note casing of "subsampling".

G2 subsampling settings.
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

Changed in 1.0.x.x Updated with 1/4 and 1/8 subsampling for 26xx series.

Decreases profile's Z resolution.

  • 1 - 1
  • 2 - 1/2
  • 4 - 1/4 (26xx series only)
  • 8 - 1/8 (26xx series only)




parameters/advancedSettings

object used

Changed in 1.0.x.x Added.

G2 advanced settings.
parameters/advancedSettings/materialType integer enum, readOnly

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

  • 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.
parameters/advancedSettings/cameraSettings object readOnly

Changed in 1.0.x.x Added.

 Settings associated w/ all cameras and control of individual cameras. Modifiable when materialType is Custom
parameters/advancedSettings/cameraSettings/sensitivityCompensationEnabled bool used, actual, readOnly


parameters/advancedSettings/cameraSettings/cameras array<object>

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

See Gocator Sensor - Camera;
parameters/advancedSettings/dynamicExposure object

Changed in 1.0.x.x Added.

 Dynamic exposure parameters.
parameters/advancedSettings/dynamicExposure/sensitivity number minimum, maximum, actual, readOnly

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

 Set to readOnly unless materialType is Custom.
parameters/advancedSettings/dynamicExposure/threshold number minimum, maximum, actual, readOnly

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

 Set to readOnly unless materialType is Custom.
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 G2 range slice data when G2 scanner is running in profile range mode.
Note that enabling this flag uses more network resources.

parameters/advancedSettings/spotDetection

 object

Changed in 1.0.x.x Not changeable unless materialType is Custom

G2 spot detection parameters.
parameters/advancedSettings/spotDetection/selectionType integer actual, 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 is important for filtering false spots generated by sunlight reflection.
parameters/advancedSettings/spotDetection/minWidth integer actual, readOnly, minimum, maximum
parameters/advancedSettings/spotDetection/maxWidth integer actual, readOnly, minimum, maximum
parameters/advancedSettings/spotDetection/sobelWidthThreshold integer actual, readOnly, minimum, maximum

Changed in 1.0.x.x Renamed from widthThreshold

Only available on Sobel equipped sensor models.
parameters/advancedSettings/spotDetection/minSum integer actual, readOnly, minimum, maximum
parameters/advancedSettings/spotDetection/sobelEdgeWindow integer actual, readOnly, minimum, maximum Only available on Sobel equipped sensor models.
parameters/advancedSettings/spotDetection/sobelMaxSpots integer actual, readOnly

Changed in 1.0.x.x Moved from advanced to under spotDetection.

Only available on Sobel equipped sensor models.

If non-zero, this parameter allows users to override sensor model's default sobel max spot value.

Also note that this parameter is optional and thus may not be present in all sensors.

When it is used (ie, not 0), it is consumed by the scanner system to determine the actual max number of spots. This value does not on its own determine the actual max number of spot the scanner would generate in profile data.
parameters/advancedSettings/spotDetection/continuitySorting object

Continuity sorting parameters. Applicable only when parameters/advancedSettings/spotDetection/selectionType = 4 (Continuity)
parameters/advancedSettings/spotDetection/continuitySorting/minSegmentSize integer

actual. readOnly, minimum, maximum
parameters/advancedSettings/spotDetection/continuitySorting/searchWindowWidth integer actual, readOnly, minimum, maximum
parameters/advancedSettings/spotDetection/continuitySorting/searchWindowLength integer actual, readOnly, minimum, maximum

/scan/engines/g2xxx/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 G2 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 G2 laser light (seconds).
21201 N/A Gocator/LightOperationTimeTotal

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

G2-Specific Properties

G2 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/g2xxx/scanners/(scannerId)/sensors/(sensorId)/actions

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

Gocator Studio : G3 Scan Engine (Gocator Snapshot)

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

/scan/engines/g3xxx

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

/scan/engines/g3xxx/visibleSensors

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

G3-Specific SensorInfo:

Item Type Schema Description
parameters object readonly

G3 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/g3xxx/scanners

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

G3-Specific Properties

Item Type Schema Description

creationParams

 ParamSet readonly

G3 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/g3xxx/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 identifier of the scanner within the collection (e.g. "scanner-0").
parameters object
Scanner parameters that vary depending on the scan engine.

G3-Specific Properties

Item Type Schema Description

parameters

 object

G3 scan engine provided additional scanner information.

Scan Mode Settings


parameters/scanModeSettings object

G3 scan mode settings.

Changed in 1.0.x.xParameter group created.
parameters/scanModeSettings/scanMode integer enum

Scan mode.

  • 0 - Image
  • 3 - Surface

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/intensityEnabled bool used

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

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/tempSafetyEnabled bool used

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

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/uniformSpacingEnabled bool used
When this option is enabled, data points are resampled to a uniform spacing.

Changed in 1.0.x.x Moved to scanModeSettings.
parameters/scanModeSettings/reduceOcclusion integer enum, used

Current reduced occlusion mode.

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

Changed in 1.0.x.x Moved to scanModeSettings from sensor.
parameters/scanModeSettings/spacingInterval number used, minimum,  maximum,

Current point spacing. (millimeters)

Changed in 1.0.x.x Moved to scanModeSettings from sensor.

Trigger Settings


parameters/triggerSettings

 object

G3 trigger parameters.

Changed in 1.0.x.x Renamed to triggerSettings.
parameters/triggerSettings/source integer enum

Trigger source.

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

Filter Settings


parameters/filters object

See Gocator Scanner - Surface Filters.

Changed in 1.0.x.x Renamed to filters.

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

For metrics common across all Gocator scanners, see Scanner Resources#/scan/engines/(engineId)/scanners/(scannerId)/metrics.

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

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

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

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

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

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

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

G3-Specific Properties

G3 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 alignment can take. If this time is exceeded, alignment will be aborted.

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

G2-Specific Properties

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

Item Type Schema Description
encoderResolution number exclusiveMinimum

Encoder resolution for encoder-based triggering (mm/tick).

Note: not used by G3.
speed number exclusiveMinimum

Travel Speed of the sensor used in time mode (mm/s).

Note: not used by G3.
transform object used

Transformation object, consisting of offsets and angles. 

See Gocator Alignment - Transform.

Changed in 1.0.x.x Reserved for future.

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

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

G3-Specific Properties

G3 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

Note: Reserved for future.
grid object

Grid Layout.  See Gocator Layout - Grid.

Note: Reserved for future.

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

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

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

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

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

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

Parameters: none

Outputs: none

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

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

G3-Specific Properties

Item Type Schema Description

creationParams

 ParamSet readonly

G3 scan engine required sensor creation parameters.
creationParams/serialNumber string readonly

Serial number of a sensor to add to the scanner.

/scan/engines/g3xxx/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.

G3-Specific Properties

Item Type Schema Description

parameters

 object

G3 scan engine provided additional sensor information.
parameters/activeAreaSettings object extendedType

See Sensor - Active Area.

extendedType = TransformedBoxRegion

Changed in 1.0.x.x Renamed to activeAreaSettings.

Exposure Settings


parameters/exposureSettings object

Changed in 1.0.x.x G3 Exposure settings

Changed in 1.0.x.x Renamed to exposureSettings.
parameters/exposureSettings/exposureMode integer enum, used, readOnly

Exposure mode.

  • 0 - Single exposure
  • 1 - Multiple exposure
parameters/exposureSettings/intensitySequenceIndex integer used, minimum,  maximum,

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 used, minimum,  maximum, readOnly

Specifies which scan pattern to use when parameters/exposureSettings/videoPatternType = 3 (Scan Sequence)
parameters/exposureSettings/singleExposure number

used, minimum,  maximum, readOnly

Exposure value (microseconds).
parameters/exposureSettings/multipleExposures array<number> minItems, maxItems, used, readOnly

This contains a list of exposure values to use when parameters/exposureMode = 1 (Multiple Exposures).

(microseconds).

Advanced Settings


parameters/advancedSettings object

Changed in 1.0.x.x Renamed to advancedSettings

G3 advanced settings.
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 used, read-only

Changed in 1.0.x.x Added.

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.

Advanced Camera Settings


parameters/advancedSettings/cameraSettings/

cameras 		array<object>

Changed in 1.0.x.x Moved to advancedSettings

G3 has two camera objects; analogGain does not apply.

See Gocator Sensor - Camera.

Advanced Projector Settings


parameters/advancedSettings/projectorSettings object

Changed in 1.0.x.x Moved to advancedSettings

G3 projector parameters.
parameters/advancedSettings/projectorSettings/intensity number minimum,  maximum, readOnly

Changed in 1.0.x.x Updated to use %.

Current projector intensity in percentages (%).

(The min/max of intensity is usually [0,100]%).
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/g3xxx/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 G3 Sensor:

Item Internal Type Type Description

expTimeTotal

 k64s integer

Changed in 1.0.x.x

Total projector exposure time (seconds).

(In Gocator 6.x: Light Operation Time, ID: 21201)

projectorTempPanel

 k64s integer

Changed in 1.0.x.x

Projector filter array temperature (millidegrees C).

projectorTempLight

 k64s integer

Changed in 1.0.x.x

Projector illumination temperature (millidegrees C).

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

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

G5 Scan Engine - Gocator Confocal Profiler

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

/scan/engines/g5xxx

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

/scan/engines/g5xxx/visibleSensors

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

G5-Specific SensorInfo:

Item Type Schema Description
parameters object readOnly

G5 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/g5xxx/scanners

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

G5-Specific Properties

Item Type Schema Description

creationParams

 object readOnly

G5 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/g5xxx/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 identifier of the scanner within the collection (e.g., "scanner-0").
parameters object
Scanner parameters that vary depending on the scan engine.

G5-Specific Properties

Item Type Schema Description

parameters

 object

G5 scan engine provided additional scanner information.
parameters/family integer readOnly, used

Sensor family.

  • 5 - G5 (Gocator confocal profiler)

Changed in 1.0.x.x Removed.
parameters/runningState integer readOnly, used

Changed in 1.0.x.x Removed.

Run state.

  • 0 - Ready
  • 1 - Running
  • 2 - Error
pparameters/maxSensorCount integer minimum, readOnly, used

Max sensor count.

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

0.3.3.50 Supported maxSensorCount is 2.




parameters/scanModeSettings

 object

G5 scan mode settings.

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

Changed in 1.0.x.x Moved to scanModeSettings
parameters/scanModeSettings/intensityEnabled bool used

When this option is enabled, an intensity value will be produced for each data point.
parameters/scanModeSettings/uniformSpacingEnabled bool used When this option is enabled, data points are resampled to a uniform spacing.
parameters/scanModeSettings/arrayedOutputs bool used

Combine top and bottom sensor outputs to array.

0.3.3.50 Added

Changed in 1.0.x.x Parameter renamed
parameters/scanModeSettings/individualLayersEnabled bool used

Separate layer outputs from arrayed output.

Changed in 1.0.x.x Added.
parameters/scanModeSettings/spacingIntervalEnabled bool used

Enables custom spacing interval.

Changed in 1.0.x.x Parameter renamed
parameters/scanModeSettings/spacingInterval number minimum, maximum, used

Custom spacing interval value (µm)

Changed in 1.0.x.x Parameter renamed.
parameters/scanModeSettings/surface object

Parameter group containing settings which are relevant when scanMode = Surface

Changed in 1.0.x.x Parameter group created




parameters/scanModeSettings/surface object

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

Changed in 1.0.x.x Parameter group created

parameters/scanModeSettings/surface/type integer enum, used
  • 1 - Fixed length
  • 2 - Variable length Changed in 1.0.x.x  Added.
  • 3 - Rotational Changed in 1.0.x.x  Added.
  • 0 - Continuous Changed in 1.0.x.x  Added.
parameters/scanModeSettings/surface/fixedLength

object

 used

Changed in 1.0.x.x Parameter path changed, moved under scanModeSettings. 

Fixed length surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 1 (Fixed Length)
parameters/scanModeSettings/surface/fixedLength/startTrigger integer enum, used

Start trigger.

  • 0 - Sequential
  • 1 - Digital (external) input
  • 2 - Software trigger
parameters/scanModeSettings/surface/fixedLength/inputIndex integer enum, actual, used, 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 used

Changed in 1.0.x.x Added.

Variable length surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 2 (Variable Length)
parameters/scanModeSettings/surface/variableLength/maxLength number readOnly Maximum surface length (mm).
parameters/scanModeSettings/surface/rotational

Changed in 1.0.x.x Added.

Rotational surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 3 (Rotational)
parameters/scanModeSettings/surface/rotational/ticksPerRev number readOnly Ticks per revolution.
parameters/scanModeSettings/surface/continuous object used

Changed in 1.0.x.x Added.

Continuous surface generation parameters. Applicable when parameters/scanModeSettings/surface/type = 0 (Continuous)
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 (mm2).
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

Changed in 1.0.x.x Renamed from trigger to triggerSettings.

G5 trigger parameters.
parameters/triggerSettings/source integer enum

Trigger source.

  • 0 - Time
  • 1 - Encoder
  • 2 - Digital input
  • 3 - Software
parameters/triggerSettings/maxFrameRateEnabled bool used Trigger at maximum frame rate.
parameters/triggerSettings/frameRate number minimum, maximum, actual, used Frame rate for time trigger (Hz).
parameters/triggerSettings/encoderSpacing number minimum, maximum, used Encoder spacing (mm, degrees for surface/rotational).
parameters/triggerSettings/encoderTriggerMode integer enum, used

Encoder trigger mode.

  • 0 - Forward track (track backward)
  • 1 - Forward only (ignore backward)
  • 2 - Bi-directional
parameters/triggerSettings/schedulingUnits integer enum, used

Scheduling units.

  • 0 - Time
  • 1 - Encoder
parameters/triggerSettings/delay number minimum, maximum, used Trigger delay. µs or mm depending on parameters/trigger/schedulingUnits = 0 (Time) or 1 (Encoder), respectively.
parameters/triggerSettings/gateEnabled bool actual, used

Changed in 1.0.x.x Enables digital input gating.
parameters/triggerSettings/reversalDistanceAutoEnabled bool used Whether or not to use auto-calculated value of reversal distance.
parameters/triggerSettings/reversalDistance number readOnly, used Encoder reversal threshold (for jitter handling).




parameters/filters object

Changed in 1.0.x.x Added.

See Gocator Scanner - Filters.




parameters/advanced object

Changed in 1.0.x.x Removed.

/scan/engines/g5xxx/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.

G5 scanners do not currently have any unique metrics.

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

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

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

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

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

G5-Specific Properties

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

Item Type Schema Description
alignConfig/timeout integer

Changed in 1.0.x.x Added.

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

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

G5-Specific Properties

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

Item Type Schema Description
encoderResolution number exclusiveMinimum

Encoder resolution 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 used

Changed in 1.0.x.x Reserved for future.

Transformation object, consisting of offsets and angles. 

See Gocator Alignment - Transform.

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

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

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

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

Software trigger.

Parameters: none

Outputs: none

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

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

G5-Specific Properties

Item Type Schema Description

creationParams

 object readOnly

G5 scan engine required sensor creation parameters.
creationParams/serialNumber string readOnly

Serial number of a sensor to add to the scanner.

/scan/engines/g5xxx/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.

G5-Specific Properties

Item Type Schema Description

parameters

 object

G5 scan engine provided additional sensor information.
parameters/activeAreaSettings object extendedType

Changed in 1.0.x.x Name changed from activeArea to activeAreaSettings

See Sensor - Active Area.

extendedType = TransformedBoxRegion





parameters/exposureSettings

 object

Changed in 1.0.x.x Parameter group created; Exposure settings collected underneath one group.

G5 exposureSettings
parameters/exposureSettings/exposureMode integer enum, used, readOnly

Exposure mode.

  • 0 - Single exposure
  • 1 - Multiple exposure 0.3.2.14  Added.
  • 2 - Dynamic exposure 0.3.2.12  Added.
parameters/exposureSettings/singleExposure number minimum, maximum, used, readOnly

Single exposure value (µs).
parameters/exposureSettings/multiExposures array<number>

minItems, maxItems, used, readOnly

Changed in 1.0.x.x Added.

This contains a list of exposure values (µs) to use when parameters/exposureMode = 1 (Multiple Exposures).
parameters/exposureSettings/multiTargetIntensity integer minimum, maximum, used, readOnly

0.3.2.14 Added.

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.
parameters/exposureSettings/dynamicExposureMin number minimum, maximum, used, readOnly

0.3.2.12 Added.

User-defined minimum allowable exposure (µs) when parameters/exposureSettings/exposureMode = 2 (dynamic)
parameters/exposureSettings/dynamicExposureMax number

minimum, maximum, used, readOnly

0.3.2.12 Added.

User-defined maximum allowable exposure (µs) when parameters/exposureSettings/exposureMode = 2 (dynamic).
This is used also as a starting value for the control.
parameters/exposureSettings/dynamicTargetIntensity number minimum, maximum, used, readOnly

0.3.2.12 Added.

Exposure is continually adjusted such that the average intensity of the brightest profile layer matches user specified target intensity.

parameters/exposureSettings/intensity number minimum, maxmum, used, readOnly

Intensity control value (%).
parameters/exposureSettings/intensityMinRange integer used, minimum

Changed in 1.0.x.x Parameter removed.

Min value for intensity.
parameters/exposureSettings/intensityMaxRange integer used, minimum

Changed in 1.0.x.x Parameter removed.

Max value for intensity.




parameters/subsamplingSettings object

Changed in 1.0.x.x Parameter group created

Subsampling settings. 
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
Changed in 1.0.x.x Parameter group created.
parameters/layerSettings/layerCount integer minimum, maximum, used, readOnly

Changed in 1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/g5xxx/scanners/(scannerId)/parameters)

Max number of layers to be detected (1-8). In image mode needed for detecting spot overlays.
parameters/layerSettings/layerSortingOrder integer enum, used, readOnly

Changed in 1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/g5xxx/scanners/(scannerId)/parameters)

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. Changed in 1.0.x.x Added new layer sorting order option.
parameters/layerSettings/layerSpecificParams array<object>, used

Changed in 1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/g5xxx/scanners/(scannerId)/parameters)

See G5 Scanner - Layer Specific Params below. Array of max 8 layers.
parameters/layerSettings/layerSpecificParams[8] array<object> used

Changed in 1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/g5xxx/scanners/(scannerId)/parameters)

Changed in 1.0.x.x Moved under layerSettings group.

Array of layer-specific parameter objects. There are always 8 objects in this array, even when parameters/layerCount is less than 8.
parameters/layerSettings/layerSpecificParams/n object
Layers-specific parameter object
parameters/layerSettings/layerSpecificParams/n/intensityFilterType integer enum, readOnly, actual, used, 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, used, readOnly

Minimum thickness of the layer (µm).
parameters/layerSettings/layerSpecificParams/n/maxThickness number minimum, maximum, used, readOnly

Maximum thickness of the layer (µm).
parameters/layerSettings/layerSpecificParams/n/refractiveIndex number minimum, used, readOnly

Effective refractive index of the material.
parameters/layerSettings/layerSpecificParams/n/detectMissingLayer bool used, readOnly

0.3.3.7  Added.

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).
parameters/layerSettings/layerSpecificParams/n/detectMissingLayerGapX number minimum, maximum, used, readOnly

0.3.3.7  Added.

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.




parameters/advancedSettings

 object

Changed in 1.0.x.x Path changed to advancedSettings.

G5 advanced sensor parameters.
parameters/advancedSettings/materialType integer enum, readOnly

Changed in 1.0.x.x Moved under advancedSettings.
Changed in 1.0.x.x  Corrected that Diffuse = 1, Custom = 0 (prior documented values were wrong).

  • 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.
parameters/advancedSettings/highPowerEnabled bool used, readOnly

Changed in 1.0.x.x Added.

If enabled, intensity can be adjusted to greater than 100%.
parameters/advancedSettings/intensityCalibration bool used, readOnly

Changed in 1.0.x.x Added.

If enabled, uneven illumination is corrected for intensity values.
parameters/advancedSettings/perLayerIntensity bool readOnly

Changed in 1.0.x.x Moved to sensor level from scanner level (was at /scan/engines/g5xxx/scanners/(scannerId)/parameters/advanced)

Allows the user to configure intensity output type on per layer basis. When enabled, affects performance.
parameters/advancedSettings/roughnessFilterEnabled bool used, readOnly

Changed in 1.0.x.x Added.

If enabled, noise reduction designed for roughness applications is used.
parameters/advancedSettings/camera object used

 Settings associated with camera. Modifiable when materialType is Custom.
parameters/advancedSettings/camera/digitalGain number

Digital gain.
parameters/advancedSettings/camera/analogGain

Changed in 1.0.x.x Removed.
parameters/advancedSettings/camera/gammaType

Changed in 1.0.x.x Removed.
parameters/advancedSettings/clusteringParams object used

Changed in 1.0.x.x Added.

Short cluster removal.
parameters/advancedSettings/clusteringParams/removeShortClustersEnabled bool readOnly When enabled, connects points to clusters and removes small clusters.
parameters/advancedSettings/clusteringParams/distanceX number minimum, maximum, used, readOnly Maximum X distance (µm) to the nearest point in a cluster.
parameters/advancedSettings/clusteringParams/distanceZ number minimum, maximum, used, readOnly Maximum Z distance (µm) to the nearest point in a cluster.
parameters/advancedSettings/clusteringParams/minWidth number minimum, maximum, used, readOnly Minimum cluster width (µm) which is not removed.
parameters/advancedSettings/spotDetection

object

Changed in 1.0.x.x Path changed to advancedSettings

G5 spot detection parameters.
parameters/advancedSettings/spotDetection/edgeWindow

integer

 enum, readOnly, actual, used Gradient filter size (px).
parameters/advancedSettings/spotDetection/averageWindow

integer

 enum, readOnly, actual, used Moving average filter size (px).
parameters/advancedSettings/spotDetection/intensityWindow integer enum, readOnly, actual, used Window size for spot intensity calculation (px).
parameters/advancedSettings/spotDetection/threshold integer minimum, maximum, actual, readOnly, used Threshold to tell whether pixel is within spot.

/scan/engines/g5xxx/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 G5 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 G5 light (seconds).

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

G5-Specific Properties

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

Item Type Schema Description
reverseX boolean used Reverse X.
transform object

Transformation matrix.  See Gocator Alignment - Transform.

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

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

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
helpHtml string readOnly
Html help string for this tool. If both helpURL and helpHtml is specified helpURL will take precedence.
helpUrl string readOnly Html help string for this tool If both helpURL and helpHtml is specified helpURL 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
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.

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

Changed in 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 – i.e., 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.

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

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

Changed in 1.0.x.x Added.

Methods

Method Description
call

Example:

call /tools/TestForward-0/commands/batch

/tools/(toolId)/commands/unbatch

Resource Type: (Callable)

Command to unbatch a tool.

Changed in 1.0.x.x 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.

Changed in 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 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 is not 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).

Control Resources

This section describes the control service (/controls) resources, which apply to all control services. This information can be used to implement a generic client that works with any control service be it from LMI or 3rd party.

Specific details about the Gocator standard set of control services are found in subpages.

/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 directly via the service.

Properties

None

Methods

Method Description
read

Return list of control services available in the system

Example:

Read Available Services Example
read /controls

Example Response:

Read Available Services
  {
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/gocator"
            }
          }
        },
      ]
    },
    "_links": {
      "self": {
        "href": "/controls"
      }
    }
  },
  "status": 1,
  "type": "response"
  }

Notifications

None.

/controls/(serviceId)

Resource Type: (CollectionItem)

Information about a specific control service.

Properties:

Item Type Schema Description
displayName string readOnly

Display name of the control service that is culture-specific (i.e., translatable). This is the name that a client should display to the user.

Each service defines the value of its "displayName".
enabled bool Used to enable or disable the control 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.

Each service defines the value of its "id".
parameters object List of configurable parameters for the control service. Each control service has its own set of parameters.
status enum readOnly

Status of the service. This item is updated when the "enabled" property is changed from true to false or vice versa.

0.3.4.20 Added these enumerated values for this field:

Value Name
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 specified control service. 

Example:

Read Controls Gocator Example
read /controls/gocator

Example Response:

Read Controls Gocator
{
  "payload": {
    "_embedded": {
      "go:datasources": {
        "_links": {
          "self": {
            "href": "/controls/gocator/outputs"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/controls/gocator"
      }
    },
    "displayName": "Gocator",
    "enabled": false,
    "id": "gocator",
    "parameters": {
      "timeout": 1.0,
      "timeoutEnabled": false
    },
    "status": 1
  },
  "status": 1,
  "type": "response"
}
update

Change parameters for a service such as enable/disable service, or change a service specific parameter. To see what can be changed, do a "read /controls/(serviceId)", specifying the specific service for which you want information.

Example:

Update Protocol Property
update /controls/gocator {"enabled" : true}
update /controls/gocator {"enabled" : false}
update /controls/gocator {"enabled" : true, "parameters" : {"timeoutEnabled":true,"timeout":1.2}}
sub

Subscribe to resource to get all the properties of the service whenever a property is changed with the UPDATE method.

Example:

Subscribe Gocator 
sub /controls/gocator


Example Response:

Subscribed Notification 
{
  "payload": {
    "content": {
      "_embedded": {
        "go:datasources": {
          "_links": {
            "self": {
              "href": "/controls/gocator/outputs"
            }
          }
        },
      },
      "_links": {
        "self": {
          "href": "/controls/gocator"
        }
      },
      "_schema": {
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "parameters": {
            "properties": {
              "timeout": {
                "type": "number"
              },
              "timeoutEnabled": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "enabled": true,
      "parameters": {
        "timeout": 1.0,
        "timeoutEnabled": false
      }
    },
    "eventType": "updated",
    "path": "/controls/gocator"
  },
  "status": 1,
  "type": "notification"
  }
  
  {
  "payload": null,
  "status": 1,
  "type": "response"
  }

Notifications

Notification
updated
Occurs whenever a control property has changed.

/controls/(serviceId)/outputs

Resource Type: N/A

This resource manages a control service's output map.

All services have this common parameter.

Item Type Schema Description

acceptedDataFormats 

 DataFormat[] readOnly

List of acceptable data formats. See Common Types.

Each service output map defines its acceptable data format (scan data types).

Output map can be one of the following types:

StandardOutputs:

An output map of StandardOutputItem.

Item Type Description
map

StandardOutputItem[]

 An array of StandardOutputItem.
attributes StandardOutputsAttributes Description of the StandardOutputs information.

StandardOutputItem:

Item Type Description
outputId

16u

An id used to uniquely identify the associated data source.

Valid range is 0..216-2.

Value of 216-1 is reserved for internal use.

Note: If the client enters an output id value that is greater than 216 (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. 
source string A selected data source identifier.

StandardOutputsAttributes

Item Type Schema Description
outputIdMin 16u Read-only

Changed in 0.3.x.x added this field.

The minimum output id value for a standard output item.
outputIdMax 16u Read-only

Changed in 0.3.x.x added this field.

The maximum output id value for a standard output item.

RegisterOutputs;

An output map of RegisterOutputItem and attributes of the register output map.

Item Type Description
map

RegisterOutputItem[]

An array of RegisterOutputItem.
attributes RegisterOutputsAttributes Description of the RegisterOutputs register information.

RegisterOutputItem:

Item Type Description
outputId

16u

An id used to uniquely identify the associated data source.

Valid range is 0..216-2.

Value of 216-1 is reserved for internal use.

Note: If the client enters an output id value that is greater than 216 (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. 
source string A selected data source identifier.
dataOffset

16u

 A byte offset into the data source data received from the sensor.
dataLength

16u

 A byte length specifying number of bytes to return from the data source data received from the sensor, starting from the "dataOffset" into the data source data.

RegisterOutputsAttributes:

Item Type Schema Description
start 16u Read-only The starting register number/address.
count 16u Read-only Number of registers in the RegisterOutputs output map table.
itemSize 16u Read-only The size of each register in the register map, in bytes.

TextIdStandardOutputs:

This is similar to the StandardOutputs, but uses a string for the output id.

Item Type Keywords Description
map

TextIdStandardOutputItem[]
An array of TextIdStandardOutputItem.

TextIdStandardOutputItem:

Item Type Description
outputId string An id used to uniquely identify the associated data source.
source string A selected data source identifier.

Properties:

Item Type Description
map

StandardOutputs[] or

RegisterOutputs[] or

TextIdStandardOutputs[]

An array of either output map items. A control service supports one of the possible types.

See above for details.

Methods:

Method Description
read

Read the outputs map from the service.

Example:

Read Controls Gocator Outputs Example
read /controls/gocator/outputs

Example Response:

Note this example is for a service that uses the StandardOutputs output map.

Read Controls Gocator Outputs
{
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/outputs"
      }
    },
  "acceptedDataFormats": [
      {
        "arrayed": false,
        "type": 19
      }
    ],
    "attributes": {
      "outputIdMax": 65534,
      "outputIdMin": 0
    },
    "map": [
      {
        "outputId": 0,
        "source": "output1"
      },
      {
        "outputId": 1,
        "source": "output2"
      }
    ]
  },
  "status": 1,
  "type": "response"
  }
sub

Subscribe to the output map resource to receive the entire outputs map when outputs map is updated with the CALL method.

Example:

Subscribe Gocator
sub /controls/gocator/outputs

Example Output:

Subscribed Notification
{
  "payload": null,
  "status": 1,
  "type": "response"
  }

Notifications:

Notification
updated
Occurs whenever the output map has changed.

/controls/(serviceId)/outputs/commands/add

Resource Type: (Callable)

ADD command: to add an entry to the outputs map.

Properties

none

Methods

Method
call

Arguments:

Item Type Description
output map item

One of these:

 Add this item to the output map.
autoShift bool

An optional parameter.

When set to true, it allows new entry to be added even if it overlap with other existing item(s) in the output map. The existing item(s) will automatically move to accomodate the new item if possible.

When not preset or set to false, if overlapping condition is detected, an exception will be thrown and error will be returned.

Examples:

Add An Entry 
call /controls/gocator/outputs/commands/add {"source":"scan:test:0:Output", "outputId":0}
  call /controls/gocator/outputs/commands/add {"source":"scan:test:1:Output", "outputId":1}
  
  call /controls/gocator/outputs/commands/add {"source":"scan:test:0:Output", "outputId":0, "autoShift", true}
  call /controls/gocator/outputs/commands/add {"source":"scan:test:1:Output", "outputId":1, "autoShift", false}

/controls/(serviceId)/outputs/commands/remove

Resource Type: (Callable)

REMOVE command: to remove an entry from the outputs map.

Properties

none

Methods

Method

call

Arguments:

Item Type Description
outputId

Type depends on the output map used by the service.

 Delete the output map entry with this output id.

Examples:

Remove An Entry 
call /controls/gocator/outputs/commands/remove {"outputId":0}
  call /controls/gocator/outputs/commands/remove {"outputId":1}

/controls/(serviceId)/outputs/commands/updateId

Resource Type: (Callable)

UPDATE command: to change the output id of an existing entry.

Properties

none

Methods

Method
Call

Arguments:

Item Type Description
map

A list of two output ids.

Item Type Description
outputId Old (original) identifier value to change FROM.
outputId New identifier value to change TO.

The outputId type depends on the output map used by the service.
autoShift bool

An optional parameter.

When set to true, it allows the existing old item to change into new output ID even if new output ID would overlap with other existing item(s) in the output map. The existing item(s) will automatically move to accomodate the new item if possible.

When not preset or set to false, if overlapping condition is detected, an exception will be thrown and error will be returned.

Examples:

Update An Entry 
// 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}

/controls/(serviceId)/outputs/commands/addAll

Resource Type: (Callable)

ADDALL command: to add a list of data sources to the output map table. The list of data sources do not include output ids. The back end always auto-generate the NUMERIC output ids.

For TEXT output id, if it is provided, then it is used, otherwise missing TEXT output id is auto-generated using the "source" string.

Properties

none

Methods

Method
Call

Arguments:

Item Type Description
map array<string>

A list of data sources entry. Each entry has one field.

Item Type Description
source string A data source to add to the output map. 

Examples:

Add Multiple Entries 
call /controls/gocator/outputs/commands/addAll {"map": [ { "source": "tools:ProfileInfo-0:outputs:MaxZ" }, { "source": "tools:ProfileInfo-1:outputs:MaxY" } ] }

/controls/(serviceId)/outputs/commands/removeAll

Resource Type: (Callable)

REMOVEALL command: to remove all entries in the output map table.

Properties

none

Methods

Method
Call

Arguments: None

Examples:

Remove All Entries 
call /controls/gocator/outputs/commands/removeAll

/controls/(serviceId)/outputs/commands/compactId

Resource Type: (Callable)

COMPACTID command to renumber consecutively the output ids. Starting output id depends on the output map type.

For StandardOutputs, starting default output id is 0.

For RegisterOutputs, the starting output id is start register value specified in the RegisterOutputsAttributes.

For TextIdStandardOutputs, this operation is not supported.

See StandardOutputItem, RegisterOutputItem, and TextIdStandardOutputItem for more information about these types.

Properties

none

Methods

Method
Call

Arguments: None

Examples:

Compact Output Ids 
call /controls/gocator/outputs/commands/compactId

/controls/(serviceId)/metrics

Resource Type: (Streamable)

This resource manages a control service metrics.

Properties:

Each service defines its own set of metrics. Clients can only read the metrics.

Common Metrics:

Item Internal Type Type Description

Changed in 0.3.x.x Added

controlDrops

 k64u integer

All services contain this generic drops metric. How each service updates this metric depends on the service.

Generally, services that promise lossless data will increment this drop if they cannot fulfill this promise.

Services that are lossy or otherwise cannot drop generally will not update this at all.

Methods:

Method Descripton
read

Read the metrics maintained by the service.

Example:

Read Metrics 
read /controls/gocator/metrics


Example Response:

Read Metrics Output 
{
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/gocator/metrics"
      }
    },
    "controlDrops": 0,
    "ethernetOutput": 0,
    "ethernetOutputCount": 0,
    "ethernetRate": 0
  },
  "status": 1,
  "type": "response"
  }
stream

Stream metrics from the service

Examples:

Stream Metrics 
stream /controls/gocator/metrics
cancelStream

Stop streaming metrics from the service

Examples:

Cancel Streaming Metrics
cancelStream /controls/gocator/metrics

/controls/(serviceId)/registerAssemblies

Changed in 1.0.x.x Resource added.

html

Resource Type: N/A

Methods

Method
Read

Returns the list of register assembly links supported by this service.

Example:

Read Register Assemblies
read  /controls/test/registerAssemblies

Example Response:

Read Register Assemblies Response
{
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/test/registerAssemblies/testAssembly-0"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/test/registerAssemblies/testAssembly-1"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/test/registerAssemblies"
      }
    }
  },
  "status": 1,
  "type": "response"
  }

The example shows the service has two register assemblies with identifiers:

  • testAssembly-0
  • testAssembly-1

/controls/(serviceId)/registerAssembies/(registerAssemblyId)

Resource Type: N/A

Properties

Item

Type

 Schema

Description
supportedBlockTypes array<object>
Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n object
Register block type object.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Changed in 0.3.x.x Added the following Internal names for the block types:

Block Type Internal Id (Type Name)
Control Input (for client to send commands to device) "ControlInput"
Control Output (for device to send back command status) "ControlOutput"
System (for system related information) "System"
Scanner (for scanner related information) "Scanner"
Stamp (for scan message stamp information) "Stamp"
Measurement (for scan measurement information) "Measurement"
supportedBlockTypes/n/displayName culture-specific string readOnly

Culturally-sensitive name that can be presented to the user to describe the register block.
supportedBlockTypes/n/registerCount integer readOnly Number of registers that this register block uses.
supportedBlockTypes/n/instanceCount integer readOnly Number of instances of this register block type that have been added to the register assembly.
supportedBlockTypes/n/minInstanceCount integer readOnly Minimum number of instances of this register block type that must exist in the register assembly.
supportedBlockTypes/n/maxInstanceCount integer readOnly Maximum number of instances of this register block type that can exist in the register assembly.

blocks

 array<object>
Array of register block objects that have been added to the register assembly.
blocks/n object
Register block object.
blocks/n/type string readOnly Internal id that uniquely identifies the register block type.
blocks/n/outputId integer

The output id uniquely identifies the register block in the register assembly. For one register block type (identified by type), there may be multiple register blocks - each each individual register block is identified by outputId. 

If a global address space is used, the output id represents the starting register address of the register block. 

Valid range is 0..216-1.
blocks/n/scannerId string used

Identifies the scanner for which the register block is associated. 
blocks/n/displayName culture-specific string

Culturally-sensitive name to describe the register block. displayName defaults to be the same as the title of the corresponding register block type.
blocks/n/dataSource string

The data source of the register block. 

If the block type is a scan output block type (e.g., measurement/stamp block), this field is present. Otherwise, the dataSource field is not present.
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True if the control service uses a global address space. False otherwise.

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

Changed in 0.3.x.x renamed from registerAddressMax. Removed "used" schema attribute.

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

Changed in 0.3.x.x renamed from registerAddressMin. Removed "used" schema attribute.

Methods

Method
read

Read the list of supported blocks types and added block instances for the specified register assembly use by the  control protocol. Different control protocols may support different register block types.

Returns commands as links.

Example:

Read Register Assembly
read  /controls/test/registerAssemblies/testAssembly-0

Example Response:

Read Register Assembly Output
{
    "payload": {
      "_links": {
        "go:command": [
          {
            "href": "/controls/test/registerAssemblies/testAssembly-0/commands/add"
          },
          {
            "href": "/controls/test/registerAssemblies/testAssembly-0/commands/remove"
          },
          {
            "href": "/controls/test/registerAssemblies/testAssembly-0/commands/compact"
          },
          {
            "href": "/controls/test/registerAssemblies/testAssembly-0/commands/update"
          }
        ],
        "self": {
          "href": "/controls/test/registerAssemblies/testAssembly-0"
        }
      },
      "attributes": {
        "id": "testAssembly-0",
        "isGlobalAddressSpaceUsed": true,
        "outputIdMax": 3000,
        "outputIdMin": 0
      },
      "blocks": [
        {
          "displayName": "Control Input",
          "outputId": 0,
          "scannerId": "",
          "type": "ControlInput"
        },
        {
          "displayName": "Control Output",
          "outputId": 267,
          "scannerId": "",
          "type": "ControlOutput"
        },
        {
          "displayName": "System State",
          "outputId": 470,
          "scannerId": "",
          "type": "System"
        },
        {
          "displayName": "Sensor Group State",
          "outputId": 746,
          "scannerId": "",
          "type": "Scanner"
        }
      ],
      "supportedBlockTypes": [
        {
          "category": 1,
          "displayName": "Control Input",
          "hasDataSource": false,
          "instanceCount": 1,
          "maxInstanceCount": 1,
          "minInstanceCount": 1,
          "registerCount": 267,
          "type": "ControlInput"
        },
        {
          "category": 2,
          "displayName": "Control Output",
          "hasDataSource": false,
          "instanceCount": 1,
          "maxInstanceCount": 1,
          "minInstanceCount": 1,
          "registerCount": 203,
          "type": "ControlOutput"
        },
        {
          "category": 3,
          "displayName": "System State",
          "hasDataSource": false,
          "instanceCount": 1,
          "maxInstanceCount": 1,
          "minInstanceCount": 1,
          "registerCount": 276,
          "type": "System"
        },
        {
          "category": 4,
          "displayName": "Sensor Group State",
          "hasDataSource": false,
          "instanceCount": 1,
          "maxInstanceCount": 1,
          "minInstanceCount": 1,
          "registerCount": 218,
          "type": "Scanner"
        },
        {
          "category": 5,
          "displayName": "Stamp",
          "hasDataSource": true,
          "instanceCount": 0,
          "maxInstanceCount": 65534,
          "minInstanceCount": 0,
          "registerCount": 233,
          "type": "Stamp"
        },
        {
          "category": 6,
          "displayName": "Measurement",
          "hasDataSource": true,
          "instanceCount": 0,
          "maxInstanceCount": 65534,
          "minInstanceCount": 0,
          "registerCount": 5,
          "type": "Measurement"
        }
      ]
    },
    "status": 1,
    "type": "response"
  }

/controls/(serviceId)/registerAssemblies/(registerAssemblyId)/commands

Resource Type: (CollectionItem)

A collection of commands for the control service's register assembly.

Methods:

Method

Description
read

Returns a list of register assembly commands as embedded resources.

Example:

Read Register Assembly Commands
read  /controls/test/registerAssemblies/testAssembly-0/commands

Example response:

ead Register Assembly Actions
{
                    "payload": {
                      "_embedded": {
                        "item": [
                          {
                            "_links": {
                              "self": {
                                "href": "/controls/test/registerAssemblies/testAssembly-0/commands/add"
                              }
                            }
                          },
                          {
                            "_links": {
                              "self": {
                                "href": "/controls/test/registerAssemblies/testAssembly-0/commands/remove"
                              }
                            }
                          },
                          {
                            "_links": {
                              "self": {
                                "href": "/controls/test/registerAssemblies/testAssembly-0/commands/compact"
                              }
                            }
                          },
                          {
                            "_links": {
                              "self": {
                                "href": "/controls/test/registerAssemblies/testAssembly-0/commands/update"
                              }
                            }
                          }
                        ]
                      },
                      "_links": {
                        "self": {
                          "href": "/controls/test/registerAssemblies/testAssembly-0/commands"
                        }
                      }
                    },
                    "status": 1,
                    "type": "response"
                  }

/controls/(serviceId)/registerAssemblies/(registerAssemblyId)/commands/add

Resource Type: (CollectionItem, Callable)

ADD command: to add one or more register blocks to the register assembly.

This command can also be read to obtain information about the command.

Properties

Item

Type

 Schema

Description
id string
The identifier of the register assembly command.
parameters object

Describes the parameters that the register assembly command can take. 

Methods

Method
read

Returns the input parameters for the command.

Example:

Read Register Assembly Command Add
read  /controls/modbus/registerAssemblies/registerAssembly-0/commands/add

Example response:

Read Register Assembly Add
  {
  "payload": {
  "_links": {
  "self": {
  "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/add"
  }
  },
  "id": "add",
  "parameters": {
  "autoShift": false,
  "blocks": []
  }
  },
  "status": 1,
  "type": "response"
  }
call

If one or more of the register blocks listed in the "blocks" array cannot be added, a user log warning will be generated with a corresponding error message. The invalid block entry will be skipped and the rest of the blocks in the "blocks" array will be added to the register assembly.

If one or more of the register blocks listed in "blocks" are successfully added to the register assembly, the add command will return successfully. If none of the register blocks listed in "blocks" were able to be added to the register assembly, the add command will return an error.

Arguments:

Item Type Description
blocks array<object> Array of parameters of register blocks to be added to the register assembly.
blocks/n object Parameters of one register block.
blocks/n/type

string

Unique identifier of the register block type to be added.

Register block type must be specified in order to add a register block of that block type to the register assembly.
blocks/n/dataSource string

The data source of the register block. 

If the block type is a scan output block type (e.g., measurement/stamp block), this field is required.
blocks/n/outputId integer

(Optional) The output id uniquely identifies the register block. If a global address space is used, the output id represents the starting register address of the register block. 

If the output id is not specified, the register assembly will automatically generate the new block's output id. The generated output id will be set so that the new block is placed after the last block in the register assembly's "blocks" list. The new block will be appended to the back of the list.

Note that the valid range for the output id is 0..216-1. If the client enters an output id value that is greater than 216 (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

(Optional) The scanner to be associated with the register block being added.

If no scanner id is specified, the register block will be associated with the first scanner found.
blocks/n/displayName string

(Optional) The display name of the register block being added.

If no display name is specified, the register block will provide a default display name.
autoShift bool 

(Optional) If adding a block with an output id which overlaps with an existing block and autoShift is set to true, the existing overlapping blocks will be shifted to make room for the new block. If autoShift is set to false, the block will not be added.

If autoShift is not specified, this field defaults to false.

Examples:

The add command can be used for the following scenarios:

  1. Add one register block - blocks list only contains one item. Note that different control protocols may support different types of register blocks.

    Add Register Block
    // Add a ModbusControl register block to the Modbus protocol.
                                    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
                                        "autoShift":true,
                                        "blocks":[{
                                            "type":"Control",
                                            "outputId":100,
                                            "scannerId":"scanner-0",
                                            "displayName":"New Block"}]}
                                    
                                    // Add a defaultControl register block to the test protocol.
                                    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
                                        "autoShift":true,
                                        "blocks":[{
                                            "type":"defaultControl",
                                            "outputId":100,
                                            "scannerId":"scanner-0",
                                            "displayName":"New Block"}]}

  2. Add all of one type of register block - the optional parameters (outputId, scannerId, displayName, autoShift) may also be specified 

    Add Register Block
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
                                        "blocks":[
                                            {"type":"Measurement","dataSource":"tool1:data:source:id"},
                                            {"type":"Measurement","dataSource":"tool2:data:source:id"},
                                            {"type":"Measurement","dataSource":"tool3:data:source:id"}]}

  3. Add all available register blocks - the optional parameters (outputId, scannerId, displayName, autoShift) may also be specified 

    Add Register Block
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/add {
                                        "blocks":[
                                            {"type":"Control"},
                                            {"type":"SystemState"},
                                            {"type":"ScannerState"},
                                            {"type":"Measurement","dataSource":"tool1:data:source:id"},
                                            {"type":"Measurement","dataSource":"tool2:data:source:id"},
                                            {"type":"Measurement","dataSource":"tool3:data:source:id"},
                                            {"type":"Stamp","dataSource":"tool1:data:source:id"},
                                            {"type":"Stamp","dataSource":"tool2:data:source:id"},
                                            {"type":"Stamp","dataSource":"tool3:data:source:id"}]}

/controls/(serviceId)/registerAssemblies/(registerAssemblyId)/commands/remove

Resource Type: (CollectionItem, Callable)

REMOVE command: to remove one or more register blocks from the register assembly.

This commandcan also be read to obtain information about the command.

Properties

Item

Type

 Schema

Description
id string
The identifier of the register assembly command.
parameters object

Describes the parameters that the register assembly command can take. 

Methods

Method
read

Returns the input parameters for the command.

Example response:

Read Register Assembly Remove
{
    "payload": {
      "_links": {
        "self": {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/remove"
        }
      },
      "id": "remove",
      "parameters": {
        "blockIds": []
      }
    },
    "status": 1,
    "type": "response"
  }
call

If one or more of the register blocks listed in the "blockIds" array cannot be removed, a user log warning will be generated with a corresponding error message. The invalid block entry will be skipped and the rest of the blocks in the "blockIds" array will be removed from the register assembly.

If one or more of the register blocks listed in "blockIds" are successfully removed from the register assembly, the remove command will return successfully. If none of the register blocks listed in "blockIds" were able to be removed from the register assembly, the removed command will return an error.

Item Type Description
blockIds array<object> Array of output ids which correspond to the register blocks to be removed from the register assembly.
blockIds/n object Object containing a register block output id.
blockIds/n/outputId integer

The output id of the register block to be removed from the register assembly.

Examples:

The remove command can be used for the following scenarios:

  1. Remove one register block - blockIds only contains one item.

    Remove one block example
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/remove {"blockIds":[{"outputId":0}]}

  2. Remove all of one type of block/remove all added blocks

    Remove multiple blocks example
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/remove {"blockIds":[{"outputId":0},{"outputId":100},{"outputId":200}]}

/controls/(serviceId)/registerAssemblies/(registerAssemblyId)/commands/compact

Resource Type: (CollectionItem, Callable)

COMPACT command: to compact the output ids in the register assembly to eliminate unused space between register blocks.

This command can also be read to obtain information about the command.

Properties

Item

Type

 Schema

Description
id string
The identifier of the register assembly command.
parameters object

Describes the parameters that register assembly commands can take. 

Methods

Method
read

Returns the input parameters for the command.

Example response:

Read Register Assembly Compact
{
    "payload": {
      "_links": {
        "self": {
          "href": "/controls/modbus/registerAssemblies/registerAssembly-0/commands/compact"
        }
      },
      "id": "compact",
      "parameters": {
        "startingOutputId": null
      }
    },
    "status": 1,
    "type": "response"
  }
call

Arguments:

Item Type Description

startingOutputId

integer

(Optional) The 16-bit starting address (output id) of the first block in the register assembly.

If the starting address is not specified, then the starting address of the first block will default to the register assembly's minimum register address value, if register assembly attributes isGlobalAddressSpaceUsed is true.

If attributes/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 while isGlobalAddressSpaceUsed is true, then the default value is the register assembly's attribute outputIdMin value.

If attributes/isGlobalAddressSpaceUsed is false, then default value is 0.

Important

If the client enters an output id value that is greater than 216-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 an output 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. 

Changed in 0.3.x.x added this field which was originally called startingAddress.

Changed in 0.3.x.x renamed from startingAddress to startingOutputId.

Examples:

The compact command can be used for the following scenarios:

  1. Compact blocks to the register assembly's default minimum address

    Compact Register Blocks
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact

  2. Compact blocks to a specific register address.

     

    Changed in 0.3.x.x added this option to specify starting address.

    Compact Register Blocks
    call /controls/modbus/registerAssemblies/registerAssembly-0/commands/compact {"startingOutputId":100}

/controls/(serviceId)/registerAssemblies/(registerAssemblyId)/commands/update

Resource Type: (CollectionItem, Callable)

UPDATE command: to update a register block in the register assembly.

This command can also be read to obtain information about the command.

Properties

Item

Type

 Schema

Description
id string
The identifier of the register assembly command.
parameters object

Describes the parameters that the register assembly command can take.

Methods

Method
read

Returns the input parameters for the command.

Example response:

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

Arguments:

Item Type Description

outputId

integer

The 16-bit integer output id of the block to be updated.
autoShift bool 

(Optional) If updating a block's output id causes the block to overlap with an existing block and autoShift is set to true, the existing overlapping blocks will be shifted to make room for the updated block. If autoShift is set to false, the block will not be updated.

If autoShift is not specified, this field defaults to false.
newParams object The new parameters that the register block will be updated with.
newParams/dataSource string

(Optional) The updated data source of the register block.

This parameter is only used for block types that support data source.

newParams/outputId integer

(Optional) The updated 16-bit integer output id of the register block.

Note that the valid range for the output id is 0..216-1. If the client enters an output id value that is greater than 216 (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. 
newParams/scannerId string

(Optional) The updated scanner id of the register block.
newParams/displayName string

(Optional) The updated culturally-sensitive name to describe the register block.

Examples:

Update block example
call /controls/modbus/registerAssemblies/registerAssembly-0/commands/update {
          "outputId":100, 
          "autoShift":true, 
          "newParams":{
            "dataSource":"tool1:data:source:id", 
            "outputId":200,
            "scannerId":"scanner-0", 
            "displayName":"New Display Name"}}

GoPxL Data Protocol (GDP)

GDP Resources

This section describes the standard control protocol resources called Gocator Data Protocol that is included with each LMI Gocator release. Please refer to Control Resources page for general background on the control resources.

/controls/gocator

Gocator Protocol

Gocator supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, GDP adds the following:

Properties:

Item Type Schema Description
displayName string readOnly Set to "Gocator"
id string readOnly

Set to "gocator".

Parameters:

Item Type Schema Description
timeoutEnabled bool When enabled, a blocked write operation times out and causes the connection to close.
timeout number minimum, maximum The timeout value in us.

/controls/gocator/outputs

Gocator Protocol Output Map

Uses the StandardOutputs output map.

/controls/gocator/metrics

Gocator Protocol Metrics

Metrics behavior and base functionality is covered for all Control protocols in Control Resources /controls/(protocolId)/metrics

In addition to this, the gocator control protocol adds the following metrics:

Metrics:

Item Type Schema Description Gocator IndicatorId Gocator Instance Gocator Name
ethernetOutput integer

Number of bytes sent out by the Gocator Data Protocol over the Ethernet interface via TCP.

 21003 N/A gocator/netTp
ethernetOutputCount integer
Number of messages sent by the Gocator Data Protocol over the Ethernet interface via TCP. N/A N/A N/A
ethernetRate integer
The rate of transmission out the Ethernet interface in bytes per second over the Ethernet interface via TCP. 21004 N/A gocator/netRate

controlDrops

 integer

Note: this is a generic metric across all control services, but this implementation is GDP-specific.

Number of dropped scan results.

Changed in 0.3.x.x Added this metric.

21012

 N/A

gocator/serverDrops
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. N/A N/A N/A
maxInputBufferMsgCount integer
Maximum number of messages that Gocator Data Protocol's input buffer(s) can contain. N/A N/A N/A
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. N/A N/A N/A
maxOutputBufferMsgCount integer
Maximum number of messages that Gocator Data Protocol's output buffer(s) can contain. N/A N/A N/A

Note:
ethernetOutput will keep its last known value during the following scenarios:

  • Scanner stops producing data, i.e., Scanner stopped.
  • All GDP outputs unselected.
  • No GDP clients, i.e., last GDP client disconnects from the server.

ethernetOutput will reset to 0 when scanner starts again.

ethernetRate is calculated upon every metrics refresh/update trigger, currently at 4hz.

  • If no data is transferred during a update period, then the ethernetRate will be shown as 0 for that period.

GDP server holds one or more of internal message queue for buffering. if during its operation, its internal buffer is full, the messages will start to get dropped, thus a serverDrops will be reported.

controlDrops may happen for various reasons,

  • TCP/GDP client is not able to clear its received buffer fast enough, thus GDP cannot sent its data fast enough.
  • Scanner 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, one or a combination of the following conditions will occur,

  • Camera buffer drop.
  • controlDrops in GDP server
  • Processing drop.
  • Other drops somewhere in the pipeline processing.

Because camera buffer has a total buffer size limit, and GDP server internal queue has a total number of messages limit, thus whether the messages are dropped in camera buffer or GDP controlDrops is influenced by many factors such as the individual messages size, number of messages over a period of time, etc.

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.

HMI Resources

This section describes the standard control protocol resources called HMI Protocol that is included with each LMI Gocator release. Please refer to Control Resources page for general background on the control resources.

/controls/hmi

HMI Protocol

HMI supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, HMI adds the following:

Properties:

Item Type Schema Description
displayName string readOnly

Set to "HMI"
id string readOnly

Set to "hmi".

Parameters:

Item Type Schema Description
appUrl string readOnly The web URL used to connect to the HMI application. Defaults to "Undefined".
appName string readOnly The name of the HMI application. Defaults to "GoHMI".
appState integer readOnly, enum

The status of the HMI application.

The fields for this enumeration are:

Value Name
0 "ServiceNotStarted"
1 "Ready"
2 "Running"
3 "NotFound"
4 "HasWorkspace"
5 "NotCompatible"
6 "Error"
7 "ConnectIsAlreadyUp"
8 "ServiceIsLaunching"
9 "ApplicationIsStopping"
connectVersion string readOnly The version of the Smart HMI WebIQ Connect that is running on the same platform as the Gocator software.

/controls/hmi/outputs

HMI Service Output Map

Uses TextIdStandardOutputs output map.

For the AddAll command, the output ids are optional. If they are missing, they will be auto-generated using the "source" string. 
If it is present, then the client provided output id is used.

/controls/hmi/metrics

HMI Service Metrics

Currently there are no HMI metrics defined.

/controls/hmi/actions

HMI Service Actions

Resource Type:  (CollectionItem)

Description

A collection of HMI application actions defined by the HMI service.

Methods

Method Description
read

Returns a list of actions for the HMI service as embedded resources.

Examples:

HMI Service Actions Example
read /controls/hmi/actions
 
 Output:
 {
  "payload": {
    "_embedded": {
      "item": [
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/activate"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/deactivate"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/createApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/removeApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/downloadApp"
            }
          }
        },
        {
          "_links": {
            "self": {
              "href": "/controls/hmi/actions/uploadApp"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/controls/hmi/actions"
      }
    }
  },
  "status": 1,
  "type": "response"
 }

Notifications

None.

/controls/hmi/actions/(actionId)

HMI Application Action Ids

Resource Type:  (CollectionItem, Callable)

ID: Predefined by HMI service.

Description

A custom HMI service callable action. It can also be read to obtain information about the action such as the parameters supported.

Properties

Item Type Schema Description
parameters object readOnly

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

Action Parameters Returned Data
activate

None.

 None.
deactivate None. None.
createApp None. None.
removeApp None. None.
downloadApp None.

"data": ** binary byte stream ** of the HMI application ZIP file.

  • JSON binary object.
uploadApp

Changed in 0.3.x.x changed the "data" array from array of bytes to a binary byte stream.

"data": ** binary byte stream ** of the HMI application ZIP file.

  • JSON binary object.
 None.

Methods

Method Description
read

Reads the HMI service custom action resource.

Example response:

read /controls/hmi/actions/uploadApp
 
 Output:
 {
  "payload": {
    "_links": {
      "self": {
        "href": "/controls/hmi/actions/uploadApp"
      }
    },
    "id": "uploadApp",
    "parameters": {
      "data": []
    }
  },
  "status": 1,
  "type": "response"
 }
call

Calls the action resource.

Example request:

call /controls/hmi/actions/uploadApp {"parameters": {"data": ** binary byte stream **}}

Notifications

None.

Modbus Resources

This section describes the standard control protocol resources called Modbus Protocol that is included with each LMI Gocator release. Please refer to Control Resources page for general background on the control resources.

/controls/modbus

Modbus Protocol

Modbus supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, Modbus adds the following:

Properties:

Item Type Schema Description
displayName string readOnly

Set to "Modbus"
id string readOnly

Set to "modbus".

Parameters:

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

/controls/modbus/metrics

Modbus Protocol Metrics

Currently no Modbus metrics are defined.

/controls/modbus/outputs

Modbus Protocol Output Map

Modbus does NOT support the "outputs" resource.

/controls/modbus/registerAssemblies

Modbus Register Assemblies

Changed in 1.0.x.x added support for registerAssemblies resource.

Modbus supports the "registerAssemblies" resource. It has just one instance of the resource whose identifier is "registerAssembly-0".

   /controls/modbus/registerAssemblies/registerAssembly-0

/controls/modbus/registerAssemblies/(registerAssemblyId)

Modbus Protocol Register Assembly

Modbus register assembly instance has the following properties:

Properties:

Item

Type

 Schema

Description
supportedBlockTypes array<object>
Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Changed in 0.3.x.x added the following set of block type names.

Block type names used by Modbus are:

Block Type Internal Id (Type Name)
Control Input (for client to send commands to device) "ControlInput"
Control Output (for device to send back command status) "ControlOutput"
System (for system related information) "System"
Scanner (for scanner related information) "Scanner"
Stamp (for scan message stamp information) "Stamp"
Measurement (for scan measurement information) "Measurement"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMax

 integer

readOnly.

The maximum register address value of the service register assembly.

Changed in 0.3.x.x changed name from registerAddressMax to outputIdMax.

  • Value is set to 2999.
  • Removed "used" from schema.

attributes/outputIdMin

 integer

readOnly.

The minimum register address value of the service register assembly.

Changed in 0.3.x.x changed name from registerAddressMin to outputIdMin.

  • Value is set to zero (0).
  • Removed "used from schema.

GoPxL: Ethernet ASCII Resources

This section describes the standard control protocol resources called Ethernet ASCII Protocol that is included with each LMI Gocator release. Please refer to Control Resources page for general background on the control resources.

/controls/e-ascii

Ethernet ASCII supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, Ethernet ASCII adds the following:

Properties

Item Type Schema Description
displayName string readOnly

Set to "Ethernet ASCII"
id string readOnly

Set to "e-ascii".

Parameters:

Item Type Schema Description
allowAsync bool

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.3.5 added this parameter.
commandDelimiter character

Determines the delimter used to separate command fields and output fields.

Default value is ",".
controlPort number

16-bit port number of TCP connection used to connect to the Ethernet ASCII service.

Default value is 8190.

Minimum value is 0.

Maximum value is 65534.
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]"
delimiterTermination 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".
invalidValue string

A string that the Ethernet ASCII service uses to indicate that a measurement value is invalid.

Default value is "INVALID".
asyncFormatMode number

User configured output format mode that the Ethernet ASCII service should use when sending data to the Ethernet ASCII client in asynchronous mode operation.

0 = Standard formatting of output. The output format is "M<id><delim>V<value><delim>D<decision><delim>"

1 = 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 formatting (see customFormat description above). 

Default value is 0 ("Standard")

/controls/e-ascii/metrics

Ethernet Ascii Metrics

Currently no Ethernet ASCII metrics are defined.

/controls/e-ascii/outputs

Ethernet Ascii Output Map

Ethernet ASCII does NOT support the "outputs" resource

/controls/e-ascii/registerAssemblies

Ethernet Ascii Register Assemblies

Changed in 1.0.x.x added support for registerAssemblies resource.

Ethernet ASCII supports the "registerAssemblies" resource. It has just one instance of the resource whose identifier is "registerAssembly-0".

 /controls/e-ascii/registerAssemblies/registerAssembly-0

/controls/e-ascii/registerAssemblies/(registerAssemblyId)

Ethernet Ascii Register Assembly

Ethernet ASCII register assembly instance has the following properties:

Properties

Item Type Schema Description
supportedBlockTypes array<object>
Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Changed in 0.3.x.x added the following block names.

Block type names used by Ethernet ASCII are:

Block Type Internal Id (Type Name)
Scanner (for scanner related information) "Scanner"
Stamp (for scan message stamp information) "Stamp"
Measurement (for scan measurement information) "Measurement"
attributes
attributes/isGlobalAddressSpaceUsed bool readOnly False

attributes/outputIdMax

 integer

readOnly.

The maximum register address value of the service register assembly.

Changed in 0.3.x.x renamed from registerAddressMax to outputIdMax.

  • Removed "used" from schema.
  • value is set to 65534.

attributes/outputIdMin

 integer

readOnly.

The minimum register address value of the service register assembly.

Changed in 0.3.x.x renamed from registerAddressMin to outputIdMin.

  • Removed "used" from schema.
  • Value is set to zero (0).

EtherNet/IP Resources

This section describes the standard control protocol resources called Ethernet/IP Protocol that is included with each LMI Gocator release. Please refer to the Control Resources page for general background on the control resources.

/controls/ethernetIp

EtherNet/IP supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, EtherNet/IP adds the following:

Properties:

Item

Type

Schema

Description
displayName string readOnly

Set to "EtherNet/IP"
id string readOnly

Set to "ethernetIp".
enabled boolean read/write

Set to true for enabling EtherNet/IP service

Set to false for disabling EtherNet/IP service

Parameters:

Item

Type

Schema

Description
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 detected within a time frame shorter than the polling rate of the PLC. 
isBigEndianOutput boolean
Output in Big Endian Format
implicitTriggerOverride enum

Implicit Trigger Override

Macro Value Name
EIP_TRIGGER_OVERRIDE_OFF 0 Implicit Trigger Override Off
EIP_TRIGGER_OVERRIDE_CYCLIC 1 Implicit Trigger Override Cyclic
EIP_TRIGGER_OVERRIDE_STATE_CHANGE 2 Implicit Trigger Override Change of State


/controls/ethernetIp/metrics

EtherNet/IP Protocol Metrics

Currently no EtherNet/IP metrics are defined.

/controls/ethernetIp/outputs

EtherNet/IP Protocol Output Map

EtherNet/IP does NOT support the "outputs" resource.

/controls/ethernetIp/registerAssemblies

EtherNet/IP Register Assemblies

Changed in 1.0.x.x added support for registerAssemblies resource.

Ethernet/IP supports the "registerAssemblies" resource. It has multiple instances of the register assembly resource whose identifier are:

Register Assembly Name Register Assembly Id Rest API
Command Input 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 has an corresponding object in EtherNet/IP protocol. The mandatory objects doesn't have a register assemblies in EtherNet/IP. 
Register assembly cannot be created or deleted via the EtherNet/IP protocol.

Methods

Method

Description
read

Reads all register assemblies, the list of register assemblies are returned as embedded items.

Example response:

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

/controls/ethernetIp/registerAssemblies/(registerAssemblyId)

EtherNet/IP Protocol Register Assembly 

/controls/ethernetIp/registerAssemblies/commandInput

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly Command Input instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
Control Input (for client to send commands to device) "ControlInput"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 67.

/controls/ethernetIp/registerAssemblies/commandOutput

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly Command Output instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
Control Output (for device to send back command status) "ControlOutput"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 3.

/controls/ethernetIp/registerAssemblies/implicitCommandInput

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly Implicit Command Input instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
Control Input (for client to send commands to device) "ControlInput"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 67.

/controls/ethernetIp/registerAssemblies/sampleState

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly Scan Output instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
Stamp (for scan message stamp information) "Stamp"
Measurement (for scan measurement information) "Measurement"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 376.

/controls/ethernetIp/registerAssemblies/scannerState

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly Sensor Group State instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
Scanner (for scanner related information) "Scanner"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 504.

/controls/ethernetIp/registerAssemblies/systemState

EtherNet/IP Protocol Register Assembly 

EtherNet/IP register assembly System State instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by EtherNet/IP is:

Block Type

Internal Id (Type Name)
System (for system related information) "System"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 76.

PROFINET Resources

This page describes the standard control protocol resources called PROFINET Protocol that is included with each LMI Gocator release. Please refer to Control Resources page for general background on the control resources.

/controls/profinet

PROFINET Protocol

PROFINET supports the properties and parameters documented for Control Resources /controls/(serviceId)

In addition, PROFINET adds the following:

Properties:

Item Type Schema Description
displayName string readOnly

Set to "Profinet"
id string readOnly

Set to "profinet".

/controls/profinet/metrics

PROFINET Protocol Metrics

Currently no PROFINET metrics are defined.

/controls/profinet/outputs

PROFINET Protocol Output Map

PROFINET does NOT support the "outputs" resource.

/controls/profinet/registerAssemblies

PROFINET Register Assemblies

Changed in 1.0.x.x added support for registerAssemblies resource.

PROFINET supports the "registerAssemblies" resource. It has multiple instances of the resource whose identifier are:

 

Register Assembly Name Register Assembly Id Rest API
Command Input 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"

NOTE: Each module in PROFINET has corresponding register assembly support.
Register assembly cannot be created or deleted via the PROFINET protocol.

Methods

Method

Description
read

Reads all register assemblies, the list of register assemblies are returned as embedded items.

Example response:

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

/controls/profinet/registerAssemblies/(registerAssemblyId)

PROFINET Protocol Register Assembly 

/controls/profinet/registerAssemblies/commandInput

PROFINET Protocol Register Assembly 

PROFINET register assembly Command Input instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by Ethernet/IP is:

Block Type

Internal Id (Type Name)
Control Input (for client to send commands to device) "ControlInput"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 67.

/controls/profinet/registerAssemblies/commandOutput

PROFINET Protocol Register Assembly 

PROFINET register assembly Command Output instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by PROFINET is:

Block Type

Internal Id (Type Name)
Control Output (for device to send back command status) "ControlOutput"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 3.

/controls/profinet/registerAssemblies/stamp

PROFINET Protocol Register Assembly 

PROFINET register assembly Stamp Scan Output instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by PROFINET is:

Block Type

Internal Id (Type Name)
Stamp (for scan message stamp information) "Stamp"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 33.

/controls/profinet/registerAssemblies/measurement

PROFINET Protocol Register Assembly 

PROFINET register assembly Measurement Scan Output instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by PROFINET is:

Block Type

Internal Id (Type Name)
Measurement (for scan measurement information) "Measurement"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 800.

/controls/profinet/registerAssemblies/scannerState

PROFINET Protocol Register Assembly 

PROFINET register assembly Sensor Group State instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by PROFINET is:

Block Type

Internal Id (Type Name)
Scanner (for scanner related information) "Scanner"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 18.

/controls/profinet/registerAssemblies/systemState

PROFINET Protocol Register Assembly 

PROFINET register assembly System State instance has the following properties:

Properties:

Item

Type

Schema

Description

supportedBlockTypes

array<object>

Array of register block types that are supported by the control service's register assembly.
supportedBlockTypes/n/type string readOnly

Internal id that uniquely identifies the register block type.

Block type names used by PROFINET is:

Block Type

Internal Id (Type Name)
System (for system related information) "System"
attributes


attributes/isGlobalAddressSpaceUsed bool readOnly True

attributes/outputIdMin

 integer

readOnly

The minimum register address value of the service register assembly.

  • Value is set to zero (0).

attributes/outputIdMax

 integer

readOnly

The maximum register address value of the service register assembly.

  • Value is set to 76.

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.

Control Metrics

See Control Resources and sub pages for information about available metrics for each respective control protocol

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 specified helpURL will take precedence.
helpUrl  string readOnly Html help URL string for this routine. If both helpURL and helpHtml is specified helpURL 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
created

Occurs whenever a new routine instance is created.

Example:

{ "eventType": "created", "path": "/routines/routineId" }
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 form applies 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 is 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

Standard Routine Resources

Throughout this document, the annotation is used to indicated that a Resource, or particular aspect of a Resource is currently "in-progress" and subject to change.

The routines are listed here separately for easier searching and lookup.

Alignment Routine

Resource Type: N/A

Contains information on what an alignment routine contains and how it is designed to function.

Alignment Parameters

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 "g2xxx" scan engine and the first available scanner in the engine, usually "scanner-0".

Example:

update /routines/Alignment-0 {"parameters": {"scannerEngineId": "g2xxx", "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
  1. 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 "g2xxx" and "scanner-0" are the defaults. 
update /routines/Alignment-0 {"parameters": {"scannerEngineId": "g2xxx", "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

Metrics

Overview

The equivalent of health indicators in Gocator are called Metrics in GoPxL. 

This is in and of itself, a better name, because the Gocator 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 (min, max, average, and std deviation).

The subsequent sections describe the main areas that the Gocator 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 Gocator 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 GoPxL Metrics:

Metrics Path Description Gocator 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 (i.e., Gocator, Ascii, Ehternet/IP, 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 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;
    //...
};

Gocator Health Probe System

GoPxL metrics 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 in GoPxL 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 Gocator for viewing health such as:

  • health.cgi
  • kStudio 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 Health system was limited to outputting data as integer values.

GoPxL Metrics are intended to support more output data types, by leveraging the designs associated with flexible parameters and Schema and Data Types

Metrics resources can be read from to learn about the schema:

read /system/metrics

the response contains the schema:

 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": 1053257728,
      "memUsed": 127340960,
    },
    "status": {
      "encoderFreq": 0,
      "encoderValue": 0,
      "upTime": 8738
    }
  },
  "status": 1,
  "type": "response"
}

REST API

GoPxL Metrics 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 the GoPxL 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 (i.e., 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": 1053257728,
      "memUsed": 127340960,
    },
    "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 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.

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

Message Serialization

Overview

This section describes the serialization format of messages for scan data messages sent to external clients such as the GUI or SDK.

Message Header (Header)

Message Header is revised from Gocator as the control field is no longer needed. Since GoPxL will allow multiple scanners running at different rates, a single isLast flag received by the client is insufficient in identifying a complete data set.

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 3D Euclidean space with units of length defined in mm.

2 – Image Space. Data exists within a 2D Euclidean space with units 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. If hasTransform=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 if hasTransform= 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 if hasTransform= 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 (mm).
  • Y - Y-coordinate of the center (mm).
  • Z - Z-coordinate of the center(mm).
  • Width - Width is the size along the x-axis (mm).
  • Length- Length is the size along the y-axis (mm).
  • Height- Height is the size along the z-axis (mm).

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 a non-arrayed output) 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 of this message in the source array that contains the individual messages in the source array.

If arrayCount is 0, ignore this arrayIndex field.
dataSourceIdLength (DSIL)

16u

arrayIndex offset + 4

Length of the dataSource id in bytes.
dataSourceId char[] dataSourceIdLength offset + 2

DataSource Id used to identify the source of the message and distinguish multiple arrayed messages. 
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 message in 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

Changed in 0.3.x.x Added.

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.

Message Types

Message Types

Name

Type

Signal

1

Null

10

Stamp

11

Uniform Profile

12
Profile Point Cloud 13

Uniform Surface

14

Point Cloud Surface

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

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

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

Profile Point Cloud (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 Y-value.

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 is scale and offset values and the transform applied to it.

exposure

32f

Exposure in microseconds (us).

isAdjacent

8u

NOTE: This field is present ONLY for Point Cloud Surface. For Uniform Surface, this field is ABSENT.

Is the data Adjacent/Sorted (ie is it graphable)

0 = not adjacent.

1 = adjacent.

How FE GUI interprets this property:

  • isAdjacent means that points in surface data are sorted by X and Y positions, so that points in the same row are always sorted by X, and points in the same column are always sorted by Y
  • this is always the case with surface data generated by the sensor, but it may not be the case with data generated by tools - only the tool knows how it generates the data, so it is up to the tool to set the value of that flag of the surface data
  • the practical difference between adjacent and non-adjacent surface data is that only adjacent data (where the points are sorted) can be presented as a mesh, but non-adjacent data can only be presented as a points 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 Point Cloud Surface and is therefore PRESENT in the SurfaceAttrs for Point Cloud Surface.

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];
int xRange = range[0];
float xPos = (xRange * xScale) + xOffset;

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.

pixelFormat

32s

Pixel format:

1 – 8-bit greyscale

2 – 8-bit color filter

3 – 8-bits-per-channel color  (B, G, R, X)

colorFilter

32s

Color filter array alignment:

0 – None

1 – Bayer BG/GR

2 – Bayer GB/RG

3 – Bayer RG/GB

4 – Bayer GR/BG

reserved

16u

Reserved

exposure

32f

Exposure in microseconds (us).

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.

H9vYs6OWi7SAwAAAABJRU5ErkJggsVQkw==

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

Changed in 0.3.x.x Added.

If row based, this value is the image height.

if column based, his value is the image width.
spotCenterMin 32u

Changed in 0.3.x.x Added.

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.

spotCenterMax 32u

Changed in 0.3.x.x Added.

Maximum allowable raw value of a spot's center.

if row based, this value is typically the originating image width.

if column based, this value is typically the originating image height.

This is not the maximum of the actual spot center values, it is the maximum allowable raw value for spots in this message. There may not actually be a spot with a center value equal to spotCenterMax.

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) 

All counts of each graphic primitive were moved into this attribute section as of Changed in 0.3.x.x Added.
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

number of point sets (PointSet) contained in the graphics object. Changed in 0.3.x.x 
lineSetCount 16u

number of line sets (LineSet) contained in the graphics object. Changed in 0.3.x.x Added.
regionCount 16u

number of regions (Region) contained in the graphics object. Changed in 0.3.x.x Added.
planeCount 16u

number of planes (Plane) contained in the graphics object. Changed in 0.3.x.x Added.
rayCount 16u

number of rays (Ray) contained in the graphics object. Changed in 0.3.x.x Added.
labelCount 16u

number of labels (Label) contained in the graphics object. Changed in 0.3.x.x Added.
positionCount 16u

number of positions (Position) contained in the graphics object. Changed in 0.3.x.x Added.

PointSet

Field

Type

Description
pointSetAttrs PointSetAttrs PointSet Attributes section. See below.
points[C]

Point32f

Array of points.

Array of points where count C is from PointSetAttrs
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

LineSet

Field

Type

Description

linesetAttrs

LineSetAttrs

LineSet Attributes section. See below.
points[C]

Point32f

Array of points.

Array of points where C is from LineSetAttrs.
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

whether each 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)
Point32f

Field

Type

Description

x

32f

 x coordinate of point.
y 32f y coordinate of point.
z 32f z coordinate of point.
Point32s

Field

Type

Offset

Description

x

32s

0

 x coordinate of point.
y 32s 4 y coordinate of point.
z 32s 8 z coordinate of 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 the center 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

X component of the center of the region.
y

64f

Y component of the center of the region.
z

64f

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

X component of the normal vector.
yNormal

32f

Y component of the Normal vector.
zNormal

32f

Z component of the normal vector.

Ray

Field

Type

Description

attributeSize

16u

Size of attributes, in bytes, including this field.

xPosition

32f

x component of the position.
yPosition

32f

y component of the position.
zPosition

32f

z component of the position.

xDirection

32f

x component of the direction.
yDirection

32f

y component of the direction.
zDirection

32f

z component 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 position component of the label.
y

64f

y position component of the label.
z

64f

z position component 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 component of 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

X component of the position of the point.
yPoint

64f

Y component of the position of the point.
zPoint

64f

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

X component of the position of the point.
yPoint

64f

Y component of the position of the point.
zPoint

64f

Z component of the position of the point.
xDirection

64f

X component of direction vector.
yDirection

64f

Y component of direction vector.
zDirection

64f

Z component of direction vector.

Plane Feature

Field

Type

Description

header

Header

Message header (see above).
commonAttrs CommonAttrs Common Attribute Section (see above)
xNormal

64f

X component of the normal vector.
yNormal

64f

Y component of the normal vector.
zNormal

64f

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

X component of the center point of the circle.
yPoint

64f

Y component of the center point of the circle.
zPoint

64f

Z component of the center point of the circle.
xNormal

64f

X component of normal vector of the plane the circle is lying in.
yNormal

64f

Y component of normal vector of the plane the circle is lying in.
zNormal

64f

Z component of normal vector of the plane the circle is lying in.
radius

64f

Radius of the circle.

Common Types

This sections focuses on Data Types as described in the Back End, none of this information should be used by clients. For message serialization information, see Message Serialization Format

Data Types

The types here are used in a few places including the Message Serialization message header

Name Value Notes
Signal 1 Used to signal the GUI to clear the visualizer
Null 10 Null Message carrying a status message from tool developers
Stamp 11 Represents the stamp message, which contains the time and encoder values for the data the moment the data was collected. Stamps are always in "None" spaceType.
Uniform Profile 12 A uniform (aka "resampled) profile. Primary data structure is a 1-dimensional array of Z values. X values are implied by array index. Profiles are always in "Data" spaceType, and have XZ values with units of mm.
Profile Point Cloud 13 A non-uniform (aka "raw") profile. Primary data structure is a 2-dimensional array of XZ values. Profiles are always in "Data" spaceType, and have XZ values with units of mm.
Uniform Surface 14 A uniform (aka "resampled) surface. Primary data structure is a 2-dimensional array of Z values. X and Y values are implied by array indices. Surfaces are always in "Data" spaceType, and have XYZ values with units of mm.
Point Cloud Surface 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 is 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 may be added over time, so applications should interpret unknown negative status codes as ERROR.

ParamSet

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 but 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. The GoPxL GUI client will only show 3 levels of nesting. After that, additional nesting levels will be combined into a single level.

For example, the ParamSet for a simple tool might look like this:

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.

Control Service Status

This represents the status of a control service.

Name Value
Running 0
Stopped 1
Starting 2
Stopping 3
Failed To Start 4
Failed To Stop 5

HMI Application Status

This represents the status of an HMI application started up by the HMI service.

Name Value Description
Service Not Started 0 HMI control service is not enabled (started).
Ready 1 HMI application is ready to use.
Running 2 HMI application is running (activated).
Not Found 3 HMI application was not found.
Has Workspace 4 HMI application has a workspace (is loaded in the WebIQ Designer).
Not Compatible 5 HMI application was created with higher version of WebIQ Connect than the one that is being used by the GoPxL.
Error 6 Unexpected WebIQ Connect API call error.
Connect Is Already Up 7

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).
Service Is Launching 8 HMI control service has been enabled and is starting up.
Application Is Stopping 9 HMI application is being stopped.

Extended Types 

See Schema and Data Types.

Terminology

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 is 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) noted in the 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 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" 
}

Schema and Data Types

Overview

A client must know the "shape" of an object to be able to use it. The "shape" in this case refers to the structure of the object, the types of each of its members, and other meta data describing the object and its fields. Traditionally, the shape is defined as a part of the protocol. However there are times where a client must discover this shape at runtime, without prior knowledge.

Some notable examples that require this dynamic discovery:

  1. Client-Side validation: In some cases the client (eg the GUI) needs to know the validation data about a given property on a resource. Simple examples include min/max for numeric inputs, and options for enum/list inputs. 
  2. Dynamic client generation: In some cases the GUI needs to dynamically generate its views based on the shape of the resources. This is the case for tools, where the tool developer specifies the parameters available for a given tool type, but the GUI does not know about this in advance.

The schema system allows the shape of an object to be expressed through a standardized format. It designed to be extensible so that meta data can be added over time without breaking compatibility. A client can simply choose to ignore meta data that it does not understand.

The design of the schema documents is based on the design of JSON Schema and is more-or-less a subset of functionality. Many of the concepts and terminologies are borrowed from this spec, so as to minimize the possibility of confusion caused by inconsistency. Future developers familiar with JSON schema should find themselves at home working with our schema format. This approach should allow us to claim compliance with JSON Schema Validation standard, at which point many existing 3rd party tools and libraries may become usable.

Our implementation has the following non-inclusive set of limitations from the official JSON schema spec:

This list may change over time.

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 practise, 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. Keywords defined here are applicable to to all types.

Keyword Category Type Description
type Assertion string or array of strings

Enumerates the possible JSON types of the field. Available types are “object”, “array”, “number”, "integer", “boolean”, “string”, "binary", and “null”. An instance validates if and only if the instance is in any of the sets listed for this keyword.

Type can be an array of strings. For example ["object"] or even ["object,"string"]. However GoPxL's use of JSON schema makes very limited use of this capability. Arrays will only be used on one of the following 2 ways

  1. Array contains a single type of the above list (eg ["object"]). This has no effect - an array containing a single type can be treated as a single type
  2. Array contains a single type of the above list and null (eg ["object", "null"]. This is used as a way of declaring whether an instance supports null or not (ie, is nullable).

Official JSON Schema spec does not support "binary", but GoPxL's spec does. This is because GoPxL'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 must be a base64 encoded string. In "pure" JSON Schema, this is equivalent to:

{ type: "string",contentEncoding: "base64"}

GoPxL won'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.

The "extendedType" keyword offers much of the same functionality as the "format" keyword in official JSON Schema spec which has a few pre-defined formats. GoPxL does not support nor use any of these defined formats. In the future, the "extendedType" keyword may be deprecated in favor of the "format" keyword.
readOnly Both boolean

If "readOnly" has a value of boolean true, it indicates that the value of the instance is managed exclusively by the Back End and not the Front End, and attempts by a Front End to modify the value of this property are expected to be ignored or rejected, at the Back End's discretion.

This keyword can apply both to single-value instances (number, integer, boolean, string, binary, null) as well as multi-value instances (object, array). For multi-value instances, the entire instance is considered readOnly, including any children.
used Annotation boolean

A property is normally used. It is not used if its associated feature is disabled; in this case, the current value has no effect on operation.

The 'used' field is the manner by which the Back End can hint to the Front End that a particular property is "applicable" or "no longer applicable". 

When 'used' is false, the Front End should strive to remove all visible entities related to such property from its display.
actual Annotation (ValueType)

Sometimes the actual value of a property is overriden by a system-calculated one. For example, if the 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".
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 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.

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.
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 Groups but 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
{
  "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",
  ...
}

TransformedBoxRegion

Base type: object

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

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

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 contains string 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
AppId string Unique ID of the application instance. Mandatory.
AppVersion string Version of the application instance
ControlPort number Raw socket REST API port. Typically 3600 but can vary to avoid port conflicts.
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) 
GdpPort number Gocator Data Protocol port. Typically 3196 but can vary to avoid port conflicts.
IsRemote boolean True if LMI device is remotely connected/controlled from another GoPxL instance. Remote sensors should generally not to be connected to via the control API. This includes websocket connections on path /ws/controlAsync, as well as raw socket connections on ControlPort.
Address string Configured host address. When GoPxL is running on PC, this could be the address of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).
Mask string Configured host subnet mask. When GoPxL is running on PC, this could be the subnet mask of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).
Gateway string Configured host gateway. When GoPxL is running on PC, this could be the gateway of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).
Dhcp boolean True if DHCP is enabled. When GoPxL is running on PC, this could be the DHCP state of any reachable interface. When running on LMI device, it shall be of the primary ethernet interface (eg interface 1).
AddressConflict boolean The IP address may have been automatically assigned due to an address conflict.

An example of the reply message payload from the sensor:

'{"SerialNumber":"DeviceModel","45045":"2330"}'

The client, upon receiving the reply, verifies the header fields (Length, Message Id and Signature). Then the remaining bytes in the stream of bytes starting at location for Message Payload is to be treated as a string, and parsed using a JSON parser.

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

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 3210, 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 The request/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 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 here

Over time, as the protocol evolves and changes, this list may grow. Methods will rarely, if ever, be removed. Such an act would be a breaking protocol change.
path string Yes the path of the resource, eg "/system/commands"
payload JSON No

If the resource requires request data (sometimes called "arguments", but not to be confused with "args" below), they should be in the payload object. 

If no request data is required the payload should be an empty object "{}" or null (as specified in the Resource Reference).
args JSON No

Additional method arguments passed to the request handler. Args modify the way the method is processed, and are not typically handled by the resource request. These are defined within the context of application logic, rather than the protocol.
See for example: Documentation Conventions#ReadTrait:ExpandLevelArgumentExpandLevel and Documentation Conventions#ReadTrait: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 Sometimes

Changed in 1.0.x.x The "path" field is the resource path in the request message, if the request supplied a resource path.

This value can also be 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. 
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.

If no payload is available, it can be a JSON null, especially for the last message in a streamed sequence.

When the type is "response", the payload contains the content relevant to the request.

When the type is "notification", the payload contains the content pertaining to the relative URI path raising the event notification.
status signed integer Yes

Status of the request. See here for a list of possible status codes. 

This status code is not related to the carrier message layer. For example, a request for a resource which doesn't exist would return status == OK in the carrier message and status != OK in the Control message.

Think of the carrier message status = OK as meaning "message received" and the control message status != OK as meaning "request failed".

When response status is not OK, there may be errors in the payload to help explain the failure. See Error Handling for more detail about how error messages are provided in this case.
type string Yes

This field indicates the type of response message.

There are three response message types:

Message Type Description
"response" Response type messages are the logical/semantic reply to a request.
"notification"

Notification type messages are asynchronously provided to the client for a particular resource.

These are usually generated in response to a request to report resources affected by the request.

Notification messages for a resource is sent to a client if the client has subscribed to that resource.
"stream"

Stream type messages are asynchronously sent to the client if the client has subscribed to a streamable resource.


Request Response Type Message

Request response type of response message are response messages from the server for the client's request. This type of response message has all the fields for a basic response message described above.

Example: read request to the resource "/logs/summary". In this example, the "path" field value is also present in the "payload/_links/self/href" field. 

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


Notification Type Message

Notification type response messages are messages from the server sent asynchronously to the client, that is not a response to an explicit client request. For notification type messages, an "eventType" field is present at the top level, in addition to the basic response message fields.

Field Type Required Description
eventType string Yes

Changed in 1.0.x.x 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"
path string Yes

Changed in 1.0.x.x The path is the resource that generated the notification.
payload json No Content associated with the event notification.  This is usually all the properties normally provided via a read of the same resource.

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

Changed in 1.0.x.x 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.
streamId unsigned integer Yes

Changed in 1.0.x.x 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.
streamStatus string Yes

Changed in 1.0.x.x 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.

Example:

Commands used for this example:
stream "/dataSources/scan:g2xxx:scanner-0:top:profile:uniform/data"

{
"path": "/dataSources/scan:g2xxx:scanner-0:top:profile:uniform/data",
"payload": {
"type": 12,
"commonAttrSize": 151,
"hasTransform": true,
...
"xOffset": -16.25,
"zOffset": 0.0004,
"exposure": 100.09765625
},
"status": 1,
"streamId": 1,
"streamStatus": "streaming"
"type": "stream"
}

Not all resources support streaming, and some resources may only support streaming. Error is returned when trying to access these resources in an unsupported manner.

Payload could be a binary or it could be JSON data. This is specified in the documentation of the respective resource.

Documentation Shorthand

For brevity, the documentation adopts a shorthand when providing examples of requests. The shorthand follows the following general syntax

METHOD PATH {PAYLOAD} [{ARGUMENTS}]

Arguments are optional, and are therefore only documented where appropriate.

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

LMI Technologies, Inc. • www.lmi3d.com