Working with Module Files

Module files provide pre-fabricated NetLinx code to control a specific device on the bus. Module files are stored in the Module folder in the Workspace tab (FIG. 105):

FIG. 105 Module folder indicating three Module files (.JAR, .XDD, and *.TKO)

    • 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 supports several types of Module files:

*.axs - NetLinx Module files

*.jar - Duet Module Files

*.xdd - Driver Design files

*.tko - Complied NetLinx Module files

Duet (JAR) Module Files

NetLinx Studio 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. JAR module files are also stored in the Module folder (in the Workspace tab of the Workspace Bar), and the same basic rules apply to JAR module files that are 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 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 is a DynaZip file containing the compiled TKN file as well as the JAR modules that need to be transferred to the NetLinx master for the TKN file to execute properly.

NOTE: Refer to the Cafe Duet online help f ile for details on creating JAR module f iles.

Adding a New Module File to a System

  1. Right-click on the Module folder to access the Module File Folder context menu, and select Add New Module File (FIG. 106).

FIG. 106 Add New Module File

  1. This opens the File Template dialog. This dialog prompts you to either use a template to create the new file or to create an empty AXS file not based on a template (FIG. 107)

FIG. 107 File Template dialog

    • Alternatively, you can also either select File > New or click the New toolbar button and select Module File in the New dialog.
    • Note that the new file will be added to the selected System, even if it is not the currently active system.
    • If you select Yes, click Next to proceed to the next File Template dialog (see Step 3).
    • If you select No, click Next to proceed to the New File Location dialog (see Step 4).

  • In this dialog, select a template to use to create the file (NetLinx Module Template or User-Defined Template), and click Next to proceed (FIG. 108).

FIG. 108 File Template dialog

    • If you select NetLinx Module Template, the new Module 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 Module file for the indicated system type.
    • If you select User Defined Template, enter the file path for the AXS, AXI, AXB (or other) file to be used as the file template. Use the Browse (...) button to locate and select the file via the Open dialog.

  • In this File Template dialog, enter a file name for the new file (FIG. 109).

FIG. 109 File Template dialog

  1. In the New File Location dialog, specify a target directory for the file.
    • By default, the target directory is the NetLinx Studio directory.
    • Use the Browse (...) button to navigate to another folder if necessary. (FIG. 110).

FIG. 110 New File Location dialog

  1. Click Next to proceed to the final File Template dialog which notifies you that the file was created (FIG. 111).

FIG. 111 File Template dialog

  1. Click Finish to close the File Template dialog.

The new Module file is opened in an Editor window for editing. Also, the new file should now appear in the Module folder, under the selected System (FIG. 112).

FIG. 112 Workspace tab - Module File Added

Adding an Existing Module File to a System

  1. Click to select (highlight) a System in the Workspace tab of the Workspace Bar.
  2. Right-click on the Module folder to access the Module Folder context menu, and select Add Existing Module File (FIG. 113).

FIG. 113 Source Folder Context Menu

  1. In the Add Existing Module File dialog, locate and select the Module file that you want to add to the selected System. (FIG. 114).

FIG. 114 Add Existing Module File dialog

  1. With one or more Module files selected, click Open to access the File Properties dialog where you can view/edit general file information for the selected file(s) (FIG. 115).

FIG. 115 File Properties dialog (Module File)

NOTE: If you select multiple f iles to add to the System, the program will prompt you to edit the f ile properties for each f ile before adding them.

  1. Edit the file information (if necessary) for each file being added to the System.
  2. Click OK to add the file to the selected System.

Note that the file now appears in the Module folder under the selected System. Double-click to open the file in an Editor window (FIG. 116).

FIG. 116 Module Folder - New JAR file

Creating a New AXS Module File (Outside of a System)

To create a new *.axs Module file (that is not associated with a System).

  1. Click File > New, and select Module File in the New dialog (FIG. 117).

FIG. 117 New dialog - Module File selected

  1. Click OK to close this dialog and open the File Template dialog (FIG. 118).

FIG. 118 File Template dialog

  1. Select Yes (default) or No, and click Next to proceed.
    • If you select Yes, click Next to proceed to the next File Template dialog (see Step 4).
    • If you select No, click Next to proceed to the New File Location dialog (see Step 6).
  2. In this dialog, select a module template to use to create the file (NetLinx Module Template or User-Def ined Template), and click

Next to proceed. (FIG. 119).

FIG. 119 File Template dialog

    • If you select to use the NetLinx Module template, the new Module 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 NetLinx Module file.
    • If you select User Defined Template, enter the file path for the AXS, AXI, AXB (or other) file to be used as the file template. Use the Browse (...) button to locate and select the file via the Open dialog.

  • In this File Template dialog, enter a file name for the new Module file, and click Next to proceed (FIG. 120).

FIG. 120 File Template dialog

  1. In the New File Location dialog, specify a target directory for the file.
    • By default, the target directory is the NetLinx Studio directory.
    • Use the Browse (...) button to navigate to another folder if necessary. (FIG. 121).

