AMX EQUIPMENTMONITOR User Manual

Download

instruction manual

i!-EquipmentMonitor

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!-EquipmentMonitor ........................................................................................... 2

Running i!-EquipmentMonitor .................................................................................3

Sending Email ................................................................................................................... 3

Receiving Email................................................................................................................. 4

Configuring for Timezone .................................................................................................. 6

i!-EquipmentMonitorOut.axi............................................................................................... 7

Constants ................................................................................................................................. 7

Structures................................................................................................................................. 8

Variable .................................................................................................................................... 8

Functions.................................................................................................................................. 8

i!-EquipmentMonitorIn.axi................................................................................................ 11

Constants ............................................................................................................................... 11

Structures............................................................................................................................... 11

Variables ................................................................................................................................ 11

Functions................................................................................................................................ 12

i!-EquipmentMonitor

Table of Contents

i!-EquipmentMonitor

Introduction

i!-EquipmentMonitor™ is an application that allows you to send and receive e-mail directly from a

NetLinx

Control System e-mails, such as sending e-mail notifications for system problems or equipment

trouble and receiving

e-mails for Control System messaging. i!-EquipmentMonitor consists of the following files:

Supported Operating Systems

™

Control System. i!-EquipmentMonitor is primarily used to send and receive NetLinx

 i!-EquipmentMonitorIn.axi is an include file for receiving e-mails using POP3

protocol.

 i!-EquipmentMonitorOut.axi is an include file for sending e-mails using SMTP

protocol.

 i!-EquipmentMonitorTest.axs is a test program using both i!-EquipmentMonitorIn.axi

and i!-EquipmentMonitorOut.axi.

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

/98® (with at least 48 MB of installed memory)

