EAN-Script Development
Sales: sales@sightlineapplications.com

2024-04-16

Support: support@sightlineapplications.com

Exports: Export Summary Sheet

Phone: +1 (541) 716-5137

EULA: End User License Agreement
Web: sightlineapplications.com

1

Overview ................................................................ 1

8.4

SLNewCmdCallback (New in 2.24.xx) ................... 11

1.1

Developing On-Board Applications ........................ 1

9Using Lua to Initialize Hardware .......................... 11

1.1.1 Lua .......................................................................... 1

9.1

Create Lua Script .................................................. 12

1.1.2 C/C++ ...................................................................... 1

9.2

Load Script to Target Hardware ........................... 13

1.2

Additional Support Documentation ....................... 1

9.3

Configure Acquisition Parameters ....................... 13

1.3

SightLine Software Requirements .......................... 2

9.4

Enable Lua Script .................................................. 13

2

Example Scripts ...................................................... 2

10

Troubleshooting ................................................... 14

2.1

Install Directory ...................................................... 2

10.1 Additional Script Debugging ................................ 14

2.2

Script Summary ...................................................... 2

10.2 Questions and Additional Support ....................... 14

3

Basic Setup ............................................................. 4

Appendix A - Lens Control Scripts ................................... 15

4

Development Environment .................................... 5

A1

Overview .............................................................. 15

5

Uploading Scripts ................................................... 6

A2

Testing on SightLine Hardware ............................ 15

6

Enabling / Disabling Scripts .................................... 7

A3

Basic Troubleshooting .......................................... 17

6.1

Running Scripts at Startup ..................................... 7

A4

Serial Ports ........................................................... 18

7

Script Interface ....................................................... 8

A5

Camera Index ....................................................... 18

7.1

LUA Script and VideoTrack ..................................... 8

Appendix B - Reticle Selection Script .............................. 18

7.2

Create Script Function ............................................ 8

B1

Overview .............................................................. 18

8

Key Script Interfaces .............................................. 9

B2

Configuring Reticle Scripts ................................... 18

8.1

SLPostAnalyze ........................................................ 9

B3

Reticle Color Mapping .......................................... 19

8.2

SLUnLoad (New in 2.24.xx)................................... 10

B4

Reticle Index......................................................... 20

8.3

SLLoad (New in 2.24.xx), ...................................... 11 CAUTION: Alerts to a potential hazard that may result in personal injury, or an unsafe practice that causes damage to the equipment
if not avoided.

 IMPORTANT: Identifies crucial information that is important to setup and configuration procedures.

 Used to emphasize points or remind the user of something. Supplementary information aids in the use or understanding of theequipment or subject, which is not critical to system use.

© SightLine Applications, LLC

EAN-Script-Development

1

Overview

This document provides information and steps for developing and running custom scripts in Lua on theSightLine OEM video processing boards.
1.1 Developing On-Board Applications
SightLine provides two primary ways for customers to develop their own on-board applications: C/C++
and Lua. Each technology has benefits and costs for solving a problem. It is impossible to prescribe theright technology for every scenario. This section helps provide general guidelines to assist inunderstanding the tradeoffs.
1.1.1 Lua
Lua is recommended for light-weight applications that need to perform simple data processing andinteraction with the onboard video processing application, VideoTrack. Applications such as dynamic
on-screen displays based on telemetry data, or simple command and control from serial ports are
effective uses for Lua. Lua scripts are executed in-line with our video processing and cannot be
synchronized with the processing of video frames. Issues such as increased latency and otherperformance impacts can arise from Lua scripts that can be complex.
1.1.2 C/C++
If an application requires complex data handling, frequent real-time access to IO, or should be run inparallel with VideoTrack, SightLine recommends creating C/C++ applications that can be run on the
ARM processor. Information on creating embedded C/C++ applications can be found in EAN-ARMDevelopment-1500-3000-OEM or EAN-ARM-Development. When reviewing options, contact Support
to discuss your application.
Table 1: Lua and C/C++ Comparison Table
Benefits
Lua•
Simple to deploy.
•
Frame synchronized execution.
•
Can leverage numerous examples from SightLine or the internet.
C/C++•
Wide acceptance within the embedded programming industry.
•
Can be easy to test on a PC before deploying on target hardware.
•
Real-time debugging.
•Complete access to IO, file system, etc.
•
Can leverage numerous examples from SightLine or the internet.
•
Can run in parallel to existing applications.
•Portable to numerous platforms.

1.2

