Commands and Formats

Commands are sent from the client to the sensor. The commands are not case sensitive. However, the readprop command's metrics path argument is case sensitive.

The command format is:

<COMMAND><DELIMITER><PARAMETER><TERMINATION>

If a command has more than one parameter, each parameter is separated by the delimiter.

Similarly, the reply has the following format:

<STATUS><DELIMITER><OPTIONAL RESULTS><DELIMITER>

The status can either be "OK" or "ERROR". The optional results can be relevant data for the command if successful, or a text based error message if the operation failed. If there is more than one data item, each item is separated by the delimiter.

You can change the delimiter and termination characters in the Special Character settings in the GoPxL interface. For more information, see Ethernet ASCII Protocol.

Measurement IDs come from the ID field in the connection map. Be sure to add measurements to the connection map and make note of the IDs of the measurements you need to add to the data format.

Ethernet ASCII client commands

Ethernet ASCII client commands

Command

 Arguments

Description
start - Starts the sensor.
stop - Stops the sensor.
trigger - Software Trigger.
loadjob Job name

Load the specified job file, up to 63 character long, including the last null terminating character.
result -

Return the measurement or string data specified in the custom format string.

For a description of the measurement value (prefixed with the letter "V") and decision (prefixed with the letter "D") format, see Measurement Output Format and String Output Format.
One or more measurement or string IDs, separated by command delimiter.

Return the measurement or string data for each measurement or string ID in the following format string: M[ID],V[VALUE],D[DECISION],...

Note that string data will not include a decision.

Example: result,0,1

Output: OK,M0,V-5000,D0,S1,VsampleString
measurement One or more measurement IDs, separated by command delimiter.

Return the measurement data for each measurement ID in the following format string: M[ID],V[VALUE],D[DECISION],...

For a description of the measurement value (prefixed with the letter "V") and decision (prefixed with the letter "D") format, see Measurement Output Format.

Example: measurement,0,1

Output: OK,M0,V-5000,D0,M1,V5000,D1
string One or more string IDs, separated by command delimiter.

Return the string data for each string id in the following format string: S[ID],V[VALUE],,...

For a description of the string value (prefixed with the letter "V"), see String Output Format.

Example: string,0,1

Output: OK,S0,VsampleString,S1,V2ndString
value One or more measurement or string IDs, separated by command delimiter.

Return the measurement or string value for each measurement or string ID in the following format string: M/S[ID],V[VALUE],...

For a description of the measurement/string value (prefixed with the letter "V"), see Measurement Output Format and String Output Format.

Example: value,0,1

Output: OK,M0,V-5000,S1,VsampleString
decision One or more measurement IDs, separated by command delimiter.

Return the measurement decision for each measurement ID in the following format string: M[ID],D[DECISION],...

For a description of the measurement decision (prefixed with the letter "D") format, see Measurement Output Format.

Example: decision,0,1

Output: OK,M0,D0,M1,D1
stamp

 

 

 -

Return the time, encoder and frame index stamp values for the first stamp ID found.

Order of values returned is: Time, Encoder, Frame.

For the "time" argument, this is the timetick of the last frame.

A timetick is a 64-bit positive integer that is guaranteed to increase monotonically starting from zero. It is guaranteed to be unique for every scan from a given sensor group.

To convert this value to microseconds, use the following:

time in microseconds = timetick / 1.024

Example: stamp

Output: OK,Time,381497381349,Encoder,0,Frame,18,

One or more of these arguments in any order, separated by the command delimiter:

"time"

"encoder"

"frame"

Return the specified stamp value(s) in the order of the provided arguments.

Example: stamp,time,frame

Output: OK,381497381349,18

A stamp ID.

Return the time, encoder, and frame index stamp values for the passed stamp ID.

Example: stamp,1
time One or more stamp IDs, separated by command delimiter.

Return the stamp's time value for each stamp ID.

The timetick of the last frame.

A timetick is a 64-bit positive integer that is guaranteed to increase monotonically starting from zero. It is guaranteed to be unique for every scan from a given sensor group.

To convert this value to microseconds, use the following:

time in microseconds = timetick / 1.024

Example: time,1

Output: OK,381497381349
encoder One or more stamp IDs, separated by command delimiter.

Return the stamp's encoder value for each stamp ID.

Example: encoder,1

Output: OK,0
frame One or more stamp IDs, separated by command delimiter.

Return the stamp's frame index stamp value for each stamp ID.

Example: frame,1

Output: OK,18
align - Performs the alignment operation.
clearalign - Clears sensor alignment.
readprop One or more strings representing a resource whose property to return, separated by command delimiter.

Returns the resource JSON object specified by the resource path.

It is possible to use JSON pointers to retrieve a specific value within the JSON document.

 

Example #1: readprop,/system

Output: OK,{"_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":true,"runState":1},

 

Example #2: readprop,/system#/runState,/system#/autostart

Output: OK,1, true,

 

Example #3: readprop,/jobs#/loadedJob

Output: OK,"Job02",

 

Example #4: readprop,/jobs#/loadedJobDirty

Output: OK,false,

The following lists the possible errors for each command.

Ethernet ASCII error handling

Command

 Arguments

Description
start ERROR,Could not start the sensor
stop ERROR,Could not stop the sensor
trigger ERROR,Could not trigger
loadjob ERROR,Job name required. Job name has to be provided as a command argument.
  ERROR,Failed to load job <job name>.gpjob
