Amx I!-SCHEDULE User Manual

Download

i!-Schedule

instruction manual

integration!Solutions

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. 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.

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.

AMX Corporation disclaims all other warranties, either expressed or implied, including, but

. In no event shall AMX Corporation be liable for any damages

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

Table of Contents

i!-Schedule

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

 Windows NT 4.0

64 MB of installed memory)

 Windows 2000

(minimum requirement); 300 MHZ or faster recommended, with 96 MB of installed

memory.)

 Windows ME

300 MHZ or faster recommended, with 96 MB of installed memory.)

 Windows XP

300 MHZ or faster recommended, with 128 MB of installed memory.)

Introduction

/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 266 MHZ processor

(running on a Pentium 266 MHZ processor (minimum requirement);

i!-Schedule

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

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.

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,

support the events you want scheduled using this virtual device.

Using i!-Schedule

vdvSchEvents. You must

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] (* Outdoor Lights On *) { PUSH: { ON[RELAY,1] } } BUTTON_EVENT[TP,2] (* Outdoor Lights Off *) { PUSH: { OFF[RELAY,1] } }

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] (* Outdoor Lights On *) { PUSH: { ON[RELAY,1] } } BUTTON_EVENT[vdvSchEvents,2] (* Outdoor Lights Off *) { PUSH: { OFF[RELAY,1] } }

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.

i!-Schedule

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

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

event. To provide dynamic events, you must provide dynamic

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,

BUTTON_EVENT to handle the push and/or release of that

BUTTON_EVENTS.

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.

i!-Schedule

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

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-<Parameter 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)"

Continued

(* 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] (* VCR Recording *) { PUSH: { Switch (nVCRNumberParam) { Case 1: dvVCRDev = dvVCR1

i!-Schedule

Case 2: dvVCRDev = dvVCR2 Case 3: dvVCRDev = dvVCR3 Case 4: dvVCRDev = dvVCR4 Case 5: dvVCRDev = 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.

Using i!-Schedule

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

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

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

Using i!-Schedule

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 Description

1-240 Events 1 - 240 are active, Push for Start and Release for stop with Channel Status.

241 Sunrise occurred, Push only.

242 Sunset occurred, Push only.

243 Daylight savings status, Push when active and release when not active with Channel Status.

244 Time changed by time sever update, Push only.

250 Enables Schedule debugging, Channel status Only.

251 Enables Time manager debugging, Channel status Only.

Programming i!-Schedule

Levels

i!-Schedule supports the following levels:

i!-Schedule Levels

Level Description

1-8 Event Value Parameters 1-8

9 Total Event Slots

10 Slots Event Left

11 Next free Event index

12 Current Event selected

13 Next Event to start

14 Next Event to stop

15 Total Events today

16 Events completed today

17 Number of current events

18 Events left today

i!-Schedule

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 Description

"'SET EVENT-[Event Number],[Event Name], [Date String],[Start Time String], [End Time String]'"

"'GET EVENT-[Event Number]'"

"'SET NAME-[Event Number],[Event Name]'"

"'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'"

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].

Continued

i!-Schedule

Programming i!-Schedule

i!-Schedule Send_Commands (Cont.)

Command Description

"'FBON'" Turns on unsolicited feedback. They are sent as today's event lists change.

"'FBOF'" Turns off unsolicited feedback. They are sent as today's event lists change.

"'RESET'" Resets the schedule engine to re-schedule all events and re-build the event list for today.

"'VERSION'" Sends version information to master debug port (master messaging).

Where:

[Event Number] 1 - 240

[Event Name] Any ASCII Readable string of characters.

[Param Number] 1 - 8

[Param String] Any string of characters, ASCII or NON-ASCII.

[Param Value] Any value 0-2^32 (1-4294967295)

[Time String] Any time or time from Astronomical event in 24 hour time where Astronomical event is

[Date String] Any fixed date in "MM/DD/YYYY" format.

"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'.

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]"

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 Description

"'PAST',[Binary Event List String]"

"'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]'"

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

i!-Schedule

Programming i!-Schedule

i!-Schedule Strings

String Description

"'ETIME[Event Number],[Time String]'"

"'DATE[Event Number],[Date String]'"

"'PARAM[Param Number],[Param String]'"

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.

End Time String for event number

Date String for event number

Parameters for a current event that is about to be run.

 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 Description

vdvSchEvents

dvTmTimeSync

strTmTzName

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

i!-Schedule

i!-ScheduleEngineMod Module Parameters (Cont.)

strTmTzDesc

dTmTzGmtOffset

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" Eastern time zone

• "C%sT" Central time zone

• "M%sT" Mountain time zone

• "P%sT" Pacific 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.

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.

Programming i!-Schedule

i!-Schedule

Continued

Programming i!-Schedule

i!-ScheduleEngineMod Module Parameters (Cont.)

strTmTzDstRules

strTmLocName

dTmLocLong and dTmLocLat

nTmTsProtocol

nTmTsCheck_Time

strTmTsServer

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'"

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).

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).

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.