Drawbacks
Lua•
Not as widely used as C/C++.
•
Access to IO is complex and difficult.
•Real-time debugging is not available.
•
Networking is not yet supported.
C/C++•
Deploying application to launch at run time can beerror prone, e.g., file location, system permission, etc.
•
Existing setup procedure is complex (VMWare,
CCStudio, mapped drives, NFS booting).

 These tools and procedures are complex but used industry widewith TI embedded systems.

Additional Support Documentation

The Panel Plus User Guide provides a complete overview of settings and dialog windows. Accessedfrom the Help menu of the Panel Plus application.
The Interface Command and Control (IDD) describes the native communications protocol used by theSightLine Applications product line. Also available as a PDF from the Software Downloads page.
Additional Engineering Application Notes (EANs) and ICDs are available on the Documentation page.
© SightLine Applications, LLC

1

EAN-Script-Development

1.3

SightLine Software Requirements IMPORTANT: The Panel Plus software version should match the firmware version running on theboard. Firmware and Panel Plus software versions are available on the Software Download page.
Table 2: SightLine OEM Software Requirements
OEM
Initial Software Release4100-OEM
3.7.x
1750-OEM
3.6.x
4000-OEM
3.00.xx
Legacy OEMs
1500-OEM
2.20.xx
3000-OEM
2.22.xx

2

Provisions
Dual channel processing is available in 3.7.x and above.

Legacy OEMs are supported up to 3.5.x. Some features in 3.6.x andabove may not be available on these platforms.

Example Scripts

The sample applications/scripts installer (SLA ARM Examples) can be downloaded from the SightLine
Applications website. Run the installer before setting up the development environment.

 LUA 5.1 is currently supported.
2.1

Install Directory

The example scripts are intended to serve as a starting point for any script development. A summary ofeach example script is shown below. The example scripts are in C:\SightLine Applications\SLAExamples-ARM<<version number>>\SLAScripts\Scripts.
2.2

Script Summary

 Example scripts in the install directory that are used internally are not shown in this list.
Table 3: Script Summary
Available Scripts
Camera Control

Description

cameraControl_Atom1024.lua

Opens a serial port and sends commands to configure the camera for 8-bit or 14-bit mode.
Enables a GPIO to pull camera out of reset then opens a serial port and sends commands to configure
the camera for 8-bit or 16-bit mode.
Enables a GPIO to pull camera out of reset.
Enables serial communications to the camera through the FPC board, which is normally done in thecamera init code.
Generic example that enables GPIO for output then toggles the line low.

cameraControl_Boson.lua
cameraControl_CC3Rst.lua
cameraControl_FPC.lua
cameraControl_GP1Low.lua

Common functionality for use by other scripts, such as querying acquisition parameters, working withGPIO and serial ports.
Configures serial port parameters such as baud rate, then sends configuration commands to thecameraControl_JAI.lua
camera.
A template that includes methods on how to use CameraControlProperties data structure and serial
cameraControl_Sample.lua
port communication.
Configures serial port parameters such as baud rate, then sends commands to the camera to set it intocameraControl_Sony720P60.lua
720P mode, power the camera off, then on again. This script supported on 3000-OEM only.
cameraControl_Analog.lua
A generic script for customizing analog camera capture parameters.
cameraControl_internal.lua© SightLine Applications, LLC

2

EAN-Script-Development(Script Summary table continued)
Lens Control.

 If using software 3.5.x and above use the Lens DLL interface described in EAN-Lens-Focus-Control.
lensctrl.lua
ophirctrl_internal.lua

hitachictrl_internal.lua

sonyctrl_internal.lua

ophirlens_ctrl.lua
Serialslrs232_internal.lua
RecordingstartRecord.lua

snapFocus.lua

gpioSnapShot.lua

A complex script that provides example implementations of auto focus algorithms and other lenscontrol functions. More details can be found in the Appendix A.
Interface to the Ophir lens for auto focus. This does not to replace the built-in auto focus on the Ophir,but it provides an example of how to implement an auto focus algorithm.
Interface to the Hitachi camera for lens control and focus mechanism. Testing was done with the
Hitachi DI-SC123R camera. This does not replace the built-in auto focus on the Hitachi but provides anexample of how to implement an auto focus algorithm and sending Hitachi commands over serial tothe camera.
Interface to the Sony camera for lens control and focus mechanism. Testing was done with the SonyFCB-EH6300 camera. This does not to replace the built-in auto focus on the Sony, but it provides anexample of how to implement an auto focus algorithm and sending VISCA commands over serial tothe camera.
The Ophir lens example provides support for basic lens control functions like zoom and focus. Users
can choose between the example auto focus or native camera implementation. The example
implementation is for a one-push auto focus method. It will not continue to track focus through zoom
and scene changes.
Wrapper for SightLine Application Inc. serial port class.
Configures recording destination (uSD),and then starts recording video for Net0 on the 10th frame andends recording on the 1000th frame.
This script uses focus metric and takes a group of snapshots when the focus is greater than the focus
of a past window of frames. It also demonstrates how to kick off a script task using a SightLine
command. Focus metric telemetry must be enabled using CoordinateReportingMode (0x0B). Moreuser information is included in comments in the script.
Example program that takes snapshots on GPIO175 toggle to high then low. See EAN-GPIO-and-I2C for
more information on available GPIO on 1500-OEM and 3000-OEM hardware.

