1 2 Installing Heyu on a Unix-like system. 3 4(This file is duplicated as both INSTALL and README.INSTALL, in the 5event your case-insensitive file system overwrites INSTALL with the 6install script.) 7 8Heyu requires a reasonable compiler (GCC works well), the 'make' program, 9and the development header (.h) files. Many OS distributions will either 10install these by default or provide a visible option to include the 11"development package" during OS installation. But some of the newer OS's 12do not, e.g., with Ubuntu Linux it's necessary to afterward execute the 13command 'apt-get install build-essential'. 14 15Note: If you're upgrading from a previous version of Heyu, run 'heyu stop' 16under that version before proceeding. 17 18Quickstart: 19 sh ./Configure [option] (As a normal user) 20 make (As a normal user) 21 su (Become superuser) 22 make install (As superuser) 23 exit (Revert to normal user) 24 heyu info (As a normal user, to test installation) 25 26(The 'make install' requires that you have write permissions to 27/usr/local/bin, man page, and other directories.) 28 29Ubuntu Linux users should execute 'sudo make install' rather than 30the three commands 'su', 'make install', and 'exit'. 31 32*** Kindly report any compile errors or warnings to the author.*** 33 34It can take 5-8 seconds to set up the heyu_relay daemon and initialize 35the CM11A interface the first time Heyu is run, e.g., with 'heyu info'. 36 37Running 'heyu help' will display the long list of Heyu commands. 38These are further explained in the man page heyu(1). 39 40CUSTOMIZING 41----------- 42The Configure script creates a Makefile by running 'uname -s' and then 43adding known good configuration options to the Makefile. The contents 44of Makefile.in is then appended to the Makefile. Changes to the makefile 45should be made in Configure or Makefile.in. 46 47If Configure can not figure out what your system is, you can try 48sh ./Configure generic 49 or 50sh ./Configure sysv 51 52If those don't work, we'll have to figure it out by hand. Please contact 53the author so your discoveries can be integrated into the next release. 54 55SERIAL PORTS 56------------ 57Many newer computers don't have built-in RS232 serial ports, only USB 58ports. For these computers a USB-Serial adapter is required to connect 59the CM11A. Before purchasing a USB-Serial adapter, verify that the driver 60for your OS is available, either built-in to the OS, provided with the 61adapter on a companion disc, or downloadable from the adapter 62manufacturer's website. 63 64If you have a choice, select an adapter with an FTDI chipset over one 65with a Prolific chipset. One dealer who specifies the chipset 66and supported operating systems for each adapter model for sale is 67ByteRunner (http://ww.byterunner.com). 68 69Drivers for adapters with a Prolific PL2303 chipset can often be found 70at http://www.prolific.com.tw/eng/downloads.asp?ID=31 71 72For Linux, the serial device name for a USB-Serial adapter will normally 73be /dev/ttyUSBx, where x = 0 for the first adapter plugged into the 74USB port and higher numbers for subsequent adapters. 75 76Note: The International 230V version of the CM11 sold in Europe and 77elsewhere is now usually provided with a USB cable in addition to the 78standard RS232 cable. Many Linux users have experienced lockups and 79other problem with this USB cable (based on a Prolific chipset) which 80disappeared when they switched to a regular USB-Serial adapter. 81 82OPTIONS 83------- 84By default, Heyu allocates space for 32 common flags, 32 counters, and 8532 user countdown timers. The number of each of these can be increased 86at compile time with switches -flags=NN, -counters=NN, and -timers=NN. 87The specified NN must be in the range 1-1024 and will be rounded up to 88the nearest multiple of 32, e.g., 89 90 sh ./Configure -flags=64 -timers=75 91 92will allocate space for 64 flags and 96 timers, the latter because 93the specified 75 is rounded up to 96. The number of counters will 94remain 32. 95 96By default, support for the X10 CM17A "Firecracker" device is compiled 97into Heyu. As there is no known version of this device available which 98transmits at frequencies other than the 310 MHz used for transceivers 99in North America, users outside this region may wish to compile without 100CM17A support. Since the CM17A is both powered and actuated by the DTR 101and RTS serial lines, support for this device might as well also be 102omitted if your serial port hardware does not support these lines. 103To do so, run the Configure step mentioned above with the '-nocm17a' 104switch, i.e., 105 106 sh ./Configure -nocm17a 107 108By default, support for Extended Type 0 (Shutter and Shade) commands 109is compiled into Heyu. As there is only one module known to support 110these commands (the 230V, 50Hz Marmitek SW10 Shutter Motor Controller 111sold in Europe), this support may be omitted by using Configure with 112the '-noext0' switch, i.e., 113 114 sh ./Configure -noext0 115 116By default, support for RFXSensors is compiled into Heyu. RFXSensors 117require a WGL W800RF32 or RFXCOM X10 RF receiver as well as a RFXSensor 118transmitter. This support may be omitted by including the '-norfxs' 119switch with Configure, i.e., 120 121 sh ./Configure -norfxs 122 123By default, support for RFXMeters is compiled into Heyu. RFXMeters 124requires a 433.92 MHz RFXCOM X10 RF receiver as well as the RFXMeter 125transmitter. This support may be omitted by including the '-norfxm' switch 126with Configure, i.e., 127 128 sh ./Configure -norfxm 129 130By default, support for the Digimax 210 remote thermostat is compiled 131into Heyu. The Digimax requires a 433.92 MHz RFXCOM X10 RF receiver as 132well as the Digimax transmitter. This support may be omitted by 133including the '-nodmx' switch with Configure, i.e., 134 135 sh ./Configure -nodmx 136 137By default, support for Oregon RF sensors is compilied into Heyu. 138Oregon sensor support requires a 433.92 MHz RFXCOM X10 RF receiver 139as well as a supported model of Oregon sensor. This support may be 140omitted by including the '-noore' switch with Configure, i.e., 141 142 sh ./Configure -noore 143 144By default, support for signals received from KaKu and HomeEasy 145transmitters is compiled into Heyu. KaKu/HomeEasy support requires a 146433.92 MHz RFXCOM X10 RF receiver. This support may be omitted 147by including the '-nokaku' switch with Configure, i.e., 148 149 sh ./Configure -nokaku 150 151 152Notes for Mac OS X: 153------------------- 154The heyu executable is installed in directory /usr/local/bin, which 155is not on the Mac's default PATH. You will have to add this directory 156to your $PATH. Similarly you may have to add the man page directory 157/usr/local/man to your $MANPATH (or the /usr/share/misc/man.conf file 158for newer versions of OS X which have deprecated $MANPATH). 159 160Newer Macs don't have an actual RS232 serial port, only a USB port, 161and a USB/Serial adapter is required. The manufacturer's adapter 162driver will usually add two or more different devices in /dev 163(and often with "usbserial" as part of the name). You'll have 164to experiment to see which one works with Heyu by trying the 165different names in the TTY directive in the heyu configuration 166file. The device name which also includes "cu" rather than "tty" 167has been found to work on the (few) Macs tested thusfar. 168 169 170Notes for AT&T SysV r4: 171---------------------- 172The function uname(1) used to determine the system type for 173Configure does not distinguish this OS from other sysv systems. 174Supply the system type parameter "attsvr4" to Configure, i.e., 175run 'sh ./Configure attsvr4'. 176 177Notes for OpenSolaris: 178--------------------- 179The directories in which the Heyu binary executable and man pages 180are installed are set per the OpenSolaris system conventions to: 181 BIN = /opt/heyu/bin 182 MAN = /opt/heyu/man/man1 183 MAN5 = /opt/heyu/man/man5 184However for a virgin OS installation, none of these directories 185are on the system's PATH/MANPATH and the user is responsible 186for adding them to the PATH/MANPATH in order to have full use of 187Heyu. 188 189The user may alternatively rerun Configure for "OpenSolaris_BSD", i.e., 190 sh ./Configure opensolaris_bsd 191which will set the directories using the BSD convention under 192the /usr/local tree, which however may be deleted when OpenSolaris 193is upgraded. 194 195Some older versions of OpenSolaris, in particular SXCE (Solaris 196Express Community Edition), may encounter an error when running 197'make install' like "test: argument expected". If this occurs, 198change the first line of file install.sh to read "#!/bin/ksh". 199 200 201 202