Pepperl+Fuchs OHV300 Operating instructions

FACTORY AUTOMATION
MANUAL
JAVASCRIPT PROGRAMMING
GUIDE

2
With regard to the supply of products, the current issue of the following document is
applicable: The General Terms of Delivery for Products and Services of the Electrical
Industry, published by the Central Association of the Electrical Industry (Zentralverband
Elektrotechnik und Elektroindustrie (ZVEI) e.V.) in its most recent version as well as the
supplementary clause: "Expanded reservation of proprietorship"

3
JavaScript Programming Guide
1Introduction ............................................................................ 10
1.1 Document Organization ...................................................................... 10
1.2 Document and Coding Conventions.................................................. 10
1.3 Related Documents ............................................................................. 10
1.4 Related Utility ....................................................................................... 11
2Programming Environment................................................... 12
2.1 Editor..................................................................................................... 12
2.2 CodeViewer Application...................................................................... 12
2.3 Security................................................................................................. 12
2.4 Debugging ............................................................................................ 13
3Programming Concepts ........................................................ 14
3.1 Simplicity .............................................................................................. 14
3.2 The OHV300 gui Object ....................................................................... 15
3.2.1 Softkey Implementation..........................................................................................16
3.2.2 Forms ....................................................................................................................16
3.2.3 Menus....................................................................................................................17
3.2.4 Text .......................................................................................................................19
3.3 Event ..................................................................................................... 19
3.3.1 Decode Events ......................................................................................................20
3.3.2 Key Events.............................................................................................................21
3.3.3 Command Execution..............................................................................................22
3.4 Reader Configuration .......................................................................... 22
3.5 Symbol Decoding ................................................................................ 23
3.5.1 Transform Data by Symbology ...............................................................................25
3.5.2 Evaluate Data Format ............................................................................................26
3.5.3 Detect Format Errors..............................................................................................27

4
JavaScript Programming Guide
3.5.4 Let the Handheld Process the Decode ...................................................................27
3.5.5 Ignore the Decode .................................................................................................28
3.5.6 Determine the Orientation of the Decode................................................................28
3.6 Host Communication........................................................................... 29
3.7 Data in Handheld Local Storage ........................................................ 30
3.8 Demo Programs ................................................................................... 30
4Class Reference ..................................................................... 31
4.1 decode .................................................................................................. 31
4.1.1 Properties ..............................................................................................................31
4.1.1.1 data............................................................................................................................... 31
4.1.1.2 symbology..................................................................................................................... 31
4.1.1.3 symbology_ex...............................................................................................................32
4.1.1.4 symbologyModifier........................................................................................................32
4.1.1.5 symbologyModifier_ex ..................................................................................................32
4.1.1.6 symbologyIdentifier....................................................................................................... 32
4.1.1.7 x ....................................................................................................................................32
4.1.1.8 y ....................................................................................................................................32
4.1.1.9 time ...............................................................................................................................33
4.1.1.10 quality_percent .............................................................................................................33
4.1.1.11 qrPosition ...................................................................................................................... 33
4.1.1.12 qrTotal...........................................................................................................................33
4.1.1.13 qrParity..........................................................................................................................33
4.1.1.14 linkage...........................................................................................................................33
4.1.1.15 bounds ..........................................................................................................................33
4.1.1.16 numExtraFields ............................................................................................................. 34
4.1.1.17 decoderType.................................................................................................................34
4.1.1.18 aimSymbology ..............................................................................................................34
4.1.1.19 aimModifier ...................................................................................................................35
4.1.1.20 decodeOutputFormat.................................................................................................... 35