Overlay / Graphics
helloworld.lua
klvOverlay.lua
telemdata.lua

reticles.lua
reticlesConfig_internal.lua
windowPTZ.lua
TemperatureDetect_Basic.lua
frameCountOverlay.lua
Track / Detect
autoTrackScript.lua
snapshot.lua
tracksnap.lua
gpio.luaTemperatureDetect.lua© SightLine Applications, LLC

Sends a command to VideoTrack to draw a text overlay with the following text: Hello World. Removes
the overlay when the script is unloaded.
Draws KLV overlays on the screen.
Sends commands to VideoTrack to display the registration and stabilization telemetry data as onscreen overlays. It also displays the hex codes for any SightLine command messages received by thesystem. This diagnostic tool provides examples of message parsing.
Used to generate custom on screen display reticles. There are four distinct types of reticles to choose
for each camera. Configuration details for reticles script are loaded from a secondary file. See
Appendix B.
Support file for reticles.lua.
Example program that draws rectangles on the screen representing the capture and display areas.
Uses pixel statistics to detect ranges of temperature from a calibrated infrared camera. If the criteria
are met, it will draw green and red overlay boxes around targets and take a snapshot of the target.
Creates an overlay reporting the frame number. Updated once per frame after the script is loaded.
Example program that toggles GPIO on MTI detections and shows how detection can transition to
tracking automatically. See EAN-GPIO-and-I2C for more information on available GPIO. This example
uses 175, which is valid for the 1500-OEM.
Retrieves the current version of SightLine software, starts a track at coordinates (320,240), takes asnapshot, and then prints out tracking positions.
Example program that gets the version, starts a track, and takes a snapshot.
Toggles the GPIO based on MTI detections. See EAN-GPIO-and-I2C for more information on available
GPIO. The example highlights how to get telemetry from the SightLine software, and how to set GPIO
from a script.
Logs the telemetry data and messages to a file on the microSD card.

3

EAN-Script-Development(Script Summary table continued)
Misc
getParams.lua
setSystemValue.lua
error_internal.lua
errorExample.lua
filesystem_example.lua
klvstatic.lua
mtisnap.lua
sla_internal.lua
telemlogger.lua
template.lua
commandPassthrough.lua

3

Examples of how to query for data/state.
This script is an example of how to interpret SetSystemValue (0x92) commands whensystemValueType is set for CUSTOMER USE (18). Values 0 - 3 can be either left unused or can containdata that is interpreted by the script. This script can be used to write customer input to a file, change
network performance using traffic control (tc), and make the file system writeable (3000-OEM).
Provides utility for generating user warnings and errors to assist in debugging.
Provides examples for how to use lua script errors and warnings.
An example of how to interact with files (open, close, write, copy). Currently file details (name, anddirectory location) are set as globals. This code can easily be modified to have these as values that are
passed in.
This script pushes static metadata values to VideoTrack for KLV output with streaming video.
Injects MISB ST 0601 metadata values for Platform Designation (TAG 10), Image Source Sensor (TAG
11), and Platform Tail Number (TAG 4), which are then sent with the MPEG2-TS stream as KLV.
Used during development, this script defines the SightLine Command interfaces. Used as an API in
IDEs, it is not a script that runs on the target.
Similar to telemdata.lua. Instead of sending commands to draw the information on top of the video,
telemetry data and messages are logged to a file on the microSD card.
A minimal set of functions that allow it to be called from VideoTrack. Shows how to use error andwarning printing.
Demonstrates how to send a passthrough command through a serial port with a Lua script. Performs
a GetVersion request through command passthrough on the 10th frame.

Basic Setup

The following are the major components of the development and deployment of LUA scripts:•

Any development environment can be used to write scripts. This is usually some form of text editor
or more advance Interface Development Environment (IDE).

•

The SightLine Firmware upgrade utility is used to upload scripts from the PC to the target
hardware.