FIG. 121 New File Location dialog

  1. Click Next to proceed to the final File Template dialog which notifies you that the file was created (FIG. 122).

FIG. 122 File Template dialog

  1. Click Finish to close the File Template dialog. The new file is opened in an Editor window.

Including a NetLinx Module in Your Program

To include a module in your NetLinx program, use the following module line:

DEFINE_MODULE 'DMS-IMSMod' Module_Name(Virtual_Dev, Real_Dev, strFileName, strVarTextArray)

Where:

Module_Name DMS-IMSMod.tko

Virtual_Dev A virtual device you define.

Real_Dev The device number of the DMS or IMS panel.

StrFileName A string variable (CHAR array) containing the file name of the file to run.

StrVarTextArray A 2-dimensional array for storing store variable text. The first dimension 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).

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 The name of the compiled TKO file. MdlDMS The module name.

DvDMS The module ID device number (ex 32768).

DvDMS_R The device number of the keypad.

StrFILE_NAME Exact name of the file.

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

Loading a Device Driver (XDD) in NetLinx Code

NetLinx Studio supports Device Driver (*.XDD) files. An XDD File represents a compiled and exported Driver Design Project. The DeviceDriverEngine module specifies the Device Driver(s) that will be loaded in the NetLinx code.

The method of loading your Device Driver(s) in NetLinx code depends on whether the NetLinx code utilizes static device binding or dynamic device binding.

The basic difference between the two device binding methods is that static device binding requires that the .XDD file is specifically named in the DEFINE_VARIABLE and DEFINE_START portions of the NetLinx code. Conversely, dynamic device binding does not reference the Device Driver by filename in the NetLinx code. Instead, use the Master's WebConsole to bind the Device Driver.

Either way, the steps described in the topics listed below require that your Device Driver (*.XDD) has been successfully exported to a local directory that you can access (in order to transfer the Device Driver to the Master). The Device Driver will reside in the directory specified when the file was exported.

NOTE: In the event that the XDD f ile does not transfer to the Master, refer to

page 68

for details.

Loading a Device Driver (XDD) in NetLinx Code - Static Device Binding

These instructions assume that your NetLinx code utilizes static device binding. Use NetLinx Studio to modify, compile and transfer NetLinx code to the NetLinx Master.

  1. Transfer the Device Driver (*.XDD) file to the NetLinx Master ("drivers/" directory), via FTP:
    1. In Windows Explorer, locate and select the Device Driver (*.XDD) file that you want to transfer.
    2. Select Edit > Copy.
    3. In the address bar, enter "FTP://<IP Address of the Master>" and press Enter.
    4. The Master will require you to login - enter a valid Username (default = administrator) and Password (default = password).
    5. Paste the Device Driver file into the "drivers/" directory.
  2. In NetLinx Studio, modify the DEFINE_VARIABLE and DEFINE_START sections of the main NetLinx code:
    1. Under DEFINE_VARIABLE, enter the name of the Device Driver file (.XDD) using the CHAR[] parameter to specify the name of the Device Driver (.XDD) file. The syntax is shown below:

DEFINE_VARIABLE

CHAR <variableName>[] = 'name of the Device Driver xdd file'

    1. Under DEFINESTART, use DEFINE_MODULE to load the '_DeviceDriverEngine' module. The parameters for the DeviceDriverEngine module will define the device and the device driver to use. The syntax is shown below:

DEFINE_START

DEFINE_MODULE 'DeviceDriverEngine' InstanceName(<parameter list>)

Where:

  • InstanceName: the name to assign to the instance of the module.
  • <parameter list>: the list of parameters that is available to the DeviceDriverEngine module. For statically bound devices, the parameters include device information for the device that will use this Device Driver (vdvDevice, dvDevice), as well as the name of the Device Driver file to be used.

The example below shows a Device Driver named "Hitachi_Video_Projector_CPWX3014WN_1.0.0.xdd" loaded:

PROGRAM_NAME='DeviceDriverTest'

DEFINE_DEVICE

dvSerial1 = 5001:1:0

dvSerial2 = 5001:2:0

vdvDevice1 = 41001:1:0

vdvDevice2 = 41002:1:0 DEFINE_VARIABLE

CHAR myDriver1[] = 'Hitachi_Video_Projector_CPWX3014WN_1.0.0.xdd' CHAR myDriver2[] = ''

DEFINE_START

// This is an example of loading a static device driver. If using NetLinx

// Studio version 3.3.525 (or earlier), the device driver file has to be

// manually transferred to the NetLinx system.

DEFINE_MODULE 'DeviceDriverEngine' staticDev(vdvDevice1, dvSerial1, myDriver1) DEFINE_PROGRAM

  1. Save and compile the NetLinx code.
  2. Transfer the updated code to the NetLinx Master.
  3. Open the Master's built-in WebConsole to the System page - Manage Devices tab (FIG. 123):

FIG. 123 Master's WebConsole - System Page/Manage Devices

Under Device Configuration Pages, the Device Driver file that was uploaded to the Master's "drivers" directory (via FTP - see above) is indicated. This entry includes relevant information for the statically bound device

