Sie sind auf Seite 1von 200

instruction manual

NetLinx Studio
v2.4 or higher

So ftw are

Software License and Warranty Agreement


LICENSE GRANT.
AMX grants to Licensee the non-exclusive right to use the AMX Software in the manner described in this License. The AMX Software is licensed, not sold. The AMX Software consists of generally available programming and development software, product documentation, sample applications, tools and utilities, and miscellaneous technical information. Please refer to the README.TXT file on the compact disc or download for further information regarding the components of the AMX Software. The AMX Software is subject to restrictions on distribution described in this License Agreement. YOU MAY NOT LICENSE, RENT, OR LEASE THE AMX SOFTWARE. You may not reverse engineer, decompile, or disassemble the AMX Software.

INTELLECTUAL PROPERTY.
The AMX Software is owned by AMX and is protected by United States copyright laws, patent laws, international treaty provisions, and/or state of Texas trade secret laws. Licensee may make copies of the AMX Software solely for backup or archival purposes. Licensee may not copy the written materials accompanying the AMX Software.

TERMINATION. AMX RESERVES THE RIGHT, IN ITS SOLE DISCRETION, TO TERMINATE THIS LICENSE FOR ANY REASON AND UPON WRITTEN NOTICE TO LICENSEE.
In the event that AMX terminates this License, then Licensee shall return all copies of the AMX Software to AMX and certify in writing that all copies have been destroyed.

PRE-RELEASE CODE.
Portions of the AMX Software may, from time to time, as identified in the AMX Software, include PRE-RELEASE CODE and such code may not be at the level of performance, compatibility and functionality of the final code. The PRE-RELEASE CODE may not operate correctly and may be substantially modified prior to final release or certain features may not be generally released. AMX is not obligated to make or support any PRE-RELEASE CODE. ALL PRE-RELEASE CODE IS PROVIDED "AS IS" WITH NO WARRANTIES.

LIMITED WARRANTY.
AMX warrants that the AMX Software will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt. AMX DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE AMX SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. Any supplements or updates to the AMX SOFTWARE, including without limitation, any (if any) service packs or hot fixes provided to you after the expiration of the ninety (90) day Limited Warranty period are not covered by any warranty or condition, express, implied or statutory.

LICENSEE REMEDIES.
AMX's entire liability and your exclusive remedy shall be repair or replacement of the AMX Software that does not meet AMX's Limited Warranty and which is returned to AMX. This Limited Warranty is void if failure of the AMX Software has resulted from accident, abuse, or misapplication. Any replacement AMX Software will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. Outside the United States, these remedies may not available. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL AMX BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS AMX SOFTWARE, EVEN IF AMX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/ COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. U.S. GOVERNMENT RESTRICTED RIGHTS. The AMX Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable.

This Agreement replaces and supercedes all previous AMX Software License Agreements and is governed by the laws of the State of Texas, and all disputes will be resolved in the courts in Collin County, Texas, USA. Should you have any questions concerning this Agreement, or if you desire to contact AMX for any reason, please write: AMX Corporation, 3000 Research Drive, Richardson, TX 75082.

Table of Contents

Table of Contents
NetLinx Studio (v2.4 or higher) ...............................................................................1
Overview ........................................................................................................................... 1 Supported Operating Systems and Minimum PC Requirements ...................................... 2
Supported operating systems: ................................................................................................. 2 PC Requirements:.................................................................................................................... 2 Other PC requirements: ........................................................................................................... 2

Supported File Types ........................................................................................................ 2 What's New Dialog ............................................................................................................ 3 WebUpdate ....................................................................................................................... 3 Software History2 Application ........................................................................................... 3 DIP Switch 2.0................................................................................................................... 3

The NetLinx Studio v2.4 Work Area ........................................................................5


Overview ........................................................................................................................... 5 Title Bar ............................................................................................................................. 5 Toolbars ............................................................................................................................ 5 Menu Bar........................................................................................................................... 6 Status Bar.......................................................................................................................... 6 Workspace Window........................................................................................................... 8
Workspace Window - Workspace Tab ..................................................................................... 8 Workspace Folder .................................................................................................................... 9 Project Folders ......................................................................................................................... 9 System Folders ........................................................................................................................ 9 System File Folders ............................................................................................................... 10 System Files........................................................................................................................... 10 File Mapping Information........................................................................................................ 10 Other key functions and features of the Workspace tab include:........................................... 10 Workspace File Context Menu ............................................................................................... 11 Workspace Window - Online Tree Tab .................................................................................. 12

Output Display Window ................................................................................................... 12


Output Display Window Context Menu .................................................................................. 13 File Transfer Tab Context Menu ............................................................................................ 14 Output Display Window - Notifications Tab............................................................................ 14 Output Display Window - Diagnostics Tab............................................................................. 14

Source Code Editor Windows ......................................................................................... 15


Source Code Editor Window - Features................................................................................. 15

Terminal Window............................................................................................................. 17

NetLinx Studio (v2.4 or higher)

Table of Contents

Using The Terminal Window .................................................................................................. 17 Terminal Window Context Menu ............................................................................................ 18

Watch Window ................................................................................................................ 18


Watch Window Context Menu................................................................................................ 19

Using NetLinx Studio ............................................................................................. 21


The Netlinx Studio Workspace Wizard............................................................................ 21
Using the Workspace Wizard................................................................................................. 21 Building the Workspace ......................................................................................................... 23

The Netlinx Studio Code Wizard ..................................................................................... 23

Working With Workspace Files ............................................................................. 25


Overview ......................................................................................................................... 25
Opening Workspace Files ...................................................................................................... 26 Creating New (empty) Workspace Files................................................................................. 26 Import an Existing Project ...................................................................................................... 26 Copying and Pasting Projects ................................................................................................ 27 Deleting A Project From The Workspace............................................................................... 27 Importing Projects Into A Workspace..................................................................................... 27 Saving The Workspace .......................................................................................................... 28 Exporting Workspace Files For Distribution ........................................................................... 28 Importing Exported ("To Go") Workspace Files ..................................................................... 29 Viewing and Editing Workspace Properties ........................................................................... 30 Workspace File Context Menu ............................................................................................... 30

Working With Projects ........................................................................................... 33


Overview ......................................................................................................................... 33 Opening Projects in NetLinx Studio v2.0 (or higher) ....................................................... 33 Creating A New Project................................................................................................... 33 Building the Selected Project .......................................................................................... 34 Viewing And Editing Project Properties........................................................................... 34 Converting NetLinx Studio v1.2 Project Files.................................................................. 35
Project Folder Context Menu ................................................................................................. 36

Working With Systems and System Files ............................................................ 37


Working With Systems .................................................................................................... 37 Creating A New System .................................................................................................. 38 Adding An Existing System To a Project......................................................................... 39
Importing Systems Into A Project........................................................................................... 39 Copying And Pasting Systems............................................................................................... 39

Deleting A System From A Project.................................................................................. 39 System Status: Active Vs. Inactive.................................................................................. 40

ii

NetLinx Studio (v2.4 or higher)

Table of Contents

Designating The Active System ............................................................................................. 40

Configuring System-Level Communications Settings ..................................................... 40 Adding A File To A System ............................................................................................. 41


Drag And Drop Files Into A System ....................................................................................... 42

Removing A File From A System .................................................................................... 42 Building (Compiling Systems) ......................................................................................... 43


Building The Selected System ............................................................................................... 43 Building The Active System ................................................................................................... 43

Viewing And Editing System Properties .......................................................................... 44


System Folder Context Menu................................................................................................. 44

System Files.................................................................................................................... 45 Creating New System Files ............................................................................................. 46


File Types And Extensions..................................................................................................... 46

Identifiers vs. Disk Filenames.......................................................................................... 47 Viewing And Editing System File Properties ................................................................... 47 Device Mapping............................................................................................................... 48
Device Mapping Dialog .......................................................................................................... 48 DEVICE:PORT:SYSTEM (D:P:S) .......................................................................................... 49 To Remove Device Mapping Information from a File............................................................. 50 System File Device Map Context Menu ................................................................................. 50

Working With System Source Code Files ....................................................................... 50


Adding A New Source Code File To A System ...................................................................... 51 Adding An Existing Source Code File To A System............................................................... 51 Removing A File From A System ........................................................................................... 52 Creating A Source Code File ................................................................................................. 52 Saving The Active File ........................................................................................................... 53 Saving All Open Files............................................................................................................. 53 File Revisions......................................................................................................................... 53 Designating The System's Master Source Code File............................................................. 54 Compiling Source Code Files................................................................................................. 54 UTF-8 Encoding ..................................................................................................................... 55 SRC File Extraction................................................................................................................ 55 ZIP File Extraction.................................................................................................................. 56 Source File Folder Context Menu .......................................................................................... 56 Source Code File Context Menu ............................................................................................ 57

Working With Include Files.............................................................................................. 57


NetLinx .AXI File .................................................................................................................... 57 Creating An Include File......................................................................................................... 57 Adding A New Include File To A System ............................................................................... 58 Adding An Existing Include File To A System ........................................................................ 58

NetLinx Studio (v2.4 or higher)

iii

Table of Contents

Include File Folder Context Menu .......................................................................................... 58 Include File Context Menu ..................................................................................................... 59

Working With Module Files ............................................................................................. 59


Duet (JAR) Module Files ........................................................................................................ 59 Minimum Support Requirements For Modules....................................................................... 60 Minimum support requirements for Duet modules (*.JAR):.................................................... 60 Adding A New Module File To A System ............................................................................... 60 Adding An Existing Module File To A System........................................................................ 60 Source Code Entry................................................................................................................. 61 Compiling Module Files.......................................................................................................... 62 Module File Folder Context Menu .......................................................................................... 62 Module File Context Menu ..................................................................................................... 62

Working With User Interface Files................................................................................... 63


Adding An Existing User Interface File To A System ............................................................. 63 Configuring NetLinx Source Code for KPD Files ................................................................... 64 Sample Netlinx Code ............................................................................................................. 65 User Interface File Folder Context Menu ............................................................................... 66 User Interface File Context Menu .......................................................................................... 66

Working With IR Files...................................................................................................... 66


Adding An Existing Ir File To A System ................................................................................. 66 IREDIT ................................................................................................................................... 67 Working With IREdit Database (*.IRN) Files .......................................................................... 67 Adding An IR File From the AMX IR Database ...................................................................... 67 Adding An IR File From an IREDIT User Database (*IRN) File ............................................. 68 IR File Folder Context Menu .................................................................................................. 69 IR File Context Menu ............................................................................................................. 69

Working With "Other" Files.............................................................................................. 70


Creating a Text File................................................................................................................ 70 Adding an Existing "Other" File To a System......................................................................... 70 Other File Folder Context Menu............................................................................................. 71 Other File Context Menu ........................................................................................................ 71

Search Operations .......................................................................................................... 71


Using The Edit And Search Functions ................................................................................... 71 Searching Within the Active Source Code File ...................................................................... 71 Search And Replace Within The Active Source Code File .................................................... 72 Searching Across Multiple Files ............................................................................................. 73 Searching For Ir Library (IRL/IRV) Files................................................................................. 73

Printing Files ................................................................................................................... 74


Print Preview Window ............................................................................................................ 74 Print Dialog............................................................................................................................. 75

iv

NetLinx Studio (v2.4 or higher)

Table of Contents

Programming ..........................................................................................................77
Overview ......................................................................................................................... 77
Source Code Editor Context Menu ........................................................................................ 77

Using The Code Wizard .................................................................................................. 78


Creating Events With the Code Wizard.................................................................................. 79 Creating Send_Commands With the Code Wizard................................................................ 79 Generating Constants From an IR File With the Code Wizard .............................................. 79 Code Wizard - Advanced Users............................................................................................. 80 Code Wizard Dialog - Button Tab .......................................................................................... 80 Code Wizard Dialog - Channel Tab ....................................................................................... 81 Code Wizard Dialog - Level Tab ............................................................................................ 82 Code Wizard Dialog - Data Tab ............................................................................................. 83 Code Wizard Dialog - Send Command Tab........................................................................... 84 Code Wizard Dialog - IR Constant Tab.................................................................................. 84 Syntax Highlighting ................................................................................................................ 85 Default Syntax Highlighting Colors......................................................................................... 85 AutoComplete and AutoSuggest............................................................................................ 86 Call Tips ................................................................................................................................. 87 Code Folding.......................................................................................................................... 88 Unicode Characters ............................................................................................................... 89 UTF-8 Encoding ..................................................................................................................... 89 Insert Section ......................................................................................................................... 89 Goto Section .......................................................................................................................... 90 Goto Line................................................................................................................................ 90 Goto Function Or Subroutine ................................................................................................. 90 Block Comment - Uncomment ............................................................................................... 90 Case Inversion ....................................................................................................................... 91 Clipboard Text Buffer ............................................................................................................. 91 Using The Clipboard Text Buffer............................................................................................ 91 Find Matching Brace .............................................................................................................. 92 Sequentially Renumber Selection .......................................................................................... 92 Show Whitespace .................................................................................................................. 92 Show End Of Line .................................................................................................................. 92 Rescan Current Source File................................................................................................... 92 Advanced Editor Commands ................................................................................................. 92 Supported Regular Expression Special Characters............................................................... 93 Cut, Copy And Paste.............................................................................................................. 93 Undo/redo .............................................................................................................................. 94

Working With Bookmarks ................................................................................................ 94 Debugging ....................................................................................................................... 94

NetLinx Studio (v2.4 or higher)

Table of Contents

Debugging Source Code Files ............................................................................................... 94 To enter debug mode:............................................................................................................ 95 Using Single-step Mode ......................................................................................................... 95 Master Controller Debug Options........................................................................................... 96 Changing The Value Of A Watched Variable......................................................................... 96 Debug Mode Error Messages ................................................................................................ 96

Breakpoints ..................................................................................................................... 97
Using Breakpoints (NetLinx Only) .......................................................................................... 97 Setting A Breakpoint .............................................................................................................. 97 Clearing Breakpoints.............................................................................................................. 98 Editing Breakpoints ................................................................................................................ 98

PUSH Messages............................................................................................................. 98
Insert Push Message Dialog .................................................................................................. 98 Find Push Message Dialog .................................................................................................... 99

Working With Unicode..................................................................................................... 99


Configuring NSX For Unicode Support .................................................................................. 99 Enabling UTF-8 ...................................................................................................................... 99 Enabling Unicode Compiling .................................................................................................. 99 Including the Unicode Library................................................................................................. 99 Defining a Unicode String Literal.......................................................................................... 100 Storing a Unicode String ...................................................................................................... 100 Working With Widechar Arrays and Unicode Strings........................................................... 100 Unicode - Character Case Mappings ................................................................................... 101 Unicode - Concatenating String ........................................................................................... 101 Unicode - Converting Between WIDECHAR and CHAR...................................................... 101 Unicode - Using FORMAT ................................................................................................... 101 Unicode - Reading and Writing To Files .............................................................................. 102 Unicode - Send Strings To A User Interface ........................................................................ 102 Right-to-Left Unicode Strings ............................................................................................... 103 Unicode - Compiler Errors.................................................................................................... 103

Using the Terminal Window .......................................................................................... 104 ASCII / HEX / DECIMAL CONVERSIONS TABLE ....................................................... 105

Compile Operations ............................................................................................. 107


Overview ....................................................................................................................... 107 Building the Workspace ................................................................................................ 107 Building the Selected Project ........................................................................................ 107 Building the Selected System ....................................................................................... 108 Building the Active System............................................................................................ 108
Designating the System's Master Source Code File ............................................................ 108

vi

NetLinx Studio (v2.4 or higher)

Table of Contents

Compiling an Individual File .......................................................................................... 109 Compiler Errors and Warnings ...................................................................................... 110 Compiler Errors ............................................................................................................. 110 Compiler Warnings........................................................................................................ 113
Compiler Error Warnings Report Dialog............................................................................... 114 Disabling Compiler Warnings In Netlinx Code ..................................................................... 114

Run-Time Errors............................................................................................................ 114

Working With Online Devices ..............................................................................115


NetLinx Network Setup.................................................................................................. 115
Network Setup...................................................................................................................... 115

Working With the Online Device Tree ........................................................................... 116


Device Tree Elements.......................................................................................................... 117 Device States ....................................................................................................................... 118 Device Tree Context Menu .................................................................................................. 119 Checking Port Status ........................................................................................................... 119 Binding/Unbinding Devices .................................................................................................. 120

NetLinx Diagnostics - NetLinx Device Notification ........................................................ 121


Adding A Device To The Device Notification List................................................................. 121 Editing Device Notification Settings ..................................................................................... 122 Removing Devices From The Notifications List ................................................................... 123

NetLinx Diagnostics - NetLinx Internal Diagnostics Messages ..................................... 123


Debugging NetLinx Programs with Terminal or Telnet messages ....................................... 123 Buffering of the Notification and Diagnostic Tabs ................................................................ 127

NetLinx Diagnostics - NetLinx Device Emulation .......................................................... 127 NetLinx Diagnostics - NetLinx Device Control............................................................... 129
Viewing Push Results .......................................................................................................... 130

NetLinx Diagnostics - Netlinx Device Addressing ......................................................... 131


Changing The Device/System Address On A Netlinx Device .............................................. 131 Restoring The Default Device and System Numbers On A Netlinx Device ......................... 132 Using ID Mode To Change The Device Address On a NetLinx Device ............................... 132

NetLinx Diagnostics - URL Lists.................................................................................... 133


Creating a URL List.............................................................................................................. 133

NetLinx Diagnostics - Network Addressing ................................................................... 134


Changing the System Number On a Netlinx Master ............................................................ 134 Changing the IP Address On a NetLinx Device Using DHCP.............................................. 134 Setting the DNS Address For a Netlinx Master.................................................................... 134 Setting the IP Address For a NetLinx Master....................................................................... 135 Changing the IP Address On a Netlinx Master (Use DHCP) ............................................... 135 Changing the IP Address On a Netlinx Master (Specify IP Address)................................... 136

NetLinx Studio (v2.4 or higher)

vii

Table of Contents

Setting NetLinx Time and Date ..................................................................................... 136 Rebooting the Master.................................................................................................... 137 Axcess/NetLinx Debugging ........................................................................................... 137
Debugging Source Code Files ............................................................................................. 137 Notes on Using Current Length (when the Total Length option is disabled):....................... 138 Master Controller Debug Options......................................................................................... 138 Changing The Value Of a Watched Variable ....................................................................... 139

Communications and File Transfers .................................................................. 141


Configuring Default Communications Settings.............................................................. 141 Configuring System-Level Communications Settings ................................................... 142 Configuring Terminal Communications Settings ........................................................... 143 Setting the Default Control Platform.............................................................................. 144 Changing The System Platform (Axcess / Netlinx) ....................................................... 144 Connecting To A Netlinx Master ................................................................................... 144
Configuring Virtual Netlinx Master Communication Settings (Netlinx Only)......................... 144 Connecting To a Netlinx Master Via TCP/IP ........................................................................ 145 Connecting To a NetLinx Master Via Serial Port.................................................................. 146 Connecting To A NetLinx Master Via Modem ...................................................................... 146 Connecting To A Secured Netlinx Master ............................................................................ 147 If you don't connect: ............................................................................................................. 148

Connecting To an Axcess Master ................................................................................. 148


Connecting To An Axcess Master Via Serial Port................................................................ 148 Connecting To An Axcess Master Via Modem..................................................................... 148

File Transfer Operations ............................................................................................... 149


File Transfers Edit Sub-Menu .............................................................................................. 150 File Transfer Status Information........................................................................................... 151 Canceling Transfers ............................................................................................................. 151 Transfer Errors And Definitions............................................................................................ 151

Step 1: Adding Files To The Transfer Queue ............................................................... 152


Using The Quick Load Dialog .............................................................................................. 152 Adding Files To The Files To Send Queue .......................................................................... 153 Adding All Files Contained In An APW Or AXW File ........................................................... 153 Adding Files From A Specific Project/system ...................................................................... 153 Adding Individual System Files From The Open Workspace File ........................................ 154 Adding Orphan Files ............................................................................................................ 154 Adding Files To The Files To Receive Queue ..................................................................... 155

Step 2: Communication Settings................................................................................... 156


Listening For Netlinx Masters On The Subnet ..................................................................... 156 Configuring Communications Settings ................................................................................. 156

viii

NetLinx Studio (v2.4 or higher)

Table of Contents

Configuring TCP/IP Communication Settings (Netlinx Only) ............................................... 156 Configuring Serial Communication Settings......................................................................... 157 Configuring Modem Communication Settings...................................................................... 157 Configuring Virtual Netlinx Master Communication Settings (Netlinx Only)......................... 158 Configuring the Panel For Virtual Netlinx Master TCP/IP Transfers .................................... 158

Step 3: Device Mapping ................................................................................................ 159


Setting Device-File Mapping Information ............................................................................. 159 Editing Device Mapping Information .................................................................................... 159

Step 4: Transferring the Files ........................................................................................ 159


Sending Files To System Devices ....................................................................................... 159 Receiving Files From System Devices................................................................................. 159 Receiving Files Directly From A System Device (Serial Connections Only) ........................ 160

Virtual NetLinx Master (Masterless) Transfers .............................................................. 160


Virtual Netlinx Master USB Transfers .................................................................................. 160 Configuring the Touch Panel for Virtual NetLinx Master USB Transfers ............................. 161 AMX USB Driver Information For USB Enabled G4 Panels................................................. 161 Configuring NetLinx Studio for Virtual NetLinx Master Transfers......................................... 162 Transferring Files Using A Virtual Netlinx Master Usb Connection...................................... 162 Virtual NetLinx Master TCP/IP Transfers ............................................................................. 163 Configuring The Touch Panel For Virtual Netlinx Master Tcp/ip Transfers.......................... 163 Configuring Netlinx Studio For Virtual Netlinx Master Tcp/ip Transfers ............................... 164 Transferring Files Using A Virtual Netlinx Master Tcp/ip Connection .................................. 164

Firmware Transfers ....................................................................................................... 165


Sending Firmware To a NetLinx Device (Kit File) ................................................................ 165 Sending Firmware To An Axcess Device (Tsk File)............................................................. 166

Netlinx Master Security ................................................................................................. 167


Enabling Security On Netlinx Masters.................................................................................. 167 Master Controller User Name and Password Dialog ........................................................... 168 Applying Security To Individual File Transfers ..................................................................... 168 Connecting To a Secured Netlinx Master ............................................................................ 169 If you don't connect: ............................................................................................................. 170

Tested Modems List ...................................................................................................... 170

Setting Program Preferences ..............................................................................171


Overview ....................................................................................................................... 171 Preferences Dialog - General Tab................................................................................. 171 Preferences Dialog - Axcess Compiler Tab .................................................................. 171 Preferences Dialog - Netlinx Compiler Tab ................................................................... 173 Preferences Dialog - Editor Tab .................................................................................... 174
Importing/Exporting Editor Preferences ............................................................................... 177

NetLinx Studio (v2.4 or higher)

ix

Table of Contents

Preferences Dialog - Commands Tab........................................................................... 177


Adding/Removing Commands From The Toolbars.............................................................. 177 Creating Custom Toolbars ................................................................................................... 178

Preferences Dialog - Toolbars Tab ............................................................................... 178 Preferences Dialog - Tools Tab .................................................................................... 178
Adding/Removing Application Shortcuts In The Tools Menu ............................................... 179

Preferences Dialog - Keyboard Tab.............................................................................. 179


Creating Custom Shortcut Keys........................................................................................... 180

Preferences Dialog - Menu Tab .................................................................................... 180


Customizing The Menus ...................................................................................................... 181

Preferences Dialog - Diagnostics Tab........................................................................... 182 Preferences Dialog - Terminal Tab ............................................................................... 183 Preferences Dialog - File Transfer Tab ......................................................................... 183 Preferences Dialog - Workspace Tab ........................................................................... 184

Troubleshooting ................................................................................................... 185


NetLinx Debugger Not Stopping On A Breakpoint ........................................................ 185
Symptoms ............................................................................................................................ 185 Cause................................................................................................................................... 185 Resolution ............................................................................................................................ 185

NetLinx Master Error - Device_ID Error ........................................................................ 186 Debug Option Disabled For Axcess Code File.............................................................. 186
Symptom .............................................................................................................................. 186 Cause................................................................................................................................... 186 Resolution ............................................................................................................................ 186

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)


Overview
NetLinx Studio v2 is a 32-bit Windows application that allows you to program and maintain entire control systems. NetLinx Studio fully supports both NetLinx and Axcess system programming. Beyond creating, editing and compiling source code in two programming languages (Axcess and NetLinx), NetLinx Studio makes it easy to manage all of the files associated with an entire control system (i.e. Master Source Code/Source Code (.AXS), Include (*.AXI) files, Module (.AXS or .JAR) files, IR (*.IRL/*.IRV) files, User Interface (.TPD, .TP4, .KPD), and Other (any file type) files) into one centralized location, as a System. To maintain multiple systems, one or more Systems can be organized within a larger Project. A Project can contain as many Systems as are required for a job. The Workspace Window organizes and displays all of these Project and System files in a logical hierarchical tree structure. To review a list of features that are new to this release, read the What's New document (opens by default on startup, or select Help > What's New to open). The on-line help program is designed to offer key information to help to learn about and use the NetLinx Studio program. Use the Table Of Contents on the left side of the help window to navigate to a particular help topic, or press the F1 key while any dialog is open to open the help topic associated with the active dialog. The Help menu also contains shortcuts to the Axcess and NetLinx Keywords help files. Each is a comprehensive listing of the commands included in each programming language. Additionally, you can view a brief description of each Axcess and/or NetLinx programming command by highlighting any reserved keyword in an open code file and pressing the F1 key. For example, highlight the reserved identifier "DO_PUSH" in a source code editor window and hit F1. A help topic describing the DO_PUSH keyword opens automatically. Use the Index and Search tabs to perform more detailed searches. Use the Browse Sequences to quickly browse related topics. Click the AMX.COM toolbar button to access the www.amx.com home page. Click the NetLinx Studio Online Help toolbar button to access an online version of this help file. The online version of the help will always contain the most recent information, including any possible updates.

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)

Supported Operating Systems and Minimum PC Requirements


Supported operating systems: Windows XP Professional (service pack 1 or greater) Windows 2000 (service pack 3 or greater)

You must have Administrator rights to install and run all required System files.

PC Requirements: Pentium 233 MHZ processor (minimum requirement); 300 MHZ or faster recommended. 75 MB of free disk space (minimum requirement); 150 MB recommended. 128 MB of installed memory (RAM). Minimum (VGA) screen resolution of 800x600. Other PC requirements: Windows-compatible CD-ROM drive. Windows-compatible mouse (or other pointing device).
If the mouse wheel on your Microsoft IntelliMouse doesn't' work with NetLinx Studio, try downloading the latest IntelliMouse drivers from Microsoft.

Supported File Types


NetLinx Studio supports the following file types for editing with the Source Code Editor:
Type Text files Source files Include files Block files Lib Files NetLinx Studio v1.2 Project files Extension *.TXT *.AXS *.AXI *.AXB *.LIB *.PJS

The following file types are supported, but are edited using external AMX applications, as described below:
Type TPD file Associated AMX Application Extension TPDesign3 *.TPD *.TP4 *.KPD *.IRL, *.IRV

TP4 files TPDesign4 KPD files KPDesign IR files IREdit

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)

NetLinx Studio will attempt to open all other file types (*.*) using the application already associated with that file type in Windows.

What's New Dialog


The "What's New" dialog is displayed when NetLinx Studio is launched. This dialog provides a (read-only) text file describing the features that are new to this release. To prevent this dialog from being displayed every time the program is launched, select the Don't Show Me Again option at the bottom of the dialog. This dialog can always be accessed via the Help > What's New option.

WebUpdate
The AMX WebUpdate program is a stand-alone application that communicates with the AMX website, allows a user to select from a list of available AMX Software programs to choose for updating, determines the latest version of the selected applications, returns a listing of available updates, allows a user to download the selected installation files, and upon request, launches the installation of those downloads.
The WebUpdate application is not installed by NetLinx Studio, and must be installed separately. If not found, NetLinx Studio will prompt you to download the application from www.amx.com.

Select Help > Web Update to launch this application. Refer to the WebUpdate on-line help for details and instructions.

Software History2 Application


The AMX Software History2 application provides the ability to display detailed information on AMX hardware and software. Click Tools > Software History to launch the application. Refer to the AMX Software History 2 Application on-line help file for details and instructions.

DIP Switch 2.0


DIP Switch 2.0 is an AMX application that graphically displays the dip switch settings necessary to address Axcess, NetLinx and TXC+ devices and configure communications settings. Click Tools > DIP Switch to launch the application. Refer to the DIP Switch 2.0 on-line help file for details and instructions.

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

The NetLinx Studio v2.4 Work Area


Overview
The NetLinx Studio work area contains the elements of the NetLinx Studio user interface. Before jumping into a project, take a few moments to familiarize yourself with the main user interface elements.

FIG. 1 The NetLinx Studio v2.4 Work Area

Title Bar
Displays the name of the application, and the name of the currently active file. An asterisk (*) after the file name indicates that it contains unsaved changes.

Toolbars
There are eight toolbars in NetLinx Studio. Hover the mouse cursor over any toolbar button (for about one second) to display a" tooltip" describing the button. Choose View > Toolbars to open the Toolbars sub-menu to view or hide the toolbars:

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Build toolbar Debug Watch toolbar Diagnostics toolbar Edit toolbar Project toolbar Standard toolbar Terminal toolbar Window Mgmt toolbar FIG. 2 Toolbars

See Also... The Adding/Removing Commands From The Toolbars section on page 177. The Creating Custom Toolbars section on page 178.

Menu Bar
The Menu Bar is located along the top of the application window, between the title bar and the toolbars. Click on any of the main menu items to open the associated drop-down menu.
If you are running NetLinx Studio in Windows 2000, NT or XP, you may have to press the ALT key to view the menu item hotkeys.

See Also... The Customizing The Menus section on page 181

Status Bar
Click View > Status Bar (or click the toolbar button) to toggle (hide/show) the Status Bar. The Status Bar displays general information, including communication status, a brief description of any option in the program, cursor location, last Push received, COM port currently being used, network IP address (NetLinx systems only) and current PC keyboard settings.

FIG. 3 Status Bar

The elements of the Status Bar are described below, from left to right:

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Program Status/Quick descriptions of program options - The far-left side of the status bar displays quick descriptions of program options anytime you position the mouse cursor over a toolbar button or menu item. This field also displays the total number of replaced instances resulting from a search & replace operation. Notifications Messages Status - Displays the status of NetLinx notification messages (OFF/ON). Diagnostics Messages Status - Displays the status of asynchronous notification messages (OFF/ON). Last Push Message and History - Displays the most recently received Push (if Push is enabled via the Diagnostics > Enable Push Message Status Bar Display command), or Push status (Push Enabled/Disabled). Left-mouse click on the push message displayed to view a history of push messages. Then, right-mouse click within the list box to view the available options. Master Controller Connection Information - Displays the name and status of the active communications port. If a TCP/IP connection exists, the current IP address is displayed. If Virtual NetLinx Master is selected, then the Virtual NetLinx Master is displayed with its System number. Master Security Status - Indicates the current security status for the Master (locked = Authentication Enabled, unlocked = Authentication disabled). Cursor Location - Displays the cursor's location in the active Source Code Editor window (line and column numbers). Keyboard Settings - When a file is open (in a Source Code Editor window), the three boxes on the far-right side of the status bar indicate the status of the following keyboard settings: OVR: Overwrite/Insert (OVR indicates that the keyboard is currently in overwrite mode - new characters will replace or overwrite existing characters in the Source Code Editor). CAP: Caps Lock (CAPS indicates that the keyboard is currently in Caps Lock mode - all letters typed will appear in upper case. NUM: Number Lock (NUM indicates that the 10-key number/arrow keypad is set to type numbers - arrow functions are disabled).

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Workspace Window
Use the Workspace Window (FIG. 4) to manage Project files, System files and online devices. The Workspace Window contains two tabs (Workspace and Online Tree), which display all open Workspace files (containing Projects and their associated System files), and all devices currently on-line, in a tree structure.

FIG. 4 Workspace Window (by default, displays the Workspace tab)

Click View > Workspace (or click the toolbar button) to toggle (show/hide) the Workspace window. Right-click inside the menu bar or menu area to display the View Control Context Menu, where you can select to hide or display the NetLinx Studio toolbars. Workspace Window - Workspace Tab The Workspace tab contains a tree structure of all the available Projects (and Systems) contained within a Workspace file. You may create multiple Projects within a Workspace. Within a Project, you can create multiple Systems. The Workspace view can be expanded to show all of the various elements within each opened Project file, as shown below. The first level within the open Workspace is the Project folder level. The next level is the System(s) contained within the Project, each represented by a System folder. The third level contains the System File folders (Source, Include, Module, User Interface, IR and Other).

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

The 'Module' folder only appears if NetLinx is designated as the system platform (via the Communication Settings dialog).

The fourth level contains all of the actual files that make up the System (.AXS, .AXI, .TPD, .TKO, .TP4 .IRL/.IRV, and *.*). The fifth and final level indicates the file mapping information for each file, as applicable.

FIG. 5 Workspace Window - Workspace Tab

Click on the "+" folder flags to expand the folders to expose any subfolders; click the "-" folder flags to collapse the folders. The hierarchical file structure of the Workspace tab is described below: Workspace Folder You can have one Workspace open at a time. A Workspace contains at least one Project, and each Project contains at least one System. Right-mouse click anywhere within the workspace tab to open the Workspace context menu. Project Folders Right-mouse click on any Project folder to open the Project Folder context menu. Expand any Project folder to display the System folder(s) contained in that Project. System Folders Each System has it's own platform (Axcess or NetLinx) setting along with the communication information (i.e. IP address or COM port setting with the appropriate baud rate, etc.). Right-mouse click on any System folder to open the System Folder context menu.

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Expand any System folder to display the six System File folders contained in that System (Source, Include, Module, User Interface, IR and Other). System File Folders Expand any System File folder to display the System File(s) contained in that folder. Right-click on any System File folder to open the System File Folder context menu associated with that folder type. System Files Right-mouse click on any System File to open the System File context menu associated with that file type. Double-click any code file (Master Source Code, Source Code, Module or Include) to open that file for viewing and/or editing in a Source Code Editor window. Double-click any TPD file to open the TPDesign3 program (if it is installed). Double-click any TP4 file to open the TPDesign4 program (if it is installed). Double-click any KPD file to open the KPDesign program (if it is installed). Double-click any IR file to open the IREdit program (if it is installed). When you add a file to a System (Project > Add File To System), the file is automatically placed (as a link) in the appropriate System File folder, based on it's file type. You cannot have the same file referenced more than once within a system (i.e. cannot add the same file name to the Source folder and the Other folder within the same System). File Mapping Information Any file that has device-file mapping information associated with it is represented in the Workspace tab with a "+" flag. Click on the "+" symbol to expand the view to indicate the File Mapping Information. Other key functions and features of the Workspace tab include: You can drag and drop files from Explorer into the appropriate sub-folders within a System. All files are linked files associated with a system, not copies of files from one location to another. For the TPD/4, IR files and other source code files, you have the ability to map multiple devices to the selected file. The Master Source Code file will always be mapped automatically to device address 0:1:0 for NetLinx masters or 0 for Axcess masters. You have the ability to copy a selected System folder to paste into another or the same Project folder. You have the ability to designate a single source code file as the Master Source Code file.

10

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Right-click on any open area inside the Workspace tab to open the Workspace Window Context Menu. Workspace File Context Menu Right-click on the Workspace file (in the Workspace tab of the Workspace Window) to open the Workspace File context menu. This context menu contains various Workspace file-level commands and options, including:
New Workspace Closes the currently open Workspace file, and starts a new (empty) workspace (no Project/System associated until you add them manually). Launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project/System. Opens the Open Workspace dialog, where you can locate and select an existing Workspace (.APW) file. You can have only one Workspace open at any time, so in the event that you have a Workspace open, it will be replaced by the one you open. Closes the Workspace file. The program prompts you to close the files associated with the Workspace before closing them. Saves the Workspace file, under its current name and location. Opens the Save Workspace As dialog, where you can specify a new name and/or location for the saved Workspace file. Builds (compiles) the Workspace (including all contained Projects). The progress and results of the build can be viewed in the Status tab of the Output Display window. Opens the Export Workspace File To Go dialog, where you can export the Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace making them ideal for distribution to remote sites. Opens the Select AXW File dialog, where you can select a previously exported "To Go" (AXW) file to import into the program. Opens the New Project Properties dialog, which allows you to assign an Identifier and general properties for a new Project. Once created, the new project is added to the Workspace. Opens the Open Workspace dialog, where you can locate and select a Workspace (.APW) file. This invokes the Import Components From a Workspace dialog. Use the dialog to select a specific Project contained in the Workspace. You can copy and paste Projects by selecting Copy Project from the Project Folder context menu, and selecting the Paste Project command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).

Workspace Wizard Open Workspace

Close Workspace Save Workspace Save Workspace As Build Workspace

Export Workspace Files To Go

Import From Exported Workspace File New Project

Import a Project

Paste Project

Collapse Tree

Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking view Hide Quick Load Workspace Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option allows you to access the File Transfer dialog, already configured to send all files in the Workspace (active Project/System only) to the Master associated with the active System. Opens the Workspace Properties dialog, where you can view the basic properties of the open Workspace. The options in this dialog also allow you to edit the Workspace Identifier and Description.

Workspace Properties

NetLinx Studio (v2.4 or higher)

11

The NetLinx Studio v2.4 Work Area

Workspace Window - Online Tree Tab The Online Tree tab of the Workspace Window (FIG. 6) displays an Online Device tree for either the NetLinx or Axcess Master Controller. This tab displays a list of devices detected to be currently online by the Master Controller (and the firmware version for each). The Device Tree also provides port status information for each device.

FIG. 6 Workspace Window - Online Tree Tab

Refer to the Working With the Online Device Tree section on page 116 for more information.

Output Display Window


Select View > Output (or click the toolbar button) to toggle (show/hide) the Output Display window (FIG. 7).

FIG. 7 Output Display Window (by default opens to the Status tab)

12

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

There are 6 tabs contained in the dockable Output Display window:


Status Tab The Status tab displays build information pertaining to the last compilation of source code files, as well as port status information. Double click on a line containing an compiler error message to open the file in a Source Code Editor window, with the cursor positioned at the beginning of the line containing the indicated error. Note: The version number of the compiler (NetLinx or Axcess) is displayed in the Status tab, whenever source code is being compiled. Find In Files tab The Find In Files tab displays the results of a Tools > Find In Files search operation. Right-mouse click in the view to see the available options to save or copy the contents of this list. Find IR Files tab The Find IR Files tab displays the results of a Tools > Find IRL/IRV search operation. To add one or more of the listed IR files to a System in the open Workspace, select a file (or Ctrl + click to select multiple files), then drag and drop the file(s) into the System folder of the System that you want to add the file(s) to. This invokes the File Properties dialog, where you can change the Identifier, File Name and Description for each file that you are adding to the System. Double click on a listed file to open it for viewing/editing in the IREdit utility program. File Transfer Status tab The File Transfer Status tab of the Output Display Window displays the status on the list of files that are have been or are being transferred. Notifications tab The Notifications tab displays several types of auto-notification messages from one or more specified NetLinx devices. See the NetLinx Diagnostics - NetLinx Device Notification section on page 121 for details. Diagnostics tab The Diagnostics tab displays internal system diagnostics messages sent by the NetLinx master controller

Right-click inside any of the Output Display window tabs to access the Output Display window context menu. Output Display Window Context Menu Right-click inside any of the Output Display window tabs (Status, Find In Files, Find IR Files, File Transfer Status, Notifications or Diagnostics) to open the Output Display window context menu.

As indicated, some of the options below are not relevant to all tabs.

The options in this menu include:


Enable/Disable Asynchronous Notifications (Notifications tab only) Enable/Disable Diagnostics Messages (Diagnostics tab only) Copy All Items Copy Selected Items Stops or starts the asynchronous notifications messages that are sent by the NetLinx master controller without visiting the menu bar. Stops or starts the internal system diagnostics messages that are sent by the NetLinx master controller without visiting the menu bar. Copies all items in the list to the clipboard. Copies only the selected items in the list to the clipboard.

NetLinx Studio (v2.4 or higher)

13

The NetLinx Studio v2.4 Work Area

Save All Items Save Selected Items

Saves all items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Saves only the selected items to a user-defined file. You will be prompted for a file name to save the contents of the tab.

Compiler Error /Warning Report This option scans the contents of the Status tab, and then lists each compiler error and warning (one per line) in the Status tab. This option invokes the Compiler Error Warnings Report dialog, which allows you to specify wether you want to include compiler Errors, Warnings or both in the report. By default, Errors and Warnings are both selected. Find (Notifications and Diagnostics tabs only) Search for text within the tab, via the Find dialog. You may search up or down the tab based on the current cursor location within the tab. The search can be case sensitive. When the text is found in the tab, the program highlights the row and scrolls the row into view. Clears all the items within the list.

Clear

File Transfer Tab Context Menu Right-click on any item listed in the File Transfer Status tab of the Output Display window to access the File Transfer Tab Context Menu:
Copy All Items Copy Selected Items Save All Items Save Selected Items Clear Copies all items in the list to the clipboard. Copies only the selected items in the list to the clipboard. Saves all items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Saves only the selected items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Clears all the items within the list. WARNING: Canceling during a file transfer may leave the target device in an unstable state. Cancel Selected Transfer Items Cancel Remaining Transfer Items Cancel All Transfer Items Cancels only transfer items that have been selected (highlighted). Cancels all remaining transfers in the list, but allows the current transfer to complete. Cancels all transfer items in the list, including the current one (if applicable).

Cancel Current Transfer Cancels the current transfer.

Output Display Window - Notifications Tab The Notification tab of the Output Display Window displays the asynchronous notification messages being received from the master controller. You can right-mouse click in the tab to see the available options to save or copy the contents of this list. Output Display Window - Diagnostics Tab The Diagnostics tab of the Output Display Window displays all internal system diagnostic messages that are generated by a NetLinx master controller. You can right-mouse click in the tab to see the available options to save or copy the contents of this list.

14

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Source Code Editor Windows


Use Source Code Editor windows (FIG. 8) to display, view and edit Axcess and NetLinx source code files. You can have multiple files open at any time. Each code file is opened in a separate Source Code Editor window.

FIG. 8 Source Code Editor Window

Use the Source Code Editor windows to generate and edit Axcess and/or NetLinx code files.
NetLinx Studio features a Code Wizard that steps you through the process of generating several different types of code.

Do not attempt to open .LIB or .SYC files for editing in the Source Code Editor. Doing so could cause program failure.

Source Code Editor Window - Features Source Code Editor window features include:
Unicode Characters Select Unicode Edit from the Edit menu, or the Source Code Editor Context Menu (right-click inside the editor window to access) to open the Enter Text... dialog which allows you to insert unicode characters in your code, at the cursor position in the editor.

NetLinx Studio (v2.4 or higher)

15

The NetLinx Studio v2.4 Work Area

Code folding

Fold levels can be used to simplify the view in the Source Code Editor windows by allowing you to "fold" each major section of the code (DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) so that only the header row is visible. This way, you only see the section(s) that you are actually working in. In order to use fold levels, you must first enable the option in the Editor tab of the Preferences dialog (by default, this option is disabled). As you type in a variable name, device name or a language reserved word, the program will suggest a name that has been previous defined within the source code (this option is toggled on and off in the Preference dialog - Editor Options tab). Press the Tab key to incorporate an Auto-Suggest. The text in the Editor windows is syntax highlighted for increased readability with a default set of colors. Use the options in the Editor Options tab of the Preferences dialog to customize various aspects of the Source Code editor windows (i.e. syntax highlighting, auto-indent, show/hide line numbers and clipboard text buffer settings). Note: Syntax highlighting assigns different colors to different types of data in your Source Code file. Use syntax highlighting to make your code easier to read and manage. For example, you could syntax highlight all comments to yellow, all identifiers to red and strings to blue to make them more easily identifiable in your code file.

Auto-suggest and Auto-complete functionality

Syntax Highlighting

Drag and drop Support

Drag and drop any supported file type from Explorer into the Source Code Editor to open that file in a new Source Code Editor window. Drag and drop selected text to another Editor window (at the cursor location), or to another location within the same Editor window.

Floating Window

Source Code Editor windows are moveable and resizeable. Use the options in the Window menu to arrange (cascade or tile) multiple windows. Use the New Window option in the Window menu to open the same code file in multiple Editor windows. This feature allows you to view and edit different locations in a large code file. Right-click anywhere within a Source Code Editor window to open the Source Code Editor context menu. Hold down the Alt key and select text with the left mouse button for columnar Cut, Copy, and Paste operations. Use the Edit > Insert Section option to insert a (empty) section of code at the cursor position. Use the Edit > Goto Section option to move the cursor to the beginning of a selected section of code in the active Editor window. The Edit > Undo and Redo commands allow unlimited Undo/ Redo operations. Use the Edit > Make Selection Uppercase and Make Selection Lowercase commands to automatically change the case on a selection of text.

Windows > New Window

Source Code Editor context menu Columnar Cut, Copy and Paste Insert Section Goto Section

Undo and Redo Make Selection Uppercase and Make Selection Lowercase

Sequentially Renumber Selection Use the Edit > Sequentially Renumber Selection command to sequentially renumber selected number text in the active Editor window. Block Comment-Uncomment The Edit > Block Comment-Uncomment option allows you to block comment-uncomment selected text in the active Editor window.

16

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Indentation Other Features include:

To indent a block of text, select text and press the Tab key. Use Shift + Tab to remove the indentation. Multiple clip-board buffer capabilities. Ability to print an entire file. Mouse wheel support.

Terminal Window
NetLinx Studio provides a terminal interface to NetLinx and Axcess devices that support an interactive terminal mode. Select Tools > Terminal (or click the toolbar button) to invoke the Terminal Window. Key features of the Terminal window (accessible through the Terminal window context menu) are described below: Paste operations - Text data contained in the clipboard can be pasted into the terminal window. However, text can only be pasted when the Terminal window is connected (online), and only the first line of text in the clipboard will be pasted.
All characters pasted in the Terminal window are not pasted into the window directly, regardless of the current position of the caret. Rather, they are sent out the port to the device just as if they had been typed directly from the keyboard. This means that you will not necessarily see the text that was pasted unless echoing is currently enabled on the device. Also, carriage-return characters are not appended to the pasted text (even if the clipboard text contains one). You must press the return key to enter a pasted command.

Terminal communication settings - The Terminal window has it's own dedicated communications settings. Refer to the Master Communication Settings help topic for information on configuration of the Terminal communication settings. The Terminal window does not support: Cut operations. Editing operations within the window, other than to input characters at the cursor (the text in the terminal window actually reflects what has been received from the device. Text that is typed in the window will not appear unless echoing is currently enabled on the device). Using The Terminal Window Select Tools > Terminal (or click the toolbar button) to open the Terminal window. The Terminal window puts the Master Controller into dumb terminal mode. Anything that is typed on the screen exits through the Master communications port, and anything coming in from the communications port is displayed in the Terminal window. Use the Terminal window to communicate directly with the Master Controller and to debug RS-232-controlled devices. You cannot use the Terminal window while a communication port is in use for a file transfer or debug operation. Type "ECHO ON" in the Terminal window to display messages. If the Terminal window becomes unresponsive, close and re-open the window. To leave the Terminal Emulator window active for a long session, click the Terminal Locks the Port option in the General tab of the Preferences dialog.

NetLinx Studio (v2.4 or higher)

17

The NetLinx Studio v2.4 Work Area

Use the Terminal Options tab of the Preferences dialog to modify the behavior and change the appearance of the Terminal window. To use the Terminal window with NetLinx systems, you must be connected to the Master via the PROGRAM port. Otherwise, you can use Windows TelNet for terminal control of NetLinx systems. Terminal Window Context Menu Several of the key functions of the Terminal Window are accessible via the Terminal Window context menu. To open this context menu, right-click inside the Terminal Window. The options include:
Display Clear Save To File Disconnect Click to open the Display sub-menu, which contains view options for the Terminal Window. The options are ASCII, HEX (hexadecimal) and DEC (decimal). Clears the contents of the Terminal Window. Opens the Save As dialog, which allows you to save the contents of the Terminal Window as a text file (.txt). Disconnects the Terminal. The terminal window background turns a light shade of gray, to indicate that it is disconnected.

Last commands At the bottom of this menu is a list of the last commands entered. Use the items in this list as shortcuts to recently used commands.

Watch Window
The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of specified variables within a compiled Axcess or NetLinx program. Also, you can control the execution of the mainline of a compiled Axcess or NetLinx program. The Watch window contains three tabs (Watch1-Watch3), which allow you to watch up to three separate sets/ lists of specified variables. The Watch window consists of a table with four columns:
Name Enter the name of the watched variable in this column.

Line (NetLinx only) Enter line number (in the Source Code file) where the variable is declared. Length Value Display This column displays the length of the watched variable. This column displays the value of the watched variable. This column displays the format of the variable (ASCII, Decimal, Hexadecimal, Octal, ASCII or Binary).

You can also drag and drop a variable from the Source Code Editor window into the debug window.

Right-click inside the Watch Window to access the Watch Window context menu.

18

NetLinx Studio (v2.4 or higher)

The NetLinx Studio v2.4 Work Area

Watch Window Context Menu Right-click inside the Watch Window to access the Watch Window context menu, described below:
Refresh List Add Variable Refreshes the contents of the Watch Window. Opens a text field in the Name column, to allow you to add a variable to the Watch Window.

Add Variable From List Opens the List of Watched Variables dialog, where you can select a variable to add to the Watch Window from a list of all variables located in the TKN file of a compiled NetLinx source code file. Delete Variable Delete All Variables Total Length Deletes the selected variable from the Watch Window. Deletes all variables from the Watch Window. Sets the viewing mode for arrays to show the total length of the array in the Length column of the Watch Window. All of the locations of the array are displayed, regardless of the Current Length value of the array. By default, this option is enabled. When disabled, the viewing mode shows Current Length in the Length column. Toggles the step mode between Run and Single Step mode. In NetLinx systems, this command executes a single instruction in the source file; in Axcess systems, it executes a single line of code in the Mainline.

Step Mode Single Step

NetLinx Studio (v2.4 or higher)

19

The NetLinx Studio v2.4 Work Area

20

NetLinx Studio (v2.4 or higher)

Using NetLinx Studio

Using NetLinx Studio


The Netlinx Studio Workspace Wizard
A key feature of NetLinx Studio (v2.x) is the Workspace Wizard. The Workspace Wizard quickly steps you through the process of creating a new Workspace, with a Project and a System. Using the Workspace Wizard The NetLinx Studio Workspace Wizard provides an quick and easy way to create a new Workspace (.APW) file with one Project and one System. It presents a series of dialogs, which allow you to enter workspace information based on specific questions. 1. To start the Workspace Wizard, select File > New (or click the toolbar button). 2. In the New dialog, select Workspace Wizard and click OK. 3. In the Workspace Wizard dialog, enter a name (up to 128 characters) for the new Workspace file in the text field (required). To enter an optional text description for the new Workspace, click the Workspace File Description button, and enter the description in the Workspace File Description dialog (2000 characters max). Click OK to return to the Workspace Wizard dialog. 4. Click Next to proceed to the Workspace File Location dialog. 5. Specify the target location for the Workspace file in the text field, or click the Browse button (to the right of the text field) to locate and select a target directory via the Browse For Folder dialog. 6. Click Next to proceed to the Project Identifier dialog. 7. Enter an identifier (name) for the new Project in the text field. To enter additional information for the new Project, click the Project Information button, and fill in the Project Information (up to 128 characters) and Description (up to 2,000 characters) text fields in the Project Information dialog (all fields in this dialog are optional). Click OK to return to the Project Identifier dialog. 8. Click Next to proceed to the System Type dialog. 9. Use the radio buttons to select which type of System to add to the Project (NetLinx or Axcess). This dialog also includes the option to add the System later, in which case the Workspace Wizard is complete. Select either NetLinx or Axcess and click Next to proceed to the System Information dialog. 10. Enter a name for the new System in the text field. To enter an optional text description for the new System, click the Workspace File Description button, and enter the description in the System Description dialog (2,000 characters max). Click OK to return to the System Information dialog. 11. Click Next to proceed to the Assign System ID dialog. 12. To associate a System ID to the new System, enter the System ID in the text field. By default the ID is set to zero (0 = this System).

NetLinx Studio (v2.4 or higher)

21

Using NetLinx Studio

13. Click Next to proceed to the System Communications dialog. This dialog displays the current Master Communication Settings in a read-only text box. 14. Click Communication Settings to set the communication settings for this System, in the Communication Settings dialog.
These settings become the default communication settings for all new Workspace files, until they are manually changed.

15. Click Next to proceed to the Master Source Code File Selection dialog. 16. Use the radio buttons to select the type of Master Source Code file to create for this System: Create an empty AXS File - This option generates an AXS file that is totally empty (no templates used): a. Click Next to proceed to the Master Source Code File Name dialog. b. Enter a name (up to 128 characters) for the new (empty) Master Source Code File. c. Click Source Code File Description to enter a description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Master Source Code File Name dialog. d. Click Next to proceed to the New File Location dialog. e. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog). f. Click Next to complete the Wizard. Add an existing AXS File to the System - This option adds an existing AXS file to the System as the Master Source Code File: a. Click Next to proceed to the Existing Master Source File Location dialog. b. Enter a path and filename of the desired Master Source Code File, or click the Browse button to locate and select the desired AXS file via the Open dialog. c. Click Source Code File Description to enter an optional description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Existing Master Source File Location dialog. d. Click Next to complete the Wizard. Create an AXS File using Templates - This option generates an AXS file using either the NetLinx or Axcess template, depending on the System type specified in Step 9. This option results in a Source Code file that is formatted with header/footer information and all of the main sections of a typical Source Code File of the selected type: a. Click Next to proceed to the File Template dialog. b. Enter a name (up to 128 characters) for the new Master Source Code File. c. Click Next to proceed to the New File Location dialog. d. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog).

22

NetLinx Studio (v2.4 or higher)

Using NetLinx Studio

e. Click Source Code File Description to enter an optional description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Master Source Code File Name dialog. f. Click Next to proceed to the New File Location dialog. g. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog). h. Click Next to complete the Wizard. Add the Master Source Code File Later - This option allows you to exit the Workspace Wizard at this point, and manually specify the System's Master Source Code File later. 17. In the Wizard Completed dialog, click Finish to exit the Wizard. The new Workspace (with your new Project containing the new System) is represented in the Workspace tab of the Workspace Window. Building the Workspace One advantage to the Workspace concept employed by NetLinx Studio (v2.0 or later) is that you can choose to build (compile) the entire Workspace. That is, every Source Code, Include, and Module file contained within the open Workspace can be compiled with a single command: Build Workspace. There are several ways to access the Build Workspace command - via the Build menu, the Workspace context menu (in the Workspace tab of the Workspace Window), or via the toolbar button. To compile the open Workspace: 1. Select Build > Build Workspace (or click the toolbar button). Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window.

The Netlinx Studio Code Wizard


Select Tools > Code Wizard to launch the NetLinx Studio Code Wizard. The Code Wizard consists of a series of dialogs that help you quickly generate various types of Axcess and NetLinx code segments. The wizard can help construct the following type of code segments: Button Events Channel Events Level Events Data Events Send Commands IR Constants

NetLinx Studio (v2.4 or higher)

23

Using NetLinx Studio

The Code Wizard can be toggled to display individual dialogs for all the above functionality, for use by advanced users. When the Wizard generates a new code segment, it is automatically inserted in the active Source Code file, in the appropriate section of the code.

Refer to Using The Code Wizard section on page 78 for details.

24

NetLinx Studio (v2.4 or higher)

Working With Workspace Files

Working With Workspace Files


Overview
NetLinx Studio utilizes a new concept for working with multiple projects/files simultaneously: the Workspace file. A Workspace represents at least one Project (containing at least one System), however a Workspace can contain multiple Projects. Each Project in turn can contain multiple Systems. At any time, you can create a Workspace file (via the File > Save Workspace option). Once created, you can re-open that Workspace file to recall the NetLinx Studio workspace, exactly as it was when the Workspace file was created. All Workspace information is saved in an XML formatted file with the .APW file extension.
The File > Save Workspace command only saves the Workspace (APW) file itself, and does not save changes made to the System files contained in the Workspace. Use the File > Save All command to save the Workspace file and all of the System files it contains.

One advantage of the Workspace file is that it serves as a time-saver: Once you have saved a Workspace file, (containing a particular set of Projects, Systems and System Files), the next time you open the application, you can simply open the single Workspace file (File > Open Workspace) to load the Projects/Systems it contains. This way you bypass the need to open each Project, System and System File individually. All Projects and associated Systems and System files are linked to the Workspace, so that you can add and remove Projects and Systems without having to make copies of the files. NetLinx Studio also allows you to copy and paste Projects within the Workspace; in the case that you need to create several similar Projects you can quickly generate multiple Projects and modify each one as necessary.
Since all System files are linked to the Workspace, when you open a file for editing, you are opening and editing the actual file, not a local copy. It is important to understand that in the event that the file is linked to multiple Systems, any changes made to the file will be reflected in every instance that the file is used (not just the System that you were in when the changes were made). Even if you don't have multiple links to the same file, you should still be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.

Workspace files also allow you to build (compile) multiple Projects/Systems. The Build Workspace command compiles every file contained in the Workspace. It is important to note that in NetLinx Studio (v2.0 and later), there is no concept of Projects outside the context of a Workspace. A Project can only be opened by adding it to a Workspace. This is to support the file linking aspect of the program.

NetLinx Studio (v2.4 or higher)

25

Working With Workspace Files

Other features of the Workspace file include: You can import other Project or Systems folders from previously saved Workspace files. You can copy and paste existing Projects and Systems within a Workspace. You can edit the identifier that is used to display the workspace name in the tree display along with the description for the Workspace file via the Workspace Properties dialog. You can export all the files associated with the Workspace (including the Workspace file) into a .ZIP file. Opening Workspace Files 1. Select Open Workspace from the File menu or the Workspace context menu (or click the toolbar button) to open the Open Workspace dialog. 2. Use the options in this dialog to locate and select a Workspace (.APW). 3. Click Open to open the selected Workspace file.
Since you can only have one Workspace open at a time, the program will prompt you to save any changes before closing the active Workspace and opening the selected one.

Creating New (empty) Workspace Files To create a new empty Workspace: Right-click on the Workspace folder to access the Workspace context menu, and select New Workspace. Before the new Workspace is created, the program will prompt you to save any changes made to the currently open Workspace (if applicable). A new Workspace file is created. As indicated in the Workspace tab, this Workspace contains no Projects/Systems. All Projects/Systems and associated files must be added manually.

To create a new Workspace with a Project and System, use the Workspace Wizard.

Import an Existing Project You can import existing Projects into the active workspace, via the Import a Project option in the Workspace context menu. To import an existing Project into the active Workspace: 1. Right-click on the Workspace folder (in the Workspace tab of the Workspace window) and select Import a Project from the Workspace context menu. 2. In the Open Workspace dialog, locate and select the Workspace (.APW) file that the Project you want to import currently belongs to.

The same Project can be included in more than one Workspace file.

26

NetLinx Studio (v2.4 or higher)

Working With Workspace Files

3. In the Import Components From a Workspace dialog, use the check boxes to select which Project(s) contained in the specified Workspace file to import. 4. Click OK.
If the selected Project(s) contain any identifiers that are already being used by the target Workspace, the program prompts you to change them. In this case, use the Import Name Change dialog to specify a new identifier for the imported Project.

5. The specified Project(s) should now appear as part of the open Workspace. Copying and Pasting Projects One advantage to the concept of Workspaces is that you can easily copy and paste Projects (and all of the associated Systems and System Files) within a Workspace. This allows you to develop a core Project which you can then copy, paste and modify as necessary. In cases where there are only minor variations from one Project to the next, this can be a real timer-saver. To copy and paste a Project (within a Workspace): 1. Open a Workspace (in the Workspace tab of the Workspace Window) and click to select (highlight) a Project folder. 2. Right-click on the Project folder and select Copy Selected Project from the Project Folder context menu. 3. Right-click on the Workspace file, and select Paste Project from the Workspace context menu. Deleting A Project From The Workspace When you "delete" a Project from the open Workspace, no System files are actually deleted from the hard drive; the Project is simply removed from the open Workspace. To delete a Project from the Workspace: 1. Click to select the Project that you want to remove (in the Workspace tab of the Workspace Window). 2. Select Delete Project from the Project menu, the Project Folder context menu, or click the toolbar button. 3. The program prompts you to confirm removing the selected Project. 4. Click Yes to remove the Project. Importing Projects Into A Workspace You can import existing Projects into the active workspace, via the Import a Project option in the Workspace context menu. To import an existing Project into the active Workspace: 1. Right-click on the Workspace folder (in the Workspace tab of the Workspace window) and select Import a Project from the Workspace context menu. 2. In the Open Workspace dialog, locate and select the Workspace (.APW) file that the Project you want to import currently belongs to.

NetLinx Studio (v2.4 or higher)

27

Working With Workspace Files

The same Project can be included in more than one Workspace file.

3. In the Import Components From a Workspace dialog, use the check boxes to select which Project(s) contained in the specified Workspace file to import. 4. Click OK.
If the selected Project(s) contain any identifiers that are already being used by the target Workspace, the program prompts you to change them. In this case, use the Import Name Change dialog to specify a new identifier for the imported Project.

5. The specified Project(s) should now appear as part of the open Workspace. Saving The Workspace Click File > Save Workspace (or click the toolbar button) to save the Workspace using the current filename and identifier. Select File > Save Workspace As to save the file under a new name. If you save the Workspace under a different name, the program will ask you wether you want to change the Workspace Identifier (the name that appears at the top of the Workspace tab of the Workspace Window) to match the new filename. Exporting Workspace Files For Distribution The Export Workspace Files To Go option in the Project menu allows you to export the open Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace, making them ideal for distribution to remote sites. As is indicated in this dialog, there are three major points to understand when exporting your Workspace files: All files will reside in the same directory as the APW file upon extraction of the AXW file. No directory/path information is required for the "To Go" APW File Name. You may enter non-existing folders and the program will create them for you. 1. Select Export Workspace Files To Go from the Project menu, the Workspace context menu, or click the toolbar button to open the Export Workspace Files To Go dialog. 2. By default, the name and target directory of the AXW file to be created matches the name of the open Workspace file. Use the Name of the "To Go" File text field to change the name and target directory for the resulting AXW file, if desired. Use the Browse button to navigate to a different folder. 3. By default, the name and target directory of the APW file to be created (and included in the AXW "To Go" file) matches the name of the open Workspace file, with "_Exported" appended to the end (for example "NetLinx Boardroom.APW" becomes "NetLinx Boardroom_Exported.APW" once it is extracted from the AXW file). Use the "To Go"

28

NetLinx Studio (v2.4 or higher)

Working With Workspace Files

Workspace Filename To Create text field to change the name and target directory for the resulting AXW file, if necessary. 4. Use the radio buttons in the Export Options area of the dialog to specify exporting the Full Workspace (all Projects and Systems included), or only the currently active Project (Only Active Project) or the currently active System (Only Active System). By default, the program is configured to export the entire Workspace file. 5. Use the checkboxes in the Export Options area to select additional options as desired: Select the Include User IRN Database(s) checkbox to include any user-defined .IRN (IR database) files in the resulting AXW file. If the selected Workspace file does not include any user-defined IRN files, this option is disabled. Select the Include Module Files that are not part of the Workspace checkbox to include AXS (*.TKO) and Duet (*.JAR) Module files that are needed for a successful NetLinx compile and link, but have not been added to the Workspace. Module files are found by searching the "Module Files" directories defined on the NetLinx Compiler tab of the Preferences dialog. If the selected Workspace file does not utilize Module files, this option is disabled. Select the Exclude All Source Code/AXS and Duet Module Files checkbox to exclude source code and Duet module files from the resulting AXW file. Excluding AXS/AXI files will result in device mappings of the exported AXW file to be set to "Custom". Since no source files will be part of the exported AXW, all device mappings will need to be resolved in the newly created APW file. Naturally, the previous two options are mutually exclusive. If you select one, the other is disabled. Select the Include the Compiled TKN/TOK File checkbox to include the compiled TKN/TOK file in the exported APW file. Select the Include the Complied SRC File checkbox to include the compiled SRC file (in addition to the compiled TKN/TOK file). Note that this option is only enabled if the Include the compiled TKN/TOK file option is selected. The Progress bar indicates the progress of the export operation. Once the export operation is done, detailed results of the operation are listed in the Export Workspace Files Report dialog. Importing Exported ("To Go") Workspace Files 1. Select Project > Import From Exported Workspace File (or click the toolbar button) to access the Select AXW File dialog. 2. Locate and select the desired AXW file, and click Open. 3. In the Import From Exported Workspace File dialog, the file selected in the Select AXW File dialog is listed in the AXW File to Extract From field. Use the browse button to locate and select a different file, if necessary. 4. The target directory indicated in the Extract To field matches the source directory for the selected file by default. Use the browse button to locate and select a different target directory for the Workspace file, if necessary.

NetLinx Studio (v2.4 or higher)

29

Working With Workspace Files

5. Click Extract to extract the selected Workspace file to the specified directory. If a file of the same name already exists in the target directory, the NetLinx Studio Extraction Overwrite dialog prompts you to either overwrite the existing file (Yes or Yes To All), to preserve the existing file (No), or to cancel the operation. 6. Once the file is extracted, the Workspace file is automatically loaded, and is represented in the Workspace tab of the Workspace Window.
If a Workspace file is open when the file is extracted, the program prompts you to close the currently open Workspace, as well as any associated System files.

Viewing and Editing Workspace Properties Use the Workspace Properties dialog to view and/or edit general properties of the open Workspace. To access this dialog, select Workspace Properties from the Project menu, the Workspace context menu, or click the toolbar button. You can edit the Identifier and Description fields, but the File Name and Creation Date are readonly.
Identifier File Name Description Creation Date The Workspace Identifier can have a maximum of 128 characters. The File Name cannot be changed and is only for display. The Description text is optional and can have a maximum of 2,000 characters. This read-only field indicates the creation date of the open Workspace.

Conversion Date If a NetLinx Studio v2.0 (or higher) workspace file was converted from a NetLinx Studio v1.2 *.PJS file, the Conversion Date will also be displayed.

Workspace File Context Menu Right-click on the Workspace file (in the Workspace tab of the Workspace Window) to open the Workspace File context menu. This context menu contains various Workspace file-level commands and options, including:
New Workspace Closes the currently open Workspace file, and starts a new (empty) workspace (no Project/System associated until you add them manually). Launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project/System. Opens the Open Workspace dialog, where you can locate and select an existing Workspace (.APW) file. You can have only one Workspace open at any time, so in the event that you have a Workspace open, it will be replaced by the one you open. Closes the Workspace file. The program prompts you to close the files associated with the Workspace before closing them. Saves the Workspace file, under its current name and location. Opens the Save Workspace As dialog, where you can specify a new name and/or location for the saved Workspace file. Builds (compiles) the Workspace (including all contained Projects). The progress and results of the build can be viewed in the Status tab of the Output Display window.

Workspace Wizard Open Workspace

Close Workspace Save Workspace Save Workspace As Build Workspace

30

NetLinx Studio (v2.4 or higher)

Working With Workspace Files

Export Workspace Files To Go

Opens the Export Workspace File To Go dialog, where you can export the Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace making them ideal for distribution to remote sites. Opens the Select AXW File dialog, where you can select a previously exported "To Go" (AXW) file to import into the program. Opens the New Project Properties dialog, which allows you to assign an Identifier and general properties for a new Project. Once created, the new project is added to the Workspace. Opens the Open Workspace dialog, where you can locate and select a Workspace (.APW) file. This invokes the Import Components From a Workspace dialog. Use the dialog to select a specific Project contained in the Workspace. You can copy and paste Projects by selecting Copy Project from the Project Folder context menu, and selecting the Paste Project command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).

Import From Exported Workspace File New Project

Import a Project

Paste Project

Collapse Tree

Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking view Hide Quick Load Workspace Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option allows you to access the File Transfer dialog, already configured to send all files in the Workspace (active Project/System only) to the Master associated with the active System. Opens the Workspace Properties dialog, where you can view the basic properties of the open Workspace. The options in this dialog also allow you to edit the Workspace Identifier and Description.

Workspace Properties

NetLinx Studio (v2.4 or higher)

31

Working With Workspace Files

32

NetLinx Studio (v2.4 or higher)

Working With Projects

Working With Projects


Overview
A Project in NetLinx Studio contains one or more Systems (a System represents a control system (an Axcess or NetLinx Master, one or more user-interface devices and various types of controlled devices on the bus). Projects are represented by Project folders in the Workspace tab of the Workspace Window. A Workspace can contain several Projects (which in turn can contain multiple Systems). In NetLinx Studio (v2.0 and later), all Projects and associated Systems and System files are linked to the Workspace, so that you can add and remove Projects and Systems without having to make copies of the files. NetLinx Studio (v2.0 and later) also allows you to copy and paste Projects within the Workspace; in the case that you need to create several similar Projects you can quickly generate multiple Projects and modify each one as necessary.
Since all System files are linked to the Workspace, when you open a file for editing, you are opening and editing the actual file, not a local copy. It is important to understand that in the event that the file is linked to multiple Systems, any changes made to the file will be reflected in every instance that the file is used (not just the System that you were in when the changes were made).

Even if you don't have multiple links to the same file, and instead have only a single link, you still need to be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.

Opening Projects in NetLinx Studio v2.0 (or higher)


In NetLinx Studio version 2.0 or later, Projects are always contained within a Workspace, and there is no concept of a Project outside of a Workspace. So, rather than opening a Project directly (like you would have in NetLinx Studio v1.2), you must open the Workspace that contains the Project you want to work on.

Creating A New Project


In order to create a Project, you must first open or create a Workspace file. When a Project is created, it is automatically added to the open Workspace. To create new Project: 1. Select New Project from the Project menu or the Workspace context menu (or click the toolbar button) to open the New Project Properties dialog.

A Workspace must be open for these options to be enabled.

2. Enter an Identifier (name) for the Project (required). The Identifier can have a maximum of 128 characters, and must be unique within the open Workspace file.

NetLinx Studio (v2.4 or higher)

33

Working With Projects

3. Enter Dealer, Designer, Sales Order, Purchase Order info (maximum of 128 characters each), and a Description for the Project (maximum of 2,000 characters). These fields are all optional. 4. Click OK to add the new Project to the active Workspace.

Building the Selected Project


You can select to compile a single Project within the open Workspace, using the Build Project command. When you compile a Project, every Source Code, Include, and Module file contained in all of the Systems within the selected Project are compiled. There are several ways to access the Build Project command - via the Build menu, the Project Folder context menu (in the Workspace tab of the Workspace Window), or via the toolbar button. To compile a Project: 1. Click to select and highlight the Project that you want to compile (in the Workspace tab of the Workspace Window). 2. Select Build > Build <Project Name> Project. Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 3. The status and results of the build are displayed in the Status tab of the Output Display Window.

Viewing And Editing Project Properties


Use the Project Properties dialog to view and/or edit general properties of the selected Project. To access this dialog, select Project Properties from the Project menu, the Project Folder context menu, or click the toolbar button. You can edit all of the information in this dialog:
Identifier Dealer Sales Order Designer Purchase Order Description The Project Identifier is required and can have a maximum of 128 characters. Optional, maximum of 128 characters. Optional, maximum of 128 characters. Optional, maximum of 128 characters. Optional, maximum of 128 characters. Optional, maximum of 2,000 characters.

34

NetLinx Studio (v2.4 or higher)

Working With Projects

Converting NetLinx Studio v1.2 Project Files


NetLinx Studio v2.0 (and higher) supports Project (.PJS) files created in NetLinx Studio v1.2, via the File > Open or File > Open Workspace commands. The program converts the .PJS file into an .APW Workspace file that can be used by NetLinx Studio.

The original NetLinx Studio v1.2 file is not altered during this conversion process.

To convert NetLinx Studio v1.2 Project Files for use with NetLinx Studio v2.0: 1. Select File > Open Workspace (or use the toolbar button) to open the Open Workspace dialog. 2. Change the Files of type option (at the bottom of the dialog) to NetLinx Studio V1.2 PJS File (*.pjs) files. 3. Locate and select the desired NetLinx Studio v1.2 Project file (*.PJS). 4. The program prompts you to proceed with the conversion process. Click Yes to continue to the PJS to APW Project File Conversion dialog. 5. Click Convert to start the process. 6. The program prompts you when the conversion is complete (click OK in the Conversion Succeeded dialog). 7. Once the file has been successfully converted, the program prompts you to change the Communication Settings for the converted file. For Projects with multiple systems, the program prompts you to change the communication settings for each System individually. Click Yes to change the System-Level Communications Settings for each System contained in the converted Project (via the Master Communications Settings dialog), or click No to leave the communication settings alone for this Project/System. The converted file now exists as a .APW file, in the same folder that contained the original .PJS file under the same name, but with the .APW file extension. The new Workspace file is automatically opened in the Workspace Window - Workspace tab. At this time, any open Workspace files are automatically closed. If there have been any unsaved changes made to the open Workspace, the program prompts you to save your changes before the Workspace is closed. The converted file now appears as a Workspace with one Project, and one System, and can be treated like any other NetLinx Studio v2.0 Workspace file.
When converting NetLinx Studio v1.2 Projects that contain Module Files, all Module files will appear in NetLinx Studio v.2's Source folder, as opposed to the Module folder. Any TKO files resulting from compiling those files will be placed in the Module file folder. This is only true for converted files, and doesn't apply to Module files added to a new Workspace file created in NetLinx Studio v2.0.

NetLinx Studio (v2.4 or higher)

35

Working With Projects

Project Folder Context Menu Right-click on any Project folder (in the Workspace tab of the Workspace Window) to open the Project Folder context menu. This context menu contains various Project -level commands and options, including:
New Project Opens the New Project Properties dialog. The options in this dialog allow you to specify information for the new Project, including Project Identifier, Dealer, Sales Order, Designer, Purchase Order and Description. Deletes the selected Project from the Workspace. This option does not delete the Project or its associated files from the disk. Builds (compiles) the Project (including all contained Systems and System files). The progress and results of the build can be viewed in the Status tab of the Output Display window. Copies the selected Project to clipboard memory, so it can be pasted (within the same Workspace only), via the Paste Project command in the Workspace context menu. Opens the System Properties dialog, which allows you to assign an Identifier, System ID, and Description for a new System. The System Properties dialog also contains options that allow you to set custom communication settings for the new system. Once created, the new system is added to the Project. Opens the Open Workspace dialog, where you can locate and select the Workspace (.APW) file that contains the System you want to import into the Project. Once you select an APW file, the Import Components From a Workspace dialog is invoked. Use this dialog to select specific Systems contained in the selected Workspace. You can copy and paste Systems (within a single Workspace) by selecting Copy Selected System from the System context menu, then opening the target Project, and selecting the Paste System command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).

Delete Project Build Project

Copy Selected Project

New System

Import a System

Paste System

Collapse Tree

Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking View - Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hide Quick Load Project Hides the Workspace Window. This option (only available for the active Project) allows you to access the File Transfer dialog, already configured to send all files in the active Project to the Master associated with the active System. Opens the Project Properties dialog, where you can view and edit the basic properties of the Project (Project Identifier, Dealer, Sales Order, Designer, Purchase Order and Description).

Project Properties

36

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Working With Systems and System Files


Working With Systems
A System in NetLinx Studio represents an Axcess or NetLinx-based control system. Each System has its own Master Controller (and associated Master Source Code file) and set of devices on the bus (and their associated files). Systems are represented by System Folders in the Workspace tab of the Workspace Window. Any Project can contain multiple Systems, and Systems only exist within the context of a Project. A control system typically uses several different types of files. You must have a Master Source Code file to download to the Axcess or NetLinx Master Controller, but a complete control system also typically uses an assortment of other file types. The System file types recognized by NetLinx Studio are described below:
Source Code Files Include files Module Files These include the Master Source Code File and all other source code (.AXS) files associated with the System. These are Axcess or NetLinx code files (.AXI) that are referenced in any source code file by the 'Include' statement. NetLinx Module files provide pre-fabricated (.AXS) code or compiled (.TKO) code to control a specific device on the bus. Module files cannot be designated as master files. When the System is being compiled, Module files are compiled first, then copied to the directory where the designated Master Source code file resides. These files (.TPD, .TP4 or .KPD) are created in TPDesign3, TPDesign4 or KPDesign, and contain touch panel pages, buttons and their associated functionality. These files (.IRL or .IRV) are created in the IREdit Program, and contain infrared (IR) control functions for IR controlled devices. These files (.IRN) contain links to either the AMX IR Database or to a user-defined IR database. In many cases, it is helpful to save document and image files (for example, .TXT, .DOC, .BMP) with the other system files, even if they are not directly utilized by the control system.

User Interface (UI) files

Infrared (IR) library files IR Database files Other files

In NetLinx Studio v2.0 (or later), all Projects and associated Systems and System files are linked to the Workspace, so that you can add and remove Projects and Systems without having to make copies of the files. NetLinx Studio v2 also allows you to copy and paste Projects within the Workspace; in case you need to create several similar Projects you can quickly generate multiple Projects and modify each one as necessary.
Since all System files are linked to the Workspace, when you open a file for editing, you are opening and editing the actual file, not a local copy. It is important to understand that in the event that the file is linked to multiple Systems, any changes made to the file will be reflected in every instance that the file is used (not just the System that you were in when the changes were made).

Even if you don't have multiple links to the same file, and instead have only a single link, you still need to be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should

NetLinx Studio (v2.4 or higher)

37

Working With Systems and System Files

make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.

Creating A New System


When you create a new System, it is automatically added to the Project that is currently selected (highlighted) in the Workspace tab.

To create a new System: 1. Select the Project that you want to add the new System to in the Workspace Window (Workspace tab). 2. Select New System from either the Project menu or the Project context menu (or click the toolbar button) to open the New System dialog. Use the options in this dialog to specify an Identifier, System ID and Description for the new System.
The System ID number only applies to NetLinx systems. If you are creating an Axcess system, ignore the System ID field.

3. Click Communication Settings to open the Communication Settings dialog, where you specify the System platform, communications port settings or network settings as required: Click the Platform Selection radio buttons to select either Axcess or NetLinx as the system platform. Select a Transport Connection Option (TCP/IP, Serial or Modem). TCP/IP - To specify network TCP/IP settings (NetLinx systems only), select the TCP/IP radio button, and click Settings to open the TCP/IP Settings dialog, where you can enter the System's IP Address assignment.

Do not change the Port number! It should always be set to 1319 (default).

Serial - Select the Serial radio button, and click Settings to open the Serial Settings dialog, where you can select and configure a Serial COM port to use. Modem - Select the Modem radio button, and click Settings to open the Modem Settings dialog, where you can select and configure a Modem COM port to use. 4. Click OK to add the new System to the selected Project.

38

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Adding An Existing System To a Project


Importing Systems Into A Project Its easy to import one or more existing Systems into a Project in the open Workspace. You just need to know which Workspace file contains the System(s) that you want to add to your Project: 1. Select (highlight) the Project that you want to add the imported System into (in the Workspace tab of the Workspace Window). 2. Right-click to access the Project folder context menu, and select Import a System to open the Open Workspace dialog. 3. Use the options in this dialog to locate and select the Workspace (.APW) file that contains the System that you want to import into the Project. 4. Click Open to access the Import Components From a Workspace dialog. 5. Check each System that you want to import, and click OK to add the selected System(s) to the Project. Copying And Pasting Systems NetLinx Studio v2.0 (or later) allows you to easily copy and paste Systems (and all associated System Files) within a Workspace. This allows you to develop a set of core Systems which you can then copy, paste and modify as necessary. In cases where there are only minor variations from one System to the next, this can be a real timer-saver. To copy and paste a System (within a Workspace): 1. Open a Workspace (in the Workspace tab of the Workspace Window) and click to select (highlight) a System folder. 2. Right-click on the System folder and select Copy Selected System from the System Folder context menu. 3. Right-click on the Project that you want to paste the System into, and select Paste System from the Project Folder context menu. 4. The System is added to the selected Project.

Deleting A System From A Project


When you "delete" a System from a Project, no System files are actually deleted from the hard drive; the System is simply removed from the Project in the Workspace. To delete a System from a Project: 1. Click to select the System that you want to remove (in the Workspace tab of the Workspace Window). 2. Select Delete System from the Project menu or the System Folder context menu. 3. The program prompts you to confirm removing the selected System. 4. Click Yes to remove the System.

NetLinx Studio (v2.4 or higher)

39

Working With Systems and System Files

System Status: Active Vs. Inactive


You may have multiple systems within a Project, but only one is designated as the "Active System", meaning that all communication with the master controller (i.e. diagnostics, online tree, etc.) will be done with the communications settings of the selected System. The currently active System is bolded in the Workspace tab of the Workspace Window, and the status bar at the bottom of the program will display the selected System communication settings. If there is currently an active connection to a master controller when you select a System with different communications settings, the program will prompt you to see if you want to stop the current connection and continue with the selected active System communication settings. Designating The Active System You can set one System in the Workspace to be the "Active System". This signifies that all communication with the master controller (i.e. diagnostics, online tree, etc.) will be done with the communications settings of the specified System. The Workspace tree indicates the active System with bold type, and the status bar at the bottom of the program will display the selected System communication settings. If there is currently an active connection to a master controller when you select a System to be active, the program will prompt you to see if you want to stop the current connection and continue with the selected Active System communication settings. To designate the active System, select (highlight) a System (in the Workspace tab of the Workspace Window), then select Set as Active System from either the Project menu or the System Folder context menu (or click the toolbar button).

Configuring System-Level Communications Settings


The Master Communication Settings dialog contains options that allow you to specify System-level communication settings. Each System can have its own dedicated communication settings. These System-level settings override the default communications settings. To set System-level communication settings: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. The Available System(s) list in this dialog represents all Systems contained within the open Workspace (and their parent Projects). 2. Click to select a System from the Available System(s) list. 3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (TCP/IP, Serial, Modem or Virtual NetLinx Master).
The TCP/IP and Virtual NetLinx Master options are only available if NetLinx is selected as the platform.

6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog).

40

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1

Flow Control None

Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.

7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. Alternatively, you can also access these System-level communications settings options via the System Properties dialog: 1. Select (highlight) a System in the Workspace tab of the Workspace Window, and select System Properties from either the Project menu or the System Folder context menu (or click the toolbar button) to open the System Properties dialog. 2. In the Communication Settings area (at the bottom of the dialog), click Communication Settings to open the Communication Settings dialog. 3. Follow steps 4 through 8 (above) to specify communication settings for the selected System.

Adding A File To A System


When a file is added to a System, the file is always added to the selected (highlighted) System (in the Workspace tab of the Workspace Window), and it is always automatically added to the appropriate System File folder, based on file type. To add a file to a System: 1. Select (highlight) the System that you want to add the file to. 2. Select Add File to System from either the Project menu, the System Folder context menu (or click the toolbar button) to open the Add Existing File dialog. 3. In the Existing tab, locate and select the file to add to the selected System.
By default, the Files of Type option is set to look for Source (.AXS) files. Change this option to look for the desired file type if necessary.

NetLinx Studio (v2.4 or higher)

41

Working With Systems and System Files

Use the Recent tab to quickly locate and select recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. If the file you are adding is to be used as the Master Source Code file, check the Master File option. 7. Click OK to add the file to the selected System. Alternatively, you can drag and drop files into a System in the Workspace Window from Windows Explorer or from the Find In Files/Find IR Files tabs of the Output Display Window. See the Drag and Drop Files into a System topic for details.
Drag And Drop Files Into A System

NetLinx Studio allows you to drag and drop files into a System: In Windows Explorer, select a file that you want to add to a System in the Workspace Window (Workspace tab). Drag and drop the file into the System folder. In the Output Display Window, you can select any of the files listed as search results in either the Find In Files or Find IR Files tabs. Drag and drop the file into the System folder.
Do not drop the file into the specific System File folder that matches its type. Regardless of type, all files must be dropped into the System folder to be added (imported) correctly into the System.

When the file is dropped into the System folder, the File Properties dialog is invoked. Use the options in this dialog to rename the selected file, browse for a different file, and/or enter a description for the file (if desired). Click OK to add the file to the System. Note that the file is placed in the appropriate System File folder based on the file type.

Removing A File From A System


Since all files are linked in NetLinx Studio v2.0 (or later), when you remove a file from a System, the file is not deleted from the disk, only removed from the System. If the same file is used in multiple Systems in the open Workspace, the Remove File from System option only removes the file from the selected System (as opposed to all instances of the file in the Workspace). To remove a file from a System (in the open Workspace): 1. Click to select (highlight) the file that you want to remove. 2. Select Remove File From System from either the Project menu or the System File context menu (or click the toolbar button).

42

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

3. The program prompts you to verify this action. 4. Click Yes to remove the file from the System.
Alternatively, you can simply select a System file and press the Delete key for the same results.

Building (Compiling Systems)


Building The Selected System You can select to build (compile) any System in the Workspace, using the Build System command. When you build a System, every Source Code, Include, and Module file contained in the selected System is compiled. The Build System command always works on the selected System, regardless of whether it is currently designated as the active system or not. To compile a System: 1. Click to select (highlight) the System that you want to build (in the Workspace tab of the Workspace window). 2. Select Build System <System name> from the Build menu, or select Build System from the System Folder context menu (or click the toolbar button). Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 3. The status and results of the build are displayed in the Status tab of the Output Display Window. Building The Active System You can select to build (compile) only the System currently designated as the Active System, using the Build Active System command. When you compile a System, every Source Code, Include, and Module file contained in the selected System is compiled.
The currently active System is indicated in bold (in the Workspace tab of the Workspace Window).

To compile the Active System: 1. Select Build Active System from the Build menu, or click the toolbar button. Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. Assuming that a Master Source Code file has been defined for the System, this dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window.

NetLinx Studio (v2.4 or higher)

43

Working With Systems and System Files

Viewing And Editing System Properties


Use the System Properties dialog to view and/or edit the information for the selected System entered in the New System dialog when the System was created. To access this dialog, select System Properties from the Project menu, the System Folder context menu, or click the toolbar button. You can edit all of the information in this dialog:
Identifier System ID Description Required, and can have a maximum of 128 characters. Optional, the range is from 0 - 65535 Optional, and can have a maximum of 2,000 characters.

Communication Settings The Communication Settings window displays the current communications settings for this System. To change these settings, click the Communication Settings command button to open the Communication Settings dialog.

System Folder Context Menu Right-click on any System folder (in the Workspace tab of the Workspace Window to open the System Folder context menu. This context menu contains various System-level commands and options, including:
Set as Active System New System Sets the currently selected System as the Active System. Opens the New System dialog. The options in this dialog allow you to specify information for the new System, including System Identifier, System ID, Description and Communication Settings. Deletes the selected System from the selected Project. This option does not delete the System or its associated files from the disk. Builds (compiles) the active System (including all contained System files). The progress and results of the build can be viewed in the Status tab of the Output Display window.

Delete System Build System

Copy Selected System Copies the selected System to clipboard memory, so it can pasted into another Project (via the Paste System command in the Project Folder context menu). Add File To System Opens the Add Existing File dialog, which allows you locate and select an individual file to be added to the active System. The selected file will automatically be added to the appropriate System File folder, based on file type. Collapses the System/File tree to hide all System files. Expands the System/File tree to show all System files contained in the System File folders. Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option (only available for the active System) allows you to access the File Transfer dialog, already configured to send all files in the active System to the Master associated with the active System. Opens the System Properties dialog, where you can view and edit the basic properties of the active System (System Identifier, System ID, Description and Communication settings).

Collapse Tree Expand System Tree Docking View Hide Quick Load System

System Properties

44

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

System Files
System Files represent the actual files that are needed to operate a particular controlled device in the named System. System files include Source Code, Include files, NetLinx Module files, IRLib files, User-Interface (UI) files and any other (*.*) files that you might want to include. System files are placed in the appropriate System file folder (in the Workspace tab of the Workspace Window) as links only. System file types are described below:
Master Source Code file Source Code files This is the Source Code file that defines the devices in the System. Master Code files are sent only to the Axcess or NetLinx Master Controller. Master Source Code files are placed in the Source file folder. These include all code files (.AXS) that are not Master Code Files. Source Code Files are created in NetLinx Studio, and are sent to specific devices on the bus. Source Code files are placed in the Source file folder. These are Axcess or NetLinx code files (.AXI) that are separate from the main Master and Source Code files, but are included in the compile process. These files are created in NetLinx Studio. Include files are placed in the Include file folder. These files provide pre-fabricated (.AXS) code or compiled (.TKO) code to control a specific device on the bus. NetLinx Studio v2.3 (or higher) supports Duet (.JAR) Module files. Module files cannot be designated as master files. When the System is being compiled, these Module files are compiled first, then copied to the directory where the designated Master Source code file resides. Module files are placed in the Module file folder. User-Interface (UI) files These are (.TPD/.TP4) or (.KPD) files that are imported into Projects. TPD/TP4 touch panel UI files define the look and functionality of touch panel pages. TPD files are touch panel UI files created in TPDesign3 (for use with G3 level firmware touch panels), TP4 files are created in TPDesign4 (for use with G4 level firmware touch panels, i.e. Modero series panels). KPD files are created in the KPDesign KeyPad Design program, and define the buttons and functionality of PLK-DMS and PLK-IMS Keypads. UI files represent the user-interface for the control system. UI files are placed in the User Interface file folder. These files (.IRL or .IRV) are created in IR Edit and contain infrared (IR) control functions for IR controlled devices. IR files are placed in the IR folder. IRN files provide links to the AMX IR Database and/or user-defined IR Database files. In many cases, it is helpful to save document and image files (for example, .TXT, .DOC, .BMP) with the other system files, even if they are not directly utilized by the control system. "Other" files are placed in the Other file folder.

Include files

Module Files

Infrared (IR) library files IRN files Other files

NetLinx Studio (v2.4 or higher)

45

Working With Systems and System Files

Creating New System Files


Use the File > New command (or toolbar button) to create all types of System files, including Source Code, Include, Block and Text files. This command creates a new file, but does not automatically associate the new file with any Project or System.

Use the Project > Add File To System command to add the file to a System.

To create new System file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select the type of file that you want to create (Source File, Include File, Block File, or Standard Text).
The Workspace Wizard option launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project and one System.

3. Click OK to open an empty Source Code Editor window. 4. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 5. Specify a name and target location for the new file in the Save As dialog. File Types And Extensions
File Type Axcess Source Code File Include File File Extension .AXS .AXI

Compiled Axcess Source Code File .TOK Compiled NetLinx Source Code File .TKN NetLinx Source Code File Block File TPDesign3 User Interface File TPDesign4 User Interface File KPDesign Keypad Touch File IR Library File IRV File IRN (IR Database) File Standard Text File Other File .SRC .AXB .TPD .TP4 .KPD .IRL .IRV .IRN .TXT .* (any other extension)

46

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Identifiers vs. Disk Filenames


Workspace and System files (displayed in the Workspace tab of the Workspace Window) are represented by the name assigned in the Identifier field in the Workspace Properties, Project Properties, System Properties, and File Properties dialogs. The disk file name is the full file name (plus it's extension) as it appears in Windows Explorer. For example, if you create a Source Code File into a Project and enter "My File" in the Identifier field, the file will appear in the Workspace Window as "My File", but the disk file name is "My File.AXS". You can change a file's Identifier without affecting the disk filename. Identifiers must be unique to each System, regardless of the file type. If you assign an identifier to a file that already exists in the System, the program will prompt you to enter a different identifier. You can change the assigned identifier of any System file (via the File Properties dialog), but remember that identifiers only apply to the specific file that they are applied to, and not to any others. For example if you change a file's identifier, the file's associated *.TOK file still reflects the disk file name.

Viewing And Editing System File Properties


Use the File Properties option in the System File context menus to open the File Properties dialog, which allows you to view general properties for the selected file. The fields in the File Properties dialog include:
Identifier File Name Relative Path The File Identifier can have a maximum of 128 characters, and must be unique within a System. You can change the file name in this text box. Use the browse button to navigate to the desired file you want. This (read-only) field represents the location of the file, relative to the Workspace file that is currently open. All files are linked to the workspace (not copied over to the workspace directory). The Description text is optional and can have a maximum of 2,000 characters. This check box designates that this file is the Master Source Code file. When checked, the Compile As combo box will be grayed out. The Master File will be compiled for the platform designated in the System Properties dialog. This combo box allows you to compile a source code file to a platform (Axcess or NetLinx) different than the System's designated platform. This option is available if the Master File check box is deselected (unchecked).

Description Master File

Compile As

Creation Date The date the file was created (read only).

NetLinx Studio (v2.4 or higher)

47

Working With Systems and System Files

Device Mapping
The Device Mapping dialog allows you to map files to System devices for file transfers. To access the Device Mapping dialog, select a System (in the Workspace tab of the Workspace Window) and select Project > Device Mapping. Alternatively, you can access the Device Mapping command via the Device Mapping command in the Source File, User Interface, and IR File context menus, or use the toolbar button. Device Mapping Dialog The Device Mapping dialog consists of two windows. The File View window (on the left) presents a view of the Projects, Systems and System Files contained in the open Workspace file, in a tree structure similar to the one displayed in the Workspace tab of the Workspace Window. Double-click the Project folders to show the System folders. Double click to expand the System folders to show the System File folders (Source, User Interface and IR only, since these are the only file types that can mapped). Double-click these folders to view the System files. The Device View window (on the right) presents a view of devices specified in the DEFINE_DEVICE section of the selected System's Master Source Code file, with their associated device numbers. There is also a <Custom> listing, which allows you to specify a D:P:S assignment other than what is specified within the Master Source Code file. With a file selected (in the File View window), select a target device for the file in the Device View window, and click the Map button to map that file to the selected device. If you select <Custom>, the Enter DPS dialog will prompt you to enter the D:P:S assignment of the device you want to map to. Files can be mapped to multiple devices. In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0), and cannot be mapped to any other device. This does not apply to NetLinx Master Source Code files. Once a file has been mapped to a device, the mapping assignment is indicated in the File View window of the Device Mapping dialog as well as in the Workspace tab of the Workspace Window. The file mapping information is saved with the Workspace file, and this association is maintained until the mapping information is removed (via the Remove option in the Device Mapping dialog, or the Delete command in the System File Device Map context menu.

Workspace mappings are only updated when the source code file is saved.

NetLinx Studio makes it easy to map System files to devices on the bus for file transfer operations: 1. Select and open the Project containing the Source Code file to be mapped to a device (in the Workspace tab of the Workspace Window). 2. Select the System containing the file.

48

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

3. Select Device Mapping from the Project menu (or use the toolbar button) to open the Device Mapping dialog.
You can also access the Device Mapping command via the Source File, User Interface, and IR File context menus. The Device Mapping option is only available if you have selected a Source Code file that is not designated as the Master Source Code file.

4. In the Device Mapping dialog, select a System from the File View window on the left side of the dialog (if different than the System already selected). 5. Double-click to expand the System folder to view the System File folders (Source, User Interface and IR). 6. Double-click to expand the System File folder containing the file you want to map to a device, and select the file you want to map. 7. In the Device View window (on the right side), select the target device for the selected file from the list of devices (as specified in the in the DEFINE_DEVICE section of the System's Master Source Code file). To map to a device that is not specified in the Master Source Code file, select <Custom>, and enter the device's D:P:S assignment (in the Enter DPS dialog).
The System's Master Source file will always be mapped automatically to 0:1:0 for NetLinx Masters, and 0 for Axcess Masters.

8. Click the Map button to map the file to the target device. Once a file has been mapped to a device, the mapping assignment is indicated in the File View window of the Device Mapping dialog as well as in the Workspace tab of the Workspace Window. The file mapping information is saved with the Workspace file, and this association is maintained until the mapping information is removed (via the Remove option in the Device Mapping dialog, or the Delete command in the System File Device Map context menu.

Workspace mappings are only updated when the source code file is saved.

DEVICE:PORT:SYSTEM (D:P:S) A device is any hardware component that can be connected to the NetLinx bus. Each device must be assigned a unique number to locate that device on the bus. The Axcess language allows physical device numbers in the range 0-255. The NetLinx language allows numbers in the range 0-32767. Device 0 refers to the master; numbers above 32767 are reserved for internal use. NetLinx requires a Device:Port:System (D:P:S) specification where Axcess expected only a device number. This D:P:S triplet can be expressed as series of constants, variables separated by colons, or as a DEV structure, to explicitly represent a device number, port and system. Here's the syntax:
DEVICE:PORT:SYSTEM

NetLinx Studio (v2.4 or higher)

49

Working With Systems and System Files

where: Device: 16-bit integer representing the device number Port: 16-bit integer representing the port number (in the range 1 through the number of ports on the device) System: 16-bit integer representing the system number (0 = this system) that the device belongs to. For example, 128:1:0 represents the first port on device 128 on this system. DEV structure example:
STRUCTURE DEV { INTEGER Number INTEGER Port INTEGER System }

// device number // port on device // system device belongs to

In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0), and cannot be mapped to any other device. This does not apply to NetLinx Master Source Code files.

To Remove Device Mapping Information from a File 1. Select a device-mapping icon in the File View window. 2. Click the Remove button. System File Device Map Context Menu Right click on a Device Mapping icon (in the Workspace tab of the Workspace Window) to access the System File Device Map context menu:
Device Mapping Opens the Device Mapping dialog for mapping files to System devices. Delete Removes the selected file's device-file mapping association.

Working With System Source Code Files


You can create new Source Code files in NetLinx Studio, or add existing Source Code files to a System. Source Code files are created and/or edited in the Source Code Editor windows. Source Code files are stored in the Source folder (in the Workspace tab of the Workspace Window). NetLinx Studio distinguishes between two types of Source Code files: the Master Source Code file and System Source Code files: Master Source Code file - The Source Code that is sent to an Axcess or NetLinx Master Controller. The Master Source Code file defines all of the devices in the System and sets any global parameters for the System. Source Code files - Axcess or NetLinx Source Code files that are sent to specific NetLinx or Axcess devices on the bus. You can have as many Source Code files in the Source Code System folder as is required for the System. Source Code files are stored in the Source folder (in the Workspace tab of the Workspace Window).

50

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Adding A New Source Code File To A System NetLinx Studio provides a set of dialogs that step you through the process of creating a new Source Code (*.AXS) file. To create new Source Code file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Source folder to access the Source File Folder context menu, and select Add New Source File to open the File Template dialog.
Alternatively, you can also either select File > New, and select Source File (in the New dialog), or click the New toolbar button.

3. In the File Template dialog, select a template to use to create the file (NetLinx Standard, Axcess Standard or User-Defined), and click Next to proceed.
If you select to use the NetLinx or Axcess templates, the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.

4. Enter a file name for the new Source Code file, and select wether to assign this new file as the System's Master Source Code file (via the Make this the Master Source Code file option checkbox). Click Next to proceed. 5. In the New File Location dialog, specify a target directory for the file. By default, the target directory is the NetLinx Studio v2 directory. Use the Browse button to navigate to another folder if necessary. 6. The program notifies you that the file was created. Click Finish to close the File Template dialog. The new file should appear in the Source folder, under the selected System. Adding An Existing Source Code File To A System To add an existing Source Code file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Source folder to access the Source File Folder context menu, and select Add Existing Source File. 3. In the Add Existing Source File dialog, locate and select the Source (.AXS) file that you want to add to the selected System.

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

NetLinx Studio (v2.4 or higher)

51

Working With Systems and System Files

5. Edit the file information (if necessary). 6. If the file you are adding is to be used as the Master Source Code file for the System, check the Master File option. 7. Click OK to add the file to the selected System. 8. The file should now appear in the Source folder under the selected System, as the Master Source Code file (indicated by the letter "M" on the file icon in the Workspace tab). Removing A File From A System Since all files are linked in NetLinx Studio v2.0 (or later), when you remove a file from a System, the file is not deleted from the disk, only removed from the System. If the same file is used in multiple Systems in the open Workspace, the Remove File from System option only removes the file from the selected System (as opposed to all instances of the file in the Workspace). To remove a file from a System (in the open Workspace): 1. Click to select (highlight) the file that you want to remove. 2. Select Remove File From System from either the Project menu or the System File context menu (or click the toolbar button). 3. The program prompts you to verify this action. 4. Click Yes to remove the file from the System.
Alternatively, you can simply select a System file and press the Delete key for the same results.

Creating A Source Code File To create a Source Code file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select Source File and click OK. 3. In the File Template dialog, select whether to use an existing template to create the file: If you click Yes, you will be prompted to select a template (NetLinx, Axcess or User Defined). If you select the User-Defined Template option, click the Browse button (...) to open locate and select any Source file (.AXS) to use as the template (via the Open dialog). Select the desired template or file and click Next to proceed to step 4. If you click No, you can start developing the file immediately, in a new Source Code Editor window.
If you select to use one of the existing templates (NetLinx or Axcess), the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.

4. Enter a name for the new Source Code file. 5. The program notifies you that the file was created.

52

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

6. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 7. Specify a name and target location for the new file in the Save As dialog.
Existing Source Code files can be added to Systems via the Project > Add File To System command.

Saving The Active File Click File > Save (or click the toolbar button) to save the active file in the Source Code Editor, using the current file name and identifier. Saving All Open Files Click File > Save All (or click the toolbar button) to save all open files, using their current file names and identifiers. File Revisions The Save As Revision option allows you to save the active Source Code files with file revision information included in the file. This feature allows you to specify a revision number (or other identifier), and add text comments to assist in managing multiple revisions of the same file. Additionally, the program automatically includes a date/time stamp in the revision information. This file revision information is then added as a block of text to the top of the source code file when the revision is saved. Use the options in the Save File Revision dialog (File > Save File Revision) to view/edit the PROGRAM_NAME, revision number (or identifier), file name, and add any comments associated with this revision that you would like to include. To save a file revision of the active Source Code file: 1. Select File > Save File Revision to open the Save File Revision dialog. 2. Enter/edit the information in this dialog as desired:
PROGRAM_NAME = Revision This editable field indicates the PROGRAM_NAME, as it appears in the active source code file. Enter a number (or other identifier) for this revision of the file (for example, REV 1).

Update Name With Revision Text Click this option to automatically generate the PROGRAM_NAME and the File Name to include the revision identifier (as entered in the Revision field). File Name Directory Path Comments This editable field indicates the name (*.AXS) of the active file. This read-only field indicates the directory path of the active Source Code file. Use this field to record any comments that would be helpful to add to the file.

3. Click Save to save the file revision. Note that the specified revision information is added to the top of the file, as can be seen in the Source Code Editor window.

NetLinx Studio (v2.4 or higher)

53

Working With Systems and System Files

The file that was replaced with the new file revision will not be deleted from your hard drive.

The program will insert the file revision information specified here at the top of the source code file, before any other revision information that already exists in the file (if any exists). The example below shows file revision information, as it appears in the source code file after two revision have been saved:
In this case, the Update Name With Revision Text option was enabled, as is indicated by the "Rev2 " that follows the comma delimiter in the PROGRAM_NAME line.

FIG. 9 File Revisions example

Designating The System's Master Source Code File Each System must have a Master Source Code file, and only one Source Code file in the System can be designated as the Master Source. There are two possible ways to designate the Master Source Code file for a System: You can designate a Source Code file as the Master Source at the time that it is added to the System, via the Master File option in the File Properties dialog. Alternatively, you can designate any Source Code file in the System as the Master Source by right-clicking on a Source Code file (in the Workspace tab of the Workspace Window), and selecting Set As Master from the Source Code File context menu. Compiling Source Code Files There are several ways to compile individual Source Code files: Right-click on a Source Code file (in the Workspace tab of the Workspace Window), and select Compile from the Source Code File context menu. In the Build menu, select Compile <filename.AXS>.

54

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

To specify the compiler to use (NetLinx or Axcess), double-click to open the file in a Source Code Editor window, and select Compile as NetLinx or Compile As Axcess from the Build menu. The status and results of the build are displayed in the Status tab of the Output Display Window. UTF-8 Encoding In the Save As dialog, select UTF-8 from the Encoding menu to enable UTF-8 support for new files, to help NetLinx Studio files to work better with other editors. You can also select the Enable UTF-8 Encoding option in the Editor tab of the Preferences dialog.
You may also encode files created with a previous version of NetLinx Studio by choosing "Save-As" and selecting the UTF-8 encoding.

SRC File Extraction NetLinx Studio can generate a compressed version of NetLinx program files anytime they are compiled or transferred. The compressed NetLinx files are called Source Files, and have the extension .SRC. To generate NetLinx Source Files at compile time, enable the Build With Source option in the NetLinx Compiler tab of the Preferences dialog. If this option is not enabled, a dummy file is zipped and named "NOSOURCE.TXT".
The Build With Source option also allows you later send the Source files to another Master, with the ability to debug the code.

The Extract From SRC File command allows you to extract these files: 1. Select Tools > File Extraction > Extract From SRC File to open the Select SRC File dialog. 2. Locate and select the SRC file you want to extract, and click Open.
This is the directory containing the actual program file (.AXS). Source files only exist in the directory if the program file has been successfully compiled (using the Build With Source option).

3. In the Extract NetLinx Source From a SRC File dialog, the selected file (with full directory path) is indicated in the SRC File To Extract From field. 4. In the Extract To field, specify the target directory for the extracted NetLinx Source files, and click Extract to extract the files. When extracted, the program will always replicate the directory paths associated with the compressed files when the file was created. To use the original directory paths, enter C:\ as the destination directory. For example if you enter C:\ as the destination directory, you know that the NetLinx.AXI file will be copied into the proper directory for compiling (C:\Program Files\Common Files\AMXShare\AXIs). If a file with the same name already exists in the specified target directory, the program alerts you, and prompts you to overwrite it or pick a different target directory. If you enter non-existent folders, the program will create them for you.

NetLinx Studio (v2.4 or higher)

55

Working With Systems and System Files

The error "Dynazip Unzip Error: Bad or missing decryption key (Problem extracting file(s))" indicates a mismatch between the password assigned to the file (via the Build With Password option), and the NetLinx password entered in the NetLinx Compiler tab of the Preferences dialog (Password field). If you receive this error message, click OK in the error message dialog to access the Enter Password dialog, and re-enter the password exactly as it was entered when the file was compiled.

ZIP File Extraction NetLinx Studio allows you to export an entire Workspace (including all contained Projects, Systems and System Files) as a .ZIP file. The Extract From ZIP File command allows you to extract these files: 1. Select Tools > File Extraction > Extract From ZIP File to access the Select ZIP File dialog. 2. Locate and select the ZIP file you want to extract, and click Open.
While this feature exists primarily to allow you to unzip exported Workspace files, you can use this feature to unzip any .ZIP file.

3. In the Files From a ZIP File dialog, the selected file (with full directory path) is indicated in the ZIP File To Extract From field. Select the Extract using original directory path(s) option to preserve the original directory paths of the files (default = disabled). 4. In the Extract To field, specify the target directory for the extracted Workspace files, and click Extract to extract the files.
If a file with the same name already exists in the specified target directory, the program alerts you, and prompts you to overwrite it or pick a different target directory.

Source File Folder Context Menu Right-click on any Source folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Source File Adds a new Source Code (.AXS) file to the selected (not necessarily the "active") System, via the new file wizard. The options in the new file wizard dialogs allow you to assign a File Template, File Name and Location to the new Source Code file.

Add Existing Source File Opens the Add Existing Source File dialog, where you can add an existing Source Code file to the System containing the selected Sources folder. The new file will be added to the selected Sources folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

56

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Source Code File Context Menu Right-click on any Source Code File (in the Workspace tab of the Workspace Window) to access the context menu described below:
Set As Master Compile Sets the selected Source Code file as the Master Source file for the system it belongs to. Compiles the selected file, using the compiler (Axcess or NetLinx) associated with the file. The status and results of the build are displayed in the Status tab of the Output Display Window. Opens the Device Mapping dialog which allows you to map the file to a system device for transfer.

Device Mapping

Remove File From System Removes the selected file from its System (the file is not deleted from the disk, only removed from the System). Quick Load File This option (only available for the Master file in the active System) allows you to access the File Transfer dialog, already configured to send the file to the Master associated with the active System. Opens the File Properties dialog, where you can view (and edit) properties for the selected Source Code file.

File Properties

Working With Include Files


An Include file is a type of code file (.AXI) that is included in the compiling process without having to reside in the Master Code file itself. Include files are effectively linked to the Source Code file, and must be called in the Master Source Code. You can create new Include files using the File, New, Include File option, or import existing Include files into your Project. Include files are stored in the Include folder (in the Workspace tab of the Workspace Window). If any Include files are present in the Include System File folder when the Project is compiled (and if they are called in the source code), they are compiled as if the code that they contain was part of the Master Source Code file. NetLinx .AXI File Any time you compile a NetLinx file, the file "NetLinx.AXI" is accessed. This is the default NetLinx include file, and contains various standard NetLinx system structures and variables. This file is called at every NetLinx compile operation, and is included even without being specified in the program. The NetLinx.AXI file is updated in step with version changes of NetLinx Studio. If there are ever any interim updates to the NetLinx.AXI file, you will be notified via the AMX newsletter, and the update will be posted to the Software Center on the AMX.com website. Creating An Include File To create an Include file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select Include File and click OK. 3. An (empty) Include file is created in a new Source Code Editor window. By default, this file is named AXI<n>.axi. 4. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 5. Specify a name and target location for the new file in the Save As dialog.

NetLinx Studio (v2.4 or higher)

57

Working With Systems and System Files

Existing Include files can be added to Systems via the Project > Add File To System command.

Adding A New Include File To A System To create new Include file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Include folder to access the Include File Folder context menu, and select Add New Include File. 3. In the New Include File dialog, specify a File Name and target location for the new Include file. 4. Click OK to create the file. The new file should appear in the Include folder, under the selected System. Adding An Existing Include File To A System To add an existing Include file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Include folder to access the Include File Folder context menu, and select Add Existing Include File. 3. In the Add Existing Include File dialog, locate and select the Include (.AXI) file that you want to add to the selected System.

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Include folder under the selected System. Include File Folder Context Menu Right-click on any Include folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Include File Adds a new Include (.AXI) file to the selected (not necessarily the "active") System, via the New Include File dialog. The options in this dialog allow you to assign a name and target directory for the new Include file.

58

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Add Existing Include File Opens the Add Existing Include File dialog, where you can add an existing Include file to the System containing the selected Include folder. The new file will be added to the selected Include folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

Include File Context Menu Right-click on any Include file (in the Workspace tab of the Workspace Window) to access the context file described below:
Remove File From System Click to remove the selected Include file from the System that it is saved in. The program prompts you to confirm this action before the file is deleted from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected Include file.

Working With Module Files


Module files provide pre-fabricated (.AXS) NetLinx code or pre-compiled (.TKO) NetLinx code to control a specific device on the bus. Module files are stored in the Module folder (in the Workspace tab of the Workspace Window). Module files cannot be designated as Master Source Code files. When the System is being compiled, first the Module files are compiled and then the Master Source Code (.AXS) file is compiled. NetLinx Studio v2.3 (or higher) supports two types of Module files: *.AXS - NetLinx Module files *.JAR - Duet Module Files Duet (JAR) Module Files NetLinx Studio v2.3 (or higher) supports Duet (*.JAR) module files in addition to NetLinx module files. JAR module files are similar to NetLinx module files except that are generated using the AMX Cafe Duet design application.

Refer to the Cafe Duet online help file for details on creating JAR module files.

JAR module files are also stored in the Module folder (in the Workspace tab of the Workspace Window), and the same basic rules apply to JAR module files that were true for NetLinx modules: Module files cannot be designated as Master Source Code files. When the System is being compiled, first the Module files are compiled and then the Master Source Code (.AXS) file is compiled. NetLinx Studio (v2.3 or higher) constructs a composite TKN file when Duet module(s) are included in the Workspace and are referenced in the NetLinx Source code. The composite TKN file

NetLinx Studio (v2.4 or higher)

59

Working With Systems and System Files

is a DynaZip file containing the compiled TKN file as well as the JAR modules that need to be transferred to the NetLinx master in order for the TKN file to execute properly. Minimum Support Requirements For Modules Minimum support requirements for the KPDesign module: PLK-DMS Keypad, v5.1 PLK-IMS Keypad, v5.0 NetLinx Studio v1.2 NetLinx Master v2.0, build 94 Minimum support requirements for Duet modules (*.JAR): NetLinx Studio v2.3 NetLinx Master Firmware build 304 Adding A New Module File To A System To create new Module (*.AXS) file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Module folder to access the Module File Folder context menu, and select Add New Module File. 3. In the File Template dialog, select whether to use an existing template to create the file. If you click Yes, you will prompted to select the template (NetLinx or Axcess). You can select to create a module file using the "module standard" template ("NetLinx Module.axs"). The module standard template file is located in the same directory as the NetLinx Studio application .EXE file. If you click No, you will proceed directly to the New File Location dialog.
If you select to use one of the existing templates (NetLinx or Axcess), the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.

4. In the New File Location dialog, enter a File Name, and specify a target directory for the module file. Use the Browse button to navigate to another folder, if necessary. 5. The program notifies you that the module file was created. 6. Click Finish to close the File Template dialog. The new file should appear in the Module folder, under the selected System. Adding An Existing Module File To A System To add an existing Module file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). Doubleclick the folder to view the System File folders.

60

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

2. Right-click on the Module folder to access the Module File Folder context menu, and select Add Existing Module File (or click the toolbar button). 3. In the Add Existing Module File dialog, locate and select the Module (.AXS, .TKO or .JAR) file that you want to add to the selected System.

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected module file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Module folder under the selected System. Source Code Entry To include a module into your program, use the following module line: DEFINE_MODULE 'DMS-IMSMod' Module_Name(Virtual_Dev, Real_Dev, strFileName, strVarTextArray) Where:
Module_Name Virtual_Dev Real_Dev StrFileName
DMS-IMSMod.tko A virtual device you define. The device number of the DMS or IMS panel. A string variable (CHAR array) containing the file name of the KPD file to run. should be the largest variable text number you want to use. The second dimension should be the maximum size of the string you want displayed (maximum is 40 characters).

StrVarTextArray A two-dimensional array to store variable text in. The first dimension

For example, a NetLinx module for a DMS keypad would look like:
DEFINE_MODULE "DMS-IMSMod" mdlDMS (dvDMS, dvDMS_R, strFILE_NAME, StrVartextArray)

Where:
DMS-IMSMod MdlDMS DvDMS DvDMS_R StrFILE_NAME
The name of the compiled TKO file. The module name. The module ID device number (ex 32768). The device number of the keypad. Exact name of the KPD file.

StrVarText Array Description of the parameters for the variable text buffer.

NetLinx Studio (v2.4 or higher)

61

Working With Systems and System Files

Compiling Module Files There are several ways to compile individual Module files: Right-click on a Module file (in the Workspace tab of the Workspace Window), and select Compile from the Module File context menu. Double-click to open the Module file in a Source Code Editor window and select Compile <filename.AXS> from the Build Menu. To specify the compiler to use (NetLinx or Axcess), open the Module file in a Source Code Editor window, and select Compile as NetLinx or Compile As Axcess from the Build menu. The status and results of the build are displayed in the Status tab of the Output Display Window. Module File Folder Context Menu Right-click on any Module folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Module File Adds a new Module (.AXS) file to the selected (not necessarily the "active") System, via the new file wizard. The options in the new file wizard dialogs allow you to assign a File Template, File Name and Location to the new Module file.

Add Existing Module File Opens the Add Existing Module File dialog, where you can add an existing Module file to the System containing the selected Module folder. The new file will be added to the selected Module folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

Module File Context Menu Right-click on any Module file (in the Workspace tab of the Workspace Window) to access the context menu described below:
Compile Compiles the selected Module file. This option is available only if the selected file is an AXS file (not available for TOK or JAR files).

Remove File From System Click to remove the selected Module file from the System that it is saved in. The program prompts you to confirm this action before the file is deleted from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected Module file.

62

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Working With User Interface Files


User-Interface (UI) files are sent to either touch panels or keypads, and provide the user-interface that allows the end user to control the system. User Interface files are placed (as links) in the User Interface folder (in the Workspace tab of the Workspace Window). There are two basic types of user-files: Touch Panel and Keypad. Touch Panel UI files are created in either TPDesign3 (.TPD) or TPDesign4 (.TP4), and Keypad UI files (.KPD) are created in KPDesign. TPDesign3 is a touch panel design program for use with G3-firmware touch panels (all models except Modero and NXP-TPI/4). TPDesign4 is a touch panel design program for use with G4-firmware touch panels (Modero panels and NXP-TPI/4). KPDesign is a keypad design program for use with PLK-DMS and PLK-IMS keypads. Use the KPDesign to design the keypad display pages and buttons, and their associated functionality, and use NetLinx Studio to transfer the KPDesign file (KPD) to the NetLinx Master. In order to use KPDesign file with the appropriate keypads, the NetLinx code file must first be configured (in NetLinx Studio), compiled, and then transferred to the NetLinx Master.
Refer to the on-line help files for instructions on generating UI files in these applications. These software applications are available for transfer via the www.amx.com website (Dealers > Tech Center > Downloadable Files > Application Files).

NetLinx Studio allows you to associate UI files with each System, and to map and transfer the files to their target panels or master.
While Touch Panel UI files are transferred to the panels themselves, KPD files are transferred to the master and not directly to the keypad.

If the TPDesign3, TPDesign4 and/or KPDesign applications are installed on your PC, you can double-click on any UI file in the Workspace tab to launch the associated editor program (TPDesign3, TPDesign4 or KPDesign). You can add external programs to the Tools menu via the Add Tool option. Adding An Existing User Interface File To A System To add an existing User Interface (UI) file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the User Interface folder to access the User Interface File Folder context menu, and select Add Existing User Interface File. 3. In the Add Existing User Interface File dialog, locate and select the UI (.TPD, TP4 or .KPD) file that you want to add to the selected System. .TPD = Touch panel UI files created in TPDesign3 .TP4 = Touch panel UI files created in TPDesign4 .KPD = Keypad UI files created in KPDesign

NetLinx Studio (v2.4 or higher)

63

Working With Systems and System Files

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the User Interface folder under the selected System. Configuring NetLinx Source Code for KPD Files You need to configure your NetLinx code to accommodate using KPD files. Before beginning, either use or write a new program (in NetLinx Studio) that: Defines the Virtual devices Defines the Keypad devices Associates the KPD file with defined devices Once you have a program: 1. In the DEFINE_DEVICE section of the code, verify that the dvDMS is set to any user-defined value within the range of 32768 - 36863. 2. In the REALS section of the program, re-write the dvDMS_R to equal the value of the new Device number set in the Device Addressing Tab of the Tools > NetLinx Diagnostics dialog box. An example is if the Changed Device number value is set to 6001, the dvDMS_R value would now read 6001:1:0. Each consecutive keypad device would become:
dvDMS_R 6002, 6003, 6004 +.

3. In the STARTING CODE GOES HERE / CREATE FILE section of the program, the StrFILE_NAME must equal the exact name of the KPD file being used in the compile. 4. Add the KPD file to the project by choosing Project > Add File To System. This opens the Add Existing File dialog. 5. Locate and select for the desired KPD file. 6. Click OK to close the Add Existing File dialog. The file is added to the project file in the UI system folder (in the Workspace tab of the Workspace Window).

64

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Sample Netlinx Code To send a KPD file to a NetLinx Master, you must use the NetLinx DMS-IMS module, with the following DEFINE_MODULE entry in the Master Source Code:
DEFINE_MODULE 'DMS-IMSMod' Module_Name(Virtual_Dev, Real_Dev, strFileName, strVarTextArray)

Where: Module_Name is a unique name. For example:


DEFINE_MODULE 'DMS-IMSMod' mdlDMS (

or
DEFINE_MODULE 'DMS-IMSMod' mdlIMS (

For example:
(**********************************************) (* DEVICE NUMBER DEFINITIONS GO BELOW *) (**********************************************) DEFINE_DEVICE DvVIRT = 33001:1:0 DvDMS = 6020:1:0 (**********************************************) (* VARIABLE DEFINITIONS GO BELOW *) (**********************************************) DEFINE_VARIABLE CHAR strFileName[100] (**********************************************) (* STARTUP CODE GOES BELOW *) (**********************************************) DEFINE_START StrFileName = 'avcnt11.kpd' (**********************************************) (* VARIABLE DEFINITIONS GO BELOW *) (**********************************************) DEFINE_VARIABLE CHAR strVarTextArray[100][40]

Where:
DVVirt DvDMS StrFileName
an arbitrary Virtual Device number you define (range for keypad panels = 32768 -36863). the real device number of the DMS or IMS panel. a string variable (CHAR array) containing the file name of the KPD file to transfer or run. should be the largest variable text string number you want to use. The second dimension should be the maximum size of the string you want displayed (maximum is 40 characters). When using two or more keypad panels, you can create a single threedimensional array for a keypad panels, instead of separate two-dimensional arrays for each keypad panel.

StrVarTextArray a two-dimensional array to store variable text in. The first dimension

NetLinx Studio (v2.4 or higher)

65

Working With Systems and System Files

User Interface File Folder Context Menu Right-click on any User Interface folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing User Interface File Opens the Add Existing User Interface File dialog, where you can add an existing User Interface file to the System containing the selected User Interface folder. Docking View Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

Hide

User Interface File Context Menu Right-click on any User Interface file (in the Workspace tab of the Workspace Window) to access the context file described below:
Device Mapping Opens the Device Mapping dialog to map the selected User Interface file to a specific device on the bus.

Remove File From System Click to remove the selected User Interface file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the System. The file is not deleted from disk. Quick Load TPD/TP4 File This option allows you to access the File Transfer dialog, already configured to send the selected UI file to the Master associated with the active System. Opens the File Properties dialog, where you can view (and edit) properties for the selected UI file.

File Properties

Working With IR Files


IR files (.IRL and .IRV) contain IR control data to operate IR-controlled system devices. NetLinx Studio v2 allows you to link existing IR files into your Project/System. IR files are stored in the IR folder (in the Workspace tab of the Workspace Window). IRL files are standard IR library files. IRV files are IR files exported from the VPXpress application (for use with AMX ViewPoint wireless touch panels).
NetLinx Studio v2.0 (or later) also supports IR Database (.IRN) files. IRN files are generated in the IREdit application, and consist of a database of IR files (either the read-only AMX IR Database or a user-defined database).

Adding An Existing Ir File To A System To add an existing IR file to a selected System in the current Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the IR folder to access the IR File Folder context menu, and select Add Existing IR File. 3. In the Add Existing IR File dialog, locate and select the IR (.IRL or .IRV) file that you want to add to the selected System.

66

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. The file should now appear in the IR folder under the selected System. IREDIT IREdit is a separate application that works in conjunction with NetLinx Studio v2.0 (or later). The IREdit software application allows you to view and edit IR files. Once IREdit is installed, you can double-click on any IR file in the Workspace tab of the Workspace Window or the Find IR Files tab of the Output Display Window to open the selected IR file for viewing and editing in IREdit.
For instructions on using IREdit to view and edit IR files, refer to the IREdit on-line help.

Working With IREdit Database (*.IRN) Files NetLinx Studio supports IR Database (*.IRN) files generated in the IREdit application. IRN Database files contain many individual IR files, organized by Manufacturer, Device Category, Device Model #, and Hand Control Model #. To launch the IREdit program double-click on an IR file in the Workspace tab of the Workspace Window or double-click on an IR file in the Find IR Files tab of the Output Display Window (results of a search). For detailed instructions on using IREdit, refer to the IREdit online help file. The options in the Select IR From a Database dialog allow you to locate and select IR file(s) from within either the (read-only) AMX IR Database, or a user-defined IR database (*IRN file). Adding An IR File From the AMX IR Database If you have installed the IREdit application, the Add From AMX IR Database option is available in the Project menu, the IR File Folder context menu and the Project Toolbar.

The AMX IR Database is read-only.

To add an IR file from the AMX IR Database to your Project: 1. Select Project > Add From AMX IR Database to open the Select IR From a Database dialog, with the AMX IR Database displayed.

NetLinx Studio (v2.4 or higher)

67

Working With Systems and System Files

2. In the IR Database Navigator Window (on the left side of this dialog), start by picking the Manufacturer of the device associated with the desired IR file, and drill down through the subfolders (Product Category, Product Model Number and Hand Control Model Number) to locate and select the desired IR file (FIG. 10).

FIG. 10 IR Database Navigator Window

3. Double-click on the file (or select the file and click the Add To List button) to add the file to the Selected IR List. 4. Repeat steps 2 and 3 as often as necessary to populate the Selected IR List, and click OK to close the Select IR From a Database dialog. 5. The selected IR files are add to the selected System (in the IR system file folder).
The file(s) will be added to the selected (highlighted) System in the Workspace tab, which is not necessarily the active system.

Adding An IR File From an IREDIT User Database (*IRN) File Use the options in the Select IR From a Database dialog to access individual IR files from within an existing IREdit IR Database (*IRN) file: 1. Select Add From User IR Database from the Project menu, the IR File Folder context menu, or click the toolbar button to open the Select IRN User Database dialog. 2. Locate and select the *IRN file that contains the IR file(s) that you want to add to the selected System. 3. Click Open to open the selected IRN file in the Select IR From a Database dialog. 4. In the Select IR From a Database dialog, select the Manufacturer, Product Category, Model #, Hand Control Model # and then select the IR file to add to the System. 5. With the desired IR file selected, click Add to add the file to the Selected IR File(s) list. 6. Repeat steps 4 and 5 as many times as is necessary to add the desired files to the Selected IR File(s) list. To remove a file from the Selected IR File(s) list, select a file and click Remove. 7. Click OK to close the Select IRN User Database dialog and open the File Properties dialog, where you can change the selected file's name (Identifier) and Description if necessary. You can assign multiple different identifiers, file names and descriptions to the same file for use in different Projects and Systems, as needed. 8. Click OK to add the file to the selected System (which is not necessarily the active system). The file appears in the IR System File Folder (in the Workspace tab of the Workspace Window).

68

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

IR File Folder Context Menu Right-click on any IR folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing IR File Opens the Add Existing IR File dialog, which allows you to locate and select an IR file (*.IRL, *.IRV) to add to the System.

Add From AMX IR Database Opens the Select IR From a Database dialog, which allows you to locate and select a hand control record from within the 'AMX IR' database. Add From User IR Database Opens the Select IRN User Database dialog, which allows you to locate and select an IREdit Database file (*.IRN). Docking View Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

Hide

IR File Context Menu Right-click on any IR file in the Workspace tab of the Workspace Window to access the IR File context menu:
Device Mapping Export to IRL File Opens the Device Mapping dialog to map the selected IR file to a specific device on the bus. This option is only available if the IR file you selected was extracted from an IR Database (*.IRN) file. IR Database files come from the IREdit application, and represent either the AMX IR Database (included with the IREdit application), or a user-defined IR Database file. Once you have added an IR file from an IR Database file (via the Add From AMX IR Database or Add From User IR Database options in the Project menu, IR File Folder context menu, or Project toolbar), you can use this option to export the file as an IRL file that can then be treated as a stand-alone IR entity (independent of the IR Database file that originally contained it). Remove File From System Click to remove the selected IR file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the Project. The file is not deleted from the disk. File Properties On IRL files, this option opens the standard File Properties dialog, where you can view (and edit) properties for the selected file. For IR Database (*.IRN) files (from either the AMX IR database or a User IR Database file), this option opens the IRN File Properties dialog, which includes several fields and options that are specific to IR Database files.

NetLinx Studio (v2.4 or higher)

69

Working With Systems and System Files

Working With "Other" Files


The Other file folder (in the Workspace tab of the Workspace Window) contains all other (nonAxcess/NetLinx specific) file types that you want to include with your Project. These files are not compiled, but are saved with the Project. Use this folder to store standard text files, image files, etc.
AMX recommends that documents such as AXwires, button-by-button, system drawings, etc. should all be placed in a "_Docs" folder under the project directory on disk. This "_Docs" folder must be created in Windows Explorer. The underscore is placed in the front to ensure this folder will be located first under the project root. This makes it easier to view the overall project in Explorer.

Do not attempt to open .LIB or .SYC files for editing in the Source Code Editor. Doing so could cause program failure.

Creating a Text File To create a Standard Text (.TXT) file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select Standard Text and click OK. 3. An (empty) Standard Text file is created in a new Source Code Editor window. By default, this file is named TXT<x>.txt. 4. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 5. Specify a name and target location for the new file in the Save As dialog.
Existing Text files can be added to Systems via the Project > Add File To System command.

Adding an Existing "Other" File To a System To add an existing "Other" file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Other folder to access the Other File Folder context menu, and select Add Existing Other File. 3. In the Add Existing Other File dialog, locate and select the file that you want to add to the selected System. The Add Other dialog is set to look for .TXT files by default; change the Files of Type option to All Files (*.*) to look for other file types.

Use the Recent tab to quickly access recently used files.

4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.

70

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.

5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Other folder under the selected System. Other File Folder Context Menu Right-click on any Other folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing Other File Opens the Add Existing Other File dialog, where you can add an existing non-System type file to the System containing the selected Other folder. The new file will be added to the selected Other folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.

Other File Context Menu Right-click on any Other (non-System type) file (in the Workspace tab of the Workspace Window) to access the context file described below:
Remove File From System Click to remove the selected file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected file.

Search Operations
Using The Edit And Search Functions The Edit and Search functions are accessible via the Edit menu: The Edit > Cut, Copy and Paste options work the same in NetLinx Studio as they do in any other Windows program. The Edit > Find, Find Next and Replace options allow you to perform search and replace operations. You can search and search/replace within the active Source Code file, or search across multiple files. Searching Within the Active Source Code File Use the Find and Find Next options in the Edit menu to search within the active Source Code file: 1. Choose Edit > Find (or click the "Find" toolbar button) to open the Find dialog. 2. Enter a search string in the Find What text box.

NetLinx Studio (v2.4 or higher)

71

Working With Systems and System Files

3. Click one or more of the checkboxes to set any additional search criteria, as desired.
Match whole word only Searches for instances of the search string that exist as whole words only. For example, a search for "yell", only finds the word "yell", as opposed to any instance of the search string (i.e. "yellow"). Searches only for instances that match the case (UPPERCASE or lowercase) of the characters in the search string. Start the search at the cursor's position, and automatically loop the cursor to either the top or bottom of the file (depending on the Direction setting) to finish searching the entire file, to the cursor's position. Start the search at the top of the file (regardless of the cursor's position). Click the radio buttons to specify whether to search Up (backward) or Down (forward) relative to the cursor's current position in the file (default = Down).

Match case Loop

Start At Top Direction

4. Click the Direction radio buttons to specify the direction of the search (Up or Down). 5. Click Find Next to perform the search and close the Find dialog. The first instance of the search string is highlighted in the Source Code Editor window. 6. Choose Edit > Find Next (or click the "Find Next" toolbar button) to continue the search after the first instance of the search string is found. Search And Replace Within The Active Source Code File To perform a Search and Replace operation within the active Source code file: 1. Choose Edit > Replace to open the Replace dialog. 2. Enter a search string in the Find What box. 3. Enter the replace string in the Replace With box. 4. Click the checkboxes to set additional search options, as desired:
Match whole word only Searches for instances of the search string that exist as whole words only. For example, a search for "yell", only finds the word "yell", as opposed to any instance of the search string (i.e. "yellow"). Searches only for instances that match the case (UPPERCASE or lowercase) of the characters in the search string. Start the search at the cursor's position, and automatically loop the cursor to either the top or bottom of the file (depending on the Direction setting) to finish searching the entire file, to the cursor's position. Start the search at the top of the file (regardless of the cursor's position). Click the radio buttons to specify whether to search Up (backward) or Down (forward) relative to the cursor's current position in the file (default = Down).

Match case Loop

Start At Top Direction

5. Click Find Next to perform the search. The first instance of the search string is highlighted in the Source Code Editor window. 6. Click Replace to replace the highlighted instance of the search string with the replace string, or click Replace All to replace all instances of the search string.

72

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

The total number of replaced instances is indicated in the Status bar (on the left-hand side).

Searching Across Multiple Files To perform a Search operation across multiple files: 1. Choose Tools > Find In Files (or click the toolbar button) to open the Find In Files dialog. 2. Enter a search string (up to 255 characters) in the Find What text box.
If you select text in a Source Code Editor window before opening the Find In Files dialog, the selection appears in the Find What text box.

3. Click the In files/file types down arrow to open a list of file types to search. This selection limits the search to a specific file type. To search all files, select the *.* option from this list. You can also manually enter any three-character file extension to search for a specific type of file. 4. Specify a folder to search in the In Folder text box: a. Click the down arrow to open a list of recently searched folders. b. Click the browse button to open the Browse For Folder dialog. Use this dialog to navigate to the desired folder and click OK to return to the Find In Files dialog. 5. Select the checkboxes to enable other search options, as desired (Match whole word only, Match case, Regular Expression, Look in subfolders, and Include Hidden and System Files). 6. Click Find to perform the search. The first instance of the search string is highlighted in the Find In Files tab of the Output Display window.

To cancel a Find in Files search, click Stop Find In Files (in the Tools menu).

7. The results of the Find In Files operation are displayed in the Find In Files tab of the Output Display window, along with the total number of instances of the search string that were found in the specified directory. 8. Double-click on any file listed in the Find In Files tab to open it in a Source Code Editor window, with the cursor positioned at the beginning of the line containing the search string. Searching For Ir Library (IRL/IRV) Files Use the Find IRL/IRV Files option in the Tools menu to search for an IR file in a specific directory, based on certain search criteria: 1. Choose Tools > Find IRL/IRV Files (or click the toolbar button) to access the Find IR Files dialog. 2. Fill in the search criteria fields:
Manufacturer Enter the name manufacturer of the IR device associated with the file you are searching for.

NetLinx Studio (v2.4 or higher)

73

Working With Systems and System Files

Hand Control Model # Enter the model number for the hand-held IR remote associated with the file you are searching for. Device Model # Where To Search Enter the manufacturer's model number for the IR device associated with the file you are searching for. Use the radio buttons to select one of three ways to specify where to search for IR files: IR Files in Folder - Use this option to specify a target directory to search. Click the Browse button to select the directory to search in the Browse For Folder dialog. The first time you search within any given directory, NetLinx Studio generates an index file of all IR files in that directory. The status of this operation is indicated in the Status dialog. This only happens the first time a directory is searched. AMX IRN Database - Use this option to search the AMX IRN Database. User's IRN Database - Use this option to search for IR files within an existing User IR Database (*.IRN) file. IRN files are generated in the IREdit utility program.

Once you have entered one or more items in the search criteria fields, you can use the down arrows to the right of these fields to open and select from a list of previously entered items. For example, once you have typed "Sony" in the Manufacturer field, the next time you need to search for Sony devices, just select "Sony" from the dropdown list.

3. Click OK to begin the search, based on the specified criteria. 4. The results of the Find IRL/IRV search operation are listed in the Find IRL Files tab of the Output Display Window. The information in this tab includes the search criteria entered in the Find IR Files dialog. Double-click any item in the Find IR Files tab to open the selected IR file in the IREdit application. Right-click in the Find IR Files tab to open the Output Display window context menu.

Printing Files
You can print the active file in the Source Code Editor using the Print option in the File menu. 1. Choose File > Print Preview to open the Print Preview window, to preview the file, as it will be printed (if necessary). 2. Choose File > Print Setup to open the Print Setup dialog, to choose and configure your printer (if necessary). 3. Choose File > Print (or click the toolbar button) to print the file. Print Preview Window This option displays a preview of the file or code block in a separate window, as it will appear when printed. If a block of text (in a Source Code Editor window) is selected, the highlighted block of text will appear in the Print Preview window. Otherwise, the active file will appear for preview.

74

NetLinx Studio (v2.4 or higher)

Working With Systems and System Files

The options in the Print Preview window toolbar include:


Print Next Page Prev Page Prints the current page view Displays the next page of the selected file Displays the previous page of the selected file

One Page/Two Page Toggles the page view to one or two pages. This option is enabled only if the active file is longer than one page. Zoom In Zoom Out Close Zooms in on the page view Zooms out from the page view Closes the Print Preview window

If you don't have a printer installed on your PC, the Print and Print Preview options invoke a message alerting you to install a printer.

Print Dialog Select Print from the File menu (or click the toolbar button) to access the Print dialog. Use the options in this dialog to set preferences for your printer, and send the file in the currently active Source code Editor window to a specified printer.
Name Properties Click the down arrow to display a list of available printers. Select the target printer from this list. Click to open the Printer Setup dialog to set options specific to the selected printer. All - Click to print the entire file Pages - Click to enable the from: and to: fields where you can specify the pages that you want to print. Selection - Click to print only the currently selected (highlighted) text in the file. This option is only available if a block of text is selected in the active Source Code Editor window. Copies - Click the up and down arrow buttons to specify the number of copies to print.

Print Range Use the radio buttons to specify the range of the active file to be printed:

NetLinx Studio (v2.4 or higher)

75

Working With Systems and System Files

76

NetLinx Studio (v2.4 or higher)

Programming

Programming
Overview
Use Source Code Editor windows (FIG. 11) to display, view and edit Axcess and NetLinx source code files. You can have multiple files open at any time. Each code file is opened in a separate Source Code Editor window.

FIG. 11 Source Code Editor Window

Refer to the Source Code Editor Window - Features section on page 15 for a list of supported features.

Source Code Editor Context Menu Right-click inside any Source Code Editor window to open the Source Code Editor context menu. The options in this menu include:
Build Active System Compiles all Source Code files (and any associated Include and Module files) in the active System. Compile <active Source Code File> Compile as NetLinx Compile as Axcess Compiles the active file, using the compile type associated with the file (the compile type can be changed via the File Properties dialog). Click to compile the active file using the NetLinx compiler, regardless of it's Compile As property. Click to compile the active file using the Axcess compiler, regardless of it's Compile As property.

NetLinx Studio (v2.4 or higher)

77

Programming

Undo, Redo Cut, Copy, Paste

Undo and Redo the last text editing action. Cut the selected text to the clipboard, Copy the selected text to the clipboard, and Paste the contents of the clipboard to the active file, at the cursor position. Deletes the selected (highlighted) text in the active Source Code Editor window. Selects all of the code in the active file. Click to open the Goto Section sub-menu, which contains a listing of code sections in a Source Code File. Select a section from this list to jump to the beginning of that section in the active file. If a section that does not exist within the active code file is chosen, nothing happens. Opens the Goto Line dialog, where you can specify the line of code to which you want to move the cursor in the active file. If a line number is entered that is beyond the max number of lines in the file, the cursor is moved to the last line in the file. Inserts a bookmark at the line containing the cursor in the active file. Bookmarks are indicated by a blue box in the left margin of the Source Code Editor window. You can have as many bookmarks as number of lines in the source code. Places a breakpoint in the active file, at the cursor position (NetLinx files only). Once a breakpoint has been inserted in the file, place the cursor in the line with the breakpoint and select Toggle Breakpoint again to remove the breakpoint. Removes all NetLinx breakpoints. Select to open the Enter Text... dialog, which allows you to insert unicode characters in your code, at the cursor position in the editor.

Delete Select All Goto Section

Goto Line

Bookmark

Toggle Breakpoint

Clear Breakpoints Unicode Edit

Using The Code Wizard


Select Tools > Code Wizard to launch the NetLinx Studio Code Wizard. The Code Wizard consists of a series of dialogs that help you quickly generate various types of Axcess and NetLinx code segments. The wizard can help construct the following type of code segments: BUTTON_EVENTs CHANNEL_EVENTs LEVEL_EVENTs DATA_EVENTs SEND_COMMANDs (including G3 and G4 Send Commands) IR Constants
A source file must be open in Source Code Editor window in order to use the Code Wizard.

78

NetLinx Studio (v2.4 or higher)

Programming

Creating Events With the Code Wizard 1. In the first Code Wizard dialog, select the appropriate radio button for the type of event you want to create (BUTTON_EVENTs, CHANNEL_EVENTs, LEVEL_EVENTs or DATA_EVENTs). 2. Click Next to proceed to the next Wizard dialog. The options in the Wizard dialogs are different for each event type. The Next button is enabled in each dialog as the required information is supplied. 3. Specify the Device for which you want to create this event, and enter a comment to include in the generated code (optional). 4. Click Finish to exit the Code Wizard. The new event is placed in the active Source Code file, in the DEFINE_EVENT section. The Code Wizard also automatically updates the DEFINE_PROGRAM section, and any other parts of the source code that are affected by the addition of the new code segment. Creating Send_Commands With the Code Wizard 1. In the first Code Wizard dialog, select the I want to generate a SEND_COMMAND radio button. 2. Click Next to proceed to the next Wizard dialog, where you can specify the type of SEND_COMMAND to create (select either to Make a New Page (PAGE) or to Make a New Popup Page (@PPN)), and specify the name of the new page or popup page. This dialog also contains the option to change the text on a specified button on a touch panel, in which case you must specify the Variable Text Channel, and the replacement Text for that button. Click Next to proceed. 3. Specify the Device for which you want to create this event, and enter a comment to include in the generated code (optional). 4. Click Finish to exit the Wizard. The new SEND_COMMAND is placed in the active Source Code file, at the current cursor location. Generating Constants From an IR File With the Code Wizard 1. In the first Code Wizard dialog, select the I want to generate constants from an IR file radio button. 2. Click Next to proceed to the next Wizard dialog, where you can specify the IR file to generate constants from (use the Browse button to locate and select the file via the Open IR File dialog). Specify a comment to add to the generated code segment containing the IR constants (optional), and specify a prefix to be added to each IR constant generated (also optional). 3. Click Finish to exit the Wizard. The new IR constants from the specified file are placed in the active Source Code file, in the DEFINE_CONSTANT section.

NetLinx Studio (v2.4 or higher)

79

Programming

Code Wizard - Advanced Users The Code Wizard can be toggled to show the individual dialogs (containing detailed options) for all the above functionality that can be used by advanced users. To view the advanced options in every dialog, de-select the Wizard Style checkbox (on by default). When the Wizard generates a new code segment, it is inserted in the active Source Code file, in the appropriate section of the code. Code Wizard Dialog - Button Tab Select Tools > Code Wizard to launch the NetLinx Studio Code Wizard. De-select the Use Wizard Style checkbox to access the individual tabs containing detailed options for each code type. In NetLinx, button events are always created using the BUTTON_EVENT handler in the DEFINE_EVENT section. In Axcess, PUSHes, RELEASEs and feedback assignments are generated in the DEFINE_PROGRAM section. The items in the Button tab are described below:
Push Release Hold Feedback No Arrays Generate PUSH statements Generate RELEASE Statements Generate HOLD statement. Not supported in Axcess. Generate feedback assignments. Button Range will be generated without using arrays, i.e. multiple BUTTON_EVENTs, PUSHes or RELEASEs will be generated. This is the default option is generating code for Axcess. Button ranges will be placed in a DEVCHAN array named Array Name using the Device and button range defined as From through To in the DEFINE_VARIABLE section. A single BUTTON_EVENT statement referencing Array Name will be generated. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Button ranges will be placed in an INTEGER array named Array Name using the button range defined as From through To in the DEFINE_VARIABLE section. A single BUTTON_EVENT statement referencing Device and Array Name will be generated. This option is not available if generating code for Axcess.

Use DEVCHAN

Use INTEGER

Button Index/GET_LAST() This option will include a calculation for the button index using a mathematical calculation, BUTTON.INPUT.CHANNEL - From, for non-array button ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array button ranges. The button index calculation is used if generating code for Axcess. SWITCH/CASE This option will include a SWITCH/CASE construct under the PUSH and/or RELEASE statements. The SWITCH will be based on the Button Index. Note that when SWITCH/CASE is selected, the Button Index option is selected, and grayed out. When generating Axcess code, a SELECT/ACTIVE construct will be generated instead of a SWITCH/CASE. This option will cause each button in the Array Name definition to be generated on its own line with an empty comment at the end of the line. If this option is not selected, eight channels will be generated on each line with an empty comment above the line. This option will include the REPEAT keyword in the HOLD event handler. This option is not available when generating Axcess code.

Stacked

Hold Repeat

80

NetLinx Studio (v2.4 or higher)

Programming

Device

The device name used during code generation. This name may appear in a DEVCHAN definition, BUTTON_EVENT, PUSH, RELEASE or feedback assignment statements depending on the platform and options selected. The button range used during code generation. The range is 1 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all button" handler. In this case, code generation cannot support arrays or feedback. The array name used for generating DEVCHAN or INTEGER array for button ranges. This value is used when generating the HOLD statement. This value is used on the lines before the array definition, BUTTON_EVENT, PUSH, and RELEASE and feedback statements as determined by the options. Comments in NetLinx are always linestyle comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

From, To, Total

Array Name Hold Time Comment

Insert

Code Wizard Dialog - Channel Tab The items in the Channel tab are described below:
On Off No Arrays Use DEVCHAN Generate ON statements Generate OFF Statements Channel ranges will be generated without using arrays, i.e. multiple CHANNEL_EVENTs will be generated. Channel ranges will be placed in a DEVCHAN array named Array Name using the Device and channel range defined as From through To in the DEFINE_VARIABLE section. A single CHANNEL_EVENT statement referencing Array Name will be generated. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Channel ranges will be placed in an INTEGER array named Array Name using the channel range defined as From through To in the DEFINE_VARIABLE section. A single CHANNEL_EVENT statement referencing Device and Array Name will be generated.

Use INTEGER

Channel Index/GET_LAST() This option will include a calculation for the channel index using a mathematical calculation, CHANNEL.CHANNEL - From, for nonarray channel ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array channel ranges. The channel index calculation is used if generating code for Axcess. SWITCH/CASE This option will include a SWITCH/CASE construct under the ON and/or OFF statements. The SWITCH will be based on the Channel Index. Note that when SWITCH/CASE is selected, the Channel Index option is selected, and grayed out. This option will cause each channel in the Array Name definition to be generated on its own line with an empty comment at the end of the line. If this option is not selected, eight channels will be generated on each line with an empty comment above the line. The device name used during code generation. This name may appear in a DEVCHAN definition or CHANNEL_EVENT statement depending on the platform and options selected.

Stacked

Device

NetLinx Studio (v2.4 or higher)

81

Programming

From, To, Total

The channel range used during code generation. The range is 1 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all channel" handler. In this case, code generation cannot support arrays. The array name used for generating DEVCHAN or INTEGER array for channel ranges. This value is used on the lines before the array definition, CHANNEL_EVENT statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

Array Name Comment

Insert

Code Wizard Dialog - Level Tab The advanced options available for Level_Events (in the Level tab of the Code Wizard dialog) are described below:
Event Create Send Generate LEVEL_EVENT statements. Generate CREATE_LEVEL statements. Generate SEND_LEVEL statements. Note: You cannot generate EVENT_LEVEL statements and CREATE_LEVEL or SEND_LEVEL statements at the same time. No Arrays Use DEVLEV Level ranges will be generated without using array, i.e. multiple LEVEL_EVENTs will be generated. Level ranges will be placed in a DEVLEV array named Array Name using the Device and button range defined as From through To in the DEFINE_VARIABLE section. A single LEVEL_EVENT statement referencing Array Name will be generated. If CREATE_LEVEL and/or SEND_LEVEL statements will be generated, each construct will reference this array for the level number for NetLinx only. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Level ranges will be placed in an INTEGER array named Array Name using the button range defined as From through To in the DEFINE_VARIABLE section. A single LEVEL_EVENT statement referencing Device and Array Name will be generated. If CREATE_LEVEL and/or SEND_LEVEL statements will be generated, each construct will reference this array for the level number for NetLinx only.

Use INTEGER

Level Index/GET_LAST() This option will include a calculation for the level index using a mathematical calculation, LEVEL.INPUT.LEVEL- From, for non-array level ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array level ranges. The option is only used for LEVEL_EVENTs. SWITCH/CASE This option will include a SWITCH/CASE construct under the LEVEL_EVENT statement. The SWITCH will be based on the Level Index. Note that when SWITCH/CASE is selected, the Level Index option is selected, and grayed out. This option will cause each level in the Array Name definition to be generated on it's own line with an empty comment at the end of the line. If this option is not selected, eight levels will be generated on each line with an empty comment above the line The device name used during code generation. This name may appear in a DEVLEV definition, LEVEL_EVENT, CREATE_LEVEL or SEND_LEVEL statements depending on the platform and options selected.

Stacked

Device

82

NetLinx Studio (v2.4 or higher)

Programming

From, To, Total

The level range used during code generation. The range is 1 - 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all level" LEVEL_EVENT handler. In this case, code generation cannot support arrays. Note: The range setting (1-1000) affects the load placed on the CPU at compile time. Higher range settings may result in slower compile operations.

Array Name Value/Variable Name

The array name used for generating DEVLEV or INTEGER array for level ranges. The array name or value used for generating CREATE_LEVEL or SEND_LEVEL statements. If generating code for a level range on NetLinx, this variable will be created as an array. If generating code for a level range on Axcess, this variable will be created as a series or variable starting with this name, i.e. Variable Name 1, Variable Name 2, etc This value is used on the lines before the array definition, LEVEL_EVENT, CREATE_LEVEL, and SEND_LEVEL statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

Comment

Insert

Code Wizard Dialog - Data Tab The advanced options available for Data_Events (in the Data tab of the Code Wizard dialog) are described below:
Online Offline OnError String Command Create Buffer Generate ONLINE statements. In Axcess, a construct for detecting device online status is generated. Generate OFFLINE statements. In Axcess, a construct for detecting device offline status is generated. Generate ONERROR Statements (not supported in Axcess). Generate STRING statements (not supported in Axcess). Generate COMMAND Statements (not supported in Axcess). Define a buffer and connect it to a device using CREATE_BUFFER, in the DEFINE_START section.

Process Buffer Generate a construct for detecting incoming strings. If generating code for NetLinx, this code is placed in the STRING section of the DATA_EVENT. If generating code for Axcess, this code is placed in the DEFINE_PROGRAM section. Device The device name used during code generation. This name may appear in a variable declaration, ONLINE/OFFLINE construct, DATA_EVENT or CREATE_BUFFER statements depending on the platform and options selected. This value is used on the lines before the variable declaration, ONLINE/ OFFLINE construct, DATA_EVENT or CREATE_BUFFER statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

Comment

Insert

NetLinx Studio (v2.4 or higher)

83

Programming

Code Wizard Dialog - Send Command Tab The advanced options available for Send_Commands (in the Send Command tab of the Code Wizard dialog) are described below:
Page @T @BMF @PPN @PPF @PPK @PPX Custom Device Generate PAGE- page flip send command for touch panels. Generate @T variable text send command for touch panels. Generate @BMF variable text send command for touch panels. Generate @PPN- popup on send command for touch panels. Generate @PPF- popup off send command for touch panels. Generate @PPK- popup kill send command for touch panels. Generate @PPX- kill all popups send command for touch panels. Generate a custom send command. The device name used during code generation. This name will appear in the SEND_COMMAND statement.

Sub Command The command parameter used in the SEND_COMMAND. Depending on options, this may be the Page Name, Text to Send, @BMF sub-command, popup page name or custom command. Comment Insert This value is used on the line before the SEND_COMMAND statement. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

Code Wizard Dialog - IR Constant Tab Constants are generated from IR files. One constant is generated for every IR function and are placed in the DEFINE_CONSTANT section. The advanced options available for IR Constants (in the IR Constant tab of the Code Wizard dialog) are described below:
Device IR File The device name used during code generation. This name is used to generate the Constant Prefix field. The IR file for which you would like to generate constants.

Constant Prefix The prefix to precede all constant declaration. By default, this will be <Device>_. Comment Insert This value is used on the line before the constant declarations. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.

84

NetLinx Studio (v2.4 or higher)

Programming

Syntax Highlighting When a source file is loaded in the editor, it is read line by line. Each line is broken up into its constituent words. Technically the line is broken into tokens, but the concept of a word is more familiar to most people. Different words and groups of words are handled differently. Here is a breakdown of the mechanism used:
Comments Any portion of the line that initiates or falls within a comment is considered to be one comment (essentially it's treated as one big word). The comment is then syntax highlighted using the color specified in Preferences > Editor > Comment. When NetLinx Studio is started it loads two files: NetLinx.rw and Axcess.rw. These are the "reserved word" files. These files contain all of the words that NetLinx Studio will consider to be "Language Reserved Words". Language Reserved Words are syntax highlighted using the color specified in Preferences > Editor > Language Reserved Word. If a partial word that is typed is recognized as a reserved word, the editor will suggest its closest match. Operator All of the following operators

Language Reserved Words

= < > + - * / % ! & | ^ ~ <= >= <> && || ^^


and the longer forms:

BOR AND XOR NOT BAND BNOT BXOR OR


are syntax highlighted using the color specified in Preferences > Editor > Operator. Floating Point Numbers Number A number is considered a floating point number if it contains a decimal point. Floating point numbers are syntax highlighted using the color specified in Preferences > Editor > Floating Point Number. A number is any series of digits that does not include a decimal point. A number may have the optional prefix "$" for hex or the optional postfix "b" for binary. If the number is a hexadecimal number then it may contain the letters A-F or a-f. Numbers are syntax highlighted using the color specified in Preferences > Editor > Number. Strings are any series of characters and digits that occur within two single quotes. Strings are syntax highlighted using the color specified in Preferences > Editor > String. Since NetLinx code may be divided into the following sections DEFINE_CONSTANT, DEFINE_DEVICE, DEFINE_TYPE, DEFINE_VARIABLE, anytime a word is encountered that falls within one of these sections it is parsed, remembered and then syntax highlighted according to the section in which it occurred. So if a DEFINE_DEVICE section contains a line that reads "dvTP = 128" the word dvTP will be remembered as a device and syntax highlighted using the color specified in Preferences > Editor > Device. Additionally, if the editor recognizes that you have partially typed the name of the above section variable (say "dv"), it will autosuggest "dvTP". It does this for all of the items it encountered in any of the above DEFINE_ sections. Default Text Any word that is not recognized as any of the above is syntax highlighted using the color specified in Preferences > Editor > Default Text.

String

Constants, Devices, Type, Variable

Default Syntax Highlighting Colors The text in the Source Code Editor windows is syntax highlighted with color codes for increased readability with a default set of colors that can be customized via the options in the Editor tab of the Preferences dialog. Syntax Highlighting assigns different colors to different types of data in your Source Code file.

NetLinx Studio (v2.4 or higher)

85

Programming

Use chroma-coding to make your code easier to read and manage. For example, you could chromacode all comments to yellow, all identifiers to red and strings to blue to make them more easily identifiable in your code file. The text elements that can be chroma-coded, and their default color assignments are listed below:
Comments Default Text Floating Point Number green red dark green

Language Reserved Word blue Number Operator teal red Note: All of the following color as operators: =, <, >, +, -, *, /, %, <=, >=, <>, AND, OR, XOR, NOT, BAND, BOR, BXOR, BNOT, &&, ||, ^^, !, &, |, ^, ~ String maroon

AutoComplete and AutoSuggest You may enable or disable this feature by toggling the Enable AutoComplete/AutoSuggest checkbox in the Editor tab of the Preferences dialog. With this option enabled, the Editor can automatically complete typing many common and standard programming terms for you. When you begin typing in the editor, a drop-down list of probable matches for the term you started typing is displayed. Auto-Suggest will suggest a single word if that word matches something that has already been typed. Auto-Suggest will drop the rest of the word that has been typed (to the right of the cursor) when a suggestion is selected. Use the scroll bar to scroll through the list (if necessary) and click to select the desired term or phrase that you want to insert at the cursor's position. Double-click or press the Tab key (or Enter on your keyboard) to insert the selection. In the example below (FIG. 12), the user has typed the character "D", and is selecting to insert the phrase "DEFINE_EVENT" into the code. The selection always replaces the character(s) typed before the AutoComplete/AutoSuggest drop-down was invoked.

FIG. 12 Autocomplete And Autosuggest example

Note that AutoComplete/AutoSuggest is case-sensitive. Typically section headings are capitalized, and commands are not. Use the Edit > Rescan Current Source File option to rescan the active file, in order to rebuild the symbol information utilized by the AutoComplete/AutoSuggest feature.

86

NetLinx Studio (v2.4 or higher)

Programming

With AutoComplete/AutoSuggest enabled, as you type in a variable name, device name or a reserved identifier, the program will suggest a name that has been previously defined within the source code. When the editor makes a suggestion, you may choose to accept the suggestion by hitting the TAB key (or a different keystroke as defined in the Keyboard tab of the Preferences dialog). However, if the suggestion is not what you intended, you may choose to have the editor display it's next suggestion. You can cycle through all of the suggestions by using the keystroke defined in the Keyboard tab of the Preferences dialog (the Next Suggestion item in the Advanced Editor category). There is no default keystroke assignment for Next Suggestion (to avoid conflicting with pre-existing custom keystrokes). You must set your own keystroke to take effect. Use the Edit > Rescan Current Source File option to rescan the active file to rebuild the symbol information used by the AutoComplete and AutoSuggest features. Stack Variables/Parameters only auto-suggest when they are within the scope of the CALL, FUNCTION or EVENT that they were declared in. Call Tips Call tips are similar to the AutoComplete and AutoSuggest functions, except that Call Tips assist you with adding declared functions by displaying a list of parameters that are valid for the particular function you are adding. Call Tips are shown for declared functions when: A function name is followed by an open parenthesis. A single-quoted call name is followed by an open parenthesis. A single-quoted system call name is followed by an open parenthesis. The application displays a list of calls when the word "CALL" is followed by a single quote. It displays a list of System Calls when the word "SYSTEM_CALL" is followed by a single quote as shown in FIG. 13:

FIG. 13 Call Tips

The list of calls is in alphabetical order (with the very first item highlighted by default) - type the first letter of the desired call to jump to that point in the list. Use the scroll bar to scroll through the list of calls and click to select the item that you want to insert at the cursor's position. Double-click, or press the Tab key (or Enter on your keyboard) to insert the selection. In the example below, the user entered SYSTEM_CALL, then selected 'LDP1F', and added a space and an open single-quote to receive the following Call Tip:

NetLinx Studio (v2.4 or higher)

87

Programming

FIG. 14 Call Tips

The Call Tip displays a list of parameters that are valid for the particular function you are adding (separated by commas), with the current parameter being entered in bold (DEV DECK in the example above).
You may enable or disable this feature by toggling the Enable Call Tips checkbox in the Editor tab of the Preferences dialog.

Code Folding Fold levels can be used to simplify the view in the Source Code Editor windows by allowing you to "fold" each major section of the code (DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) so that only the header row is visible. This way, you only see the section(s) that you are actually working in. Fold levels can be collapsed and expanded, in much the same way as the tree structures that occur in the Workspace window. Fold levels that are collapsed are indicated by a blue plus sign (+) to the left of the line containing that section's header row. Fold levels that are expanded are indicated by a red minus sign (-) to the left of the line containing that section's header row. In FIG. 15, all fold levels are collapsed except DEFINE_CONSTANT (in this example there are no data type definitions).

FIG. 15 Code Folding

In order to use fold levels, you must first enable the option in the Editor tab of the Preferences dialog (by default, this option is disabled). Once the Enable Code Folding option is enabled, use the Expand All Fold Levels and Collapse All Fold Levels options (via either the Edit menu or the Edit toolbar) to control the fold levels (FIG. 16):
Expand All Fold Levels -Select this option to automatically expand all fold levels in the active file. Collapse All Fold Levels - Select this option to automatically collapse all fold levels in the active file. FIG. 16 Code Folding options

88

NetLinx Studio (v2.4 or higher)

Programming

If the Enable Code Folding option has not been enabled, these two options are unavailable. Also note that the application will remember your last code folding settings when the file is closed, so they will still be in place the next you open the file (v2.4 or later). Unicode Characters To insert unicode characters into the active Source Code file, at the cursor's position: 1. Select Unicode Edit from the Edit Menu or the Source Code Editor Context Menu to access the Enter Text... dialog. 2. Type one or more characters in the upper text field to display the characters' unicode send command value in the lower (read-only) window. 3. Press OK to insert the unicode send command value in the code, at the cursor's position. UTF-8 Encoding In the Save As dialog, select UTF-8 from the Encoding menu to enable UTF-8 support for new files, to help NetLinx Studio files to work better with other editors. You can also select the Enable UTF-8 Encoding option in the Editor tab of the Preferences dialog.
You may also encode files created with a previous version of NetLinx Studio by choosing "Save-As" and selecting the UTF-8 encoding.

Insert Section The Insert Section option allows you to insert a particular section heading in your code, at the cursor's position. This option is available via the Edit menu, the Source Code Editor context menu, or the Edit toolbar.

This command only works on the open Source Code Editor window.

1. Select Edit > Insert Section to access the Insert Section sub-menu. 2. Position the cursor at the beginning of the line that you want to add the section heading to. 3. Select the section heading that you want to add from the sub-menu. The available options are:
NetLinx: DEFINE_DEVICE DEFINE_CONSTANT DEFINE_TYPE DEFINE_VARIABLE DEFINE_LATCHING DEFINE_TOGGLING DEFINE_VARIABLE DEFINE_LATCHING DEFINE_TOGGLING Axcess: DEFINE_DEVICE DEFINE_CONSTANT

DEFINE_MUTUALLY_EXCLUSIVE DEFINE_MUTUALLY_EXCLUSIVE DEFINE_CONNECT_LEVEL DEFINE_START DEFINE_CONNECT_LEVEL DEFINE_START

NetLinx Studio (v2.4 or higher)

89

Programming

DEFINE_MODULE DEFINE_EVENT DEFINE_PROGRAM DEFINE_PROGRAM

4. The section heading is added at the cursor's position. Goto Section The Goto Section option allows you to jump to a particular section in your code. This option is available via the Edit Menu, the Source Code Editor context menu or the Edit toolbar. 1. Select Edit > Goto Section to access the Goto Section sub-menu. 2. Select the section that you want to jump to from the sub-menu.
The Insert Section and Goto Section sub-menus may include sections that are not defined in the Source Code file being edited. The valid commands for the System type will be available whether they are actually in the file or not.

3. The cursor jumps to the top of the selected section in the open Source Code Editor window. Goto Line Select Goto Line from the Edit menu, the Source Code Editor context menu (or click the toolbar button) to jump to a particular line number in your code.
To display line numbers in the Source Code Editor windows, select the Show Line Numbers option in the Editor Options tab of the Preferences dialog.

1. Right-click inside a Source Code Editor window to access the Source Code Editor context menu, and select Goto Line to access the Goto Line dialog. 2. Enter the line number in the Enter Line Number field and click OK to jump to the specified line number in the open Source Code Editor window. Goto Function Or Subroutine The Goto Function or Subroutine toolbar command allows you to jump to a particular section in your code, in the active Source Code Editor window. 1. Click the Goto Function or Subroutine toolbar button to access a list of functions contained within the active Source Code file. 2. Select the function or subroutine that you want to jump to from the list. 3. The cursor jumps to the top of the selected section in the Source Code Editor window. Block Comment - Uncomment Select Edit > Block Comment - Uncomment (or click the toolbar button) to toggle one or more selected lines of code to and from being a comment (by inserting two forward slashes at the beginning of the line containing the cursor).
Since the Block Comment-Uncomment command is a toggle function, in order to "uncomment" a block the first character set must be a double forward slash (//). Without the double forward slash, the selected block will be commented (rather than "uncommented).

90

NetLinx Studio (v2.4 or higher)

Programming

Case Inversion Use the case inversion tools in the Edit menu (or the Edit toolbar) to quickly switch selected characters in the Source Code Editor window: Make Selection Uppercase - Changes all selected characters in the file to uppercase. Make Selection Lowercase - Changes all selected characters in the file to lowercase. Invert Case - With text selected in the Source Code Editor window, click this option to invert the case of the selected text. All uppercase characters become lowercase, and viceversa. Clipboard Text Buffer Select Edit > Clipboard Buffers (or click the toolbar button) to access a listing of the contents of the clipboard text buffer. Use this feature to reuse multiple text blocks that have been copied in the Source Code Editors. To retrieve text from the Clipboard Buffer and insert it into the active code file: 1. Copy (or cut) a selection from a code file (in a Source Code Editor window). 2. Position the cursor in the file at the point that you want to insert the copied text.
You can copy and paste across files, so you don't have to paste it into the same file it was copied from.

3. Select Edit >Clipboard Buffers (or click the toolbar button). This displays a list of all items currently stored in clipboard memory. Any text that has been cut or copied to clipboard memory is shown in the list, starting with the most recent entry. 4. Click on the item in the list that you want to insert into the active code file. The selected clipboard item is inserted into the active file at the cursor's position. Using The Clipboard Text Buffer The Clipboard Text Buffer allows you to copy multiple selections from the Source to clipboard memory as separate items that you can selectively paste from the clipboard. You can have up to 30 clip-board buffer items. The maximum display width is 80 characters. Clipboard items are not saved when the application terminates. To use the Clipboard Text Buffer: 1. Highlight a selection of code in a Source Code Editor window. 2. Press Ctrl+C to copy the selection to the clipboard. 3. Highlight another selection of code in a Source Code Editor window. 4. Press Ctrl+C to copy this selection to the clipboard as well. 5. Place the cursor in the location that you want to paste one of the copied items (in a Source Code Editor window).

NetLinx Studio (v2.4 or higher)

91

Programming

6. Click the Clipboard Text Buffer toolbar button to access a list of items in the Clipboard Text Buffer. 7. Click an item in the list to paste it into the active Source Code Editor window, at the cursor location. Find Matching Brace Select Edit > Find Matching Brace (or click the toolbar button) to quickly locate the second (matching) brace in a set. With the cursor on one brace in a Source Code Editor window, click Find Matching Brace to move the cursor to the other (matching) brace in the set. Sequentially Renumber Selection Click Edit > Sequentially Renumber Selection (or click the toolbar) to re-arrange the selected text in the Source Code Editor window to make all numbers in the code (i.e. device numbers, channel numbers, etc) fall into ascending sequential order. Show Whitespace Select Edit > Show Whitespaces (or click the toolbar button) to place dots in the Source Code Editor window to indicate "whitespaces" (spaces and tabs) in the code. By default, this option is disabled. Show End Of Line Select Edit >Show End Of Line (or click the toolbar button) to toggle the display of the end of each line of code (indicated by "CRLF") as black text on a red background, as opposed to the default view which indicates the end of each line with a red bar. By default, this option is disabled. Rescan Current Source File Select Edit > Rescan Current Source File (or click the toolbar button) to rescan the active Source Code (*.AXS) file, in order to rebuild the symbol information utilized by the Auto-Complete/AutoSuggest feature. Advanced Editor Commands The following commands/keyboard movements are supported by the Source Code Editor:
Action Select None Delete Selection Delete All Select Word Select Word Left Description removes any selection. deletes whatever is selected. Equivalent to hitting the delete key when you have a selection. deletes everything. Clears the document. selects the nearest word to the cursor. selects from the cursor to the start of the word.

Select Word Right selects from the cursor to the end of the word Select Line Select Line Left Select Line Right selects the current line at the cursor selects from the cursor to the beginning of the line selects from the cursor to the end of the line

92

NetLinx Studio (v2.4 or higher)

Programming

Delete Word Delete Word Left

deletes the current word at the cursor deletes from the cursor to the start of the word

Delete Word Right deletes from the cursor to the end of the word Delete Line Delete Line Left Delete Line Right deletes the current line at the cursor deletes from the cursor to the beginning of the line deletes from the cursor to the end of the line

None of these commands have default keyboard hotkeys assigned. To assign hotkeys, use the Keyboard tab of the Preferences dialog (select Advanced Editor from the Category drop-down list).

Supported Regular Expression Special Characters The following regular expression special characters are supported for Regular Expression search operations:
Special Character Description

. \( \) \n

Matches on any character. This marks the start of a region for tagging a match. This marks the end of a tagged region. Where n is 1 through 9 refers to the first through ninth tagged region when replacing. For example: if the search string was Fred\([1-9]\)XXX and the replace string was Sam\1YYY, when applied to Fred2XXX this would generate Sam2YYY. This matches the start of a word. This matches the end of a word. This allows you to use a character x that would otherwise have a special meaning. For example: \[ would be interpreted as [ and not as the start of a character set. This indicates a set of characters. For example: [abc] means any of the characters a, b or c. You can also use ranges. For example: [a-z] for any lower case character. The complement of the characters in the set. For example: [^A-Za-z] means any character except an alphabetic character. This matches the start of a line (unless used inside a set, see above). This matches the end of a line. This matches 0 or more times. For example: Sa*m matches Sm, Sam, Saam, Saaam and so on. This matches 1 or more times. For example: Sa+m matches Sam, Saam, Saaam and so on.

\< \> \x [...] [^...] ^ $ * +

Cut, Copy And Paste NetLinx Studio supports Cut, Copy and Paste functionality in the Source Code Editor: Select Edit > Cut (or click the toolbar button) to cut the selected text to the clipboard. Select Edit > Copy (or click the toolbar button) to copy the selected text to the clipboard. Select Edit > Paste (or click the toolbar button) to Paste the contents of the clipboard to the active file, at the cursor position.

NetLinx Studio (v2.4 or higher)

93

Programming

Undo/redo NetLinx Studio supports Undo and Redo functionality in the Source Code Editor: Click Edit > Undo (or click the toolbar button) to undo the last action. Click Edit > Redo (or click the toolbar button) to redo (repeat) the last action.

Working With Bookmarks


NetLinx Studio allows you to place bookmarks in your program files for quick navigation to key points in the code. Use the bookmarks commands in the Edit menu to create, jump to and clear bookmarks. To create a bookmark, place the cursor in the line that you want to bookmark, and select Bookmark from the Edit menu, the Source Code Editor context menu, or use the toolbar button. The bookmark is indicated by a blue rectangle in the left margin of the Source Code Editor window. Use the Next Bookmark and Previous Bookmark options to jump to your bookmarks. Use the Clear Bookmarks command to clear all bookmarks in the Source Code Editor window.

Debugging
Debugging Source Code Files NetLinx Studio contains several useful options for debugging your Master Controller and Source Code files.
The Debugging feature allows you to view variables declared within the scope of a Function and or Call procedure. However, stack and parameter values are not editable. If you attempt to edit either the stack or parameter values, a warning message is displayed.

In order to begin debugging, your computer must be connected to a Master Controller, and you must have a compiled Source Code file active. To use debugging, the Build With Source option must be selected in the Axcess Compiler and/or NetLinx Compiler tabs of the Preferences dialog, before the file is compiled. For NetLinx code, select You cannot compile, send/receive files, or change port settings while the program is in debug mode. Avoid declaring variables as volatile whenever possible, since volatile variables will not display their contents during the debug session. NetLinx character strings by default are displayed in current length mode, while all other strings (including Integer strings) are displayed in total length mode.

94

NetLinx Studio (v2.4 or higher)

Programming

To enter debug mode: 1. Open and compile a Source Code file (that contains at least one variable), if you have not already done so. The file must be successfully compiled before you can enter debug mode. 2. Choose Build > Debug (or click the toolbar button) to open the Watch window. If this option is disabled, make sure your Master Communications Port settings are set to connect to your Master Controller. 3. Right-click inside the Watch window to open the Watch Window context menu. 4. Click Add to insert a new variable in the Watch window. A box appears in the window, with a cursor blinking in the Name column. 5. Type the syntax of the variable exactly as it is defined in the code and press the Enter key. The value of the specified variable appears next to the variable (in the Value column). 6. You can select different view formats for the Value by right-clicking on the line containing the variable/value, and clicking on Display in the Watch window context menu. This opens the Display sub-menu, containing the following view options:
ASCII Display Decimal Display displays the value of the watched variable in ASCII format. displays the value of the watched variable in decimal format.

Hexadecimal Display displays the value of the watched variable in hexadecimal format. Octal Display Binary Display displays the value of the watched variable in octal format. displays the value of the watched variable in binary format.

To exit Debug mode, close the Watch window. Using Single-step Mode In Single-step mode, program execution is suspended between each pass through mainline, allowing you to test programs one line at a time. Single-step mode works differently in NetLinx than it does in Axcess: In NetLinx systems it executes a single instruction in the source file In Axcess systems it executes a single line of code in the Mainline To use Single-step mode: 1. Right-click on a watched variable and choose Debug > Single Step (or click the toolbar button) to put the Master into single-step mode. 2. With the watched variable selected, select Debug > Single Step (or click the toolbar button). This command executes mainline one time and breaks.
In NetLinx, you can use breakpoints with single-step mode. When the breakpoint is encountered (and the program is suspended), you can single-step without a watched variable reference.

NetLinx Studio (v2.4 or higher)

95

Programming

Master Controller Debug Options The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of variables within a compiled Axcess or NetLinx program. Also, you can control the execution through each pass of the mainline of a compiled Axcess or NetLinx program. Once Start Debugging has been selected, the other options in the Debug menu become available:
Start/Stop Debugging Ability to toggle the debug state of the application. There is no limitation on then number of NetLinx variables that can be watched in the Debug Watch windows. A maximum of 10 watch variables are allowed when debugging an Axcess master controller. Step Mode Enable/Disable Step mode causes the Interpreter to break after each execution of the mainline. Watch variables are always updated after each pass through mainline. To continue program execution while in Step mode, you must invoke the "Step" command again. Execute one line of a source code file at a time for a NetLinx master controller or execute one pass through the mainline code for an Axcess controller.

Single Step

The following options are only needed for debugging code located on a NetLinx master controller:
Run Run To Cursor Break Edit Breakpoints To continue execution after a Single Step operation or from a toggled break point. Execute the program and break on the line of code where the cursor is residing on the screen. Stop execution of the program and highlight the line of code on the screen. A dialog box appears listing all the break points within the code.

Toggle Break Point Toggle a break point on the screen where the cursor is residing. A red diamond appears next to the line of code to signify a break point. Clear Break Points Clears all the break points within the source code file.

Changing The Value Of A Watched Variable Once you have entered Debug mode, you can change the name and/or value of any watched variable, via the Value column in the Watch window: 1. Select a watched variable in the Watch window. 2. To change the variable's value, double-click on the desired variable's value to change the value to an edit field, which you can modify as desired. Debug Mode Error Messages The most common warnings that you may get when entering Debug Mode (Debug > Start Debugging) are: 1. No Debug Symbols: The source code file was not compiled with debug symbols - this can usually be ignored if you're only watching variables, but if you're getting weird behavior, recompile with "Compile with Debug Info" enabled (in the NetLinx Compiler tab of the Preference dialog). You will always need debug symbols for breakpoint debugging.

96

NetLinx Studio (v2.4 or higher)

Programming

FIG. 17 No Debug Symbols

2. File no longer matches:

FIG. 18 File no longer matches

If you've made any changes to the source file, including a re-save, you'll get a message similar to the one above. It can often be safely ignored, but select No if you've done any significant editing. 3. Missing files

Breakpoints
Using Breakpoints (NetLinx Only) While Single Step Mode allows you to execute a single line of code in the Mainline in Axcess systems, NetLinx systems allow you to use Breakpoints to execute a single instruction in the source file. You can set a breakpoint on any line of code (other than a comment) that is within the DEFINE_PROGRAM section. The following is an example of a SEND_LEVEL breakpoint:
PUSH[dvLocalTP3,1] PUSH[dvLocalTP3,2] { fTestLevel=fTestLevel + 1; SEND_LEVEL dvLocalTP3,1,fTestLevel; }

Note that semicolons are used in the example to terminate each line in a breakpoint. The only time that the semicolon is absolutely necessary is when a breakpoint is set at the last line of code. To keep things simple, consider terminating each breakpoint with a semicolon. Setting A Breakpoint 1. Place the cursor on a line of code in the DEFINE_PROGRAM section (other than a comment). 2. To insert the breakpoint at the cursor position, right-click to open the Source Code Editor context menu, and select Toggle Breakpoint, or use the Toggle Breakpoint toolbar button. 3. A red arrow appears in the Source Code Editor window, to the left of the cursor position. A green bar highlighting the line of code, and the execution arrow (a little green arrow) indicate the current execution point.

NetLinx Studio (v2.4 or higher)

97

Programming

To execute the next line of code, right-click and choose Step Into. You'll see the execution pointer advance one line. If you no longer need to single step, right-click and choose Run.
If you are not currently debugging, you won't see execution break until you start debugging (Debug > Start Debugging).

Clearing Breakpoints You clear an individual breakpoint, or clear all breakpoints in a file: To clear an individual breakpoint - Place the cursor on a line of code containing a set breakpoint, and choose Debug > Toggle Breakpoint, or use the Toggle Breakpoint toolbar button to unset the breakpoint on that line. To clear all breakpoints in a file - Choose Debug > Clear All Breakpoints, or use the Clear All Breakpoints toolbar button. Editing Breakpoints Select Debug > Edit Breakpoints (or click the toolbar button) to access the Breakpoints dialog. Use the options in this dialog to toggle any breakpoints set in the active (NetLinx) Source Code file.

PUSH Messages
Select Diagnostics > Enable Push Message Status Bar Display (or click the toolbar button) to display Push message status (Enabled/Disabled):
By default, Push Messages are disabled, as indicated in the Status Bar. Push Messages are enabled via the Diagnostics menu or the Diagnostics toolbar. Once the Push Message Status Bar display is enabled, you can send Push messages to the Master, via the Emulate a Device dialog. The Push Message Status Bar display then shows the D:P:S and Channel information for the most recently received Push

Left- click within the Push Message Status Bar display to view a list of recently received Push messages: FIG. 19 PUSH Messages

Insert Push Message Dialog Select Insert Push Message from the Edit menu to open the Insert Push Message dialog. This dialog displays a list of recent Push messages that were sent to the Master. Click to select a Push from the list, and click OK to insert the code for that Push message at the cursor's position in the active code file.

98

NetLinx Studio (v2.4 or higher)

Programming

Find Push Message Dialog Select Find Push Message from the Edit menu to open the Find Push Message dialog. This dialog displays a list of recent Push messages that were sent to the Master. Select a Push from the list, and click OK to locate the selected Push message code in the active file.

Working With Unicode


NetLinx Studio (v2.4 or higher) supports 16-bit Unicode characters. You can type Unicode character literals strings into you program, assigned them to variables, manipulate them using string operations, read and write Unicode characters to the file system and send Unicode strings to user interfaces for display. Configuring NSX For Unicode Support Before you begin to work with Unicode, you must enable the UTF-8 Unicode option in NetLinx Studio. This option will tell Studio to store your file as UTF-8, which will support Unicode characters. Enabling UTF-8 1. Choose Settings > Preferences to open the Preferences dialog. 2. Select the Editor tab. 3. Under Display, check the Enable UTF-8 format checkbox. 4. Close the Preferences dialog. Enabling Unicode Compiling 1. Choose Settings > Preferences to open the Preferences dialog. 2. Select the NetLinx Compiler tab. 3. Under Options, check the Enable _WC Preprocessor checkbox. 4. Close the Preferences dialog. Including the Unicode Library The Unicode Library is implemented in a NetLinx Include file, UnicodeLib.axi, that must be included in your program in order to access the Unicode functions. The Unicode Library is located in an Include file located in the C:\Program Files\Common Files\AMXShare\AXIs directory. Because this location is the default Include search path, you do not need to specify the directory in the include statement. To include the Unicode Library to your program add these lines to your program:
(***********************************************************) (* INCLUDE FILES GO BELOW *) (***********************************************************) #INCLUDE 'UnicodeLib.axi'

NetLinx Studio (v2.4 or higher)

99

Programming

Defining a Unicode String Literal To enter Unicode characters into your program, enclose the characters in single quotes, like you would any other string, and wrap the string literal in the Unicode macro _WC. Example:
_WC('Your string goes here') All Unicode string literals must be wrapped in the _WC macro. Failing to wrap a Unicode string in the _WC macro will result in a compiler error.

Storing a Unicode String Unicode strings are stored in WIDECHAR arrays, similar to the way ASCII strings are stored in CHAR arrays. To define a WIDECHAR constant or variable and initialize it using a Unicode string literal, use the following syntax:
WIDECHAR wcMyString[] = _WC('My String') The "wc" prefix is Hungarian notation for widechar. This is simply a programming convention and is completely optional. Hungarian notation helps you better identify your variables while you are programming and is a general recommended standard. For more information, see Wikipedia's Hungarian Notation page.

Working With Widechar Arrays and Unicode Strings Working with WIDECHAR arrays and Unicode strings is very similar to working with CHAR arrays and ASCII strings. Most operation that can be performed on a CHAR array can be performed on a WIDECHAR array. For instance, to assign a string to a variable use this syntax:
wcMyString = _WC('My String')

The string functions defined for CHAR arrays have been defined for WIDECHAR array for use in Unicode programming. These functions allow you to operate on strings similar to the way you would with CHAR array. For instance, to remove the first 3 characters from a WIDECHAR array and return those characters as a WIDECHAR array, use WC_GET_BUFFER_STRING:
wcRemoved = WC_GET_BUFFER_STRING(wcMyString,3)

You will find that most other function work exactly as their CHAR counterpart do except they work on and return WIDECHAR arrays. The list of Unicode compatible functions is:
WC_COMPARE_STRING WC_GET_BUFFER_CHAR WC_GET_BUFFER_STRING WC_LEFT_STRING WC_FIND_STRING WC_LENGTH_STRING WC_LOWER_STRING WC_MAX_LENGTH_STRING WC_MID_STRING WC_REMOVE_STRING WC_RIGHT_STRING WC_SET_LENGTH_STRING WC_UPPER_STRING

100

NetLinx Studio (v2.4 or higher)

Programming

Unicode - Character Case Mappings Converting between upper and lower case is accomplished by using the Unicode.org character database to determine the mapping between upper case and lower case characters. Not all Unicode characters have an upper or lower case equivalent; these characters will not be affected by WC_UPPER_STRING and WC_LOWER_STRING. Only the characters defined by Unicode.org as having an upper or lower case mapping are affected by these functions.
For more information on Unicode character conversion, see the Unicode.org character conversion FAQ.

Unicode - Concatenating String Unicode strings and WIDECHAR array cannot be concatenated using the same syntax that ASCII strings use. In NetLinx, string expressions are enclosed in double quotes and can only contain 8-bit strings. To concatenate Unicode strings and WIDECHAR arrays, you must use the WC_CONCAT_STRING function:
wcMyString = WC_CONCAT_STRING(_WC('First name'),_WC(' SurName'))

If you attempt to concatenate Unicode strings or WIDECHAR arrays using NetLinx string expressions, expect data loss. Unicode - Converting Between WIDECHAR and CHAR On occasion, you may need to convert a CHAR array to a WIDECHAR array or a WIDECHAR array to a CHAR array. The CH_TO_WC and WC_TO_CH functions can be used to accomplish these conversions. For example:
wcMyString = CH_TO_WC('Any ASCII string') wcMyString = CH_TO_WC(cMyString) cMyString = WC_TO_CH(_WC('Any Unicode string')) cMyString = WC_TO_CH (wcMyString)

When converting from WIDECHAR to CHAR, Unicode characters are converted to '?'. Any ASCII or extended ASCII characters, i.e. 8-bit characters, contained in the WIDECHAR array will appear in the CHAR array. Converting from CHAR to WIDECHAR never results in loss of data. Unicode - Using FORMAT The NetLinx Unicode library does not include a Unicode compatible FORMAT function. In NetLinx, the format function is used to convert numbers to text. To use FORMAT with Unicode string, use FORMAT to convert the number to a CHAR array and then use CH_TO_WC and WC_CONCAT_STRING to combine the result with an existing WIDECHAR array. The following two syntaxes are functionality equivalent:

NetLinx Studio (v2.4 or higher)

101

Programming

fTemperature = 98.652 cMyString = FORMAT('The current temperature is %3.2f',fTemperature) -----------------------------------------------------------------------fTemperature = 98.652 cTempString = FORMAT('%3.2f',fTemperature) wcMyString = _WC('The current temperature is ') wcMyString = WC_CONCAT_STRING(wcMyString,CH_TO_WC(cTempString))

Unicode - Reading and Writing To Files The NetLinx Unicode library supports reading and writing of WIDECHAR arrays. The WC_FILE routines operate the same as the FILE routines with the exception of FILE_OPEN. WC_FILE_OPEN takes an additional parameter; the file format. The WC_FILE_OPEN returns a special file handle so it is important to only use the file handle returned by WC_FILE_OPEN with other WC_FILE functions and the file handle used with WC_FILE functions must have been obtained by calling WC_FILE_OPEN. The NetLinx Unicode library supports three different file formats for compatibility with files created on a computer. Windows Notepad supports the same three file formats so files created in Notepad can be read using the WC_FILE routines and files created using the WC_FILE routines can be read with Notepad. When reading or appending to file, the file format is automatically determined when the file is opened. You can pass in a variable to WC_FILE_OPEN and the function will set the variable to the file format that was detected. When writing files, the file format parameter will determine how data is written to the file. The following constants can be used for specifying or checking the file format: WC_FORMAT_UNICODE, WC_FORMAT_UNICODE_BE, WC_FORMAT_UTF8. The Unicode file format, specified by the constant WC_FORMAT_UNICODE, is the fastest to encode and decode. You should use this format unless you have a particular application that requires either UTF-8 or Unicode BE encoding. The WC_FILE_READ/WRITE functions take the number of characters that will be read or written to the file. However, the functions return the number of bytes read or written to the file, not the number of characters. For Unicode and Unicode BE encoding, there are 2 bytes for every character. For UTF-8 encoding, the number of bytes for every character varies depending on the character. Unicode filenames are not supported. The parameter for the file name is a CHAR array. Always use a non-Unicode name for the file. The following file functions support WIDECHAR arrays:
WC_FILE_OPEN WC_FILE_CLOSE WC_FILE_READ WC_FILE_READ_LINE WC_FILE_WRITE WC_FILE_WRITE_LINE

Unicode - Send Strings To A User Interface Sending a WIDECHAR array to a user interface is accomplished using WC_TP_ENCODE. WC_TP_ENCODE takes a WIDECHAR array and returns a CHAR array formatted for a user interface UNI or BAU command.
cMyString = WC_TP_ENCODE(wcMyString) SEND_COMMAND dvTP,"'^UNI-1,0,',cMyString "

102

NetLinx Studio (v2.4 or higher)

Programming

Right-to-Left Unicode Strings Right-to-Left Unicode languages are stored in memory the same way left-to-right language are. The first memory position of an array contains the first logical character. You can access the rightmost character of a Right-to-Left Unicode string using this notation:
wchChar = wcString[1]

Right-to-left languages are not stored differently than left-to-right languages, they are simply rendered differently than right to left languages. However, note that the functions WC_LEFT_STRING and WC_RIGHT_STRING remove a number of characters from the start and end of a string respectively. Using WC_LEFT_STRING on a right-to-left language will return the number of right-most, i.e. first, characters you requested, not the left-most, i.e. end, characters. WC_LEFT_STRING returns the number of characters request from the front of the string and WC_RIGHT_STRING return the number of characters requested from the end of the string, regardless of the language's orientation. Unicode - Compiler Errors The most common type of compiler errors you will encounter while programming for Unicode are caused by not wrapping Unicode string literals in _WC, passing a WIDECHAR to a function that take a CHAR array or passing a CHAR array to a function that takes a WIDECHAR array. If you forget to wrap a Unicode string in _WC, expect to see the following compiler error: On the line where the string is defined:
C10571: Converting type [string] to [WIDECHAR]

On the line where the constant or variable is used:


C10585: Dimension mismatch: [1] vs. [0] and C10533: Illegal assignment statement

If you try to pass a CHAR array to a function that expects a WIDECHAR array, expect to see the following compiler error: On the line where the function call is made:
C10585: Dimension mismatch: [1] vs. [0] and Type mismatch in call for parameter [WCDATA]

If you try to pass a WIDECHAR array to a function that expects a CHAR array, expect to see the following compiler error: On the line where the function call is made:
C10585: Dimension mismatch: [1] vs. [0] and Type mismatch in call for parameter [A]

Parameter names might not match those listed above.

NetLinx Studio (v2.4 or higher)

103

Programming

Using the Terminal Window


Select Tools > Terminal (or click the toolbar button) to open the Terminal window. The Terminal window puts the Master Controller into dumb terminal mode. Anything that is typed on the screen exits through the Master communications port, and anything coming in from the communications port is displayed in the Terminal window. Use the Terminal window to communicate directly with the Master Controller and to debug RS-232-controlled devices. You cannot use the Terminal window while a communication port is in use for a file transfer or debug operation. Type "ECHO ON" in the Terminal window to display messages. If the Terminal window becomes unresponsive, close and re-open the window. To leave the Terminal Emulator window active for a long session, click the Terminal Locks the Port option in the General tab of the Preferences dialog. Use the Terminal Options tab of the Preferences dialog to modify the behavior and change the appearance of the Terminal window. To use the Terminal window with NetLinx systems, you must be connected to the Master via the PROGRAM port. Otherwise, you can use Windows TelNet for terminal control of NetLinx systems.

104

NetLinx Studio (v2.4 or higher)

Programming

ASCII / HEX / DECIMAL CONVERSIONS TABLE


CHR nul soh stx etc eot enq ack bel bs ht lf vt ff cr so si dle dc1 dc2 dc3 dc4 nak syn etb can em sub ec fs gs rs us sp HEX 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 DEC 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ CHR ! " # $ % & HEX 21 22 23 24 25 26 '27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 DEC 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 CHR A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` HEX 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60 DEC 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 CHR a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ del HEX 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F DEC 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

NetLinx Studio (v2.4 or higher)

105

Programming

106

NetLinx Studio (v2.4 or higher)

Compile Operations

Compile Operations
Overview
The options in the Build menu allow you to compile source code into executable code that the Axcess or NetLinx control system can understand. NetLinx Studio v2 has the ability to compile and link all the source code (.AXS and .AXI) files at the Workspace, Project, System or File level, plus the ability to compile a single file as either an Axcess or NetLinx type source code file. To send the compiled code to the Master Controller, use the File Transfers option in the Tools menu.

Building the Workspace


One advantage to the Workspace concept employed by NetLinx Studio (v2.0 or later) is that you can choose to build (compile) the entire Workspace. That is, every Source Code, Include, and Module file contained within the open Workspace can be compiled with a single command: Build Workspace. There are several ways to access the Build Workspace command - via the Build menu, the Workspace context menu (in the Workspace tab of the Workspace Window), or via the toolbar button. To compile the open Workspace: 1. Select Build > Build Workspace. Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window.

Building the Selected Project


You can select to compile a single Project within the open Workspace, using the Build Project command. When you compile a Project, every Source Code, Include, and Module file contained in all of the Systems within the selected Project are compiled. There are several ways to access the Build Project command - via the Build menu, the Project Folder context menu (in the Workspace tab of the Workspace Window), or via the toolbar button. To compile a Project: 1. Click to select and highlight the Project that you want to compile (in the Workspace tab of the Workspace Window). 2. Select Build > Build <Project Name> Project. Any errors detected by the program before the build operation starts are listed in the PreBuild Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build.

NetLinx Studio (v2.4 or higher)

107

Compile Operations

3. The status and results of the build are displayed in the Status tab of the Output Display Window.

Building the Selected System


You can select to build (compile) any System in the Workspace, using the Build System command. When you build a System, every Source Code, Include, and Module file contained in the selected System is compiled. The Build System command always works on the selected System, regardless of whether it is currently designated as the active system or not. To compile a System: 1. Click to select (highlight) the System that you want to build (in the Workspace tab of the Workspace window). 2. Select Build System <System name> from the Build menu, or select Build System from the System Folder context menu (or click the toolbar button). Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 3. The status and results of the build are displayed in the Status tab of the Output Display Window.

Building the Active System


You can select to build (compile) only the System currently designated as the Active System, using the Build Active System command. When you compile a System, every Source Code, Include, and Module file contained in the selected System is compiled.
The currently active System is indicated in bold (in the Workspace tab of the Workspace Window).

To compile the Active System: 1. Select Build Active System from the Build menu, or click the toolbar button. Any errors detected by the program before the build operation starts are listed in the PreBuild Errors dialog. Assuming that a Master Source Code file has been defined for the System, this dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window. Designating the System's Master Source Code File Each System must have a Master Source Code file, and only one Source Code file in the System can be designated as the Master Source. There are two possible ways to designate the Master Source Code file for a System: You can designate a Source Code file as the Master Source at the time that it is added to the System, via the Master File option in the File Properties dialog.

108

NetLinx Studio (v2.4 or higher)

Compile Operations

Alternatively, you can designate any Source Code file in the System as the Master Source by right-clicking on a Source Code file (in the Workspace tab of the Workspace Window), and selecting Set As Master from the Source Code File context menu.

Compiling an Individual File


You can select to compile a single Source Code, Include, or Module file, using the Compile, Compile As NetLinx and Compile as Axcess commands (or toolbar buttons). To compile an individual file: 1. Select the file that you want to compile: If the file is already included in the open Workspace, click to select the file and select the appropriate Compile command from the Build menu. If the file is not part of the open Workspace, open the file via the File > Open command, then right-click on the file (in the Source Code Editor window). 2. Select the appropriate Compile command. There are several ways to access the Compile commands - via the Build menu, the System File context menus (in the Workspace tab of the Workspace Window), the Source Code Editor context window, or via the toolbar buttons. If you create a new non-Project related file, without a Workspace file open, the Compile command compiles the file using the compiler (NetLinx or Axcess) associated with the file when it was created. If you open an existing non-Project related file, with a Workspace open, the Compile command compiles the file using the compiler specified in the System communication settings for the currently active System. The Compile as NetLinx command compiles the selected file using the NetLinx compiler. The Compile as Axcess command compiles the selected file using the Axcess compiler.
Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build.

3. The status and results of the build are displayed in the Status tab of the Output Display Window.

NetLinx Studio (v2.4 or higher)

109

Compile Operations

Compiler Errors and Warnings


These help topics contain information on the various types of errors and bugs common to programming, and some techniques for solving these problems. Note that Warnings will not automatically preclude a successful compile operation. By contrast, Errors must be corrected before your program can be compiled. Compiler Error Types There are three general types of programming errors: Compilation errors - Errors that occur at compile time. The compiler alerts you to these errors immediately and identifies each error and the line where it is located. Run-time errors - Errors that occur after the program has been compiled and loaded into the Master Controller. These errors are caused by program statements that attempt illegal operations. Logic errors - Logic errors are errors in program design and thus are the programmer's responsibility; The master cannot tell if the program it is executing is accomplishing what the user intends.

Compiler Errors
When the compiler finds an error during the compilation process, it informs the programmer. Most of the time these errors occur due to a typographical error or incorrect syntax of a particular command. Unlike warnings, errors must be corrected before your program can be executed. Compilation errors are described below:
A "<symbol>" was expected Active keyword expected The compiler is expecting a certain symbol at this particular place. An ACTIVE keyword is not present after a SELECT keyword.

Allowed only in DEFINE_START A keyword that is only allowed to appear in the DEFINE_START section of the program was encountered elsewhere. Attempted CALL to undefined subroutine Comment never ends, EOF encountered Conditional compile nesting too deep Constant type not allowed A CALL statement refers to a subroutine that has not been defined with a DEFINE_CALL statement. A comment begins but never ends. Place a close comment, * ) at the end of the unfinished comment. There are too many nested #IF_DEFINED or #IF_NOT_DEFINED conditional compilation statements. The limit is 20 nested conditional compilation statements. A constant value was declared as latching, toggling, or mutually exclusive, as shown below: DEFINE_CONSTANT PLAY = 1 DEFINE_LATCHING PLAY (* Error: PLAY is a constant *) DEFINE_CALL must have a name DEFINE_CALL name already used DEFINE_CALL must have a name after it. For example, DEFINE_CALL 'VHS'. The name of the DEFINE_CALL has already been used. This name cannot be the same as an already declared identifier of any type.

110

NetLinx Studio (v2.4 or higher)

Compile Operations

Device values must be equal Duplicate symbol Evaluation stack overflow Evaluation stack underflow Identifier expected

In a range specification, the devices (or their defined identifiers) must be equal. For example, ([1,1]..[1,5]) is valid; ([1,1]..[2,5]) is not. Duplicate definitions of variables or constants are found. All variables and constants must have unique identifiers. The expression is too complicated. Try breaking it up into smaller pieces. The compiler is expecting an identifier after a #DEFINE statement or after an integer declaration in the DEFINE_VARIABLE section. A non-array variable was treated as an array. An INCLUDE statement was encountered, but the specified Include file could not be found. A string literal enclosed in single quotes must follow the INCLUDE keyword. The library file containing the specified SYSTEM_CALL could not be found. String literals are limited in length to 132 characters, including spaces. An array type variable was expected in CREATE_BUFFER, CREATE_MULTI_BUFFER, or CLEAR_BUFFER. The identifier in question must be an integer. This error occurs when the third parameter of CREATE_LEVEL is an array or array element. This error means that the compiler cannot find the line number to even check what type of error has occurred, so it gives no details on the cause. If you get this non-descriptive error when compiling and the code contains modules, check to make sure the module parameters are the right type. If you're trying to pass in a onedimension array where the module requires a two-dimension array, or a CHAR instead of an INTEGER, etc., this error will occur.

Identifier is not an array type Include file not found Invalid Include file name Library file not found Maximum string length exceeded Must be char array reference Must be integer reference

NetLinx Compiler failed RT: -2147417851 ST:1

Out of memory

The compiler has run out of memory. Free up memory either by removing any pop-up programs or drivers, by using extended memory, or by breaking your program into one or more Include files. A value or variable passed to a CALL as a parameter is of the wrong type as defined by the DEFINE_CALL statement. Move the PROGRAM_NAME= statement to the first line of the program. A PUSH or RELEASE statement was found within a block of code headed by a PUSH or RELEASE statement. These keywords are not allowed in a section of code which will be executed due to a WAIT keyword.

Parameter mismatch in CALL PROGRAM_NAME must be on line 1 PUSH/RELEASE not allowed within PUSH/RELEASE PUSH/RELEASE not allowed within WAIT PUSH_CHANNEL not allowed within WAIT RELEASE_CHANNEL not allowed within WAIT PUSH_DEVICE not allowed within WAIT RELEASE_DEVICE not allowed within WAIT

NetLinx Studio (v2.4 or higher)

111

Compile Operations

String constant expected

A string is required for the particular operation. This error occurs if a string literal enclosed in single quotes does not follow the PROGRAM_NAME keyword. A string literal is started but never ends. Add a closing single quotation mark (') to the end of the string. A string is required for the particular operation. This error would occur if a string literal enclosed in single quotes does not follow the #WARN keyword. A subroutine cannot call itself. It can, however, call a different subroutine. A syntax error is found in an expression. In most cases, this error means that a character is out of place or something is misspelled. This error occurs when a library file is compiled and the name of the subroutine in the library file does not match the PROGRAM_NAME string on the first line of the file. This error occurs when an attempt is made to use an array variable with DEFINE_LATCHING, DEFINE_TOGGLING, or DEFINE_MUTUALLY_EXCLUSIVE.

String constant never ends, EOF encountered String literal expected

Subroutine may not call itself Syntax error

SYSTEM_CALL name not same as PROGRAM_NAME in <file> This variable type not allowed

To not allowed within DEFINE_START

These errors occur if the TO keyword is found in an erroneous location. The TO keyword can only be associated directly with To not allowed within MAINLINE a PUSH statement. To not allowed within RELEASE To not allowed within WAIT Too few parameters in CALL Too many Include files Too many parameters in CALL Type mismatch in function CALL Undefined identifier Unmatched #END_IF Unrecognized character in input file Use SYSTEM_CALL [INSTANCE] 'NAME' Variable assignment not allowed here WAIT not found There are not enough parameters being passed to the subroutine. A program may only contain up to 20 Include files. There are too many parameters being passed to the subroutine. A function was called with a parameter of the wrong type. For instance, attempting to use ITOA with an array as a parameter will result in an error. An attempt was made to reference an identifier that has not been defined previously in the program. An #END_IF keyword was found, but no #IF_DEFINED or #IF_NOT_DEFINED was previously compiled. An invalid character was found during compilation. This error occurs if a SYSTEM_CALL statement is written incorrectly as SYSTEM_CALL 'NAME' [INSTANCE NUMBER]. Variables may not be assigned a value when they are defined in the DEFINE_VARIABLE section. A statement references a WAIT by a name that does not exist. For example, CANCEL_WAIT 'CASS' will produce this error if there is no WAIT named CASS.

112

NetLinx Studio (v2.4 or higher)

Compile Operations

Compiler Warnings
Sometimes the compiler generates a warning message instead of an error message; these warning messages always start with w. A warning about a particular statement means that the statement is not technically an error, but you should be careful doing it. Warnings, unlike errors, do not stop the program from compiling. Some types of warnings can be disabled in the Compiler Options tab of the Preference dialog. Common compiler warnings are described below:
(w) Cannot assign unlike types This warning occurs when a variable or value of one type is assigned to a variable of a different type. Here are some examples: Assigning a string literal, string expression, or array to a non-array variable Assigning a non-array variable to an entire array Assigning an integer array to a non-integer array Assigning a two-dimensional array to a one-dimensional array, or vice versa Assigning the result of a function that returns an array type to a non-array variable or to a two-dimensional array variable (for example, X = ITOA(12), where X is a non-array variable or two-dimensional array variable) Assigning the result of a function that returns a non-array type to a one- or two-dimensional array variable (for example, X = ATOI('AMX'), where X is a one- or two-dimensional array variable) This message is a warning and not an error, because X = ITOA(12) works correctly when X is a simple variable, since the result is a single value between and 65,535. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. (w) Define_Call is not used This warning occurs at the end of program compilation for each DEFINE_CALL subroutine that was declared but never used. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog This warning appears when the keyword INTEGER is applied to a non-array type of variable. Doing this is not an error, because non-array variables are already integers, but it is redundant. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. This warning occurs if the compiler finds a LONG_WHILE or MEDIUM_WHILE inside a block of code following a WHILE keyword. This warning exists because the WHILE command has a 1/2 second timeout period, and the LONG_WHILE and MEDIUM_WHILE keywords do not. This could create a hard-to-find logic error. The solution is to change the WHILE to a LONG_WHILE to fix this problem. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog.

(w) Integer applies to arrays only

(w) Long_While within While

(w) Possibly too This warning appears if there is a large amount of nesting in the program. many nested levels This can happen with a long chain of IF...ELSE IF statements. The solution is to use the SELECT...ACTIVE set of statements. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. (w) Variable is not used This warning occurs at the end of compilation for each variable that was declared but never used. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog.

NetLinx Studio (v2.4 or higher)

113

Compile Operations

Compiler Error Warnings Report Dialog This dialog is invoked via the Compiler Errors/Warning Report option in the Output Display Window Context Menu. Use the options in this dialog to specify what you want to include in the report (Errors, Warnings or both). By default, both Errors and Warning are included. Note that Warnings will not automatically preclude a successful compile operation. By contrast, Errors must be corrected before your program can be compiled. Disabling Compiler Warnings In Netlinx Code In the AXCESS Compiler tab of the Preferences dialog, there are a number of Axcess compiler warnings that can be enabled / disabled, but there are no corresponding options in the NetLinx Compiler tab for enabling / disabling NetLinx compiler warnings. Disabling NetLinx compiler warnings can be done in code by adding a #DISABLE_WARNING statement with a warning number generated by the compiler. For example, if you are getting a warning you want to disable, such as:
WARNING: U:\My Documents\Studio\Test\DISABLE_WARNINGtest.axs(12): C10571: Converting type [SINTEGER] to [INTEGER]

The warning number is 10571. Add the line to the beginning of the code file:
#DISABLE_WARNING 10571

The code will now compile without generating the specified warning.

Run-Time Errors
In many cases, a program is compiled and sent to the Master Controller error-free, but the System does not act in the way it should. If the program code is correct, you should check for run-time errors. These errors occur in the Master Controller, usually when it could not perform a particular operation in the program. Run-Time errors are errors that occur during program execution, and are described below:
Bad assign 2dim... These errors occur if an attempt is made to assign a two-dimensional array to a different type (such as a variable or one-dimensional array), and vice versa. These errors occur if the Master Controller cannot assign a parameter in a CALL statement to the parameter in the corresponding DEFINE_CALL statement. These errors occur if an assignment is attempted past the end of an array, or to the location of an array (for example, ARRAY[]).

Bad assign Call...

Bad element assign...

Bad Off... Bad On... Bad To... These errors indicate that the device-channel or variable that is being referenced by an OFF, ON, or TO keyword is out of range. Bad re-assign Call... These errors occur when the Master Controller attempts to reassign the parameter variables in a DEFINE_CALL to the parameters in the corresponding CALL statement, and the assignment cannot be made. This error occurs when the Master Controller does not understand a piece of data in the program it is executing. These errors occur if the SET_LENGTH_STRING keyword tries to set the length value of an array to a value greater than the array's storage capacity. This error occurs whenever a WHILE loop terminates due to the half-second timeout imposed on WHILE loops.

Bad run token Bad Set_Length...

Bad While

114

NetLinx Studio (v2.4 or higher)

Working With Online Devices

Working With Online Devices


NetLinx Network Setup
In order for the NetLinx system to run on a network, the network settings must be configured for the target network. You will need to have detailed information about your network on hand before starting. In order for the NetLinx master to operate correctly, it must have the IP address, subnet mask, gateway address, domain name and name server addresses according to the Network Administrator-supplied values. Many Network administrators setup a DHCP server to automatically supply these values to network devices when the reboot. The NetLinx master does support DHCP and it your network supports DHCP, the network setup process will be greatly simplified. If not using DHCP, it is important to have values for all parameters listed below. Entering just one network parameter incorrectly can cause communication to the network to fail. Please contact your Network Administrator if you do not have the information necessary to complete the network settings for your system. After changing the network settings, you must reboot the NetLinx master for the settings to take effect. Network Setup Select the Tools->Master Comm Settings Menu item. Select NetLinx for the platform and then select either a COM port (if the networking is not already configured) or an IP address (if it is currently on the network). Select OK when complete. Select the Tools->NetLinx Diagnostics Menu item. Select the Networking tab from the tabs along the top. Enter 0 for both System and Device. Then press Get IP Info. Then press Get DNS Info. Is there a supplied Host name for the IP address assigned to the NetLinx master? If so, enter under Host Name. If no name is supplied, enter NetLinx. Is your IP address dynamic (DHCP) or fixed (Static)? Select the Use DHCP or Specify IP Address according to your network information. If you selected Use DHCP, then press Set IP Info and then press Reboot. When the master restarts, it will contact the DHCP server to fill in any missing network information. You are now finished with your NetLinx Network Setup. If you selected Specify IP Address, enter the IP address supplied by the network administrator. If you do not have an IP address, contact the network administrator to obtain one. If you enter the incorrect number, the NetLinx master and very likely another device on the network will not be able to communicate on the network. Enter your Subnet Mask. This value determines the scope of your network. If you did not receive a value for this, enter 255.255.255.0. It is a very common default. Do not leave this blank.

NetLinx Studio (v2.4 or higher)

115

Working With Online Devices

Enter your Gateway. This value determines a path to computers not on your network. If you did not receive a value for this, enter your IP address. Do not leave this blank. Enter your Domain Suffix. If you did not receive a value for this, leave it blank. Enter up to 3 DNS IP. This values help your master find other network resources. If you did not receive a value for these, leave them blank. Press Set IP Info, followed by Set DNS Info and then press Reboot. When the master restarts, it will use the new network settings. You are now finished with your NetLinx Network Setup.

Working With the Online Device Tree


The Online Tree tab of the Workspace Window (FIG. 20) displays an Online Device Tree for either the NetLinx or Axcess Master Controller. The Online Device Tree displays a list of devices detected to be currently online by the Master Controller (and the firmware version for each). The Device Tree also provides port status information for each device.
The Online Device tree is only a snap shot and is not updated in real time as devices come on/off line. Select Refresh System or Refresh Network from the Online Tree Context Menu to update the Online Device Tree.

An example Device Tree is shown below (FIG. 20):

FIG. 20 Online Device Tree

116

NetLinx Studio (v2.4 or higher)

Working With Online Devices

The online devices are organized according to the System they belong to. Double-click any System folder to display a list of System devices (and their firmware version) that are currently online. Double-click any online device in the list to display the ports and sub-devices associated with the device.
Sub-devices are hardware components contained within a parent device, which may require their own firmware. For example, and NXI Master Controller contains three components, each of which require firmware.

Click the Display command button (or right-click anywhere within the Online Tree tab) to access the Online Tree Context Menu. Device Tree Elements The main elements of the online device tree are described below: System: The highest-level element in the device tree is the System element. This element indicates the System Number, followed by the Master Controllers IP address and MAC address (FIG. 21):

FIG. 21 Online Device Tree - System element

Master Controller: The next element down from the System is the Master Controller element. This element indicates the Master Controllers device number, device name and indicates the Master firmware version currently loaded (FIG. 22):

FIG. 22 Online Device Tree - Master Controller element

Click the plus sign to expand the view to show sub-devices and ports on the Master. Sub-devices are indicated with red icons, and give a description and firmware version info (in parenthesis) for each. Below the sub-devices is a listing of Ports on the Master. To check the status on any port, right-click on a port and select Check Port Status from the context menu. The

NetLinx Studio (v2.4 or higher)

117

Working With Online Devices

results of this status check are indicated in the Status tab of the Output Window (see FIG. 24 on page 120). Devices: The elements below the Master Controller in the device tree represent devices in the system. These elements indicate the device number, device name and the device firmware version currently loaded (FIG. 23):

FIG. 23 Online Device Tree - Device element

Click the plus sign to expand the view to show sub-devices and ports on the Master. Sub-devices are indicated with red icons, and give a description and firmware version info (in parenthesis) for each. Below the sub-devices is a listing of Ports on the Master. To check the status on any port, right-click on a port and select Check Port Status from the context menu. The results of this status check are indicated in the Status tab of the Output Window (FIG. 24). Device States There are several possible "states" for devices listed in the online device tree:
Unbound Device: An Unbound (or "Orphan") device is one that has not been bound to a NetLinx Master. It may or may not have been assigned a Device Number. A device will live in this state until it is explicitly bound to a master. A device is "Searching" if it has been bound to a NetLinx Master in the past, but is not currently communicating with the Master. After 10 minutes with no communication with the NetLinx Master, a "Searching" device is moved into the "Lost" state. Lost: A device is "Lost" if it has been bound to a NetLinx Master in the past, but it has not communicated with the Master for over 10 minutes.

Searching:

118

NetLinx Studio (v2.4 or higher)

Working With Online Devices

Found:

A device is "Found" if the device has been bound to a NetLinx Master and is communicating with that NetLinx Master. Found devices inherit the System Number of the NetLinx Master it is "Found" by. If the device has been configured with a valid Device Number, it will communicate with the NetLinx Master as that Device Number. If it has not been configured with a valid Device Number, it will request a Dynamic Device Number from the NetLinx Master and use the Dynamic Device Number to communicate with the NetLinx Master.

Device Tree Context Menu Right-click on any device or folder, or click the Display command button (in the Online Tree tab of the Workspace Window) to open the Device Tree context menu. This context menu contains various commands and options relating to online devices, including:
Refresh System: Click to refresh the Online Device Tree for the local system (the system containing the Master Controller that your PC is connected to). For NetLinx systems, it is the Master Controller identified in the Network field of the Communication Settings dialog. The Connection Status to the Master Controller dialog may appear, if communication to the master has not already been established. Refresh Network: Device Addressing: Check Port Status: Click to refresh the entire online tree (all Systems). Click to access the Device Addressing dialog, where you can view/edit the Device/System addressing information for the selected device. This item is enabled only if a Port element is selected in the Online Device Tree. The status of the selected port is displayed in the Status tab of the Output Display window. This item only appears if you have selected a device from the Unbound Devices folder (see FIG. 20). If the device is unbound, this option binds the device to a specific Master Controller (via the Bind/Unbind Device dialog - see the Binding/Unbinding Devices section on page 120). Click to expand all of the folders in the Online Device Tree to show all devices, ports and components.

Bind/Unbind Device:

Expand Tree:

Expand to Device Level: Click to expand the Online Device Tree to show all devices in the System. Collapse Tree: Click to collapse the Online Device Tree to the top-level System Devices folder.

Checking Port Status 1. Click the plus-sign (+) next to any device in the Device Tree to expand the view to show all of the ports for that device (as shown in FIG. 20 on page 116). 2. Right-click on any Port in the list to access the Device Tree context menu. 3. Select Check Port Status. 4. The results of the status check are displayed in the Status tab of the Output window. An example is shown in FIG. 24:

NetLinx Studio (v2.4 or higher)

119

Working With Online Devices

Device:Port:System information for the selected device

FIG. 24 Example result of Check Port Status (displayed in the Status tab of the Output window)

Binding/Unbinding Devices The Unbound Devices folder in the device tree (FIG. 20) indicates all devices in the system that are not currently bound to a Master. These are "orphan" devices, until they are assigned to communicate to a specific Master. An Unbound (or "Orphan") device is an NDP-capable device which has not yet been assigned (bound) to communicate with a specific Master. Unbound devices can be associated (bound) to a Master for communications via the Bind/Unbind Device option in the Device Tree context menu. A Bound device is one which has established communication with a specific Master. To Bind an Unbound Device: 1. Right-click on a device contained in the Unbound Devices folder of the Device Tree to access the Device Tree context menu. 2. Select Bind Device to open the Bind/Unbind Device dialog (FIG. 25).

Selected Unbound Device (click down-arrow to select a different unbound device) The information here indicates: [device number], device name and firmware info Check the Master that you want to bind the device to The information here indicates: [device number], device name and firmware info

FIG. 25 Bind/Unbind Device dialog

120

NetLinx Studio (v2.4 or higher)

Working With Online Devices

3. By default, the selected device is displayed in the Device to Bind/Unbind window at the top of the dialog. If there is more than one Unbound device in the system, click the down arrow to select which device you want to bind. 4. Check the checkbox next to the Master that you want to bind the device to. If there is more than one Master in the system, check the specific Master that you want to bind the device to. 5. Select Refresh System (in the Device Tree context menu). The device should now appear in the device list (indicated with a green device icon). To Unbind a Bound Device: 1. Right-click on the device that you want to unbind in the Device Tree. 2. Select Unbind Device to open the Bind/Unbind Device dialog (FIG. 25). 3. De-select the checkbox next to the Master that the device is currently bound to. 4. Select Refresh System (in the Device Tree context menu). The device should now appear in the Unbound Devices folder (indicated with a green device icon).

NetLinx Diagnostics - NetLinx Device Notification


The NetLinx Device Notifications functionality in NetLinx Studio v2 allows you to receive several types of auto-notification messages from one or more specified NetLinx devices. Use the NetLinx Device Notifications Options dialog (Diagnostics > NetLinx Device Notification Options) to set auto-notification preferences for one or more NetLinx devices. Select Enable NetLinx Device Notifications from the Diagnostics menu (or use the toolbar button) to enable the specified NetLinx notifications. The resulting notification messages are displayed in the Notifications tab of the Output Display window. The Notifications tab contains 13 columns. Each column represents a notification type (which are enabled/disabled in the NetLinx Notification Properties dialog). If a notification type is enabled, the word ON is displayed in the appropriate column. Initially, the only entry in the notifications list is All Devices, and the only notification enabled is Input. Select the Enable Asynchronous Notifications option (in the NetLinx Device Notifications Options dialog) to enable asynchronous notifications. Adding A Device To The Device Notification List In order to edit, add or remove devices from the list you must be connected to a NetLinx master controller. 1. Select Diagnostics > NetLinx Device Notification Options to open the NetLinx Device Notifications Options dialog. 2. Click Add to open the NetLinx Notification Properties (Add) dialog. 3. Specify the Device, Port and System numbers for the NetLinx device that you want to set notification options for.
The D:P:S combination of 0:0:0 is the default setting and will show up as "All Devices".

4. Check each notification type that you want to enable for that device.

NetLinx Studio (v2.4 or higher)

121

Working With Online Devices

To set the selected set of notifications as the default notifications for this device, click the Set As Defaults button. Once you set the default notifications, you can use the Use Defaults button to recall the default set. 5. Click OK to close the NetLinx Notification Properties (Add) dialog and return to the NetLinx Device Notifications Options dialog. The new target device specified has its own line in the notifications list. The Device:Port:System values (for example, 1:0:0) identify the device in the Device column. The selected notification option(s) are labeled as ON in the associated column(s). 6. Repeat steps 2-5 to configure NetLinx Notifications for as many additional devices as is necessary.
A very large amount of data may be generated if all options are enabled for every device in a large System.

Select Enable Asynchronous Notifications to enable/disable NetLinx asynchronous notification messages being sent by the master controller. These are low-level strings of raw data, used primarily for troubleshooting the NetLinx master. This option is intended for use in conjunction with AMX Technical Support. 7. Click Done to save the changes and exit the NetLinx Device Notifications Options dialog. Editing Device Notification Settings In order to edit, add or remove devices from the list you must be connected to a NetLinx master controller. 1. Select Diagnostics > NetLinx Device Notification Options to open the NetLinx Device Notifications dialog. 2. Select a device in the Device list and click the Edit button to open the NetLinx Notification Properties - (Edit) dialog. Alternatively, you can double-click on a device in the Device list to access this dialog. 3. Check or un-check the notification types as desired. Note that the target device's Device, Port and System settings are read-only. This option allows you change the selected device's notification options only.
A very large amount of data may be generated if all options are enabled for every device in a large System.

4. Click OK to save your changes and return to the NetLinx Device Notifications Options dialog. The new notification options are indicated (as ON) in the notifications list. Select Enable Asynchronous Notifications to enable/disable NetLinx asynchronous notification messages being sent by the master controller. These are low-level strings of raw data, used primarily for troubleshooting the NetLinx master. This option is intended for use in conjunction with AMX Technical Support.

122

NetLinx Studio (v2.4 or higher)

Working With Online Devices

Removing Devices From The Notifications List In order to edit, add or remove devices from the list you must be connected to a NetLinx master controller. 1. Select Diagnostics > NetLinx Device Notification Options to open the NetLinx Device Notifications dialog. 2. Select a Device from the list and click the Remove command button.

The program will not allow you to remove the All Devices (0:0:0) listing.

NetLinx Diagnostics - NetLinx Internal Diagnostics Messages


Select Diagnostics > Enable NetLinx Internal Diagnostics Messages to display internal diagnostics messages from the Master in the Diagnostics tab of the Output window. There are two basic types of messages that are generated via this option:
SEND_STRING 0 messages that exist in the Master code

Run-time debugging messages


These are the same messages that would be displayed via a telnet session with the Master. In situations where you are receiving large numbers of messages, an actual telnet session can be more effective, since it tends to be faster (due to the lack of overhead).

Debugging NetLinx Programs with Terminal or Telnet messages This is often referred to as using "SEND_STRING 0's" in your code. Strings sent to device 0 (the master), port 1 or port 0, system 0 (the local system) will show up in a terminal or Telnet session once the programmer has typed in 'MSG ON'<enter> at the prompt. For example, if this line is in your code:
SEND_STRING 0,'some message'

your terminal will display something like:


(0100636312) some message

when the code executes. The 13 characters to the left of the message are called the "time stamp" or "tic time". Also, by default, the master will append a carriage return and line feed to the end of each string. If the master is v2.10.81 or higher, there are additional MSG ON modes: 1. All messages with tic time. This is the same as 'MSG ON' with no type. 2. SEND_STRING 0 only (no tic time in front of string and no CR and LF appended). 3. SEND_STRING 0 with tic time pre-pended to string. Example:
MSG ON 2<enter> sets the message mode to 2.

To turn off these messages type 'MSG OFF'<enter>.

NetLinx Studio (v2.4 or higher)

123

Working With Online Devices

The SEND_STRING 0 message is obviously completely customizable - whatever is typed in will be what you are going to get. This can be used as a way to see the value of variables at specific points in the code, by sending that information from that point, instead of stopping execution with a breakpoint. This is especially useful if programmers have to watch non-printable data bytes that only show as blank boxes in Windows programs, the SEND_STRING 0 code can reformat the data as a string of printable ASCII characters. The 'debug.axi' file (attached to Technote #461) contains 16 subroutines useful for this type of debugging and other purposes, e.g. DPS_TO_STRING and STRING_TO_DEV are useful for passing DEV information between masters via a virtual device in a master-to-master scenario. Theses subroutines were created as an AXI so programmers could use a single #INCLUDE at the top of the program rather than having to dig through the old programs and find the appropriate code to cut and paste. 1. FUNCTION CHAR[17] DEV_TO_STRING (DEV dvDEV) Formatting NetLinx device structures as strings take a little more than the simple ITOA(<device>) that was done in Axcess. This function takes a DEV and returns a string in the '<number>:<port>:<system>' format. 2. FUNCTION CHAR[25] DEVCHAN_TO_STRING (DEVCHAN dcDC) This function returns a DEVCHAN as a string with brackets in the format '[<number>:<port>:<system>,<chan>]'. 3. FUNCTION CHAR[25] DEV_CHAN_TO_STRING (DEV dvDEV, INTEGER nChannel) Same as DEVCHAN_TO_STRING but takes a separate DEV and INTEGER as parameters. Returns '[<number>:<port>:<system>,<chan>]'. 4. FUNCTION CHAR[25] DEVLEV_TO_STRING (DEVLEV dlDL) This function returns a DEVLEV as a string in the format '<number>:<port>:<system>,<lev>'. 5. FUNCTION CHAR[25] DEV_LEV_TO_STRING (DEV dvDEV, INTEGER nLevel) Same as DEVLEV_TO_STRING but takes a separate DEV and INTEGER as parameters. Returns '<number>:<port>:<system>,<lev>'. 6. FUNCTION CHAR[17] DPS_TO_STRING (DEV dvDEV) This function takes a DEV and returns a string in the '<number>:<port>:<system>' format. Same as DEV_TO_STRING except it always returns the actual system number, not system 0, if the device is so defined. 7. CALL 'SEND 131 BYTE PACKETS TO MASTER' (sSTRING[]) Strings sent to the master will be truncated if they are longer than 131 bytes. This call breaks the strings up if they are longer than 131 bytes. Otherwise, it does not modify the string. Use with master v2.10.81 or higher "MSG ON 2" mode to see only the data in the sSTRING. 8. CALL 'SEND 7BIT ASCII TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode) This call is similar to 'SEND ASCII TO MASTER' but with a little more flexibility: dvDEBUG is the destination device for the string. It could be the local master, a virtual device on the local system (see TN435), an IP device, serial device, etc.

124

NetLinx Studio (v2.4 or higher)

Working With Online Devices

STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and > $7E (~) are formatted as hex

and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2.
nLine is the line length. This may need to be changed if a terminal with a line length

other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for

the defaults. 9. CALL 'SEND ASCII TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode) This call is similar to 'SEND ASCII TO MASTER' but with a little more flexibility: dvDEBUG is the destination device for the string. It could be the local master, a virtual device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and $7F (DEL) are formatted as

hex and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2.
nLine is the line length. This may need to be changed if a terminal with a line length

other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for

the defaults. 10. CALL 'SEND ASCII TO MASTER' (STR1[],STR2[])


SEND_STRING 0's are formatted into 67 character lines. Since the tic time sent with MSG ON

mode 1(default) and mode 3 prepend 13 characters to the string, each line fills the typical 80 character line (67 + 183 = 80).
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and $7F (DEL) are formatted as

hex and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2. 11. CALL 'SEND DECIMAL TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode)
dvDEBUG is the destination device for the string. It could be the local master, a virtual device

on the local system (see TN435), an IP device, serial device, etc.


STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. All data bytes are formatted as 3 digit decimal and separated by commas.

As of v2.01, a space ($20) is no longer added between STR1 and STR2.

NetLinx Studio (v2.4 or higher)

125

Working With Online Devices

nLine is the line length. This may need to be changed if a terminal with a line length

other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for

the defaults. 12. CALL 'SEND DEVICE_INFO TO DEBUG' (dvDEBUG,dvDEV)


dvDEBUG is the destination device for the strings. It could be the local master, a virtual

device on the local system (see TN435), an IP device, serial device, etc.
dvDEV is the device from which to get the info.

13. CALL 'SEND DECIMAL TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode)


dvDEBUG is the destination device for the string. It could be the local master, a virtual

device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. All data bytes are formatted as 3 digit decimal and separated by commas.

As of v2.01, a space ($20) is no longer added between STR1 and STR2.


nLine is the line length. This may need to be changed if a terminal with a line length

other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for

the defaults. 14. CALL 'SEND INTEGER TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode)


dvDEBUG is the destination device for the string. It could be the local master, a virtual

device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes are not formatted.

As of v2.01, a space ($20) is no longer added between STR1 and STR2.


nLine is the line length. This may need to be changed if a terminal with a line length

other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for

the defaults. 15. CALL 'SEND ITOHEX TO MASTER' (STR1[],STR2[])


SEND_STRING 0's are formatted into 67 character lines. Since the tic time sent with MSG ON

mode 81(default) and mode 3 prepends 13 characters to the string, each line fills the typical 80 character line (67 + 13 = 80).

126

NetLinx Studio (v2.4 or higher)

Working With Online Devices

STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. All data bytes are formatted as hex and separated by commas.

As of v2.01, a space ($20) is no longer added between STR1 and STR2. 16. CALL 'STRING TO DEV' (Txt[], dvDEV) Takes ASCII string Txt[] of the form '<dev>' or '<dev>:<port>:<sys>' and stores this as a DEV. The dev data in Txt[] can be embedded in other non-numeric characters. If Txt[] does not contain any numerals, dvDEV will default to 0:1:0 (the local master). In order to use these subroutines, debug.axi must be in the compile path. It is suggested that an "AXIs" folder in the My Documents folder be created, save debug.axi there, then add that path to Netlinx Studio "Edit/Preferences/Netlinx Compiler Options/Include Files". Then add the line:
#INCLUDE 'debug.axi'

to the source code. "Debug.axi" and example code are attached to Tech Note #461. To access AMX Tech Notes, go to www.amx.com, log in as a dealer and go to Tech Center > Tech Notes. Buffering of the Notification and Diagnostic Tabs The Notification and Diagnostic tabs are capable of handling a large number of messages without adversely affecting the system. There is a buffer file for each view and you can define the combined size of the two buffer files that are used to handle the large number of messages being sent from the master controller. As the buffer files are filling with messages from the master controller, the program will read in a message and display it into the appropriate list view every quarter of a second. This will allow you to view the messages at a reasonable rate versus what is being loading into the buffer files.
The buffer files that are used by the Notification and Diagnostic tabs can become full. When this happens, the program will disable the appropriate option. You will need to clear the appropriate list before you can start the option again. You may copy the text from the list view or save the content of the list view to a file.

NetLinx Diagnostics - NetLinx Device Emulation


Emulating a device in NetLinx Studio means that the program generates messages that appear to the master to have come from a specified <D:P:S> combination (real or fictitious). The options in the Emulate a Device dialog allow you to specify the <D:P:S> combination for a device you want to emulate. Use device emulation to simulate basic control of a specified NetLinx Master, including Channels (PUSH/RELEASE), Levels and String/Commands. Use this option to test specific areas in your Source Code against a specific device. To use NetLinx Device Emulation: 1. Select Diagnostics > Emulate a Device (or click the toolbar button) to access the Emulate a Device dialog. 2. Enter the Device, Port and System <D:P:S> combination of the device you wish to emulate (real or fictitious). The <D:P:S> value ranges are 0 - 65535.

NetLinx Studio (v2.4 or higher)

127

Working With Online Devices

3. To emulate a channel (push/release), enter a valid Channel number to emulate Channel messages (i.e., Push/Release, CHON, and CHOFF) for the specified <D:P:S> in the Channel text box. The Channel number range is 0-65535. Select the Push button to emulate a push/release on the channel specified. You may click and hold down the Push button to see how the master controller responds to the push message. Select the On or Off buttons to emulate Channel ON (CHON) and Channel OFF (CHOFF) messages for the specified <D:P:S>. 4. To emulate a level, enter the desired Level (number), Value and data Type (BYTE, CHAR, WIDECHAR, INTEGER, SINTEGER, ULONG, LONG, FLOAT, or DOUBLE), and click Send to emulate the specified level and value. The Level number range is 0-65535. The list below indicates the valid level data types and their ranges:
Data Type CHAR INTEGER Min Value 0 0 Max Value 255 65535 32767 429497295 2147483647

SINTEGER -32768 LONG SLONG FLOAT 0 -2147483648

-3.402823466e+38 3.402823466e+38

5. To emulate sending a String or Command, type a String or Command in the Message(s) To Send text box. Use the Return key within the text box to enter a new line for the next message. When entering a send command (in the context of this dialog) do not include the "send c" or "send_command" in the statement - only type what would normally occur within the quotes, but don't include the quotes either. For example to send the "CALIBRATE" send command, simply type CALIBRATE (no quotes) rather than SEND_COMMAND <dev> "CALIBRATE".
Hold down the Shift key to select a specific range of lines to send to the controller instead of all the lines within the edit control.

a. Click the Message Type radio buttons (String or Command) to specify the type of message you are sending. b. Click Send To Master to send the messages in the Message(s) to Send text box to the master. If none of the messages are selected (highlighted), all messages are sent. If you have selected a line or a range of lines, only the selected messages will be sent. 6. Check the Messaging Options checkboxes to Enable Asynchronous Notifications and/or Enable Internal Diagnostic Messages.

128

NetLinx Studio (v2.4 or higher)

Working With Online Devices

It is recommended that you enable NetLinx Notifications to view the results in the Notifications tab of the Output Display window. For example, in order to view a string sent to a device (via the Emulate Device dialog), you must first enable the Strings to Device notification (in the NetLinx Device Notifications Options dialog). Additionally, to view any strings returned from the device, you must enable the Strings From Device notification.

NetLinx Diagnostics - NetLinx Device Control


Controlling a device in NetLinx Studio means that it will appear to a specified System device that messages are being sent from the NetLinx master controller. The options in the Control a Device dialog allow you to specify the <D:P:S> combination for the target device you want to control. Use device control to simulate basic control of a specified NetLinx device, including Channels (PUSH/RELEASE), Levels and String/Commands. Use this option to test specific areas in your Source Code against a specific device. To use NetLinx Device Control: 1. Select Diagnostics > Control a Device (or click the toolbar button) to access the Control a Device dialog. 2. Enter the Device, Port and System <D:P:S> combination of the device you wish to control. The <D:P:S> value ranges are 0 - 65,535. 3. To emulate a channel (push/release), enter a valid Channel number to emulate Channel messages (i.e., Push/Release, CHON, and CHOFF) for the specified <D:P:S> in the Channel text box. The Channel number range is 0-65535. Select the Push button to emulate a push/release on the channel specified. You may click and hold down the Push button to see how the master controller responds to the push message. Select the On or Off buttons to emulate Channel ON (CHON) and Channel OFF (CHOFF) messages for the specified <D:P:S>. 4. To emulate a level, enter the desired Level (number), Value and data Type (BYTE, CHAR, WIDECHAR, INTEGER, SINTEGER, ULONG, LONG, FLOAT, or DOUBLE), and click Send to emulate the specified level and value. The Level number range is 0-65535. The list below contains the valid level data types and their ranges:
Data Type CHAR INTEGER Min Value 0 0 Max Value 255 65535 32767 429497295 2147483647

SINTEGER -32768 LONG SLONG FLOAT 0 -2147483648

-3.402823466e+38 3.402823466e+38

NetLinx Studio (v2.4 or higher)

129

Working With Online Devices

5. To emulate sending a String or Command, type a String or Command in the Message(s) To Send text box. Use the Return key within the text box to enter a new line for the next message. When entering a send command (in the context of this dialog) do not include the "send c" or "send_command" in the statement - only type what would normally occur within the quotes, but don't include the quotes either. For example to send the "CALIBRATE" send command, simply type CALIBRATE (no quotes) rather than SEND_COMMAND <dev> "CALIBRATE".
Hold down the Shift key to select a specific range of lines to send to the controller instead of all the lines within the edit control.

a. Click the Message Type radio buttons (String or Command) to specify the type of message you are sending. b. Click Send To Master to send the messages in the Message(s) to Send text box to the master. If none of the messages are selected (highlighted), all messages are sent. If you have selected a line or a range of lines, only the selected messages will be sent. 6. Check the Messaging Options checkboxes to Enable Asynchronous Notifications and/or Enable Internal Diagnostic Messages.
It is recommended that you enable NetLinx Notifications to view the results in the Notifications tab of the Output Display window. For example, in order to view a string sent to a device (via the Emulate Device dialog), you must first enable the Strings to Device notification (in the NetLinx Device Notifications Options dialog). Additionally, to view any strings returned from the device, you must enable the Strings From Device notification.

Viewing Push Results The PUSH keyword is used to find out if a channel has had an input change from off to on, such as when a button is pressed. If the channel has been turned on, the corresponding Push statement is activated. The operation or operations following this Push statement are only executed once after the channel is turned on. To view Push results, select Diagnostics > Enable Push Message Status Bar Display. NetLinx Studio displays the most recently received Push, or Push status (Push Enabled/ Disabled) in the Status Bar. Left-mouse click on the push message displayed to view a history of push messages. Then, right-mouse click within the list box to view the available options.

130

NetLinx Studio (v2.4 or higher)

Working With Online Devices

NetLinx Diagnostics - Netlinx Device Addressing


Use the Device Addressing dialog to change the Device and System assignments for a specified NetLinx device, or to change a NetLinx Master's System number. Select Device Addressing from the Diagnostics menu, the Online Device context menu, or click the toolbar button to access this dialog. Use the set of options on the left side of this dialog to specify the Device and System assignments, when you know the current address assignments as well as the address that you want to change the device to. Alternatively, you can use the set of ID Mode options on the right side of this tab to change the address assignment for a specified NetLinx device, using Identity (ID) Mode. The Start Identify Mode button places the entire NetLinx system (specified in the Destination System text box) in ID Mode.
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.

Changing The Device/System Address On A Netlinx Device Select Device Addressing from the Diagnostics menu, the Online Device context menu, or click the toolbar button to access the Device Addressing dialog, which allows you to change the Device and/or System Address for a NetLinx system device: 1. Enter the target device's current Device number in the (Device to Change) Device text box. 2. Click the Change Device checkbox and enter the new Device number in the New Device text box. 3. Enter the target device's current System number in the (System to Change) System text box. 4. Click the Change System checkbox and enter the new System number in the New System text box. 5. Click the Change Device/System Number command button to set the new address information for the specified device. 6. The master must be rebooted to accept the new System number assignment. To reboot the master, select Reboot Master from the Tools menu.

Allow the master 20-30 seconds to reboot.

Alternatively, you can use the ID (Identification) Mode options on the right side of this tab to change the address assignment for a specified NetLinx device. Use ID Mode when you don't know the current address assignments. The Start Identify Mode button places the entire NetLinx system (specified in the Destination System text box) in ID Mode.

NetLinx Studio (v2.4 or higher)

131

Working With Online Devices

Restoring The Default Device and System Numbers On A Netlinx Device Use the Device Addressing dialog to restore the default Device and System numbers on a NetLinx device:
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.

1. Select the target device/system in the Online Device Tree. 2. Right-click to access the Online Tree context menu. 3. Select Set Device/System to Factory Default. Using ID Mode To Change The Device Address On a NetLinx Device The ID Mode section of the Device Addressing dialog allows you to place the program in ID (Identity) mode. This is useful when the current address assignments are unknown. ID Mode means that the entire system is put on hold while it waits for an event from any NetLinx device in the named system (for example, a button push on a NetLinx Touch Panel). The device that generates the first event is the device that gets "identified". Once a device has been identified, it will be set (or changed to) the Device/System Address specified. Use the ID Mode options in the Device Addressing dialog to set or change the Device Address (Device and System ID numbers) for a NetLinx device.
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.

1. Enter the Device and System numbers that you want to assign to the device in the (Change to Device) Device and System text boxes.
The Destination System number must be a System that is defined in the URL List dialog.

2. Enter the Device and System numbers that you want to assign to the device in the (Change to Device) Device and System text boxes. 3. Click the Start Identify Mode button to place the named System in ID Mode. The text box below this button displays a WaitingPress Cancel to Quit message. The Start Identify Mode button changes to Cancel Identify Mode (click to cancel ID Mode). 4. Generate an event from the device that you want to assign the new Device and System numbers to: For NetLinx control panels, press any button to generate a Push. For NetLinx Masters, press the ID button on the rear panel. 5. The device that generated an event is assigned the new Device and System numbers. The Online Device Tree will refresh to represent the new device address.

132

NetLinx Studio (v2.4 or higher)

Working With Online Devices

NetLinx Diagnostics - URL Lists


Use the URL Listing dialog to create a URL List for the specified master. The URL List identifies all NetLinx devices present in the same System as the Master that you are connected to. You must enter a URL for each device in the System before you can use ID Mode on other devices.
Only devices defined in the URL list will appear in the On-line device tree (with the exception of the Master that you are connected to).

Creating a URL List 1. Select Diagnostics > URL Listing (or click the toolbar button) to access the URL Listing dialog. 2. Enter the System and Device numbers for the Master that you are connected to in the appropriate text boxes. The range is 0-65535. 3. To add a device to the URL List, click Add. This opens the Add URL dialog. 4. Enter the web address (URL or IP Address) of the device in the URL text box and click OK to return to the URL List dialog.

If you enter a valid URL for a device, the program generates the device's IP Address.

5. Initially the connection status reads Looking up URL. Once found, the new device appears in the URL List with its IP Port assignment = 1319.
Do not change the IP Port number! An IP Address is assigned to this URL and is displayed in the IP Address column.

6. Click Get URL List to refresh the URL List after adding a device. 7. Repeat steps 1-5 for as many additional devices as are required. To retrieve a list of all URL's in the list, click Get IRL List. The URL List is populated with all previously set URL's. To remove a URL from the list, select the URL and click Remove. To clear all URL's from the list, click Remove All.

NetLinx Studio (v2.4 or higher)

133

Working With Online Devices

NetLinx Diagnostics - Network Addressing


Use the options in the Networking Addresses dialog to change the network settings for a specified NetLinx master.
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.

Changing the System Number On a Netlinx Master Use the System field in the Network Addresses dialog to change the System number for the connected Master: 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, specify a new System number in the System text box. 3. Click the Reboot Master button to reboot the master and accept the new changes. Allow 20-30 seconds for the master to reboot. Changing the IP Address On a NetLinx Device Using DHCP Use the IP Address options in the Network Addresses dialog to change the IP Address for a specified NetLinx Device (using DHCP): 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name and Gateway assignments. 4. Click the Use DHCP radio button, and enter a new Host Name in the text box, if necessary. 5. Click the Set IP Information button to set the new Host Name assignment. 6. Click the Reboot Master button to reboot the master and accept the new changes. Allow 2030 seconds for the master to reboot.
When you change the IP Address of a master (if connected via IP), you must also change the communication settings to match the new IP Address in the Master Communications Settings dialog.

Setting the DNS Address For a Netlinx Master 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. Enter the specified device's System and Device values in the text boxes at the top of the dialog (ranges = 0-65535).

134

NetLinx Studio (v2.4 or higher)

Working With Online Devices

NXI masters are always set to Device = 0.

3. Click Get DNS Information to populate the DNS Address fields with the current Domain Suffix, DNS IP Address #1, DNS IP Address #2 and DNS IP Address #3 assignments (as applicable). 4. Edit the DNS Address assignments and/or add new DNS address information as needed. 5. Click Set DNS Information to set the new DNS address assignments. Setting the IP Address For a NetLinx Master 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes (range = 0-65535). 3. Click Get IP Information to populate the IP Address fields with the current Host Name, IP Address, Subnet Mask and Gateway assignments. 4. Click the Specify IP Address radio button, and enter the new IP Address, Subnet Mask and Gateway assignments in the text boxes, as necessary. 5. Click Set IP Information to set the new IP Address assignment. 6. Click Reboot Master... to reboot the master and accept the new changes. Allow 20-30 seconds for the master to reboot. Changing the IP Address On a Netlinx Master (Use DHCP) Use the options in the Network Addresses dialog to change the IP Address for a specified NetLinx device (using DHCP): 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name and Gateway assignments. 4. Click the Use DHCP radio button, and enter the new Host Name in the text box, if necessary. 5. Click the Set IP Information button to set the new Host Name assignment. A message will be displayed indicating that the Master has accepted the new settings. 6. Click the Reboot Master... button to reboot the Master and accept the new changes. Allow 20-30 seconds for the Master to reboot.
If you change the IP Address of a Master (if connected via IP), you must also change the communication settings to match the new IP Address (in the Communication Setting dialog).

NetLinx Studio (v2.4 or higher)

135

Working With Online Devices

Changing the IP Address On a Netlinx Master (Specify IP Address) 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. Enter the specified master's System number in the System text box at the top of the dialog. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name, IP Address, Subnet Mask and Gateway assignments. 4. Click the Specify IP Address radio button, and enter the new IP Address, Subnet Mask and Gateway assignments in the text boxes, as necessary. 5. Click the Set IP Information button to set the new IP Address assignment. A message will be displayed indicating that the Master has accepted the new settings. 6. Click the Reboot Master... button to reboot the Master and accept the new changes. Allow 20-30 seconds for the Master to reboot.

Setting NetLinx Time and Date


Select Tools > Set Master Controller's Date/Time to open the Set Master Controller's Date/Time dialog. Use the options in this dialog to set the time and date for a specified NetLinx Master. 1. In the Master Controller ID text box, enter/edit the target System number (if necessary). 2. To retrieve the current Time/Date settings for the specified target Master, click Get Time/Date. The Master's current Time/Date settings are displayed in the (read-only) text field. 3. To change the target Master's date setting, click the down arrow next to the Date field to open the calendar window. To change the system's date, click to select the desired day. Use the forward and back arrow buttons to change the month. When you select a new date, the calendar closes and the new date is represented in the Date field. To set the system to today's date, click Today at the bottom of the calendar. 4. To change the target Master's time setting, select a field within the time display (hours, minutes, seconds, or AM/PM) and click the up and down arrows to adjust the selected field. Alternatively, you can highlight the field in the Time display that you want to adjust and type the desired number in its place. If no field is selected within the time display, the up/down arrows affect the hours setting. 5. To set the specified Time/Date settings for the target system click Set Time/Date.
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.

136

NetLinx Studio (v2.4 or higher)

Working With Online Devices

Rebooting the Master


Select to access the Reboot the Master Controller dialog. Use the options in the Reboot the Master Controller dialog to reboot a specified master controller: 1. The left side of this dialog lists the Projects and Systems that are included in the currently open workspace. By default, the currently active System is highlighted, as shown below. The Master specified in the active (highlighted) System is the one that will be rebooted. 2. Click on any other System to select a different Master to reboot. 3. Once the desired System has been selected (highlighted), click the Reboot button to reboot the Master associated with the selected System. All communications to the Master are stopped in order to activate a connection and initiate the reboot process. Allow 20-30 seconds for the reboot. You can reboot more than one Master before closing this dialog. 4. Click Done to close this dialog.

Axcess/NetLinx Debugging
Debugging Source Code Files NetLinx Studio contains several useful options for debugging your Master Controller and Source Code files.
The Debugging feature allows you to view variables declared within the scope of a Function and or Call procedure. However, stack and parameter values are not editable. If you attempt to edit either the stack or parameter values, a warning message is displayed.

In order to begin debugging, your computer must be connected to a Master Controller, and you must have a compiled Source Code file active. To use debugging, the Build With Source option must be selected in the Axcess Compiler and/or NetLinx Compiler tabs of the Preferences dialog, before the file is compiled. For NetLinx code, select You cannot compile, send/receive files, or change port settings while the program is in debug mode. Avoid declaring variables as volatile whenever possible, since volatile variables will not display their contents during the debug session. NetLinx character strings by default are displayed in current length mode, while all other strings (including Integer strings) are displayed in total length mode. To enter debug mode: 1. Open and compile a Source Code file (that contains at least one variable), if you have not already done so. The file must be successfully compiled before you can enter debug mode. 2. Choose Build > Debug (or click the toolbar button) to open the Watch window. If this option is disabled, make sure your Master Communications Port settings are set to connect to your Master Controller.

NetLinx Studio (v2.4 or higher)

137

Working With Online Devices

3. Right-click inside the Watch window to open the Watch Window context menu. 4. Click Add to insert a new variable in the Watch window. A box appears in the window, with a cursor blinking in the Name column. 5. Type the syntax of the variable exactly as it is defined in the code and press the Enter key. The value of the specified variable appears next to the variable (in the Value column). 6. You can select different view formats for the Value by right-clicking on the line containing the variable/value, and clicking on Display in the Watch window context menu. This opens the Display sub-menu, containing the following view options:
ASCII Display Decimal Display displays the value of the watched variable in ASCII format. displays the value of the watched variable in decimal format.

Hexadecimal Display displays the value of the watched variable in hexadecimal format. Octal Display Binary Display displays the value of the watched variable in octal format. displays the value of the watched variable in binary format.

To exit Debug mode, close the Watch window. Notes on Using Current Length (when the Total Length option is disabled): The way you initialize variables in your source code affects the use of Current Length. For example, if you have a variable declared as:
CHAR cat[3]

in debug, Total Length = 3 and Current Length = 0. If you modified the code as:
CHAR cat[3] = 'CAT'

in debug Total Length = 3 and Current Length = 3. If you modified the code like this:
CHAR cat[3]

and then in the DEFINE_START section of your code you added:


cat[1] = 'C' cat[2] = 'A' cat[3] = 'T'

in debug Total Length = 3 and Current Length = 0, because setting values using array indexing does not set the current length. Master Controller Debug Options The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of variables within a compiled Axcess or NetLinx program. Also, you can control the execution through each pass of the mainline of a compiled Axcess or NetLinx program. Once Start Debugging has been selected, the other options in the Debug menu become available:
Start/Stop Debugging Ability to toggle the debug state of the application. There is no limitation on then number of NetLinx variables that can be watched in the Debug Watch windows. A maximum of 10 watch variables are allowed when debugging an Axcess master controller.

138

NetLinx Studio (v2.4 or higher)

Working With Online Devices

Step Mode

Enable/Disable Step mode causes the Interpreter to break after each execution of the mainline. Watch variables are always updated after each pass through mainline. To continue program execution while in Step mode, you must invoke the "Step" command again. Execute one line of a source code file at a time for a NetLinx master controller or execute one pass through the mainline code for an Axcess controller.

Single Step

The following options are only needed for debugging code on a NetLinx master: Run Run To Cursor Break Edit Breakpoints Toggle Break Point Clear Break Points To continue execution after a Single Step operation or from a toggled break point. Execute the program and break on the line of code where the cursor is residing on the screen. Stop execution of the program and highlight the line of code on the screen. A dialog box appears listing all the break points within the code. Toggle a break point on the screen where the cursor is residing. A red diamond appears next to the line of code to signify a break point. Clears all the break points within the source code file.

Changing The Value Of a Watched Variable Once you have entered Debug mode, you can change the name and/or value of any watched variable, via the Value column in the Watch window: 1. Select a watched variable in the Watch window. 2. To change the variable's value, double-click on the desired variable's value to change the value to an edit field, which you can modify as desired.

NetLinx Studio (v2.4 or higher)

139

Working With Online Devices

140

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

Communications and File Transfers


Configuring Default Communications Settings
The Master Communication Settings dialog contains options that allow you to specify the default communication settings for NetLinx Studio. The default settings will be used when there is not a Workspace file open, or when the open Workspace does not have an active System. To set the default communication settings: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click to select <No Active Settings-Default Settings> from the Available System(s) list. 3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (TCP/IP, Serial, Modem or Virtual NetLinx Master).
The TCP/IP and Virtual NetLinx Master options are only available if NetLinx is selected as the platform.

6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog). For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1

Flow Control None

Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.

7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog.

NetLinx Studio (v2.4 or higher)

141

Communications and File Transfers

Alternatively, you can access these option via the Set Default Communication Settings with the IP option in the Network Addresses dialog.

Configuring System-Level Communications Settings


The Master Communication Settings dialog contains options that allow you to specify System-level communication settings. Each System can have its own dedicated communication settings. These System-level settings override the default communications settings. To set System-level communication settings: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. The Available System(s) list in this dialog represents all Systems contained within the open Workspace (and their parent Projects). 2. Click to select a System from the Available System(s) list.

FIG. 26 Available System(s) list

3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (TCP/IP, Serial, Modem or Virtual NetLinx Master).
The TCP/IP and Virtual NetLinx Master options are only available if NetLinx is selected as the platform.

6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog). For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1

Flow Control None

142

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.

7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. Alternatively, you can also access these System-level communications settings options via the System Properties dialog: 1. Select (highlight) a System in the Workspace tab of the Workspace Window, and select System Properties from either the Project menu or the System Folder context menu (or click the toolbar button) to open the System Properties dialog. 2. In the Communication Settings area (at the bottom of the dialog), click Communication Settings to open the Communication Settings dialog. 3. Follow steps 4 through 8 (above) to specify communication settings for the selected System.

Configuring Terminal Communications Settings


The Terminal window has it's own dedicated communications settings. Use the options in the Master Communication Settings dialog to specify communication settings for the Terminal window: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click to select the second item in the Available System(s) list (labeled <Terminal Settings>).

FIG. 27 <Terminal Settings>

3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (Serial or Modem). 6. Click Edit Settings to specify the communication settings for the selected connection option: For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem (serial-modem) connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog.

NetLinx Studio (v2.4 or higher)

143

Communications and File Transfers

Setting the Default Control Platform


You can set the default control platform and communication settings via the Configuration settings in the Master Communication Settings dialog: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Select <No Active System-Default Settings> in the Available System(s) list. With this selection, you are setting the default platform and communication settings for all new Projects/ Systems and System files. 3. Click the Configure button to access the Communication Settings dialog. 4. Select the Platform (NetLinx or Axcess) to be used as the default. 5. Click OK to save your changes and close the Communication Settings dialog. 6. Click OK to close the Master Communication Settings dialog.

Changing The System Platform (Axcess / Netlinx)


You can change the designated Platform (Axcess or NetLinx) for a System via the Platform Selection options in the Communication Settings dialog: 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. The Available System(s) list in this dialog represents all Systems contained within the open Workspace (and their parent Projects). The currently active System is highlighted in this list 2. Click to select a System from the Available System(s) list. 3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default platform (NetLinx or Axcess). Note that if you select NetLinx, a Module System file folder is included in the Workspace tab of the Workspace Window.

Connecting To A Netlinx Master


To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the TCP/IP address, serial port or modem settings, depending on the transport connection type specified. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. Configuring Virtual Netlinx Master Communication Settings (Netlinx Only) 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Select NetLinx Master as the Platform Selection. 3. Select Virtual NetLinx Master as the Transport Connection Option. 4. Click Edit Settings to access the Virtual NetLinx Master Settings dialog, which displays the System number (and IP address) of the Virtual NetLinx Master (default = 1). Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as

144

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.

5. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new VNM communication settings with the selected file. Connecting To a Netlinx Master Via TCP/IP To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the TCP/IP address. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select TCP/IP as the Transport Connection Option. 5. Click Edit Settings to open the TCP/IP Settings dialog. 6. Enter the TCP/IP Address of the master.
The Port should always be set to 1319 (default setting). Do not change the Port assignment.

7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display.

FIG. 28 System icon

12. Double-click the System icon to expand the tree to show the NetLinx master.

NetLinx Studio (v2.4 or higher)

145

Communications and File Transfers

Connecting To a NetLinx Master Via Serial Port To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the serial port settings. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select Serial as the Transport Connection Option. 5. Click Edit Settings to open the Serial Settings dialog. 6. Select a COM port and specify the communication settings for serial port communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1

Flow Control None

7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 12. Double-click the System icon to expand the tree to show the NetLinx master. Connecting To A NetLinx Master Via Modem To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the modem settings. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select Modem as the Transport Connection Option. 5. Click Edit Settings to open the Modem Port Settings dialog.

146

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

6. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None

Phone Number Enter the telephone number of the master.

7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 12. Double-click the System icon to expand the tree to show the NetLinx master. Connecting To A Secured Netlinx Master When connecting to a NetLinx Master that has security enabled, you will be required to enter a User Name and Password before you can connect. To establish a connection to a secured master, 1. Select Settings > Communication Settings to open the Communication Settings dialog and select NetLinx as the platform and select a Transport Type. 2. Click Edit Settings to configure the selected transport type. 3. Click OK to save the TCP/IP, Serial or Modem settings (depending on the transport type selected). 4. Click the Authentication Required checkbox. This enables the User Name and Password button. 5. Click on User Name and Password to enter the User Name and Password that are set for this NetLinx Master (in the Master Controller User Name and Password dialog). These are case sensitive. 6. Click OK to close the Master Controller User Name and Password dialog. 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. At this point you should be able to connect to the Master.

NetLinx Studio (v2.4 or higher)

147

Communications and File Transfers

If you don't connect: Verify that the master is set for ICSP Connectivity, with Require Encryption enabled (via the Master's built-in interface). Refer to the Master's documentation for details on enabling/disabling security.

Connecting To an Axcess Master


To connect to an AXCESS master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the serial port or modem settings, depending on the transport connection type specified. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the AXCESS master is established. Connecting To An Axcess Master Via Serial Port To connect to an AXCESS master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the serial port or modem settings, depending on the transport connection type specified. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the AXCESS master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select Axcess Master as the Platform Selection. 4. Select Serial as the Transport Connection Option. 5. Click Edit Settings to open the Serial Settings dialog. 6. Select a COM port and specify the communication settings for serial port communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None

7. Click OK to return to the Communication Settings dialog. 8. Click OK to return to the Master Communication Settings dialog. 9. Click OK to close the Master Communications dialog. 10. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 11. Double-click the System icon to expand the tree to show the Axcess master. Connecting To An Axcess Master Via Modem To connect to an AXCESS master, use the options in the Master Communication Settings and Communication Settings dialogs to specify serial port or modem settings, depending on the

148

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

transport connection type specified. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select Axcess Master as the Platform Selection. 4. Select Modem as the Transport Connection Option. 5. Click Edit Settings to open the Modem Settings dialog. 6. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None

Phone Number Enter the telephone number of the master.

7. Click OK to return to the Communication Settings dialog. 8. Click OK to return to the Master Communication Settings dialog. 9. Click OK to close the Master Communications dialog. 10. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 11. Double-click the System icon to expand the tree to show the Axcess master.

File Transfer Operations


NetLinx Studio supports asynchronous communications (send and receive to and from the bus on all available communications ports simultaneously). You can send and receive both Axcess and NetLinx Source Code files to and from the Master Controller or bus device. Axcess or NetLinx Source Code files (.AXS) can be sent to the Master Controller, or other control devices on the bus. Source code files must be successfully compiled before they can be sent. Touch Panel UI files created in TPDesign3 (.TPD) are sent directly to wired Touch Panels on the bus via an AXlink/serial connection where the Device ID = 0. Touch Panel UI files created in TPDesign4 (.TP4) are sent to the Master, either serially or over TCP/IP. G4 panels are connected to the Masters via TCP/IP and cannot be sent over AXlink. You can choose to include buttons and pages only, or include fonts, bitmaps and/ or icons in the transfer. KeyPad UI files (.KPD) are sent to a NetLinx Master.

NetLinx Studio (v2.4 or higher)

149

Communications and File Transfers

IR library files (.IRL/.IRV) are sent to IR-controlled devices on the bus, or directly to a System device (i.e. Touch Panels). The Virtual NetLinx Master option allows you to transfer files directly to G4 devices, without the need for an intermediate NetLinx Master. The File Transfer dialog (Tools > File Transfer) provides an easy to understand approach to file transfer while still providing a high level of flexibility. File Transfers Edit Sub-Menu With a file selected in the Files To Send table (of the File Transfer dialog), click the Edit command button to open the File Transfers Edit sub-menu, containing the following options: Options - This option is only available if you have selected a TPD or TP4 touch panel UI file. If you have selected a TPD (TPdesign3) file, this option opens the TPD Transfer Options dialog, where you can select which parts of the TPD file to include when the file is sent (the options are Bitmaps, Fonts and Icons - by default they are all selected). If you have selected a TP4 (TPDesign4) file, this option opens the TP4 Transfer Options dialog, where you can select to enable Smart Transfer. Smart Transfer automatically optimizes the transfer by identifying the various components (fonts, bitmaps, sound files, even pages and popup pages) of the selected panel file, and comparing them to the elements already present on the target panel. Any shared components are not sent, resulting in a much faster transfer (assuming that there are shared components).
When sending a TP4 file to a G4 panel, verify that the NetLinx Master Firmware is build 85 or later. Verify the TPDesign4 program being used is Version 1.01 or higher. Earlier versions of the firmware and TPD4 software are incompatible with G4 panels.

Communication Settings - Opens the Communication Settings dialog, where you can edit the Platform, Transport Connection type and Communication Settings for the selected file.
Alternatively, you can double-click in the Connection column to access the Communication Settings dialog.

Device Mapping - Opens the Enter DPS dialog, where you can view/edit the D:P:S assignment of the target device for the selected file.
In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0). Master Source Code files cannot be mapped to any other device. NetLinx Master Source Code files are mapped according to the System settings when the Project was created. The only way to modify these settings is via the System Properties dialog. Also, when sending TPD files directly to a Touch Panel (i.e. via serial cable connection), the device = 0.

150

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

File Transfer Status Information Once you have started a file transfer operation, the following types of status information are displayed in the File Transfer Status tab of the Output Display window:
Type Status Connection Mapping The type of transfer (sending or receiving). The current state of the transfer (Pending, Transferring, Complete or Failed). The communications settings used to establish communication with the target device. The number(s) used to identify the target device on the bus or the message "Direct to Device (No Master)" if the target device does not reside behind a master. The name and extension of the file being transferred. The full path of the file being transferred.

File Path

Bytes Transferred The number of bytes transferred, and the total number of bytes left to transfer. Error Last Transfer An error message if an error has occurred. The time and date of the last transfer.

Canceling Transfers A file transfer may be cancelled by right-clicking on the item in the Output Display Window - File Transfer Status tab and selecting Cancel Transfer from the context menu. Canceling an item that is not currently transferring removes it from the transfer queue.

Canceling during a file transfer may leave the target device in an unstable state.

Transfer Errors And Definitions The following table describe the most common error messages that might be displayed in the Error column of the Transfer Status Window.
Error String Failure Success File does not exist Failed to create temporary file Invalid file type Unknown Error File: <filename> does not exist and cannot be transferred! File: <filename> is currently opened by another application and cannot be transferred! Nothing to transfer! [Project Identifier invalid?] [System Identifier invalid?] Meaning Generic/unclassified failure. Generic success. The file supplied on the cmdline doesn't exist. Couldn't create a required temporary file. The file supplied on the cmdline is an unknown file type. Generic/unknown error. File does not exist at location specified. This can happen if another application has an exclusive lock on a file. After processing all supplied parameters and options, there was nothing to transfer. That is, no files could be found or nothing was specified for transfer. Additionally, if you specified a project identifier and/or a system identifier, you may have inadvertently requested an empty or nonexistent set of files. Failed to open workspace! AXW file does not contain an APW.

Failed to open workspace! No APW file

NetLinx Studio (v2.4 or higher)

151

Communications and File Transfers

Step 1: Adding Files To The Transfer Queue


Before files can be sent to or received from system devices, they must first be added to the Transfer Queue in either the Send or Receive tab. Using The Quick Load Dialog Use the options in the Quick Load dialog to specify which file types (of the files included in a selected Workspace file) to add to the Files To Send queue.

The Quick Load dialog is not used for receiving files.

There are several possible ways to access the Quick Load dialog: Click the Quick Load command button. If there is not already a Workspace file open, then the Quick Load dialog will indicate that no (zero) projects are open (no Project file/file path indicated in the top text field, and "New Workspace: 0 Project(s)" indicated in the main window. You should first open a Workspace file, then use the options in the Quick Start dialog to select the files within that Workspace file to add to Files To Send queue. Without having a workspace file open, you cannot select files for transfer via the Quick Start dialog. By default, FileTransfer2 opens the Quick Load dialog when a Workspace file is opened (via the Load Workspace button, or the File > Open Workspace/AXW/FTL File menu option. With at least one Workspace file open, the options in the Quick Load dialog allow you to specify which of the files contained in the Workspace file(s) to add to the Files To Send queue:
You can disable the Quick Load dialog from automatically opening by de-selecting the After opening a Workspace file. Visit the Quick Load dialog option in the Preferences dialog.

1. Selection Options menu - Click the down arrow to access the following load options: Active System - Loads only the files from the active System. Entire Workspace - Loads all files from the Workspace. Select System - Select an individual System from the Workspace to load. 2. File type checkboxes - The checkbox options in this dialog allow you to simplify the transfer operation by only sending only specific file types (including TKN, TOK, SRC, IRL, KPD, TP4 and TPD files). Use the Select All and Deselect All command buttons to streamline the selection process. Note that there are additional options associated with TP4 and TPD files. If you select TP4 Files, you also have the option of enabling Smart Transfer for those files. Similarly, if you select TPD files, you have the additional options of including Bitmaps, Icons, and/or Fonts for those files. 3. Remove Duplicates When Loading - Enable this option to prevent having any duplicate entries in the Files To Send queue (default = enabled).

152

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

Adding Files To The Files To Send Queue There are several possible approaches to adding files to the Files To Send List (Send tab). Add some or all of the files contained in a Workspace file or a Workspace-To-Go file. Add individual systems (see Supported File Types list). Notes: The file types that are available for selection depend on the selected Platform (Axcess or NetLinx), Send/Receive selection and Communication settings. All files must mapped to devices before they can be selected for transfer. You can edit the file's mapping information via the Edit menu (Device Mapping option), but without any mapping information associated with the file, it cannot be selected. Source Code files cannot be sent until they have been successfully compiled. While Touch Panel UI files are sent to the panels themselves, KPD files are sent to the master and not directly to the keypad. Before sending a KPD (KPDesign) file to the target keypad(s), be sure that you have successfully compiled the Source Code file that contains the keypad module, and sent it to the Master. Adding All Files Contained In An APW Or AXW File In the Send tab: 1. Select File > Open Workspace/AXW/FTL File or click the Load Workspace command button to open the Open File dialog. 2. Select either NetLinx Studio Files (*.apw) or Export-To-Go Files (*axw) from the File of Type drop-down menu (depending on which type of file contains the system files that you want to transfer). This dialog contains two tabs: Existing and Recent. Use the Existing tab to locate and select the desired file, with the ability to navigate through all available local and network drives. The Recent tab contains a listing of the most recently used files (of all types). 3. Locate and select the Workspace file that you want to add, and click Open. This opens the Quick Load dialog. 4. In the Selection Options section, select Entire Workspace. 5. Click Select All to add every file type in the Workspace, and enable the Remove Duplicates when Loading option. 6. Click OK to close the Quick Load dialog and add the files to the File To Send queue. Adding Files From A Specific Project/system In the Send tab: 1. Select File > Load Workspace/AXW/FTL File or click the Load Workspace command button to open the Open File dialog. 2. Set the File of Type drop-down to NetLinx Studio Files (*.apw).

NetLinx Studio (v2.4 or higher)

153

Communications and File Transfers

This dialog contains two tabs: Existing and Recent. Use the Existing tab to locate and select the desired file, with the ability to navigate through all available local and network drives. The Recent tab contains a listing of the most recently used files (of all types). 3. Locate and select the Workspace file that contains the Project/System with the file(s) you want to add, and click Open. This opens the Quick Load dialog. 4. In the Selection Options section: Select Active System to add files from the active System in the open Workspace. Select a Project-System to add files from a specific Project/System in the open Workspace. 5. Click in the checkboxes to specify which file types in the selected System to add. 6. Click OK to close the Quick Load dialog and add the files to the File To Send queue. Adding Individual System Files From The Open Workspace File With a Workspace (or Workspace To-Go) file open, use the Add command button (in the Send tab) to select individual System files to add to the Files To Send queue: 1. Click the Add command button to open the Select Files For File Transfer dialog. 2. Open the Current Workspace tab. This tab consists of a display of the (compiled) Source Code (.AXS), Token (.TKN), UserInterface (.TPD/.TP4) and IR (.IRL) files contained in the currently open Workspace. Use the options in the Current Workspace tab to locate and select file(s) for transfer to the Master or System devices on the bus. Use this tab if the file(s) you want to transfer are included in the open Workspace. 3. Click OK to add the selected file(s). Adding Orphan Files In the Send tab: 1. Click the Add command button to open the Select Files For File Transfer dialog. 2. Open the Other tab. Use this tab if the file(s) you want to transfer are not included in the open Workspace. This tab consists of a display of the different types of files that can be transferred to the Master or System devices on the bus: IR Codes (*.IRL/*.IRV) NetLinx Source Code (*.SRC) Compiled NetLinx Source Code (*.TKN) Compiled Axcess Source Code (*.TOK) Touch Panel Design File (*.TPD) TP4 Touch Panel (*.TP4) KPD Keypad Touch File (*.KPD)

154

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

3. Select the type of file that you want to add to the Transfer List. 4. Click the Add button. This invokes the Open dialog, with the Files of Type selection already set to the selected file type. 5. In the Open dialog, locate and select the file that you want to add. 6. Click Open to add the selected file to the Files To Send queue. Adding Files To The Files To Receive Queue

IR files cannot be received from Axcess Master controllers.

To add files to the Files To Receive queue: 1. Open the Receive tab. 2. Click the Add command button to open the Select Files For Transfer dialog. 3. Select the type of file you want to receive from the system device (IRL/IRV, TPD, SRC, AXS or TP4), and click Add (opens the Save As dialog).
The file types that are available for selection depend on the selected Platform (Axcess or NetLinx), Send/Receive selection and Communication settings.

4. In the Save As dialog, specify a name and target directory for the retrieved file. Click Save to close this dialog and open the Enter Device Mapping Information dialog. 5. Enter the Device, Port and System numbers for the source device, and click OK to close the dialog and add the to the File list at the bottom of the Select Files To Transfer dialog. 6. Click Settings in the Communication Settings section at the bottom of the dialog to open the Communication Settings dialog and specify the communication settings for the source device. Note that in the Select Files For File Transfer dialog, communication settings apply to every file in the File list (since in this case the communication settings are relating to a system device that is the source for files you are receiving, not to individual files that may be sent to any of several devices in the system). 7. Click OK to close the Select Files For File Transfer dialog. The files you added should now appear in the Files To Receive queue of the Receive tab. 8. Repeat steps 2 - 7 to add files to retrieve from different system devices to the Files To Receive queue.

NetLinx Studio (v2.4 or higher)

155

Communications and File Transfers

Step 2: Communication Settings


Use the options in the Master Communication Settings dialog to set the communication settings for connecting to a NetLinx or Axcess master controller. A connection can be made to a NetLinx master controller via TCP/IP, Serial-RS232, Modem. A connection can be made to a Axcess master controller via Serial-RS232 or a Modem. Listening For Netlinx Masters On The Subnet Click the Listen button in either the TCP/IP Settings dialog or the URL Listing dialog to listen for "blink" (UDP) messages from NetLinx Masters on the same subnet, in the Listen For Masters dialog. As NetLinx Masters are detected on the subnet, they are displayed in the Listen For Masters dialog, with the option of adding them to the List of Addresses in the TCP/IP Settings dialog. Configuring Communications Settings NetLinx Studio v2 allows you to specify and maintain separate communications settings for each file in the Files To Send and Files To Receive queues: 1. Select a file (Send or Receive tabs). 2. Click the Edit command button and select Communication Settings from the Edit menu to open the Communication Settings dialog. a. Select a Platform for this transfer (Axcess or NetLinx). b. Select a Transport Connection Option (TCP/IP, Serial, Modem or Virtual NetLinx Master).
The TCP/IP and Virtual NetLinx Master options are only available if NetLinx is selected as the platform.

c. Click Edit Settings to specify the communication settings for the selected connection option. 3. Click OK to close the Communication Settings dialog. Configuring TCP/IP Communication Settings (Netlinx Only) With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Select NetLinx Master as the Platform Selection. 3. Select TCP/IP as the Transport Connection Option. 4. Click Edit Settings to open the TCP/IP Settings dialog. 5. Enter the TCP/IP Address of the master: a. Click New to open the New TCP/IP Setting dialog. b. Enter the new TCP/IP Address and (optional) Description in the text fields provided.

156

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

c. By default, the program is set to automatically ping the master controller to ensure availability. De-select this option if desired.
The Port should always be set to 1319 (default setting). Do not change the Port assignment.

d. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new TCP/IP communication settings with the selected file. Configuring Serial Communication Settings With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Specify the Platform Selection (NetLinx Master or Axcess Master). 3. Select Serial as the Transport Connection Option. 4. Click Edit Settings to open the Serial Settings dialog. 5. Select a COM port and specify the communication settings for serial port communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None

6. Click OK to return to the Communication Settings dialog. 7. Click OK to save the new Serial communication settings with the selected file. Configuring Modem Communication Settings With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Specify the Platform Selection (NetLinx Master or Axcess Master). 3. Select Modem as the Transport Connection Option. 4. Click Edit Settings to open the Modem Settings dialog. 5. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity COM1 38400 8 None

NetLinx Studio (v2.4 or higher)

157

Communications and File Transfers

Stop Bits Flow Control

1 None

Phone Number Enter the telephone number of the master.

6. Click OK to return to the Communication Settings dialog. 7. Click OK to save the new Modem communication settings with the selected file. Configuring Virtual Netlinx Master Communication Settings (Netlinx Only) 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Select NetLinx Master as the Platform Selection. 3. Select Virtual NetLinx Master as the Transport Connection Option. 4. Click Edit Settings to access the Virtual NetLinx Master Settings dialog, which displays the System number (and IP address) of the Virtual NetLinx Master (default = 1). Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.

5. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new VNM communication settings with the selected file. Configuring the Panel For Virtual Netlinx Master TCP/IP Transfers If it is not already powered up and connected, apply power to the G4 panel and verify that it is connected to the LAN via the TCP/IP connector on the rear (or side) of the panel. 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select Ethernet as the Master Connection. 6. Set the System Number to 0 (zero). 7. Select the Master URL / IP input box and enter the IP address of your PC.
To get your PC's IP address, select Start > Run and type cmd to open a DOS window. Then, enter ipconfig to display the IP address of your PC.

8. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel.

158

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

9. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device.

Step 3: Device Mapping


Setting Device-File Mapping Information Every time you select a file (to send or receive) via the Select Files For File Transfer dialog (Other tab), the program prompts you to enter (or verify) its device mapping information, in the Enter Device Mapping Information dialog. Use this dialog to define the Device:Port:System (D:P:S) address assignment for a target device. Editing Device Mapping Information 1. Select a file in the Transfer List (Send or Receive tab). 2. Click Edit to open the Edit menu, and select Device Mapping. This opens the Enter DPS dialog. 3. Enter the Device:Port:System (D:P:S) information for the selected file. 4. Click OK to save the D:P:S assignment and close the dialog.

Step 4: Transferring the Files


Sending Files To System Devices Once you have: 1. Added the desired file(s) to the File To Send Queue, 2. Configured the communication settings for the files in the list, and 3. Specified the device-file mapping information for the files in the list, ...you are ready to begin transferring the file(s) to devices in the system: Click the Send command button. This initiates the transfer of every file listed in the Transfer (Send) List, in the order in which they are listed (top to bottom). The progress and status of each file transfer is indicated in the File Transfer Status tab of the Output Window. Receiving Files From System Devices Once you have: 1. Added the desired file(s) to the File To Receive Queue, 2. Configured the communication settings for the files in the list, and 3. Specified the device-file mapping information for the files in the list, ...you are ready to begin receiving the file(s) from devices in the system: Click the Receive command button. This initiates the transfer of every file listed in the Files To Send List, in the order in which they are listed. The progress and status of each file transfer is indicated in the Transfer Status Window.

NetLinx Studio (v2.4 or higher)

159

Communications and File Transfers

Receiving Files Directly From A System Device (Serial Connections Only) To receive files directly from a system device (Serial connections only): 1. In the Receive tab, click to select a file in the Files to Receive queue. 2. Click Edit to open the Edit menu and select Device Mapping. This opens the Enter DPS dialog. 3. Enter the Device:Port:System (D:P:S) information for the selected file. 4. Check the Connect directly to the device - No Master... option. 5. Click OK.

Virtual NetLinx Master (Masterless) Transfers


NetLinx Studio v2.1 (or higher) supports direct connection to G4 panels via TCP/IP and USB, for situations where the target panel is not connected to a NetLinx Master. In this situation, you can use your PC's Ethernet or USB connectors to connect directly to the panel, using your PC as a Virtual NetLinx Master. Virtual NetLinx Master supports both TCP/IP and USB connections. Virtual NetLinx Master can be used to transfer TPDesign4 panel (.TP4) file, NetLinx Firmware (.KIT) files, or IR Files directly to G4 touch panels. G4 touch panels that support USB connection include the MVP-8400, MVP-7500 and NXD/T-CV7. USB direct transfers require that you configure the Master Connection setting on the panel itself to USB prior to attempting the transfer. TCP/IP direct transfers require that you configure the Master Connection setting on the panel itself to TCP/IP prior to attempting the transfer. Virtual Netlinx Master USB Transfers TPDesign4 v2.2 (or higher) supports direct connection to G4 panels via USB (and TCP/IP), for situations where the target panel is not connected to a NetLinx Master. In this situation, you can use your PC's USB connection to connect directly to the panel, using your PC as a Virtual NetLinx Master. There are three basic steps to Virtual NetLinx Master USB file transfers: Configuring the Touch Panel for Virtual NetLinx Master USB Transfers Configuring NetLinx Studio for Virtual NetLinx Master USB Transfers Transferring Files Using a Virtual NetLinx Master USB Connection If it is not already powered up and connected, apply power to the G4 panel and verify that it is connected to the PC running NetLinx Studio via the USB connector on the rear (or side) of the panel.

160

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

Configuring the Touch Panel for Virtual NetLinx Master USB Transfers Connect the Panel to Your PC Via USB: 1. Apply power to the panel by plugging in the power supply. 2. Wait for the splash screen to disappear, then use a (Type A) USB cable to connect the panel to an available USB port on your PC. Plug the USB cable into the panel first, then connect to the PC. Configure the Panel for USB Virtual NetLinx Master Transfers: 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select USB as the Master Connection. 6. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device. AMX USB Driver Information For USB Enabled G4 Panels The AMX USB driver (required to connect to USB-enabled G4 panels via USB) is included with the NetLinx Studio (as well as TPDesign4) installation programs. Once you have installed the latest version of either NetLinx Studio (v2.4 or higher) or TPD4 (v2.4 or higher), you should have the required USB driver. After having installed NetLinx Studio 2 (or TPDesign4), follow the steps below to ensure a valid USB connection to the G4 panels: 1. Power up the Panel without the USB cable connected to the panel. 2. Plug in the USB cable into the G4 panel. 3. You should see an USB icon show up in the System Tray. 4. Double click on the icon to bring up the list of USB devices (you should see the "AMX USB LAN LINK"" device in the list). 5. If the "Install Driver" dialog doesn't appear automatically, select the "Properties" button and then the "Update Driver" button. 6. When the Install Driver dialog does appear, click on the Next buttons, accepting all the default prompts. 7. The OS will complain about the fact that the driver you are installing/updating does not have a digital signature. This is acceptable, so select to continue the installation. 8. After installation is complete, you are ready to connect to the USB port of the G4 panel. a. Select Settings > Master Communication Settings to open the Master Communications Settings dialog.

NetLinx Studio (v2.4 or higher)

161

Communications and File Transfers

b. Click the Communication Settings button to access the Communication Settings dialog. c. Select Virtual NetLinx Master as the Transport Connection Option. d. Click OK to close this dialog. e. Click OK to close the Master Communication Settings dialog. Configuring NetLinx Studio for Virtual NetLinx Master Transfers 1. Select Settings > Master Communications to open the Master Communication Settings dialog. 2. Make a selection in the Available Systems list to specify the scope of this communication setting: Select <No Active System-Default Settings> to set Virtual NetLinx Master as the default communication setting. To set Virtual NetLinx Master as the communication setting for a particular system in the active project, select one of the Systems listed under NetLinx Project. 3. Click Communication Settings to access the Communication Settings dialog. 4. Verify that NetLinx Master is selected as the Platform Selection, and select Virtual NetLinx Master as the Transport Connection Option. 5. Click Edit Settings to access the Virtual NetLinx Master Settings dialog. 6. The System Number field is set to 1 by default. Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.

Transferring Files Using A Virtual Netlinx Master Usb Connection


Verify that Virtual NetLinx Master is selected as the Transport Connection Option in the Communication Settings dialog.

To use Virtual NetLinx Master to transfer TPDesign4 panel (.TP4) files, NetLinx Firmware (.KIT) files or IR files directly to a MVP-7500, MVP-8400 or NXD/T-CV7 panel via USB: 1. Select Tools > File Transfer to open the File Transfer dialog (open to the Send tab). 2. Click the Add button to open the Select Files for File Transfer dialog. 3. Click the Other tab, and select the type of file you want to transfer (only IRL/IRV, TP4 or IRN files can be transferred via a Virtual NetLinx Master connection). 4. Click the Add button. This invokes the Open dialog, where you can locate and select the file you want to transfer.

162

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

5. Select the desired file and click OK to close this dialog and invoke the Enter Device Mapping Information dialog. 6. Review the mapping information, and click OK to return to the Select Files for File Transfer dialog. 7. Click OK to return to the File Transfer dialog, where the new file should appear in the Files to Send list. 8. Click inside the checkbox to the left of the file you just added. Keep in mind that any files with a checkmark will be included in this transfer. Note that the Connection column indicates that the file you just added is using Virtual NetLinx Master. 9. Click the Send button to begin the transfer. Virtual NetLinx Master TCP/IP Transfers TPDesign4 v2.2 (or higher) supports direct connection to G4 panels via TCP/IP (and USB), for situations where the target panel is not connected to a NetLinx Master. In this situation, you can use your PC's Ethernet connection to connect directly to the panel, using your PC as a Virtual NetLinx Master. There are three basic steps to Virtual NetLinx Master TCP/IP file transfers: Configuring the Touch Panel for Virtual NetLinx Master TCP/IP Transfers Configuring NetLinx Studio for Virtual NetLinx Master TCP/IP Transfers Transferring Files Using a Virtual NetLinx Master TCP/IP Connection Configuring The Touch Panel For Virtual Netlinx Master Tcp/ip Transfers If it is not already powered up and connected, apply power to the G4 panel and verify that it is connected to the LAN via the TCP/IP connector on the rear (or side) of the panel. 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select Ethernet as the Master Connection. 6. Set the System Number to 0 (zero). 7. Select the Master URL / IP input box and enter the IP address of your PC.
To get your PC's IP address, select Start > Run and type cmd to open a DOS window. Then, enter ipconfig to display the IP address of your PC.

8. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel.

NetLinx Studio (v2.4 or higher)

163

Communications and File Transfers

9. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device. Configuring Netlinx Studio For Virtual Netlinx Master Tcp/ip Transfers 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Select the System that you want to set communication settings for (from the Available System(s) list. 3. Click the Communication Settings button to open the Communication Settings dialog. 4. Select [Virtual NetLinx Master] as the Transport Connection Option. 5. Click the Edit Settings button to access the Virtual NetLinx Master Settings dialog, which displays the System number of the Virtual NetLinx Master (default = 1). Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.

6. Click OK to close the Virtual NetLinx Master Settings dialog. 7. Click OK to close the Communication Settings dialog. Transferring Files Using A Virtual Netlinx Master Tcp/ip Connection
Verify that Virtual NetLinx Master is selected as the Transport Connection Option in the Communication Settings dialog.

To use Virtual NetLinx Master to transfer TPDesign4 panel (.TP4) files, NetLinx Firmware (.KIT) files or IR files directly to a MVP-7500, MVP-8400 or NXD/T-CV7 panel via TCP/IP: 1. Select Tools > File Transfer to open the File Transfer dialog (open to the Send tab). 2. Click the Add button to open the Select Files for File Transfer dialog. 3. Click the Other tab, and select the type of file you want to transfer (only IRL/IRV, TP4 or IRN files can be transferred via a Virtual NetLinx Master connection). 4. Click the Add button. This invokes the Open dialog, where you can locate and select the file you want to transfer. 5. Select the desired file and click OK to close this dialog and invoke the Enter Device Mapping Information dialog. 6. Review the mapping information, and click OK to return to the Select Files for File Transfer dialog. 7. Click OK to return to the File Transfer dialog, where the new file should appear in the Files to Send list.

164

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

8. Click inside the checkbox to the left of the file you just added. Keep in mind that any files with a checkmark will be included in this transfer. Note that the Connection column indicates that the file you just added is using Virtual NetLinx Master. 9. Click the Send button to begin the transfer.

Firmware Transfers
NetLinx Studio provides the ability to transfer KIT and TSK firmware files to a NetLinx or Axcess master controller. To send firmware files, select Tools > Firmware Transfers, then select either Send to NetLinx Device, or Send to Axcess Device from the sub-menu. Sending Firmware To a NetLinx Device (Kit File) Use the Firmware Transfers options in the Tools menu to update the firmware in NetLinx Master Controllers or System devices. NXI Master Controllers use Kit files for firmware upgrades. A Kit file (.KIT) is a package of several files, all of which are required to upgrade the firmware, and are available online via www.amx.com. The Online Device Tree (Online Tree tab of the Workspace Window) displays information about each online device, including the current firmware version. Before attempting to upgrade the firmware, you must have the appropriate Kit file for your NetLinx Master.
If for any reason your Kit file transfer should fail, continue to retry the transfer until you are successful. DO NOT reboot the Master, or change connections until the transfer is complete. Failure to complete this operation successfully may result in a factory repair of the Master.

To update NetLinx firmware: 1. Choose Tools > Firmware Transfers > Send to NetLinx Device to open the Send To NetLinx Device dialog. 2. Click the Browse button to navigate to the target directory (in the Browse For Folder dialog). The selected directory path is displayed in the Location text box. Assuming that the specified target directory contains one or more Kit files, the Kit files in the selected directory are displayed in the Files list box (with the file's last modified date and time). 3. Select the appropriate .KIT file from the list. 4. Enter the Device and System ID numbers for the target NetLinx Device in the Device and System text boxes. If the Kit file is determined to be specifically for the target Master, the Device number is forced to zero. If the Kit file is for an unspecified device, you must enter the correct Device ID number. You can use the Online Device Tree to determine the device's assigned ID. 5. Review the File, Connection, Address, and Target Device information before you send. Check the Reboot option (if required by the target device - see note below).

NetLinx Studio (v2.4 or higher)

165

Communications and File Transfers

Click the Send button to send the selected KIT file to the specified device. You can watch the progress of the transfer in the "Send to NetLinx Device" dialog. When the transfer is finished, and the reboot is complete, press the Close button.
If the device is a NetLinx Master or NXI, then the Reboot option is valid. Other NetLinx devices need to be given the command to reboot (if they support it). Allow 20-30 seconds for NetLinx Masters to reboot. When the Master has rebooted, the Status LED on the front panel blinks once a second to indicate that it is functioning properly. Once it has rebooted, click OK.

Sending Firmware To An Axcess Device (Tsk File) Use the Firmware Transfers options in the Tools menu to update the firmware in Axcess Masters. Axcess Master Controllers use .TSK files for firmware upgrades. To update Axcess firmware: 1. Choose Tools > Firmware Transfers > Send To Axcess Device to open the Send To Axcess Device dialog. 2. Click the Browse button to navigate to the target directory (in the Browse For Folder dialog). The selected directory path is displayed in the Location text box. Assuming that the specified target directory contains one or more TSK files, the TSK files in the selected directory are displayed in the Files list box (with the file's last modification date and time). 3. Select the desired TSK file from the list. 4. Click the Query command button to populate the Devices list with a list of all Axcess devices currently online and capable of receiving the firmware. 5. Select the target AXlink device from the list. 6. Review the File, Connection, and Target Device information before you send. Click the Send button to send the selected TSK file to the specified device. You can watch the progress of the transfer in the "Send to Axcess Device" dialog. Once the TSK file has been transferred, the program prompts you to reboot the Master. Click Yes to reboot, and the program initiates the reboot sequence. When the Master has rebooted, the Status LED on the front panel of the Master blinks once a second to indicate that it is functioning properly. Once it has rebooted, click OK.

166

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

Netlinx Master Security


NetLinx Studio (v2.3 or higher) supports security for NetLinx Masters, via the Authentication Required option in the Communication Settings dialog. Before you can enable/disable NetLinx security on a Master through NetLinx Studio, you must verify the following: The target Master has been loaded with firmware that supports security. This means that the Master must have Master Firmware version 304 (or higher) to support this functionality. If your master does not have firmware loaded that supports security, the Master will not be secured (although it might appear to be in NetLinx Studio). Security has been enabled on the target Master (via options in the Security tab of the Master's built-in interface). Refer to the Master's documentation for details on enabling/ disabling security. With security enabled, users will be required to provide the correct User Name and Password in order to establish communication with the Master. The User Name and Password are case-sensitive. If the correct User Name and Password are not entered, NetLinx Studio will display an "Authentication Failure" message, and the connection to the Master will be denied. You can apply a default User Name and Password to the No active System - Default Settings option, so that as you create new NetLinx systems they will always require that User Name/Password combination.
This security option is not available for Axcess masters, or for NetLinx Virtual Master connections.

Enabling Security On Netlinx Masters Before you can enable/disable security on a NetLinx Master through NetLinx Studio, you must: Have loaded firmware in the target Master that supports security. This means that the Master must have NetLinx Master Firmware version 304 or higher to support this functionality. If your master does not have firmware loaded that supports security, the Master will not be secured (although it might appear to be in NetLinx Studio). Have security enabled on the target Master (via options in the Security tab of the Master's built-in interface). Refer to the NetLinx Master's documentation for details on enabling/ disabling security. You must first establish communication with the NetLinx Master in order to apply security (see Connecting to a NetLinx Master). 1. Once you are connected to the Master that you want to apply security to, select Settings > Master Communication Settings to access the Master Communication Settings dialog.
You can apply a default User Name and Password to the No active System - Default Settings option, so that as you create new NetLinx systems they will always require that User Name/Password combination.

NetLinx Studio (v2.4 or higher)

167

Communications and File Transfers

2. Verify that you have connected to the desired Master by checking the information in displayed in the Configuration window. 3. Click the Communication Settings command button to access the Communication Settings dialog. 4. Click to select the Authentication Required option. This enables the User Name and Password command button. 5. Click the User Name and Password button to access the Master Controller User Name and Password dialog. 6. Enter the User Name and Password that will be required to establish communication with this Master (as long as the Authentication Required option is selected). The User Name and Password must each be between 4 and 20 characters long. 7. Click OK to save your changes and return to the Communication Settings dialog. 8. Click OK to save your changes and return to the Master Communication Settings dialog. Now that security has been applied to the Master, note that the Master Security Status icon in the Status Bar changes to indicate that the Master is "locked" (FIG. 29).
= Master is secured = Master is unsecured FIG. 29 Master Security Status icons

Master Controller User Name and Password Dialog Click the User Name and Password command button (in the Communication Settings dialog) to access the Master Controller User Name and Password dialog. Use this dialog to specify a User Name and a Password for the secured NetLinx Master (this option is only enabled if the Authentication Required option is enabled). The User Name and Password must each be between 4 and 20 characters long. Once these have been applied, any user must provide both correctly in order to establish communication with the Master. If the User Name and Password are not entered correctly, the program will indicate failed authentication status in the Connection Status and Reboot the Master Controllers dialogs. Applying Security To Individual File Transfers In addition to the security for NetLinx Masters that can be enabled per system, NetLinx Studio (v2.3 or higher) also allows you to apply security to individual file transfers via options in the File Transfer dialog. With security enabled on a file transfer operation, users will be required to provide the correct User Name and Password in order to transfer the file to/from the Master.

168

NetLinx Studio (v2.4 or higher)

Communications and File Transfers

When you apply security to an individual file transfer operation (as described below), the individual file's security settings will be overridden by the security set for the target Master. For example, if the target Master already has security enabled (via the Authentication Required option in the Communication Settings for that Master), the user will have to provide the correct User Name and Password set for that Master, even if the File also requires a User Name and Password to successfully transfer to/ from the Master.

Before you can enable/disable NetLinx security on a File Transfer operation, you must verify the following: The target Master has been loaded with firmware that supports security. This means that the Master must have Master Firmware version 304 (or higher) to support this functionality. If your master does not have firmware loaded that supports security, the Master will not be secured (although it might appear to be in NetLinx Studio). Security has been enabled on the target Master (via options in the Security tab of the Master's built-in interface). Refer to the Master's documentation for details on enabling/ disabling security. To Apply Security To an Individual File Transfer Operation: 1. Queue up one or more files in the File Transfer dialog. 2. In the File Transfer dialog, click to select a file transfer from the list of files in the queue. 3. Click the Edit button and select Communication Settings from the drop-down menu to open the Communication Settings dialog. The settings you specify here are applied only to the selected File Transfer operation. 4. Click to select the Authentication Required option. 5. Click the User Name and Password button to open the Master Controller User Name and Password dialog, and enter the User Name and Password combination that the program will require in order to start this file transfer. Once security is applied, if the correct User Name and Password are not entered when prompted, NetLinx Studio will display an "Authentication Failure" message in the Error column of the File Transfer Status window, and the transfer will not complete. Connecting To a Secured Netlinx Master When connecting to a NetLinx Master that has security enabled, you will be required to enter a User Name and Password before you can connect. To establish a connection to a secured master, 1. Select Settings > Communication Settings to open the Communication Settings dialog and select NetLinx as the platform, and select a Transport Connection type. 2. Click Edit Settings to configure the selected transport type. 3. Click OK to save the TCP/IP, Serial or Modem settings (depending on the transport type selected). 4. Click the Authentication Required checkbox. This enables the User Name and Password button.

NetLinx Studio (v2.4 or higher)

169

Communications and File Transfers

5. Click on User Name and Password to enter the User Name and Password that are set for this NetLinx Master (in the Master Controller User Name and Password dialog). These are case sensitive. 6. Click OK to close the Master Controller User Name and Password dialog. 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. At this point you should be able to connect to the Master. If you don't connect: Verify that the master is set for ICSP Connectivity, with Require Encryption enabled (via the Master's built-in interface). Refer to the Master's documentation for details on enabling/disabling security.

Tested Modems List


The following is a list of internal and external modems that have been tested with the program.
Internal Modems Manufacturer Diamond Diamond Lucent US Robotics US Robotics Zoom Model - Internal Supra 336i SP ASVD Supra 56i SP 56K LU PCI 56k Fax PCI #3CP5610A Sportster WinModem - #0467 Fax 28.8 v.341 #275 --- Windows Operating System -95 ? ? ? ? ? ? 98 C C C C X C ME ? ? ? ? ? ? NT ? ? C C ? ? 2000 ? ? ? ? ? ? XP ? ? ? ? ? ?

Note: Internal modes were tested only for calling capabilities. External Modems Manufacturer Boca Hayes Hayes MultiTech Model - External 14.4 V.32b #MV.34xx Accura 56k #03328-A Accura 144+Fax 144 #5300AM MultiModem 19.2k Data/Fax --- Windows Operating System --95 X ? X ? ? ? CA ? ? ? 98 X C X X C< CA CA ? ? CA ME X C X ? ? ? CA ? ? C NT X C C A ? CA CA CA ? CA 2000 X C X A X CA CA ? ? C XP X ? X ? ? ? ? ? ? ?

Practical Peripherals PM288MT II v.34 - 28K US Robotics US Robotics US Robotics US Robotics Zoom 56k Fax v.90 #USR5686D Sportster56k Fax #USR5686-03 Sportster 33.6 - #0413 Sportster 14.4 Fax CJE-0235 Fax 56kx Dualmode #2949L

C = Call - means that the FileTransfer program can get the modem to call another modem and establish communications. A = Answer - means that the FileTransfer program can get the modem to answer inbound calls and establish communications with the master controller. X = Not supported. < = Less 100% reliable.

170

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

Setting Program Preferences


Overview
Select Settings > Preferences to open the Preferences dialog, where you can set various application-level preferences.

Preferences Dialog - General Tab


Use the options on the General tab of the Preferences dialog to set general program defaults. The options on this tab include: Window Color Display Options - This area of the dialog allows you to change the foreground/background colors for the following windows of the application:
Output Bar Output Bar Output Bar Output Bar Output Bar Output Bar Workspace Project Tree Online Tree Foreground Color Background Color Status (Status tab of the Output Display window) Find in Files (Find in Files tab of the Output Display window) Find IR Files (Find IR Files tab of the Output Display window) File Transfer Status (File Transfer Status tab of the Output Display window) Notifications (Notifications tab of the Output Display window) Diagnostics (Diagnostics tab of the Output Display window) (Workspace tab of the Workspace window) (Online Tree tab of the Workspace window) This is the text color setting for the selected window. This is the background color setting for the selected window.

Software History Application This option allows you to specify wether to automatically close the AMX Software History Application when you exit NetLinx Studio, or to leave it running (default = Close when NetLinx Studio Exits). Recent File List Size This field allows you to change the size of the recent file list, displayed at the bottom of the File menu (range = 1-9),

Preferences Dialog - Axcess Compiler Tab


Use the options in the Axcess Compiler Options tab of the Preferences dialog to set default preferences for the Axcess compiler. The items on this tab include: Warnings - Click these checkboxes to specify which warnings to display in the Build tab of the Output Window, after compile operations. The warnings are described below: Integer on non-arrays - This warning appears when the keyword INTEGER is applied to a non-array type of variable. Doing this is not an error, because non-array variables are already integers, but it is redundant. Assignment of unlike types - This warning occurs when a variable or value of one type is assigned to a variable of a different type. Here are some examples:
Assigning a string literal, string expression, or array to a non-array variable. Assigning a non-array variable to an entire array. Assigning an integer array to a non-integer array.

NetLinx Studio (v2.4 or higher)

171

Setting Program Preferences

Assigning a two-dimensional array to a one-dimensional array, or vice versa. Assigning the result of a function that returns an array type to a non-array variable or to a two-dimensional array variable (for example, X = ITOA(12), where X is a nonarray variable or two-dimensional array variable). Assigning the result of a function that returns a non-array type to a one- or twodimensional array variable (for example, X = ATOI('AMX'), where X is a one- or twodimensional array variable).

This message is a warning and not an error, because X = ITOA(12) works correctly when X is a simple variable, since the result is a single value between and 65,535. Variable not used - This warning occurs at the end of compilation for each variable that was declared but never used. Define_Call not used - This warning occurs at the end of program compilation for each DEFINE_CALL subroutine that was declared but never used. Too many nested levels - This warning appears if there is a large amount of nesting in the program. This can happen with a long chain of IF...ELSE IF statements. The solution is to use the SELECT...ACTIVE set of statements. Long_While in While - This warning occurs if the compiler finds a LONG_WHILE or MEDIUM_WHILE inside a block of code following a WHILE keyword. This warning exists because the WHILE command has a 1/2 second timeout period, and the LONG_WHILE and MEDIUM_WHILE keywords do not. This could create a hard-to-find logic error. The solution is to change the WHILE to a LONG_WHILE to fix this problem. Separate Define Call list - Check to store all DEFINE_CALL subroutines in a separate section of the Master Controller memory than the DEFINE_PROGRAM section. This effectively allows the code size of a program to reach 128K (64K for the DEFINE_CALLS and 64K for the DEFINE_PROGRAM section). Source Options - Click these checkboxes to enable the following build (compile) options: Build with Source - Check to compile the source code with the executable code so that you may later retrieve the source code from the device you send the compiled code to. If Build with Source is disabled, only the executable code is sent when the file is transferred to the master. Build With Password Protection - Select this option to apply a password to the Source file. Once applied, you cannot retrieve the source code from the Master Controller unless you provide the correct password. Select the Change button to edit the password (via the Change Password dialog). A password must be at least 6 characters in length (maximum of 20 characters).
When building with source, only the files needed for the compilation process are compressed. Though the APW may contain many files, if the source file only uses one axi file, then only 2 files will be compressed.

Directories - Click to open the directories menu, where you select the directories to point the compiler to, by file type. Once a directory type is selected, the directory list is

172

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

populated with the directories of that type that have been mapped. There are a maximum of 100 directories that can be entered for each type. Select Include Files to select or create the directory that the compiler will look for Include files in. Select Library Files to select or create the directory that the compiler will look for (IR) Library files in.

Preferences Dialog - Netlinx Compiler Tab


Use the options in the NetLinx Compiler tab of the Preferences dialog to set default preferences for the NetLinx compiler. The items on this tab include: Directories - Click to open the directories menu, where you select the directories to point the compiler to, by file type. Once a directory type is selected, the directory list is populated with the directories of that type that have been mapped. There are a maximum of 100 directories that can be entered for each type. Select Include Files to select or create the directory that the compiler will look for Include files in. Select Library Files to select or create the directory that the compiler will look for System Call files in. Note that the compiler processes the Library directories listed here in reverse order (that is, from the bottom up). Select Module Files to select or create the directory that the compiler will look for Duet Module files (*.JAR) and AXS Module files (*.TKO). Compile With Debug Info - Select this option to include variable symbol information in the compiled file. This allows the debugger to identify and validate variable symbols in the code. You must compile with debug info in order to debug NetLinx files. Build With Source - Check to include the executable code and the source code to the Master Controller or data device when the file is sent (memory permitting). This allows the Receive option to retrieve the source code from the Master Controller. If Build with Source is disabled, only the executable code is sent, which cannot be retrieved from the Master Controller.
When building with source, only the files needed for the compilation process are compressed. Though the APW may contain many files, if the source file only uses one AXI file, then only 2 files will be compressed.

Build With Password Protection - Select this option to apply a password to the Source file. Once applied, you cannot retrieve the source code from the Master Controller unless you provide the correct password. Select the Change button to edit the password (via the Change Password dialog). A password must be at least 6 characters in length (maximum of 20 characters).

NetLinx Studio (v2.4 or higher)

173

Setting Program Preferences

Preferences Dialog - Editor Tab


Use the options on the Editor Options tab of the Preferences dialog to set default preferences for the Source Code Editor windows. The items in this tab include: Syntax Highlighting - These options allow you to customize syntax highlighting within the Source Code Editor windows. The term Syntax Highlighting refers to the fact that various terms in the code file (including Reserved Identifiers, Constants, Devices, Types and Variables) are automatically highlighted (displayed in a specific foreground and/or background) in the Source Code Editor windows. Document Type - Select the type of document that you want to set highlighting options for (Axcess/NetLinx Source code files or Text Files). Styles - This is a list of all the items that can be customized in the Source Code Editor Windows. The items that appear in this list depend on the Document Type selection:
Text Files Default Text Selected Text Caret Axcess/NetLinx Source (code files) Space Comment Reserved Word

Window Background String Margin Operator Number Float (Floating Point Number) Device Constant Variable Type Default Text Selected Text Caret Function Names Stack/Param Variables Code-Fold Margin Code-Fold Plus Code-Fold Minus Window Background Margin

Select an item from this list to customize.


Since NetLinx code may be divided into sections (DEFINE_CONSTANT, DEFINE_DEVICE, DEFINE_TYPE, and DEFINE_VARIABLE), anytime a word is encountered that falls within one of these sections it is parsed, remembered and then the syntax is highlighted according to the section in which it occurred. Therefore, if a DEFINE_DEVICE section contains a line that reads "dvTP = 128" the word dvTP will be remembered as a device and syntax highlighted. Additionally, if the editor recognizes that you have partially typed the name of the above section variable (for example "dv"), it will auto-suggest "dvTP". The program will do this all of the items it has encountered in any of the DEFINE sections.

174

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

Background Color - This is the background color setting for the selected Item. Click the down arrow to select a different color from a palette.
Click the More Colors button on the color palette to access the advanced color selection palette.

Apply to All - Use this option to apply the selected background color to all items in the Selections list. Text Color - This is the text color setting for the selected Item. Click the down arrow to select a different color from a palette.
Click the More Colors button on the color palette to access the advanced color selection palette.

Bold/Italic - Use these checkboxes to specify the text style setting for the selected Item. Font - The Selection button opens the Font dialog, where you can select the font, font style (regular, italic, bold) and font size to be displayed in the Source Code Editor window. Check Only Fixed Pitch Fonts to limit the font selection list to include only fixedpitch fonts (such as Courier or Terminal). Printer - These options let you control how to best print source files that use colorcoding: Print Black on White: Print all text as black on a white background. Print Color on White: Print all text using the same colors displayed in the Source Code Editor window, on a white background. Print Color on White but Invert Light Colors: This is the same as "Print Color on White", except that light colors are automatically be inverted for better readability on a white background. Display options - These options offer more display-oriented options for the Source Code Editor window: Show Line Numbers - This option displays line numbers along the left-hand edge of the Source Code Editor window (default = enabled). Enable AutoComplete/Suggest - With this option enabled, the application examines the first few characters in a variable name, device name or a reserved identifier, and automatically finishes typing it for you (default = enabled). In some cases, the program will suggest the rest of the word. With option enabled, the program will automatically finish typing many common terms for you, to save time and effort. Click here for more details.

NetLinx Studio (v2.4 or higher)

175

Setting Program Preferences

Enable Indentation Guides - This option causes the program to draw vertical lines indicating the tab stops in the Source Code Editor window (default = enabled). Note that indentation guides only appear if there are tabs present in the code. Enable Call Tips - This option enables the Call Tips function. Call Tips assist you with adding declared functions by displaying a list of parameters that are valid for the particular function you are adding. Enable Code Folding - This option allows you to "fold-up" each section of code in the Source Code Editor (default = enabled). With this option enabled, a grey bar is displayed in the Editor window, between the Line Numbers (if that option is enabled) and the actual code. Contained within this grey bar are red minus symbols (-) next to the first line of each section of code. Click on the minus symbol to "fold" (collapse) that section. When a section is folded, the minus symbol is replaced by a blue plus symbol (+). Click the plus symbol to expand the section for viewing/ editing. Use the Code-Fold Margin, Code-Fold Plus and Code-Fold Minus options in the Syntax Highlighting section to customize the color settings for code-folding (select Axcess/NetLinx Source as the Document Type).
Additionally, you can expand or collapse all fold levels in the active file via the Expand All Folded Levels and Collapse All Folded Levels commands in the Edit menu.

Enable UTF-8 format to display Hebrew, Arabic, Cyrillic and Han characters - This option allows these special character sets to be displayed in the Source Code Editor windows. You must close and re-open all files in order for this option to take effect. Tabs and Indentation Preferences - This set of options allows you to specify the following indentation preferences: Set tab stops every X characters - Use this option to specify the size (in number of characters) of the tab stops in the Source Code Editor window (default = 4). Each line contains a number of tab stops placed at regular intervals (for example, every 8 characters). When you press the tab key, the cursor or insertion point jumps to the next tab stop. Changing this value changes the interval of the tab stops. Indent with X characters - This value sets the number of space characters to be inserted by auto-indentation (default = 10). Enable Auto-Indentation - This option causes the program to automatically indent lines that occur after an indented line. When indenting, text is prepended the amount of spacing specified in the Indent with X Characters field (see above). Clipboard Text Buffer - These options allow you to define the number of clipboard buffer entries and the maximum width to display (via the Clipboard Buffers option in the Edit menu): Max Items - You can have a maximum of 30 clip-board buffer items (default = 20). Max Display Width - You can set the maximum display width to up to 80 characters (default = 50). Clear Text Buffer History - Clears all the clipboard text items from the list.

176

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

Importing/Exporting Editor Preferences Use the Import Editor Preferences and Export Editor Preferences options in the Tools menu to import/export the current Source Code Editor preferences, as they are defined in the Editor tab of the Preferences dialog: To export the current Editor Preferences, as a *.EPX file: 1. Select Tools > Export Editor Preferences. 2. In the Save As dialog, specify a name and target directory for the resulting *.EPX file, and click OK. To import an existing *.EPX file: 1. Select Tools > Import Editor Preferences. 2. The program will prompt you to acknowledge that the imported settings will overwrite your current Editor preferences - click OK to proceed. 3. In the Open dialog, locate and select the desired *.EPX file, and click Open. The Editor tab of the Preferences dialog should now reflect the preferences specified in the imported *.EPX file.

Preferences Dialog - Commands Tab


Use the options on the Commands tab of the Preferences dialog to add/remove commands from the toolbars. The items on this tab include: Categories - This is a list of command categories. Each command category in this list contains several commands (displayed in the Commands list). Commands - This is a list of the commands included in the selected Command Category. Description - This (read-only) field displays a brief description of the selected Command. Adding/Removing Commands From The Toolbars Use the options on the Commands tab of the Preferences dialog to add/remove commands from the toolbars. To add a command to an existing toolbar: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Commands tab, select the command category that the command you want to add belongs to (in the Category list). 3. In the Commands list, select the command you want to add. 4. Click and drag the command from the Commands list, and drop it into any open toolbar. To remove a command from an existing toolbar: 1. Select Settings > Preferences to open the Preferences dialog. 2. Select a toolbar button in any open toolbar. 3. Click and drag the button out of the toolbar.

NetLinx Studio (v2.4 or higher)

177

Setting Program Preferences

Creating Custom Toolbars Use the options on the Commands tab of the Preferences dialog to create custom toolbars: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Toolbars tab, click New. 3. Enter a name in the Toolbar Name dialog, and click OK. 4. The new toolbar appears in the Toolbars list, and the new (empty) toolbar appears within the Toolbars list area of this tab. 5. Click and drag the new toolbar into the work area. 6. Populate the toolbar with command buttons as desired.

Preferences Dialog - Toolbars Tab


Use the options on the Toolbars tab of the Preferences dialog to add/delete/rename and reset the toolbars. The items on this tab include: Toolbars - This list represents all toolbars currently loaded in the GUI, including any custom toolbars. The checkboxes next to each toolbar indicate which toolbars are currently enabled. Use these check boxes to specify which toolbars to show by default at startup. Reset - With one of the System (non-custom) toolbars selected in the Toolbars list, the Reset button resets the toolbar to its default set of command buttons. Reset All - Click to reset all System toolbars to their default set of command buttons. New - Click to create a new custom toolbar via the Toolbar Name dialog. Rename - Select a custom toolbar and click Rename to rename the selected toolbar via the Toolbar Name dialog. You cannot rename or delete system toolbars. Delete - Select a custom toolbar and click Delete to delete the selected toolbar. You cannot rename or delete system toolbars.

Preferences Dialog - Tools Tab


Use the options on the Tools tab of the Preferences dialog to add a shortcut to another application in the Tools menu. The items on this tab include: Menu Contents - This list represents all shortcuts to external applications currently loaded in the Tools menu. This list is empty until you add a shortcut. The text entered here is what will be displayed in the Tools menu. Command - Click the browse button (to the right of the Command text box) to locate and select the .EXE for the application that you want to add to the Tools menu. Arguments - This option allows you to apply Arguments (also known as "switches") to the command line of the selected program. Arguments allow you to customize the application in various ways. For example, if you specify Notepad.EXE in the Command field, you could enter the argument "C:\somefile.txt" in the Arguments field to cause the program to try to open a file on the root C: drive called "somefile.txt". Click the right-

178

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

arrow button (to the right of the Arguments text box) to access a list of arguments supported by the specified application.
To use arguments, you need to be familiar with the capabilities of the application you are adding. Consult the program's manufacturer for details on argument support.

Initial Directory - This option allows you to specify the initial directory for the specified application to open by default when the program is launched. Adding/Removing Application Shortcuts In The Tools Menu Use the options on the Tools tab of the Preferences dialog to add/remove shortcuts to external applications in the Tools menu: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Tools tab, click the New button to create an empty text field in the Menu Contents list. 3. Enter a name for the application. 4. Click the browse button ( ) to locate and select the application's .EXE file. The directory path is displayed in the Command text box. 5. Specify any Arguments, if necessary. Click the right-arrow button to select from a list of all applicable arguments. 6. Specify an Initial Directory, if necessary. Click the right-arrow button to select an initial directory option, or select Browse to specify an initial directory via the Browse For Folder dialog. 7. Click Close to close the Preferences dialog. 8. The new shortcut should appear at the bottom of the Tools menu.

Preferences Dialog - Keyboard Tab


Use the options on the Keyboard tab of the Preferences dialog to set custom keyboard accelerators (shortcut keys/key combinations) for often-used commands. The items on this tab include: Category - This drop-down list represents the various command categories. Select a Category to populate the Commands list. Commands - This list represents all of the commands contained within the selected command Category. Description - With a command selected (in the Commands list), this text box displays a brief (read-only) description of the selected command. Set Accelerator for - (this function is not used by NetLinx Studio). Current Keys - With a command selected (in the Commands list), this text box displays the current keyboard accelerator assignment (read-only). Press the New Shortcut Key - With a command selected (in the Commands list), this text box allows you to enter the new keyboard shortcut for that command.

NetLinx Studio (v2.4 or higher)

179

Setting Program Preferences

Assign - Click to assign the newly specified keyboard shortcut to the selected command. This button is only enabled if a command is selected, and new shortcut keys have been entered in the Press New Shortcut Key text box. Remove - With a command selected (in the Commands list), click Remove to remove the associated keyboard shortcut. Reset All - Click to reset all keyboard shortcuts to the defaults. Creating Custom Shortcut Keys Use the options on the Keyboard tab of the Preferences dialog to set custom keyboard accelerators (shortcut keys/key combinations) for often-used commands: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Keyboard tab, select the command Category that contains the command that you want to create a new shortcut key for. 3. In the Commands list, select the command that you want to create a shortcut key for. If a shortcut key is already associated with the selected command, it is indicated in the Current Keys text box. 4. Place the cursor in the Press New Shortcut Key text box, and enter the desired shortcut key or key combination. If the new shortcut key is already assigned to another command, it is indicated directly below the Press New Shortcut Key text box, and the Assign button will be disabled to prevent duplicate assignments. 5. Click Assign to assign the new shortcut key to the selected command.

Preferences Dialog - Menu Tab


Use the options on the Menu tab of the Preferences dialog to customize the menus and reset the menus to their original default state. To reset a menu, select a particular window view (i.e. AXS type views or TXT type views) from the combo box and then select the Reset button. The items on this tab include: Application Frame Menus - Click the down-arrow to access a list of all Application Frame Menus. These relate to file types that can be opened and edited in NetLinx Studio. Reset - Click to reset the selected application frame menu to its default state. Context Menus - Click the down-arrow to access the two context menu options: Source View and Text View. Source View sets the context menu to include commands associated with creating/ editing source code files. Text View sets the context menu to list only commands that relate to creating / editing text documents. Reset - Click to reset the selected context menu to its default state.

180

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

Source View FIG. 30 Context menu options

Text View

Customizing The Menus Use the options on the Commands tab of the Preferences dialog to customize menus, and reset the menus to their original default state. To customize a menu: 1. Select Settings > Preferences to open the Preferences dialog. 2. Open the Commands tab. 3. Open a menu (in the main Menu bar). To add a command: Select a command category and a select the command you want to add to the menu. Click and drag the command out of the Commands list and into the desired position in the open menu. To remove a command: Select a command from the open menu, and click and drag it outside of the menu. 4. Click Close to close the Preferences dialog.

NetLinx Studio (v2.4 or higher)

181

Setting Program Preferences

Preferences Dialog - Diagnostics Tab


Use the options on the Diagnostics tab of the Preferences dialog to set default diagnostics preferences. The items in this dialog include: Notification View - Use this set of options to set default display preferences for the Notification tab of the Output Display Window. Display Line Numbers - Toggles the display of line numbers in asynchronous notification displays (default = enabled). Display Time Stamp - Toggles the display of time stamps in asynchronous notification displays in one-second increments (default = enabled). When enabled, the Display Milliseconds option causes asynchronous notification time stamps to be displayed in milliseconds (default = disabled). Display Control Codes as - Converts unprintable characters (i.e. Control Codes) into either Hexadecimal or Decimal values within the message (default = Hex Values).
Hex values will display with a leading $ character. For example the message: STRING from CHANNEL 6 - $0F$1D has two control codes converted to hexadecimal. Decimal values will display with a leading # character: STRING from CHANNEL 6 - #15#29.

Diagnostics View - Use this set of options to set default display preferences for the Diagnostics tab of the Output Display Window. Display Line Numbers - Toggles the display of line numbers in system diagnostics displays (default = enabled). Display Time Stamp - Toggles the display of time stamps in system diagnostics displays in one-second increments (default = enabled). When enabled, the Display Milliseconds option causes diagnostics time stamps to be displayed in milliseconds (default = disabled). Display Control Codes as - Converts unprintable characters (i.e. Control Codes) into either Hexadecimal or Decimal values within the message (default = Hex Values).
The Line Number, Time Stamp and Control Code display options will only take affect after you stop and then start the asynchronous notifications/diagnostics message feeds.

Buffer File Options - Use the text box to specify the total size of the two files that are used by the program to buffer the asynchronous notification and system diagnostic messages. The number specified here will be divided evenly between the two files. The range is 2 - 500 MB (default = 10). If you have less than 500 MB free on your disk, then the upper range value will be adjusted according to the amount of free space on your

182

NetLinx Studio (v2.4 or higher)

Setting Program Preferences

disk. Your TEMP or TMP environment variables are used to determined the drive used for the two buffer files. Available Disc Space on drive c - this read-only field indicates the current amount of free disc space available on your local hard disc (c:). Use this number as reference if you are increasing the buffer file size.

Preferences Dialog - Terminal Tab


Use the options on the Terminal Options tab of the Preferences dialog to set default Terminal window preferences. The items in this dialog include: Add line feed character - This option controls whether line-feed characters are added to incoming carriage returns if they do not already have them (default = disabled). This is so that text copied from the terminal displays correctly in windows text editors. Many editors do not recognize text that just has carriage returns at the end as lines and will instead display a continuos string. Send Ctrl characters to port - This option toggles the transmission of control characters to the terminal's port (default = disabled). Colors - These options allow to customize the colors for both states (Active (Connected) and Inactive (Disconnected)) of the terminal window. To change the colors on the terminal window, select Active (Connected), then click the down arrows to access the Foreground (text) and Background color palettes. Select the desired colors, and repeat for the Inactive (Disconnected) state.

Preferences Dialog - File Transfer Tab


Use the options on the File Transfer tab of the Preferences dialog to set default preferences for file transfer operations. The options on this tab include: Automatically select reboot when sending a TKN file (default = enabled). When sending a TKN, automatically send the associate SRC (default = enabled). Automatically choose "Smart Transfer" when sending a TP4 file (default = disabled). By default, select "Send Bitmaps" when sending a TPD file (default = enabled). By default, select "Send Icons" when sending a TPD file (default = enabled). By default, select "Send Fonts" when sending a TPD file (default = enabled). Assume I am connected directly to a touch-panel (no master) whenever transferring TPD files (default = disabled).

NetLinx Studio (v2.4 or higher)

183

Setting Program Preferences

Preferences Dialog - Workspace Tab


Use the options on the Workspace tab of the Preferences dialog to set various display and file preferences relating to the Workspace Window. The items on this tab include: Restore Workspace On Startup - This option (on by default) automatically restores the workspace file upon startup of the application. With this option enabled, all files that were opened and the dockable windows that were displayed when you closed the application will be restored when you restart the program. Display System Configuration Setting in the Identifier - This option (off by default) displays the System Configuration settings as part of the System identifier (as displayed in the Workspace tab of the Workspace Window). Enable Auto Save - Toggles the timed auto-saving of text files and the duration of time between auto saves. Auto Save Every <x> Minutes - This field is only enabled when the Enable Auto Save option is selected. The range is 1-120 minutes, the default setting is 5. Automatically Save File Before Compile - Toggles auto-saving of code files before a compile. Automatically Stamp File with Creation and Last Modified Date -This option automatically stamps all Workspace files with Creation and Last Modified dates when the file is closed (default = enabled). Enable Window Tabs - This option toggles the display of the window tabs that appear by default along the lower edge of the Source Code Editor windows area of the GUI. These tabs provide easy access for each open Source Code Editor window. If this option is not selected, the following tab-oriented options are disabled. Enable File Icons In Tabs - This option toggles the file icons displayed in the Source Code Editor window tabs. Enable Window Close Button - This option toggles the Window Close button ( ). When Closing the Workspace - This section contains options for closing files associated with a Workspace that is being closed. The options are: Close Associated Files Without Prompting Always Prompt Before Closing Associated Files Do Not Prompt Or Close Associated Files When Removing a File From the Workspace - This section contains various options for closing files when they are removed from the current Workspace. The options are: Close File Without Prompting Always Prompt Before Closing Files Do Not Prompt Or Close File

184

NetLinx Studio (v2.4 or higher)

Troubleshooting

Troubleshooting
NetLinx Debugger Not Stopping On A Breakpoint
Symptoms A breakpoint is set on a line of code, but the code does not stop execution on this line. The line of code in question contains a SEND_COMMAND, SEND_STRING, or SEND_LEVEL. Cause The debugger will not stop on a line of code that sends a command, string, or level because of a device declared as an integer instead of a DEVICE:PORT:SYSTEM (D:P:S) structure. Example:
DEFINE_DEVICE VCR = 2 TP = 128 DEFINE_EVENT BUTTON_EVENT[TP,101] { PUSH: { SEND_COMMAND VCR," 'SP', 9" //The debugger will not stop if you put a breakpoint here } }

Resolution Declare devices using the full D:P:S structure. In fact, you should always do this in Netlinx. Example:
DEFINE_DEVICE VCR = 2:1:0 TP = 128:1:0 DEFINE_EVENT BUTTON_EVENT[TP,101] { PUSH: { SEND_COMMAND VCR," 'SP', 9" //The debugger will now stop if you put a breakpoint here } }

NetLinx Studio (v2.4 or higher)

185

Troubleshooting

NetLinx Master Error - Device_ID Error


When calling DEVICE_ID, this run time error can occur:
CIpLibrary::Device_ID - Error 1

This error is cause by passing a parameter that is not of type DEV to the DEVICE_ID keyword. This usually occurs when converting AXCESS code to Netlinx. To fix this error, try the following: Look for all references to the DEVICE_ID function Make sure the value passed to the function is of type DEV. If this appears inside a DEFINE_CALL or DEFINE_FUNCTION and a parameter is passed to the DEVICE_ID function, make sure that parameter is of type DEV.

Debug Option Disabled For Axcess Code File


Symptom After compiling and downloading an Axcess code file, the Start Debugging option (in the Debug menu) is disabled. Cause The code was created as an Axcess file, but was compiled as a NetLinx file. Resolution 1. Select the file in the Project Navigator window (Workspace tab), and right-click to open the Source Code File Context Menu. 2. Select File Properties to open the File Properties dialog. 3. Change the Compile As selection to Axcess. 4. Click OK to save the change and close the File Properties dialog. 5. Recompile the file (as Axcess) and download.

186

NetLinx Studio (v2.4 or higher)

Index

NetLinx Studio (v2.4 or higher)

187

033-004-2713 11/05 2005 AMX Corporation. All rights reserved. AMX, the AMX logo, the building icon, the home icon, and the light bulb icon are all trademarks of AMX Corporation. *In Canada doing business as Panja Inc.

AMX reserves the right to alter specifications without notice at any time.
ARGENTINA AUSTRALIA BELGIUM BRAZIL CANADA CHINA ENGLAND FRANCE GERMANY GREECE HONG KONG INDIA INDONESIA ITALY JAPAN LEBANON MALAYSIA MEXICO NETHERLANDS NEW ZEALAND PHILIPPINES PORTUGAL RUSSIA SINGAPORE SPAIN SWITZERLAND THAILAND TURKEY USA

ATLANTA BOSTON CHICAGO CLEVELAND DALLAS DENVER INDIANAPOLIS LOS ANGELES MINNEAPOLIS PHILADELPHIA PHOENIX PORTLAND SPOKANE TAMPA

3000 RESEARCH DRIVE, RICHARDSON, TX 75082 USA 800.222.0193 469.624.8000 469-624-7153 fax 800.932.6993 technical support www.amx.com

Last Revision: 11/11/05