i.LON® SmartServer 2.
Echelon, i.LON, LON, LONWORKS, LonTalk, Neuron, LONMARK, 3120, 3150, LNS, LonMaker, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonPoint and LonSupport are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Table of Contents Preface .................................................................................................. viii Welcome......................................................................................................... ix Purpose .......................................................................................................... ix Audience......................................................................................................... ix Models ........................
Using Include Directives ................................................................... 59 Example Model Files ........................................................................ 59 Saving your Model File ..................................................................... 62 Generating a Device Interface (XIF) File ................................................ 63 Using Long and Short Command Switch Forms .............................. 64 Other Command Switches.................................
Updating Device Interfaces ............................................................ 139 Deploying FPMs on Multiple SmartServers................................................. 142 Deploying Licensed FPM Applications ........................................................ 143 7 Creating FPM Application Licenses ............................................ 145 Licensing Overview ..................................................................................... 146 Creating an FPM Licensing Tool....
Internal FPM Data Point Methods......................................................... 209 Changed()....................................................................................... 209 NotifyOnAllUpdates()...................................................................... 210 Propagate()..................................................................................... 210 Write() ............................................................................................. 211 ResetPriority().
Appendix C FPM FAQ ....................................................................... 241 i.LON SmartServer 2.
Preface You can use i.LON SmartServer 2.0 Programming Tools to create custom embedded applications and drivers, which are referred to as freely programmable modules (FPMs), for your SmartServer. FPMs let you customize the embedded software of the SmartServer to meet your specific needs. Using i.LON SmartServer 2.0 Programming Tools, you can write FPMs in C or C++, compile them, and then upload them to your SmartServer.
Welcome The SmartServer includes i.LON SmartServer 2.0 Programming Tools for creating custom C/C++ applications and drivers (called freely programmable modules [FPMs]) that you can use to customize the functionally of the SmartServer. You can use your FPMs for a number of applications, including energy optimization, data analysis, lighting control, and room control. You can also use the i.LON SmartServer 2.
○ A sample license generator configuration file (an XML file named iLONLicenseGenValuesSample.xml) that demonstrates the structure of the i.LON License Generator user interface and provides sample pre-defined values. ○ A sample security DLL file (LicenseSecurityHMACMD5.dll) that takes the values entered in the i.LON License Generator user interface and creates an FPM license. See Chapter 7 for more information on creating FPM application licenses.
Web site at www.echelon.com/products/cis/activate. To run Echelon first-party FPMs or third-party FPMs on your SmartServer, your SmartServer must also have a separate FPM application license from Echelon or the third-party FPM vendor. Creating FPM Application Licenses You can create FPM application licenses for your FPMs to protect your FPMs from unauthorized use and piracy, and to make your FPMs available to customers for order. The i.LON SmartServer 2.
• Neuron C Programmer’s Guide. Describes how to write programs using the Neuron® C Version 2.1 language. • Neuron C Reference Guide. Provides reference information for writing programs using the Neuron C language. • LONMARK Resource Files, version 13.00. Documents the standard network variable types (SNVTs), standard configuration property types (SCPTs), and standard enumeration types that you can declare in your FPM applications and drivers. You can go to types.lonmark.org/index.
For More Information and Technical Support The i.LON SmartServer 2.0 Programming Tools ReadMe document provides descriptions of known problems, if any, and their workarounds. To view the i.LON SmartServer 2.0 Programming Tools ReadMe document, click Start, point to Programs, point to Echelon i.LON SmartServer 2.0 Programming Tools, and then select i.LON SmartServer 2.0 Programming Tools - ReadMe. You can also find additional information about the SmartServer at the i.LON Web page at www.echelon.com/ilon.
xiv Region China Languages Supported Chinese English Contact Information Echelon Greater China Rm. 1007-1008, IBM Tower Pacific Century Place 2A Gong Ti Bei Lu Chaoyang District Beijing 100027, China Phone: +86-10-6539-3750 Fax: +86-10-6539-3754 lonsupport@echelon.com.cn Other Regions English Japanese Phone: +1.408-938-5200 Fax: +1.408-328-3801 lonsupport@echelon.
1 Introduction This chapter provides an overview of freely programmable modules (FPMs) and explains the types of tasks FPMs can perform. It describes the types of custom embedded applications and drivers you can create with FPMs. It explains how to create and configure FPMs. It summarizes how to create FPM application licenses in order to protect your FPM applications and make them available to customers for order. It provides a quick-start exercise that you can use to create a simple FPM application. i.
Overview of Freely Programmable Modules Freely Programmable Modules (FPMs) are custom C/C++ applications and drivers that you can use to customize the functionality of the SmartServer. You can use FPM applications to supplement the built-in applications on the SmartServer and provide solutions for a number of applications, including energy optimization, data analysis, lighting control, and room control.
You can create up to 10 internal FPM devices on the SmartServer. Each internal FPM device may have multiple functional blocks, and the functional blocks may represent different instances of the same FPM application or they may represent instances of different FPM applications. For example, you can create an internal device that has two functional blocks that are both instances of the same FPM application for adding the values of two data points.
You can move your mouse pointer over an object in your FPM to open a tooltip that provides a description and the API of the selected object. Debugging FPMs The SmartServer uses a VxWorks® real-time operating system to run its embedded applications. If you need a source level debugger (VxWorks 6.2 - Wind River Workbench 2.4) or access to VxWorks system calls not encapsulated in the Echelon FPM API, contact Wind River® sales at www.windriver.com/company/contact/index.
iLonSystemWbdEnd image on your SmartServer to iLonSystem, reboot the SmartServer, create a debug configuration of your FPM in the i.LON SmartServer 2.0 Programming Tool and upload it to your SmartServer, and then connect the Workbench debugger to the iLonSystemWbd or iLonSystemWbdEnd image on your computer via the target server. For more information on how to do this, see Chapter 5, Creating FPMs.
just re-name the sample DLL file LicenseSecurity.dll; however, you are solely responsible for the creation of the security DLL file. You also need to modify your FPM application so that it can check whether a customer’s SmartServer has a valid FPM license file for running your FPM.
Note: An FPM programming license must be installed on your SmartServer for the FPM to run on your SmartServer. You can order a FPM programming license from the i.LON SmartServer 2.0 Web site at www.echelon.com/products/cis/activate 7. On your SmartServer, create Web connection between the data points declared in your FPM application and the data points on the SmartServer, and then use the View – Data Points Web page to test that the Web connections are updating the FPM data points.
e. In the channel (TT) field of the Program ID box, enter 04 if you have an FT-10 model of the SmartServer or enter 10 if you have a PL-20 model of the SmartServer. f. In the Resource File Set Name box, enter “FPM Development”, “FPM Examples”, or something comparable g. Click OK. 3. Expand the folder containing your company’s FPM resource file set, right-click the Functional Profile Template folder, and then click New FPT on the shortcut menu. 4.
fblock UFPTMath { in1 implements in1; in2 implements in2; out1 implements out1; } fbMathFunction external_name ("Math Function"); 3. Save your model file on your computer. This example stores a model file named “math.nc” in a folder named “ModelFile” that has been created under the C:\LonWorks directory. The file path of the source file in this example is therefore C:\LonWorks\ModelFile\math.nc. 4.
10 3. In the Server/IP-Address box in the LonMark Resource View, enter the hostname or IP address of your SmartServer and then click the Go button to the right. 4. Expand the SmartServer icon and then expand the LonMark folder. The resource files in the root/lonWorks/types folder on your SmartServer flash disk are shown. 5. Expand your company’s FPM resource file set, expand the Functional Profile Templates folder, right-click the .
7. If you will be deploying this example FPM on a SmartServer 2.0, click Finish to accept the default settings. If you will be deploying this example FPM on a SmartServer 1.0, click FPM Application, and then click Finish. Note: Avoid modifying the default project name. This ensures that the your FPM project has a unique namespace by following the FPM naming convention, which is .UFPT< FPT Name>. 8.
9. You can observe that the Data Point Variable Declarations section automatically includes DECLARE statements for each data point in the .UFPTMath template. For more information on creating FPM projects, see Chapter 5, Creating FPMs. Step 4: Writing the FPM Application You can write the FPM application using the i.LON SmartServer 2.0 Programming Tool. This mainly entails specifying the logic to be executed on the data points declared in the application.
void CUFPTMath::Work() { if (Changed(in1) || Changed(in2)) { out1 = in1 + in2; printf("%i + %i = %i \n", *in1, *in2, *out1); } } 3. Build the FPM application. To do this, click File and then click Save. The FPM executable module (.app extension) is updated. If the build is not performed, click Project and then click Build Project. You can then click Project and select Build Automatically so that your FPM applications are built automatically when you save them.
3. 14 The Install FPM Module dialog opens with the Deployment Settings window.
4. Enter the following information if different than the defaults: • The IP address or hostname of the SmartServer to which the FPM is to be uploaded. The default is the SmartServer IP address or hostname entered in the LonMark Resource View. • The user name and password used to access the SmartServer FTP server. The default user name and password are both “ilon”. • The directory on your SmartServer flash disk to which your FPM application is to be stored. The default directory is root/modules.
16 5. Expand the LonMark (XIF) folder, expand the root/lonworks/import/ folder, and then select the XIF for your Math FPM. 6. Click OK. A Math Device (Internal) device is added to the bottom of the LON channel tree. 7. Click Submit. You must wait for the SmartServer to instantiate the XIF file used for the internal Math device. The time it takes depends on the size of the XIF.
Step 6: Testing the FPM Application After you deploy an FPM application, you can test your FPM application using the View – Data Points Web page. To do this, you open the View – Data Points Web page, add the input and output data points in the FPM application, update one of the input data points, and observe that the output data point is updated accordingly. To test an FPM application on your SmartServer, follow these steps: 1. Click View and then click Data Points. The View – Data Points Web page opens.
in2 data points declared in the FPM device and that the out1 data point in the FPM device is updating the dynamic data point on the SmartServer. To connect the data points declared in your FPM to the data points on the SmartServer, follow these steps: 18 1. Create a dynamic SNVT_count data point on the VirtFB functional block under the i.LON App (Internal) device. To do this, follow these steps: 1. From the tree, expand the Net network, expand the LON channel, and then expand the i.
6. Click OK. A data point with the name you specified in step d is added underneath the VirtFB functional block. 7. Click Submit. 2. Create two copies of the dynamic SNVT_count data point that you created in step 1. a. Right-click the dynamic SNVT_count data point, and then click Duplicate Data Point on the shortcut menu. b. The Duplicate Data Point dialog opens. c. In the Number of Copies property, enter 2. i.LON SmartServer 2.
3. 4. 20 d. Click OK. Two copies of the data point named “Copy of ” are added underneath the VirtFB functional block. Note that the second data point copy will have an index appended to its name. e. Click Submit. Re-name the two data point copies you created in step 2. To do this, follow these steps: a. Right-click the first data point copy, and then click Rename on the shortcut menu. b. The Enter Name dialog opens. c.
5. The Configure – Web Binder Web page opens and the hostnames of the local SmartServer and any remote SmartServers added to the LAN, which are collectively referred to as Webbinder Destinations, appear in the application frame to the right. 6. From the Webbinder Destinations tree on the right frame, expand the i.
14. Enter values for both the VirtFB/count1 and VirtFB/count2 points. Observe the following: • The Math Function/in1 and Math Function/in2 data points in the FPM are updated to the same values as the dynamic data points on the SmartServer to which they are connected. The Web connections keep these sets of data points synchronized. • The Math Function/out1 FPM output data point is updated to reflect the sum of the in1 and in2 FPM input points.
2 Installing i.LON SmartServer 2.0 Programming Tools This chapter describes how to install, upgrade, and uninstall the i.LON SmartServer 2.0 Programming Tools. i.LON SmartServer 2.
Installation and Upgrading Overview The i.LON SmartServer 2.0 DVD includes a demo version of the i.LON SmartServer 2.0 Programming Tools, which you can use to write FPM applications and drivers. You cannot use the demo version, however, to compile and deploy the FPMs. To compile and deploy FPMs, you must use the full version of the i.LON SmartServer 2.0 Programming Tools. The full version of the i.LON SmartServer 2.0 Programming Tools is included on the i.LON SmartServer 2.
3. Click Install Products. The Install Products dialog opens. 4. Click Echelon i.LON SmartServer 2.0 Programming Tools. 5. If a previous version of the i.LON SmartServer 2.0 Programming Tools (Release 4.0, 4.01, 4.02, or the demo version of Release 4.03) is installed on your computer, the following dialog opens prompting you to confirm that you want to upgrade to the i.LON SmartServer 2.0 Programming Tools software. Click Yes to upgrade. i.LON SmartServer 2.
26 6. A dialog opens prompting to close all applications currently running on your computer. Close any applications running on your computer, and then click OK. 7. The Echelon i.LON SmartServer 2.0 Programming Tools software installer opens. 8. Read the information on the Welcome window and click Next. The License Agreement window appears. Installing i.LON SmartServer 2.
9. Read the license agreement (you can read a printed copy of this license agreement in Appendix E of the i.LON SmartServer 2.0 User’s Guide). If you agree with the terms, click Accept the Terms and then click Next. The Customer Information window appears. . 10. Enter your name and company name in the appropriate fields. The name and company may be entered automatically based on the user currently logged on and whether other Echelon products are installed on your computer. Click Next.
11. By default, the i.LON SmartServer 2.0 Programming Tools software will be installed in the C:\LonWorks\iLON\Development directory, or it will be installed in the C:\Program Files\LonWorks\iLON\Development directory if you have not previously installed any Echelon or LONMARK products. You can click Change to select a different destination folder. Click Next. The Setup Type window appears. 12. Select the type of installation to be performed. It is recommended that you select Complete. Click Next.
13. Click Install to begin the installation. After the i.LON SmartServer 2.0 Programming Tools have been installed, a window appears stating that the installation has been completed successfully. 14. Click Finish. The i.LON SmartServer 2.0 Programming Tools ReadMe file appears. When you finish reading the ReadMe file, close the window. Upgrading the i.LON SmartServer 2.0 Programming Tool You can upgrade your i.LON SmartServer 1.0 Programming Tools to the i.LON SmartServer 2.
1. Browse to the LonWorks\iLON\Development\eclipse\workspace.fpm folder on your computer. This folder contains your FPM projects and code. This folder is required if you later re-install the i.LON SmartServer 2.0 Programming Tool and need to import and modify your existing FPM projects or port code over to new FPM projects. See the next section, Importing FPM Projects, for more information on how to import existing FPM projects to an updated version of the i.LON SmartServer 2.0 Programming Tool. 2.
4. The Import Projects window opens. 5. Click Browse. The Browse for Folder dialog opens. Browse to the location of the backup copy of the FPM project to be imported and then click OK. i.LON SmartServer 2.
32 6. The selected FPM projects are listed in the Import Projects dialog. Select the Copy Projects into Workspace check box. 7. Click Finish. 8. If the Update Managed Build Project dialog opens, click Yes to convert the build settings to the version 4.0 format Installing i.LON SmartServer 2.
9. The selected FPM projects appear in the C/C++ Projects View. Converting FPM Projects to the Release 4.03 Configuration If you want to upgrade existing FPMs built with the i.LON SmartServer 1.0 Programming Tool (Release 4, Release 4.01, or Release 4.02 FPMs), you must first convert them to the Release 4.03 configuration. To do this, follow these steps: 1.
34 2. Click C/C++ Build. 3. Click Manage Configurations. The Manage Configurations dialog opens. Installing i.LON SmartServer 2.
4. Click New. The Create New Configurations dialog opens. 5. In the Name property, enter Release 4.03. If you are upgrading a debug configuration of an FPM, enter Debug 4.03. 6. In the Default Configuration property, select Release 4.03. If you are upgrading a debug configuration of an FPM, select Debug 4.03. i.LON SmartServer 2.
7. Click OK twice to return to the C/C++ Build window. 8. In the Configuration property, select Release 4.03. If you are upgrading a debug configuration of an FPM, select Debug 4.03. 9. If you are upgrading a release configuration of an FPM, Click OK to return to the C/C++ Projects view, and then skip to step 10. If you are upgrading a debug configuration of an FPM, configure its settings following these steps: a. 36 Expand C/C++ Build and then click Settings. Installing i.LON SmartServer 2.
b. Click Debugging in the Tool Settings tab. c. In the Level box, select Default (-g). i.LON SmartServer 2.
d. Click OK to return to the C/C++ Projects view. 10. Set the build target for your FPM to the Release 4.03 or Debug 4.03 configuration. To do this, right-click the FPM project in the C/C++ Projects view, point to Build Configurations, point to Set Active, and then click Release 4.03 or click Debug 4.03 if you are upgrading a debug configuration of an FPM. 38 Installing i.LON SmartServer 2.
11. You can upgrade your FPM application or driver, rebuild it, and then upload it to your SmartServer 2.0. Note: FPMs that have been upgraded to the Release 4.03 or Debug 4.03 configuration can only run on a SmartServer 2.0 (a SmartServer with the Release 4.03 image). You cannot run an upgraded FPM on a SmartServer 1.0 (a SmartServer with a Release 4.0, 4.01, or 4.02 image). Uninstalling i.LON SmartServer 2.0 Programming Tools If you need to uninstall the i.LON SmartServer 2.
40 Installing i.LON SmartServer 2.
3 Creating FPM Templates This chapter describes how to use the NodeBuilder Resource Editor to create userdefined functional profile templates (UFPTs). It explains how to upload your company’s updated FPM resource file set to your SmartServer so that you can create an FPM project and begin writing your FPMs. i.LON SmartServer 2.
Creating FPM Templates Overview Before you can begin writing an FPM, you need to create its user-defined functional profile template (UFPT) using NodeBuilder Resource Editor 3.13. Functional profile templates are LONMARK specifications that enable you to specify the functionality required for a device. A functional profile template defines the set of network variables and configuration properties within a functional block that collectively perform a single device function.
2. 3. Create a folder under the LonWorks\types\user directory on your computer if one doesn’t already exist. To do this, follow these steps: a. Right-click the LonWorks/types/Ldrf.Cat file and then click Add Folder on the shortcut menu. b. Open the User folder, create a new folder named YourCompany, and then click Open twice. c. The YourCompany folder appears at the bottom of the resource catalog view. Create a new resource file set for your company.
44 b. The New Resource File Set dialog opens. c. If you plan on integrating your FPM applications with an LNS application such as the LonMaker tool, you should select 5 in the Scope box (this sets the scope to device class, manufacturer, usage, and channel type). d. In the manufacturer (MMMMM) field of the Program ID box, enter your 5-digit manufacturer ID in hexadecimal format.
Note: If your company does not have a manufacturer ID, you can get a temporary manufacturer ID from LonMark at www.lonmark.org/mid. In addition, if your company has many FPM developers, it is recommended that you request temporary manufacturer IDs for them. After you obtain your temporary manufacturer ID, you can enter it in the MMMMM field of the Program ID box. 4. e. In the format (F) field of the Program ID box, enter 9 (this sets the Standard Development Program ID flag). f.
5. Create a UFPT. You can create a new UFPT, or you can create one by copying an existing SFPT to your resource file set. To create a UFPT from an SFPT, skip to step 7. To create a new UPFT, follow these steps: a. Expand the folder containing your company’s FPM resource file set, right-click the Functional Profile Template folder, and then click New FPT on the shortcut menu. Note: Do not expand a resource file set that does not have your unique program ID or is one that you do not manage. 46 b.
6. To create a UFPT from an SFPT, follow these steps: a. Expand the STANDARD resource file set under the LonWorks\Types folder, expand the Functional Profile Templates folder to show all the SFPTs in the folder, right-click a SPFT, and then click Copy on the shortcut menu. b. Right-click the Functional Profile Templates folder in your company’s FPM resource file set and click Paste on the shortcut menu. i.LON SmartServer 2.
c. You can then add, delete, and edit the network variable and configuration property members in the SFPT to fit your FPM application or driver. Adding Network Variable and Configuration Property Types You can add network variable and configuration property types to your UFPT.
resource file set (the resource file set that has your manufacturer ID). To add network variable and configuration property types to your UFPT, follow these steps: 1. Double-click the new UFPT, or right-click it and click Open on the shortcut menu. The Modify Functional Profile dialog opens. 2.
50 4. The selected data type appears below the folder to which it was added in the Profile (center) pane, and the selected data type can be edited in the Properties (right) pane. 5.
Name Enter the name of the network variable within the functional profile template. The name of the network variable may contain letters, digits, and underscore characters, but it cannot start with a digit. Optionally, you can insert “nvi” and “nvo” in front of input and output network variable names, respectively, to simplify the identification of the input and output network variables in the functional profile template.
Application Layer Interoperability Guidelines for more information about configuration property restriction flags. • const_flag. The value of the configuration property cannot be changed. Note: When you deploy the FPM on the SmartServer, the configuration property is automatically set to be persistent.
7. Repeat steps 3–6 for each data type to be added to the functional profile template. 8. Click OK. Generating and Copying the Updated FPM Resource File Set Once you create a UFPT and add all the required network variable and configuration property members to it, you can generate the updated FPM resource file set in which the UFPT was created. After you generate the updated FPM resource file set, you can copy it to the flash disk of your SmartServer.
54 2. The Generate Resources Set dialog opens. 3. Click Yes to generate the updated FPM resource file set. 4. Use FTP to access the root/lonworks/types/user directory on the flash disk of your SmartServer. Create a User/ folder if it does not already exist in the root/lonworks/types directory. 5. Browse to the LonWorks\Types\User\ folder on your computer, and then copy your company’s .ENU, .fmt, .fpt, .ls, and .
4 Creating FPM Device Interface (XIF) Files This chapter describes how to write a model file that declares the network variables and configuration properties in your FPM and a functional block implementing an instance of the UFPT used by your FPM. It explains how to use the i.LON SmartServer 2.0 LONWORKS Interface Developer tool to convert your model file to a device interface (XIF) file and how to copy the XIF to your SmartServer. i.LON SmartServer 2.
Creating FPM Device Interface (XIF) Files Overview In order to deploy an FPM application on the SmartServer, you need to create a device interface (XIF) file extension). The XIF exposes the logical interface of your FPM application so that network tools such as the SmartServer and the LonMaker tool can manage it. The XIF specifies the number and types of functional blocks, and the number, types, and directions of the network variables and configuration properties in your FPM application.
You must declare all the mandatory network variables in the UFPT you created for your FPM. You may declare none to all of the optional network variables in the UFPT. SYNTAX You can declare a network variable in your model file using the following syntax: network input || output type identifier; The network keyword declares a network variable of a specific type with a specific identifier. The input and output keywords define the direction of the network variable.
The type property corresponds to the standard or user-defined network variable type (SCPT or UCPT) used by the configuration property. The specified data type must match the one defined for the referenced configuration property in the UFPT. The config_prop or cp keyword declares the data type as a configuration property. The identifier property is a reference to the configuration property in the UFPT.
external_name property, the SmartServer uses the FPT key of the UFPT for the functional block name. The FPT key is a unique ID (20000 or higher) defined for the UFPT within a resource file set. The fb-property-list is used to implement the configuration properties declared in the model file that apply to the functional block.
nviSetPoint implements nviSetPoint; nviTemp implements nviTemp; nvoAC_OnOff implements nvoAirConditioner_OnOff; nvoFurnace_OnOff implements nvoFurnace_OnOff; } fbHVACFunction external_name ("HVAC Function") fb_properties { nciHeartbeat,nciOffline,nciThrottle,nciHysteresis }; Multiple Functional Blocks with the Same UFPT The following example demonstrates how to use a functional block array in a model file to create two functional blocks that are instances of the same UFPT.
nviTemp implements nviTemp; nvoAC_OnOff implements nvoAirConditioner_OnOff; nvoFurnace_OnOff implements nvoFurnace_OnOff; } fbHVACFunction external_name ("HVAC Function") fb_properties { nciHeartbeat,nciOffline,nciThrottle,nciHysteresis }; /////////////second FB instantiated///////////////////////// network input SNVT_switch nviACSwitch; network input SNVT_switch nviFurnaceSw; network output SNVT_hvac_mode nvoHVACMode; fblock UFPTSwitchEncoder { nviACSwitch implements nviACSwitch; nviFurnaceSw implements nv
nciHeartbeat[0],nciOffline[0],nciThrottle[0],nciHysteresis[0] }; /////////////second FB array instantiated////////////////////////// network input SNVT_switch nviACSwitch[NUM_SWITCH_ENCODER_FBs]; network input SNVT_switch nviFurnaceSw[NUM_SWITCH_ENCODER_FBs]; network output SNVT_hvac_mode nvoHVACMode[NUM_SWITCH_ENCODER_FBs]; fblock UFPTSwitchEncoder { nviACSwitch[0] implements nviACSwitch; nviFurnaceSw[0] implements nviFurnaceSwitch; nvoHVACMode[0]implements nvoHVACMode; } fbSwitchEncoder[NUM_SWITCH_ENCODER
In addition, you should create a folder for your company under the C:\LonWorks\Import folder if one does not already exist. This is where the XIF generated by the i.LON SmartServer 2.0 LonWorks Interface Developer tool will be stored. Generating a Device Interface (XIF) File You can convert a model file to a XIF using the i.LON SmartServer 2.0 LonWorks Interface Developer tool. This tool is a command line interface that requires you to type a few simple commands to create the XIF.
Using Long and Short Command Switch Forms Most command switches come in long and short forms. The long form consists of the verbose, casesensitive name of the command, and it must be prefixed with a double dash '- -'. Long command switches require a separator (a single space or the equals sign [=]) between the command switch and its respective argument.
5 Creating FPMs This chapter describes how to use the i.LON SmartServer 2.0 Programming Tool to create new FPM projects and then write, compile, and debug FPM applications and FPM drivers. i.LON SmartServer 2.
Creating FPMs Overview You can use the full version of the i.LON SmartServer 2.0 Programming Tool to create FPMs. The full version of the i.LON SmartServer 2.0 Programming Tool includes all the components needed to manage an FPM project: • • • • • Eclipse Development Kit preconfigured for writing, building, and uploading FPMs. FPM template files. FPM library. A tool for creating the C structures of user-defined UNVTs is also included. C++ compiler. CYGWIN environment.
Creating New FPM Projects You can create a new FPM project using the i.LON SmartServer 2.0 Programming Tool. To create a new FPM project, you do the following: 1. View the resource files on your SmartServer. 2. Create a new FPM application or FPM driver from the resource file set you added to the SmartServer flash disk. 3. Declare the data points to which the FPM will read and write. Viewing the Resource Files on a SmartServer To view the resource files on a SmartServer, follow these steps: 1.
Creating an FPM To create an FPM application or an FPM driver, follow these steps: 68 1. Expand the SmartServer icon, and then expand the LonMark folder. The resource files in the root/LonWorks/types folder on your SmartServer flash disk are shown. 2. To create an FPM driver, right-click your company’s FPM resource file set, and then click New FPM Driver on the shortcut menu. To create an FPM application, skip to step 3.
Alternatively, you can click the resource file set and then click the Create FPM icon ( top of the LonMark Resource View. 3. To create an FPM application, expand your company’s FPM resource file set, expand the Functional Profile Templates folder, right-click the .UFPT, and then click New FPM Application on the shortcut menu. Alternatively, you can click the UFPT and then click the Create FPM icon ( LonMark Resource View. 4.
5. 70 Optionally, you can specify the project name and the location where the FPM project is to be stored on your computer. a. The default project name is .UFPT. You can accept the default name, which is recommended, or you can enter a different project name. If you enter a different project name, it should adhere to the following naming convention: . .
8. Clear the check boxes for any of the configuration you do not plan on deploying. For example, if you are not deploying the FPM on a SmartServer 1.0, you can clear the Release check box. If you do not plan on debugging your FPM with WindRiver Workbench, you can clear the Debug 4.03 and Debug check boxes. Click Finish. 9. A new FPM project folder with the name specified in step 5 is added to the C/C++ Projects view, and the source file view opens to the right of the C/C++ Projects view. i.
10. In the Data Point Variable Declarations section, located just below the namespace declaration, you can observe that DECLARE statements have automatically been added to the source file for each data point defined in the UFPT. The data points automatically declared includes standard and user-defined types.
disk. See Chapter 3 for more information on generating an updated resource file set and uploading the updated resource files to the SmartServer. After you generate and copy your updated resource files set to the SmartServer, you can manually import one to all of the data point declarations. Manually Importing All Data Point Declarations In the source file (.
Manually Importing Individual Data Point Declarations In the source file (.cpp extension) of your FPM, you can individually add new data points that has been created in the UFPT, and you can individually update existing data points that have been modified in the UFPT. To do this, follow these steps: 74 1. In the LonMark Resource View, expand the UFPT from which the FPM project was created to show all the mandatory and optional data points defined in the UFPT. 2.
3. An updated DECLARE statement for the selected data point is added to the data point declaration section just below the namespace declaration. 4. Repeat steps 2–3 to add or update additional data points in the UFPT. Using UFPT Local Variables Creating an FPM application or driver with the New FPM Project wizard in the i.LON SmartServer 2.0 Programming Tool generates a class that inherits from CFPM_App. This class provides the implementation for an FPM functional block.
SYNTAX DECLARE_FB_INSTANCE_LOCAL(dataType, variableName) EXAMPLE // <= section datapoint variable declarations DECLARE_FB_INSTANCE_LOCAL(int, callCount); Writing an FPM Application You can write an FPM application using the i.LON SmartServer 2.0 Programming Tool. An FPM application reads and writes to the data points declared in it, reads data point properties, executes code upon data point updates, and controls timers and executes code upon their expiration.
//set initial data point values nviSetPoint = 0; nviTemp = 0; nciHystereis = -17.77778; //start timers m_oTimer1.Start(FPM_TF_REPEAT, 2000); m_oTimer2.Start(FPM_TF_ONETIME, 3000); START_TIMER(m_oTimer3, FPM_TF_REPEAT, 2000, OnMyTimer3); // to do: create OnMyTimer3()routine to handle m_oTimer3 } Note: Initialized input data point values are not propagated to output data points when the Initialize() routine executes.
The following code demonstrates how to create repeating and one-time timers using the Start() method: CFPM_Timer m_oTimer1; CFPM_Timer m_oTimer2; , m_oTimer1(this) , m_oTimer2(this) // // // // declared in declared in initialized initialized header file header file in source file in source file ... m_oTimer1.Start(FPM_TF_REPEAT, 2000); m_oTimer2.Start(FPM_TF_ONETIME, 3000); Using the START_TIMER() Macro The START_TIMER() macro is an alternative approach to creating and starting timers.
In the algorithm, you can directly read and write values to the data points declared in your FPM application without using any additional methods. In addition, you can read the statuses, names, and times of last update of the data points using a collection of data point property methods, and you can start and stop timers. For more information on starting timers, see the previous section, Writing the FPM Application Initialize() Routine.
Note: You can modify the behavior of the Changed()method so that it can determine whether any data point property has changed, including value, status, time of last update, and priority. See the next section, Checking for Data Point Property Updates, for how to do this.
Reading Data Point Properties You can read the name, alias name, time of last update, and status of each data point declared in the FPM application in the Initialize(), Work(), and OnTimer()routines. To read these data point properties, you use a collection of get property methods belonging to each data point.
} } Reading Structured Data Points To read the value of a structured data point, you first need to store the data point field in a temporary data point variable. Note that you use the -> operator (element selection through pointer) to reference the fields of a structured data point. The following code demonstrates how to read the fields of a structured data point: void CUFPTHVACController::Work() { SNVT_switch tmpSwitch; tmpSwitch.state = nvoAirConditioner_OnOff->state; tmpSwitch.
Writing Data Point Values You can write updated values to the scalar and structured data points declared in your FPM application in the Work() routine. The updated values are then written back to the data points when the FPM application exits the Work() routine. You can directly write an updated value to a scalar data point by simply assigning it a value. nviTemp = 25.28; nviSetPoint = 22.22; Writing an updated value to a structured data point requires a few additional steps.
Writing to Enumerated Data Points To write to an enumerated data point, you need to use the values of the corresponding enumeration type. The following code demonstrates how to write to an hvac_t enumeration in the standard.h file in the LonWorks\iLON\Development\include folder: DECLARE(_0000000000000000_0_::SNVT_hvac_mode, nvoHVACMode, OUTPUT_DP) ......... void CUFPTHVACController::Work() { SNVT_switch ACSwitch; SNVT_switch FurnaceSwitch; ACSwitch.state = nviACSwitch->state; FurnaceSwitch.
The following code demonstrates how to create an OnTimer()routine that handles the expiration of multiple timers started with the Start() method of the CFPM_Timer class. Observe that the m_oTimer.Expired()method is called first to determine which of the two timers started in the Initialize() routine expired. void CUFPTHVACController::Initialize() { m_oTimer1.Start(FPM_TF_REPEAT, 2000); m_oTimer2.Start(FPM_TF_ONETIME, 3000); } void CUFPTHVACController::OnTimer() { if (m_oTimer1.
void CUFPTHVACController::Shutdown() { m_oTimer1.Stop(); StopAllTimers(); } See the Programmer’s Reference in Appendix A for more information on stopping timers. Writing an FPM Driver You can write an FPM driver using the i.LON SmartServer 2.0 Programming Tool. An FPM driver creates data points on the SmartServer and provides values for them by reading and writing to the RS232 and RS-485 ports on the SmartServer.
Line1.SetDpProperty(FPM::Dp::cfgUCPTpersist, bValue); //write data point poll rate in milliseconds Line1.SetDpProperty(FPM::Dp::cfgUCPTpollRate, nValue); // write data point unit string Line1. SetDpProperty(FPM::Dp::cfgUCPTunit, pszValue); The following code demonstrates the methods you can create in the Initialize() routine in an FPM driver for the RS-232 interface: CFPM_Timer m_oDisplay_InputTimer; //declare timer in header file ............
FPM and the devices connected to the RS-232 and RS-485 serial interfaces, read data from the RS232 or RS-485 interface, write updated values to data points, and read data point properties. If you started more than one timer using the Start()method of the CFPM_Timer class, you must first identify the timer that expired using the m_oTimer.Expired() method. In addition, you must create custom OnMyTimer() routines for each user-defined timers you started with the START_TIMER()macro in the Initialize() routine.
Compiling an FPM Once you finish writing an FPM, you can compile it with the i.LON SmartServer 2.0 Programming Tool. If your code has any errors, they will be listed with any warnings in the Problems view at the bottom of the document window. You can click on the errors and warnings listed in this view to debug your FPM. Following the coding guidelines described in this section will help you debug your code. To compile your FPM, click File and then click Save.
Once you correct all the compile errors and the warnings, click File and then Save to re-compile your code. Tip: You can also check the Console view (located to the right of the Problems view) to see if there is more detailed information available for a given compiler error. Using Non-Latin Characters The Eclipse environment uses Cp1252 text encoding by default. If you insert non-Latin characters in your code, you need to implement additional steps to save your FPM project and to display the characters.
2. In the Text File Encoding box, click Other and then select UTF-8 from the bottom of the list. 3. Click OK. You can now save your FPM project. If you want to save an FPM project that has non-Latin characters and display the characters in your code, you can change your Windows Regional Settings to the native language of the characters. To do this, close the i.LON SmartServer 2.
debug configuration of your FPM in the i.LON SmartServer 2.0 Programming Tool and upload it to your SmartServer, and then connect the Workbench debugger to the iLonSystemWbd or iLonSystemWbdEnd image on your computer via the target server. If you are not using Wind River Workbench to debug your FPMs, you can still perform some debugging by adhering to a number of guidelines. These guidelines include connecting the computer running the i.LON SmartServer 2.0 Programming Tool to the i.
• 5. To reboot your SmartServer using the SmartServer console application, enter the reboot command. For more information on using the SmartServer console application, see the i.LON SmartServer 2.0 User’s Guide. Create a debug configuration for your FPM project. You can skip to step 6 if you already have a debug configuration for your FPM. You have already created a debug configuration if you imported and upgraded an existing debug configuration of an FPM project to the Debug 4.
c. This dialog lists the build configurations available for your FPM. If the Debug 4.03 configuration is listed (or Debug if you plan on running your debug configuration on a SmartServer 1.0), you can skip to step 6; otherwise continue to step d. Note: If you are debugging an FPM to be run on a SmartServer 1.0, select or enter Debug in the following steps instead of Debug 4.03. 94 d. Click New in the Manage Configurations dialog. The Create New Configurations dialog opens. e.
h. Click OK to return to the C/C++ Projects view. 6. Set the Debug 4.03 or Debug configuration as the active configuration so that it is built automatically when you build your FPM. To do this, right-click the FPM project, point to Build Configurations, point to Set Active, and then click Debug 4.03 or Debug. 7. Build your FPM project, as described in Compiling an FPM earlier in this chapter. A Debug 4.03 or Debug folder now appears in the C/C++ Projects View under the Includes folder. i.
8. Upload the debug configuration of your FPM to your SmartServer. To do this, expand the Debug 4.03 or Debug folder, right-click the .UFPT.app || .drv file and then click Transfer to i.LON SmartServer in the shortcut menu. In the Install FPM Module dialog, enter the IP address or hostname of your SmartServer in the Host box, select the Reboot check box, click Finish, and then click Yes to confirm the rebooting of your SmartServer. 9.
c. The New Connection dialog opens. In the Connection Type window, select the WindRiver VxWorks 6.x Target Server Connection and then click Next. i.LON SmartServer 2.
d. In the Target Server Options window, enter the IP address or hostname of the SmartServer on which the FPM to be debugged is installed. e. In the Kernel Image box, click File, click Browse, and then browse to the LonWorks/iLON/Development/Debug/ES_Debug. folder on your computer. f. Click Finish. The iLonSystem image and the FPM executable module (.app or .drv extension) appear in the Target Manager view. 11.
b. The Load/Add Symbols to Debug Server dialog opens. In the Symbol Files and Order box, click Add and then browse to the debug configuration of your FPM. i.LON SmartServer 2.
c. Click OK. The symbols in your FPM are now loaded in the Target Manager view. Symbol icons should appear on the icons representing the FPM executable module and the iLonSystem image. 12. Use WindRiver Work Bench to debug your FPMs, following these steps: 100 a. Expand the Kernel Tasks icon. b. In the Target Manager view, right-click the FPM task and click Attach to Kernel Task (Task Mode) on the shortcut menu. c.
d. If you are using the iLonSystemWdbEnd image and want to switch to System Mode, rightclick the FPM task, point to Target Mode, and click System Mode on the shortcut menu. e. ) is enabled. In the Name In the Symbol Browser view, first verify that the Debug icon ( Filter box, you can search for the symbol for which you want to set a breakpoint. f. Once the symbol appears in the Symbol Browser view, double-click it. The source file view displays the routine to be debugged. g.
• Add your user help functions to the UFPT_Utils.cpp file (this file is created when you create a new FPM project). This further isolates your code for debugging, and it enables you to port the code over to another FPM project. • Insert printf()statements in your code frequently. This enables you to do some debugging with the console port of the i.LON during runtime, as the console port will receive the printf()statements.
• Math. This FPM application adds two SNVT_count input data points when one of the data point values changes, and it writes the sum in a SNVT_count output data point. i.LON SmartServer 2.
104 Creating Freely Programmable Modules
6 Deploying FPMs on a SmartServer This chapter describes how to use the i.LON SmartServer 2.0 Programming Tool to upload FPMs to one or more SmartServers. It explains how to select a network management service (LNS or Standalone) for running your LONWORKS network. It describes how to create, commission, and connect, and test FPM devices on the SmartServer. It describes how to create a custom configuration Web page for FPM applications. It explains how to update FPM applications.
FPM Deployment Overview After you write and compile an FPM application or driver, you can deploy it on your SmartServer. This enables you to apply the algorithms defined in the FPM application or FPM driver to the data points on the SmartServer.
• An FPM programming license must be installed on your SmartServer in order for an FPM to function on the SmartServer. If FPM Programming is not licensed on a SmartServer, the SmartServer will not process the tasks defined in the FPM application. You can order a FPM programming license from the i.LON SmartServer 2.0 Web site at www.echelon.com/products/cis/activate.
4. 108 The Install FPM Module dialog opens with the Deployment Settings window.
5. Enter the following properties: FTP Settings Host Enter the IP address or hostname of the SmartServer to which the FPM is to be uploaded. The default is the IP address or hostname entered in the LonMark Resource View. FTP Port Enter the port the SmartServer uses for FTP communication. The default FTP port is 21. User Enter the user name to log in to the SmartServer. The default user name is ilon. Password Enter the password to log in to the SmartServer. The default password is ilon.
7. This window lists the tasks to be performed, which consists of uploading the FPM to the root/modules directory on the SmartServer flash disk, deleting any existing module with the same name of the FPM being uploaded, rebooting the SmartServer if you selected the Reboot check box in the Deployment Settings window in step 4, and optionally creating a default configuration Web page if you selected the Default Web Page check box. Click Finish. 8.
To order an FPM programming license for your SmartServer, go to the i.LON SmartServer 2.0 Web site at www.echelon.com/products/cis/activate. Deploying FPM Applications If you are deploying an FPM application, your FPM application is initialized once it has been uploaded to the SmartServer.
Selecting a Network Management Service Before you create your FPM devices on the SmartServer, you need to verify that you have selected a network management service mode (LNS or Standalone) for running your LONWORKS network. • In LNS mode (LNS Auto or LNS Manual), the SmartServer transmits network messages to devices through an LNS server, and the SmartServer and the devices connected to it communicate in a peer-to-peer manner.
2. Install the Echelon Enterprise Services 2.0 (EES 2.0) and LNS Server Service Pack 5 on an LNS Server (running LNS Turbo Server [version 3.2] or newer) from the i.LON SmartServer 2.0 DVD or the i.LON SmartServer 2.0 Programming Tools DVD. See Chapter 1 of the Echelon Enterprise Services 2.0 User’s Guide for how to perform these installations. 3. Add an LNS Server to the LAN and then synchronize the network attached to your SmartServer to an LNS network database.
If you are using the SmartServer in Standalone mode and your internal FPM devices are using the v40 XIF (your FPM devices have dynamic functional blocks), you should not switch to LNS mode and select an existing LNS network database to be synchronized with your SmartServer. Dynamic functional blocks are not supported in LNS; therefore, the synchronization process may corrupt your LNS network database.
3. The Create Device dialog opens. 4. In the Name property, enter a meaningful name for the device. 5. In the Location property, select Internal. 6. Expand the LonMark (XIF) folder, expand the root/lonworks/import/ folder, and then select the XIF created for your FPM application. i.LON SmartServer 2.
7. Click OK. An internal device representing your FPM application is added to the bottom of the LON channel tree. 8. Click Submit. You must wait approximately 15 seconds for the SmartServer to instantiate the XIF file used for the internal device. Once the XIF has been instantiated, you can expand the FPM device and its functional block to show the data points in the FPM application. Note: The FPM device will be highlighted orange in the SmartServer tree, indicating that it not commissioned.
Using a Dynamic Device Interface If you are running your network with the SmartServer operating as a standalone network manager, the internal device can use a static or dynamic interface. To use a dynamic interface, you select the SmartServer’s v40 XIF from the root/lonworks/import/Echelon/iLON100 folder, and you then add a dynamic functional block to the device that uses a UFPT representing your FPM application. To add an FPM device that uses a dynamic interface to a SmartServer, follow these steps: 1.
118 7. The Add Functional Block dialog opens. 8. In the Name property, enter a name for the functional block that summarizes the functionality of the FPM. 9. In the Select property, expand the Dynamic folder, expand the folder in the root/lonworks/types/user directory containing your company’s resource file set, expand your company’s resource file set to show the available UFPTs, and then select the UFPT representing the FPM application (.UFPT).
10. Click OK. 11. Click Submit. A functional block representing the FPM application and all of the data points declared in the FPM application are added to the tree under the internal device. Note: The FPM device will be highlighted orange in the SmartServer tree, indicating that it not commissioned; however, you do not need to commission the FPM device in order for it to run its application. i.LON SmartServer 2.
Commissioning FPM Devices If you are running your LONWORKS network in LNS mode (LNS Auto or LNS Manual) and you plan on using LONWORKS connections to bind the data points in your FPM application with the data points on the internal SmartServer device, on another FPM device, or on the external devices connected to the SmartServer, you must first commission your FPM device.
2. Follow the instructions in the Commission Device Wizard and then click Finish. See the LonMaker User’s Guide for more information on using this wizard. 3. When the LonMaker tool is done commissioning the FPM device, the FPM device shape will be solid green (online) or crosshatched green (soft offline), indicating that the FPM device has been commissioned. In addition, the FPM device should be clear in the SmartServer tree.
Testing FPM Applications After you add an FPM application on the SmartServer, you can test it using the View – Data Points Web page. To do this, you open the View – Data Points Web page, add the input and output data points in the FPM device that you can use to observe the FPM application processing data point updates, update one or more of the input data points, and observe that the output data points are updated accordingly. To test an FPM on your SmartServer, follow these steps: 1.
The major difference between LONWORKS connections and Web connections is that LONWORKS connections propagate data point updates over a LONWORKS channel via the LonTalk Protocol or the LonTalk protocol tunneled through an IP-852 channel. Web connections propagate data point updates via SOAP/HTTP over a TCP/IP network.
124 5. The Configure – WebBinder Web page opens and the hostname of the LNS Server and the LNS network database in which the hub network variable is stored appear under the WebBinder Destinations icon in the application frame to the right. 6.
7. References to the target LONWORKS network variables ( ) are added underneath the hub network variables in the LNS tree in the left frame. Updates to the selected hub network variable will be propagated to the target network variables listed underneath the hub. Repeat this step to connect the selected hub network variable to any other desired compatible target hub network variables. • If the target network variable is not compatible with the hub network variable a warning message appears.
See Chapter 5 of the i.LON SmartServer 2.0 User’s Guide for more information on selecting a messaging service. 10. You can add the hub and target network variables to the View – Data Points Web page and test that the LonWorks connections are updating the target network variables accordingly. To test your LONWORKS connections in the LNS tree, follow these steps: 126 a. Click View and then click Data Points. The View – Data Points Web page opens. b.
Note: For more information on creating LONWORKS connections with the LNS tree, including how to validate and delete them, see Chapter 5 of the i.LON SmartServer 2.0 User’s Guide. Connecting FPM Data Points with the LonMaker Tool You can use the LonMaker tool to create LONWORKS connections with the data points declared in your FPM application. To do this, follow these steps: 1. Verify that you have completed the following steps: a.
To create Web connections with the data points declared in your FPM application, follow these steps: 1. 2. 128 If you want to use Web connection to bind the data points in your FPM application to data points on SmartServers other than your local SmartServer, you can add one or more remote SmartServers to the LAN. To add a remote SmartServer to the LAN, follow these steps: a. Right-click the LAN icon, point to Add Host, and then click i.LON SmartServer 2.0 on the shortcut menu. b. The Setup – Remote i.
c. In the tree of the target SmartServer, right-click the any object in the network branch and click Paste External... on the shortcut menu. d. The data points and their parent channel, device, and functional block are added to the network tree of the target SmartServer. i.LON SmartServer 2.
e. 130 Click Submit. 3. From the local SmartServer tree on the left frame, right-click a source data point and then click Add Binding in the shortcut menu. The source data point will typically be an output data point on the internal SmartServer device, an output data point on an external device connected to the SmartServer, or an FPM output data point. Updates to the source data point in a Web connection are propagated to one or more target data points. 4.
5. From the Webbinder Destinations tree on the right frame, expand the SmartServer Webbinder destination icon containing the target data points to be connected, expand the network, channel, device, and functional block containing the desired target data point, and then click one or more compatible target data points.
6. Click Submit. References to the target data points are added underneath the source data point in the local tree on the left frame. 7. Test that your Web connections are updating the FPM data points accordingly following these steps: a. Click View and then click Data Points. The View – Data Points Web page opens. b. Close the graph by clicking the ‘X’ in the upper right-hand corner of the application frame. c.
Note: For more information on using Web connections, including how to validate, delete, and add attachments to them, see Chapter 4 of the i.LON SmartServer 2.0 User’s Guide. Creating Custom FPM Configuration Web Pages You can create configuration Web pages for your FPM applications using i.LON Vision 2.0. To do this, you add i.LON Vision 2.0 read/write and application objects to the default custom Web page that was created for your FPM when you uploaded it to the SmartServer flash disk.
If an .htm file for your FPM application is not in the folder, use the i.LON Development tool to create the default FPM configuration Web page following these steps: 134 a. In the C/C++ Projects view, expand the Release folder, right-click the .UFPT.app file and then click Transfer to i.LON SmartServer in the shortcut menu. b. In the Deployment Settings window of the Install FPM Module dialog, select the Default Web Page check box. c. Click Finish.
The NLS Text object is used to translate custom SmartServer Web pages into multiple languages. The NLS Text object provides a single user-defined key that you can associate with multiple text strings in different languages. These text strings are saved in .properties files corresponding to the custom Web page and their respective languages (e.g., page.properties, page_de.properties, page_es.properties, and so on). The .
9. 136 Specify the data point to be monitored and controlled by the i.LON Vision 2.0 object. You can either click Prog Name and manually enter the name of the data point, or you can click Select and use the Data Points dialog to select the data point following these steps: a. In the Data Points dialog, click Prog Name. This enables all instances of your FPM application to write to their respective data points.
10. Configure the other object properties in the dialog following the i.LON Vision 2.0 User’s Guide, and then click OK. 11. Repeat steps 7–10 to add other i.LON Vision 2.0 objects to your custom FPM configuration Web page. 12. Optionally, you change the title of your FPM configuration Web page. The default page title is NLS_TEXT. To change the page title, follow these steps: a. 8. Click Format and then click Page Title Properties. The Page Properties dialog opens.
13. Click Publish on the Editor toolbar ( ), click File and then click Publish, or click the Browse tab to publish your custom Web page to save the current draft of your custom FPM configuration Web page. 15. View your custom FPM configuration Web page from the SmartServer Web interface. To do this, click the General button above the navigation pane on the left side of the SmartServer Web interface, and then click the functional block representing your FPM application.
2. Upload your company’s updated resource file set to the root/LonWorks /types/User/ folder on the SmartServer flash disk. 3. Use the i.LON SmartServer 2.0 Programming Tool to manually import the new or updated data point declarations. In the LonMark Resource View, right-click the UFPT from which the FPM project was created, and then click Import All Declarations on the shortcut menu.
5. 140 Select the XIF file to be activated, following these steps: a. In the Template property, click the button to the right. b. The Choose File dialog opens. c. Expand either the LonMark (XIF) folder, expand the subfolders containing the XIF file to be loaded onto the SmartServer, and then click the XIF file.
d. Click OK to return to the Setup - LON Device Driver Web page. e. Click Submit. 6. Right-click one of the selected devices in the SmartServer tree, point to Manage, and then click Activate Template in the shortcut menu. Alternatively, you can clear and then select the Smart Network Management check box to the left of the Template property in the Setup -LON Device Driver Web page and then click Submit. 7. You must wait approximately 15 seconds for the SmartServer to instantiate the updated XIF file.
8. If you switched a static device interface to a dynamic interface, add a functional block representing your FPM application as described in the Using a Dynamic Device Interface section earlier in this chapter Deploying FPMs on Multiple SmartServers After you have deployed FPMs on a development SmartServer, you can deploy the FPM applications and drivers you have developed on multiple SmartServers.
• If you are deploying an FPM application that uses static functional blocks, copy the device interface (XIF) file (.xif extension) to the root/lonworks/import/ folder. • Copy the FPM executable modules (.app or .drv extension) to the root/modules/user/ folder. • If you created a custom FPM configuration Web page for your FPM applications, copy your custom Web pages to the root/web/config/Fb folder. 6. If you are deploying an FPM driver, reboot the SmartServers. 7.
144 Deploying Freely Programmable Modules on a SmartServer
7 Creating FPM Application Licenses This chapter describes how to create licenses for your FPMs so that customers can order and implement your FPMs on their SmartServers. It describes how to build an FPM licensing tool. It explains how to enable a license validation feature in your FPM application. It describes how to create FPM licenses. It lists the files you need to provide to customers who order your licensed FPM applications. i.LON SmartServer 2.
Licensing Overview You can create FPM application licenses and let customers order and implement your FPMs on their SmartServers. To create an FPM application license and make your FPM application available for order, you do the following: 1. 2. 3. 4. 5. Create an FPM licensing tool. Enable license validation in your FPM application. Build the release version of your licensed FPM application. Create FPM application licenses.
demonstrates the structure of the element and the properties you can define in it is provided after the table. Property Company CompanyName ShortCompanyName LonMarkID Company/Feature FeatureName ShortFeatureName AlgorithmIndex Description Specify the name of your company. Specify the name of your company or an abbreviated name. Legal characters are those that would be legal for file names on the SmartServer. You should only use letters, numbers or the underscore character.
LicenseType LockType Options SecretKey indexes. Specify the type of license to be issued. The default LicenseType is “Unlimited”. You may create your own license type designations. For example, you could specify a “Demo” license if you plan on modifying your FPM application so that the license provided to a customer expires after a specified trial period such as 30 days. Specify the type of lock used to uniquely identify a customer’s SmartServer.
Creating a Security DLL File The i.LON License Generator requires a security DLL file named LicenseSecurity.dll that implements a specific security algorithm. The security algorithm enables you to publish unique digital signatures for your FPM licenses. You can build your own LicenseSecurity.dll file, or you can use the sample security DLL file provided by Echelon. The following sections describe how to build the security DLL file and how to use the provided sample security DLL file.
the C macro DONT_TRANSLATE_NAMES before each of these files. The names of the routines to be used all begin with “LICMGR_” If you use the supplied implementation of the HMAC-MD5 digest algorithm, you can optionally turn it into a non-standard algorithm by adjusting the pre-defined HMAC_IPAD_XOR_VALUE and HMAC_OPAD_XOR_VALUE values. If you want to modify the pad XOR values, you must define them as one-byte hex values.
To verify that the license key in the FPM license file is valid, your license validation routine needs to first check the results of the Node Lock Check. If the SmartServer passed the Node Lock Check, your license validation routine should then check the FPM license data; otherwise, it should log a license error.
Tips for Securing your Licensing Scheme: You can implement a number of security measures in your licensing scheme to help protect your FPM application from unauthorized use or piracy. The examples provided in this section demonstrate some of these measures, which are designed to force anyone attempting to break the licensing scheme to disassemble your object code and reverse-engineer the algorithms. To test the strength of your licensing scheme, you should attempt to break it once you have completed it.
3. Click the header file. The header file view opens to the right of the C/C++ Projects view. 4. Insert the following include directives in the “includes go here.” section of the header file. // Required include statement. // node lock check. #include "LicenseMgr.h" Finds FPM license and performs // Define name translations for macros in MD5 digest if not // already defined in file.
2.
Tips: • You should obscure the name of the license validation routine (and other symbols shown in all capitals) to help secure your FPM application. To do this, define a macro with the same name as the symbol and then specify a name translation for it. For example, the following macro could be defined for the license validation routine created in step 2. #define FPM_CHECK anotherFPMfunction • 3. You can alternatively create your license validation routine as a static file-scope routine.
Step 4: Writing the License Validation Algorithm You need to write a license validation algorithm that (1) verifies that the Lock ID (MACID, LUID, or other user-defined lock type) specified in the FPM license matches the one on the customer’s SmartServer, and (2) verifies that the license key in the FPM license file is valid. To do this, your license validation algorithm must call the method in the i.LON License Manager that finds and parses an FPM license and performs a Node Lock Check.
Generator Configuration File for more information on the CompanyName and FeatureName properties. 5. Declare a License Manager control structure, then set the license file path and the license ID fields. The file path field corresponds to the path of the FPM license file relative to the root/config/license folder on the SmartServer flash disk, and the name of the FPM license file. The default file name of an FPM license is .xml.
Verifying the License Key To write your license validation algorithm so that it verifies the license key in the FPM application license file, you do the following: 1. Check the results of the Node Lock Check. For example: if (taskCallBlock.sts == LicMgrStsOK) { //store the license data pLic = taskCallBlock.pLicense; … 2. If the SmartServer passes the check, get the secret key defined for your FPM in a block of memory. If you split it into pieces, you must assemble them here.
Note: Pointers to strings will not be NULL if they are not used, instead some may point to empty strings. 6. Based on the results of the license key evaluation, validate the FPM license, or log a license error. You can use a value other than 1 and later check for that specific value instead of using a boolean zero/non-zero check. For example: FPM_IS_LICENSED = SOME_MAGIC_NUMBER; } else { taskCallBlock.
char msg[100]; sprintf(msg, "FPM license key is invalid: file \"%s\"\n", taskCallBlock.pFilePath); taskCallBlock.pGeneric = (void*)msg; LICMGR_TaskCall_LogLicenseError(&taskCallBlock); } }else { char msg[100]; sprintf(msg, "FPM license not found: file \"%s\"\n", taskCallBlock.pFilePath); taskCallBlock.
set path=%path%;C:\LonWorks\iLON\Development\eclipse\plugins\ com.echelon.eclipse.ilon100.fpm_0.9.0\compiler\3.3.2-vxworks6.2\x86-win32\i586-wrs-vxworks\bin 4. Use the GNU strip command to remove the internal-only symbols from your FPM executable module. To do this, type the following command: strip --strip-unneeded –-target=elf32-big modulename where modulename is the name of your FPM executable module in the following format: .UFPT.app.
2. By default, the first pre-defined feature specified in the license configuration file (iLONLicenseGenValues.xml) and its associated default values appear in the dialog. 3. In the Feature Name property, select the FPM to be licensed from the list of the FPMs defined in the tags in the license configuration file. The specified default values of the properties associated with the selected FPM appear in the dialog. 4.
• To locate the LUID (Neuron ID) from the SmartServer Web pages, click Driver at the top of the tree in the sidebar (left) frame, expand the Net network, expand the LON channel, and then click any internal SmartServer device, which have “(Internal)” appended to their names. The Setup – LON Device Driver Web page opens. The Neuron ID is the first property listed under the Identification Property header. 6.
The FPM application license log file lists the following information: • • • • The date on which the FPM application license was created. Your company’s name and LonMark ID The customer information you entered in step 9. The FPM license data, which consists of your company’s name, the name of the FPM licensed, the license type, lock type, lock ID, any options specified, and the license key generated for the FPM application by the security DLL file.
LonWorks\iLON\Development\eclipse\workspace.fpm\.UFPT\Release folder on your computer, and it is named .UFPT.app. See Chapter 5, Creating FPMs, for more information on creating and compiling the FPM application. See Enabling License Validation in an FPM Application in this chapter for more information on protecting your FPM applications. • The FPM application license. This is the .xml file you created with the i.
166 Creating FPM Application Licenses
8 Localizing the SmartServer Web Interface This chapter describes how to translate custom SmartServer Web pages and the entire SmartServer Web interface to a different language. i.LON SmartServer 2.
Language Localization Overview You can localize the language of the SmartServer Web interface using the i.LON SmartServer 2.0 Programming Tool. The SmartServer includes English, German, and French languages, but you can work with the SmartServer in any one-byte or two-byte character language by translating the .properties files on the SmartServer. You can perform language localization using either the demo version of the i.LON SmartServer 2.0 Programming Tools included on the i.LON SmartServer 2.
b. Paste the folder in the same directory. c. Rename the folder to something meaningful such as “i.LON 100 4.0 ”. 3. Start the i.LON SmartServer 2.0 Programming Tool. To do this, click Start, point to Programs, point to Echelon i.LON SmartServer 2.0 Programming Tools, and then click i.LON SmartServer 2.0 Programming Tools. The i.LON SmartServer 2.0 Programming Tool opens. 4. Click File and then click Import. The Import dialog opens in the Select window. i.LON SmartServer 2.
170 5. Expand the General folder, click Existing Projects into Workspace, and then click Next. The Import Projects window opens. 6. Click Browse. The Browse to Folder dialog opens.
7. Browse to the LonWorks\iLon100\images\iLon100 4.0 folder and then click OK. A new project called NLS appears in the Projects: box. This means that your language localization project has been created within the current workspace. 8. Click Finish. An NLS project appears in the C/C++ Projects view. i.LON SmartServer 2.
9. Expand the NLS folder. All the English, German, and French .properties files for the SmartServer embedded applications, system setup Web pages, and headers and properties appear under the NLS folder. Note: A language localization project is stored in its own set of resource files; therefore the installation of an updated version of the SmartServer embedded image will not conflict with these resource files.
8000010128000000[4].UFPTscheduler.properties files in the root/web/nls/echelon/ folder with the i.LON SmartServer 2.0 Programming Tool. 3. Create a custom SmartServer Web page using i.LON Vision 2.0. Translating Common Properties You can translate the COMMON.properties file in the root/web/nls/echelon/ folder on the SmartServer flash disk with the i.LON SmartServer 2.0 Programming Tool. To translate this file, you do the following: 1. In the C/C++ Projects view of the i.LON SmartServer 2.
174 3. The left frame in the view lists all the common properties in the SmartServer Web interface. The right frame includes boxes that display the English (Default), German, and French translations of a selected property. The bottom includes tabs that you can click to view and edit a list of all the properties within a .properties file for a specific language. 4. Click the New tab at the bottom of the Editor view. The New Properties File: dialog opens. 5.
6. The Lang. and Country properties are filled in. Optionally, you can enter a Variant to further categorize the selected language. This is useful if you want to create different translations of the same language with the same regional version. 7. Click Create. i.LON SmartServer 2.
8. A new COMMON<_language[_REGION] [_variant]>.properties file is added to the C/C++ Projects view and this file appears in the Editor view. In addition, a box marked with the language you selected is added to the bottom of the right frame of the Editor view. Note that all the properties listed in the left frame are marked with warning symbols, indicating that the property has not yet been translated. Once you enter a translation for a property, the warning symbol is removed. 9.
) in the upper You can comment out the text in a translation by selecting the checkbox ( right-side of the language box. You can switch to your language’s property tab by clicking the arrow ( ) on the upper right-hand corner of your language box. • To translate the properties from your language’s tab, first copy the Default (English) translation and paste it into your language’s tab. You can begin translating the properties listed in your language’s tab.
a. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web\nls\echelon directory or on your computer (or other location where your working copy of the NLS files is stored). b. Use FTP to access the root/web/user/echelon/folder on the flash disk of your SmartServer. c. Copy the COMMON<_language[_REGION] [_variant]>.properties file in the LonWorks\iLon100\images\iLon100 4.0 \web\nls\echelon folder on your computer to the root/web/nls/echelon/ folder on the SmartServer flash disk.
2. Re-name the copy by deleting the “Copy of” pre-fix and inserting the “<_language[_REGION] [_variant]>” suffix between the name of the embedded application and the .properties extension. For example, you can create a Spanish version of the Event Scheduler by copying and pasting the 8000010128000000[4].UFPTscheduler.properties file and re-naming it 8000010128000000[4].UFPTscheduler_es.properties. 3. Click OK. The new localized version of the .properties file appears in the C/C++ Projects view. 4.
2. Connect i.LON Vision 2.0 to your SmartServer. To do this, click Manage Connections in the Sites pane on the left side, or click File and then click Site Manager. The Site Manager dialog opens. Click New Site, the Edit Site dialog opens. Enter your SmartServer’s information, and then click OK twice. A link with the IP address of your SmartServer is added to the Sites pane. 3. Create a new custom SmartServer Web page.
8. The iLON Vision -Object – dialog opens. 9. Configure the application object to fit the functionality provided by your custom SmartServer Web page. In the Default Language box, select your localized language, and then click OK. 10. Edit and link your custom SmartServer Web page as described in the i.LON Vision 2.0 User’s Guide. 11. Click Publish on the Editor toolbar ( Publish. The Publish As dialog opens. ), click the Browse tab, or click File and then click i.LON SmartServer 2.
12. In the File Name property, enter the name of the .htm file (one word with no spaces), and then click OK. Creating Localized FPM Configuration Web Pages You can localize the language for custom FPM configuration Web pages. To do this, follow these steps: 182 1. Copy the root/web/config/Fb/NLS folder on the SmartServer flash disk to your computer. 2. Start the i.LON SmartServer 2.0 Programming Tool. To do this, click Start, point to Programs, point to Echelon i.LON SmartServer 2.
5. Click Browse. The Browse to Folder dialog opens. 6. Browse to the web/config/Fb/NLS folder you copied to your computer and then click OK. A new project called web-config-Fb (custom NLS) appears in the Projects: box. This means that your language localization project has been created within the current workspace. i.LON SmartServer 2.
7. Click Finish. A web-config-Fb (custom NLS) project appears in the C/C++ Projects view. 8. Expand the web-config-Fb (custom NLS) folder. The English .properties files for the FPM configuration Web pages appear under the NLS folder. 9. Create a new .properties file for the FPM configuration Web page as described in Translating Common Properties earlier in this chapter. 10. Translate any NLS Text objects you added to your FPM configuration Web page and translate the page title property (NLS_TITLE).
Localizing the Language of the SmartServer Web Interface Localizing the language of the SmartServer Web interface entails doing the following: 1. Translating one-by-one all of the .properties file in the web/nls/echelon folder on the SmartServer flash disk with the i.LON SmartServer 2.0 Programming Tool. 2.
To create a new web/user/echelon/ folder, follow these steps: 1. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web\user\echelon folder on your computer (or other location where your working copy of the SmartServer embedded image is stored). 2. Create a new folder named . For example, if you are creating a Korean translation, create a new folder named “ko”.
4. Save the index.htm file. 5. Copy the index.htm file to the SmartServer. To do this, follow these steps: a. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web folder on your computer (or other location where the index.htm file in your working copy of the SmartServer embedded image is stored). b. Use FTP to access the root/web folder on the SmartServer flash disk. c. Copy the index.htm file on your computer to the root/web folder on the SmartServer flash disk.
opens. Click New Site, the Edit Site dialog opens. Enter your SmartServer’s information, and then click OK twice. A link with the IP address of your SmartServer is added to the Sites pane. 4. ) on the Editor toolbar to open the Select File dialog opens. Select Click the Choose button ( the web/user/echelon//Welcome.htm Web page, and then click OK. 5. The English version of the Welcome.htm Web page opens. 6. Click Edit on the Editor toolbar ( ) or click the Layout tab.
8. a. In the Page Title box, enter a descriptive page title. b. Click OK. Click Publish. The Welcome.htm Web page appears in your localized language. Translating the Welcome.htm File with a Text Editor You can translate the Welcome.htm file using a text editor such as Notepad, WordPad, or TextPad. To do this, follow these steps: 1. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web\user\echelon folder on your computer (or other location where the Welcome.
190 • Line 8 corresponds to the “i.LON SmartServer 2.0 – Welcome” title at the top of the SmartServer Welcome Web page. • Lines 32–34 correspond to the “i.LON SmartServer 2.0 – Welcome” text at the bottom of the SmartServer Welcome Web page. 4. Save the Welcome.htm file. 5. Copy the Welcome.htm file to the SmartServer. To do this, follow these steps: a. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web\user\Echelon folder on your computer (or other location where the Welcome.
Translating the Menu.htm File You can translate the Welcome.htm and Menu.htm files in the web/user/echelon/ folder in your working copy of the SmartServer embedded image. You can do the translation with i.LON Vision 2.0, or you can do it with a text editor. Translating the Menu.htm File with i.LON Vision 2.0 You can translate the Menu.htm file using i.LON Vision 2.0. To do this, follow these steps: 1.
192 ) or click the Layout tab. 6. Click Edit on the Editor toolbar ( 7. Double-click the Menu bar and the top of the Web page, or right-click the Menu bar and click Object Properties on the shortcut menu. The Navigation Edit dialog opens.
8. Expand SETUP to display its submenu items. i.LON SmartServer 2.
9. Click Edit. The Navigation Subtree dialog opens. 10. In the Label box, translate SETUP to your localized language and then click OK. 11. One-by-one, click the items listed under SETUP, click Edit, enter the translation in the Label box of the Navigation Link dialog, and then click OK. 12. Repeat steps 9-12 to translate the remaining subtree and link menus items.
13. When you have finished translating the menus and menu items to your localized language, click OK. 14. Change the language of the Submit and Back buttons to your localized language. To do this, follow these steps: a. Double-click the Submit button, or right-click the Submit button and click Object Properties on the shortcut menu. The Menu Button dialog opens b. Select your localized language from the Default Language box and then click OK.
c. Repeat steps a–b to change the language of the Back button to your localized language. 15. Click Publish. The Menu.htm Web page appears in your localized language. Translating the Menu.htm File with a Text Editor You can translate the Menu.htm file using a text editor such as Notepad, WordPad, or TextPad. This entails translating the menu and menu items and updating the language settings in the file.
• Lines 32–44 in this example correspond to the “Setup” menu and its menu items. • Lines 62–82 in this example correspond to the “View” menu and its menu items. i.LON SmartServer 2.
• Lines 85–93 in this example correspond to the “Settings”, “Help”, and “Log Off” menus. Note that the translation of the SmartServer online help files is not supported. 4. Change the language for the Submit and Back buttons to “elon_lang_” (lines 121 and 127 in the following example). 5. Save the Menu.htm file. 6. Copy the Menu.htm file to the SmartServer. To do this, follow these steps: a. Browse to the LonWorks\iLon100\images\iLon100 4.
2. Connect i.LON Vision 2.0 to your SmartServer. To do this, click Manage Connections in the Sites pane on the left side, or click File and then click Site Manager. The Site Manager dialog opens. Click New Site, the Edit Site dialog opens. Enter your SmartServer’s information, and then click OK twice. A link with the IP address of your SmartServer is added to the Sites pane. 3. ) on the Editor toolbar to open the Select File dialog opens.
6. Double-click the Menu bar and the top of the Web page, or right-click the Menu bar and click Object Properties on the shortcut menu. The Navigation Edit dialog opens. 7. Select your localized language from the Default Language box and then click OK. This sets your localized language as the default for the Sidebar.htm file. 8. Click Publish. The Sidebar.htm Web page appears in your localized language. Translating the Sidebar.
1. Browse to the LonWorks\iLon100\images\iLon100 4.0 \web\user\Echelon folder on your computer (or other location where the Sidebar.htm file in your working copy of the SmartServer embedded image is stored). 2. Open the Sidebar.htm file with your text editor. 3. Change the one “elon_lang_de” setting to “elon_lang_” (line 12 in the following example). 4. Save the Sidebar.htm file. 5. Copy the Sidebar.htm file to the SmartServer.
3. Click Login. The localized i.LON SmartServer 2.0 - Welcome Web page opens. 4. The menus, the objects in the sidebar frame (left frame), and text in the i.LON SmartServer 2.0 Welcome Web page (application frame to the right) should appear in your localized language. 5. Click the menus to view the translated menu items. Expand the tree in the sidebar frame and click the objects in the tree to see their translated Configuration and Driver property Web pages.
Appendix A FPM Programmer’s Reference This appendix details the files, routines and methods you will use to create and program your FPMs. i.LON SmartServer 2.
Overview This chapter provides details you will need when programming your module. It includes the following sections: • Template Files. This section describes the template files you will use to create your module. • Routines. This section describes the four main routines you will need to implement within your custom module: Initialize(), Work(), OnTimer(), and Shutdown(). • Methods.
Initialize() The Initialize() routine in the .cpp file is called when your FPM application or driver starts or is enabled. For an FPM application, you can use the Initialize() routine to write initial data point values, and start timers. For an FPM driver, you can use the Initialize() routine to open RS-232 or RS-485 connections, start timers, and write data point properties. • You can start timers using the Start()method of the CFPM_Timer class or the user-defined START_TIMER() macro.
For an FPM application, you can also use the Work() routine to start and stop timers, and you can use it to read data point properties. For an FPM driver, if a data point value has changed and you want to write data to the RS-232 interface as a result, you must first initialize communication between your FPM and the devices connected to the RS-232 and RS-485 interfaces. You can initialize communication with the interfaces using the rs232_ioctl() and rs485_ioctl() methods.
For an FPM application, you can also use the OnTimer() routine to start and stop timers, and you can use it to read and write to data point properties. For an FPM driver, you can use the OnTimer() routine to read and write to the RS-232 and RS-485 interfaces. FPM Application The following code demonstrates code you could use in the OnTimer() routine in an FPM application. In this example, the m_oTimer.Expired()method valuates which of two timers has expired and performs some tasks upon their expiration.
Shutdown() The Shutdown() routine in the .cpp file is called when your FPM stops or is disabled. You can use the Shutdown () routine to stop timers and close RS-232 and RS-485 connections in an FPM driver. In addition, you can use Shutdown() routine to free previously allocated memory and perform any required cleanup before shutting down the FPM. • You can stop a timer using use the Stop()and StopAllTimers()methods of the CFPM_Timer class.
Variable Type Size unsigned long long unsigned int int float double 32 Bits 32 Bits 32 Bits 32 Bits 32 Bits 64 Bits Internal FPM Data Point Methods For the data points declared in an FPM application or FPM driver, you can use the Changed()method to determine if a data point value has been changed, and you can use the NotifyOnAllUpdates() method to modify the Changed() method so that it checks whether any data point property has been updated, including value, status, time of last update, and priority.
{ Note: You can use the NotifyOnAllUpdates() method modify so that the Changed()method checks whether any data point property has changed, including value, status, time of last update, and priority. See NotifyOnAllUpdates() for more iinformation. NotifyOnAllUpdates() You can call the NotifyOnAllUpdates() method in the constructor of your FPM so that the Changed() method checks whether any data point property has changed, including value, status, time of last update, and priority.
Note: You can also use temporary data point variables to write values to the fields within a structured data point. To do this, you declare a temporary data point, store the desired values in the various fields of the temporary data point, and then assign the declared data point a reference to the temporary data point variable. The following code demonstrates how to write to a structured data point using temporary data point variables SNVT_switch tmp_switch; //create temporary DP variable tmp_switch.
If the priority specified in the nPrioAuthority parameter is equal to or higher than the priority currently assigned to the data point, this method returns a STATUS value of OK and the priority used by the FPM application to write to the data point is reset to 255. All applications in which the data point is registered are notified that they can write values to the data point, and the application with highest priority is able to write values to the data point.
This method returns the UCPTname configuration property of the data point in the following format: ////. The UCPTname configuration property is an array unsigned ASCII characters. EXAMPLE const char* nviSetPoint_name; nviSetPoint_name = nviSetPoint.
SYNTAX const timespec GetDpPropertyAsTimeSpec(FPM::Dp::dataUCPTlastupdate) This method returns the UCPTlastupdate configuration property of the data point in the following format: YYYY-MM-DDTHH:MM:SSZ. The UCPTlastupdate configuration property is a timestamp in UTC (Coordinated Universal Time) indicating the last time the data point configuration was updated. EXAMPLE timespec nviSetPoint_lastUpdateTime; nviSetPoint_lastUpdateTime = nviSetPoint.
AL_FIR_MONITOR_COND AL_FIR_MAINT_ALERT AL_FATAL_ERROR AL_ERROR AL_WARNING AL_HEADER AL_FOOTER AL_DEBUG AL_INFO AL_SYSTEM_INFO AL_VALUE_INVALID AL_CONSTANT AL_OFFLINE AL_UNKNOWN AL_NUL =20 =21 =30 =31 =32 =243 =244 =245 =246 =250 =251 =252 =253 =254 =255 EXAMPLE FPM::Dp::PointStatus nviSetPoint_status; nviSetPoint_status = nviSetPoint.
void SetDpProperty(FPM::Dp::dataUCPTAliasName, const char* const pszValue) The pszValue parameter specifies an alias name to be assigned the data point. The alias name can be any string that describes the data point. EXAMPLE nviSetPoint.SetDpProperty(FPM::Dp::dataUCPTAliasName, “FPM DP Setpoint”); SetDpProperty (UCPTpriority) You can use the SetDpProperty(UCPTpriority) method in the Work()and OnTimer()routines of an FPM application to write a priority to a data point.
EXAMPLE F1.SetDpProperty(FPM::Dp::cfgUCPTdefOutput, 100); SetDpProperty(persist) You can use the SetDpProperty(persist) method in the Initialize()routine of an FPM driver to set whether a data point is persistent (a constant). SYNTAX void SetDpProperty(FPM::Dp::cfgUCPTpersist, bool bValue) The bValue parameter specifies whether the data point is persistent. Specify true to make the data point a constant. Specify false to enable the value of the data point to be updated. EXAMPLE F1.
External SmartServer Data Point Methods In an FPM application, you can use the List() method with a specific xSelect syntax to obtain a list of external data points on the SmartServer. External data points include those data points on the internal SmartServer device [i.LON App (Internal)] and the data points of the external devices connected to the SmartServer.
v.GetDpPropertyAsString(Dp::cfgUCPTname), v.GetDpPropertyAsString(Dp::cfgUCPTaliasName), v.GetUCPTindex(), v.GetDpPropertyAsItemCfgDepth(Dp::cfgItemDepth)); } Notes: • You can also define an xSelect statement that queries data point properties instead of actual data points. For example, you could define an xSelect statement that queries the AliasName configuration property of a data point.
• -1. The data point value is read from the SmartServer’s internal data server. The poll rate used by the FPM application is set to the poll rate configured for that data point in its Setup LON Data Point Driver Web page. This is the default. • 0. The data point value is read directly from the data point. Note that because the data point value is being read synchronously, the FPM application may not able to perform any other processing until it receives the data point value. • >1.
The pbyValue parameter specifies the value to be written to the data point. The STATUS value returned by this method can either be ERROR or OK. EXAMPLE The following example demonstrates a Write()method that changes the value of a data point returned by a List() method.
in the Initialize(), Work(), and OnTimer()routines of an FPM application, and you can use it in the Initialize()routine of an FPM driver. SYNTAX START_TIMER(timeVar, mode, timeoutMillis, funcName) The timeVar parameter specifies the name of the timer to be started. The mode parameter specifies the type of the timer. You can enter FPM_TF_REPEAT for a repeating timer, or you can enter FPM_TF_ONETIME for a timer that is used just once. The nTimeoutMillis parameter specifies the timer interval in milliseconds.
m_oTimer2.Start(FPM_TF_ONETIME, 0); } void CUFPT_FPM_Application::OnTimer() { if (m_oTimer2.Expired()) { m_oTimer2.Start(FPM_TF_ONETIME, 2000); } } Stop () You can use the Stop()method of the CFPM_Timer class to stop a timer that is running. You can use this method in the Work(), OnTimer(), Shutdown() routines of an FPM application, and you can use it in the Shutdown()routine of an FPM driver. SYNTAX bool Stop() If the timer has expired, the method returns TRUE.
if (m_oTimer1.lsRunning()) { //execute code } GetMode() You can use the GetMode()method to check the type of the referenced timer (repeating or one-time) when it is running. This method may be useful during runtime. SYNTAX FPM_TimerFlags_t GetMode() This method returns the type of timer (repeating or one-time) if the referenced timer is running. If the referenced timer has been stopped, this method returns UNKNOWN.
extern "C" STATUS fnRebootSmartServer (int a_nBootFlag); #endif … void CUFPTmath::Work() { printf("\nCUFPTmath::Work(): "); if (Changed( in1 ) || Changed( in2 )) { out3 = in1 + in2; printf("out3 = %d = %d + %d", *out3, *in1, *in2 ); } if (Changed(str)) { printf("str = %s", (char*) str->ascii ); } // REBOOT here if(100 < *out3) { fnRebootSmartServer(0x00); } } RS-232 Interface Methods You can use RS-232 interface methods to connect an FPM driver to the devices attached to the RS-232 serial port on the Smart
int fd = rs232_open(9600); rs232_ioctl() You can use the rs232_ioctl() method in the Initialize() routine to initialize and send commands to the RS-232 interface. You should call this method immediately after opening the RS232 interface with the rs232_open() method. Note that you can send commands to the RS-232 interface using other I/O control methods besides the rs232_ioctl() method.
parameter is set to IOCTL_SIO_HW_OPTS_SET. This method returns the 0 upon success, and it returns -1 upon failure. A failure could occur if another FPM is using the interface, or if the interface is not properly connected to the RS-232 port. EXAMPLE The following example demonstrates a rs232_ioctl()method that returns the current configuration used by the RS-232 interface.
int nBytesRead = ReadBytes(RS232_fd, rxBuf, MAX_RX_BYTE_SIZE); //check whether something has been read if (nBytesRead >= 1) { printf ("Read %c from RS232\n", Line1); //if something has been read, write it to display device rs232_write(RS232_fd, (Byte *)rxBuf, nBytesRead); } } } int CRs232Driver::ReadBytes(HANDLE handle, Byte* buffer, int bytesToRead) const { fd_set readFds; FD_ZERO(&readFds); FD_SET(handle, &readFds); Timeval readTimeout; readTimeout.tv_sec = 0; readTimeout.
The buf parameter specifies a pointer to the memory area containing the data to be written to the RS-232 interface. The length parameter specifies the maximum number of bytes that are to be read. This method returns the number of bytes read upon success, and it returns -1 upon failure. A failure could occur if another FPM is using the interface, or if the interface is not properly connected to the RS-232 port.
Verify that the file handle is specified in a global variable so that you can reference it from the Work() and Shutdown() routines. EXAMPLE The following example demonstrates a rs485_open()method that opens an RS-485 connection with a baud rate of 9600. int fd = rs485_open(9600); rs485_setparams() You can use the rs485_setparams() method in the Initialize() routine to set the operating parameters of the RS-485 interface.
iLON/Development/eclipse/plugins/com.echelon.eclipse.ilon100.fpm_0.9.0/compiler/echelon/fpm /include folder in your LONWORKS directory. The values you can specify for the cmd and data parameters are as follows: cmd parameter data parameter IOCTL_BAUDRATE Specify the baud rate at which the RS-485 interface will communicate with the serial port on the i.LON. IOCTL_RCVBUFSIZE Specify the receive buffer size. For more information, see the rs485_setbuffersize() section.
The length parameter specifies the maximum number of bytes that are to be read. This method returns the number of bytes read upon success, and it returns -1 upon failure. A failure could occur if another FPM is using the interface, or if the interface is not properly connected to the RS-485 port. EXAMPLE The following example demonstrates a rs485_read()method that reads data from the RS-485 interface.
File Access Methods You can read and write to data files on the SmartServer using the following ANSI ‘C’ file methods: fopen(), fread(), fwrite(), fseek()and, fclose(). fopen() You can use the fopen()method to open a file and assign it a stream that can be identified by other methods. SYNTAX FILE fopen (const char * filename, const char * mode); The filename parameter specifies the name of the file to be opened.
EXAMPLE The following example demonstrates an fopen()method that creates a new text file for writing and assigns it to a file stream. FILE * pFile; pFile = fopen ("myfile.txt","w"); fread() You can use the fread()method to read a block of data from a file stream. This method reads an array of elements from the file stream and stores the data in a block of memory on the SmartServer. Note: The SmartServer does not have memory protection.
fclose(pFile); } } fseek() You can use the fseek()method to set the position indicator associated with the a file stream to a new position. SYNTAX int fseek (FILE * stream, long int offset, int origin); The stream parameter specifies a pointer to a FILE object that identifies the stream. The offset parameter specifies the number of bytes to be offset from origin. The origin parameter specifies the position from where offset is to be added.
if((pFile = fopen(Filename,"a")) == NULL) { printf(“Can't open or create i.LON 100 file = %s \n", Filename); } else { fwrite(buf,1,len,pFile); fclose(pFile); printf("Wrote %d bytes to file = %s \n", len, Filename); } fclose() You can use the fclose()method to close a file. SYNTAX int fclose (FILE * stream); The stream parameter specifies a pointer to a FILE object that specifies the file stream to be closed. If the file has been closed successfully, this method returns a zero value.
Appendix B FPM Development and Deployment Checklist This checklist outlines the steps required to develop and deploy your FPMs on the SmartServer. i.LON SmartServer 2.
1. Create User-Defined Functional Profile Template (UFPT) NodeBuilder Resource Editor à Request temporary manufacturer ID from LonMark www.lonmark.org/mid if you do not have one or, if your company has many FPM developers. Create a new FPM resource file set for company. Must create scope 5 resource file set if integrating FPM application with an LNS Application such as the LonMaker tool.
à à à Use i.LON SmartServer 2.0 Programming Tool to upload FPM executable module (.app or .drv extension) to root/modules/user/ folder on SmartServer flash disk. Must have FPM license on SmartServer to upload FPMs. Select Default Web Page check box in Deployment Settings window of Install FPM Module dialog to create custom FPM configuration Web page for FPM applications. If you are deploying an FPM driver, reboot the SmartServer.
à Use Adobe Contribute CS3 with i.LON Vision 2.0 toolkit to create custom FPM configuration Web Pages. 5. Deploy FPM Applications or Drivers on Multiple SmartServers in Field To view custom FPM configuration Web page, click General above navigation pane on left side of the SmartServer Web interface and then click a functional block under FPM device.
Appendix C FPM FAQ This FAQ answers common question related to FPMs. . i.LON SmartServer 2.
SmartServer FPM FAQs 1. What are Freely Programmable Modules (FPMs)? FPMs are custom C/C++ applications or drivers (RS-232 or RS-485) that allow you to customize the SmartServer’s embedded software. You can use FPMs to perform tasks not provided by the SmartServer’s built-in applications. FPMs can have both network variables (NVs) and Configuration Properties (CPs). 2. • An FPM Application reads and writes values to the data points declared in it.
• • For FPM Applications. o Add an internal device using the above XIF (Static FBs) or the SmartServer’s v40 XIF (Dynamic FBs). o You may need to commission the internal device in order to use certain features (e.g., when using LONWORKS connections with Static FBs) For FPM Drivers. o 4. Nothing, once uploaded to the SmartServer you are done.
If you use Static FBs for the figure above then you would have to create two XIF files because the number of FBs is not the same for both devices. If you were using multiple identical internal devices then you only need to create one XIF file. 7. What is the relationship between FPM applications and the functional blocks (FBs) in an internal device? The relationship is similar to the built-in SmartServer applications and the functional.
For Static FBs, you need to create a model file (*.nc extension) in which you declare all the data points in the UFPT used by the FPM, and a functional block that implements an instance of the UFPT. You then need to use the i.LON SmartServer 2.0 LonWorks Interface Developer tool to convert the model file to a XIF file.
(UFPT), which defines the NVs and CPs to which your FPM will read and write. The NodeBuilder Resource Editor is available on the i.LON SmartServer 2.0 Programming Tools DVD. The UFPT serves as the FBs specification for your FPM. 14. What is a resource file set? These files define the external FBs of your FPM module. This includes the NVs and CPs to which your FPM will read and write. The resource files set needs to be defined before you can start coding your FPM.
File: fpmMathAdder.xif generated by LonTalk Interface Developer Revision 3.00.35, XIF Version 4.401 Copyright (c) Echelon Corporation 2002-2008 All Rights Reserved.
No. You can only use one NV type (SNVT or UNVT) for each FPM NV which you specify within the resource file set. 25. Can I add Dynamic NVs to my FPM FB? No. Dynamic NVs are not supported (only NVs that are declared at compile time are supported). 26. Can I access the Configuration Properties of other devices? Only CPs that are defined as CP NVs. 27. Does an FPM have access to the SmartServer TCP/IP protocol stack (Sockets)? No, this feature is not supported. FPMs can not directly make an outbound SOAP call.
data points on external devices, dynamic network variables added to the SmartServer’s internal automated systems device [“i.LON App (Internal)” by default], and data points in FPM applications and drivers. You can add more than 1,000 data points, but you should periodically open the Setup - System Info Web page to verify that SmartServer has enough resources (Spare Flash Blocks, Free Disk Space, RAM, and CPU Utilization) to support the additional data points.
void CUFPTfpmTempController::Initialize()] {] // Determine FB index by looking at one of the NVs name, [index] char * nv_name = (char *)nviTemp.
Yes. This how you pass data from the FPM driver to the FPM applications. 44. Can a FPM application access the default UART Drivers? No, you will need to write your own driver. 45. Can you use logic in a FPM driver? You can, but we don’t recommend it. You should use the FPM driver to send and receive data to the UART and do all of your processing in a FPM application. i.LON SmartServer 2.
www.echelon.