result ERROR,There is no measurement data to output. Please confirm that the sensor is running Could not find any measurements. Make sure protocol's connection map is not empty and the sensor is running.
ERROR,Invalid parameter. Please verify your input Provided command argument was invalid. It must be a number.
ERROR,Specified measurement ID not found. Please verify your input Could not find a measurement data for specified ID.
ERROR,The custom format string is not valid. Please verify your input Custom format string is invalid.
measurement ERROR,One or more measurement ID must be provided Measurement ID has to be provided as an argument.
ERROR,There is no measurement data to output. Please confirm that the sensor is running Could not find any measurements. Make sure protocol's connection map is not empty and the sensor is running.
ERROR,Invalid parameter. Please verify your input Provided command argument was invalid. It must be a number.
ERROR,Specified measurement ID not found. Please verify your input Could not find a measurement data for specified ID.
string ERROR,One or more string ids must be provided. String ID has to be provided as an argument.
ERROR,There is no data to output. Please confirm that the sensor is running. Could not find any data. Make sure protocol's connection map is not empty and the sensor is running.
ERROR,Invalid parameter. Please verify your input. Provided command argument was invalid. It has to be a number.
ERROR,Specified id not found. Please verify your input. Could not find an output for specified ID.
value ERROR,One or more measurement/string ids must be provided. Measurement/string ID has to be provided as an argument.
ERROR,There is no data to output. Please confirm that the sensor is running. Could not find any data. Make sure protocol's connection map is not empty and the sensor is running.
ERROR,Invalid parameter. Please verify your input. Provided command argument was invalid. It has to be a number.
ERROR,Connection with id not found. Could not find data for specified ID.
decision ERROR,One or more measurement ids must be provided. Measurement ID has to be provided as an argument.
ERROR,There is no data to output. Please confirm that the sensor is running. Could not find any data. Make sure protocol's connection map is not empty and the sensor is running.
ERROR,Invalid parameter. Please verify your input. Provided command argument was invalid. It has to be a number.
ERROR,Connection with id not found. Could not find data for specified ID.
ERROR,String connection with id does not contain a decision. A string id was included in the decision command.
ERROR,Connection with id %u is not a measurement or string. An id mapping to neither measurement nor string was included in the decision command.
stamp ERROR,Invalid stamp command format. Invalid command arguments.
ERROR,One or more stamp ids must be provided. Stamp ID has to be provided as an argument.
ERROR,Invalid parameter. Please verify your input. Provided stamp ID was invalid. It has to be a number.
ERROR,Stamp with id not found. Could not find stamp data for specified ID.
ERROR,Connection id is not a stamp. Specified id was not a stamp.
time ERROR,One or more stamp ids must be provided. Stamp ID has to be provided as an argument.
ERROR,Invalid parameter. Please verify your input. Provided stamp ID was invalid. It has to be a number.
ERROR,Stamp with id not found. Could not find stamp data for specified ID.
ERROR,Connection id is not a stamp. Specified id was not a stamp.
encoder ERROR,One or more stamp ids must be provided. Stamp ID has to be provided as an argument.
ERROR,Invalid parameter. Please verify your input. Provided stamp ID was invalid. It has to be a number.
ERROR,Stamp with id not found. Could not find stamp data for specified ID.
ERROR,Connection id is not a stamp. Specified id was not a stamp.
frame ERROR,One or more stamp ids must be provided. Stamp ID has to be provided as an argument.
ERROR,Invalid parameter. Please verify your input. Provided stamp ID was invalid. It has to be a number.
ERROR,Stamp with id not found. Could not find stamp data for specified ID.
ERROR,Connection id is not a stamp. Specified id was not a stamp.
align ERROR,Could not align
clearalign ERROR,Could not clear alignment
readprop ERROR,String representing a resource must be provided Resource path must be provided as an argument.
ERROR,Could not read property

Resource may not exist.

Data Output Format Mode

Polling Mode

Polled data output is displayed using the custom format. You can modify this format in the GoPxL interface. For more information, see Ethernet ASCII Protocol. Because polling mode is always available, even when asynchronous output is enabled, you can always modify the custom format.

Format Mode

Description
Custom

This format can be changed/edited by the user.

Default formatting is: %time, %value[0] %decision[0]

It is possible to format the specified measurement or string value according to the format string.

This pattern does not apply to measurement decisions.

Example: %sprintf[%9.3f, %value[0]] to format the measurement value of measurement id 0 as a floating-point number with 9 digits and 3 decimal places.

Asynchronous Mode

When asynchronous output mode is enabled, the data output can be in one of three formats:

Format Mode

Description
Standard

This is a pre-defined format that cannot be changed. The format is available as Read-Only information for reference.

Formatting is: M[id],V%value[id],D%decision[id],...

Note that string ids will not include decisions.
Standard with Stamp

The format is the Standard format pre-pended with the Time and Encoder information.

This is a pre-defined format that cannot be changed. The format is available as Read-Only information for reference.

Formatting is: T%time,E%encoder,M[id],V%value[id],D%decision[id],..

Note that string ids will not include decisions.
Custom

This format is the same as the format used by Poll mode and can be changed/edited by the user.

Default formatting is: %time, %value[0] %decision[0]

It is possible to format the specified measurement value according to the format string.

This pattern does not apply to measurement decisions.

Strings can also be formatted using sprintf.

Example: %sprintf[%9.3f, %value[0]] to format the measurement value of measurement id 0 as a floating-point number with 9 digits and 3 decimal places.

Measurement Output Format

A measurement contains the fields described below.

Field

Type

 Address offset Description
Value 32s 0

Measurement value. This value is the actual measurement value multiplied by 1000.

If the measurement value is invalid, the string "INVALID" is the output for the measurement value.
Decision 8u 4

Measurement decision.

Bit 0: 

0 = Fail

1 = Pass

Bit 1:

0 = Decision value is valid

1 = Decision value is invalid

String Output Format

A string contains the fields described below.

Field

Type

 Address offset Description
Value string 0

String value.

If the string value is invalid, the invalid value parameter is output.