•SightLine Panel Plus is used to debug the script through error messages. Panel Plus may also be
used to see custom graphics or other functions that are being executed by the LUA script.

•

The Panel Plus External Programs dialog is used to load and unload scripts. Keeping this dialog open
during development allows the developer to easily iterate during script development or try new
scripts.
PC

Development
Environment

Panel Plus

FirmwareUpgrade Utility

External
Programs

Figure 1: Common Windows Layout During Script Development© SightLine Applications, LLC

4

EAN-Script-Development

4

Development Environment

Lua scripts can be developed with almost any IDE. However, to get syntax highlighting, static analysis,
and autocomplete capabilities, SightLine recommends using the ZeroBrane IDE from ZeroBrane Studio.

 If a script uses another script internally, include the keyword internal in the script file name so it will
not show up in the Panel Plus list of programs.
In this example, the application has been installed to C:\ZeroBraneStudio. The steps below reference
the install location as ZBS.
1. Download and install ZeroBrane IDE from ZeroBrane Studio.
2. Copy sla_internal.lua from the installed sample directory /SightLine Applications/SLA-ExamplesARM/SLAScripts to the ZBS\api\lua directory. This will define the API used by SightLine Command
and Control protocol.
3. Open ZeroBrane Studio and choose the menu option project directory: Project » Project Directory »Choose.
4. Select the directory with the example scripts. C:\SightLine Applications\SLA-Examples-ARM<<version number>>\SLAScripts\Scripts. (See Install Directory)
5. Choose the menu option Edit » Preferences » Settings:User. This opens a user settings file. Add thefollowing line to end of the file:
api = {'sla_internal'}

 For SightLine firmware version 2.23.xx add the following line to the end of the file: api = {'sla'}
instead.
6. Restart the ZeroBrane Studio application.
7. The helloworld.lua example can now be edited. To verify autocomplete is working, type ffi.n after
the definition of framecount. It should show new as an option.

 ZeroBrane Studio includes a static analyzer. To use this, go to the menu option Project » Analyze
after editing a file. This is strongly recommended before sending files to the SightLine hardware. If
using a different IDE that does not contain a static analyzer, there are other third-party tools
available on the web.

© SightLine Applications, LLC

5

EAN-Script-Development

5

Uploading Scripts

User developed scripts can be uploaded to the OEM hardware using the SightLine upgrade utility.
1. Click the Find IP Address to get a list of devices on the network.
2. Select the target hardware from the list of devices.
3. From the upgrade utility menu go to File » Program Files » Put Files (PC->SLA) …

4. Select the directory containing the developed Lua scripts or the Example scripts directory. This
uploads all the Lua files (*.lua) from that directory to the SightLine hardware.

 The upgrade utility can also be used to retrieve all the scripts from the hardware.
5. Confirm success by checking the Status window.

 Ignore the Restart board alert. Use the Clear button if the Status window is too full of message.
6. Once the scripts are uploaded, they must be enabled (see the next section).

© SightLine Applications, LLC

6

EAN-Script-Development

6

Enabling / Disabling Scripts

Scripts can only run if they are enabled. This can be done through the command and control protocol
using the ExternalProgram (0x8F) command. It can also be done from the External Programs dialog
window in Panel Plus, main menu » File » Programs.
To enable a script, select it in the drop-down menu and click Send. To disable a script, select None andclick Send.

helloworld.lua 3.76 KB
gpio.lua 6.41 KB

Figure 2: External Programs

 Sending the message again or clicking the Send button again will cause the scripts to be reloaded.
This is especially useful when debugging or incrementally adding functionality to the script.

 IMPORTANT: Problems with scripts show up as a user warning. When loading scripts, it isimportant to monitor the User Warning dialog window. From the Panel Plus main menu, go to View
» User Warning.

Figure 3: User Warning Dialog

6.1

Running Scripts at Startup

To run the script at startup, enable the script and then save the settings to the board, main menu »Parameters » Save to board.

© SightLine Applications, LLC

7

EAN-Script-Development

7

Script Interface

The script interface to VideoTrack is documented in the IDD. The IDD provides details on structures,functions, and other protocols available through the script interface.
7.1

LUA Script and VideoTrack

