home *** CD-ROM | disk | FTP | other *** search
/ World of Ham Radio 1994 January / AMSOFT_1994.iso / misc / homectrl / prog / x10guide.txt < prev    next >
Encoding:
Text File  |  1993-12-31  |  12.5 KB  |  465 lines
  1.    X-10 POWERHOUSE
  2. BASIC UTILITY PROGRAM
  3.     FOR IBM(TM) &
  4.      COMPATIBLES
  5.  
  6.  
  7.  
  8. CONTENTS
  9.  
  10.  1. Introduction
  11.  2. Using the Utility Program
  12.  3. Variables
  13.  4. Sub-Routine Locations
  14.  5. Initializing the Communications Port
  15.  6. Setting the Real Time Clock
  16.  7. Reading the Real Time Clock
  17.  8. Setting the Base Housecode
  18.  9. Sending an Instant X-10 Code
  19. 10. Downloading Graphics Data
  20. 11. Uploading Graphics Data
  21. 12. Downloading Timer events
  22. 13. Uploading Timer Events
  23. 14. SOFTWARE LICENSE
  24.  
  25.  
  26.  
  27. 1. INTRODUCTION
  28.  
  29. If you like to write your own software, this manual is for you.
  30.  
  31. It is assumed that you are familiar with Basic programming and some knowledge of
  32. Binary programming will also be useful.  This manual should be sufficient to let
  33. you write simple Basic programs to set and read the Real Time Clock in the
  34. Interface and to turn modules on and off manually etc. For more complex programs
  35. involving "Timed Events" etc. you should refer to the Programming Guide which
  36. deals in more detail with Binary and Hex programming.
  37.  
  38. The Utility Program is written in Basic and stored in ASCII format to allow
  39. merging with an existing Basic Program. This lets you write programs in Basic
  40. and use sub-routines to perform functions such as setting the clock, uploading
  41. or downloading timer events etc.
  42.  
  43.  
  44.  
  45. 2. USING THE UTILITY PROGRAM
  46.  
  47. The Utility Program sub-routines occupy Basic lines 19999 - 372 and therefore
  48. any program using the sub-routines should leave these lines free. Alternatively
  49. you could re-number the sub-routines remembering to update the GOSUB addresses
  50. also.
  51.  
  52. There are two ways to load the Utilities.
  53.  
  54. 1. If you are writing a completely new program, you can  just LOAD "X1"
  55.  
  56. 2. If you are combining the Utilities with an existing program, (e.g. MY
  57. PROGRAM) you first load your existing program  i.e. LOAD "MY PROGRAM", then
  58. merge the Utilities into the memory area by MERGE "X1". Once merged your
  59. program is ready to run.
  60.  
  61. NOTE. If you forget to merge the Utilities, your prm will not run.
  62.  
  63.  
  64.  
  65. 3. VARIABLES
  66.  
  67. Below is a list of variables used by the Utility program. These variables should
  68. only be used in your program to transfer data between the main program and the
  69. sub-routine and vice versa.
  70.  
  71. A              FUNCTION
  72. A$             GRAPH (2, 256)
  73. ADDR1          HITEMP
  74. ADDR2          HIUNIT
  75. ADDRESS        HOURS
  76. BTEMP          HOUSECODE
  77. BASECODE       LEVEL
  78. CHKSUM         LOUNIT
  79. CODCONV (16)   MINS
  80. COUNT          PORT
  81. DAY            STATUS
  82. EVENT          TIM (8, 128)
  83. FTEMP          XTEMP
  84.  
  85.  
  86.  
  87. 4. SUB-ROUTINE LOCATIONS
  88.  
  89. The Utility Program has 9 sub-routines which give the Basic Programmer full
  90. control over the Interface. These are located at the following lines.
  91.  
  92. 2   Initializing the com. port / defining the variables.
  93. 21   Setting the real time clock in the interface.
  94. 22   Setting the base housecode in the Interface.
  95. 23   Reading the real time clock from the Interface.
  96. 25   Sending an INSTANT on or off X-10 code.
  97. 28   Downloading a Timer Event to the Interface.
  98. 29   Uploading ALL Timer Events from the Interface.
  99. 21   Downloading Graphics Data to the Interface.
  100. 211   Uploading ALL Graphics Data from the Interface
  101.  
  102. STATUS
  103. The Utility sub-routines return a status value indicating the following:
  104.  
  105. If 'STATUS = 1' then 'GOSUB' was successful.
  106. If 'STATUS = ' then 'GOSUB' was successful but the Interface indicated that it
  107. had been powered down and contains no data.
  108. If 'STATUS = -1' then 'GOSUB' was unsuccessful. This indicates that there may be
  109. a problem with the connections to the Interface or the Interface may not have
  110. power.
  111.  
  112.  
  113.  
  114. 5. SETTING THE COM PORT
  115.  
  116. LINE 2
  117.  
  118. This sub-routine initializes the communications port (COM1).
  119.  
  120. This sub-routine also assigns all the variables used within the utility
  121. sub-routines. It should be called at the beginning of a program and should only
  122. be called once. If called more than once an error will occur.
  123.  
  124. EXAMPLE
  125.  
  126. 1      GOSUB 2
  127.         Rest of the Basic Program.
  128.  
  129. 19999
  130.   '
  131.   '     Utilities
  132.   '
  133. 372
  134.  
  135.  
  136.  
  137. 6. SETTING THE REAL TIME CLOCK
  138.  
  139. To set the real time clock in the Interface.
  140.  
  141. LINE 21
  142.  
  143. Variables passed to the sub-routine.
  144. DAY     (1-7)
  145. HOURS   (-23)
  146. MINS    (-59)
  147.  
  148. Variables passed from the sub-routine.
  149. STATUS  (-1, , 1)
  150.  
  151. Before calling this sub-routine, first assign a value to DAY, HOURS and MINS.
  152. Then call the sub-routine. The values stored in DAY, HOURS and MINS will then be
  153. transferred to the Interface. On returning from the sub-routine the STATUS
  154. should be compared with the value -1 to ensure that the download was successful.
  155.  
  156. EXAMPLE
  157. 5       CLS:PRINT "Setting the real time clock"  : PRINT
  158. 1      GOSUB 2
  159. 2      INPUT "Enter the DAY (1= Sun, 7=Sat) "; DAY
  160. 3      INPUT "Enter the HOURS (-23) "; HOURS
  161. 4      INPUT "Enter the MINUTES (-59) "; MINS
  162. 5      GOSUB 21:IF STATUS =-1 THEN PRINT
  163.         "*** ERROR***": END
  164. 6      PRINT:PRINT "The time has been set": END
  165.  
  166.  
  167.  
  168. 7. READING THE REAL TIME CLOCK
  169.  
  170. LINE 23
  171.  
  172. Variables passed to the sub-routine
  173. NONE
  174.  
  175. Variables passed from the sub-routine
  176.  
  177. DAY     (1-7)
  178. HOURS   (-23)
  179. MINS    (-59)
  180. STATUS  (-1, , 1)
  181.  
  182. To read the time from the Interface, call the sub-routine. The time will then be
  183. transferred to the variables DAY, HOURS and MINS, providing the STATUS is not
  184. returned -1.
  185.  
  186. EXAMPLE
  187.  
  188. 1      GOSUB 2
  189. 2      GOSUB 23: IF STATUS =-1 THEN PRINT
  190.         "***ERROR***" :END
  191. 3      PRINT "DAY = "; DAY; "HOURS = "; HOURS;
  192.         "MINUTES = "; MINS
  193. 4      END
  194.  
  195.  
  196.  
  197. 8. SETTING THE BASE HOUSECODE
  198.  
  199. LINE 22
  200.  
  201. Variables passed to the sub-routine.
  202. BASECODE  (1-16)
  203.  
  204. Variables passed from the sub-routine.
  205. STATUS  (-1, , 1)
  206.  
  207. To set the Base Housecode in the Interface, first assign a value to BASECODE as
  208. shown below.
  209.         A=1     B=2     C=3     D=4
  210.         E=5     J=1    K=11    L=12
  211.         M=13    N=14    O=15    P=16
  212. Then call the sub-routine to change the Base housecode in the Interface.
  213.  
  214. NOTE. calling this sub-routine will erase all the data stored in the Interface.
  215.  
  216. EXAMPLE
  217. 5       CLS:PRINT "Setting the base Housecode": PRINT
  218. 1      GOSUB 2
  219. 2      INPUT "Enter Base Housecode"; A$:BASECODE=ASC
  220.         (A$) - 64
  221. 3      GOSUB 22: IF STATUS =-1 THEN PRINT
  222.         "***ERROR***" :END
  223. 4      PRINT:PRINT "The Base Housecode has been set" :END
  224.  
  225.  
  226.  
  227. 9. SENDING AN INSTANT X-10 CODE
  228.  
  229. LINE 25
  230.  
  231. Variables passed to the sub-routine.
  232.  
  233. FUNCTION
  234.  
  235. This is a number between 1 and 3. 1=ON  2=OFF  3=DIM.
  236.  
  237. LEVEL
  238.  
  239. This is a number between  and 15 which sets the intensity of the DIM command.
  240. If FUNCTION is set to 1 or 2, LEVEL will be ignored.
  241.  
  242. HOUSECODE
  243.  
  244. This is a value between 1 and 16 where A=1 and P=16.
  245.  
  246. LOUNIT
  247.  
  248. This is a bit mapped value corresponding to the unit codes 1 thru 8 as follows:
  249.  
  250.    1=128   2=64    3=32    4=16
  251.    5=8     6=4     7=2      8=1
  252.  
  253.  
  254. HIUNIT
  255.  
  256. This is a bit mapped value corresponding to the unit codes 9 thru 16 as follows:
  257.  
  258.    9=128   1=64   11=32   12=16
  259.    13=8    14=4     5=2    16=1
  260.  
  261.  
  262. Variables passed from the sub-routine.
  263.  
  264. STATUS       (-1, , 1)
  265.  
  266. FUNCTION     (1, 2, 3)
  267.  
  268. LOUNIT       ( - 255)
  269.  
  270. HIUNIT       ( - 255)
  271.  
  272. HOUSECODE    ( - 16)
  273.  
  274.  BASECODE    ( - 16)
  275.  
  276.  
  277. To transmit an X-10 code instantly, you must first assign values to FUNCTION,
  278. LEVEL, HOUSECODE, LOUNIT and HIUNIT relating to the code to be sent; then call
  279. the sub-routine. If the STATUS is not -1, the sub-routine will return the values
  280. of FUNCTION, LEVEL, HOUSECODE, LOUNIT and HIUNIT as sent to the Interface. These
  281. values can then be used by your program to verify the code sent.
  282.  
  283. EXAMPLE
  284. 1      GOSUB 2
  285. 2      LEVEL =
  286. 3      INPUT " Enter the FUNCTION (1=On 2=Off 3=Dim)"
  287.         ; FUNCTION
  288. 4      IF FUNCTION=3 THEN PRINT :INPUT " Enter the
  289.         LEVEL " ; LEVEL
  290. 5      PRINT:INPUT " Enter the HOUSECODE (A-P) " ; A$:
  291.         HOUSECODE=ASC(A$) - 64
  292. 6      PRINT:INPUT " Enter the value for HIUNIT
  293.         (=NONE) " ; HIUNIT
  294. 7      PRINT:INPUT " Enter the value for LOUNIT
  295.         (=NONE) " ; LOUNIT
  296. 8      GOSUB 25: IF STATUS =-1 THEN PRINT
  297.         " *** ERROR***" : END
  298. 9       PRINT " The X-10 message has been sent" : END
  299.  
  300.  
  301.  
  302. 10. DOWNLOADING GRAPHICS DATA
  303.  
  304. LINE 21
  305.  
  306. Variables passed to the sub-routine
  307. ADDRESS ( - 255)
  308.  
  309. Data stored in Basic array
  310. GRAPH (, ADDRESS)  ( - 254)
  311. GRAPH (1, ADDRESS)  ( - 254)
  312.  
  313. Variables passed from the sub-routine
  314. STATUS  (-1, , 1)
  315.  
  316. This sub-routine takes the data stored in the Basic arrays GRAPH (, ADDRESS)
  317. and GRAPH (1, ADDRESS) and transfers it to the RAM in the INTERFACE. NOTE - The
  318. values stored in these arrays should never equal 255. An error will occur if
  319. this happens.
  320.  
  321. EXAMPLE
  322. 1      CLS: PRINT " Downloading Graphics data " : PRINT
  323. 2      GOSUB 2
  324. 3      INPUT " Enter the ADDRESS (-255) " ; ADDRESS
  325. 4      PRINT : INPUT "DATA 1"; GRAPH (,ADDRESS)
  326. 5      PRINT : INPUT "DATA 2"; GRAPH (1, ADDRESS)
  327. 6      GOSUB 21 : IF STATUS =-1 THEN PRINT
  328.         " ***ERROR*** " : END
  329. 7      PRINT " DONE " : END
  330.  
  331.  
  332.  
  333. 11. UPLOADING GRAPHICS DATA
  334.  
  335. LINE 211
  336.  
  337. Variables passed to the sub-routine
  338. NONE
  339.  
  340. Variables passed from the sub-routine
  341. STATUS  (-1, , 1)
  342.  
  343. Data stored in Basic array      GRAPH  (, X)
  344.                                 GRAPH  (1, X)
  345.  
  346. This sub-routine is used to request the Interface to upload ALL 256 pairs of
  347. GRAPHICS data and store them in a Basic array GRAPH (, X) and GRAPH (1, X)
  348. overwriting any data previously stored in the array.
  349.  
  350. EXAMPLE
  351.  
  352. 1      CLS : PRINT " Uploading Graphics Data " : PRINT
  353. 2      GOSUB 2
  354. 3      GOSUB 211 : IF STATUS =-1 THEN PRINT
  355.         " ***ERROR*** " : END
  356. 4      PRINT " DONE " : END
  357.  
  358.  
  359.  
  360. 12. DOWNLOADING TIMER EVENTS
  361.  
  362. LINE 28
  363.  
  364. Variables passed to the sub-routine.
  365. ADDRESS  ( - 127)
  366.  
  367. Basic array.
  368.         TIM     (,  ADDRESS)   (Equals BYTE 2)
  369.         TIM     (1,  ADDRESS)   (Equals BYTE 2 1)
  370.         TIM     (2,  ADDRESS)   (Equals BYTE 2 2)
  371.         TIM     (3,  ADDRESS)   (Equals BYTE 2 3)
  372.         TIM     (4,  ADDRESS)   (Equals BYTE 2 4)
  373.         TIM     (5,  ADDRESS)   (Equals BYTE 2 5)
  374.         TIM     (6,  ADDRESS)   (Equals BYTE 2 6)
  375.         TIM     (7,  ADDRESS)   (Equals BYTE 2 7)
  376.  
  377. Variables passed from the sub-routine.
  378.  
  379. STATUS   (-1, , 1)
  380.  
  381. This sub-routine should only be used by programmers familiar with Binary
  382. Programming and the Timer Events downloading information on page 21 of the
  383. Programming Guide, supplied with the Interface.
  384.  
  385. First set up the arrays with the data relating to the timed events required, and
  386. then call the sub-routine. The timer events will be transferred to the Interface
  387. and a STATUS = 1 will be returned if the download was successful.
  388.  
  389. EXAMPLE
  390.  
  391. 1      CLS : PRINT " Downloading a Timer Event " : PRINT
  392. 2      GOSUB 2
  393. 3      INPUT " Enter the ADDRESS ( - 127) " ; ADDRESS
  394. 4      FOR X = 1 to 7
  395. 5      PRINT " Enter the Data for BYTE"; 2+X; : INPUT
  396.         TIM (X, ADDRESS) : NEXT X
  397. 6      GOSUB 28 : IF STATUS =-1 THEN PRINT
  398.         " *** ERROR *** " : END
  399. 7      PRINT " DONE " : END
  400.  
  401.  
  402.  
  403. 13. UPLOADING TIMER EVENTS
  404.  
  405. LINE 29
  406.  
  407. Variables passed to the sub-routine.
  408. NONE
  409.  
  410. Variables passed from the sub-routine.
  411.  
  412. STATUS  (-1, , 1)
  413.  
  414. Data stored in Basic array
  415.  
  416. TIM   (, X) .....TIM  (7, X)
  417.  
  418. This sub-routine requests the Interface to upload ALL 128 Timer Events and store
  419. them in the Basic arrays TIM (, X) thru TIM (7, X).
  420.  
  421. EXAMPLE
  422.  
  423. 1      CLS : PRINT " Uploading Timer Event " : PRINT
  424. 2      GOSUB 2
  425. 3      GOSUB 29 : IF STATUS =-1 THEN PRINT
  426.         " *** ERROR *** " : END
  427. 4      PRINT " DONE " : END
  428.  
  429.  
  430.  
  431. 14. SOFTWARE LICENSE
  432.  
  433. X-10 (USA) Inc. grants the user a non-exclusive license to use the X-10(R)
  434. POWERHOUSE(tm) software. The software is NOT copy protected and the user is
  435. encouraged to make back up copies. It is a good idea to keep a copy in a safe
  436. place such as in a friend's house. In fact why not make a copy for all your
  437. friends (we don't mind at all if they dash out to their local computer store and
  438. buy an Interface to use it with).
  439.  
  440. X-10 (USA) Inc. makes no warranty as to the capability, capacity or suitability
  441. for use of the software, except as provided in this paragraph. Software is
  442. licensed on an "AS IS" basis, without warranty. The original CUSTOMER'S
  443. exclusive remedy, in the event of a software manufacturing defect, is it's
  444. repair or replacement within 12 months of the date of purchase.
  445.  
  446. Some states do not allow limitations on how long an implied warranty lasts, so
  447. the above limitations may not apply to the CUSTOMER.
  448.  
  449.  
  450.  
  451. X-10 (USA) Inc.
  452. 185A LeGrand Ave.
  453. Northvale, N. J. 07647
  454. (201) 784-9700  or 1-800-526-0027
  455.  
  456.  
  457.  
  458. X-10 Home Controls Inc.
  459. 1200 Aerowood Dr., Unit 20
  460. Mississauga, Ontario L4W 2S7
  461. Canada
  462. (416) 624-4446
  463.  
  464.  
  465.