X-10 POWERHOUSE BASIC UTILITY PROGRAM FOR IBM(TM) & COMPATIBLES CONTENTS 1. Introduction 2. Using the Utility Program 3. Variables 4. Sub-Routine Locations 5. Initializing the Communications Port 6. Setting the Real Time Clock 7. Reading the Real Time Clock 8. Setting the Base Housecode 9. Sending an Instant X-10 Code 10. Downloading Graphics Data 11. Uploading Graphics Data 12. Downloading Timer events 13. Uploading Timer Events 14. SOFTWARE LICENSE 1. INTRODUCTION If you like to write your own software, this manual is for you. It is assumed that you are familiar with Basic programming and some knowledge of Binary programming will also be useful. This manual should be sufficient to let you write simple Basic programs to set and read the Real Time Clock in the Interface and to turn modules on and off manually etc. For more complex programs involving "Timed Events" etc. you should refer to the Programming Guide which deals in more detail with Binary and Hex programming. The Utility Program is written in Basic and stored in ASCII format to allow merging with an existing Basic Program. This lets you write programs in Basic and use sub-routines to perform functions such as setting the clock, uploading or downloading timer events etc. 2. USING THE UTILITY PROGRAM The Utility Program sub-routines occupy Basic lines 19999 - 372 and therefore any program using the sub-routines should leave these lines free. Alternatively you could re-number the sub-routines remembering to update the GOSUB addresses also. There are two ways to load the Utilities. 1. If you are writing a completely new program, you can just LOAD "X1" 2. If you are combining the Utilities with an existing program, (e.g. MY PROGRAM) you first load your existing program i.e. LOAD "MY PROGRAM", then merge the Utilities into the memory area by MERGE "X1". Once merged your program is ready to run. NOTE. If you forget to merge the Utilities, your prm will not run. 3. VARIABLES Below is a list of variables used by the Utility program. These variables should only be used in your program to transfer data between the main program and the sub-routine and vice versa. A FUNCTION A$ GRAPH (2, 256) ADDR1 HITEMP ADDR2 HIUNIT ADDRESS HOURS BTEMP HOUSECODE BASECODE LEVEL CHKSUM LOUNIT CODCONV (16) MINS COUNT PORT DAY STATUS EVENT TIM (8, 128) FTEMP XTEMP 4. SUB-ROUTINE LOCATIONS The Utility Program has 9 sub-routines which give the Basic Programmer full control over the Interface. These are located at the following lines. 2 Initializing the com. port / defining the variables. 21 Setting the real time clock in the interface. 22 Setting the base housecode in the Interface. 23 Reading the real time clock from the Interface. 25 Sending an INSTANT on or off X-10 code. 28 Downloading a Timer Event to the Interface. 29 Uploading ALL Timer Events from the Interface. 21 Downloading Graphics Data to the Interface. 211 Uploading ALL Graphics Data from the Interface STATUS The Utility sub-routines return a status value indicating the following: If 'STATUS = 1' then 'GOSUB' was successful. If 'STATUS = ' then 'GOSUB' was successful but the Interface indicated that it had been powered down and contains no data. If 'STATUS = -1' then 'GOSUB' was unsuccessful. This indicates that there may be a problem with the connections to the Interface or the Interface may not have power. 5. SETTING THE COM PORT LINE 2 This sub-routine initializes the communications port (COM1). This sub-routine also assigns all the variables used within the utility sub-routines. It should be called at the beginning of a program and should only be called once. If called more than once an error will occur. EXAMPLE 1 GOSUB 2 Rest of the Basic Program. 19999 ' ' Utilities ' 372 6. SETTING THE REAL TIME CLOCK To set the real time clock in the Interface. LINE 21 Variables passed to the sub-routine. DAY (1-7) HOURS (-23) MINS (-59) Variables passed from the sub-routine. STATUS (-1, , 1) Before calling this sub-routine, first assign a value to DAY, HOURS and MINS. Then call the sub-routine. The values stored in DAY, HOURS and MINS will then be transferred to the Interface. On returning from the sub-routine the STATUS should be compared with the value -1 to ensure that the download was successful. EXAMPLE 5 CLS:PRINT "Setting the real time clock" : PRINT 1 GOSUB 2 2 INPUT "Enter the DAY (1= Sun, 7=Sat) "; DAY 3 INPUT "Enter the HOURS (-23) "; HOURS 4 INPUT "Enter the MINUTES (-59) "; MINS 5 GOSUB 21:IF STATUS =-1 THEN PRINT "*** ERROR***": END 6 PRINT:PRINT "The time has been set": END 7. READING THE REAL TIME CLOCK LINE 23 Variables passed to the sub-routine NONE Variables passed from the sub-routine DAY (1-7) HOURS (-23) MINS (-59) STATUS (-1, , 1) To read the time from the Interface, call the sub-routine. The time will then be transferred to the variables DAY, HOURS and MINS, providing the STATUS is not returned -1. EXAMPLE 1 GOSUB 2 2 GOSUB 23: IF STATUS =-1 THEN PRINT "***ERROR***" :END 3 PRINT "DAY = "; DAY; "HOURS = "; HOURS; "MINUTES = "; MINS 4 END 8. SETTING THE BASE HOUSECODE LINE 22 Variables passed to the sub-routine. BASECODE (1-16) Variables passed from the sub-routine. STATUS (-1, , 1) To set the Base Housecode in the Interface, first assign a value to BASECODE as shown below. A=1 B=2 C=3 D=4 E=5 J=1 K=11 L=12 M=13 N=14 O=15 P=16 Then call the sub-routine to change the Base housecode in the Interface. NOTE. calling this sub-routine will erase all the data stored in the Interface. EXAMPLE 5 CLS:PRINT "Setting the base Housecode": PRINT 1 GOSUB 2 2 INPUT "Enter Base Housecode"; A$:BASECODE=ASC (A$) - 64 3 GOSUB 22: IF STATUS =-1 THEN PRINT "***ERROR***" :END 4 PRINT:PRINT "The Base Housecode has been set" :END 9. SENDING AN INSTANT X-10 CODE LINE 25 Variables passed to the sub-routine. FUNCTION This is a number between 1 and 3. 1=ON 2=OFF 3=DIM. LEVEL This is a number between and 15 which sets the intensity of the DIM command. If FUNCTION is set to 1 or 2, LEVEL will be ignored. HOUSECODE This is a value between 1 and 16 where A=1 and P=16. LOUNIT This is a bit mapped value corresponding to the unit codes 1 thru 8 as follows: 1=128 2=64 3=32 4=16 5=8 6=4 7=2 8=1 HIUNIT This is a bit mapped value corresponding to the unit codes 9 thru 16 as follows: 9=128 1=64 11=32 12=16 13=8 14=4 5=2 16=1 Variables passed from the sub-routine. STATUS (-1, , 1) FUNCTION (1, 2, 3) LOUNIT ( - 255) HIUNIT ( - 255) HOUSECODE ( - 16) BASECODE ( - 16) To transmit an X-10 code instantly, you must first assign values to FUNCTION, LEVEL, HOUSECODE, LOUNIT and HIUNIT relating to the code to be sent; then call the sub-routine. If the STATUS is not -1, the sub-routine will return the values of FUNCTION, LEVEL, HOUSECODE, LOUNIT and HIUNIT as sent to the Interface. These values can then be used by your program to verify the code sent. EXAMPLE 1 GOSUB 2 2 LEVEL = 3 INPUT " Enter the FUNCTION (1=On 2=Off 3=Dim)" ; FUNCTION 4 IF FUNCTION=3 THEN PRINT :INPUT " Enter the LEVEL " ; LEVEL 5 PRINT:INPUT " Enter the HOUSECODE (A-P) " ; A$: HOUSECODE=ASC(A$) - 64 6 PRINT:INPUT " Enter the value for HIUNIT (=NONE) " ; HIUNIT 7 PRINT:INPUT " Enter the value for LOUNIT (=NONE) " ; LOUNIT 8 GOSUB 25: IF STATUS =-1 THEN PRINT " *** ERROR***" : END 9 PRINT " The X-10 message has been sent" : END 10. DOWNLOADING GRAPHICS DATA LINE 21 Variables passed to the sub-routine ADDRESS ( - 255) Data stored in Basic array GRAPH (, ADDRESS) ( - 254) GRAPH (1, ADDRESS) ( - 254) Variables passed from the sub-routine STATUS (-1, , 1) This sub-routine takes the data stored in the Basic arrays GRAPH (, ADDRESS) and GRAPH (1, ADDRESS) and transfers it to the RAM in the INTERFACE. NOTE - The values stored in these arrays should never equal 255. An error will occur if this happens. EXAMPLE 1 CLS: PRINT " Downloading Graphics data " : PRINT 2 GOSUB 2 3 INPUT " Enter the ADDRESS (-255) " ; ADDRESS 4 PRINT : INPUT "DATA 1"; GRAPH (,ADDRESS) 5 PRINT : INPUT "DATA 2"; GRAPH (1, ADDRESS) 6 GOSUB 21 : IF STATUS =-1 THEN PRINT " ***ERROR*** " : END 7 PRINT " DONE " : END 11. UPLOADING GRAPHICS DATA LINE 211 Variables passed to the sub-routine NONE Variables passed from the sub-routine STATUS (-1, , 1) Data stored in Basic array GRAPH (, X) GRAPH (1, X) This sub-routine is used to request the Interface to upload ALL 256 pairs of GRAPHICS data and store them in a Basic array GRAPH (, X) and GRAPH (1, X) overwriting any data previously stored in the array. EXAMPLE 1 CLS : PRINT " Uploading Graphics Data " : PRINT 2 GOSUB 2 3 GOSUB 211 : IF STATUS =-1 THEN PRINT " ***ERROR*** " : END 4 PRINT " DONE " : END 12. DOWNLOADING TIMER EVENTS LINE 28 Variables passed to the sub-routine. ADDRESS ( - 127) Basic array. TIM (, ADDRESS) (Equals BYTE 2) TIM (1, ADDRESS) (Equals BYTE 2 1) TIM (2, ADDRESS) (Equals BYTE 2 2) TIM (3, ADDRESS) (Equals BYTE 2 3) TIM (4, ADDRESS) (Equals BYTE 2 4) TIM (5, ADDRESS) (Equals BYTE 2 5) TIM (6, ADDRESS) (Equals BYTE 2 6) TIM (7, ADDRESS) (Equals BYTE 2 7) Variables passed from the sub-routine. STATUS (-1, , 1) This sub-routine should only be used by programmers familiar with Binary Programming and the Timer Events downloading information on page 21 of the Programming Guide, supplied with the Interface. First set up the arrays with the data relating to the timed events required, and then call the sub-routine. The timer events will be transferred to the Interface and a STATUS = 1 will be returned if the download was successful. EXAMPLE 1 CLS : PRINT " Downloading a Timer Event " : PRINT 2 GOSUB 2 3 INPUT " Enter the ADDRESS ( - 127) " ; ADDRESS 4 FOR X = 1 to 7 5 PRINT " Enter the Data for BYTE"; 2+X; : INPUT TIM (X, ADDRESS) : NEXT X 6 GOSUB 28 : IF STATUS =-1 THEN PRINT " *** ERROR *** " : END 7 PRINT " DONE " : END 13. UPLOADING TIMER EVENTS LINE 29 Variables passed to the sub-routine. NONE Variables passed from the sub-routine. STATUS (-1, , 1) Data stored in Basic array TIM (, X) .....TIM (7, X) This sub-routine requests the Interface to upload ALL 128 Timer Events and store them in the Basic arrays TIM (, X) thru TIM (7, X). EXAMPLE 1 CLS : PRINT " Uploading Timer Event " : PRINT 2 GOSUB 2 3 GOSUB 29 : IF STATUS =-1 THEN PRINT " *** ERROR *** " : END 4 PRINT " DONE " : END 14. SOFTWARE LICENSE X-10 (USA) Inc. grants the user a non-exclusive license to use the X-10(R) POWERHOUSE(tm) software. The software is NOT copy protected and the user is encouraged to make back up copies. It is a good idea to keep a copy in a safe place such as in a friend's house. In fact why not make a copy for all your friends (we don't mind at all if they dash out to their local computer store and buy an Interface to use it with). X-10 (USA) Inc. makes no warranty as to the capability, capacity or suitability for use of the software, except as provided in this paragraph. Software is licensed on an "AS IS" basis, without warranty. The original CUSTOMER'S exclusive remedy, in the event of a software manufacturing defect, is it's repair or replacement within 12 months of the date of purchase. Some states do not allow limitations on how long an implied warranty lasts, so the above limitations may not apply to the CUSTOMER. X-10 (USA) Inc. 185A LeGrand Ave. Northvale, N. J. 07647 (201) 784-9700 or 1-800-526-0027 X-10 Home Controls Inc. 1200 Aerowood Dr., Unit 20 Mississauga, Ontario L4W 2S7 Canada (416) 624-4446