Optimet Plugin for Mach 4 Programming Guide · Mach 4 provides an extensive application programming...

Optimet Plugin for

Mach 4

Programming Guide

2/25/2016 ©2016 Flexware Innovation, Inc.

2

©2016 Flexware Innovation, Inc.

Contents

1 Overview .............................................................................................................................................. 4

1.1 Audience ....................................................................................................................................... 4

2 Register Interface ................................................................................................................................ 5

2.1 Overview ...................................................................................................................................... 5

2.1.1 Register Naming Conventions ............................................................................................. 5

2.1.2 Register Categories .............................................................................................................. 5

2.1.3 Register Data Types ............................................................................................................. 6

3 Plugin API ............................................................................................................................................. 7

3.1 Command Register Interface ...................................................................................................... 7

3.2 Command Response .................................................................................................................... 8

3.2.1 Command Response Format ............................................................................................... 8

3.2.2 Return Code vs. Response Message ................................................................................... 8

3.2.3 Error Response Examples .................................................................................................... 9

3.3 Command List ............................................................................................................................ 10

3.4 Command Reference ................................................................................................................. 10

3.4.1 AutoConnect ...................................................................................................................... 10

3.4.2 ClearMeasurementBuffer ................................................................................................... 11

3.4.3 ClearZeroReference ............................................................................................................ 11

3.4.4 Connect................................................................................................................................ 12

3.4.5 Disconnect ........................................................................................................................... 12

3.4.6 SaveMeasurementBuffer ................................................................................................... 12

3.4.7 SetAcquisitionParameters .................................................................................................. 13

3.4.8 SetActiveLens ...................................................................................................................... 13

3.4.9 SetZeroReference .............................................................................................................. 14

3.4.10 SetZeroReferenceFromSample ......................................................................................... 14

3.4.11 StartMeasurementStream................................................................................................. 14

3.4.12 StopMeasurementStream .................................................................................................. 15

3.4.13 TakeSingleMeasurement .................................................................................................... 15

3.4.14 TakeZeroReferenceSample ................................................................................................ 15

4 Register List ......................................................................................................................................... 17

4.1 Configuration Registers .............................................................................................................. 17

4.2 Command Registers ................................................................................................................... 19

3


4.3 Status Registers ......................................................................................................................... 19

5 Script Example ................................................................................................................................... 22

4


1 Overview Mach 4 provides an extensive application programming interface (API) which allows end users to

extend and customize the application’s behavior. One way to access this API is by creating macros

(scripts). The main scripting language supported by Mach 4 is Lua. The current version of Mach 4

contains a complete development environment for editing, running, and debugging Lua scripts from

within Mach 4.

The Optimet plugin is designed to take advantage of the scriptable nature of Mach 4. When the

Optimet plugin is loaded by Mach 4, the plugin creates a register interface which exposes

configuration, status, and command registers to the Mach 4 platform. (A register is a named piece

of memory shared between the plugin and the Mach 4 application.) End users can take advantage of

this register interface to create custom macros for many tasks, including configuring the probe,

taking measurements, and even storing results to a file.

The software package for the Optimet plugin includes several macros to perform basic tasks, such as

starting and stopping the probe’s measurement stream. The Optimet Plugin User’s Guide describes

how to integrate these macros with G code. If the included macros fulfill your project’s

requirements, you do not need to perform any custom programming as described in this guide.

1.1 Audience This programming guide is intended for users who wish to extend the functionality of Mach 4 and

the Optimet probe to perform more complex tasks.

This guide assumes the following:

The user is familiar with Mach4CoreAPI.chm (this is the API documentation included with

Mach 4).

The user can create, edit, and debug scripts within the Mach 4 application.

The user understands how to integrate macros with G code.

Please refer to the Mach4 Scripting Manual and Mach4 Operation Manual for additional information on

the above topics.

5


2 Register Interface

2.1 Overview A register is a named value that is shared between the Mach 4 application and a plugin. The Mach 4

API provides a function, mcRegGetHandle, which looks up a register by name and returns its handle.

(A handle is a unique numeric value assigned by Mach 4 and is how most APIs interact with

registers.)