Workstation or Server (service pack 6 B or greater, with at least

Professional or Server (running on a Pentium 233 MHz processor

Introduction

Minimum PC Requirements

 Windows-compatible mouse (or other pointing device)

 At least 5 MB of free disk space (150 MB recommended)

 VGA monitor, with a minimum screen resolution of 800 x 600

 A Network adapter

 A Web server such as Personal Web Server (PWS) or Internet Information Server (IIS)

 Windows 95

 Windows 2000

and 98® use PWS.

Professional or Server, and Windows NT 4.0® Server use IIS.

i!-EquipmentMonitor

Introduction

Installing i!-EquipmentMonitor

1. In Explorer, double-click i!-EquipmentMonitorSetup.exe from the directory window where

you downloaded the i!-EquipmentMonitor install program.

2. After reading the License Agreement, select I Agree and Next to proceed.

3. The Welcome To i!-EquipmentMonitor Setup dialog appears, reminding you to close all

Windows programs before going any further. Click Next to proceed.

4. In the Select i!-EquipmentMonitor Install Location dialog, use the Browse button to navigate

to a directory other than the default install directory, if desired. Click Next.

5. In the i!-EquipmentMonitor Shortcut Creation dialog, select Install Shortcut Icons for the

installed components on your desktop, if desired.

6. Click Next in the Start i!-EquipmentMonitor Installation dialog to install the selected

components.

The program prompts you to restart your system to complete the installation.

i!-EquipmentMonitor

Running i!-EquipmentMonitor

Very little work is required to add e-mail support to your existing NetLinx code. Receiving and

sending e-mail are independent of each other; each one will be covered in it's own section. You do

not need to add support for sending and receiving if only one of the features is needed.

Sending Email

To support sending email, first include the i!-EquipmentMonitorOut.axi (page 7) into your

program:

#INCLUDE 'i!-EquipmentMonitorOut.axi' // Include to send email

Next, make sure that the default IP local port used by i!-EquipmentMonitorOut.axi is available on

your system. i!-EquipmentMonitorOut.axi uses local port 0:10:0 for sending emails. Make sure

there is no current entry in your

0:10:0, you can change the existing entry to another local port number or override the default local

port used by

i!-EquipmentMonitorOut.axi like this in the

dvSmtpSocket = 0:3:0

Next, you need to initialize the SMPT server value by calling SmptSetServer(). You need the

name or IP address of your local SMPT server, which you can obtain from you Network

administrator. Using a name for the server is acceptable if you have DNS properly configured on

the NetLinx Master. Otherwise, you need an IP address. Make sure to use the SMPT server value

here. Often, the "email server" refers to the POP3 server; most likely, this is not what you need.

Once you have the correct SMPT server name or address, call

SmtpSetServer('smtpserver.mydomain.com')

SmtpSetServer('192.168.12.175')

If the SMTP email server requires user authentication to send email, you must configure i!-

EquipmentMonitor with the username and password of a valid account registered to the SMTP

server. You can do this by calling the SmtpSetUser() function. This line is typically included

immediately after the SmtpSetServer() initialization command function. An example is provided

below:

DEFINE_DEVICE section for 0:10:0. If there is a current entry for

DEFINE_DEVICE section:

Running i!-EquipmentMonitor

SmptSetServer() like this:

i!-EquipmentMonitor

SmtpSetUser('user1','password') // include only if you need SMTP authentication

If the SMTP email server allows anonymous access and does not require authentication, you simply

comment out the previous SmtpSetUser() function call. Without an SMTP username and password

configured, i!-EquipmentMonitor will connect to the SMTP server with anonymous access.

Running i!-EquipmentMonitor

Now, all you need to do is call the function that sends an email. If you want to send an email every

time someone presses a button on a touch panel, your code would look like this:

BUTTON_EVENT[dvTP,1] { PUSH: { SmtpQueMessage('fromAddress@mydomain.com', 'toAddress@mydomain.com ', 'My Emails subject’,

'this is the body of my email! Wow, this is Cool!', '') } }

The call to SmtpQueMessage() causes your email to queue and transmit to the SMTP server. The

maximum number of emails that can be queued is controlled by the constant

which defaults to 10. You can override this value if you choose; you will probably never have a

need to since the emails are sent very quickly.

SMTP_MAX_EMAILS,

The parameters to

SmtpQueMessage() control where your email will be sent. The first parameter

is the From Email Address. This usually does not have to be a real email address but some SMTP

server configurations may require a valid one. It is best to obtain an email address from your email

administrator.

The second parameter is the To Email Address. This can be a list of addresses separated by a ";" so

you can send an email to more than one recipient in a single call to

SmtpQueMessage(). The next

two parameters are the subject and message of the email. The message can be up to

SMTP_MSG_MAX characters long (the default value is 2000 but you can override it if necessary).

The last parameter is an attachment file name. If you supply a value for this parameter,

i!-EquipmentMonitorOut attempts to open this file from the Master’s file system and include it as

an attachment to the email. Binary files are not supported at this time so the file must be ASCII

(text) only. If the file does not exist or cannot be opened, an error is printed to the terminal, but the

email is still sent without an attachment.

Receiving Email

To support receiving email, first include the i!-EquipmentMonitorIn.axi (page 11) into you

program:

#INCLUDE 'i!-EquipmentMonitorIn.axi' // Include to get email

Next, make sure that the default IP local port used by i!-EquipmentMonitorIn.axi is available on

your system.

i!-EquipmentMonitorIn.axi uses local port 0:11:0 for sending emails. Make sure there is no current

entry in your

change the existing entry to another local port number or override the default local port used by i!-

EquipmentMonitorIn.axi like this in the

dvPop3Socket = 0:4:0

Next, you need to initialize the POP3 server value by calling Pop3SetServer (). You will need

the name or IP address of your local POP3 server, provided by your Network administrator. Using a

name for the server is acceptable if you have DNS properly configured on the NetLinx Master.

Otherwise, you will need an IP address. Once you have the correct POP3 server name or address,

call Pop3SetServer like this:

DEFINE_DEVICE section for 0:11:0. If there is a current entry for 0:11:0, you can

DEFINE_DEVICE section:

i!-EquipmentMonitor

Running i!-EquipmentMonitor

Pop3SetServer ('mail.mydomain.com')

Pop3SetServer ('192.168.12.175')

Next, you need to setup the user and password for the email account you will be retrieving email

from. Your email administrator should supply you with a user name and password for an email

account that can receive email. Once you have these, call

Pop3SetUser() and supply these values

like this:

Pop3SetRefresh(300,1) // How often the check email server in Seconds and should I delete?

Supplying a refresh time of 0 seconds disables automatic email retrieval. If you decide you want to

retrieve email manually, all you need to do is call

Pop3GetEmail(). Pop3GetEmail() takes 1

parameter: a flag (1 or 0) indicating if you want email deleted from the server. You can call

Pop3GetEmail() even if you have setup for automatic email retrieval to force email to be retrieve.

You might supply the user with a button to force email to be retrieved like this:

BUTTON_EVENT[dvPanel,6] { PUSH: Pop3GetEmail(0); }

You can check for the email to arrive by waiting for the offline message from the dvPop3Socket

device. i!-EquipmentMonitor makes the emails available to you in three different variables:

sPop3EmailMessage, nPop3QtyMail and nPop3TotalMail. nPop3QtyMail and

nPop3TotalMail tell you how many email messages were retrieved (up to POP3_MAX_EMAILS,

default = 20) and how many emails were on the server when i!-EquipmentMonitor last logged in.

Up to

POP3_MAX_EMAILS are downloaded and all other emails, if any, remain on the server until

you retrieve them again.

sPop3EmailMessage is an array of structures containing the actual emails. The structure contains

the following items:

LmsgSize The number of bytes in the email message.

cFrom[] A string containing the senders email address.

cFromPersonal[] The friendly name of the sender (if one was supplied).

cTo[] A string containing the recipient's email address or addresses.

cToPersonal[] The friendly name of the recipient if one was supplied.

cDate[] A string containing the data and time the email was sent.

cSubject[] The subject of the email.

cMessage[] The body of the email.

NattachCount The number of attachments to the email.

cAttachments[][] The names of the files attached.

The subject and body are the items you need most in the structure. The count of file attachments

tells you the total number of files attached but the

POP3_ATTACH_MAX (default is 5) file names. The attached files are not saved. Only the file names

cAttachments containing up to

are supplied for reference.

i!-EquipmentMonitor

Continued

Running i!-EquipmentMonitor

You can use the following code to loop through the downloaded emails whenever new email

arrives:

DATA_EVENT[dvPop3Socket] { OFFLINE: {

STACK_VAR INTEGER nLoop Integer nLoop1 For (nLoop=1;nLoop<=nPop3QtyMail;nLoop++) { SEND_STRING 0,'i!Email Test-Print Message' SEND_STRING 0,' ' SEND_STRING 0,"'Message #',Itoa(nLoop)" SEND_STRING 0,"'Date:',sPop3EmailMessage[nLoop].cDate" SEND_STRING 0,"'From: "',sPop3EmailMessage[nLoop].cFromPersonal, '" <',sPop3EmailMessage[nLoop].cFrom,'>'" SEND_STRING 0,"'To: "',sPop3EmailMessage[nLoop].cToPersonal,

'" <',sPop3EmailMessage[nLoop].cTo,'>'" SEND_STRING 0,"'Subject:',sPop3EmailMessage[nLoop].cSubject" SEND_STRING 0,"'Message:',sPop3EmailMessage[nLoop].cMessage" SEND_STRING

0,"'Attachments:',Itoa(sPop3EmailMessage[nLoop].nAttachCount)" For (nLoop1=1;nLoop1<=sPop3EmailMessage[nLoop].nAttachCount;nLoop1++) SEND_STRING 0,"'Attachment ',Itoa(nLoop1),':',

sPop3EmailMessage[nLoop].cAttachments[nLoop1]"

SEND_STRING 0,' ' } } }

Once the emails are processed, you can delete any emails you like by calling

Pop3ClearEmailMessage () or Pop3ClearAllEmailMessages ().

Pop3ClearEmailMessage allows you to delete one email at a time;

Pop3ClearAllEmailMessages () allows you to delete all the emails at once.

Configuring for Timezone

The i!-EquipmentMonitorOut.axi file can read the time zone information from i!-TimeManager and

includes this information in email and notifications. Simply include the i!-TimeManager moodule

and make sure to name the i!-TimeManager virtual device '

'i!-EquipmentMonitorTest with i!-TimeManager.axs' provides an example of using these two

applications together.

Using i!-TimeManager is recommended for use with i!-EquipmentMonitor since some email

clients may improperly display the time when the email or notification was sent. i!-TimeManager

provides i!-EquipmentMonitor with a universal time reference, including any Daylight Savings

time offsets, and includes this information in the email or notification.

The i!-TimeManager Module is not included with i!-EquipmentMonitor. To obtain the i!-TimeManager Module (i!-TimeManager.tko), please download the i!-TimeManager install from our web site.

vdvTmEvents'. The file

i!-EquipmentMonitor

Running i!-EquipmentMonitor

i!-EquipmentMonitorOut.axi

Constants

The following table lists i!-EquipmentMonitorOut.axi constants.

i!-EquipmentMonitorOut.axi Constants

dvSmtpSocket The IP device number for sending e-mails (default = 0:10:0}.

SMTP_VERSION The version number of the include file.

SMTP_PORT IP Port that the SMTP server is listening on (default = 25).

SMTP_SERVER_TO Timeout in 1/10 for contacting the SMTP server (default = 1200).

SMTP_URL_MAX Maximum length for e-mail server name (default = 1000).

SMTP_USER_MAX Maximum length for e-mail addresses (default = 500).

SMTP_LINE_MAX Maximum length for date, subject and attached file (default = 256).

SMTP_MAX_EMAILS Maximum length for number of queued e-mails (default = 10).

SMTP_MSG_MAX Maximum length for e-mail message (default = 2000).

i!-EquipmentMonitor

Continued

Running i!-EquipmentMonitor

Structures

The following defines an i!-EquipmentMonitorOut.axi structure:

Structure _sSMTPMessage { CHAR cDate[SMTP_LINE_MAX]; CHAR cSource[SMTP_USER_MAX]; CHAR cDest[SMTP_USER_MAX]; CHAR cSubject[SMTP_LINE_MAX]; CHAR cMessage[SMTP_MSG_MAX]; CHAR cFile[SMTP_LINE_MAX]; }

Variable

The following is an i!-EquipmentMonitorOut.axi variable:

VOLATILE CHAR bSMTPDebug Set to 1 to enable debugging

Functions

The following are a list of i!-EquipmentMonitorOut.axi functions:

i!-EquipmentMonitorOut.axi Functions

SmtpQueMessage

Call this to send an e-mail message.

Syntax:

SLONG SmtpQueMessage(CHAR Source[],CHAR Dest[],CHAR Subject[],CHAR Message[],CHAR File[])

SmtpQueMessage has these arguments:

Source: String containing the senders e-mail address.

Dest: String containing the recipients e-mail address or addresses.

Subject: String containing the subject of the e-mail.

Message: String containing the message body of the e-mail.

File: String containing the ASCII (text) only file name to attach to the e-mail.

SmtpQueMessage returns these values:

-1: If the message was not successfully queued for sending.

>0: If the message was successfully queued for sending.

Example:

SmtpQueMessage('me@mydomain.com','vmorrison@moondance.com', 'Wild Nights',

'Are they calling?','')

Remarks:

SmtpQueMessage should be called if you want to send a message. The To parameter can contain multiple addresses separated by a ";". The file parameter is the path and file of an ASCII (text) only file contained on the master's file systems. This file is transmitted as an attachment.

i!-EquipmentMonitor

i!-EquipmentMonitorOut.axi Functions (Cont.)

SmtpSetTimeOffset(CHAR Offset[])

Call this to configure the local timezone

SmtpSetServer

Sets your SMTP Server Name for your use.

SmtpSetTimeOffset has these arguments:

Offset String containing the local timezone offset. This string is formatted as "+/HHMM" where "+/=" is "+" or "-" depending on your timezone relative to GMT, "HH" is the offset in hours relative to GMT and "MM" is the offset in minutes relative to GMT.

Some Common Offsets are:

-0500 : Eastern time (UTC - 5:00)

-0600 : Central time (UTC - 6:00)

-0700 : Mountain time (UTC - 7:00)

-0800 : Pacific time (UTC - 8:00)

-0900 : Alaska (UTC - 9:00)

-1000 : Hawaii (UTC - 10:00)

+0000 : Greenwich Mean Time (same as UTC)

+0000 : Dublin, Edinburgh, Lisbon, London (UTC + 0:00)

+0100 : Brussels, Copenhagen, Madrid, Paris, Vilnius (UTC + 1:00)

+0100 : Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna (UTC + 1:00)

+0200 : Eastern Europe (UTC + 2:00)

+0900 : Osaka, Sapporo, Tokyo (UTC + 9:00)

+0800 : Hong Kong SAR (UTC + 8:00)

+0700 : Bangkok, Hanoi, Jakarta (UTC + 7:00)

+0300 : Baghdad, Kuwait, Riyadh (UTC + 3:00)

+0200 : Israel (UTC + 2:00)

-0600 : Mexico City, Tegucigalpa (UTC - 6:00)

-0600 : Central America (UTC - 06:00)

+0200 : Jerusalem (UTC + 2:00)

+0300 : Nairobi (UTC + 3:00)

Example:

SmtpSetTimeOffset ('-0600')

Remarks:

SmtpSetTimeOffset should be called to configure i!-EquipmentMonitor to send emails with the correct time. Some SPAM detectors may mark an e-mail as spam if the timezone is not correctly reported.

i!-EquipmentMonitor is designed to work with i!-TimeManager to obtain timezone information. If you have included i!-TimeManager in your program and the virtual device for i!-TimeManager is defined as "vdvTmEvents", the timezone will be configured correctly.

Syntax:

SmtpSetServer(CHAR Server[])

SmtpSetServer has these arguments:

Server: String containing the name or IP of your e-mail (SMTP) server.

SmtpSetServer does not return a value.

Example:

SmtpSetServer('mail.amx.com')

Remarks:

SmtpsetServer should be called in DEFINE_START of your application.

Running i!-EquipmentMonitor

i!-EquipmentMonitor

Running i!-EquipmentMonitor

i!-EquipmentMonitorOut.axi Functions (Cont.)

SmtpSetUser

Call this to configure the username and password for SMTP server authentication to send outbound emails.

EncrBase64Encode

This function is used internally to encrypt the username and password for SMTP server authentication.

ConfigNotify

Sets your notification paramaters for your use.

SendNotify

Call this function to send an equipment notification.

SmtpSetUser(CHAR LogInName[],CHAR LogInPass[])

SmtpSetUser has these arguments:

LogInNameString containing the username for the SMTP server.

LogInPassString containing the password for them STMP server.

SmtpSetUser doe not return any values.

Example:

SmtpSetUser ('MyUserName','MyPassword')

Remarks:

SmtpSetUser should be called to configure i!-EquipmentMonitor to send emails to an SMTP server that required authentication.

You should not have to call this function directly. To configure SMTP authentication, please see the SmtpSetUser() function.

Syntax:

ConfigNotify(CHAR Source[],CHAR Dest[],CHAR Subject[])

ConfigNotify has these arguments:

Source String containing the senders email address.

Dest String containing the recipients email address or addresses.

Subject String containing the subject of the email.

ConfigNotify does not return a value.

Example:

ConfigNotify('user2@test.com','user1@test.com','Equipment Notification Room 301')

Remarks:

ConfigNotify should be called in DEFINE_START of your application. You must also call the SmtpSetServer Function.

The To parameter can contain multiple addresses separated by a ";".

Syntax:

SLONG SendNotify(CHAR Message[],CHAR File[])

SendNotify has these arguments:

Message String containing the message body of the email.

File String containing the ASCII (text) only file name to attach to the email.

SendNotify returns these values:

-1 If the message was not successfully queued for sending.

>0 If the message was successfully queued for sending.

Example:

SendNotify('The VCR needs to be cleaned.','')

Remarks:

SendNotify should be called if you want to send a notification. The To, From and Subject used in the ConfigNotify function is included in the notification.

The file parameter is the path and file of an ASCII (text) only file contained on the Master's file systems. This file is transmitted as an attachment.

Continued

i!-EquipmentMonitor

Running i!-EquipmentMonitor