home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / vrac / x10ec130.zip / X10ECDOS.EXE / XDC.DOC < prev    next >
Text File  |  1996-05-31  |  13KB  |  317 lines
  1. --------------------------------------------------------------------
  2. XDC - X-10 Command Line Control
  3. --------------------------------------------------------------------
  4. Version 1.10
  5. May 1996
  6.  
  7. Copyright 1994-1996 - D.Huras - All Rights Reserved
  8.  
  9. -------------------------------------------------XDC.DOC v1.10------
  10. CONTENTS
  11. --------------------------------------------------------------------
  12.  1. DESCRIPTION
  13.  2. FEATURES
  14.  3. WARRANTY & LICENSE
  15.  4. COMMAND LINE ARGUMENTS
  16.  5. XDC DOS ENVIRONMENT VARIABLE
  17.  6. COMMUNICATION PORTS
  18.  7. X-10 COMMAND DIRECTIVES
  19.  8. PROGRAM OVERVIEW
  20.  9. XDC ERRORLEVELS
  21. 10. RELEASE HISTORY
  22.  
  23. 1. DESCRIPTION
  24. --------------------------------------------------------------------
  25. XDC is a command line driven program which sends 'immediate' command
  26. directives to the X-10 CP290 Computer Interface.  The CP290 will act
  27. on these directives and impose the requested X-10 command signals
  28. onto the powerline.  The registered version of XDC is supplied with
  29. the registered versions of X10DC (X-10 Direct Control) and X10EC
  30. (X-10 Event Control) as a registration incentive; it is not
  31. shareware and is not to be copied or distributed.
  32.  
  33. 2. FEATURES
  34. --------------------------------------------------------------------
  35. -XDC supports all of the X-10 Commands supported by X10DC/X10EC
  36.  including the 5 undocumented commands, specifically:
  37.    - ON/OFF/DIM
  38.    - ALL LIGHTS ON/OFF
  39.    - ALL UNITS OFF
  40.    - FADE-OFF
  41.    - X-LIGHT
  42.  
  43. -XDC supports 16 discrete brightness levels for the DIM Command.
  44.  
  45. -XDC supports the synchronization of the CP290 Clock to the PC Clock
  46.  or the converse.
  47.  
  48. -Standard Commports 1 - 4 are supported as well as a User Defined
  49.  CommPort that can be comprised of any IRQ + Base I/O Address.
  50.  
  51. -A single X-10 Command can be passed to XDC on the command line OR
  52.  multiple X-10 Commands can be passed to XDC by creating a file of
  53.  X-10 Commands and passing the filename to XDC using the /F command
  54.  line argument.
  55.  
  56. Note: You cannot target multiple units with a single X-10 command
  57.       directive using XDC except where multiple units are implied
  58.       (ie. ALL LIGHTS ON).
  59.  
  60. 3. WARRANTY & LICENSE
  61. --------------------------------------------------------------------
  62. XDC is supplied AS IS. The author disclaims all warranties,
  63. expressed or implied, including, without limitation, the warranties
  64. of merchantability and of fitness for any purpose.  The author
  65. assumes no liability for damages, direct or consequential, which may
  66. result from the use of XDC.
  67.  
  68. You may use the program on a single machine, and make a backup copy,
  69. but you are prohibited from making or transferring additional
  70. copies.
  71.  
  72. You acknowledge that you have read this license, understand it and
  73. agree to be bound by its terms as the complete and exclusive
  74. statement of the agreement between us, superseding any proposal or
  75. prior agreement, oral or written, and any other communications
  76. between us relating to the subject matter of this license.
  77.  
  78. 4. COMMAND LINE ARGUMENTS
  79. --------------------------------------------------------------------
  80. The following command line arguments can be entered in any order:
  81.  
  82. /Cn       - COMMPORT where n = 1,2,3 & 4 [DEFAULT: 1]
  83.  
  84. /Annnn(n) - Base I/O Address applicable to User Defined CommPort
  85.             (Must be specified as a decimal number)
  86.             If /I argument is present, but /A is not; then Base
  87.             I/O Address will default to 1016 (3F8 Hex).
  88.  
  89. /In       - IRQ applicable to User Defined CommPort where n = 1 - 15
  90.             If /A argument is present, but /I is not; then IRQ
  91.             will default to 4.
  92.  
  93. /F:[d]:\filespec - File Name containing X-10 Command directives
  94.                    to be pressed. (eg. /F:C:\X10\X10.CMD)
  95.  
  96. /Q       - Quiet Mode; Display no messages during program execution
  97.  
  98. /SYNC    - Synchronize CP290 using PC Clock (will wait until top of
  99.            the minute, i.e. seconds=0)
  100. /SYNCPC  - Synchronize PC Clock to CP290 Clock (immediate)
  101.  
  102. /?       - Display Command Line Arguments & Environment Variable syntax
  103.  
  104. h,u,c,l  - X-10 Command Directive where:
  105.            h = House Code (A - P)
  106.            u = Unit Code (1 - 16)
  107.            c = X-10 Command (ON,OFF,DIM,ALLLIGHTSON,ALLLIGHTSOFF,
  108.                ALLUNITSOFF,FADEOFF,XLIGHT)
  109.            l = Level (1 - 16) when applicable
  110.  
  111. Notes:- The /C argument will be ignored if either the /I or /A
  112.         argument is passed on the command line.
  113.       - Command line options override any settings stored within
  114.         DOS environment variable, XDC.
  115.       - Multiple occurrences of the same command line argument
  116.         are accepted; the last instance will be used by XDC.
  117.       - X-10 Commands ALLLIGHTSON,ALLLIGHTSOFF,ALLUNITSOFF can
  118.         be abbreviated to ALON,ALOFF,AUOFF respectively.
  119.       - The Clock Synchronization command line arguments are mutually
  120.         exclusive, if multiple arguments are included on the command
  121.         line only the last instance will be acted upon.  However, both
  122.         "SYNC" and "SYNCPC" can be included within command files passed
  123.         with the /F: argument.
  124.  
  125. 5. XDC DOS ENVIRONMENT VARIABLE
  126. --------------------------------------------------------------------
  127. To minimize program size and improve performance, XDC does not
  128. support an INI file of program parameters.  However, you can avoid
  129. using command line arguments by setting up a DOS environment
  130. variable that contains program settings.  The DOS environment
  131. variable 'XDC' is used to pass settings to XDC.EXE.  You use the
  132. DOS 'SET' command to assign a value to an environment variable.
  133. The syntax is:
  134.  
  135.   SET XDC=c,i,a,q
  136.  
  137.     where: c = CommPort (1 thru 4)
  138.            i = IRQ (1 - 15)
  139.            a = Base I/O address (must be > 0)
  140.            q = Quiet Mode
  141.  
  142. You do not need to specify values for parameters that you do
  143. not wish to change.  However, XDC environment variable parameters
  144. are positional so you must use comma's as placeholders if you
  145. wish to skip a parameter.  Trailing comma placeholders are not
  146. required.  Examples are shown below:
  147.  
  148.    To turn on Quiet Mode:      SET XDC=,,,Q
  149.  
  150.    To set CommPort to 2:       SET XDC=2
  151.  
  152.    To set CommPort to 2
  153.    and turn Quiet Mode On:     SET XDC=2,,,Q
  154.  
  155.    To set IRQ to 5:            SET XDC=,5
  156.  
  157.    To set IRQ to 5 and
  158.    Base I/O Address* 12832:    SET XDC=,5,12832 *specify in decimal
  159.  
  160. The DOS environment variable only needs to be SET once so a logical
  161. place for it is within your AUTOEXEC.BAT file.
  162.  
  163. Note: CommPort and IRQ+Base I/O Address are mutually exclusive
  164.       and you should set either one or the other.  If both are
  165.       set then IRQ+Base I/O Address override CommPort.
  166.  
  167. 6. COMMUNICATION PORTS
  168. --------------------------------------------------------------------
  169. XDC supports "pseudo standard" CommPorts 1 thru 4 using the
  170. following settings:
  171.  
  172.             +----------+------+------------------+
  173.             |          |      | Base I/O Address |
  174.             | CommPort | IRQ  +---------+--------+
  175.             |          |      | Decimal |  HEX.  |
  176.             +----------+------+---------+--------+
  177.             |    1     |   4  |  1016   |  3F8   |
  178.             +----------+------+---------+--------+
  179.             |    2     |   3  |   760   |  2F8   |
  180.             +----------+------+---------+--------+
  181.             |    3     |   4  |  1000   |  3E8   |
  182.             +----------+------+---------+--------+
  183.             |    4     |   3  |   744   |  2E8   |
  184.             +----------+------┴---------+--------+
  185.  
  186. If one of these CommPort settings matches your hardware
  187. configuration simply use the /C command line argument with the
  188. appropriate CommPort.  The XDC DOS Environment variable can also be
  189. used.
  190.  
  191. If your hardware configuration differs from the table above, then
  192. you can define your own CommPort by using the /I and /A command line
  193. arguments or by setting the XDC DOS Environment variable.  IRQ can
  194. be set to any value between 1 and 15 (inclusive).  Base I/O Address
  195. can be set to any value greater than zero.  CAUTION: your hardware
  196. may "lock up" if incorrect settings are used.  You should supply
  197. both arguments (/A & /I), however, if you only supply one of the
  198. arguments then the defaults applicable to CommPort 1 will apply to
  199. the other argument.  (eg. if only the /I5 argument is supplied, then
  200. the /A argument defaults to 1016).  Note that if XDC receives either
  201.  /I or /A or both, then any /C (CommPort) setting is ignored.
  202.  
  203. NOTES:
  204. ------
  205. 1) The Base I/L Address must be specified in decimal notation.
  206. 2) PS/2 Commports 3 - 8 must be specified using the /I and /A arguments.
  207.  
  208.           IBM PS/2 CommPort Parameters are shown below:
  209.             +----------+------+------------------+
  210.             |   PS/2   |      | Base I/O Address |
  211.             | CommPort | IRQ  +---------+--------+
  212.             |          |      | Decimal |  HEX.  |
  213.             +----------+------+---------+--------+
  214.             |    1     |   4  |  1016   |  3F8   |
  215.             |    2     |   3  |   760   |  2F8   |
  216.             |    3     |   3  | 12832   | 3220   |
  217.             |    4     |   3  | 12840   | 3228   |
  218.             |    5     |   3  | 16928   | 4220   |
  219.             |    6     |   3  | 16936   | 4228   |
  220.             |    7     |   3  | 21024   | 5220   |
  221.             |    8     |   3  | 21032   | 5228   |
  222.             +----------+------+---------+--------+
  223.  
  224. 7. X-10 COMMAND DIRECTIVES
  225. --------------------------------------------------------------------
  226. X-10 Command Directives are structured as follows:
  227.  
  228.   h,u,c,l
  229.  
  230. where: h = House Code (A - P)
  231.        u = Unit Code (1 - 16) [Not Required for Global Commands]
  232.        c = X-10 Command:
  233.             ON
  234.             OFF
  235.             DIM
  236.             ALL LIGHTS ON [can abbreviate to: ALON]*Global Command
  237.             ALL LIGHTS OFF [can abbreviate to: ALOFF]*Global Command
  238.             ALL UNITS OFF [can abbreviate to: AUOFF]*Global Command
  239.             FADEOFF [Dim Light to 1 then OFF]
  240.             XLIGHT [Exclusive Bright Light]
  241.        l =  Level [Only REQUIRED for DIM, but also accepted for
  242.             ALL LIGHTS OFF + XLIGHT]
  243.  
  244. The h,u,c,l parameters are positional within the X-10 Command
  245. Directive and the order cannot be changed. To skip a parameter it is
  246. necessary to include a comma as a place holder.  Any extraneous
  247. parameters will be accepted (and ignored). Examples are shown
  248. below:
  249.       A,1,ON      Turn device A1 ON
  250.       A,1,DIM,16  DIM device A1 to 16 (Maximum Brightness)
  251.       A,,ALON     Turn all Lights on House Code A ON
  252.  
  253. 8. PROGRAM OVERVIEW
  254. --------------------------------------------------------------------
  255. When the program loads, it looks for the XDC variable in the DOS
  256. Environment and then proceeds to parse it if found.  If any errors
  257. are detected then the program will terminate with an appropriate
  258. message, otherwise it will parse the command line arguments (which
  259. override the XDC environment variable).   Once again, if any errors
  260. are found it will terminate with an appropriate message.  If the
  261. /SYNC or /SYNCPC argument is found on the command line it will be
  262. processed before any X-10 command directives on the command line.
  263.  
  264. If the /F: argument was included on the command line then XDC will
  265. attempt to open the file and process the X-10 command directives.
  266. Otherwise, XDC will look for a X-10 command directive on the command
  267. line and execute it.  Note: If both the /F: argument AND an X-10
  268. Command Directive name are passed on the command line, XDC will
  269. ignore the X-10 Command directive from the Command line and process
  270. the X-10 Command Directives within the file specified with /F:.
  271.  
  272. If XDC encounters an invalid X-10 command directive it will
  273. terminate with a message displaying the offending directive.  When
  274. XDC sends a command directive to the CP290, it waits for an
  275. acknowledgement before sending another command directive.
  276.  
  277. 9. XDC ERRORLEVELS
  278. --------------------------------------------------------------------
  279. XDC will return one of the following ERRORLEVELS to the operating
  280. system upon program termination.
  281.  
  282. Normal Termination
  283. ------------------
  284.  0 - Program terminated normally; no errors
  285.  
  286. Execution Errors
  287. ----------------
  288. 97 - CP290 returned bad Checksum
  289. 98 - CP290 did not respond
  290. 99 - Fatal Communications Error
  291.  
  292. Syntax Errors
  293. -------------
  294.  1 - Invalid COMMPORT on Command Line
  295.  2 - Invalid IRQ on Command Line
  296.  3 - Invalid BASE I/O Address on Command Line
  297.  5 - Invalid FileName on Command Line
  298.  6 - Invalid Command Line Argument
  299.  7 - No X-10 Command to execute
  300.  8 - Invalid XDC DOS Environment Variable
  301.  9 - Invalid COMMPORT in XDC Variable
  302. 10 - Invalid IRQ in XDC Variable
  303. 11 - Invalid BASE I/O Address in XDC Variable
  304. 14 - Invalid X-10 Command
  305. 15 - Invalid House Code in X-10 Command
  306. 16 - Invalid Unit Code in X-10 Command
  307. 17 - Invalid Dim Level in X-10 Command
  308.  
  309. 10. RELEASE HISTORY
  310. --------------------------------------------------------------------
  311. VERSION    DATE     REVISION DESCRIPTION
  312. =======  =========  ================================================
  313.   1.10   May   '96  ∙Clock Sychronization feature added
  314.   1.01   Oct.  '94  ∙Respect for X10DC & X10EC Registration Keys added
  315.   1.00   April '94  ∙First Release
  316.   1.0ß   April '94  ∙Initial Beta Version
  317.