NodeBuilder® FX/PL Examples Guide ® 078-0403-01A
Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital Home, i.LON, LNS, LonMaker, LonMark, LonPoint, LonTalk, NodeBuilder, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonScanner, LonSupport, OpenLDV, and LNS Powered by Echelon are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Table of Contents Preface .................................................................................................... iv Purpose ........................................................................................................... v Audience.......................................................................................................... v System Requirements ..................................................................................... v Content ...............................
Preface The NodeBuilder® FX/PL Development Tool includes a Neuron C example application that you can load into your LTM-10A Platform. You can use this example to test the I/O devices on the Gizmo 4 I/O Board, and create a simple managed LONWORKS® network. You can follow the instructions in this document to create the example device application from scratch.
Purpose This document describes how to load and use the Neuron C example application included with the NodeBuilder FX/PL Development Tool. Audience This guide is intended for device and system designers with an understanding of control networks. System Requirements Requirements for computers running the NodeBuilder PL examples are listed below: • Microsoft® Windows Vista or Microsoft Windows XP.
an IP-852 router, your computer must have an IP network interface such as an Ethernet card or modem with PPP software. In addition, the i.LON software must be installed on your computer, and the IP-852 channel must be configured using the LONWORKS-IP Configuration Server application software. The LonMaker tool, which is included with the NodeBuilder software, automatically installs drivers for all local and remote network interfaces, except the SLTA-10 Serial LonTalk Adapter.
LTM-10A User's Guide Describes how to use the LTM-10A Platform for testing your applications and I/O hardware prototypes. Also describes how you can design the LTM-10A flash Control Module into your products. The LTM-10A Platform is included with the NodeBuilder FX/PL Development Tool. Neuron® C Programmer’s Guide Describes how to write programs using the Neuron C Version 2.2 language. Neuron® C Reference Guide Provides reference information for writing programs using the Neuron C language.
viii Region Europe Languages Supported English German French Italian Contact Information Echelon Europe Ltd. Suite 12 Building 6 Croxley Green Business Park Hatters Lane Watford Hertfordshire WD18 8YH United Kingdom Phone: +44 (0)1923 430200 Fax: +44 (0)1923 430300 lonsupport@echelon.co.uk Japan Japanese Echelon Japan Holland Hills Mori Tower, 18F 5-11-2 Toranomon, Minato-ku Tokyo 105-0001 Japan Phone: +81-3-5733-3320 Fax: +81-3-5733-3321 lonsupport@echelon.co.
1 Using the NodeBuilder FX/PL Example This chapter introduces the Neuron C example application that you can run on an LTM-10A Platform and test with the Gizmo 4 I/O Board. It describes how to load the pre-built example application on an LTM-10A Platform using the LonMaker Integration Tool, which is included with the NodeBuilder FX Development tool, and how to use the I/O devices on the Gizmo 4 I/O Board to test the example application.
Introduction to the NodeBuilder FX/PL Example The NodeBuilder FX/PL Development Tool includes a Neuron C example application, NcExample, that you can load into your LTM-10A Platform. You can use this example application to test the I/O devices on the Gizmo 4 I/O Board, and create simple managed LONWORKS networks. The example application is designed to run on a Gizmo 4 I/O Board attached to an LTM-10A Platform.
Released Binaries The NcExample device application includes a pre-built binary application image file (.apb extension) that you can download to your LTM-10A Platform using the LonMaker tool. This folder also contains a pre-built text device interface file (.xif extension) that exposes the example application’s device interface so that the LonMaker tool can manage the example application.
Using the Pre-Built Example Device Application You can use the LonMaker tool to download the NcExample device application to the LTM-10A Platform and install it in a LONWORKS network. To do this, you restore the NcExa.zip file in the LonWorks\NeuronC\Examples\NodeBuilder LTM-10A\Database folder, load the pre-built binary application image file (.apb extension) for the NcExample application to the device, and then commission the example device.
6. Click OK. 7. By default, the LonMaker tool will prompt you to select whether to install any new files in the Import folder (includes LONMARK® resource files) and then any new files in the Types folder (includes XIF and application image files [.apb extension]). Click Yes to restore the files. 8.
10. Select the Network Attached check box. In the Network Interface Name property select the network interface to be used for communication between the LonMaker tool and the LTM-10A Platform over the LONWORKS channel. Click Next. You can use the U20 USB Network Interface included with the NodeBuilder FX/PL Development Tool, or you can use another network interface such as an i.LON SmartServer or an i.LON 100 e3 Internet Server.
12. Select OnNet to immediately propagate changes you make to the example device in the LonMaker drawing to the physical device on the network. Click Finish. 13. A message appears recommending that you recommission devices that have changed since the network was backed up. Click No. 14. The LonMaker drawing for the example application opens.
Downloading the Example Application To download the example application to the LTM-10A Platform, follow these steps: 1. 8 Right-click the yellow cross-hatched device shape representing your uncommissioned example device, point to Commission, and then click Commission on the shortcut menu.
2. The Commission Device Wizard opens with the Application Image window displayed. Select the Load Application Image check box. This specifies that you will download the pre-built binary application image file for the NcExample application (NcExample.apb) to the device. The NcExample.apb file is stored in the LonWorks\NeuronC\Examples\NodeBuilder LTM-10A\ReleasedBinaries\Release folder. 3. Click Finish. The Press Service Pin window appears. 4. Press the service pin on the Gizmo 4 I/O Board.
Testing the I/O Devices on the Gizmo 4 I/O Board You can use the I/O devices on the Gizmo 4 I/O Board to observe how network variable connections enable devices to exchange data. You can use a switch device to control a lamp device on the Gizmo 4 I/O Board. You can then set an alarm condition, trigger the alarm and activate the piezo buzzer and an LED on the Gizmo 4 I/O Board, and then use a switch device on the Gizmo 4 I/O Board to acknowledge the alarm and turn off the buzzer and LED.
2. Press and hold the SW2 button at the bottom left side of the Gizmo 4 I/O Board (Button 2). Observe that LED2 above the SW2 button (LED 2) turns on. Also, observe that input and output values displayed on the connector shape in the LonMaker drawing are 0.0 1. This means that the Switch and LED are at their minimum values (0%) and on (1). 3. Release the SW2 button to turn off LED2. Also, observe that input and output values displayed on the connector shape in the LonMaker drawing are now 0.0 0.
so that they are all selected, right-click one of the selected functional block shapes, and click Browse on the shortcut menu. 12 2. The LonMaker Browser opens. It displays the three selected functional blocks (Button 1, RTC, and LED 1) and the network variables and configuration properties within each functional block. Note that you can only write values to the input network variables (blue) and writable configuration properties (green). 3. Click the Monitor All button ( 4.
5. Click anywhere in the nviAlarmTime row and enter a time in the Value box at the top of the Browser that is a few seconds later than the current time in nvoTimeDate. The device application evaluates whether the current time in nvoTimeDate is later than the alarm time in nviAlarmTime, and triggers an alarm if it is. 6. When the alarm time you set passes, the piezo buzzer will generate audio feedback and LED1 on the bottom left side of the Gizmo I/O Board will turn on.
Creating the Example Device Application This section details how to create the NcExample device application from scratch. It describes how each part of the example was developed using the NodeBuilder tool and the LonMaker tool. The example is divided into the nine steps, which introduce different parts of the device development process. You should complete these steps in order because each step assumes that you have successfully completed the previous one.
warning that you have a mismatch between the Program ID and the transceiver type. For purposes of the example, you can ignore this warning. If you want to change the Program ID to the appropriate transceiver value, you must set the scope of the resource file created in Step 5: Implementing a Simple Type Translator to 4 so that the Program ID of the resource file set will match the Program ID of the device. Click Next. The Target Platforms window opens. 9.
Now that you have added the device to the LonMaker drawing and loaded the device with its application, the NodeBuilder Project Manager and the LonMaker tool will automatically load new builds of the application into the device. 9. The Gizmo display shows an “Echelon NEURON C Example Application” message after loading and commissioning has been completed. 10. Use the LonMaker tool to test the device.
same as the type of the primary input network variable of the functional block (nviDigitalOutput). 11. Click Generate and Close. 12. Open the device template’s Source Files folder and open ncexample.h by double clicking it. Add the following lines of code shown in bold: #ifndef _NcExample_H_ #define _NcExample_H_ #define SWITCH_ON 0x01 #define SWITCH_OFF 0x00 This code defines enumerations to use for on and off values for the buttons and LEDs. 13. Open DigitalOutput.
// initialize output lines: GizmoSetLed(0, DigitalOutput[0]::cpDigitalDefault.state); GizmoSetLed(1, DigitalOutput[1]::cpDigitalDefault.state); setLockedOutBit(uFblockIndex, FALSE); } else if ((TFblock_command)iCommand == FBC_DISABLED) This code causes LEDs to be set to the value specified in the cpDigitalDefault configuration property when the device is reset. 16. Build the development target. To do this, right click the Development target, and then click Build on the shortcut menu.
8. Repeat steps 3 and 4, but rename the nviAnalog network variable to nviAnalogOutput. 9. Right-click the AnalogInput functional block’s Implementation-specific CPs folder and select Add CP from the shortcut menu. The Add Configuration Property dialog opens. 10. Add an implementation-specific SCPTupdateRate configuration property. Name the new configuration property cpUpdateRate.
#define AI_FILTERSIZE #define AI_CHANNELS 4 AnalogInput_FBLOCK_COUNT mtimer ai_timer; // the buffer for the averaging filter: unsigned long ai_rawdata[AI_CHANNELS][AI_FILTERSIZE]; // recent value (required to detect changes for minimum NV updates) unsigned long ai_rawrecent[AI_CHANNELS]; //{{NodeBuilder Code Wizard Start The Gizmo 4's PIC controller does not provide an interrupt upon the availability of new analog data.
ai_rawdata[iChannel][iIndex] = ai_rawdata[iChannel][iIndex + 1]; } // fetch current value (store in filter history and also // use current value to initialize current result ulValue = ai_rawdata[iChannel][AI_FILTERSIZE-1] = GizmoReadAnalog(iChannel); // compute average over averaging window: for (iIndex = 0; iIndex < AI_FILTERSIZE-1; ++iIndex) { ulValue += ai_rawdata[iChannel][iIndex]; } // now we've got the sum, let's divide in a reasonable // way.
24. Browse the Analog Output 1 and Analog Input 2 functional blocks using the LonMaker Browser. Verify that an update to the nviAnalogOutput network variable on Analog Output 1 gets reflected in the nvoAnalogInput network variable on Analog Input 2. Allow a generous conversion error—the Gizmo 4 I/O Board has a 10-bit ADC and an 8-bit DAC converter that are daisy-chained, which causes conversion errors to be multiplied.
13. Use the LonMaker Browser to browse the translator. Enable monitoring for nvoPercentage, and force nviTempP to several values within and outside the supported range of 0-+30°C. 14. Connect the nvoPercentage output network variable to the input network variable of one of the analog output functional block blocks, connect a multimeter to the relevant analog output. 15. Use the LonMaker Browser to change the nviTempP value, and observe the results.
13. Repeat steps 11 and 12, but set CP Name to UCPTmaxTemp. 14. Right-click the UFPTtranslator functional profile and select Open. The Modify Functional Profile Template dialog opens. 15. Add one configuration property of each of the new types to the Mandatory CPs folder. Name them cpTransInMin and cpTransInMax, respectively. 16.
The (tempP * 2) term transforms an unscaled SNVT_temp_p value into an equivalent unscaled SNVT_lev_percent value, and the second 100/30 term adjusts so that 30° C converts to 100% of the output signal range. Both terms could be combined in a single factor, but this example uses both for double-precision intermediate results. 22. Build the development target. To do this, right click the Development target, and then click Build on the shortcut menu.
else if ((TFblock_command)iCommand == FBC_WHEN_RESET) HVACTempOld = 0; UpdateTemperature(); // get going: setLockedOutBit(uFblockIndex, FALSE); break; 10. Still in TempSensor.nc, add the following functions to the code: #endif //_HAS_INPUT_NV_ int cmptime ( const SNVT_elapsed_tm * const a, const unsigned long b ) { unsigned long ulA; int iResult; // convert SNVT_elapsed_tm_a into a value of type(b).
when (timer_expires(hvac_coretick)) { // advance the timers: HvacMinSendTimer += HVAC_CORETICK; HvacMaxSendTimer += HVAC_CORETICK; // get new value and re-transmit if needed UpdateTemperature (); // transmit most recent value if needed due to heartbeat timer: if (cmptime((const SNVT_elapsed_tm * const) &(TempSensor::cpMaxSendTime), HvacMaxSendTimer) <= 0 ) { PropagateTemp( HVACTempOld ); } } void TempSensorDirector(unsigned uFblockIndex, int iCommand ) The cmptime(a,b) function compares the a and b values.
7. Right-click the RealTimeKeeper functional block’s Optional CPs folder and select Implement Optional CP from the shortcut menu. The Implement Optional CP dialog appears. 8. Implement the nciUpdateRate configuration property. Name the new configuration property cpRtcUpdRate. Set Initial Value to 3L. 9. Right-click the RealTimeKeeper functional block’s Implementation-specific NVs folder and select Add NV from the shortcut menu. The Add NV to Functional Block dialog appears. 10.
&& (current.hour == RealTimeKeeper::nviAlarmTime.hour) ) { // raise alarm rtc_alarmstate = rtc_alarm_alarm; RealTimeKeeper::nviAlarmState.state = SWITCH_ON; } break; case rtc_alarm_alarm: // alarm currently visible/audible, // awaiting acknowledgement break; } } rtc_coretick = RealTimeKeeper::nvoTimeDate::cpRtcUpdRate * 100UL; } void RealTimeKeeperDirector(unsigned uFblockIndex, int iCommand) This code controls timer processing. 18. Still in RealTimeKeeper.
// #ifdef _HAS_INP_NV_6 // // when(nv_update_occurs(nviTimeSet)) { if (fblockNormalNotLockedOut( fblock_index_map[nv_in_index]) ) { updateDeviceState(nv_in_index, nv_array_index, fblock_index_map[nv_in_index]); // TODO: process nviTimeSet event here } } when(nv_update_occurs(nviAlarmAck)) // //--}}NodeBuilder Code Wizard End // disabled the above to prevent CodeWizard from re-generating // associated code { if (fblockNormalNotLockedOut(fblock_index_map[nv_in_index]) ) { upda
5. Open the Wheel functional block’s Mandatory NVs folder. Right-click the nvoValue network variable and select Properties from the shortcut menu. The NV Properties dialog opens. 6. Set NV Type to SNVT_lev_percent and Name to nvoWheel. 7. Right-click the Wheel functional block’s Optional CPs folder and select Implement Optional CP from the shortcut menu. The Implement Optional CP dialog appears. 8. Implement the nciGain configuration property. Name the new configuration property cpWhGain.
} priority when (io_changes(ioWheel)) { if (fblockNormalNotLockedOut( Wheel::global_index)) { if (Wheel::cpWhGain.divisor) { // No division by zero. Use gain factor and send new // incremental value to heartbeat/throttle handler WheelIncrValue(muldivs(input_value, Wheel::cpWhGain.multiplier, Wheel::cpWhGain.divisor)); } } } The Cp2Tick() function converts a SNVT_elapsed_tm value into a tick count (a tick occurs each WHEEL_HBCORE milliseconds).
// Manage the throttle preferences. Note the throttle tick // counter is maintained by the WheelTimer routine. if (ulMinSendT >= Cp2Tick(&Wheel::nvoValue::cpWhMinSendT)) { ulMinSendT = 0; ulMaxSendT = 0; nvoWheel = lWheelValue; } } 25. Still in wheel.
This code updates the output network variable with recent physical data to wipe out the override value. This implementation ignores any value updates received during the override period, but resets the output to the last known value when the device entered the override state. This allows the device to be set into override while the sensor unit is replaced or while diagnosing the network. The interpretation of correct override behavior is device-dependent and subject to the device implementation.
www.echelon.