Mach 4 allows several plugins to be loaded simultaneously. It also allows several devices of the same

type to be created within the same plugin. To guard against name collisions, each register is

identified by a path that includes the device name and register name. When accessing a register via

Mach 4, the full path name must be used. Generally, the format of this path is

DeviceName/RegisterName.

All of the Optimet plugin’s registers are accessed as OptimetPlugin0/RegisterName. As an example,

OptimetPlugin0/StatusActiveLensDescStr accesses a register that contains a string description of

the currently active lens.

2.1.1 Register Naming Conventions Optimet registers are divided into three logical categories: status registers, configuration registers,

and command registers. These categories are described in more detail in section 2.1.2. Additionally,

Optimet registers can hold different types of data – such as string and long – as described in section

2.1.3. The register category and data type determine how the register should be used and accessed

using the Mach 4 API. This is described in more detail in the following sections.

The name of each register contains information about its category type and data type. The category

type is specified in the prefix, and the data type is specified in the suffix. Because registers follow

this naming convention, they are self-documenting.

2.1.2 Register Categories Registers are divided into 3 categories:

1. Status registers

2. Configuration registers

3. Command registers

2.1.2.1 Status Registers

A status register is an output parameter with respect to the Optimet plugin. Status registers allow a

script to inspect the state of the plugin. For example, StatusActiveLensDescStr contains a string

description of the currently active lens.

IMPORTANT: Status registers are output-only. User scripts should only read these registers. User scripts should never modify these registers.

6


2.1.2.2 Configuration Registers

A configuration register is an input parameter with respect to the Optimet plugin. Configuration

registers allow a script to set parameters for a command before invoking the command. For

example, CfgSetZeroRefDistanceDbl allows the user to set the zero reference distance (a double

value) prior to invoking the SetZeroReference command.

2.1.2.3 Command Registers

The command register is also an input parameter with respect to the Optimet plugin. There is only

one command register for the entire plugin, named CmdChannel. Scripts use the mcRegSendCommand

function (provided by Mach 4) to write commands into CmdChannel. A command is executed by the

plugin synchronously, as soon as it is received. A complete list of commands is provided in section 3.

2.1.2.4 Summary

Category Register Name Prefix Data Direction Example Register

Status Status Output StatusActiveLensDescStr

Configuration Cfg Input CfgSetZeroRefDistanceDbl

Command Cmd Input CmdChannel

2.1.3 Register Data Types A status or configuration register is designed to hold one of the following types of data:

1. String

2. Long

3. Double

4. Boolean

Mach 4 provides different functions for reading and writing values of different data types (e.g.

mcRegGetValueLong and mcRegGetValueString). By indicating the data type in the register name, it

is clear which API to use to work with values.

Data Type Register Name Suffix

Mach 4 API Example Register

String Str mcRegGetValueString, mcRegSetValueString

StatusProbePropSerialNumberStr

Long Long mcRegGetValueLong, mcRegSetValueLong

StatusProbeFrequencyLong

Double Dbl mcRegGetValue, mcRegSetValue

StatusLastMeasurementDistanceDbl

Boolean1 Bool mcRegGetValueLong1, mcRegSetValueLong1

StatusIsBufferEmptyBool

1 Mach 4 does not have native support for a Boolean type. Boolean values are stored as a long: 0 is false and 1 is true. Use mcRegGetValueLong and mcRegSetValueLong to get and set Boolean values.

7


3 Plugin API This section describes the list of commands supported by the Optimet plugin.

3.1 Command Register Interface The Optimet plugin supports receiving commands from macros (scripts) via its command register,

named CmdChannel. The workflow for running a command always follows this pattern:

1. Set the configuration register(s) associated with the command, if any.

2. Write the command to the CmdChannel register using the mcRegSendCommand function.

3. Read the status register(s) with the result(s), if needed.

Not all of these steps apply to every command. For example, the TakeSingleMeasurement command

[see 3.4.13] has no input configuration registers associated with it, so step 1 can be skipped.

Refer to section 5 for a complete example.

8


3.2 Command Response The mcRegSendCommand function allows the plugin to return a string containing response information.

