BOA Spot

Scripting Guide

BOA Spot Scripting Guide 1 Version 1.5; 2019-9-18

 Notice
BOA Spot Scripting Guide
Document Number 405-00060-00
Copyright 2019 Teledyne Imaging.
All rights reserved.

All copyrights in this manual, and the hardware and software described in it, are the
exclusive property of Teledyne Imaging and its licensors. Claim of copyright does not imply
waiver of Teledyne Imaging or its licensors other rights in the work. See the following
Notice of Proprietary Rights.

NOTICE OF PROPRIETARY RIGHTS

This manual and the related products are confidential trade secrets and the property of
Teledyne Imaging and its licensors. Use, examination, reproduction, copying, transfer
and/or disclosure to others of all or any part of this manual and the related documentation
are prohibited except with the express written consent of Teledyne Imaging.

The information in this document is subject to change without notice. Teledyne Imaging
makes no representations or warranties with respect to the contents of this manual and
specifically disclaims any implied warranties of merchantability or fitness for a particular
purpose. Teledyne Imaging assumes no responsibility for errors or omissions in this
document.

The Teledyne Imaging logo is a trademark of Teledyne Imaging. All other

trademarks are the property of their respective owners.

Teledyne Digital Imaging US, Inc.

Information: [email protected]
Support: [email protected]
Web: http://www.teledynedalsa.com/visionsystems

700 Technology Park Drive

Billerica, MA, USA 01821
Tel 1.978.670.2002 Fax 1.978.670.2010

BOA Spot Scripting Guide 2 Version 1.5; 2019-9-18

Table Of Contents

Introduction About Scripting in iNspect for BOA Spot ……………………...... 5

The Script Panel Accessing the Script Panel ……………………...... 6

Variable Tree List ……………………...... 7

Function List ……………………...... 7
Script Editor ……………………...... 8
Scripting Basics ……………………...... 9

About Variables Special Global Variables ……………………...... 10

Persistent Variables ……………………...... 11

Variable Basics ……………………...... 11
Variable Listing ……………………...... 12

About Functions Preordered Functions ……………………...... 13

Periodic Function ……………………...... 13

Function Timing ……………………….. 14

Function Listing ……………………….. 15

- String and Character Functions ……………………….. 15

- Tool Statistics & Attributes Functions ……………………….. 15

- Digital IO & Acquisition Control Functions ……………………….. 15

- Logging Functions ……………………….. 16

- Serial IO Functions ……………………….. 16

- Comm & TCP IO Functions ……………………….. 16
- System & Misc. Functions ……………………...... 17

String Editor String Formatting Window ……………………...... 18

String Formatting Reference ……………………...... 19

Script Examples Manipulating Outputs ……………………...... 21

Hide and Show Variables ……………………...... 23

Disable and Enable Tools ……………………...... 23
Solution Switching ……………………...... 24
Trigger Control ……………………...... 26

BOA Spot Scripting Guide 3 Version 1.5; 2019-9-18

 Image Logging ……………………...... 27

Adding a Wait ……………………...... 28

Communicating Using Strings ……………………...... 28

Customizing Text in the Monitor panel ……………………...... 30

Manipulating Text in the Graphics Tool ……………………...... 32

Using Arrays ……………………...... 33

Using arrays for Communication ……………………...... 36

BOA Spot Scripting Guide 4 Version 1.5; 2019-9-18

Introduction

About Scripting in iNspect for BOA Spot

Scripting offers greater application flexibility by allowing users to define or manipulate
system control and integration features. The Script Tool differs from the rest of the BOA
Spot GUI in that it supports the use of functions and more traditional programming
constructs.
Scripting is not always required for basic applications that only require a pass/fail
decision output, but it is widely used for communicating with 3rd party devices over
Ethernet or serial RS-232.
An in-depth knowledge of software design is not a prerequisite for using the Scripting
Tool, but a basic understanding of process control is essential.
Note: This manual was written for all models of the BOA Spot: SL, EL, IDS, IDE. The
examples may use tools that are not available on all models.

Support
In addition to this user manual, help with scripting is available from the following:
1. Online help: Fingertip help is available on every screen (panel) of the BOA Spot
User Interface
2. Self help material and sample job files are included on the BOA Spot CD
3. Call, fax or email your local Teledyne Imaging representative who sold you the
product
4. Factory support is available at [email protected]

BOA Spot Scripting Guide 5 Version 1.5; 2019-9-18

The Script Panel

Accessing the Script Tool

The Script Tool is mostly used for control and communication, which is why it follows the
Connections button in the Navigation bar.
Click the Script button in the Navigation bar to open the Edit Scripts menu.

Inside the script panel there are 3 sections. The control panel on the left side contains a
variable tree list and function list. On the right side below the image window is the Script
Function manager.

BOA Spot Scripting Guide 6 Version 1.5; 2019-9-18

The Variable Tree List
The variable tree at the top of the control panel lists all of the variables available to the
script tool, namely:

• Tool outputs from user-defined

measurements (i.e. L.Result)
• Predefined keywords (control words
such as PassCount)
• Discrete I/O (physical inputs and
outputs available to the device )
• User variables
Variables can have Boolean meaning, such
as TRUE/FALSE or ON/OFF, or they can
store numbers or strings of user defined
information.

The Function List

The Function list is available at the
bottom of the control panel. It contains
the predefined functions for solution
initialization, preprocessing. post
processing and periodic. These functions
are empty when starting a new solution,
meaning they do nothing until you add
something to them.

To edit a function, select it in the function list. In the bottom panel click the Edit button to
open a separate Edit window.