(manufacturer and model number | virtual device address | real device address | bound XDD file).

  1. Click on the Device Driver entry to open the Device Personality page of the Master's WebConsole. The information under

Current Personality reflects the properties of the bound Device Driver (FIG. 124):

FIG. 124 Master's WebConsole - Device Personality page

Loading a Device Driver (XDD) in NetLinx Code - Dynamic Device Binding

These instructions assume that your NetLinx code utilizes dynamic device binding. By using Dynamic device binding, the Device Driver (XDD) is not referenced by filename in the NetLinx code. Instead, use the Master's WebConsole to bind the Device Driver. Use NetLinx Studio to modify, compile and transfer NetLinx code to the NetLinx Master.

  1. In NetLinx Studio, modify the DEFINE_VARIABLE and DEFINE_START sections of the main NetLinx code:
    1. Under DEFINE_VARIABLE, enter an empty CHAR[] parameter:

DEFINE_VARIABLE

CHAR <variableName>[] = ''

    1. Under DEFINE_START, use DEFINE_MODULE to load the 'DeviceDriverEngine' module. The parameters for the DeviceDriverEngine module will define the device and the device driver to use. The syntax is shown below:

DEFINE_START

DEFINE_MODULE 'DeviceDriverEngine' InstanceName(<parameter list>)

Where:

  • InstanceName: the name to assign to the instance of the module.
  • <parameter list>: the list of parameters that is available to the DeviceDriverEngine module. For dynamically bound devices, the parameters include device information for the device that will use this Device Driver (vdvDevice, dvDevice), as well as the name of the Device Driver file to be used.

Example:

PROGRAM_NAME='DeviceDriverTest'

DEFINE_DEVICE

dvSerial1 = 5001:1:0

dvSerial2 = 5001:2:0

vdvDevice1 = 41001:1:0

vdvDevice2 = 41002:1:0 DEFINE_VARIABLE

CHAR myDriver1[] = 'Hitachi_Video_Projector_CPWX3014WN_1.0.0.xdd' CHAR myDriver2[] = ''

DEFINE_START

// This is an example of loading a dynamic device driver. Use the NetLinx

// master's web pages to transfer and bind the device driver to the

// DeviceDriverEngine module.

DEFINE_MODULE 'DeviceDriverEngine' dynamicDev(vdvDevice2, dvSerial2, myDriver2) DEFINE_PROGRAM

  1. Save and compile the NetLinx code.
  2. Transfer the updated code to the NetLinx Master.
  3. Open the Master's built-in WebConsole to the System page - Manage Devices tab (FIG. 125):

FIG. 125 Master's WebConsole - System Page/Manage Devices

Under Device Configuration Pages, see the entry named "Unknown". For dynamically bound devices, the entry under Device Configuration Pages does not indicate any information for a bound device (because initially there is no device bound).

However, the entry does indicate the virtual device address and real device address that were defined in the NetLinx code.

  1. Click on the Device Driver entry that is to be dynamically bound. This opens the Device Personality page of the Master's WebConsole (FIG. 126):

FIG. 126 Master's WebConsole - Device Details

Note that on this page:

  • Because no file is yet bound, Personality File is blank, and the Manufacturer and Model fields indicate "Unknown".
  • Because a file is not yet bound, the Communications information indicates "serial,ip", because both options are available to the user.

  • The Manage Personality Binding section contains a listing of all personality files (including Device Driver *xdd files) that are currently stored in the "drivers/" directory of the NetLinx Master. Any of these files can be selected to be bound to the device.

  • Under Select a personality f ile to bind to, specify the Device Driver (*.xdd) file that you want to upload to the NetLinx Master (in the /user/drivers/ directory):

  • If the desired .xdd file is present in the file list, select it and press *Bind.

  • If the desired .xdd file is not in the list, upload the file to the Master, and then select it from the list and click *Bind.

  • After the selected file is bound, the Device Details page is refreshed to display the information for the bound file, in the Current Personality section (FIG. 127):

FIG. 127 Master's WebConsole - Device Details

If the XDD Does Not Transfer When Updating NetLinx Code

In some cases, the XDD may not transfer when updating the NetLinx code. To verify that the XDD has successfully been transfered to the NetLinx Master:

  1. Load Windows Explorer.
  2. In the address bar, enter "FTP://&lt;IP Address of the Master>"
  3. The Master will require you to login - enter a valid Username (default = administrator) and Password (default = password).
  4. Look to see if the XDD is available.

If the XDD is not present, then manually paste the file into the "drivers/" directory. NOTE: A reboot of the master is required after the XDD f ile is placed in the drivers directory.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 Bar), and select Compile from the Module File context menu.
    • Double-click to open the Module file in an Editor window and select Compile <f ilename.axs> from the Build menu.
    • To specify the compiler to use, open the Module file in an Editor window, and select Compile as NetLinx from the Build menu.

FIG. 128 Compile command - Module Context Menu and Build Menu

The status and results of the build are displayed in the Status tab of the Output Bar.

results matching ""

    No results matching ""