The Optimet plugin uses this response string to indicate status and to report detailed error

information upon failure. End users may use some or all of this information to help when creating

and debugging scripts.

3.2.1 Command Response Format If a command completes with no errors, the response string simply contains the value OK.

For error cases, the response is a multi-field string where each field is delimited by the pipe (|)

symbol. To make parsing simple, field values are guaranteed not to contain the pipe symbol. The

format of the error response string is as follows:

ERR|<plugin-error-msg>|<has-lib-error-code>|<library-error-code>|<has-lib-error-

msg>|<lib-error-msg>

Field Description ERR Upon failure, the first field always contains the string ERR <plugin-error-msg> An error message generated by the plugin. This value is always set. <has-lib-error-code> This field indicates if the next field (library-error-code) contains a

valid value. This field is t (true) if the library error code field is set. This field is f (false) if the library error code is not set.

<library-error-code> If a failure occurs in a 3rd party library (such as Smart32) and a numeric error code is available, it will be captured and placed into this field. Otherwise, this field will contain 0 and should be ignored.

<has-lib-error-msg> This field indicates if the next field (lib-error-msg) contains a valid value. This field is t (true) if the library error message is set. This field is f (false) if the library error message is not set.

<lib-error-msg> If a failure occurs in a 3rd party library (such as Smart32) and a string message is available, it will be captured and placed into this field. Otherwise, this field will contain the empty string and should be ignored.

3.2.2 Return Code vs. Response Message The mcRegSendCommand function returns two values to the caller: (1) a Mach 4 return code and (2) a

response string. It is very important to understand the distinction between these values.

The Mach 4 return code only indicates if the command was delivered to the plugin and ran to

completion. It does not indicate if there were logic errors that caused the command to fail when the

plugin executed it. The return code is a numeric value in the MERROR_* family, including

MERROR_NOERROR if the command was delivered successfully and ran to completion. Refer to the

Mach4CoreAPI.chm help file in the Mach4 Docs directory for the list of return codes that apply to

mcRegSendCommand.

The response string indicates the final disposition (success or failure) of executing the command.

This value is set by the plugin prior to returning control to Mach 4 and is described in section 3.2.1.

9


Please keep the following in mind when handling return values:

If the Mach 4 return code indicates failure, the response string should not be used. It is

possible the command was not processed by the plugin and the plugin did not set a value.

It is normal for the Mach 4 return code to indicate success (because the command

completed within the Mach 4 framework) and the response string to indicate ERR (because

the command itself could not be executed or failed). Scripts should check both values for

error status.

3.2.3 Error Response Examples

3.2.3.1 Example #1: Send SetZeroReferenceFromSample with no zero reference sample set

In this example, a script attempted to set the zero reference from the zero reference sample, but no

zero reference sample was available. There is no library error code or library error message in this

response.

ERR|No zero sample is available to set the zero reference distance|f|0|f|

3.2.3.2 Example #2: Send TakeSingleMeasurement when the probe is not connected

In this example, a script attempted to take a measurement before the Connect command was

executed. There is no library error code or library error message in this response.

ERR|The action could not be completed because the network connection to the probe has not been initialized|f|0|f|

3.2.3.3 Example #3: Send TakeSingleMeasurement when network cable is unplugged

In this example, the host PC had connected to the probe, and then the network cable was

disconnected. There is both a library error code (1) and message (“Communication problem…”) in

this response.

ERR|Failed to take single measurement|t|1|t|Communication problem: select() or recv() failed.

10


3.3 Command List Command Description Cross Reference

AutoConnect Establish a network connection with the probe. The host IP address must be provided, but the probe’s IP address will be automatically discovered.

3.4.1

ClearMeasurementBuffer Clear all measurements in the measurement buffer.

3.4.2

ClearZeroReference Reset the zero reference. 3.4.3

Connect Establish a network connection with the probe. Both the host IP address and the probe IP address must be provided.

3.4.4

Disconnect Tear down the network connection with the probe. (It is rare that an end user will need to execute this command.)

3.4.5

SaveMeasurementBuffer Store the measurement buffer to a file. 3.4.6