BOA Spot Scripting Guide 7 Version 1.5; 2019-9-18

 The Script Editor
The editor buttons provide drop-down menus for quick access to functions, variables,
equation operators and program flow commands. A string editor is included to simplify
the formatting of communication strings to external devices. Clicking on a drop-down
feature from the list will add it to the script. Manually add parameters and associated
control statements to each script as required.

The “Check Syntax” button checks the “programmatic grammar” of the individual
strings, but cannot parse the statements for runtime context errors that may occur
outside this window. The bottom pane may show syntax error messages. You can
click on a message to highlight the related line of code in the upper pane.

Equations associated with a function can be exported to a user defined text file by
clicking the “Export” button. Similarly, equations stored in a local text file can be
imported into a selected function by clicking the “Import” button. This is a convenient
method of sharing scripts or script snippets (application specific code) across
solutions.

BOA Spot Scripting Guide 8 Version 1.5; 2019-9-18

 Scripting Basics
1. Comment your code. This will make it much easier for you to debug should you
need to come back to the solution at a later time. You can add comment lines using
the prefix "//" (two forward slashes) for example: // Initialize the x array
2. All of your expressions, equations, and variables are saved in the Solution file, and
persist when the Solution file is reloaded.
3. Statements are formed in a plain algebraic format, for example: a = b+c
4. Functions are called simply in the form: z = aFunctionName(param1, param2)
5. Variable names have a limit of 60 characters
6. A line of script has a limit of 256 characters. Numbers of lines are only limited by
available memory.
7. Max time for the Pre-image Process function is 100 ms
8. Max time for Post Image Process function is 300 ms
9. Max time the Solution Initialize function is 1000 ms
10. Max time for the Periodic function is under 200 ms
11. The time a Script takes can be reduced significantly by sending an array of data
verses multiple read/writes (time to send an array is the same as a single piece of
data). Bit functions can also be used.
12. It is good practice to always close “If” statements with “Endif”, even though this is
not required for single command statements. This makes code easier to read and
debug.
13. Once created, script variables will persist even if you delete them inside a script. A
variable can be selected and deleted from the variable tree list or by starting a new
solution.

BOA Spot Scripting Guide 9 Version 1.5; 2019-9-18

About Variables

There are 3 classes or types of variables that can be used in a script:

1. Global device variables – variables associated with external hardware such as I/O
2. Global control variables – variables that provide system wide status or control
3. Local user variables – variables associated with tools or functions defined by the user

Special Global Variables

Some special variables are not visible in the variable tree or the free editor. These
variables are as follows:
• ShowPreprocessed - Enables (=1) or disables (=0) display of preprocessing in ROI
at runtime
• RelearnIndex - uses one of the General Purpose Inputs to trigger retraining or
relearning specific tools (Match, Locator, Barcode, 2D Code, OCR). RelearnIndex=1
will execute a relearn (in the next acquired image) when GPI[1] is asserted.
(RelearnIndex=2 will execute when GPI[2] is asserted.) This statement should be
added in the Solution Initialize function. To assign a tool to relearn, create a new
Relearn variable. For example, to assign a Match “MS1” to be retrained,
MS1.Relearn=1. The Match tool will be retrained (in the next image) when the input
assigned by RelearnIndex GPI[1] is asserted.
NOTE: The inputs on the BOA Spot read 1 when nothing is connected, or when the input
is lower than the logic threshold. You must be careful to connect the input so that GPI[1]
will only read 1 when relearn is desired, or use the RelearnOnZero variable.
• RelearnOnZero - RelearnOnZero =1 forces relearn to occur when the defined Relearn
input (RelearnIndex) is 0, not 1. This statement should be added in the Solution
Initialize function. NOTE: GPI[0] is the BOA Spot trigger input.
The Result variable returns the result from each defined camera, as well as the overall
inspection result. Result.0 variables return the result before an action is decided (i.e. it is
made available so that user-defined functions can use it to define actions).
Result=1 (PASS)
Result=2 (RECYCLE)
Result=3 (FAIL)

BOA Spot Scripting Guide 10 Version 1.5; 2019-9-18

You can override (not typical for most applications) the composite result, by adding
variables "PASS", "RECYCLE", "FAIL", (must be all capitals) and setting their values to 1
(for TRUE) or 0 (for FALSE).

NOTE: In formation of (creating or composing) the final Result, FAIL supersedes

RECYCLE, and RECYCLE supersedes PASS. Put your tests for FAIL, RECYCLE, PASS
in the "Post Image Processing" function.

Persistent Variables
When a solution is saved, any associated variables are saved also. When a solution is
loaded, only its associated variables are loaded. This means that variables associated
with the previous solution will be deleted unless they are also saved in the new solution.
The exception to this rule is Persistent Variables. These special variables will persist
even if the solution that created them is replaced by a different solution. Persistent
variables are therefore used more for system (BOA Spot) variables as opposed to
solution specific variables. Persistent variables will persist until the BOA Spot camera is
power cycled. Persistent variables are defined with a Prog prefix and can also be saved
in a solution file (i.e. Prog.myvariable)

Variable Basics
1. Use square brackets for variable names, especially names with spaces in them.
Notice that variable names inserted or dragged into a field, are enclosed in brackets.
2. All of your expressions, equations, and variables are saved in the Solution file, and
persist when the Solution file is reloaded.
3. User added variables belong to the current Solution. Loading a different Solution will
cause your user variable set to be replaced with the set belonging to that new
Solution.
4. There are many pre-defined variables with special meaning for use in scripts. You can
also create your own variables. Referencing a variable automatically creates or
instantiates that variable. A separate step for creating or declaring, is not necessary.
5. A complete listing of predefined variables follows on the next page.