It is important that understand that the LUA script is running on the same ARM processor as theVideoTrack application. It runs in close coordination with the VideoTrack application.
All the major functions in the LUA script are performed in callback functions that are called byVideoTrack in response to events, for example:•
A new SLA command was received by VideoTrack from Panel Plus:
Forward a copy of this command to the LUA script so it can process the command.
•
A new frame of video was acquired/analyzed by VideoTrack:
Inform the LUA script so that it can do an operation, e.g., start recording based on the number offrames.
The LUA script can also generate SLA commands and send them to the VideoTrack application. For
example, in the autofocus example code the LUA script polls the VideoTrack application to receive thecurrent focus metric. It does this by calling GetParameters (0x28) with a FocusStats (0x55) ID, and thenwaits for a response from video track, which contains the focus metric.
It is important to understand that VideoTrack does not respond to some commands in certain cases,
e.g., if the LUA script is controlling a lens through a LUA serial port, then the VideoTrack application will
not respond to a CurrentLensStatus (0x6D) command (to get focus and zoom position). This is because
VideoTrack application is not currently controlling a lens and cannot respond to the command.
7.2

Create Script Function

The following example describes how to create a script function/definition from the IDD. Figure 4
shows how the DoSnapShot (0x60) command is defined in the IDD.

 This may change with software versions.

Figure 4: DoSnapShot (0x60) Command Example in IDD© SightLine Applications, LLC

8

EAN-Script-Development

All variable names and valid values are called out in the IDD. Variable names are case sensitive.
Optional values (varies) do not need to be defined.
Message ID 0x60
Byte Offset Name
4frameStep
5
6
7-…
variesvariesvariesvariesDescription
Frame Step - step between frames, e.g., 2 = every other.
Number of snapshots to take (1 to 254), 255 = continuous, 0 = Stop. Ignored if
numFrames
snapAllCameras is used.
Filename.len
String length
Filename.str
Base file name of saved files.
Mask of cameras to snap, e.g., use 0x5 to snap cameras 0 and 2. For multicamera, only
snapAllCameras
single snapshot is allowed.
When using file auto-numbering. Begin file numbering after highest-numbered existingshouldScan
filename.
autoFolder
Creates new files every maxFiles.
Maximum number of files per folder (2000 is default, 20000 is max). The folder may auto
maxFilesincrement sooner under certain conditions, e.g., snapshots being taken too fast.

Using the above information, the Lua code segment shown in Figure 5 can be created to take asnapshot.

Figure 5: Lua Code Segment for Snapshot Command

8

Key Script Interfaces

Key script interfaces are shown in Table 4. These methods are called by VideoTrack when executing a
Lua script.
Table 4: Lua Script Interfaces
Script Interfaces
SLUnLoad
SLLoadSLNewCmdCallback
SLPostAnalyze

8.1

Software Version
2.24.xx
2.24.xx
2.24.xx2.23.xx

SLPostAnalyze

This function is called by VideoTrack immediately after the analysis of a frame is complete. The analysis
step includes registration, tracking, detection, etc. All scripts should implement this function.

 SLPostAnalyze function is not called if a camera is disconnected or powered off (No Video Source
Available message).
In the helloworld.lua example, this function maintains a global framecount, and then uses it todetermine when to draw Hello World on the video. This function is passed two parameters:•_vtstate: This is a handle to the VideoTrack context and is needed in calls back to the VideoTrackprogram such as ffi.C.SLADrawObject shown in the example.
© SightLine Applications, LLC

9

EAN-Script-Development•

cameraIndex: Provides the camera index for which the script is being called. Allows users to takeactions on a specific camera or keep camera specific data separate.

 On the 1750-OEM, 3000-OEM, 4000-OEM, and 4100-OEM the SLPostAnalyze function is called for
all actively processed cameras. It is up to the user to decide how to use the cameraIndex. For
example, to draw Hello World for camera two, return at the top of SLPostAnalyze if the camera
index is not equal to 2.

Figure 6: SLPostAnalyze Usage from Hello World Example

8.2

SLUnLoad (New in 2.24.xx)

This function is called by VideoTrack whenever the script is disabled. This can happen if the board isshutting down or loading a new script. In the helloworld.lua example, this function removes thedrawObject with id 98 created in SLPostAnalyze. This function is passed only one parameter:_vtstate: This is a handle to the VideoTrack context and is needed in calls back to the VideoTrackprogram such as ffi.C.SLADrawObject shown in the example.

Figure 7: SLUnLoad Usage from Hello World Example© SightLine Applications, LLC

10

EAN-Script-Development

8.3

SLLoad (New in 2.24.xx),

This function is called by VideoTrack when loading the script.
_vtstate: This is a handle to the VideoTrack context and is needed in calls back to the VideoTrackprogram.

Figure 8: SLLoad Example

8.4

SLNewCmdCallback (New in 2.24.xx)

This function is called by VideoTrack when it receives a command. The following four parameters are
passed to this function:•_vtstate: This is a handle to the VideoTrack context and is needed in calls back to the VideoTrackprogram.
•_temp: This is a handle to the structure containing the message data.
•
len: The length of the message data.
•
type: This is the message type.