SetAcquisitionParameters Change the probe’s frequency and laser power settings.

3.4.7

SetActiveLens Change the probe’s active lens setting. 3.4.8

SetZeroReference Set the zero reference to a user-specified value.

3.4.9

SetZeroReferenceFromSample Set the zero reference to the value of the most recent zero reference sample (see TakeZeroReferenceSample).

3.4.10

StartMeasurementStream Instruct the probe to begin streaming measurements and capture measurements into the measurement buffer.

3.4.11

StopMeasurementStream Instruct the probe to stop streaming measurements.

3.4.12

TakeSingleMeasurement Instruct the probe to take one measurement at the current location. This measurement will be stored in the measurement buffer.

3.4.13

TakeZeroReferenceSample Instruct the probe to take a measurement and store it as the zero reference sample (see SetZeroReferenceFromSample).

3.4.14

3.4 Command Reference

3.4.1 AutoConnect Use this command to establish an Ethernet connection between the host PC and the probe. The

caller must provide the IP address of the adapter on the host PC. The probe will be auto-discovered.

(Use the Connect command [see 3.4.4] if you wish to specify the probe IP address instead.) If there

is an existing connection, it will be torn down before trying to establish a new connection.

11


3.4.1.1 Configuration Parameters

CfgHostIpStr: This must be set to the IPv4 address of the adapter on the host PC to use for

the connection. The address should be in dotted notation. Segments of the IP address

should not be zero-padded. For example, 1.2.3.9.


StatusIsConnectedBool: This will be set to true (1) if the connection was successful.

Otherwise, this value will be zero.

StatusHostIpStr: This will be set to the address of the host PC if successful.

StatusProbeIpStr: This will be set to the special value AUTO to indicate the connection was via

auto-discover.

NOTE: Several other status registers related to the probe’s properties, lens settings, and

acquisition parameters will also be initialized if the connection is successful. The list is too

numerous to enumerate all of the values here. Refer to section 4.3 for a complete list of status

registers related to the probe.

3.4.2 ClearMeasurementBuffer Use this command to clear all of the measurements from the measurement buffer. This essentially

begins a new scanning session. The measurement buffer is only cleared when instructed to do so

using this command. (Calling StartMeasurementStream will append measurements to the existing

buffer.)


None


StatusMeasurementBufferSizeLong: This will be reset to 0

StatusIsBufferEmptyBool: This will be reset to false (0)

NOTE: All of the status registers related to the last measurement will also be reset to their initial

values.

3.4.3 ClearZeroReference Use this command to clear (reset) the zero reference. When measurements are transformed into

point cloud coordinates, they will no longer be relative to the zero reference.


None


StatusIsZeroReferenceSetBool: This will be reset to false (0)

StatusZeroReferenceDistanceDbl: This will be reset to 0.0

NOTE: As a side effect of invoking this command, all of the status registers related to the last

measurement will be recomputed. In addition, if the GUI is visible, the visualization will be redrawn.

12


3.4.4 Connect Use this command to establish an Ethernet connection between the host PC and the probe. The

caller must provide the IP address of the adapter on the host PC and the IP address of the probe.

(Use the AutoConnect command [see 3.4.1] if you do not wish to specify the probe IP address.) If

there is an existing connection, it will be torn down before trying to establish a new connection.


CfgHostIpStr: This must be set to the IPv4 address of the adapter on the host PC to use for

the connection. The address should be in dotted notation. Segments of the IP address

should not be zero-padded. For example, 1.2.3.9.

CfgProbeIpStr: This must be set to the IPv4 address of the probe. The address must be in

dotted notation, and segments should not be zero-padded. For example, 1.2.3.4.


StatusIsConnectedBool: This will be set to true (1) if the connection was successful.

Otherwise, this value will be zero.

StatusHostIpStr: This will be set to the dotted IPv4 address of the host PC if successful.

StatusProbeIpStr: This will be set to the dotted IPv4 address of the probe if successful.

NOTE: Several other status registers related to the probe’s properties, lens settings, and

acquisition parameters will also be initialized if the connection is successful. The list is too

numerous to enumerate all of the values here. Refer to section 4.3 for a complete list of status

