User manual AMX I!-SCHEDULE

instruction manual i!-Schedule i n t e g ra t i o n ! S o l u t i o n s Software Limited Agreement 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. AMX Corporation disclaims all other warranties, either expressed or implied, including, but 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. In no event shall AMX Corporation be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use this AMX 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. 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!-Schedule ......................................................................................................... 2 Using i!-Schedule .....................................................................................................3 Dynamic Events ................................................................................................................ 4 Schedule Persistence........................................................................................................ 7 Time Protocols .................................................................................................................. 8 Programming i!-Schedule ......................................................................................11 Channels ......................................................................................................................... 11 Levels .............................................................................................................................. 11 Send_Commands............................................................................................................ 12 Strings ............................................................................................................................. 13 Modules........................................................................................................................... 14 i!-ScheduleEngineMod Module .............................................................................................. 14 i!-ScheduleMod Module ......................................................................................................... 17 i!-Schedule i Table of Contents ii i!-Schedule Introduction Introduction i!-Schedule is an application that allows you to schedule NetLinx events directly from a touch panel connected to a NetLinx control system. i!-Schedule provides a user interface to schedule up to 240 NetLinx events to run on a repeating or non-repeating basis. i!-Schedule also provides a scheduling engine that triggers each event at the appropriate time and reschedule repeating events. Two scheduling modules are available with i!-Schedule. i!-ScheduleEngineMod is the scheduling engine module only. This module has no user interface and can be used for fixed events that do not need to be edited by the user. Use this module if you do not want a user interface for scheduling. i!-ScheduleMod includes the functionality of the engine module and provides a user interface where the user can edit the scheduling of events. Use this module if you want a user interface for scheduling. You do not need to include the i!-ScheduleEngineMod if you use this module. Supported Operating Systems Windows 95®/98® (with at least 48 MB of installed memory) Windows NT 4.0® Workstation or Server (service pack 6 B or greater, with at least 64 MB of installed memory) Windows 2000® Professional or Server (running on a Pentium 266 MHZ processor (minimum requirement); 300 MHZ 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.) Minimum PC Requirements Windows-compatible mouse (or other pointing device) At least 5 MB of free disk space (150 MB recommended) SVGA monitor, with a minimum screen resolution of 800 x 600 A Network adapter i!-Schedule 1 Introduction Installing i!-Schedule 1. In Explorer, double-click i!-ScheduleSetup.exe from the directory window where you downloaded the i!-PCLinkMediaPlayer install program. 2. After reading the License Agreement, select I Agree and Next to proceed. 3. The Welcome To i!-Schedule Setup dialog opens, reminding you to close all Windows programs before going any further. Click Next to proceed. 4. In the i!-Schedule Select Components dialog, select which example programs you would like to install. 5. In the Select i!-Schedule Install Location dialog, use the Browse button to navigate to a directory other than the default install directory, if desired. Click Next. 6. In the i!-Schedule Shortcut Creation dialog, select Install Shortcut Icons for the installed components on your desktop, if desired. 7. Click Next in the Start i!-Schedule Installation dialog to install the selected components. 8. The program prompts you to restart your system to complete the installation. 2 i!-Schedule Using i!-Schedule Using i!-Schedule Little work is required to add i!-Schedule to your existing NetLinx code. i!-Schedule is implemented as a NetLinx module so you need to add the module definition and all it's parameters to your code. You must also define the NetLinx events you would like to schedule. In order to use i!-Schedule, you will need to program and define a series of events in the NetLinx control system. The key to the scheduling engine is the virtual device, vdvSchEvents. You must support the events you want scheduled using this virtual device. Think of the virtual device, vdvSchEvents, as a touch panel. Normally, you would write your NetLinx program to respond to certain push channel from a touch panel; i!-Schedule is exactly the same. Let's say you want the user to be able to schedule when the outdoor lights turn on and when they turn off. Imagine you have two touch panel buttons that do these functions. You would write code that responds to the pushes; turning the lights on and then off. (Let's use relays for lighting control to simplify the example): BUTTON_EVENT[TP,1] { PUSH: { ON[RELAY,1] } } BUTTON_EVENT[TP,2] { PUSH: { OFF[RELAY,1] } } (* Outdoor Lights On *) (* Outdoor Lights Off *) To schedule these events using i!-Schedule, we write the same code substituting the touch panel device for our scheduling virtual device: BUTTON_EVENT[vdvSchEvents,1] { PUSH: { ON[RELAY,1] } } BUTTON_EVENT[vdvSchEvents,2] { PUSH: { OFF[RELAY,1] } } (* Outdoor Lights On *) (* Outdoor Lights Off *) When the scheduling engine detects that the user has programmed the lights on event to run at a certain time and that schedule time has occurred, i!-Schedule will "push" the button on the virtual device just like a user pushes a button on a touch panel. There is now only one thing left to do: tell the user which events are which. In order to expose an event for scheduling via i!-Schedule, you need to support the programming for the event (as we have just seen) tell i!-Schedule what that event is. i!-Schedule allows a user to scroll through a list of events and edit the time which it runs. In order to associate an item in the list i!-Schedule 3 Using i!-Schedule with a button/channel number, you must tell i!-Schedule what each channel you have programmed can do. To specify the name of an event, you need to send a command to the scheduling virtual device describing the name of a given channel code. To specify the names of the commands in the above example, you would add some code like this: DATA_EVENT[vdvSchEvents] { ONLINE: { (* Setup events *) (* Outdoor Lights On *) SEND_COMMAND vdvSchEvents,"'SET NAME-1,Outdoor Lights Off '" (* Outdoor Lights Off *) SEND_COMMAND vdvSchEvents,"'SET NAME-2,Outdoor Lights Off'" } } Once i!-Scheduling receives these commands, it will show the user the two events in the main event list, sorted in alphabetical order, and allow the user to schedule these events. Whenever the user schedules the "Outdoor Lights On" event to run at a certain time and that time occurs, the scheduling engine will push button one and your code can turn the lights on. Each event can be programmed to occur on a repeating or non-repeating basis running at a single time per day. Additionally, each event can have a start and end time. Events do not have end dates so they can only span a 24-hour period; however, that 24-hour period can span 2 dates by specifying an end time less than a start time. For instance, if a user schedules an event to start at sunset and end at sunrise, i!-Schedule will start the event at sunset of the scheduled day and stop the event at sunrise of the following day. In addition to specifying the name of an event, you can also program the date and time when the event should occur. The scheduled virtual device supports a variety of commands to set and query the values of the names, dates and times for each event. See the Send_Commands section on page 12 for more details. Dynamic Events So far, i!-Schedule has handled simple fixed events where each event provides a single function and can be scheduled only once for each day. Some scheduling applications require dynamic events where the user can add and delete events on the fly. i!-Schedule has a provision to handle this case. Let's look at the programming side of i!-Schedule for a moment. For every event that needs to be scheduled, your program must contain a BUTTON_EVENT to handle the push and/or release of that event. To provide dynamic events, you must provide dynamic BUTTON_EVENTS. Let's say you want to schedule a new event using i!-Schedule while the program is running. This seems easy, you simply add the send command to name the new event: SEND_COMMAND vdvSchEvents,"'SET NAME-14,My New Event'" The name "My new Event" appears in the event list, the user schedules it to occur at 5:00 on Saturdays and everything is fine. Now Saturday 5:00 rolls around, and the scheduling engine pushes button 14 for this event to occur. Since you did not re-compile and download your program after the user scheduled the event, you would have had to add code for button event 14 prior to the user scheduling the event! So the problem is: how do you program for an unknown number of events that has not been scheduled? Additionally, since you did not define these events up front, 4 i!-Schedule Using i!-Schedule how is the distinction made between event 14 and the next event, 15 (they don't do the same thing right?). One word: Event Parameters. Event parameters provide a way to allow dynamic events to be added and deleted during run-time. The Send_Command to the scheduling virtual device allows you to add and delete events while i!-Schedule is running. Parameters will allow you to add additional information to each event to be stored by i!-Schedule and recalled at the time the event is fired. Let's take a simple example: a VCR record timer. Now let's make it a bit more complicated: How about a VCR record timer for 5 VCRs. Now, to program this in NetLinx is pretty easy, if you know the VCR number and the channel number the user whishes to record. Consider this code: BUTTON_EVENT[dcVCRRecordEvents] (* VCR Recording *) { PUSH: { (* Assume we are able to obtain the VCR Number and the Channel Number *) (* And we store them in nVCRNumber and nChannelNumber *) Switch (nVCRNumber) { Case 1: dvVCRDev = dvVCR1 Case 2: dvVCRDev = dvVCR2 Case 3: dvVCRDev = dvVCR3 Case 4: dvVCRDev = dvVCR4 Case 5: dvVCRDev = dvVCR5 } Send_Command dvVCRDev,"'CH',ITOA(nChannelNumber)" Send_Command dvVCRDev,"'SP',8" (* Record *) } RELEASE: { Switch (nVCRNumber) { Case 1: dvVCRDev = dvVCR1 Case 2: dvVCRDev = dvVCR2 Case 3: dvVCRDev = dvVCR3 Case 4: dvVCRDev = dvVCR4 Case 5: dvVCRDev = dvVCR5 } Send_Command dvVCRDev,"'SP',2" (* Stop *) } } Easy, right? If we have the VCR number and Channel number, we can easily write a BUTTON_EVENT handler for any number of buttons to start recording a certain channel on any number of VCR's for any channel number. Therefore, the VCR number and the Channel number will need to be event parameters. Now, i!-Schedule is written to be a universal scheduling engine which means it has no idea that you are interested in a VCR and Channel number. If i!-Schedule were written to understand these parameters, then it would not be very useful for automatically dialing a phone number, since the phone number could not be stored in either the VCR number location or the Channel number location. And, it would be confusing to the user to say the least! To solve this problem, i!-Schedule can support 8 number or value parameters and 8 string parameters per event. You may use these parameters in any way you see fit. To implement a parameter for a given event, you will need to collect the information, such as the VCR number and Channel number, from the user and tell i!-Schedule to store these values along with the event. In order to integrate the editing of the event and the editing of the parameters, each i!-Schedule 5 Using i!-Schedule event has a Parameters page and Parameter Text associated with it. When the user edits a given user and the event has a Parameter Page associated with it, a button labeled "Parameters" appears on the editing page. If the user presses it, i!-Schedule generates a PAGE- command to the touch panel. Optionally, if the Parameter Text option is set, the button displays this text instead of the default "Parameters". Now, this is where your programming comes into play. The user has now been flipped to the Parameter Page where they expect to event parameters. You must implement the code to allow the user to enter the parameters. For our example, we would implement some BUTTON_EVENT handlers that allow the user to select from 1 of 5 VCR's and select a channel number. Once you have gathered all the information needed to select what and where to record, you need to tell the i!-Schedule module to store the parameters for you. For VCR numbers and Channel numbers, it would be appropriate to use our value parameters to store this information. Use the Value Parameter number 1 to store the VCR number and Value Parameter number 2 to store the channel number. In practice, your page will probably have an OK and Cancel button. The Cancel would simply return them to the scheduling edit page while the OK button would return them to the scheduling edit page and update the parameters. You could send the new parameters values to i!-Schedule as the user selects them, but there would be no way to "undo" them should they decide to cancel. With that in mind, we would update i!-Schedule with the new parameters value on an OK button handler like this: BUTTON_EVENT[Tp,11] (* OK *) { PUSH: { (* VCR Number *) SEND_COMMAND vdvSchEvents,"'SET VPARAM-14,1,',ITOA(nVCRNumberFromUser)" (* Channel Number *) SEND_COMMAND vdvSchEvents,"'SET VPARAM-14,2,',ITOA(nChannelNumberFromUser)" } } Now, you do not need to remember which VCR number or Channel number was selected for this event, i!-Schedule does that for you. To complete our code, we need to retrieve the parameters from i!-Schedule when the event is triggered. i!-Schedule posts the string parameters, strings and value parameters as levels prior to firing the event. When button event 14 is fired by i!-Schedule, the VCR number and Channel number will be waiting on levels 1 and 2 to use. Add this code: DEFINE_VARIABLE Volatile Integer nVCRNumberParam Volatile Integer nChannelNumberParam DEFINE_START Create_Level vdvSchEvents,1,nVCRNumberParam Create_Level vdvSchEvents,2,nChannelNumberParam BUTTON_EVENT[dcVCRRecordEvents] { PUSH: { Switch (nVCRNumberParam) { Case 1: dvVCRDev = dvVCR1 Continued (* VCR Recording *) 6 i!-Schedule Using i!-Schedule Case Case Case Case 2: 3: 4: 5: dvVCRDev dvVCRDev dvVCRDev dvVCRDev = = = = dvVCR2 dvVCR3 dvVCR4 dvVCR5 } Send_Command dvVCRDev,"'CH',ITOA(nChannelNumberParam)" Send_Command dvVCRDev,"'SP',8" (* Record *) } RELEASE: { Switch (nVCRNumberParam) { Case 1: dvVCRDev = dvVCR1 Case 2: dvVCRDev = dvVCR2 Case 3: dvVCRDev = dvVCR3 Case 4: dvVCRDev = dvVCR4 Case 5: dvVCRDev = dvVCR5 } Send_Command dvVCRDev,"'SP',2" (* Stop *) } } i!-ScheduleModTest2.axs provides a template for building you own application with dynamic events. Schedule Persistence i!-Schedule stores the schedule information in a file called Schedule.bin located in the doc:\user\schedule directory. All event information is stored in this file and recalled during power up. Any event scheduled by the user is stored during a power cycle and will not be lost. This file is only read during start-up. The scheduling engine always attempts to read the file on start up. If you are loading a new program containing scheduling into an old master that used to have scheduling, you should use FTP to browse the NetLinx Master's file system and delete the old schedule file. Otherwise, the old scheduling information is loaded in addition to any new scheduling information you have. i!-Schedule 7 Using i!-Schedule Time Protocols i!-Schedule supports four time protocols to synchronize the NetLinx Master's clock with and Internet timeserver: DayTime (13/udp, 13/tcp) Time (37/udp, 37/tcp) SNTP (123/udp) SNTP Broadcast (123/udp). Only one of the protocols can be active at a time. The DayTime protocol is based on RFC 867 and can provide Day and Time information. While the Daytime protocol can provide accurate day and time formation, RFC867 does not specify the actual format for the message. This limits the usefulness of the DayTime protocol with one exception: The National Institute of Standards and Technology operate a series of Time Servers, known as the NIST Internet Time Servers, that provide a DayTime message of fixed format than can be reliably parsed and can be used to accurately set the Day and Time of any clock. While these Time Servers reside in the US, the Day and Time of the servers is supplied in Universal time Coordinates or UTC. The Time Management portion of i!-Schedule is capable of connecting to any of the NIST Time servers and calculating the correct time and date for any location in the world. The Time Manager also supports the standard NIST server list, a file called nist-srv.lst, and will attempt to read this file from doc:\user\time. You may get a copy of this file from the /pub directory on any NIST timeserver. If this file cannot be found on the NetLinx file system, a default list of NIST servers will be used instead. See the NIST home page at http://www.boulder.nist.gov/timefreq/ index.html for more information on NIST Time service or Servers. Additionally, the Time Manager in i!-Schedule has also been written to use a "popular" DayTime format which is used by the Linux implementation of DayTime and Tardis, a popular time synching software. Although not specified, the Date and Time of this format does not specify the time zone and is assumed to be local. If you select DayTime protocol and select a server that is running DayTime and the format, specifically "DayOfWeek Month Day HH:MM:SS Year", can be found, no time offset will be added. If you have chosen this combination and find that the time does not synchronize to the correct time, choose another protocol or server. The Time protocol, based on RFC868, is a very simple straightforward time protocol providing the number of seconds that have transpired since January 1, 1900 UTC. The current Date and time can easily be calculated form this value. However, the number of seconds in this protocol is provides as a 32 bit unsigned number, which can represent a maximum value of 4294967295 (2 ^ 32). 4294967295 seconds from January 1st, 1900 occurs on Feb 7, 2036 at 6h 28m 16s. Therefore, this protocol can only accurately represent time before this date. Many of the NIST servers, as well and many Unix, Linux and Windows programs, can provide this time protocol, and it can be reliably used up until Feb 7, 2036. The last two Time protocols share the same message format but differ in their connection scheme. SNTP stands for Simple Network Time Protocol, a subset of NTP or Network Time Protocol, is based on RFC2030. It is a highly accurate measure of time and date and also measures Date and Time as the number of seconds from January 1st 1900. However, the number of seconds is provided in two parts: the number of whole seconds, with a range of 4294967295 (2^32) and fractions of a second also with a range of 4294967295 (2^32). The Netlinx master is not able to take advantage of 8 i!-Schedule Using i!-Schedule the fractions of a second offered by SNTP and therefore has the same accuracy as the Time protocol but SNTP also provides information about the integrity of the data supplied. This makes the SNTP protocol more accurate than the Time protocol. RFC2030, which defines the SNTP protocol, has also made a provision for Dates and Time after Feb 7, 2036. SNTP message can represent a Date and Time accurately until some time in the year 2104. Most of the NIST servers also provide Date and Time information in SNTP format. The difference between SNTP (123/udp), SNTP Broadcast (123/udp) is simply one of connection. It is possible to configure an SNTP server to broadcast the time in SNTP format to an entire network or node of a network. The Time Manager in i!-Schedule can be configured to actively retrieve the time in SNTP format from an SNTP server (protocol number 3) or simply listen for SNTP broadcasts on the network (protocol number 4). Although SNTP broadcasting may sound like an ideal solution for Date and Time information, the Network Administrator should make this decision. So why did we implement so many time protocols? Which timeserver protocol should you use? This depends on your Network configuration and your Network administrator. It is probable that your network already provides some form of Date and Time information, and that information is probably obtained from a highly accurate source. Most installations of i!-Schedule should make use of the time server protocols already available on your network. To find out if such services are available on your network, contact you Network Administrator. You might also like to look at commercially available software for Time synchronization. The Time Manager in i!-Schedule has been tested with Tardis 2000 (http://www.kaska.demon.co.uk) which can provide all versions of the Time protocols above, including SNTP broadcasting. If you are interested in synchronizing many computers as well as i!-Schedule, Tardis 2000 provides a great solution. For simple Date Time synchronization, select DayTime (value=1) and leave the server field blank. A default NIST server will be selected. Most NIST servers supply all three formats of Date and Time protocols but the DayTime is the most common protocol provided by NIST servers. The Time Manager portion of i!-Schedule will synchronize the NetLinx masters time with the servers at NIST. It would be a good idea to setup the DNS server entries on the NetLinx master but not required. If the name lookup fails for a given server name, the IP address is tried directly. It may take a couple of attempts, but a server will be located and time synchronization will occur. i!-Schedule 9 Using i!-Schedule 10 i!-Schedule Programming i!-Schedule Programming i!-Schedule i!-Schedule appears on the NetLinx bus as a NetLinx device. This device has 1 port with channels, levels commands and strings like most other devices. Channels i!-Schedule supports the following channels: i!-Schedule Channels Channel 1-240 241 242 243 244 250 251 Description Events 1 - 240 are active, Push for Start and Release for stop with Channel Status. Sunrise occurred, Push only. Sunset occurred, Push only. Daylight savings status, Push when active and release when not active with Channel Status. Time changed by time sever update, Push only. Enables Schedule debugging, Channel status Only. Enables Time manager debugging, Channel status Only. Levels i!-Schedule supports the following levels: i!-Schedule Levels Level 1-8 9 10 11 12 13 14 15 16 17 18 Description Event Value Parameters 1-8 Total Event Slots Slots Event Left Next free Event index Current Event selected Next Event to start Next Event to stop Total Events today Events completed today Number of current events Events left today i!-Schedule 11 Programming i!-Schedule Send_Commands i!-Schedule supports the following out-bound commands (Master to device). In the table the command text wraps, but there are no breaks in syntax. i!-Schedule Send_Commands Command "'SET EVENT-[Event Number],[Event Name], [Date String],[Start Time String], [End Time String]'" "'GET EVENT-[Event Number]'" "'SET NAME-[Event Number],[Event Name]'" Description Sets the name, date, start and end time of an event. All Parameters are optional. Gets the name, date, start and end time of an event. Sets the name of an event. If name is an empty string, event is deleted. Gets the name of an event. Sets start time for event number. If time string is empty, the event is set for "No Start Time" (i.e. not scheduled). Gets start time for event number. Sets end-time for event number. If time string is empty, the event is set for one-shot (non-time spanning) event. Gets end-time for event number. Gets date for event number. If time string is empty, the event is set for "No Date" (i.e. not scheduled). Gets date string for event number. Sets the string parameter for event number. If no string is supplied, parameter is deleted. Gets the string parameters for event number. If the parameter number is 0, all string parameters for event number are returned. Sets the value parameter for event number. If no value is supplied, the parameter is deleted. Gets the value parameters for event number. If parameter number is 0, all value parameters for event number are returned. Sets the parameter page for event number. If no value is supplied, parameter page is deleted. Gets the parameter page for event number. Sets the parameter text for event number. If no value is supplied, parameter text is deleted. Gets the parameter text for event number. Returns past, current/active and future event lists. Runs event number and re-schedules the event (if it can be rescheduled). Cancels event form running today and re-schedules the event (if it can be rescheduled). Sets Date format European Format: Day/Month/Year. Sets Date format US style: Month/Day/Year. Sets Time format to 12 hour format: [01-12]:[00-59] [AM,PM]. Sets Time format to 24 hour (military) format: [01-23]:[00-59]. "'GET NAME-[Event Number]'" "'SET STIME-[Event Number],[Time String]'" "'GET STIME-[Event Number]'" "'SET ETIME-[Event Number],[Time String]'" "'GET ETIME-[Event Number]'" "'SET DATE-[Event Number],[Date String]'" "'GET DATE-[Event Number]'" "'SET SPARAM-[Event Number],[Param Number],[Param String]'" "'GET SPARAM-[Event Number],[Param Number]'" "'SET VPARAM-[Event Number],[Param Number],[Param Value]'" "'GET VPARAM-[Event Number],[Param Number]'" "'SET PPAGE-[Event Number],[Param Page]'" "'GET PPAGE-[Event Number]" "'SET PTEXT-[Event Number],[Param Page]'" "'GET PTEXT-[Event Number]" "'GET EVENT LISTS'" "'RUN-[Event Number]'" '"CANCEL-[Event Number]'" "'DFORMAT-DAY/MONTH'" "'DFORMAT-MONTH/DAY'" "'TFORMAT-12 HOUR'" "'TFORMAT-24 Hour'" Continued 12 i!-Schedule Programming i!-Schedule i!-Schedule Send_Commands (Cont.) Command "'FBON'" "'FBOF'" "'RESET'" "'VERSION'" Description Turns on unsolicited feedback. They are sent as today's event lists change. Turns off unsolicited feedback. They are sent as today's event lists change. Resets the schedule engine to re-schedule all events and re-build the event list for today. Sends version information to master debug port (master messaging). Where: [Event Number] [Event Name] [Param Number] [Param String] [Param Value] [Time String] 1 - 240 Any ASCII Readable string of characters. 1-8 Any string of characters, ASCII or NON-ASCII. Any value 0-2^32 (1-4294967295) Any time or time from Astronomical event in 24 hour time where Astronomical event is "Sunrise" or "Sunset" and offset can be '-' or '+' and time is 'HH:MM'. Examples: '01:00', 'Sunset', 'Sunrise', 'Sunrise+00:30', 'Sunrise-01:00', 'Sunset-00:30', 'Sunset+00:25'. Any fixed date in "MM/DD/YYYY" format. Daily: "[WD,WE] [xMultiplier]" Weekly: "[SMTWTFS] or [-------] [xMultiplier]" Monthly: "[Day 1-31] [xMultiplier]" Monthly: "[First,Second,Third,Fourth,Last][Sun,Mon,Tue,Wed,Thu,Fri,Sat] [xMultiplier]" Yearly: "[Jan,Feb,Mar,.Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec] [Day 1-31]" Yearly: "[First,Second,Third,Foruth,Last][Sun,Mon,Tue,Wed,Thu,Fri,Sat] [Jan,Feb,Mar,.Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec]" [Date String] Strings i!-Schedule supports the following in-bound strings (device to Master). In the table the string text wraps, but there are no breaks in syntax. i!-Schedule Strings String "'PAST',[Binary Event List String]" Description List of past event indexes. This string is only sent when the FBN command has been sent. List of current/active event indexes. This string is only sent when the FBN command has been sent. List of future event indexes. This string is only sent when the FBN command has been sent. Sunrise time for today. This string is sent whenever the Sunrise time string changes. Sunset time for today. This string is sent whenever the Sunset time string changes. Event Name for event number Parameter String for parameter number for event number Parameter Value for parameter number for event number Start Time String for event number Continued "'CURRENT',[Binary Event List String]" "'FUTURE',[Binary Event List String]" "'SUNRISE[Sunrise Time]'" "'SUNSET[Sunset Time]'" "'NAME[Event Number],[Event Name]'" "'SPARAM[Event Number],[Param Number], [Param String]'" "'VPARAM[Event Number],[Param Number], [Param Value]'" "'STIME[Event Number],[Time String]'" i!-Schedule 13 Programming i!-Schedule i!-Schedule Strings String "'ETIME[Event Number],[Time String]'" "'DATE[Event Number],[Date String]'" "'PARAM[Param Number],[Param String]'" Description End Time String for event number Date String for event number Parameters for a current event that is about to be run. All Time strings are in HH::MM::SS 24-hour format. All Date strings are in MM/DD/YYYY format. Modules Two scheduling modules are available with i!-Schedule. i!-ScheduleEngineMod is the scheduling engine module only. This module has no user interface and can be used for fixed events that do not need to be edited by the user. i!-ScheduleMod includes the functionality of the engine module and provides a user interface where the user can edit the scheduling of events. i!-ScheduleEngineMod Module To assist you in your programming the i!-ScheduleEngineMod Module definition code is displayed below. You can use this as a start to create custom programming or use it as-is for the standard functionality. DEFINE_MODULE 'i!-SchedulEEngineMod' mdlSch(vdvSchEvents, dvTmTimeSync, strTmTzName, strTmTzDesc, dTmTzGmtOffset, strTmTzDstRules, strTmLocName, dTmLocLong, dTmLocLat, nTmTsProtocol, nTmTsCheck_Time, strTmTsServer) Where: mdlSch is a unique module name. i!-ScheduleEngineMod Module Parameters Parameter vdvSchEvents dvTmTimeSync strTmTzName Description A virtual device number for programming NetLinx events. An IP device number for connecting to an Internet timeserver. A string containing the Time zone Name. Example: "Eastern" Continued 14 i!-Schedule Programming i!-Schedule i!-ScheduleEngineMod Module Parameters (Cont.) strTmTzDesc A string containing the time zone description. For the Eastern time zone: · "EST" for Standard time · "EDT" for Daylight Saving time For the Central time zone: · "CST" for Standard time · "CDT" for Daylight Saving time For the Mountain time zone: · "MST" for Standard time · "MDT" for Daylight Saving time For the Pacific time zone: · "PST" for Standard time · "PDT" for Daylight Saving time This string is dynamic, since the module determines Daylight Saving time. The "%s" allows the module to replace a portion of the string with a string listed in the DST rules. So to handle the case you specify: · "E%sT" · "C%sT" · "P%sT" Eastern time zone Central time zone Pacific time zone · "M%sT" Mountain time zone For description in DTS time rules, you use: · Standard Description: S · Daylight Saving Description: D Then the module will create "EST" or "EDT" (for the Eastern time zone) depending on whether DTS is in effect or not. The "%s" is a placeholder for a string specified in the DTS rules section. dTmTzGmtOffset A floating point number containing the GTM offset in hours. The common US offsets are: Eastern = -5, Center = -6, Mountain = -7, Pacific = -8. Location such as Newfoundland, which runs 3 hours 30 minutes behind GMT would use a GMT offset of -3.5. This information is used for calculating sunrise and sunset times and for calculating local time when communicating with an Internet timeserver. Continued i!-Schedule 15 Programming i!-Schedule i!-ScheduleEngineMod Module Parameters (Cont.) strTmTzDstRules A string containing 1 or more daylight saving rule strings. Multiple daylight saving rules are separated with the "$FF" character. Two standard rule strings, 'None' and 'US' will disable daylight savings time (default) and enable US daylight savings rules respectively. For other locations, daylight saving rule strings should be in the following format: Custom string: "Month" "Day Description" "Time" "Offset From Std" "Description" "Month": Month name ex: "Apr" "Time" Time to activate (hh:mm:ss, 24 hour). ex: "02:00:00" "Offset From Std" Time to offset from GMT (hh:mm:ss, 24 hour). ex: "01:00:00" "Description" String to replace "%s" with in Time zone description. ex: 'D' "Day Description" Day Description. Fixed Date, Last Day Of Week or First Day of Week Before/After Date Fixed ex: "15" Last Day of Week ex: "LastSunday" First Day of Week Before DATE-ex: "Sun<=24" First Day of Week After DATE-ex: "Sun>=1" Time zone examples: Here is an example configuration for Santiago, Chile which observes Daylight savings starting on the first Sunday on or after October 9th at midnight (jump ahead 1 hour) and the First Sunday on or after the 9th of March at midnight (jump back 1 hour): strTmTzDstRules = "'Oct Sun>=9 00:00:00 01:00:00 D',$FF,'Mar Sun>=9 00:00:00 00:00:00 S'" Here is an example configuration for Sydney, Australia which observes Daylight savings starting on the Last Sunday in October 2:00 AM (jump ahead 1 hour) and the Last Sunday in March at 3:00 AM (jump back 1 hour): strTmTzDstRules = "'Oct LastSun 02:00:00 01:00:00 X',$FF,'Mar LastSun 03:00:00 00:00:00 X'" Here is the example configuration for London, England which uses GMT and observes Daylight savings starting on the last Sunday in March at 1:00 AM (jump ahead 1 hour) and the Last Sunday in October at 1:00 AM (jump back 1 hour): strTmTzDstRules = "'Mar LastSun 01:00:00 01:00:00 BST',$FF,'Oct LastSun 01:00:00 00:00:00 GMT'" strTmLocName dTmLocLong and dTmLocLat A string describing the location the system is installed in. This could be any string describing the region or city. A double containing the longitude and latitude coordinates of the location where the system is installed. Longitude is in Degrees (Fraction of Degrees). West longitudes must be negative. Latitude is in Degrees (Fraction of Degrees). South latitudes must be negative. These parameters are used for calculating sunrise and sunset times. You can find longitude / latitude values and descriptions at: · http://geography.about.com/cs/latitudelongitude/ · http://www.census.gov/cgi-bin/gazetteer · http://www.njdxa.org/landl-lookup-dx.shtml A Timeserver protocol number to allow the NetLinx system to synchronous its clock with an Internet timeserver. The available values are: · 0 = Disabled · 1 = DayTime(13/udp, 13/tcp) · 2 = Time(37/udp, 37/tcp) · 3 = SNTP(123/udp) · 4 = SNTP Broadcast (123/udp). nTmTsProtocol nTmTsCheck_Time The time in minutes between time checked to the Internet timeserver. You can put 0 to use the default value of 120 (or 2 hours). strTmTsServer The IP address or Host Name of the preferred Internet timeserver. If left blank (empty string), a default server is picked from the nist_svr.lst file location in the doc:\time directory of the NetLinx Master. If this file is not present, an internal list of NIST time servers are used and an appropriate server is selected from the list. 16 i!-Schedule