Figure 9: SLNewCmdCallback Example

9

Using Lua to Initialize Hardware

Lua scripts can also be used to perform additional operations during the initialization of cameras. Thisis achieved by setting a custom option in the Acquisition Settings dialog window in Panel Plus andloading a Lua script that contains a special function that is called by VideoTrack during initialization.
These can also be set using the SetAcquisitionParameters (0x37) and the ExternalProgram (0x8F)
commands in the IDD.
Additional operations may include toggling GPIO to reset a camera, sending commands over the serial
port or i2c bus, or other functions that are required to successfully configure and use the camera.
Process summary:
The following process is explained in the subsequent sections below.
•
Create a Lua script that contains a custom initialization routine.
•
Upload Lua scripts to the target OEM hardware using the SightLine upgrade utility.
•
Configure the acquisition parameters in Panel Plus.
•
Enable the Lua script with Panel Plus.

© SightLine Applications, LLC

11

EAN-Script-Development

9.1

Create Lua Script

The Lua script will contain a special function that will get called during the camera initialization
process. The function name will be specified as a string in the options argument of the acquisition
parameters. The function name should follow the rules below. The camera initialization function can
exist as part of an existing Lua script or standalone.

 For an example see cameraControl_Sample.lua script.

Figure 10: Camera Initialization - cameraControl_Sample.lua script

The name of the camera initialization function should use the following pattern:
SLCam_<<CameraName>>_Init

 <<CameraName>> can be the name or model of the camera or any other string identifier that isrelevant.

 The <<CameraName>> part of the function name will be used in the options argument to theacquisition parameters.
Common functionality such as querying for information, serial port communication and GPIO, can befound in the cameraControl_internal.lua script. This script will need to be uploaded to the target
hardware along with the camera specific Lua script.

Figure 11: Including Common Functionality from Another Lua Script© SightLine Applications, LLC

12

EAN-Script-Development

9.2

Load Script to Target Hardware

Follow the existing procedures in the Uploading Scripts section to move the script to the target
hardware using the SightLine firmware upgrade utility.
9.3

Configure Acquisition Parameters

The name of the camera initialization function in the previous section can now be set as an option
argument in the Options field of the Acquisition Settings dialog in Panel Plus.
1. From the main menu in Panel Plus » Configuration » Acquisition Settings.
2. In the Options field, enter the <<CameraName>> used in the Lua script function. This can be
combined with other options separated by a comma.

 The acquisition options string matches function in Lua script as shown in Figure 12.

Figure 12: Options Field - Panel Plus Acquisition Settings Dialog

9.4

Enable Lua Script

Follow the existing procedures in the Enabling / Disabling Scripts to move the script to the target
hardware using the External Programs dialog window in Panel Plus.
When the system reboots the Lua script will be loaded and the initialization function will be called
during the camera acquisition setup procedure.

© SightLine Applications, LLC

13

EAN-Script-Development

10 Troubleshooting
Issue

Recommendation

Script does not run.

From the Panel Plus main menu, go to View » User Warnings and enable the user warnings.
Start the script and monitor the User Warning dialog window to determine if there are any
User Warning preventing the script from running.

Cannot debug script.

Print statements are helpful but require access to the Linux console to see the output. Thisrequires a serial connection as well as modifying the silent argument in u-boot on the 1500OEM and 3000-OEM. Contact support if you have further questions on how to do this.
Additionally, debug statements can be drawn to the screen in the same manner using thehelloworld.lua example.

System is sluggish after
loading script.

From the Panel Plus main menu, go to View » Performance Graphs. Select Enable System
Status and CPU Timing. After a few seconds ARM should appear in the list of timings. Expand
this and look at the time for Post AnalyzeScript. The times presented are (Average, Minimum,
Maximum) over 100 samples in microseconds. If these numbers are large, e.g., several
thousand microseconds, reevaluate the level of complexity of the script.

64-bit integer data types.

Add ULL to the end of 64-bit integer constants, e.g., setTime.utcTime = 0x54deab2bd7500ULL

 The Lua interpreter can crash without adding ULL.
10.1 Additional Script Debugging
To display diagnostics messages to the Panel Plus window, use the SightLine warning messages. Referto the error_internal.lua script. An example of using error reporting can be found inhitachi_internal.lua shown in Figure 13.

Figure 13: User Error Reporting Script Example

The output is then displayed in Panel Plus. Right-click in the command area and choose Clear Text toclear the error of extraneous errors while testing.