i!-Schedule

Programming i!-Schedule

i!-ScheduleMod Module

To assist you in your programming the i!-ScheduleMod 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!-ScheduleMod' mdlSch(vdvSchEvents,

nvTmTimeSync, nvTP, nchSchEventList, nchSchEventListCtrl, nchSchEventEdit, nchSchEngineList, nchSchEngineListCtrl, nchSchEngineListMode, nchSchEngineEdit, nchSchTimeSelect, nchSchDateSelect, nchSchSaveOpt, nchSchDateOpt, nchSchDetailSelect, nvtSchEventList, nvtSchEventInfo, nvtSchEngineList, nvtSchEngineInfo, nvtSchEngineStats, nvtSchEngineListSel, nvtSchTimeSelect, nvtSchDateSelect, nvtSchDetailSelect, strTmTzName, strTmTzDesc, dTmTzGmtOffset, strTmTzDstRules, strTmLocName, dTmLocLong, dTmLocLat, nTmTsProtocol, nTmTsCheck_Time, strTmTsServer)

i!-Schedule

Where:

mdlSch is a unique module name.

i!-ScheduleMod Module Parameters

Parameter Description

vdvSchEvents A virtual device number for programming NetLinx events.

nvTmTimeSync An IP device number for connecting to an Internet timeserver.

nvTP An array of touch panel devices implementing i!-Schedule.

nchSchEventList An INTEGER array with the following buttons:

Main Event List Items 1-8

nchSchEventListCtrl An INTEGER array with the following buttons:

• Page Up

• Page Down

• Top of List

• End of List

• Slider Channel Code

Continued

Programming i!-Schedule

i!-ScheduleMod Module Parameters (Cont.)

nchSchEventEdit An INTEGER array with the following buttons:

nchSchEngineList An INTEGER array with the following buttons:

nchSchEngineListCtrl An INTEGER array with the following buttons:

nchSchEngineListMode An INTEGER array with the following buttons:

nchSchEngineEdit An INTEGER array with the following buttons:

nchSchTimeSelect An INTEGER array with the following buttons:

nchSchDateSelect An INTEGER array with the following buttons:

nchSchSaveOpt An INTEGER array with the following buttons:

nchSchDateOpt An INTEGER array with the following buttons:

nchSchDetailSelect An INTEGER array with the following buttons:

• Edit Event

• Run Event

• Cancel Event

Today's Event List Items 1 - 6

• Page Up

• Page Down

• Top of List

• Past Events

• Current Events

• Future Events

• Run Event

• Cancel Event

• Start time - Fixed

• Start Time - Sunrise

• Start time - Sunset

• Start Time - Before Sunrise

• Start time - Before Sunset

• Start Time - After Sunrise

• Start time - After Sunset

• Start Time - Hour

• Start time - Minute

• Start Time - AM/PM

• End time - None

• End time - Fixed

• Date - Fixed

• Date - Daily

• Date - Weekly

•Save Edit

• Cancel Edit

• Parameters

• Clear Event

Pool of Channel codes for Date editing options (9 channel codes, see touch panel pages)

Pool of Channel codes for editing Date and Time parameters (37 channel codes, see touch panel pages)

• End of List

• Slider Channel Code

• End time - Sunrise

• End time - Sunset

• End time - Before Sunrise

• End time - Before Sunset

• End time - After Sunrise

• End time - After Sunset

• End time - Hour

• End time - Minute

• End time - AM/PM

• End time - Sunrise

• Hours Done/Minutes Done

• Date - Monthly

• Date - Yearly

Continued

i!-Schedule