registers related to the probe.

3.4.5 Disconnect Use this command to tear down the network connection between the host PC and the probe. It is

rare that this command should be needed.


None


StatusIsConnected: This will be set to false (0) when the connection is torn down.

NOTE: Disconnecting from the probe does not affect the contents of the measurement buffer.

3.4.6 SaveMeasurementBuffer Use this command to write the contents of the memory buffer to a file.


CfgSaveBufferFormatStr: Sets the output format of the file (e.g. comma separated or tab

delimited). Refer to the definition of this register in section 4.1 for the list of valid values for

this field.

CfgSaveBufferFilePathStr: Sets the output file path of the file. This should be an absolute

path, including a drive letter on Windows.

13


CfgSaveBufferSnrLong: Sets the signal-to-noise ratio threshold used to filter measurements

when saving to a file. This value indicates the SNR as a percentage (0-100). Measurements

with an SNR % below this value will not be written to the file.

CfgSaveBufferTotalMinLong: Set the total energy minimum threshold used to filter

measurements when saving to a file. Measurements with a total value below this value will

not be written to the file.

CfgSaveBufferTotalMaxLong: Set the total energy maximum threshold used to filter

measurements when saving to a file. Measurements with a total value above this value will

not be written to the file.


N/A – This command does not update any status registers.

3.4.7 SetAcquisitionParameters Use this command to change the laser power and frequency settings within the probe.


CfgProbeLaserPowerLong: Set this to the new laser power value to be used by the probe.

Typically, this is a value from 0 (minimum) to 4095 (maximum).

CfgProbeFrequencyLong: Set this to the new frequency value to be used by the probe. This

value should be greater than 1. The maximum frequency varies by type of probe.

CfgProbeAutoExposureBool: Set this to true (1) to enable the probe’s auto-exposure

feature, which causes the probe to auto-adjust the laser power for consistent results. (When

enabled, the laser power value represents the maximum laser power the probe may use.)

Set this to false (0) to disable the probe’s auto-exposure feature.

NOTE: if the probe does not support auto-exposure, this parameter is completely ignored.


StatusProbeLaserPowerLong: Upon successful completion, this contains the probe’s new

laser power setting.

StatusProbeFrequencyLong: Upon successful completion, this contains the probe’s new

frequency setting.

StatusProbeAutoExosureEblBool: Upon successful completion, this contains the probe’s new

auto-exposure setting.

3.4.8 SetActiveLens Use this command to change the active lens setting within the probe. The index of the new active

lens must be provided.


CfgActiveLensLong: The zero-based index of the new active lens. Note that because the

index is used, you will need some insight into the probe’s firmware configuration. The

configuration dialog in the Optimet Plugin GUI lists lenses in order by index from 0 to max.

14



StatusActiveLensDescStr: Upon successful completion, this contains a string description of

the new active lens (e.g. 50 mm).

StatusActiveLensMinDistanceDbl: Upon successful completion, this contains the minimum

distance that can be measured with the new active lens, in millimeters.

StatusActiveLensMaxDistanceDbl: Upon successful completion, this contains the maximum

distance that can be measured with the new active lens, in millimeters.

3.4.9 SetZeroReference Use this command to set the zero reference to a fixed value. When the zero reference is set,

distance measurements will be reported relative to the zero reference value.


CfgSetZeroRefDistanceDbl: Set this to the desired zero reference value. This value must be in

millimeters.


StatusZeroRefDistanceDbl: This will be set to the new zero reference value if successful.

StatusIsZeroReferenceSetBool: This will be set to true (1) to indicate the zero reference is

set.



3.4.10 SetZeroReferenceFromSample Use this command to set the zero reference sample as the zero reference value. When the zero

reference is set, distance measurements will be reported relative to the zero reference value. It is an

error to use this command if a zero reference sample is not available.


None


StatusZeroRefDistanceDbl: This will be set to the new zero reference value if successful.

StatusIsZeroReferenceSetBool: This will be set to true (1) to indicate the zero reference is

set.



3.4.11 StartMeasurementStream Use this command to begin collecting a stream of measurements from the probe. All of the