Figure 14: User Error Reporting Example in Panel Plus

10.2 Questions and Additional Support
For questions and additional support, please contact Support. Additional support documentation andEngineering Application Notes (EANs) can be found on the Documentation page of the SightLine
Applications website.
© SightLine Applications, LLC

14

EAN-Script-Development

Appendix A - Lens Control Scripts
In software 2.24.xx to 3.4.x lens control was integrated into VideoTrack instead of the DLLs. Custom
lens control in these versions is available only through Lua scripts. In software 3.5.x and above it isrecommended to use the Lens DLL framework for lens control, including custom lens control andautofocus. For more information see EAN-Lens-Focus-Control.
A1

Overview

The lens control example scripts show how to implement a basic auto focus algorithm in Lua. They also
show how to receive SightLine lens commands sent from Panel Plus or another user interface andtranslate those commands into vendor specific commands such as zoom or focus.
These examples also show how to interface with a serial port from Lua, how to do bitwise operations in
Lua, plus many other helpful functions. This script was not designed to provide an out-of-the box auto
focus algorithm that is plug-and-play for any system.

 IMPORTANT: Use Sony or Hitachi cameras with a built-in lens.
To switch from the Sony to the Hitachi camera, edit the lensctrl.lua script to require thehitachictrl_internal.lua script as shown in Figure A1.
- - Use the correct "Lens/Camera" interface here. Currently the options are- - "hitachictrl" and “sonyctrl". At this point this should be the only thing you- - n e e d t o c h a n g e t o g o b e t w e e n t h e So n y a n d H i t a c h i c a m e r a s .
local lensctrl = require(“hitachictrl_internal”)

Figure A1: Edit lensctrl.lua Script

A2

Testing on SightLine Hardware

1. Modify existing scripts as needed on the PC to match the serial port settings used by the lens.

 Other settings such as encoder positions can also be changed as needed to match the properties ofthe lens.

299
300
301
302
303

- - and writing.
function ophirctrl.open()- - open the serial port
error.Print)_vtstate," open serial port\n")port:Open(portNumber, 57600, 8, 1, 0, 0)

Figure A2: Modify Scripts to Match Lens Serial Port Settings© SightLine Applications, LLC

15

EAN-Script-Development

2. Modify the script to match the camera index that the lens control is attached to.
Add or modify code to exit early from the SLPostAnalyze function for the non-lens-controlledcamera. For example, if Cam0 is being used then exclude everything that is not cameraIndex zero(0).

- - This function is called after SightLine VideoTrack software processes a frame- - of data.
function SLPostAnalyze(vstate, cameraIndex)
if not cameraIndex == 0 thenreturnend

Figure A3: Exit from SLPostAnalyze Function - Multiple Cameras

3.
4.
5.
6.

Upload the scripts to the target hardware.
Using Panel Plus, configure the system to stream video from the digital camera.
Enable the lens script.
Configure the serial port as Port Not Used. For example, from the main menu go to Configure »Serial Ports and verify that Serial Port 2 protocol is configured as Port Not Used.

 Refer to the Serial Ports section when using VIN1 on the 3000-OEM, Cam 1 on the 4000-OEM and4100-OEM, or Cam1 on the 1750-OEM.
7. To save the configuration to the parameter file, from the Panel Plus main menu » Parameters »Save to board.

 In 3.01.xx and earlier software versions, saving the Serial Port settings will prompt an additional
dialog window. Some setting changes require the board to be restarted for the settings to takeeffect. In the Apply New Settings dialog window, select an option to save the port configuration.

Figure A4: Apply New Settings Dialog - 3.01.xx and Earlier

8. When the system has rebooted, open the Lens tab in Panel Plus:a. In 3.4.x and earlier software versions verify that the Lens Type is set to None. If not, make thechange, save parameters, and then reset the board.

© SightLine Applications, LLC

16

EAN-Script-Developmentb. In 3.5.x software and above, verify that File in the Comms section is set to None. If not, makethe change, click Send, save parameters, and then reset the board.

9. Verify functionality by using the Narrow or Wide zoom controls.

 Not all lens mode controls are implemented in every Lua example. To see the controls that are
enabled in the Lua script, review the SLNewCmdCallback function implementation. For example,
SLNewCmdCallback implements specific lens mode operations such as Zoom shown in Figure A5.

Figure A5: SLNewCmdCallback Implementation - Zoom

A3

Basic Troubleshooting

Monitor the user warnings in Panel Plus. If there are no user warnings and the camera is not
responding, try different baud rates. Common baud rates for the Hitachi are 4800 and 9600. Common
baud rates for the Sony are 9600 and 19200.
If the camera is still not responding, contact Support.