Programming i!-Schedule

i!-ScheduleMod Module Parameters (Cont.)

nvtSchEventList An INTEGER array with the following variable text channels:

• Main Event List Total Items

• Main Event List Slider Level Code

• Main Event List Items 1 - 8

nvtSchEventInfo An INTEGER array with the following variable text channels:

• Scheduled For Date

• Scheduled For time

• Runs Next at

nvtSchEngineList An INTEGER array with the following variable text channels:

• Today's Event List Total Items

• Today's Event List Slider Level Code

• Today's Event List Items 1 - 6

nvtSchEngineInfo An INTEGER array with the following variable text channels:

• Scheduled For Date

• Scheduled For time

• Runs Next at

nvtSchEngineStats An INTEGER array with the following variable text channels:

•Date

•Time

nvtSchEngineListSel An INTEGER array with the following variable text channels:

• Number of Past Events

• Number of Current Events

• Number of Future Events

nvtSchTimeSelect An INTEGER array with the following variable text channels:

• Start time - Hours

• Start Time - Minutes

• Start Time - AM/PM

• Start Time - Label

• End Time - Hours

nvtSchDateSelect An INTEGER array with the following variable text channels:

• Daily Repeat

• Weekly Repeat

• Monthly Repeat

• Monthly/Yearly Date of Month

• Monthly/Yearly Day Occurrence

• Monthly/Yearly Day of Month

• Yearly Month

• Fixed Date - Month

• Fixed Date - Day

nvtSchDetailSelect An INTEGER array with the following variable text channels:

Pool of variable text channels codes for editing Date and Time parameters (37 channel codes, see touch panel pages)

strTmTzName

A string containing the Time zone Name.

Example: "Eastern"

• Sunrise Time

• Sunset Time

• End Time - Minutes

• End Time - AM/PM

• End time- Label

• Adjustable Minutes

• Fixed Date - Year

• Year 0

• Year 1

• Year 2

• Year 3

• Year 4

• Description Schedule For Date

• Description Schedule For time

i!-Schedule

Continued

Programming i!-Schedule

i!-ScheduleMod Module Parameters (Cont.)

strTmTzDesc A string containing the time zone description.

dTmTzGmtOffset

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

• "E%sT" Eastern time zone

• "C%sT" Central time zone

• "M%sT" Mountain time zone

• "P%sT" Pacific 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.

Continued

i!-Schedule

Programming i!-Schedule

i!-ScheduleMod 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:

strTmTzDstRules = "'Oct Sun>=9 00:00:00 01:00:00 D',$FF,'Mar Sun>=9 00:00:00 00:00:00 S'"

strTmTzDstRules = "'Oct LastSun 02:00:00 01:00:00 X',$FF,'Mar LastSun 03:00:00 00:00:00 X'"

strTmTzDstRules = "'Mar LastSun 01:00:00 01:00:00 BST',$FF,'Oct LastSun 01:00:00

00:00:00 GMT'"

strTmLocName

dTmLocLong and dTmLocLat

nTmTsProtocol A Timeserver protocol number to allow the NetLinx system to synchronous its

nTmTsCheckTime The time in minutes between time checked to the Internet timeserver. You can

strTmTsServer The IP address or Host Name of the preferred Internet timeserver. If left blank

A string describing the location the system is installed in. This could be any string describing the region or city.

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

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 (137/udp).

put 0 to use the default value of 120 (or 2 hours).

(empty string), a default server will be 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 will be used and an appropriate server will be selected from the list.

i!-Schedule

AMX reserves the right to alter specifications without notice at any time.

brussels • dallas • los angeles • mexico city • philadelphia • shanghai • singapore • tampa • toronto* • york

3000 research drive, richardson, TX 75082 USA • 469.624.8000 • 800.222.0193 • fax 469.624.7153 • technical support 800.932.6993

033-004-2598 2/05

AMX reserves the right to alter specifications without notice at any time. *In Canada doing business as Panja Inc.

Amx I!-SCHEDULE User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Introduction

Supported Operating Systems

Minimum PC Requirements

Installing i!-Schedule

Using i!-Schedule

Dynamic Events

Schedule Persistence

Time Protocols

Programming i!-Schedule

Channels

Levels

Send_Commands

Strings

Modules

i!-ScheduleEngineMod Module

i!-ScheduleMod Module