measurement values reported by the probe will be collected in the measurement buffer. If the

stream is already active, this command does not take any action and returns success.

15



None


StatusIsStreamingBool: This will be set to true (1) when the stream is started.

NOTE: While the measurement stream is active, all of the StatusLastMeasurement* registers will be

updated periodically to show activity within the measurement buffer. Please refer to the table in

section 4.3 for information about these registers. In addition, StatusMeasurementBufferSizeLong

and StatusIsBufferEmptyBool will also be updated periodically to reflect updated values during the

streaming process.

3.4.12 StopMeasurementStream Use this command to stop collecting a stream of measurements from the probe. If the stream is not

currently active, this command does not take any action and returns success.


None


StatusIsStreamingBool: This will be set to false (0) when the stream is stopped.

NOTE: All of the StatusLastMeasurement* registers will be updated when the last measurement is

placed into the buffer. Also, StatusMeasurementBufferSizeLong and StatusIsBufferEmptyBool

will be updated to reflect the measurement buffer’s final size and state.

3.4.13 TakeSingleMeasurement Use this command to immediately take a single measurement using the probe. The measurement

will be added to the end of the measurement buffer.


None


StatusMeasurementBufferSizeLong: This value will be incremented by 1 when the

measurement is added to the measurement buffer.

StatsuIsBufferEmptyBool: This value will be set to false (0) when the buffer is no longer

empty.

NOTE: All of the StatusLastMeasurement* registers will also be updated to reflect the new

measurement.

3.4.14 TakeZeroReferenceSample Use this command to take a sample measurement immediately using the probe. The measurement

will be recorded as the zero reference sample. It is not added to the measurement buffer. If the

16


measurement is acceptable, it can be set as the zero reference by calling

SetZeroReferenceFromSample (see section 3.4.10).


None


StatusIsZeroSampleSetBool: This register will be set to true (1) to indicate that a zero

reference sample is available.

StatusZeroSampleDistanceDbl: This register will be set to the measurement distance

received from the probe, in millimeters.

StatsuZeroSampleSnrDbl: This register will be set to the SNR value corresponding to the

sample, as a percentage.

StatusZeroSampleTotalLong: This register will be set to the total energy value corresponding

to the sample.

17


4 Register List This section describes all of the configuration and status registers available through the Optimet

plugin.

4.1 Configuration Registers Register Name Description Used by CfgActiveLensLong The zero-based index of the lens

that should become the active lens. The index is dependent on the firmware configuration of the probe.

SetActiveLens

CfgHostIpStr The IPv4 address of the host PC adapter to use for the Ethernet connection to the probe. The format is dotted notation. Individual address segments should not be zero-padded.

AutoConnect Connect

CfgProbeIpStr The IPv4 address of the probe. The format is dotted notation. Individual address segments should not be zero-padded.

Connect

CfgProbeFrequencyLong The probe’s new frequency, in Hz. This value must be greater than 1. The maximum frequency varies by type of probe.

SetAcquisitionParameters

CfgProbeLaserPowerLong The probe’s new laser power. This value must be positive and cannot exceed the probe’s maximum laser power, normally 4095. Note that if the auto-exposure feature is enabled as described below, this value represents the probe’s maximum allowed laser power.


CfgProbeAutoExposureBool Set to true (1) to enable auto-exposure, which allows the probe to adjust the laser power dynamically to try to achieve consistent results. Set to false (0) to disable auto-exposure, in which case the laser power is fixed to the user-entered value. Note that not all probes support this feature. If the feature is not supported, this parameter is simply ignored.


18


Register Name Description Used by CfgSaveBufferFormatStr A string representing the output

file format when saving the measurement buffer to a file. Valid values are:

xyz_csv: spatial coordinates [(x,y,z) ordered triplets] written as a sequence of comma-delimited values

xyz_txt: spatial coordinates [(x,y,z) ordered triplets] written as a sequence of tab-delimited values

report_csv: measurement values (distance, SNR, total) and corresponding (x,y,z) coordinates written as a sequence of comma-delimited values