5
JavaScript Programming Guide
4.2 gui.......................................................................................................... 36
4.2.1 Methods.................................................................................................................36
4.2.1.1 alert ...............................................................................................................................36
4.2.1.2 confirm ..........................................................................................................................37
4.2.1.3 prompt........................................................................................................................... 38
4.2.1.4 putBox........................................................................................................................... 39
4.2.1.5 sendKey........................................................................................................................40
4.2.1.6 sendText ....................................................................................................................... 40
4.2.1.7 show.............................................................................................................................. 40
4.2.1.8 showForm .....................................................................................................................41
4.2.1.9 showMenu ....................................................................................................................41
4.2.1.10 showSubMenu .............................................................................................................. 42
4.2.1.11 splash and clearSplash.................................................................................................42
4.2.1.12 sync............................................................................................................................... 43
4.2.2 Properties ..............................................................................................................43
4.2.2.1 inputMode .....................................................................................................................43
4.2.2.2 key ................................................................................................................................ 44
4.2.2.3 leftSoftkey ..................................................................................................................... 44
4.2.2.4 rightSoftkey ...................................................................................................................44
4.2.2.5 statusText ..................................................................................................................... 45
4.2.3 Objects ..................................................................................................................45
4.2.3.1 gui.Button......................................................................................................................45
4.2.3.2 gui.Edit .......................................................................................................................... 46
4.2.3.3 gui.Form........................................................................................................................48
4.2.3.4 gui.Image ...................................................................................................................... 49
4.2.3.5 gui.Label ....................................................................................................................... 50
4.2.3.6 gui.Menu .......................................................................................................................50
4.2.3.7 gui.MenuItem ................................................................................................................51
4.2.3.8 gui.MultiLineEdit ........................................................................................................... 51
4.2.3.9 gui.Separator ................................................................................................................ 52

6
JavaScript Programming Guide
4.2.3.10 gui.Softkey .................................................................................................................... 53
4.2.3.11 gui.Text ......................................................................................................................... 54
4.2.3.12 gui.ToggleButton...........................................................................................................55
4.2.4 Predefined Softkey Objects....................................................................................57
4.2.4.1 backSoftkey .................................................................................................................. 57
4.2.4.2 cancelSoftkey ............................................................................................................... 57
4.2.4.3 okSoftkey ......................................................................................................................57
4.2.4.4 selectSoftkey ................................................................................................................ 57
4.2.5 Form and Menu Common Methods........................................................................57
4.2.5.1 append(control)............................................................................................................. 57
4.2.5.2 prepend(control) ........................................................................................................... 58
4.2.5.3 setActiveChild(control)..................................................................................................58
4.2.6 Form and Menu Common Properties......................................................................58
4.2.6.1 caption .......................................................................................................................... 58
4.2.6.2 onKey............................................................................................................................59
4.3 reader.................................................................................................... 59
4.3.1 Methods.................................................................................................................59
4.3.1.1 beep..............................................................................................................................59
4.3.1.2 defaultSettings .............................................................................................................. 60
4.3.1.3 getKeyboardStatus ....................................................................................................... 60
4.3.1.4 processCommand......................................................................................................... 61
4.3.1.5 readSetting....................................................................................................................61
4.3.1.6 runScript........................................................................................................................61
4.3.1.7 saveSettings .................................................................................................................62
4.3.1.8 setDisplayLed ...............................................................................................................62
4.3.1.9 setInterval ..................................................................................................................... 63
4.3.1.10 clearInterval .................................................................................................................. 63
4.3.1.11 setTimeout .................................................................................................................... 63
4.3.1.12 clearTimeout ................................................................................................................. 64
4.3.1.13 shiftJisToUnicode ......................................................................................................... 64

7
JavaScript Programming Guide
4.3.1.14 writeSetting ................................................................................................................... 64
4.3.1.15 unicodeToShiftJis ......................................................................................................... 65
4.3.2 Properties ..............................................................................................................65
4.3.2.1 onCommand ................................................................................................................. 65
4.3.2.2 onCommandFinish........................................................................................................66
4.3.2.3 onDecode ..................................................................................................................... 67
4.3.2.4 onDecodeAttempt .........................................................................................................68
4.3.2.5 onIdle ............................................................................................................................69
4.3.2.6 onStandby..................................................................................................................... 69
4.3.2.7 batteryLevel .................................................................................................................. 70
4.3.2.8 red.................................................................................................................................70
4.3.2.9 green.............................................................................................................................70
4.3.2.10 amber............................................................................................................................70
4.3.2.11 none .............................................................................................................................. 70
4.3.2.12 cabled ........................................................................................................................... 71
4.3.2.13 charging ........................................................................................................................71
4.3.2.14 hardwareVersion........................................................................................................... 71
4.3.2.15 oemId ............................................................................................................................ 71
4.3.2.16 readerId.........................................................................................................................71
4.3.2.17 softwareVersion ............................................................................................................ 71
4.3.2.18 bdAddr ..........................................................................................................................72
4.4 storage.................................................................................................. 72
4.4.1 Methods.................................................................................................................72
4.4.1.1 append.......................................................................................................................... 72
4.4.1.2 erase .............................................................................................................................72
4.4.1.3 findFirst .........................................................................................................................73
4.4.1.4 findNext.........................................................................................................................73
4.4.1.5 read...............................................................................................................................74
4.4.1.6 rename..........................................................................................................................74
4.4.1.7 size................................................................................................................................74