BOA Spot Scripting Guide 11 Version 1.5; 2019-9-18

Variable Listing
• Result.0 - the value of Result, before it is output. This allows equations to evaluate
the Result, before the decision is sent to the monitor, decision I/O and other
mechanisms. Result.0 returns 3 values: 1=Pass, 2=Recycle, 3=Reject.
• Result - the result of all measurements (the "composite result"). This result is sent
to the Monitor, decision I/O and other communication mechanisms (such as PLC,
Ethernet, serial port, etc.). Result returns 3 values: 1=Pass, 2=Recycle, 3=Reject.
Each measurement also has a Result (i.e. L1.Result).
• Global.GPI[#] - a general purpose input. The Camera treats and evaluates all
inputs as a steady state logic input. NOTE: GPI[0] is the BOA Spot Trigger input.
• Global.GPO[#] - a general purpose output. Normally, the outputs are held high or
low, until the next result is available. (The Pass/Recycle/Fail decision outputs are
pulsed.) You can use the pulse function or use the Delayed Event Function to create
a pulse output. If the strobe is enabled, GPO[0] is the strobe output.
• Global.RunMode - the current run-state or running mode. 0=running, 1=stopped.
• Global.FrameCount - number of frames or images acquired since a Solution was
loaded, or since the statistics was reset ("Reset Statistics" button on the Monitor
panel).
• Global.Missed - number of missed parts or frames.
• Global.ContinuousMissed - number of parts or frames missed in a row, or one
after another.
• Global.PassCount - the value of the Pass counter, or the number of Passed parts.
• Global.FailCount - the value of the Fail counter, or the number of Failed parts.
• Global.RecycleCount - the value of the Recycle counter, or the number of
Recycled parts.
• Global.ContinuousPassCount - the number of parts or frames passed in a row, or
one after another.
• Global.ContinuousFailCount - the number of parts failed in a row, or one after
another.

BOA Spot Scripting Guide 12 Version 1.5; 2019-9-18

About Functions

Variables are manipulated using functions. Functions are made up of equations or

instructions that affect an outcome or result. Most functions can be shared or called by
other functions (like subroutines). Some functions are executed in order (pre-ordered
functions), while others are based on a user defined event, such as a time interval or
transition on a Global Input. Pre-ordered functions are a special class of functions that
execute in a pre-defined order. They can call other functions, but can not be called by
other functions.
BOA Spot includes a library of pre-defined functions for analysis, system control and
communication. A complete listing of predefined functions starts on page 15.

Pre-Ordered Functions
Every solution has 3 pre-ordered functions which execute in the order below:

1. Solution Initialize – called immediately after a solution is loaded. Typically used to

initialize variables or outputs to a known state.
2. Pre-Image Processing – called immediately after a new image is received, but before
processing begins. Can be used to handshake with other devices or control external
I/O.
3. Post-Image Processing – Called immediately after processing. Typically used to
formulate results and communicate with external devices.

Periodic Function
In addition, there is the Periodic function which executes in a background thread.
Periodic: 200 ms – called every 200 milliseconds. Can be used to check for
communication from external devices, or physical inputs.

BOA Spot Scripting Guide 13 Version 1.5; 2019-9-18

Function Timing

Image Acquire Image Pre Process Process Image Post Process

Pre-Ordered Functions

time

start end

Periodic Event Function

The above diagram depicts the timing associated with functions. Pre-ordered functions
are synchronized to the start and of end of each inspection. The Periodic function
shown in the blue box may be used to control asynchronous events.

BOA Spot Scripting Guide 14 Version 1.5; 2019-9-18

Function Listing
Note: Please consult the On-Line Help for the most up-to-date listing.
String and Character Functions
• Find(substring, inString) - finds the first occurrence of substring in the input inString,
and returns the zero-based index location of the first matching character. Returns -1 if
no match was found. Spaces are counted.
Example: idx = find("00", "SM WRA 0057 4321") returns 7, or sets idx = 7.
• Substring(string, startIndex, length) - forms a sub-string from the input string,
beginning at startIndex (zero-based) of length characters. If length = 0 all characters to
the end of the string are included in the sub-string.
Example: s2 = substring("SM WRA 0057 4321" , 9, 0) returns string "57 4321" in s2.
• StrLen(string) - returns the number of characters in a string.
• GetChar(string, index) - returns the character located at index (zero-based) in the
string.
• SetChar(string, index, char) - sets the character in string, located at index (zero-based),
to char.
• int(string) - converts the input string (of numbers) to an integer value.
Example: x = int("33") sets x = 33
• float(string) - converts the input string (of numbers) to a floating point value.
Example: x = float("57.499") sets x = 57.499
• char(int) - converts the input integer int to a character.
• string(int) - converts an integer or floating point number to a string.
• FormatString(stringForm) - returns a string in the format defined in stringForm.
Tool Statistics and Attributes Functions
• SetToolText(toolName, toolText) – sets or changes the text toolText shown in the
Graphics Tool toolName (Express only).
• SetToolPenColor(toolName, red, green, blue) – set or change the outline of the
Graphics Tool toolName to the value of red, green, blue. Express only.
• SetToolFill(toolName, red, green, blue) – set or change the fill color in the Graphics
Tool toolName to the value of red, green, blue. Express only.
Digital IO / Acquisition Control Functions
• pulse(activeVal, offsetMillisec, durationMillisec) - generates a pulse output.
activeVal – 1=active-high pulse, 0=active low-pulse.
offsetMillisec –delay from the moment this statement executes, in milliseconds.
durationMillisec – duration of the pulse, in milliseconds.
Example: Global.GPO[1] = pulse(1,5,10)
Outputs active-high pulse 10 ms duration and offset 5 ms after statement executes.

BOA Spot Scripting Guide 15 Version 1.5; 2019-9-18

• trigger( ) - generate an image trigger signal. The Sensor Trigger must be set to
“Software Trigger" when using this function.
• TriggerSource(source) - set the trigger source or trigger mode. Do not use in the
Solution Initialize function. It will get over-written by the Solution file settings.
source –1=internal timer, 2=external trigger, 3=software
Logging Functions
• GetFtpFileStatus() - returns the status of a file on the FTP device:
0 = idle.
1 = busy transferring file.
2 = error in ftp connection.
NOTE: The BOA Spot supports ftp file logging, where BOA Spot is the ftp Client logging
to an ftp Server. The ftp File Name syntax is:
ftp://userName:password@host/path
The userName and password are optional in BOA Spot. May be required by server.
• WriteImageFile(fileName, camID) - To be called only from the "Post Image Process"
function, will write the current image from the camera specified by camID to the
fileName specified (0 for BOA Spot)
fileName – full path of file to save. camID – always 0 for the BOA Spot.
• WriteImageTools(fileName, camID) - writes an image file including the tool graphics.
fileName – full path of file to save. camID – always 0 for the BOA Spot.
Serial IO Functions
• GetPortChar( ) - returns a new character input from the serial COM port if available,
otherwise immediately returns zero.
• GetPortString(endingChar) - returns a new string input from the serial COM port if
available, otherwise immediately returns an empty string.
endingChar: – specifies the received character that should indicate the end of a received
string. This character is not included in the returned string.
• PutPortString(string) - sends a string to the serial COM port. Does not perform
embedded variable evaluations. See string formatting reference for special characters.
Comm / TCP IO Functions
• Disconnect(comVar) – force a disconnect on the connection specified by comVar.
• IsConnected(comVar) - Determines the connection state of the TCP/IP connection
specified by comvar. Returns 1 if connected. Returns 0 if disconnected.
• ReadByte(comVar) - Reads the next byte from the TCP/IP connection specified by
comVar if one is available, otherwise returns 0 immediately.

BOA Spot Scripting Guide 16 Version 1.5; 2019-9-18

• ReadString(comVar, endingChar) - Reads a string from the TCP/IP connection
specified by comVar if one is available, otherwise returns an empty string immediately.
endingChar – Specifies the char which must have been received to signal the end of a
received string.
• WriteBytes(comVar, byteArray, numBytes) - Writes a byte array to the TCP/IP
connection specified by comVar.
• WriteFormatString(commVar, formatString) - Writes a formatted string to the TCP/IO
connection specified by comVar. See also string formatting reference.
Example: WriteFormatString( TcpP5025 ,"\n\rLC1 = [LC1]")
Example: WriteFormatString( TcpP5025 , "\n\rLC1 = [LC1%0.3f], L1 = [L1%d]" )
• WriteString(comVar, String) - Writes a string to the TCP/IO connection specified by
comVar. Unlike WriteFormatString, WriteString does not perform embedded variable
evaluations. See string formatting reference for special characters supported.
Example: WriteString( TcpP5025 ,"\n\rThe measurement is correct")
System / Misc. Functions
• ChangeSolution(requestedSolutionID) – Load a Solution file. If the
requestedSolutionID does not exist, the current solution continues running without
flagging an error.
• Copy(source, dest, numElements) - Copy numElements from source (an array of
elements) to dest (an array of elements. The copy function can be used to cause
multiple PLC registers to be updated in a single transaction.
• Delay(milliseconds) – add a delay. This is more efficient than looping on a timestamp.
This function must only be used in the “Periodic 200 ms” function.
• GetSolutionID() – returns the current Solution ID number.
• GetTime( ) - returns a value representing the current date and time. The value returned
equals the number of milliseconds since January 1, 1601 (in the local time zone). See
function FormatTime().
• GetTimeString( ) - returns a string value representing the current date and time (local
time zone).
Example: now = GetTimeString() sets "now" to a string value “12/28/2016
12:25:28:429"
• SetDisplayStatus(statusMsg, color) – Set the message to be displayed in the Run
panel or Monitor.
statusMsg – a string that will be displayed. Text is automatically sized to the largest
that will fix in the Status box.
color – the String name of the text color to be used.
• SwitchingIsEnabled() – returns 1 if Solution switching is enabled; returns 0 if disabled.
• TimeMillisec( ) - returns the current time in milliseconds.

BOA Spot Scripting Guide 17 Version 1.5; 2019-9-18

Scripting Examples
The String Editor

The string editor simplifies construction of output strings. The GUI is accessed through
the “Edit” script tool and allows users to define strings without writing code. Each string
is composed of user text, formatted program variables and delimiting characters.
Strings can be written to the function being edited and attached directly to a predefined
communication port:

Strings are constructed by entering text or dragging variables into the string command
line. The above example generates the following 2 lines of code in the function being
edited (typically the Post Image Process function):
str1 = “Intensity = [IntenAvg%.6f] Pass Count = [Global.PassCount%d]”
WriteFormatString(TcpP5024, str1)

BOA Spot Scripting Guide 18 Version 1.5; 2019-9-18

String Formatting Reference
• Special Characters used in strings
\n - Line feed
\r - Carriage return
\t - Horizontal tab
\f - Form feed
\v - Vertical tab
\xhh - specify a hex byte, for example \xa6 Use the byte value a6.
Other control or non-printing characters can be formed using the \x with the hex value
for the ascii character. For example \x04 for EOT, \x07 for Bell, \x00 for Null.

• Formatting Variables used in the WriteFormatString function

The general form follows this pattern. Please note items inside braces { } are optional.
[VariableName %{width} {.precision} type ] Example: [LC1 %4.3f]
The optional fields, which appear before the type character, control other aspects of
the formatting, as described below.

• Type
A required character that determines whether the associated argument is interpreted
as a character, a string, or a number. Supported character types:
c specifies a single-byte character.
d Signed decimal integer.
i Signed decimal integer
u Unsigned decimal integer.
x Unsigned hexadecimal integer, using "abcdef".
X unsigned hexadecimal integer, using "ABCDEF".
e Signed value having the form [–]d.dddd e [sign]dd[d[ where d is a single decimal
digit, dddd is one or more decimal digits, dd[d] is two or three decimal digits
depending on the output format and size of the exponent, and sign is + or -.
f Signed value having the form [–]dddd.dddd, where dddd is one or more decimal
digits. The number of digits before the decimal point depends on the magnitude of the
number, and the number of digits after the decimal point depends on the precision.

BOA Spot Scripting Guide 19 Version 1.5; 2019-9-18

 g Signed value printed in f or e format, whichever is more compact for the given value
and precision. The e format is used only when the exponent of the value is less than -
4 or greater than or equal to the precision argument. Trailing zeros are truncated, and
the decimal point appears only if one or more digits follow it.
G Identical to the g format, except that E, rather than e introduces the exponent
(where appropriate).
s specifies a single-byte character string. Characters are printed up to the first null
character or until the precision value is reached.

• width
Optional number that specifies the minimum number of characters output.
The width argument is a nonnegative decimal integer controlling the minimum number
of characters printed. If the number of characters in the output value is less than the
specified width, blanks are added to the left until the minimum width is reached. If
width is prefixed with 0, zeros are added until the minimum width is reached.

• precision
Optional number that specifies the maximum number of characters printed for all or
part of the output field, or the minimum number of digits printed for integer values.
For types: d, i, u, o, x, X
The precision specifies the minimum number of digits to be printed. If the number of
digits in the argument is less than precision, the output value is padded on the left
with zeros. The value is not truncated when the number of digits exceeds precision.
The default precision is 1.
For types: e, E
The precision specifies the number of digits to be printed after the decimal point. The
last printed digit is rounded.
The default precision is 6. If precision is 0 or the period (.) appears without a number
following it, no decimal point is printed.
For types: f
The precision value specifies the number of digits after the decimal point. If a decimal
point appears, at least one digit appears before it. The value is rounded to the
appropriate number of digits.

BOA Spot Scripting Guide 20 Version 1.5; 2019-9-18

Scripting Examples

The following examples demonstrate usages of the script tool. Each example has a
brief description of the application and associated code snippets from the relevant
functions. These examples cover basic scripting concepts only that apply to typical
applications.
Note: This manual was written for all models of the BOA Spot: SL, EL, IDS, IDE. The
examples may use tools that are not available on all models.

Manipulating Outputs
Many applications require some sort of output manipulation. By default BOA Spot
outputs are set to the “soft pulse” setting which automatically generates output pulses
on GPO[0] and GPO[1] for pass and fail results. Below we’ll show at how to generate
pulses or levels using the script tool.

Predefined Function used:

• pulse(activeVal, offsetMillisec, durationMillisec) - generates a pulse output.
activeVal – 1=active-high pulse, 0=active low-pulse.
offsetMillisec – offset or delay from the moment this statement executes, in
milliseconds.
durationMillisec – duration of the pulse, in milliseconds.

In the Post Image Processing function:

// Set the pass/fail condition

if (Result=1) // If composite Pass condition

Global.GPO[0] = pulse(1,0,20) // generate a 20 ms pulse on output 0
else // Else fail
Global.GPO[1] = pulse(1,0,20) // generate a 20 ms pulse on output 1
endif() // Close condition statement

BOA Spot Scripting Guide 21 Version 1.5; 2019-9-18

Similar equation statements can be used to indicate that a specific measurement
caused a failure. There are many different ways to formulate a statement.

if (MS1.Result = 3) Global.GPO[1] = pulse(1,0,400)

The above equation outputs a 400 ms active high pulse on GPO[1] (no delay) if the
MS1 match tool fails (Result=3). The equation below generates the same pulse if the
MS1 match tool is not a pass (Result = 2 or 3)

if (MS1.Result != 1) Global.GPO[1] = (pulse(1,0,400)

MS1 is the measured value of the match. You can use the measured value in
statements, in place of the result of a measurement as shown below. Output a 50 ms
active high pulse on GPO[1] (5 ms delay) if the MS1 match score is less than 90

if (MS1 < 90) Global.GPO[1] = pulse(1,5,50)

Similarly, if the Distance measurement L1 is less than 400, output a 50 ms active high
pulse on GPO[1] (5 ms delay).

if (L1 < 400) Global.GPO [1] = pulse(1,5,50)

The “if” is not always required.

Set the GPO(1) to logic 1 if MS1 match tool does not pass; set GPO[1] to logic 0 if MS1
match tool passes.

Global.GPO [1] = (MS1.Result != 1)

Note: If you set an output to a level, it will stay that way until you change it. For example
you could set an output to “1” as above and then reset it to “0” before processing the
next image using the “Image Pre Process Function”.

BOA Spot Scripting Guide 22 Version 1.5; 2019-9-18

Hide and Show Variables
Any variables you define in a script will appear in the Monitor panel, iwhich could be
quite confusing when you have many variables. You can hide variables that are not
critical to the operator using scripts. We recommend using the Solution Initialize
function because it is evaluated only once, when the solution gets loaded.

Use the variable’s name, with the “Disable” switch. Disable=1 will hide the variable.
Disable=0 will show the variable. For example, you have a variable named “MyVar1”.

In the Solution Initialize function:

MyVar1.Disable=1 //hides the variable

Disable and Enable Tools

You can disable a Tool in the Tools Setup panel (in the Tool Table). The Tool is hidden in
the image, and the results are disabled. All results are shown =0. The Tool Table
disables the tool for all inspections.

But you can also disable a tool in scripts. That means you could enable or disable a tool
based on a variable or on an input.

Use the tool name, with the “Disable” switch. Disable=1 will hide the tool and disable its
results. Disable=0 will show the tool and enable its results once again. The Tool remains
disabled if you do not re-enable it.

If you wish to disable a tool based on a variable, we recommend the Pre-Image

Processing function. If you wish to disable a tool based on an input, you may use the
Periodic function which you use to monitor the input.

if(GPI[3]=1)
MS1.Disable=1 // disable & hide Match tool if the input is 1
else
MS1.Disable=0 // enable & show Match tool if the input is 0
endif

BOA Spot Scripting Guide 23 Version 1.5; 2019-9-18

Solution Switching
There are different scripting methods available for solution switching. We’ll describe two
popular scenarios that use external inputs and Variables. In the case of inputs the
scripts can be expanded with the number of inputs. Using the PL-101 will give you 3
inputs to support up to 8 solutions (unless one is used for a trigger input). Both cases
use a Periodic function:

Function used:
• ChangeSolution(requestedSolutionID) - loads a new solution number

In Solution 1, in the Periodic 200 ms function:

// GPI[1] - defines solution 0 (LOW) or solution 1 (HIGH)

if (GPI[1]=0) // Check for solution #

ChangeSolution(0) // switch to solution 0
endif // Close condition statement

In Solution 0, in the Periodic 200 ms function:

// GPI[1] - defines solution 0 (LOW) or solution 1 (HIGH)

if (GPI[1]=1) // Check for solution #

ChangeSolution(1) // switch to solution 1
endif // Close condition statement

BOA Spot Scripting Guide 24 Version 1.5; 2019-9-18

If you use a variable to define the solution # instead of an input, then the script must be
modified to reflect the variable value. BOA Spot supports variable access through
integrated network commands (inside a 3rd party program) or through PLC control. In
the latter case a PLC connection has to be established and a register or tag is assigned
as the solution ID variable.
As an example, let’s assume BOA Spot is connected to a Rockwell ControLogix PLC
with a user defined tag called “BOA _Spot_Solution”. We need to setup a Periodic script
to monitor the tag for a solution change.
Note: Since this is a variable, it is always recommended to initialize it at solution load
time. This will prevent immediately switching to an unexpected solution upon entry if the
variable is in an unknown state.

Function used:
• ChangeSolution(requestedSolutionID) - loads a new solution number
• GetSolutionID() – returns the current Solution number

Initialize variable in the Solution Initialize function:

CIx10.BOA_Spot_Solution = GetSolutionID() // Add for each solution

In the Periodic: 200 ms function :

// Monitor the tag
ChangeSolution(CIx10.BOA_Spot_Solution) // switch solution if ID is different
// does nothing if the ID is the same

BOA Spot Scripting Guide 25 Version 1.5; 2019-9-18

Trigger Control
BOA Spot supports 3 modes of triggering: internal timer, external input and software
controlled. Most applications use external input or software controlled. Internal or
external triggering selected using the BOA Spot GUI in the sensor setup panel.
Software trigger is controlled via scripting or via network commands.

This simple example shows how to software trigger inspections using scripting.

Predefined functions:
• trigger( ) - generate an image trigger signal. The Sensor Trigger must be set to
“SoftwareTrigger" when using this function.
• TriggerSource(source) - set the trigger source or trigger mode. Do not use in
Solution Initialize function. It gets over-written by the Solution settings.
source –1=internal timer, 2=external trigger, 3=software

In the Solution Initialize function:

Trigger_Enable = 1 // Trigger qualifier for handshake (arm initially)

In the Periodic: 200 ms function:

Trigger_Start = MBSlaveHrs16[2] // Read Modbus defined trigger register
if(Trigger_Start=1 AND Trigger_Enable = 1) // Check trigger condition
Trigger() // Software trigger
Trigger_Enable = 0 // Turn off Trigger gate
endif
if(Trigger_Start=0) // Wait until PLC changes Trigger state
Trigger_Enable = 1 // Re-arm trigger
endif

Note: In general, software triggers are held off during an active acquisition cycle.

BOA Spot Scripting Guide 26 Version 1.5; 2019-9-18

Image Logging
There are different ways to write images. This example shows how to log images to a
FTP Server.
BOA Spot supports ftp file logging where BOA Spot is the ftp Client logging to an ftp
Server. The user Name and password are optional in BOA Spot. They may be required
by your ftp server.
Example 1 WriteImageFile
Predefined function:
• WriteImageFile(fileName, camID) - To be called only from the "Post Image Process"
function, will write the current image from the camera specified by camID to the
fileName specified (0 for BOA Spot).
fileName – full path of file to save.
In this example, no user name or password needed. The image file name becomes
“img#.bmp”.
In the Post Image Process function:
x=x+1
fn = “ftp://ftp.acme.com/images/img” + x + “.bmp”
WriteImageFile(fn, 0)

Example 2 WriteImageTools
Predefined function:
• WriteImageTools(fileName, camID) - writes an image file including the tool graphics.
fileName – full path of file to save.
User name “Joe”, password “bananas”. The image file name becomes “tool#.bmp”.
In the “Post Image Process” function:
x=x+1
fn = “ftp://[email protected]/images/tool” + x + “.bmp”
WriteImageTools(fn, 0)

BOA Spot Scripting Guide 27 Version 1.5; 2019-9-18

Adding a Wait
Sometimes it is necessary to add a small wait to a script. This example adds a 50
millisecond wait.
Predefined function used:
• Delay(milliseconds) – adds a delay, in milliseconds.
This function is more efficient than looping on a timestamp. Adding delay blocks other
scripts from executing, and increases the execution time. Do not use a delay larger
than your average acquisition time or the time between triggers. Only use Delay() in the
“Periodic 200 ms” function, it is ignored in all other function groups.
In the Periodic 200 ms function:

Delay(50) // 50 milliseconds

Communication Using Strings

This script demonstrates how to read a string from an attached Ethernet port. In this
case, the string contains command characters for solution control and triggering. The
script parses the string to extract the control characters for action. We’ll define the string
to be 10 characters (+ delimiter character) as follows:
Char 0 = command character – “T” = Trigger
Char 1 = Solution # - 0 through 9
Char 2-9 = Job code
This script should be added to the periodic function for the following reasons:
1.Communication is asynchronous to processing
2.The Periodic function continues to run when the system is in a “stopped” state,
enabling the user to issue a “restart” command.
Predefined functions used in this example:
• ReadString(comVar, endingChar) - Reads a string from the TCP/IP connection
specified by comVar if one is available, otherwise returns an empty string immediately.
• Substring(string, startIndex, length) - forms a sub-string from the input string,
beginning at startIndex (zero-based) of length characters. If length = 0 all characters
to the end of the string are included in the sub-string.
• trigger( ) - generate an image software trigger signal. The Sensor Trigger must be set
to “Software Trigger" when using this function.

BOA Spot Scripting Guide 28 Version 1.5; 2019-9-18

In the Periodic 200 ms function:
ReadBuffer = ReadString( TcpP6001 , 13) // load string until “CR” line delimiter detected
if(ReadBuffer != "") // if buffer is not empty
CommandString = ReadBuffer // store string in string variable
CommandCharacter = Substring(CommandString, 0, 1) //extract command character
SolutionNumber = Substring(CommandString, 1, 1) // extract solution number
JobCode = Substring(CommandString, 2, 9) // extract job code
if(INT(SolutionNumber) >0 AND INT(SolutionNumber)<9) // validate solution #
SolutionNumber = INT(SolutionNumber) // convert from string to INT
ChangeSolution(SolutionNumber) // change to specified solution
endif

//Note: if SolutionNumber is different than current solution running, change will start
//immediately and the following code will be ignored. If they are the same, the following code
//will be executed
if(CommandCharacter = "T") // look for trigger command
trigger( ) // call trigger function
endif
endif // close main IF statement

Note: This example uses ReadString() for TCP/IP communication. Use GetPortString()
for Serial Port communication.

BOA Spot Scripting Guide 29 Version 1.5; 2019-9-18

Customizing Text in the Monitor Panel
iNspect offers little in the way of runtime customization, but through scripting it is
possible to display results or messages in the “Display Status” window on the Monitor
panel.
Predefined functions:
• SetDisplayStatus(statusMsg, color) - Sets the message to be displayed in the
Inspection Status box (in the Configuration and Status panel associated with the
Monitor panel). This overrides the display of "Pass" or "Fail".
NOTE: To reset the display back to the default, use SetDisplayStatus("","") or
SetDisplayStatus(0,0) in the Solution Initialize function.
statusMsg – the string that will be displayed. For multiple lines, add the character \n
to indicate a new line. Message text is automatically sized to be the largest possible
that can be contained in the Inspection Status box. String formatting information for
variables of the form [Var%FormatData] is also supported:
msg1="[L1%0.2f]" means display the value of L1 with 2 digits to the right of the
decimal point.
color – The string name of the color the message text is to appear in. Possible
values are: "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
"darkred", "darkgreen", "darkyellow", "darkblue", "darkmagenta", "darkcyan",
"lightgray1", "moneygreen", "skyblue", "cream", "lightgray2", "mediumgray".

The font size in the text window is not user selectable, but rather scales according to
how much text is being displayed. The font type is also not selectable.

The following script commands will display the messages ‘2D Code read” for pass
inspections and “Failed to Read” for fail inspections (BOA Spot-ID 2D Code tool):

if(Result=1)
SetDisplayStatus(“2D Code Read”, “green”) // post pass message
else
SetDisplayStatus(“Failed to Read”, ”red”) // post fail message
endif

BOA Spot Scripting Guide 30 Version 1.5; 2019-9-18

If you wish to display multiple lines of text, you need to construct strings accordingly
inside a single function call. If you define multiple SetDisplayStatus() functions in your
script, only the text from the last function will be displayed i.e. each will overwrite the
previous.

An example of how to define multiple lines of text in the “Post Image Process” function
is as follows:

Str1 = “Count Result = “ // define count string

Str2 = “\n Inspection Passed” // define pass message
Str3 = “\n Pass Count =“ // define pass count string
Str4 = “\n Inspection Failed” // define fail message
Str5 = “\n Fail Count =“ // define fail count string

if(Result=1)
SetDisplayStatus(Str1+N.Result+Str2+Str3+Global.PassCount, "darkgreen")
else
SetDisplayStatus(Str1+N.Result+Str4+Str5+Global.FailCount, "darkred")
endif

A pass result would produce the following text on the monitor screen:

BOA Spot Scripting Guide 31 Version 1.5; 2019-9-18

Manipulating Text in the Graphics Tool
The Graphics tool is an “Extended Level” tool, available on the IDE, CE and EL models.
The Graphics tool can be used to highlight items, or post messages in the image area.
The Graphic tool can optionally be displayed by the success or failure status of a
another tool. This can be useful for circling or pointing out a defect, to the operator or
for image logging.
Another popular use is communicating messages or instructions to the operator. The
Graphics tool message can appear on the success or failure of another tool. But
creating multiple Graphics tools for the Pass and Fail conditions can lead to a very
cluttered Setup Tool panel. To avoid this, you can create one Graphics tool and change
the displayed message using Scripts.
Predefined functions used:
• SetToolText(toolName, toolText) – changes the text shown in the Graphics tool.
Note: The font style, size and color are defined in the Graphics Tool Properties, and
cannot be changed by a Script.
In this example, we have two tools that check for the presence of two parts on an
assembly. A Graphics tool was created and the name changed to “Instr” in the Graphics
Tool Properties menu. The message in the Graphics tool is changed in this script based
on the success or failure of both tools.
In the Post Image Processing function:
part_a = (tool1.Result=1) // True if tool1 passes – Part A correct
part_b = (tool1.Result=1) // True if tool2 passes – Part B correct
if((part_a) AND (part_b))
SetToolText(Instr, “Both parts present and correct”)
else
if((part_a=1) AND (part_b=0))
SetToolText(Instr, “Fit part B”)
endif
if((part_a=0) AND (part_b=1))
SetToolText(Instr, “Fit part A”)
endif
if((part_a=0) AND (part_b=0))
SetToolText(Instr, “Fit parts A and B”)
endif
endif

BOA Spot Scripting Guide 32 Version 1.5; 2019-9-18

Using Arrays
The script tool supports the use of arrays (consecutive data registers). Arrays can be
used to segment or organize data into a user defined structure. Some complex tools
output results into arrays for script manipulation, but most users define arrays for more
efficient communication.

Array Example 1:
This simple example shows how to parse an array of blob areas (Area.[x]) from the
count tool to find the biggest blob (Note: in practice this can easily be done using the
“max” feature of the count tool without writing any script):

In Post Image Process Function:

array_count=0 // reset array_count variable

max_value=0 // reset max_value variable
while(array_count<20) // Do while array_count <20
array_value = Area.[array_count] // Read entry in array
if(array_value>max_value) // Check for high value
max_value = array_value // Make new highest value
endif
array_count=array_count+1 // Increment counter
endwhile

BOA Spot Scripting Guide 33 Version 1.5; 2019-9-18

Array Example 2:
This similar example shows how to parse an array of numbers to find two consecutive
entries that differ by more than 20%:

Input Array (entries 3 and 4 differ by 25%): ds[0:5]=90, 90, 90, 100, 80, 90

In the Post Image Process function:

//
numHi = 0
i=0
while( i < 6 )
z = i+1
while( z < 6 )
if( ds[i] < ds[z] )
ratio = ds[z] / ds[i]
else
ratio = ds[i] / ds[z]
endif
if(ratio > 1.20)
highRatio[numHi] = ratio // store high ratio
highRatio[numHi][0] = I // store first number
highRatio[numHi][1] = z // store second number
numHi = numHi+1
endif
z = z+1
endwhile
i = i+1
endwhile

BOA Spot Scripting Guide 34 Version 1.5; 2019-9-18

Array Example 3:
This example shows how to match a string to a predefined string stored in an array. The
8 string array is indexed based on a user code supplied through the Global Inputs i.e. if
input = 0x4, compare the value with string #4.

Place the 32 strings in array called “CodeList”

CodeList[0] = "M54321“
CodeList[1] = "JJ H4321"
…
CodeList[7] = "KLM6721“

In the Post Image Process function:

idx = 0
i=0
while( i < 4 ) // Find array entry to compare
idx = idx | (Global.GPI[i] << i) // Based on 3 GP inputs
i = i+1
endwhile
CodeMatch = CodeList[idx] // Compare string

BOA Spot Scripting Guide 35 Version 1.5; 2019-9-18

Using Arrays for Communication:
Arrays offer convenience and efficiency when communicating between BOA Spot and
3rd party equipment. You can define a common data structure that can be moved
quickly between devices using a single command.

• WriteBytes(comVar, byteArray, numBytes) - Writes a byte array to the TCP/IP

connection specified by comVar

• copy(source, dest, numElements) - Copy numElements from source (an array of

elements) to dest (an array of elements). The copy function can be used to cause
multiple PLC registers to be updated in a single transaction

Example:
This example shows how to send the X, Y and Z coordinates to a robot in one Modbus
multiple register transaction. With variable MB92HRs16 attached to a Modbus holding
register, the following will update the Modbus device coordinates in a single transaction.

cmd[0] = x // X coordinate
cmd[1] = y // Y coordinate
cmd[2] = z // Z coordinate
copy (cmd, MB92HRs16, 3) // Send coordinates

Similarly, you can store results from multiple tools in a single array and transfer them
efficiently using the WriteBytes function:

meas[0]= L1 // Array element 0

meas[1]= L2 // Array element 1
Meas[2]= N1 // Array element 2
…
Meas[9]= IntAverag1 // Array element 9
WriteBytes( TcpP5025 , meas, 10) // Send 10 elements

BOA Spot Scripting Guide 36 Version 1.5; 2019-9-18