report_txt: measurement values (distance, SNR, total) and corresponding (x,y,z) coordinates written as a sequence of tab-delimited values

SaveMeasurementBuffer

CfgSaveBufferFilePathStr A string containing the full path, with drive letter, of the location to write the output file.


CfgSaveBufferSnrLong A value representing the minimum SNR required for a measurement to pass the output filter. Measurements with an SNR reading below this value will be skipped when writing the file.


CfgSaveBufferTotalMinLong A value representing the minimum total energy allowed for a measurement to pass the output filter. Measurements with a total energy reading below this value will be skipped when writing the file.


19


Register Name Description Used by CfgSaveBufferTotalMaxLong A value representing the

maximum total energy allowed for a measurement to pass the output filter. Measurements with a total energy reading above this value will be skipped when writing the file.


CfgSetZeroRefDistanceDbl The distance, in millimeters, to set as the zero-reference.

SetZeroReference

4.2 Command Registers CmdChannel This register is the data path for

sending commands to the Optimet plugin. To trigger an action, the name of a command should be written into this register with the mcRegSendCommand function. Refer to the Mach 4 API help file for details.

(All commands)

4.3 Status Registers Register Name Description StatusIsBufferEmptyBool True (1) if the measurement buffer count is 0, false (0)

otherwise. StatusIsConnectedBool True (1) if the host PC has established a connection to the

Optimet probe, false (0) otherwise. StatusIsStreamingBool True (1) if the probe is currently streaming measurements

to the host PC, false (0) otherwise. StatusIsZeroReferenceSetBool True (1) if the zero reference is set (indicating that the

plugin should calculate relative measurements), false (0) otherwise.

StatusIsZeroSampleSetBool True (1) if the zero reference sample is set, false (0) otherwise. The SetZeroReferenceFromSample command will fail if the zero reference sample is not set.

StatusHostIpStr The IPv4 address associated with the host PC adapter that is connected to the probe.

StatusProbeIpStr The IPv4 address associated with the probe that the host PC is connected to. If the connection was established using the auto-discover method, this will be the special value AUTO.

StatusProbePropSerialNumberStr The serial number associated with the probe that the host PC is connected to.

20


Register Name Description StatusActiveLensDescStr A friendly string description of the active lens, such as 50 mm

or 25G mm. StatusActiveLensMinDistanceDbl The shortest distance from the probe that can be measured

with the active lens, in millimeters. StatusActiveLensMaxDistanceDbl The longest distance from the probe that can be measured

with the active lens, in millimeters. StatusProbeFrequencyLong The probe’s current frequency value, in Hz. StatusProbeLaserPowerLong The probe’s current laser power. (If auto-exposure is

enabled, this is the maximum laser power.) StatusProbeHasAutoExposureBool True (1) if the connected probe supports auto-exposure,

false (0) otherwise. StatusProbeAutoExposureEblBool True (1) if the auto-exposure feature is enabled on the

connected probe, false (0) otherwise. StatusLastMeasurementEncXLong The X encoder value associated with the most recent

measurement in the measurement buffer.2 StatusLastMeasurementEncYLong The Y encoder value associated with the most recent

measurement in the measurement buffer.2 StatusLastMeasurementDistanceDbl The distance value associated with the most recent

measurement in the measurement buffer. 2 StatusLastMeasurementSnrDbl The SNR value associated with the most recent

measurement in the measurement buffer. This value is reported as a percentage from 0% – 100%.2

StatusLastMeasurementTotalLong The total energy value associated with the most recent measurement in the measurement buffer.

StatusLastMeasurementPointXDbl The spatial x-coordinate associated with the most recent measurement in the measurement buffer, in millimeters.2 (This value represents the measurement’s point cloud position.)

StatusLastMeasurementPointYDbl The spatial y-coordinate associated with the most recent measurement in the measurement buffer, in millimeters.2 (This value represents the measurement’s point cloud position.)

StatusLastMeasurementPointZDbl The spatial z-coordinate associated with the most recent measurement in the measurement buffer, in millimeters.2 (This value represents the measurements’ point cloud position.)

StatusZeroSampleDistanceDbl The measurement distance associated with the most recent zero reference sample, in millimeters. (See TakeZeroReferenceSample.)