8
JavaScript Programming Guide
4.4.1.8 upload ...........................................................................................................................74
4.4.1.9 write ..............................................................................................................................75
4.4.1.10 getHeader .....................................................................................................................76
4.4.1.11 saveOffsetWindow........................................................................................................76
4.4.2 Properties ..............................................................................................................76
4.4.2.1 fullness_percent............................................................................................................76
4.4.2.2 isFull..............................................................................................................................77
4.4.2.3 logFullness_percent......................................................................................................77
4.5 comm..................................................................................................... 77
4.5.1 Methods.................................................................................................................77
4.5.1.1 connect ......................................................................................................................... 77
4.5.1.2 disconnect..................................................................................................................... 77
4.5.1.3 sendPacket ...................................................................................................................77
4.5.1.4 sendText ....................................................................................................................... 78
4.5.2 Properties ..............................................................................................................78
4.5.2.1 isConnected.................................................................................................................. 79
4.6 Functions.............................................................................................. 79
4.6.1 Dialog ....................................................................................................................79
4.6.1.1 alert ...............................................................................................................................79
4.6.1.2 confirm ..........................................................................................................................80
4.6.1.3 prompt........................................................................................................................... 81
4.6.2 Other Functions .....................................................................................................82
4.6.2.1 gc ..................................................................................................................................82
4.6.2.2 include ..........................................................................................................................82
4.6.2.3 print ............................................................................................................................... 82
4.6.2.4 setStandbyMessage .....................................................................................................83
4.6.2.5 wdt ................................................................................................................................83
5Glossary and Acronyms........................................................ 84
6Input Modes............................................................................ 85

9
JavaScript Programming Guide
7Format Specifiers................................................................... 86
8Supported JavaScript Core................................................... 87
9Symbology ID & Modifier Information.................................. 89

10
Introduction
1Introduction
This manual describes the application programming interface for OHV300 handhelds. It is
assumed the user will have programming knowledge and familiarity with the JavaScript
language.
Handhelds read code and can be programmed to transmit code data over a selected
communications link or to store data in reader memory (batch mode).
The programming environment provides interfaces to:
Read and manipulate data in reader memory.
Display information on the OHV300 screen.
Retrieve data from reader hardware or OHV300 key pad.
Access data sent by host.
Transmit data to a host computer via communications link.
Select type of communications link.
Set, change, and retrieve reader configuration settings.
1.1 Document Organization
This document is organized as follows:
Section 1, Introduction: gives a product description and describes how to use this
document.
Section 2, Programming Environment: identifies tools used to create and load
application software into reader.
Section 3, Programming Concepts: discusses how to accomplish various operations
on the reader using the application programming interface.
Section 4, Class Reference: presents classes, objects, methods, properties, and
constructors that support application programs.
Section 5 –9: Appendix
1.2 Document and Coding Conventions
The JavaScript library uses the following naming conventions:
identifiers: mixed-case with a capital letter where words join (soCalledCamelCase);
acronyms and other initialisms are capitalized like words, e.g., nasaSpaceShuttle,
httpServer
variables and properties: initial lower case
classes (i.e., constructors): initial capital
functions: initial lower case
unit of measure: suffix to name, separated from name by underscore, using correct
case when it’s significant, e.g., offset_pixels, width_mm, power_MW, powerRatio_dB
1.3 Related Documents
OHV manuals
Interface Configuration Document

11
Introduction
1.4 Related Utility
Vision Configurator
Example!
Visit http://www.pepperl-fuchs.com to obtain this application.