© SightLine Applications, LLC

17

EAN-Script-Development

A4

Serial Ports

3000-OEM:
If the camera is connected on VIN0 no changes are needed. If the camera is connected on VIN1 thescripts that open the serial ports should be updated to Serial Port 3 instead of Serial Port 2. See
sonyctrl_internal.lua or hitachictrl_internal.lua in the Script Summary table.
1750-OEM/4000-OEM/4100-OEM:
If using Cam 1 instead of Cam 0 update the serial ports to Serial Port 6 instead of Serial Port 2.
A5

Camera Index

1750-OEM/3000-OEM/4000-OEM/4100-OEM:
If multiple cameras are being processed, add code to exit early from the SLPostAnalyze function for the
non-lens-controlled camera. For example, if Cam0 is being used then exclude everything that is not
cameraIndex zero (0).

- - This function is called after SightLine VideoTrack software processes a frame- - of data.
function SLPostAnalyze(vstate, cameraIndex)
if not cameraIndex == 0 thenreturnend

Figure A6: Exit from SLPostAnalyze Function - Multiple Cameras

The example script does not check the commanded camera. To create auto focus scripts for two
different cameras, additional code should be added to check the camera in the SLNewCmdCallback
function.

Appendix B - Reticle Selection Script
B1

Overview

Reticle selection scripts can be used to draw overlay reticles on top of the stream and can becustomized for each camera. Two script files are available:•

ReticlesConfig_internal.lua: Configuration parameters to customize the display of reticles.

•

Reticles.lua: Adds reticles to the display image. This is the primary script file that should be loaded
to the target to display the reticles on the screen.

B2

Configuring Reticle Scripts

 IMPORTANT: Make sure to edit reticlesConfig_internal.lua with a text editor before uploading
reticles.lua to the hardware.

© SightLine Applications, LLC

18

EAN-Script-Development
Table B1: User Configuration Parameters
Parameter
CAM<X>_RETICLE_INDEX

Description
Reticle to draw for camera with index X. See Reticle index section for available
options.
Field of view of camera with index X (degrees).
Diameter of circle (degree) of camera with index X.
Radius of the center point (circle) of camera with index X, default is 2.
Foreground color (Color 1) to draw for camera with index X. Check Reticle Color
mapping section for options.
Background color (Color 2) to draw for camera with index X. Check Reticle color
mapping section for options.

CAM<X>_FIELD_OF_VIEW
CAM<X>_CIRCLE_DEGREE
CAM<X>_CENTER_CIRCLE_RADIUS
CAM<X>_COLOR_FOREGROUNDCAM<X>_COLOR_BACKGROUND

Example setting for Camera 1:
CAM1_RETICLE_INDEX = 2– set camera 1 to use reticle with index 2
CAM1_COLOR_FOREGROUND = 13
– set camera 1 foreground color as yellow
CAM1_COLOR_BACKGROUND = 12
– set camera 1 background color to orange
CAM1_FIELD_OF_VIEW = 50
– set camera 1 field of view to 50 degrees
CAM1_CIRCLE_DEGREE = 10
– set camera 1 field of view to 10 degrees
CAM1_CENTER_CIRCLE_RADIUS = 2– set camera 1 center point radius to 2

Field of View: Field of view of camera (degrees) is used to calculate the size of lines used to draw theoverlays.
Circle Degree: Diameter of Circle (degree) relative to the field of view.
Center Circle Radius: Center point used in some reticles. Diameter of the circle in degrees.
B3

Reticle Color Mapping

Reticle color mapping to be used for background and foreground color settings in the configuration
file.
Table B2: Reticle Color Mapping
Color
WHITE
BLACK
LIGHT GRAYGRAYDARK GRAY
LIGHT BLUEBLUE

© SightLine Applications, LLC

Value
0
1
2
3
4
5
6

Color
DARK BLUE
LIGHT GREENGREEN
DARK GREENRED
ORANGEYELLOW

Value
7
8
9
10
11
12
13

19

EAN-Script-Development

B4

Reticle Index

There are four distinct types of reticles available now with index ranging from 0 to 3. Each camera
index is assigned a single reticle. To choose a different reticle for a certain camera change
corresponding camera reticle index. For example, to change camera 2 to use reticle with index 0change CAM2_RETICLE_INDEX = 0. All the reticles will be drawn with the same color combination
based on COLOR_TO_DRAW value.
Table B3: Reticle Indexes
Reticle Index© SightLine Applications, LLC

PictureReticle Index

0

2

1

3

Picture20