C Other Shell
Latest commit 194c202
Mar 22, 2015
Conflicts: Makefile.in - resolved by running autoreconf
Installing Heyu on a Unix-like system. Heyu requires a reasonable compiler (GCC works well), the 'make' program, and the development header (.h) files. Many OS distributions will either install these by default or provide a visible option to include the "development package" during OS installation. But some of the newer OS's do not, e.g., with Ubuntu Linux it's necessary to afterward execute the command 'apt-get install build-essential'. Note: If you're upgrading from a previous version of Heyu, run 'heyu stop' under that version before proceeding. Quickstart: sh ./Configure.sh [option] (As a normal user) make (As a normal user) su (Become superuser) make install (As superuser) exit (Revert to normal user) heyu info (As a normal user, to test installation) (The 'make install' requires that you have write permissions to /usr/local/bin, man page, and other directories.) Ubuntu Linux users should execute 'sudo make install' rather than the three commands 'su', 'make install', and 'exit'. Advanced users and package maintainers may also wish to refer to dedicated sections at the bottom of this file. *** Kindly report any compile errors or warnings to the author.*** It can take 5-8 seconds to set up the heyu_relay daemon and initialize the CM11A interface the first time Heyu is run, e.g., with 'heyu info'. Running 'heyu help' will display the long list of Heyu commands. These are further explained in the man page heyu(1). CUSTOMIZING ----------- The Configure.sh script creates a Makefile by running 'uname -s' and then passing known good options to Autoconf configure script. The contents of Makefile.in is then expanded to the Makefile. Changes to the makefile should be made in Configure.sh or Makefile.in. If Configure.sh can not figure out what your system is, you can try sh ./Configure.sh generic or sh ./Configure.sh sysv If those don't work, we'll have to figure it out by hand. Please contact the author so your discoveries can be integrated into the next release. SERIAL PORTS ------------ Many newer computers don't have built-in RS232 serial ports, only USB ports. For these computers a USB-Serial adapter is required to connect the CM11A. Before purchasing a USB-Serial adapter, verify that the driver for your OS is available, either built-in to the OS, provided with the adapter on a companion disc, or downloadable from the adapter manufacturer's website. If you have a choice, select an adapter with an FTDI chipset over one with a Prolific chipset. One dealer who specifies the chipset and supported operating systems for each adapter model for sale is ByteRunner (http://ww.byterunner.com). Drivers for adapters with a Prolific PL2303 chipset can often be found at http://www.prolific.com.tw/eng/downloads.asp?ID=31 For Linux, the serial device name for a USB-Serial adapter will normally be /dev/ttyUSBx, where x = 0 for the first adapter plugged into the USB port and higher numbers for subsequent adapters. Note: The International 230V version of the CM11 sold in Europe and elsewhere is now usually provided with a USB cable in addition to the standard RS232 cable. Many Linux users have experienced lockups and other problem with this USB cable (based on a Prolific chipset) which disappeared when they switched to a regular USB-Serial adapter. OPTIONS ------- By default, Heyu allocates space for 32 common flags, 32 counters, and 32 user countdown timers. The number of each of these can be increased at compile time with switches -flags=NN, -counters=NN, and -timers=NN. The specified NN must be in the range 1-1024 and will be rounded up to the nearest multiple of 32, e.g., sh ./Configure.sh -flags=64 -timers=75 will allocate space for 64 flags and 96 timers, the latter because the specified 75 is rounded up to 96. The number of counters will remain 32. By default, support for the X10 CM17A "Firecracker" device is compiled into Heyu. As there is no known version of this device available which transmits at frequencies other than the 310 MHz used for transceivers in North America, users outside this region may wish to compile without CM17A support. Since the CM17A is both powered and actuated by the DTR and RTS serial lines, support for this device might as well also be omitted if your serial port hardware does not support these lines. To do so, run the Configure.sh step mentioned above with the '-nocm17a' switch, i.e., sh ./Configure.sh -nocm17a By default, support for Extended Type 0 (Shutter and Shade) commands is compiled into Heyu. As there is only one module known to support these commands (the 230V, 50Hz Marmitek SW10 Shutter Motor Controller sold in Europe), this support may be omitted by using Configure.sh with the '-noext0' switch, i.e., sh ./Configure.sh -noext0 By default, support for RFXSensors is compiled into Heyu. RFXSensors require a WGL W800RF32 or RFXCOM X10 RF receiver as well as a RFXSensor transmitter. This support may be omitted by including the '-norfxs' switch with Configure.sh, i.e., sh ./Configure.sh -norfxs By default, support for RFXMeters is compiled into Heyu. RFXMeters requires a 433.92 MHz RFXCOM X10 RF receiver as well as the RFXMeter transmitter. This support may be omitted by including the '-norfxm' switch with Configure.sh, i.e., sh ./Configure.sh -norfxm By default, support for the Digimax 210 remote thermostat is compiled into Heyu. The Digimax requires a 433.92 MHz RFXCOM X10 RF receiver as well as the Digimax transmitter. This support may be omitted by including the '-nodmx' switch with Configure.sh, i.e., sh ./Configure.sh -nodmx By default, support for Oregon RF sensors is compilied into Heyu. Oregon sensor support requires a 433.92 MHz RFXCOM X10 RF receiver as well as a supported model of Oregon sensor. This support may be omitted by including the '-noore' switch with Configure.sh, i.e., sh ./Configure.sh -noore By default, support for signals received from KaKu and HomeEasy transmitters is compiled into Heyu. KaKu/HomeEasy support requires a 433.92 MHz RFXCOM X10 RF receiver. This support may be omitted by including the '-nokaku' switch with Configure.sh, i.e., sh ./Configure.sh -nokaku By default, support for RFXLAN RF receiver (network version of RFXCOM) is compiled into Heyu. This support may be omitted by including the '-norfxlan' switch with Configure.sh, i.e., sh ./Configur.sh -norfxlan By default, support for the xPL protocol (an open protocol intended to permit the control and monitoring of home automation devices) is not compiled into Heyu. This support may be enabled by including the '-xpl' switch with Configure.sh, i.e., sh ./Configur.sh -xpl The -xpl switch can take an argument, separated with a '=' sign, which can be used to specify a location of xPLLib files, required for building xPL enabled Heyu unless the xPLLib package has already been installed into a standard system location. That argument can point to a non-standard directory where an xPLLib package files have been installed (like /opt/xPLLib, for example), or to a local directory where xPLLib sources have been unpacked, or to a local file containing a gzipped tarball or other supported archive of those sources, or to a network location where that archive can be downloaded from. If that argument is not provided, and no xPLLib files can be found in standard system locations, the ./Configure.sh script will provide the 'make' utility with a primary network location of the xPLLib sources, i.e., http://www.xpl4java.org/xPL4Linux/downloads/xPLLib.tgz, to try to download the xPLLib tarball from and use it. Then, a working wget or curl utility, as well as a tool for unpacking the archive may be required to build Heyu successfully. Notes for Mac OS X: ------------------- The heyu executable is installed in directory /usr/local/bin, which is not on the Mac's default PATH. You will have to add this directory to your $PATH. Similarly you may have to add the man page directory /usr/local/man to your $MANPATH (or the /usr/share/misc/man.conf file for newer versions of OS X which have deprecated $MANPATH). Newer Macs don't have an actual RS232 serial port, only a USB port, and a USB/Serial adapter is required. The manufacturer's adapter driver will usually add two or more different devices in /dev (and often with "usbserial" as part of the name). You'll have to experiment to see which one works with Heyu by trying the different names in the TTY directive in the heyu configuration file. The device name which also includes "cu" rather than "tty" has been found to work on the (few) Macs tested thusfar. Notes for AT&T SysV r4: ---------------------- The function uname(1) used to determine the system type for Configure.sh does not distinguish this OS from other sysv systems. Supply the system type parameter "attsvr4" to Configure.sh, i.e., run 'sh ./Configure.sh attsvr4'. Notes for OpenSolaris: --------------------- The directories in which the Heyu binary executable and man pages are installed are set per the OpenSolaris system conventions to: BIN = /opt/heyu/bin MAN = /opt/heyu/man/man1 MAN5 = /opt/heyu/man/man5 However for a virgin OS installation, none of these directories are on the system's PATH/MANPATH and the user is responsible for adding them to the PATH/MANPATH in order to have full use of Heyu. The user may alternatively rerun Configure.sh for "OpenSolaris_BSD", i.e., 'sh ./Configure.sh opensolaris_bsd', which will set the directories using the BSD convention under the /usr/local tree, which however may be deleted when OpenSolaris is upgraded. Some older versions of OpenSolaris, in particular SXCE (Solaris Express Community Edition), may encounter an error when running 'make install' like "test: argument expected". If this occurs, change the first line of file install.sh to read "#!/bin/ksh". Notes for advanced users and (binary) package maintainers: ---------------------------------------------------------- From now on, you can use standard Autotools methods to build your package instead of dealing with the old Configure.sh, Makefile.in and install.sh. See INSTALL for generic instructions. Default runtime directories passed through ./configure to make: SYSBASEDIR SYSCONFDIR/heyu, or just SYSCONFDIR if already containing 'heyu' in its path; for example, if you specify --prefix=/opt/heyu, then SYSCONFDIR will be set to /opt/heyu/etc, and SYSBASEDIR will end up as SYSCONFDIR; override with CPPFLAGS='... -DSYSBASEDIR=\"path\" ...' LOCKDIR LOCALSTATEDIR/lock; override with CPPFLAGS='... -DLOCKDIR=\"path\" ...' SPOOLDIR LOCALSTATEDIR/tmp/heyu; override with CPPFLAGS='... -DSPOOLDIR=\"path\" ...' and in case of xPL support enabled: XPLCONFDIR same as SPOOLDIR; override with CPPFLAGS='... -DXPLCONFDIR=\"path\" ...' Default installation directories passed through ./configure to 'make install': heyu binary BINDIR heyu.1 man page MANDIR/man1; override with 'man1dir=<path>' (for example, SCO used to install in /usr/local/man/man.1) *.5 man pages MANDIR/man5; override with 'man1dir=<path>' (SCO case) README, etc. DOCDIR x10*.sample SYSBASEDIR To install individual components selectively instead of all at once, use 'make install-exe', 'make install-man1', 'make install-man5' (or 'make install-man' for both man sets), 'make install-dist_docDATA' and 'make install-dist_pkgsysconfDATA' (or just 'make install-data' for non-exe parts all together) respectively. Heyu custom post-install.sh (formerly install.sh) script is no longer run by 'make install' unless instructed with --enable-postinst[=<path>]. Other than that, you are free to select your own preferred or system dependent values for CC, CPP, CFLAGS, CPPFLAGS, LDFLAGS and LIBS, as well as your preferred --enable/--disable or --with/--without options and FLAGS=n / COUNTERS=n / TIMERS=n arguments (see ./configure --help for details). Building with xPL support enabled --------------------------------- When building Heyu with xPL suppport enabled (i.e., with the --with-xpl ./configure option provided), the required xPLLib library can be built automatically, then linked statically into the Heyu binary, within a single 'make' invocation. This attempt will happen if either xPL.h or libxPL.so file cannot be found, neither in standard nor CPPFLAGS / LDFLAGS provided locations, and a directory name containing unpacked xPLLib sources, or a name of a file or URL location where xPLLib sources can be downloaded / unpacked from over the HTTP or FTP protocol, is provided as an argument to the --with-xpl ./configure option. If so, a working wget or curl utility, as well as a tool for unpacking the archive may be required in oredr to build Heyu successfully. In that case, an xPL_Hub daemon, required for the xPL enabled Heyu to work properly, can also be built, using 'make xPLHub', from sources found in the 'examples' subdirectory among those unpacked xPLLib source files. Moreover, if the --enable-postinst option is provided to ./configure, then the hub binary will be built automatically with 'make', provided that no running xPL hub is detected nor known xPL hub executable found in the $PATH at build time, then automatically installed with 'make install' along with the Heyu executable unless a running hub is detected at install time. However, if an xPLLib package has already been installed in the target system or a staging area, but its header and library files sit in a non-standard directory structure, not examined from ./configure by default, but included in the runtime default LD_LIBRARY_PATH, then providing suitable include and lib subdirectory names within "CPPFLAGS=..." and "LDFLAGS=..." arguments respectively should suffice to successfully build and run xPL enabled Heyu, compiled with the preinstalled xPL.h header, and linked dynamically to the preinstalled libxPL.so library. Obviously, no xPL hub can be built nor installed automatically with this method. It is possible to provide the ./configure script with a definition of a non-default directory name where xPL configuration files will be stored by appending it to the CPPFLAGS variable. The respective symbol name is XPLCONFDIR, and it defaults to the same value as the SPOOLDIR if not specified.