12
Programming Environment
2Programming Environment
This document is not a JavaScript manual. The following sources are a few of the many
JavaScript reference books and online documents:
JavaScript: The Complete Reference, Second Edition
by Thomas Powell, et al.
JavaScript Demystified (Demystified)
by James Keogh.
JavaScript in 10 Simple Steps or Less
by Arman Danesh.
http://www.javascript.com/
2.1 Editor
You can use your favorite editing product to create and modify JavaScript code. Turn off
any smart quote options in the editor. Smart quotes are not valid in JavaScript.
2.2 CodeViewer Application
The CodeViewer Application runs as a JavaScript application on the OHV300. The menu
driven application has features for changing configuration settings and for defining the
applications that run on the reader. JavaScript developers can make use of the following
keywords in the CodeViewer Application:
Title –Displays the title of the JavaScript rather than the file name in CodeViewer’s
‘Application’ menu. Add a comment to your script formatted as $Title: <title of script>$ to
implement.
Revision –Displays the revision of the JavaScript from the CodeViewer’s
‘Application/<script>’ submenu. Add a comment to your script formatted as $Revision:
<revision of script>$ to implement.
2.3 Security
Each handheld reader contains a unique reader ID.
Select features of the reader are protected by license.
A license file is required for each reader licensed to use protected features.
Third party software licenses may also be protected using the encryption utility.

13
Programming Environment
2.4 Debugging
The handheld reader contains a built-in error log that can be used when debugging scripts.
To debug the script when an error has occurred, send the ‘(‘ command to the reader; the
reader responds by sending the error log to the communications port. The error log may
contain messages from the firmware that should be ignored. JavaScript errors in the log
can be identified by the format: filename:lineNumber. If there are many error codes in the
error log, send the ‘)’ command to clear the log and repeat the steps to create the error,
leaving only one entry in the log.
Example:
X ap/gerror-log. storage_init: flMountVolume fail status 26,
formatting.storage_formatFilesystem: status 0.
temp.js:3: TypeError: gui.aler is not a function. X ap/dEOF.
This error log contains one firmware error and one JavaScript error. The JavaScript error
description begins with temp.js:3: and tells us that on line three of the temp.js file, gui.aler
is not recognized as a function. In this case, gui.alert has been misspelled (it is missing the
t).

14
Programming Concepts
3Programming Concepts
To help the developer create unique applications for the reader, we provide this JavaScript
Programming Guide. The developer can create complex business applications with
prompts and data entry through the OHV300 user interface features (keypad and display
screen).
The features of the programming interface include:
A graphical user interface
Event handlers
Symbol decoding
Host communications
Local data storage
Handheld configuration
In support of these features, the environment defines the following objects:
gui
reader
storage
comm
Using these features, you can create robust, interactive, and sophisticated user
applications.
A script can be made the default application using the configuration utility, or it may be run
from the configuration utility without making it the default.
Note!
The default application allows scripts to be run by host command or configuration code scan;
the command is “|run:scriptName.js” (using your own scriptName).
3.1 Simplicity
The “Hello World!” application is traditionally the first application presented in a
programming guide. It is an easy to code and understand application that illustrates how
the programming environment works.
In its simplest form, the “Hello World!” application in the OHV300 environment sends text
to the display. With the following single line of code, you can display “Hello World!” in the
screen defined by the standard OHV300 gui object (section 4.1).
gui.show(new gui.Text("Hello World!"));
Execution of this script displays the image shown in Figure 1.

15
Programming Concepts
Figure 1 –Hello World Application
Note!
The text is displayed in a text box control with a scroll bar to the right as defined by the
OHV300 gui object.
3.2 The OHV300 gui Object
The OHV300 application development environment defines a standard GUI display for
application software (Figure 2). The display supports simple prompts and data entry.
Figure 2 –The Standard GUI Display
The standard display consists of a status bar, a display area, and labels for the left and
right software programmable keys (softkeys) at the top of the OHV300 key pad (see Figure
6).
The scroll bar on the right side of the screen indicates the relative position within the
displayed object as the operator scrolls through forms, menus, or text using the up and
down keys on the keypad. This scrolling feature allows the application to display objects
larger than the display area.
Use the gui interface to develop forms and menus applications, and use the “show”
methods to display them.

