AMX I!-TIMEMANAGER User manual

instruction manual
integration!Solutions
i!-TimeManager

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 Cor-
poration'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 Com-
puter Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Soft-
ware--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
i
i!-TimeManager
Table of Contents
Introduction ...............................................................................................................1
Supported Operating Systems .......................................................................................... 1
Minimum PC Requirements .............................................................................................. 1
Installing i!-TimeManager .................................................................................................. 2
Time Protocols ..........................................................................................................3
DayTime Protocol.............................................................................................................. 3
Time Protocol .................................................................................................................... 4
SNTP Protocols................................................................................................................. 4
Choosing a Protocol .......................................................................................................... 4
Programming i!-TimeManager .................................................................................7
i!-TimeManagerEngineMod Module Definition .................................................................. 7
Channels ........................................................................................................................... 9
Commands ........................................................................................................................ 9
Strings ............................................................................................................................. 10

ii i!-TimeManager
Table of Contents

Introduction
1
i!-TimeManager
Introduction
i!-TimeManager™is an application that syncs the NetLinx™Master clock to an Internet time
server. Internet time servers provide highly accurate time and i!-TimeManager keeps the NetLinx
Master synchronized to the time servers. i!-TimeManager accounts for daylight saving time
changes (DTS changes) using U.S. or custom DTS rules. i!-TimeManager also calculates and
provides events for sunrise and sunset.
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

Introduction
2i!-TimeManager
Installing i!-TimeManager
1. In Explorer, double-click i!-TimeManagerSetup.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!-TimeManager Setup dialog opens, reminding you to close all Windows
programs before going any further. Click Next to proceed.
4. In the i!-TimeManager Select Components dialog, select which example programs you would
like to install.
5. In the Select i!-TimeManager 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!-TimeManager Shortcut Creation dialog, select Install Shortcut Icons for the installed
components on your desktop, if desired.
7. Click Next in the Start i!-TimeManager Installation dialog to install the selected components.
8. The program prompts you to restart your system to complete the installation.

Time Protocols
3
i!-TimeManager
Time Protocols
i!-TimeManager supports four time protocols:
 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.
DayTime Protocol
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. i!-TimeManager is capable of connecting to any of the NIST Time servers and calculating the
correct time and date for any location in the world. i!-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, i!-TimeManager has also been written to use a "popular" DayTime format which is
used by the Linux implementation of DayTime and Tardis, a popular time syncing 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.

Time Protocols
4i!-TimeManager
Time Protocol
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.
SNTP Protocols
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
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. i!-TimeManager 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.
Choosing a Protocol
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!-TimeManager 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.
i!-TimeManager 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!-TimeManager, 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
5
i!-TimeManager
Time protocols, but the DayTime is the most common protocol provided by NIST servers.
i!-TimeManager will synchronize the NetLinx Master’s 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.

Time Protocols
6i!-TimeManager

Programming i!-TimeManager
7
i!-TimeManager
Programming i!-TimeManager
Little work is required to add i!-TimeManager to your existing NetLinx code. i!-TimeManager is
implemented as a NetLinx module, so you need to add the module definition and all its parameters
to your code. You must define the NetLinx events you would like to schedule.
i!-TimeManagerEngineMod Module Definition
To assist you in your programming the i!-TimeManagerEngineMod 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.
Where: mdlTm is a unique module name.
DEFINE_MODULE 'i!-TimeManagerMod' mdlTm(vdvTmEvents,
dvTmTimeSync,
strTmTzName,
strTmTzDesc,
dTmTzGmtOffset,
strTmTzDstRules,
strTmLocName,
dTmLocLong,
dTmLocLat,
nTmTsProtocol,
nTmTsCheck_Time,
strTmTsServer)
i!-TimeManagerEngineMod Module Definitions
vdvTmEvents A virtual device number for NetLinx events.
dvTmTimeSync An IP device number for connecting to an Internet time server.
strTmTzName A string containing the time zone name. Example: "Eastern".
Continued

Programming i!-TimeManager
8i!-TimeManager
i!-TimeManagerEngineMod Module Definitions (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" 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.
dTmTzGmtOffset A floating point number containing the GTM offset in hours. The common US offsets
are:
• Eastern = -5
• Center = -6
• Mountain = -7
•Pacific=-8
Locations 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 a Internet time server.
strTmTzDstRules A string containing 1 or more daylight saving rule strings. Multiple daylight saving rules
are separated with the "$FF" character. Two stardard rule strings, ‘None’ and ‘US’ will
disable daylight savings time (default) and enable US daylight savings rules respec-
tively. For other locations, daylight saving rule strings should be in the following format:
Custom string: "Month" "DayDescription" "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 Timezone description. ex: 'D'
"DayDescription" 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 Beforer DATE-ex: "Sun<=24"
First Day of Week After DATE-ex: "Sun>=1"
See i!-TimeManagerEngineModTest.axs for more examples.
strTmLocName A string describing the location the system is installed in. This could be any string
describing the region or city.
Continued

Programming i!-TimeManager
9
i!-TimeManager
Channels
i!-TimeManager uses a virtual device to post channel events for certain time related activities.
i!-TimeManager supports the following channels:
Commands
i!-TimeManager supports the following commands.
i!-TimeManagerEngineMod Module Definitions (Cont.)
dTmLocLong and
dTmLocLat
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
nTmTsProtocol A time server protocol number to allow the Netlinx system to synchronous its clock with
an Internet time server. 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).
nTmTsCheck_Time The time in minutes between time checks to the Internet time server. You can put 0 to
use the default value of 120 (2 hours).
strTmTsServer The IP address or Host Name of the preferred Internet time server. If left blank (empty
string), a default server will be picked from the nist-srv.lst file location in the doc:\time
directory of the NetLinx Master. If this file is not present, an internal list of NIST time
server will be used, and an appropriate server will be selected from the list.
i!-TimeManager Channels
Channel Description
1 Sunrise Occurred
2 Sunset Occurred
3 Daylight Saving Time is active.
4 Time changed by Internet time server.
i!-TimeManager Strings
Syntax Description
"'RESET'" Resets the time zone and timeserver information.
"'VERSION'" Sends version information to Master debug port (Master messaging).

Programming i!-TimeManager
10 i!-TimeManager
Strings
i!-TimeManager supports the following in-bound strings (device to Master).
i!-TimeManager Strings
Syntax Description
"'SUNRISE-[Sunrise Time]'" Sunrise time for today
"'SUNSET-[Sunset Time]'" Sunset time for today

Programming i!-TimeManager
11
i!-TimeManager

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 [phone] • technical support 800.932.6993
033-004-2612 4/03 ©2003 AMX Corporation. All rights reserved. AMX, the AMX logo, the building icon, the home icon, and the light bulb icon are all trademarks of AMX Corporation.
AMX reserves the right to alter specifications without notice at any time. *In Canada doing business as Panja Inc.