StatusZeroSampleSnrDbl The SNR associated with the most recent zero reference sample, reported as a percentage (0% - 100%). (See TakeZeroReferenceSample.)

StatusZeroSampleTotalLong The total energy associated with the most recent zero reference sample. (See TakeZeroReferenceSample.)

21


Register Name Description StatusZeroRefDistanceDbl The measurement distance of the zero reference, in

millimeters. (See SetZeroReference or SetZeroReferenceFromSample.)

StatusMeasurementBufferSizeLong The number of measurements in the measurement buffer.2

2 When streaming is active, this register is updated periodically based on the plugin’s internal update interval, usually 250ms. It is not updated after every single measurement is placed into the measurement buffer. This is because the register interface is not designed as a high speed interface, so it is not possible to keep the register interface in sync with a high speed measurement stream. These status registers can be used to keep track of progress and provide feedback during a scan; they cannot be monitored to track every measurement that is taken.

22


5 Script Example The following script is an example of how to write a macro to interface with the Optimet plugin. This

script is designed to set the zero reference to a pre-defined value.

function m122() local mInst = mc.mcGetInstance() local cfgHReg, rc = mc.mcRegGetHandle(mInst, "OptimetProbe0/CfgSetZeroRefDistanceDbl") local rc = mc.mcRegSetValue(cfgHReg, 40.0) local hReg, rc = mc.mcRegGetHandle(mInst, "OptimetProbe0/CmdChannel") local response, rc = mc.mcRegSendCommand(hReg, "SetZeroReference") end if (mc.mcInEditor() == 1) then m122() end

This script begins by defining a function named m122. A function that will be used as a macro should

be named m<value> and should be placed in a file named m<value>.mcs. (The above script is in a file

called m122.mcs.) To be visible to Mach 4, the macro file must be placed into the Macros directory

associated with the Mach 4 profile used for scanning. Refer to the Mach 4 Scripting Manual for more

information.

First, the function gets the index of the Mach 4 instance in which the script is running. (Mach 4 may

have more than one instance running concurrently.) This value is required for subsequent Mach 4

calls.

Next, the function gets the handle of the CfgSetZeroRefDistanceDbl register using

mcRegGetHandle. Notice that the register name is fully qualified and includes the device name

(OptimetProbe0).

Once the handle of the register is available, the value can be set. The next line uses mcRegSetValue

to modify the register with a double value. In this example, the value is hard-coded to 40.0. (If you

follow the Mach 4 Operation Manual and Mach 4 Scripting Manual, you can learn how to create your

own registers and associate them with text fields on a Mach 4 screen set. This would allow you to

modify a control in the Mach 4 GUI at run time, read the control’s value from within the script, and

set the zero reference to a user-defined value instead of a hard-coded value.)

After the configuration register is set, the command may be executed. The next line retrieves the

handle of the CmdChannel register.

The next line sends the SetZeroReference command to the plugin using the CmdChannel register

handle. This is done using the mcRegSendCommand function. Note that all commands are executed

synchronously, so mcRegSendCommand does not return until the plugin has completed the command.

23


This means that if you wish to read one or more status registers after executing a command, you are

guaranteed that they are updated and stable before the function returns.

At the end of the script, you will notice some logic which checks to see if the script is running in the

Mach 4 editor. This is a convenience that will allow you to load the script file in the Mach 4 Lua script

editor and debug/run the macro function within the editor. Refer to the Mach 4 Programming Guide

for more information.

For simplicity, note that this script does not perform error checking on return codes when calling

Mach 4 functions. In general, the Mach 4 API returns 0 (equivalent to MERROR_NOERROR) for success

and non-zero to indicate failure.

The response variable that is set when calling mcRegSendCommand is a string that is set by the Optimet

plugin before returning. This string contains detailed status information, including error information

if a command fails. The format of the response string is described in section 3.2.

Optimet Plugin for Mach 4 Programming Guide · Mach 4 provides an extensive application programming...

Documents

Transcript of Optimet Plugin for Mach 4 Programming Guide · Mach 4 provides an extensive application programming...