16
Programming Concepts
3.2.1 Softkey Implementation
Softkeys are general purpose, programmable keys. The softkeys are independent of the
GUI display. The gui.showForm, gui.showMenu, and gui.showSubmenu methods include
softkey definitions appropriate for the implementation.
The following example shows the basic approach to programming the softkeys and
implementing their event handlers.
// define send-key functions used by common softkeys
function sendEnter() { gui.sendKey(gui.key.enter); }
function sendEscape() { gui.sendKey(gui.key.escape); }
// create some common softkeys
var selectSoftkey = new gui.Softkey("Select", sendEnter);
var okSoftkey = new gui.Softkey("OK", sendEnter);
var backSoftkey = new gui.Softkey("Back", sendEscape);
var cancelSoftkey = new gui.Softkey("Cancel", sendEscape);
See section 0 (gui object) for more information.
3.2.2 Forms
Forms are the building blocks of your application. Each form represents a set of actions
you want to present to the user on screen.
Use the gui.Form object (section 4.2.3.3) to define the forms for your application. Section
4.2.3 defines the form object and several constructors that you can use to create controls
on your application form.
The following examples demonstrate how to create a form. The event handler functions
need to be defined for your application.
// JavaScript Form Demo Script Document
// form event handlers
function myFormOnOk(){/* processing code (example: save the
Employee #) */}
function myFormOnCancel(){/* processing code (example: return to
main menu) */}
// create the form object
var myForm = new gui.Form(myFormOnOk, myFormOnCancel);
// create the edit control
var edit = new gui.Edit("");
// create the label control
var label = new gui.Label("Employee #:");
// position the controls on the form

17
Programming Concepts
myForm.append(label);
myForm.append(edit);
// Create the caption that will appear on the status bar
myForm.caption = "form demo";
// show the form
gui.showForm(myForm);
When the Form Demo Script runs, the OHV300 displays the following image:
Figure 3 –Form Demo Display
The user enters an employee number into the edit control and presses the left button (OK)
to submit the data.
3.2.3 Menus
Use the gui.Menu object (section 4.2.3.6) to define the menus for your application. Use the
gui.MenuItem constructor to define the controls in the menu. Each control has an
associated onClick property that defines the function of the OHV300.
The following example demonstrates how to build and display menus and submenus.
// JavaScript Menu Demo Script Document
// menu event handlers
function onTimeCard(){alert(postAlertFunc, "TimeCard");}
function onInventory()
{
gui.showSubMenu(subMenu, myMenu);
}
function onCapital(){alert(postAlertFunc, "capital");}
function onStock(){alert(postAlertFunc, "stock");}
// create menu objects
var myMenu = new gui.Menu();
var subMenu = new gui.Menu();
// create menu entries
var timeCardApp =

18
Programming Concepts
new gui.MenuItem("Time Card", onTimeCard);
var inventoryApp =
new gui.MenuItem("Inventory", onInventory);
var separator =
new gui.Separator(1, gui.separatorStyle.horizontalLine);
myMenu.caption = "menu demo";
subMenu.caption = "subMenu demo";
// create subMenu entries
var capital =
new gui.MenuItem("Capital", onCapital);
var stock =
new gui.MenuItem("Stock", onStock);
// position the controls on the menus
myMenu.append(separator);
myMenu.append(inventoryApp);
myMenu.append(timeCardApp);
subMenu.append(capital);
subMenu.append(stock);
//Specify a child to be selected when the menu is displayed
(optional)
myMenu.setActiveChild(inventoryApp);
subMenu.setActiveChild(capital);
// set the caption text for the status bar
myMenu.caption = "menu demo";
// show the menu
gui.showMenu(myMenu);
When the Menu Demo application is initiated, the OHV300 displays the following image:
Figure 4 –Menu Demo Display

19
Programming Concepts
The Select button sends gui.softkey.enter to run the highlighted application. In this
example, the Inventory option is selected. The script then displays the Inventory submenu
shown in Figure 5.
Figure 5 –Sub Menu Demo Display
3.2.4 Text
Use the gui.Text object (section 4.2.3.11) to show text. Text may exceed the display area,
toggling the arrow buttons to view all data. This should not be used to control text within
menus or forms.
3.3 Event
The JavaScript environment is event driven. The reader firmware waits for an event such
as a pressed key. The application gains control of an event by setting an object's event
properties to functions. Events include:
send and receive of communications packets
decode operations
pressed keys
command execution
change of reader mode (idle, standby, and power down)
An application gains control only when:
The reader application defines an event property.
The application creates a function and assigns it to the event property.
The event occurs.
The application can disable an event by setting the event property to null.

20
Programming Concepts
3.3.1 Decode Events
The reader object defines an event onDecode. Section 4.3.2.3 discusses decode events.
Example:
var numDecodes = 0;
var numDecodesProcessed = 0;
reader.onDecodeAttempt = function(count)
{
numDecodes = count;
numDecodesProcessed = 0;
}
reader.onDecode = function(decode)
{
if( ++numDecodesProcessed < numDecodes )
{
// process individual decode, save in variables, etc.
}
else
{
// process the whole set, using saved variables, etc.
}
}