i!-Weather
instruction manual
integration!Solutions
Software Warranty Agreement
GRANT OF LICENSE. AMX Corporation grants to you the right to use the enclosed i!-Weather software program (the
SOFTWARE) on a single central processing unit (CPU). This license is for object code only and does not convey any
rights to use of the source code.
This Agreement does not authorize you to distribute the SOFTWARE.
COPYRIGHT. The SOFTWARE is owned by AMX Corporation, and is protected by United States copyright laws and
international treaty provisions. Therefore, you must treat the SOFTWARE like any other copyrighted material (e.g., a
book or musical recording) except
val purposes, or (b) transfer the SOFTWARE to a single hard disk provided you keep the original solely for backup or
archival purposes. You may not copy the written materials accompanying the SOFTWARE.
OTHER RESTRICTIONS. You may not rent or lease the SOFTWARE, but you may transfer the SOFTWARE and
accompanying written materials on a permanent basis provided you retain no copies and the recipient agrees to the
terms of this Agreement. You may not reverse engineer, decompile, or disassemble the SOFTWARE. If the SOFTWARE is an update or has been updated, any transfer must include the most recent update and all prior versions.
You may use only one version of the SOFTWARE at any time. You may not use the version of the SOFTWARE not
being run on your CPU on any other CPU or loan, rent, lease or transfer them to another user whether with or without
consideration.
LIMITED WARRANTY
LIMITED WARRANTY. AMX Corporation warrants that the SOFTWARE will perform substantially in accordance with
the accompanying written materials for a period of ninety (90) days from the date of receipt. Any implied warranties on
the SOFTWARE and hardware are limited to ninety (90) days and one (1) year, respectively. Some states/countries do
not allow limitations on duration of an implied warranty, so the above limitation may not apply to you.
CUSTOMER REMEDIES. AMX Corporation’s entire liability and your exclusive remedy shall be, at AMX Corporation's
option, either (a) return of the price paid, or (b) repair or replacement of the SOFTWARE that does not meet AMX Corporation's Limited Warranty and which is returned to AMX Corporation. This Limited Warranty is void if failure of the
SOFTWARE or hardware has resulted from accident, abuse, or misapplication. Any replacement SOFTWARE will be
warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer.
NO OTHER WARRANTIES.
not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to the SOFTWARE,
the accompanying written materials, and any accompanying hardware. This limited warranty gives you specific legal
rights. You may have others which vary from state/country to state/country.
NO LIABILITY FOR CONSEQUENTIAL DAMAGES
whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business
information, or any other pecuniary loss) arising out of the use of or inability to use this AMX Corporation product, even
if AMX Corporation has been advised of the possibility of such damages. Because some states/countries do not allow
the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you.
that you may either (a) make one copy of the SOFTWARE solely for backup or archi-
AMX Corporation disclaims all other warranties, either expressed or implied, including, but
. In no event shall AMX Corporation be liable for any damages
U.S. GOVERNMENT RESTRICTED RIGHTS
The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the
Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is AMX Corporation, 3000 Research Drive,
Richardson, TX 75082.
If you acquired this product in the United States, this Agreement is governed by the laws of the State of Texas.
Should you have any questions concerning this Agreement, or if you desire to contact AMX for any reason, please
write: AMX Corporation, 3000 Research Drive, Richardson, TX 75082.
Table of Contents
Table of Contents
Introduction ...............................................................................................................1
Supported Operating Systems .......................................................................................... 1
Minimum PC Requirements .............................................................................................. 1
Installing i!-Weather........................................................................................................... 2
i!-Weather NetLinx Components ....................................................................................... 2
i!-Weather Applications ............................................................................................................ 2
i!-Weather Touch Panel Interfaces........................................................................................... 2
i!-Weather Engines................................................................................................................... 3
Using i!-Weather .......................................................................................................5
Configuring i!-Weather ...................................................................................................... 5
Entering Location by Zip Code .......................................................................................... 5
Entering Location by Station ID......................................................................................... 5
Using the "Browse for Location" Feature .......................................................................... 5
Saving Presets .................................................................................................................. 6
Changing Temperature Units ............................................................................................ 6
Changing Wind Speed Units ............................................................................................. 6
Changing Pressure Units .................................................................................................. 6
Auto Refresh Interval Select.............................................................................................. 6
Programming i!-Weather ..........................................................................................7
i!-WeatherApplicationTest.axs /
i!-WeatherApplicationMod.tko ........................................................................................ 7
Define Module .......................................................................................................................... 7
Devices .................................................................................................................................. 11
Constants ............................................................................................................................... 11
i!-WeatherEngineTest.axs / i!-WeatherEngineMod.tko ................................................... 12
Define Module ........................................................................................................................ 12
Devices .................................................................................................................................. 12
Structures............................................................................................................................... 13
Request New Weather Data .................................................................................................. 14
Receive New Weather Data ................................................................................................... 15
Changing Temperature, Pressure, & Speed Formats ............................................................ 15
Channels ......................................................................................................................... 17
i!-Weather Virtual Channel Map ............................................................................................. 17
Request Channels.................................................................................................................. 17
Status & Request Channels ................................................................................................... 17
Debug Channels .................................................................................................................... 17
i!-Weather
i
Table of Contents
Notification Channels ............................................................................................................. 18
Status Only Channel .............................................................................................................. 19
Commands...................................................................................................................... 19
i!-Weather Virtual Device SEND_COMMANDS ..................................................................... 19
Examples ............................................................................................................................... 20
Appendix A ...............................................................................................................1
Error Codes....................................................................................................................... 1
ii
i!-Weather
Introduction
i!-Weather™ is an application that allows you to retrieve and display current weather with 5-day
forecasting from AMX’s weather provider.
Current Weather Content:
City name for current weather Current Heat Index
Current Temperature Current Wind Chill
Wind Direction Current Humidity
Wind Speed Current Dew Point
Current Conditions Current Barometric Pressure
Forecasting Content:
High / Low Temperature
Introduction
Forecasted Conditions
In order to run i!-Weather, you will need the following:
A NetLinx™ Master with Ethernet that can reach the Internet.
i!-Weather Service Subscription
Supported Operating Systems
Windows 95
Windows NT 4.0
64 MB of installed memory)
Windows 2000
(minimum requirement); 300MHz or faster recommended, with 96 MB of installed
memory.)
Windows ME® (running on a Pentium 266 MHZ processor (minimum requirement);
300 MHZ or faster recommended, with 96 MB of installed memory.)
Windows XP® (running on a Pentium 266 MHZ processor (minimum requirement);
300 MHZ or faster recommended, with 128 MB of installed memory.)
®
/98® (with at least 48 MB of installed memory)
®
Workstation or Server (service pack 6 B or greater, with at least
®
Professional or Server (running on a Pentium 233 MHz processor
Minimum PC Requirements
i!-Weather
Windows-compatible mouse (or other pointing device)
At least 50 MB of free disk space (150 MB recommended)
VGA monitor, with a minimum screen resolution of 800 x 600
A Network adapter
1
Introduction
Installing i!-Weather
1. In Explorer, double-click i!-WeatherSetup.exe from the directory window where you
downloaded the i!-AgendaPlus install program.
2. After reading the License Agreement, select I Agree and Next to proceed.
3. The Welcome To i!-Weather Setup dialog appears, reminding you to close all Windows
programs before going any further. Click Next to proceed.
4. In the Select i!-Weather Install Location dialog, use the Browse button to navigate to a
directory other than the default install directory, if desired. Click Next.
5. In the i!-Weather Shortcut Creation dialog, select Install Shortcut Icons for the installed
components on your desktop, if desired.
6. Click Next in the Start i!-Weather Installation dialog to install the selected components.
7. The program prompts you to restart your system to complete the installation.
i!-Weather NetLinx Components
i!-Weather Applications
i!-Weather is comprised of the following applications:
i!-WeatherApplicationMod.tko: The i!-WeatherApplication module is the fully
developed NetLinx application for retrieving detailed weather data from a given location.
i!-WeatherApplicationTest.axs: NetLinx sample code provided to demonstrate the
proper implementation and usage of the i!-WeatherApplication module.
i!-Weather Touch Panel Interfaces
i!-Weather provides the following user interfaces:
i!-Weather(640X480).tpd: A fully functional user-interface (UI) which allows you to
specify location by zip code, browse to a location, setup presets and select units for
temperature, wind speed, and pressure. (for use with G3 touch panels)
i!-Weather(320x240).tpd: A display-only version for use on smaller resolution panels
(320 x 240). This version allows you to select presets and view all weather content. (for
use with G3 touch panels)
i!-Weather(1024x768).tp4: A fully functional user-interface (UI) which allows you to
specify location by zip code, browse to a location, setup presets and select units for temp,
wind speed. (for use with G4 touch panels)
i!-Weather.kpd: A display only DMS keypad layout. This version allows you to select
presets and view all weather content.
2
i!-Weather
i!-Weather Engines
i!-Weather is comprised of the following:
i!-WeatherEngineMod.tko: This i!-WeatherEngine module is provided to allow custom
NetLinx programs to retrieve weather data in a structured programmable format.
i!-WeatherEngineTest.axs: NetLinx sample code provided to demonstrate the usage of
the i!-WeatherEngine module.
Introduction
i!-Weather
3
Introduction
4
i!-Weather
Using i!-Weather
Configuring i!-Weather
For Subscription Information Contact AMX At: 800-932-6993, option 3.
Entering Location by Zip Code
To enter a location by Zip code:
1. Navigate to the "i!-Weather Select Location" page.
2. Select Enter Zip Code.
3. Enter the 5-digit zip code.
4. Press Done.
This will return you to the "i!-Weather Select Location" page and display the corresponding city in
the "current location" field. From this page you can save the location, or return to the "Main Page".
Entering Location by Station ID
Using i!-Weather
To enter a location by Station ID:
1. Navigate to the "i!-Weather Select Location" page.
2. Select Enter Station ID.
3. Enter the 4-character Station ID.
4. Press Done.
This will return you to the "i!-Weather Select Location" page and display the corresponding city in
the "current location" field. From this page you can save the location, or return to the "Main Page".
Using the "Browse for Location" Feature
To use the "Browse for Location" feature:
1. Navigate to the "i!-Weather Select Location" page.
2. Select either Browse International or Browse US.
3. Select Country or State.
4. Press Select.
5. Select the desired city. This will display the Station ID used on the "Enter Station ID" page.
This will also return you to the "i!-Weather Select Location" page and display it in the "current
location" field. From this page you can save the location or return to the "Main Page".
From time to time the browsable list of cities may become outdated, or new cities may come online.
It may be necessary to update these lists. To update these lists:
i!-Weather
1. Navigate to the "i!-Weather Select Location" page.
2. Select Update Location Lists.
3. Select Start Download to begin downloading the files.
4. Upon completion of download select Close.
5
Using i!-Weather
Saving Presets
After you have selected a location, it is retrieved immediately. To save it as a preset:
1. On the "Select Location" Page, select Save.
2. Select the preset location to save to.
The selected preset will now display the city, state / city, country.
If you select a previously used preset while save is flashing, it will be overwritten.
Changing Temperature Units
To change temperature units:
1. Navigate to the "i!-Weather Select Location" page.
2. Select Fahrenheit or Celsius.
Next time a weather refresh occurs the units will be updated.
Changing Wind Speed Units
To change wind speed units:
1. Navigate to the "i!-Weather Select Location" page.
2. Select MPH (Miles Per Hour), KPH (Kilometers Per Hour) or Knots.
Next time a weather refresh occurs the units will be updated.
Changing Pressure Units
To change pressure units:
1. Navigate to the "i!-Weather Select Location" page.
2. Select Inches of Mercury, Millimeters of Mercury (torr), or Millibars.
Next time a weather refresh occurs the units will be updated.
Auto Refresh Interval Select
To select an auto refresh interval:
1. Navigate to the "i!-Weather Select Location" Page. At the bottom-center of the page you will
find the "Automatic Refresh" options.
2. Select desired auto refresh time interval.
3. If Off is selected, the weather can only be refreshed manually.
Auto Refresh refreshes weather data for the current weather location.
6
i!-Weather
Programming i!-Weather
i!-Weather is comprised of the following files:
i!-WeatherApplicationTest.axs (Application Test/Implementation)
i!-WeatherApplicationMod.tko (Application Module Definition)
i!-WeatherEngineTest.axs (Engine Test/Demo)
i!-WeatherEngineMod.tko (Engine Module Definition)
i!-WeatherApplicationTest.axs / i!-WeatherApplicationMod.tko
Define Module
The entire application functionality of i!-Weather is contained in the
i!-WeatherApplicationMod.tko file. This file is distributed in a pre-compiled format. To include
the module in a program, an instance of the module must be defined in the parent program.
(Normally,
DEFINE_MODULE statements are listed following the DEFINE_START section):
Programming i!-Weather
DEFINE_MODULE 'i!-WeatherApplicationMod' mdlWEATHER(
//i!-Weather Engine Devices
dvWEATHER_IP_CLIENT,
dvBROWSER_IP_CLIENT,
vdvWEATHER,
//i!-Weather User Interface
Device Arrays
dvUI,
dvDMS,
//i!-Weather DMS Keypad User
Interface Integer arrays
DMS_DISPLAY_FIELDS,
DMS_CONTROL_BUTTONS,
DMS_PRESET_BUTTONS,
//i!-Weather Touch Panel User
Interface Integer arrays
UI_CURRENT_WEATHER,
UI_FORCAST_DAY,
UI_FORCAST_CONDITION,
UI_FORCAST_HI,
UI_FORCAST_LO,
UI_FORCAST_COND_BMP,
UI_DISPLAY_FIELDS,
UI_UPDATE_WEATHER_DATA,
UI_WEATHER_BUSY_INDICATOR,
UI_PRESET_BUTTONS,
i!-Weather
Continued
7
Programming i!-Weather
Where: mdlWEATHER is a unique module name.
i!-WeatherApplicationMod.tko Module Parameters
dvWEATHER_IP_CLIENT The device of an available IP port on the NetLinx Master for updating
dvBROWSER_IP_CLIENT The device of an available IP port on the NetLinx Master for updating
vdvWEATHER An available virtual device to be used exclusively for the i!-Weather Application.
dvUI A device array for all touch panels sharing the i!-Weather system.
dvDMS A device array for all DMS Keypads sharing the i!-Weather system.
DMS_DISPLAY_FIELDS A variable text integer array for the Weather Data fields on the DMS keypads
DMS_CONTROL_BUTTONS An integer array controlling the i!-Weather system with DMS Keypads
DMS_PRESET_BUTTONS An integer array recalling i!-Weather location presets from the DMS Keypads
UI_FORMAT_BUTTONS,
UI_AUTO_REFRESH_BUTTONS,
UI_LIST_SELECT,
UI_LIST_CONTROL,
UI_LIST,
UI_LIST_STATION,
UI_BROWSE_METHOD,
UI_SCROLLBAR_LEVEL,
UI_LIST_INFO,
UI_INDEX_FILE_UPDATE,
UI_INDEX_FILE_UPDATE_PROGRESS
cWEATHER_DATA_ENCODED_BUFFER)
i!-Weather data.
i!-Weather city lists.
(Var Text Codes).
• 1 - Weather Location/Last Update
• 2 - Temperature
• 3 - Current Condition
(Forecast Day 1)
• 4 - Heat Index
• 5 - Wind Chill
• 6 - Humidity
• 7 - Dew Point
• 8 - Barometric Pressure
• 9 - Wind Speed / Direction
• 10 - Today's HI / Lo Temp
(Forecast Day 1)
(Channel Codes).
• 1 - REFRESH CURRENT WEATHER
• 2 - ABORT WEATHER REQUEST
(Channel Codes & Var Text Codes).
• 1 - WEATHER PRESET 1
• 2 - WEATHER PRESET 2
• 3 - WEATHER PRESET 3
• 4 - WEATHER PRESET 4
• 5 - WEATHER PRESET 5
• 11 - Forecast Day 2
• 12 - Forecast Day 3
• 13 - Forecast Day 4
• 14 - Forecast Day 5
• 15 - Forecast Day 2 HI / LO
• 16 - Forecast Day 3 HI / LO
• 17 - Forecast Day 4 HI / LO
• 18 - Forecast Day 5 HI / LO
• 19 - Forecast Day 2 Condition
• 20 - Forecast Day 3 Condition
• 21 - Forecast Day 4 Condition
• 22 - Forecast Day 5 Condition
• 6 - WEATHER PRESET 6
• 7 - WEATHER PRESET 7
• 8 - WEATHER PRESET 8
• 9 - WEATHER PRESET 9
• 10 - WEATHER PRESET 10
Continued
8
i!-Weather
Programming i!-Weather
i!-WeatherApplicationMod.tko Module Parameters (Cont.)
UI_CURRENT_WEATHER A variable text integer array for displaying weather data to touch panels.
(Var Text Codes)
• 1 - Current Location Display
• 2 - Current Temperature
• 3 - Current Condition
• 4 - Wind Speed & Direction
• 5 - Heat Index
• 6 - Wind Chill
UI_FORCAST_DAY A variable text integer array for displaying weather forecast data to touch
panels (Var Text Codes).
• 1 - Day 1 (Today)
•2 - Day 2
•3 - Day 3
UI_FORCAST_CONDITION A variable text integer array for displaying weather forecast data to touch
UI_FORCAST_HI A variable text integer array for displaying weather forecast data to touch
UI_FORCAST_LO A variable text integer array for displaying weather forecast data to touch
UI_FORCAST_COND_BMP A variable text integer array for displaying weather forecast data to touch
UI_DISPLAY_FIELDS An integer array for the touch panel display fields (Channel Codes & Var Text
UI_UPDATE_WEATHER_
DATA
UI_WEATHER_BUSY_
INDICATOR
panels (Var Text Codes).
• 1 - Day 1 (Today)
•2 - Day 2
•3 - Day 3
panels (Var Text Codes).
• 1 - Day 1 (Today)
•2 - Day 2
•3 - Day 3
panels (Var Text Codes).
• 1 - Day 1 (Today)
•2 - Day 2
•3 - Day 3
panels (Var Text Codes).
• 1 - Day 1 (Today)
•2 - Day 2
•3 - Day 3
Codes).
• 1 - Main Status Message
• 2 - Zip code Keypad Display
(Var Text Only)
• 3 - Station Text Field Display
(Var Text Only)
An integer array for the touch panels to request weather updates (Channel
Codes).
• 1 - UPDATE CURRENT WEATHER DATA
• 2 - UPDATE WEATHER DATA ZIP CODE
• 3 - UPDATE WEATHER DATA BY STATION ID
An integer array for i!-Weather Busy status (Channel Code).
• 1 - i!-Weather Busy Status
• 7 - Humidity
• 8 - Dew Point
• 9 - Barometric Pressure
• 10 - BITMAP: Wind Direction
• 11 - BITMAP: Current Condition
•4 - Day 4
•5 - Day 5
•4 - Day 4
•5 - Day 5
•4 - Day 4
•5 - Day 5
•4 - Day 4
•5 - Day 5
•4 - Day 4
•5 - Day 5
• 4 - User Config Keyboard Field 1
• 5 - User Config Keyboard Field 2
• 6 - Configuration Page Status
Message Field
i!-Weather
Continued
9
Programming i!-Weather
i!-WeatherApplicationMod.tko Module Parameters (Cont.)
UI_PRESET_BUTTONS An integer array for the i!-Weather location presets (Var Text & Channel
UI_FORMAT_BUTTONS An integer array for the i!-Weather conversion formats (Channel Codes).
UI_AUTO_REFRESH_
BUTTONS
UI_LIST_SELECT An integer array for the i!-Weather List Select Button (Channel Code).
UI_LIST_CONTROL An integer array for the i!-Weather list control buttons (Channel Code).
UI_LIST An integer array for the i!-Weather browse list fields (Var Text & Channel
UI_LIST_STATION An integer array for the i!-Weather browse list fields 2 (Var Text Codes).
UI_BROWSE_METHOD An integer array for the i!-Weather browse method buttons (Channel Codes).
UI_SCROLLBAR_LEVEL An integer array for the i!-Weather browse scroll bar (LEVEL Code).
Codes).
• 1 - PRESET 1
• 2 - PRESET 2
• 3 - PRESET 3
• 4 - PRESET 4
• 5 - PRESET 5
• 6 - PRESET 6
• 1 - DISPLAY SPEED IN MPH
• 2 - DISPLAY SPEED IN KM/HR
• 3 - DISPLAY SPEED IN KNOTS
• 4 – DISPLAY TEMP IN FARENHEIT
• 5 – DISPLAY TEMP IN CELSIUS
An integer array for the i!-Weather auto refresh buttons (Channel Codes).
• 1 - AUTO REFRESH: OFF
• 2 - AUTO REFRESH: twice /hour
(30 min)
• 1 - Select List Item
• 1 - Page Up
• 2 - Page Down
• 3 - Top of List
Codes).
• 1 - List Column 1, Item 1
• 2 - List Column 1, Item 2
• 3 - List Column 1, Item 3
• 4 - List Column 1, Item 4
• 1 - List Column 2, Item 1
• 2 - List Column 2, Item 2
• 3 - List Column 2, Item 3
• 4 - List Column 2, Item 4
• 1 - Browse US States list
• 2 - Browse International City list
• 3 - Browse Back to Previous list
• 1 – Scrollbar (LEVEL Code)
• 7 - PRESET 7
• 8 - PRESET 8
• 9 - PRESET 9
• 10 - PRESET 10
• 11 - SAVE PRESET
(Channel Code Only)
• 6 - DISPLAY PRESSURE IN
INCHES OF MERCURY
• 7 – DISPLAY PRESSURE IN TORR
(MILIMETERS OF MERCURY)
• 8 – DISPLAY PRESSURE IN
MILIBARS
• 3 - AUTO REFRESH: 6 times /day
(4 hr)
• 4 - AUTO REFRESH: twice /day
(12 hr)
• 4 - Bottom of List
• 5 - Scrollbar
• 5 - List Column 1, Item 5
• 6 - List Column 1, Item 6
• 7 - List Column 1, Item 7
• 8 - List Column 1, Item 8
• 5 - List Column 2, Item 5
• 6 - List Column 2, Item 6
• 7 - List Column 2, Item 7
• 8 - List Column 2, Item 8
Continued
10
i!-Weather
Programming i!-Weather
i!-WeatherApplicationMod.tko Module Parameters (Cont.)
UI_LIST_INFO An integer array for the i!-Weather browse info fields (Var Text Codes).
• 1 - List Displaying ## of ## Info Field
• 2 - Listbox Message Prompt Field
• 3 - Listbox Scrollbar Tooltip
UI_INDEX_FILE_UPDATE An integer array for the i!-Weather browse list update buttons (Channel Codes).
• 1 - Update List
• 2 - Cancel
• 3 - Start Download
UI_INDEX_FILE_UPDATE_
PROGRESS
cWEATHER_DATA_
ENCODED_BUFFER
An integer array for the i!-Weather browse list update fields (Variable Text).
•1 - Status Text
• 2 - Cancel/Close
A string for the module to place updated encoded weather data.
• 3 - Percentage VT
•4 - (LEVEL CODE) Progress Bar
Level ID
Devices
You need to make sure the
//i!-Weather Devices dvWEATHER_IP_CLIENT = 0:4:0
//INTERNET CONNECTION dvBROWSER_IP_CLIENT = 0:5:0
//INTERNET CONNECTION FOR CITY BROWSER dvMANAGEMENT = 8001:1:0
//PCLINK MANAGEMENT CONSOLE vdvWEATHER = 33001:1:0
//VIRTUAL DEVICE
DEVICE IDs are correct in the DEFINE_DEVICE section:
Constants
The following channels of the virtual device are the primary interface to i!-Weather. To set a format
option or to request weather data, your NetLinx code will generate a push to the virtual weather
device (
vdvWEATHER). The i!-Weather system will generate pushes to notify weather data retrieval
success or error.
The channel mappings are also listed in Channels.
The following table lists the constants contained in i!-Weather Application.
//i!-Weather Constants
//ENUMERATE VIRTUAL CHANNELS ON VIRTUAL WEATHER DEVICE
vCH_QUERY_BY_ZIPCODE = 1
vCH_QUERY_BY_STATION = 2
vCH_TEMP_FARENHEIT = 10
vCH_TEMP_CELSIUS = 11
vCH_SPEED_MPH = 13
vCH_SPEED_KPH = 14
vCH_SPEED_KNOTS = 15
vCH_PRESSURE_INCHES = 17
vCH_PRESSURE_TORR = 18
vCH_PRESSURE_MILIBAR = 19
vCH_ERROR_UNHANDLED_COMMAND = 248
vCH_ERROR_IP_CONNECT = 249
vCH_NOT_FOUND = 250
vCH_SYSTEM_DOWN = 251
vCH_ERROR = 252
vCH_SUCESS = 253
vCH_BUSY = 254
vCH_DEBUG = 255
i!-Weather
11
Programming i!-Weather
i!-WeatherEngineTest.axs / i!-WeatherEngineMod.tko
To create a custom NetLinx application for use with i!-Weather, you will need to include the
i!-WeatherEngine module in your program. The included i!-WeatherEngineTest.axs file
demonstrates how to integrate the i!-WeatherEngine module into a program.
Define Module
The i!-WeatherEngine module is distributed as a pre-compiled NetLinx module. To include the
module in a program, an instance of the module must be defined in the parent program. (Normally,
DEFINE_MODULE statements are listed following the DEFINE_START section):
DEFINE_MODULE 'i!-WeatherEngineMod' mdlWEATHER(dvIP_CLIENT,
vdvWEATHER,
chZIPCODE,
chSTATION,
chSTRUCTURE_ENCODED_BUFFER)
Where:
mdlWEATHER is a unique module name.
i!-WeatherEngineMod.tko Module Parameters
dvIP_CLIENT The device of an available IP port on the NetLinx Master.
vdvWEATHER An available virtual device to be used exclusively for the i!-Weather Application.
chZIPCODE A character buffer that contains the current zip code to retrieve weather data.
chSTATION A character buffer that contains the current station code to retrieve weather
chSTRUCTURE_ENCODED_
BUFFER
data.
A character buffer that contains the encoded weather data structure.
Devices
Make sure the device IDs are correct in the
//i!-Weather Devices
dvWEATHER_IP_CLIENT = 0:4:0 //INTERNET CONNECTION
dvTP = 128:1:0 //i!-Weather Touch Panel
dvBROWSER_IP_CLIENT = 0:5:0 //INTERNET CONNECTION FOR CITY BROWSER
vdvWEATHER = 33001:1:0 //VIRTUAL DEVICE
DEFINE_DEVICE section:
12
i!-Weather
Programming i!-Weather
Structures
The following structures contain all the detailed weather data elements retrieved by
i!-WeatherEngine module. Any of these elements can be accessed by your program after weather
data has been received and decoded.
//i!-Weather DATA STRUCTURE
STRUCTURE _sWEATHER
{
//Location
CHAR cREPORTING_STATE[20] //Weather Data Reporting State
CHAR cREPORTING_CITY[100] //Weather Data Reporting City
CHAR cCELL[10] //Cell
CHAR cZIPCODE[5] //Weather Zip Code
CHAR cCITY[100] //Weather City
CHAR cSTATE[20] //Weather State
CHAR cSTATION[10] //Weather Station
CHAR cSUNRISE[15] //Sunrise Time (In GMT)
CHAR cSUNSET[15] //Sunset Time (In GMT)
//Weather Data
CHAR cLAST_UPDATE[20] //Last Date & Time of Current Weather Update (In GMT)
CHAR cLAST_UPD_DATE[15] //Last Date of Current Weather Update
CHAR cLAST_UPD_TIME[15] //Last Time of Current Weather Update (In GMT)
CHAR cTEMP[10] //Current Temp String
SINTEGER nTEMP //Current Temp Value
CHAR cHUMIDITY[10] //Current Humidity String
INTEGER nHUMIDITY //Current Humidity Value
CHAR cHEAT_INDEX[10] //Current Heat Index String
SINTEGER nHEAT_INDEX //Current Heat Index Value
CHAR cWIND_CHILL[10] //Current Wind Chill String
SINTEGER nWIND_CHILL //Current Wind Chill Value
CHAR cDEW_POINT[10] //Current Dew Point String
SINTEGER nDEW_POINT //Current Dew Point Value
CHAR cWIND_DIRECTION[20] //Current Wind Direction String
INTEGER nWIND_DIRECTION //Current Wind Direction Value
CHAR cWIND_SPEED[15] //Current Wind Speed String
INTEGER nWIND_SPEED //Current Wind Speed Value
CHAR cBAROMETER[20] //Current Barometric Pressure String
FLOAT fBAROMETER //Current Barometric Pressure Value
CHAR cCONDITION[20] //Current Condition String
INTEGER nCONDITION //Current Condition Value
//Forecasting
CHAR cFORECAST_DATE[20] //Forecast Start Date
CHAR cFC_HI[5][10] //Forecast Day Hi Temp String
SINTEGER nFC_HI[5] //Forecast Day Hi Temp Value
CHAR cFC_LO[5][10] //Forecast Day Lo Temp String
SINTEGER nFC_LO[5] //Forecast Day Lo Temp Value
CHAR cFC_CONDITION[5][15] //Forecast Day Condition String
INTEGER nFC_CONDITION[5] //Forecast Day Condition Value
CHAR cFC_DATE[5][15] //Forecast Day Date
INTEGER nFC_DAY_OF_WEEK[5] //Forecast Day Day of Week Index
CHAR cFC_DAY_OF_WEEK[5][10] //Forecast Day Day of Week String
//General
INTEGER nQUERY_SUCCESSFUL //Query Success or Fail
CHAR cBUFFER[65000] //XML Buffer
CHAR cGETZIPCODE[5] //ZIP Code to query for
CHAR cGETSTATION[10] //STATION Code to query for
INTEGER nQUERY_METHOD //Query Weather Method
CHAR cLAST_QUERY_DATE[15] //Last date weather was queried
CHAR cLAST_QUERY_TIME[15] //Last time weather was queried (In NetLinx Time)
INTEGER bDEMO_MODE //Data Received is in Demo Mode
INTEGER nMESSAGE_TYPE //Message Type received in weather packet
CHAR cMESSAGE[250] //Message Text received in weather packet
INTEGER nDAYS_REMAINING //Days in weather service subscription
remaining
CHAR cERROR_CODE[3] //Error Codes
i!-Weather
}
13
Programming i!-Weather
Request New Weather Data
To request new weather data, your program simply needs to specify the zip code or station code,
and then generate a
i!-WeatherEngine module receives the request notification, attempts to connect the weather
provider, and gets new weather data. An example is provided below:
PUSH notification on the virtual weather device (vdvWEATHER). The
//----------------------------------------------------------------------// i!-Weather Update Weather Data By Zip Code for: New York, New York.
//---------------------------------------------------------------------- BUTTON_EVENT[dvTP,1]
{
PUSH:
{
//Set ZIP Code
chZIPCODE = "'10101'"
//Get Weather Data By ZIP Code
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_QUERY_BY_ZIPCODE,5)
}
}
//----------------------------------------------------------------------// i!-Weather Update Weather Data By Station Code for: Dallas, Texas
//---------------------------------------------------------------------- BUTTON_EVENT[dvTP,2]
{
PUSH:
{
//Set Station Code
chStation = "'KDFW'"
//Get Weather Data By Station Code
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_QUERY_BY_STATION,5)
}
}
Weather data can also be requested via the virtual weather device command
interface.
14
i!-Weather
Programming i!-Weather
Receive New Weather Data
Once the i!-WeatherEngine module receives new weather data, it will send a notification on the
virtual weather device. Upon receiving this notification, your program can take the
chSTRUCTURE_ENCODED_BUFFER and decode it using the STRING_TO_VARIABLE function to
your local weather structure. An example is provided below:
//CHECK IN STRUCTURE TO SEE IF QUERY WAS SUCCESSFUL
IF(sWEATHER.nQUERY_SUCCESSFUL)
{
SEND_STRING 0 , "' '"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"' It is currently [',sWEATHER.cTEMP,'] in the city of
[',sWEATHER.cCITY,']'"
SEND_STRING 0 ,"' with conditions of [',sWEATHER.cCONDITION,']'"
SEND_STRING 0 ,"' The winds are at [',sWEATHER.cWIND_SPEED,'] in the
[',sWEATHER.cWIND_DIRECTION,'] direction'"
SEND_STRING 0 ,"' Reported By [',sWEATHER.cSTATION,'] at
[',sWEATHER.cLAST_UPDATE,']'"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 , "' '"
}
}
}
Changing Temperature, Pressure, & Speed Formats
The i!-WeatherEngine module can return weather data in multiple conversion formats.
i!-WeatherEngine module exposes these format controls via the virtual weather device channel
(see Channels).
Temperature, Pressure, & Speed Formats
Temperature • Fahrenheit (°F)
• Celsius (°C)
Pressure • Inches of Mercury (inches)
• Millimeters of Mercury (torr)
• Millibars (millibar)
Speed • Miles per hour (MPH)
• Kilometers per hour (KPH)
• Knots (KNOTS)
A source code example is provided below to demonstrate how to set a particular format:
//Set i!-Weather Temperature Format to i!-WeatherEngine
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_TEMP_FARENHEIT,5)
//Set i!-Weather Speed Format
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_SPEED_MPH,5)
//Set i!-Weather Pressure Format
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_PRESSURE_INCHES,5)
i!-Weather
15
Programming i!-Weather
A source code example is provided below to demonstrate how to read a particular format:
Weather data formats can also be changed via the virtual weather device command
interface (Refer to the Commands section on page 19).
//Read i!-Weather Temperature Format from i!-WeatherEngine
IF([vdvWEATHER,VIRTUAL_CHANNEL_TEMP_FARENHEIT])
{
nTEMP_FORMAT = TEMP_FARENHEIT
}
IF([vdvWEATHER,VIRTUAL_CHANNEL_TEMP_CELSIUS])
{
nTEMP_FORMAT = TEMP_CELSIUS
}
16
i!-Weather
Channels
i!-Weather Virtual Channel Map
//Request Channels (DO_PUSH)
VIRTUAL_CHANNEL_QUERY_BY_ZIPCODE = 1
VIRTUAL_CHANNEL_QUERY_BY_STATION = 2
//Status & Request Channels
VIRTUAL_CHANNEL_TEMP_FARENHEIT = 10
VIRTUAL_CHANNEL_TEMP_CELSIUS = 11
VIRTUAL_CHANNEL_SPEED_MPH = 13
VIRTUAL_CHANNEL_SPEED_KPH = 14
VIRTUAL_CHANNEL_SPEED_KNOTS = 15
VIRTUAL_CHANNEL_PRESSURE_INCHES = 17
VIRTUAL_CHANNEL_PRESSURE_TORR = 18
VIRTUAL_CHANNEL_PRESSURE_MILIBAR = 19
//Debug Channel
VIRTUAL_CHANNEL_DEBUG = 255
//Notification Channels
Programming i!-Weather
VIRTUAL_CHANNEL_ERROR_UNHANDLED_COMMAND = 248
VIRTUAL_CHANNEL_ERROR_IP_CONNECT = 249
VIRTUAL_CHANNEL_ERROR_NOT_FOUND = 250
VIRTUAL_CHANNEL_ERROR_SYSTEM_DOWN = 251
VIRTUAL_CHANNEL_ERROR = 252
VIRTUAL_CHANNEL_SUCESS = 253
//Status Only Channels:
VIRTUAL_CHANNEL_BUSY = 254
Request Channels
Sending a
DO_PUSH on a request channel notifies the i!-WeatherEngine to process the request.
//Notify i!-WeatherEngine to retrieve new weather data by ZIP Code
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_QUERY_BY_ZIPCODE,5)
Status & Request Channels
The status of the channel can be read to determine the state of the i!-WeatherEngine option.
//Determine if the i!-WeatherEngine Speed Format is set to MPH
IF([vdvWEATHER,VIRTUAL_CHANNEL_QUERY_BY_ZIPCODE])
nSPEED_FORMAT = SPEED_MPH
Sending a DO_PUSH on a request channel notifies the i!-WeatherEngine to process the request.
//Set i!-WeatherEngine to MPH Speed Format
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_SPEED_MPH,5)
Debug Channels
i!-Weather
The status of the debug channel can be read or set to enable/disable i!-WeatherEngine debug
messaging.
//Turn i!-WeatherEngine Debug Messages ON
ON[vdvWEATHER,VIRTUAL_CHANNEL_DEBUG]
17
Programming i!-Weather
Notification Channels
The i!-WeatherEngine notification channels are used by the i!-WeatherEngine to send a notification
to the parent program that information has been received, or an error has occurred. Upon detecting
a
PUSH event on these notification channels, your program can decode the weather data structure, or
process the error received.
//i!-Weather Error Channels
DEVCHAN dcWEATHER_ERROR[]=
{
{ vdvWEATHER,VIRTUAL_CHANNEL_ERROR_UNHANDLED_COMMAND },
{ vdvWEATHER,VIRTUAL_CHANNEL_ERROR_IP_CONNECT },
{ vdvWEATHER,VIRTUAL_CHANNEL_ERROR_NOT_FOUND },
{ vdvWEATHER,VIRTUAL_CHANNEL_ERROR },
{ vdvWEATHER,VIRTUAL_CHANNEL_ERROR_LOGON_FAIL }
}
//---------------------------------------------------------------------------// i!-Weather New Data Recevied----------------------------------------------//----------------------------------------------------------------------------
//i!-Weather Engine Notified Us That New Data is Ready
BUTTON_EVENT[vdvWEATHER,VIRTUAL_CHANNEL_SUCESS]
{
PUSH:
{
STACK_VAR
VOLATILE SINTEGER siRESULT
//DECODE NEW STRUCTURE DATA
siRESULT = STRING_TO_VARIABLE(sWEATHER,chSTRUCTURE_ENCODED_BUFFER,1)
//CHECK IN STRUCTURE TO SEE IF QUERY WAS SUCCESSFUL
IF(sWEATHER.nQUERY_SUCCESSFUL)
{
SEND_STRING 0 , "' '"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"' It is currently [',sWEATHER.cTEMP,'] in the city of
[',sWEATHER.cCITY,']'"
SEND_STRING 0 ,"' with conditions of [',sWEATHER.cCONDITION,']'"
SEND_STRING 0 ,"' The winds are at [',sWEATHER.cWIND_SPEED,'] in the
[',sWEATHER.cWIND_DIRECTION,'] direction'"
SEND_STRING 0 ,"' Reported By [',sWEATHER.cSTATION,'] at
[',sWEATHER.cLAST_UPDATE,']'"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 ,"'===================================================='"
SEND_STRING 0 , "' '"
}
}
}
//---------------------------------------------------------------------------// i!-Weather Error Handling-------------------------------------------------//----------------------------------------------------------------------------
//i!-Weather Engine Notified Us Of An Error
BUTTON_EVENT[dcWEATHER_ERROR]
{
PUSH:
{
//Interpret i!-WeatherEngine Error
WEATHER_ERROR(BUTTON.INPUT.CHANNEL)
}
}
18
i!-Weather
Programming i!-Weather
Status Only Channel
The status of these i!-WeatherEngine virtual channels can be read, but are only set by the
i!-WeatherEngine.
Commands
i!-Weather Virtual Device SEND_COMMANDS
The following
SEND_COMMANDS can be sent to the i!-WeatherEngine virtual device (vdvWEATHER)
either in the NetLinx code or via a terminal session. A response string will be generated back on the
i!-WeatherEngine virtual device (
vdvWEATHER).
COMMANDS RECEIVED STRING RESPONSES
Weather Temperature Format:
TEMPERATURE-CELSIUS TEMPERATURE-CELSIUS
TEMPERATURE-FARENHEIT TEMPERATURE-FARENHEIT
TEMPERATURE? TEMPERATURE-CELSIUS
TEMPERATURE-FARENHEIT
Weather Speed Format:
SPEED-MPH SPEED-MPH
SPEED-KPH SPEED-KPH
SPEED-KNOTS SPEED-KNOTS
SPEED? SPEED-MPH
SPEED-KPH
SPEED-KNOTS
Weather Pressure Format:
PRESSURE-INCHES PRESSURE-INCHES
PRESSURE-TORR PRESSURE-TORR
PRESSURE-MILIBAR PRESSURE-MILIBAR
PRESSURE? PRESSURE-INCHES
PRESSURE-TORR
PRESSURE-MILIBAR
Query for Weather Data:
WEATHER BY ZIP - [Zipcode] WEATHER BY ZIP - [Zipcode]
WEATHER BY STATION - [Station] WEATHER BY STATION - [Station]
REFRESH WEATHER REFRESH WEATHER
i!-Weather
COMMANDS RECEIVED STRING RESPONSES
Debug Messages:
DEBUG-ON DEBUG-ON
DEBUG-OFF DEBUG-OFF
Program Information:
ENGINE VERSION? ENGINE VERSION-[Engine Version]
ENGINE NAME? ENGINE NAME-[Engine Name]
Unhandled Command:
[UNHANDLED COMMAND]-[Command Received]
Continued
19
Programming i!-Weather
Examples
To retrieve New York’s weather by zip code:
To set the i!-WeatherEngine speed format to knots:
To request the i!-WeatherEngine’s temperature format:
The i!-WeatherEngine will respond by sending a STRING on the vdvWEATHER device:
Any command unrecognized by the i!-WeatherEngine module will send an error notification by a
DO_PUSH on VIRTUAL_CHANNEL_ERROR_UNHANDLED_COMMAND (248), and it will return a
SEND_STRING to the vdvWEATHER device. Below is the actual code that is executed when the
command received is not recognized:
SEND_COMMAND vdvWEATHER," ’WEATHER BY ZIP-10101’ "
SEND_COMMAND vdvWEATHER," ’SPEED-KNOTS’ "
SEND_COMMAND vdvWEATHER," ’TEMPERATURE’ "
SEND_STRING vdvWEATHER, " ‘TEMPERATURE-FARENHEIT’ "
//PULSE VIRTUAL DEVICE ERROR STATUS
DO_PUSH_TIMED(vdvWEATHER,VIRTUAL_CHANNEL_ERROR_UNHANDLED_COMMAND,5)
//UNHANDLED COMMAND
SEND_STRING vdvWEATHER, "'[UNHANDLED COMMAND] -',DATA.TEXT"
//DEBUG
IF([vdvWEATHER,VIRTUAL_CHANNEL_DEBUG])
SEND_STRING 0, "'UNHANDLED COMMAND: [',DATA.TEXT,']'"
20
i!-Weather
Appendix A
Error Codes
The i!-Weather data structure returned contains an ERROR_CODE field. This field can help
determine if an error was encounted and whay type of error it is.
Error Codes:
E01 - Subscription Invalid (Expired)
E02 - Zip Not Found
E03 - Station Not Found
E04 - System Status is Down
I01 - System Maintenance
W01 - Subscription Expiring Soon
W02 - Unregistered Master (DEMO MODE)
Appendix A
The first byte in the Error Code detmines the error type.
'E' : Error - no not process weather data.
'I' : Informaion
'W' : Warning
Additional textual information will also be returned to the MESSAGE field of the i!-Weather data
structure.
!-Weather
1
Appendix A
2
i!-Weather
Appendix A
i!-Weather
3
AMX reserves the right to alter specifications without notice at any time.
DALLAS, TEXAS • LOS ANGELES, CALIFORNIA • MEXICO CITY, MEXICO • ONTARIO, CANADA • PHILADELPHIA, PENNSYLVANIA • SHANGHAI, CHINA • SINGAPORE • TAMPA, FLORIDA • WESTERLO, BELGIUM • YORK, ENGLAND
3000 RESEARCH DRIVE, RICHARDSON, TX 75082 USA • 800.222.0193 • 469.624.8000 • 4 69-624-7153 fax • 800.932.6993 techni cal support • www.amx.com
2005 AMX Corporation. All rights reserved. AMX, the AMX logo, the building icon, th e home icon, and the light bulb icon are all trademarks of AMX Corporation.
©
033-004-2618 8/05
AMX reserves the right to alter specifications without notice at any time. *In Canada doing business as Panja Inc.
Loading...