This file (docs/install.html) is for the installation instructions. The main MisterHouse documentation is in mh. A list of update announcements is in updates. There is also a FAQ to cover misc. topics and a TWiki web-based collaboration site at http://misterhouse.wikispaces.com for other user-supplied documentation.
Gordon Meyer wrote a somewhat dated but still nice getting started article.MisterHouse has been run on Windows >= XP and the unix OSes Linux, FreeBSD, AIX, and Mac OSX. In theory, much of the functionality should work on any platform that can run Perl.
In Windows http://www.activestate.com/activeperl/ from ActiveState is known to be compatible. The most recent version known to work is Perl 5.12 but later versions may work as well. The minimum Perl version is 5.8.
These are the quick instructions for those of you who just want to kick the tires. If you decide you want to use MisterHouse in a more meaningful way you should look at the detailed instructions which covers, among other things, separating your local files from the MisterHouse distribution to make upgrades easier.
Download the the MisterHouse stable zip file from the download page
unzip the downloaded file with your favorite unzip tool or Windows explorer. Avoid parent directories with spaces in the name (e.g. c:\program files\)
Open a Windows Command Prompt and cd into the \bin directory where you unziped MisterHouse
cd misterhouse-stable\bin
mh.bat (this will call mhe.exe if it exists or 'perl mh')
This is not the preferred way to run MisterHouse for long term use but will get you started quickly if you just want to check out the capabilities. Later you should create separate code/* and data/* directories so that you can upgrade MisterHouse without overwriting your own customizations.
Change into a base directory where you want MisterHouse to live
Download the the latest zip file from the download page
Unzip the file: unzip -aU stable.zip
cd misterhouse-stable/bin
./mhl (if that doesn't work, try: mh or perl mh)
If you are running rh 8 or rh 9, you may see a memory leak which you can avoid with by setting this env var: export LANG=C (set in the mhl script)
ctl-c will terminate the program
Point your web browser to http://localhost:8080 and try out a few commands. You can search or list commands using the 'Search String' menu from the Search icon in the upper right of the default /ia5 web page. To list all commands, search on a blank string.
The default setup runs only a few core scripts from code/common directory (listed in data_dir/code_select.txt). You can use the http://localhost:8080/bin/code_select.pl menu (default web page -> MrHouse Home -> Setup MrHouse -> Common Code Activation) to select other standard code files you want to run.
To quickly test many of the code files, run:
mh -code_select code_select_test.txtTo use less memory and cpu, or if you get graphics related errors, you can run without the local gui inteface with: mh -tk 0
Also try telnet localhost 1234 and type one of the commands you saw on the web interface (e.g. say something mean from code/common/goofy.pl).
See "Coding your own events" for info on how to customized MisterHouse.
I you already have perl installed, you only need to download the stable zip file. See the download page for instructions.
Change to the drive/directory you want MisterHouse installed to (e.g. c:\). Avoid directories with spaces in the name (e.g. c:\program files\). Files/dirs with spaces in them require special handling in perl code and MisterHouse has not been written with this in mind. Now unzip the file(s) using your un-zipper of choice (use the -d if using pkunzip to preserve the directory structure). Look in the misterhouse-stable/lib directory to make sure long file names were preserved (e.g. http_server.pl). If not, you can download unzip from http://misterhouse.net/public/unzip.exe.
Download and install Perl version 5.8 (or higher) from http://www.activestate.com/ActivePerl.
After installing the core Perl package, you will likely want to install a few optional packages. MisterHouse will run without them, but they are easy to install and give it more functionality. Activestate has provided ppm (Perl Package Manager), a nifty way of automatically downloading and installing packages. You will need to retrieve the following packages using the ActivePerl PPM:
GD
DBI
DBD-mysql
Scalar-List-Utils (if you want AOL im)
Tk (if you want the Tk interface rather than the HTML interface)All other required packages should either be in the MisterHouse distribution or is now installed by default in the standard Activestate distribution, including the Tk module (used to be separate).
Download the stable zip file. See the download page for instructions.
Install the file as detailed in the quick install instructions.
Make sure you use the -a to automatically get rid of those pesky /r characters that DOS like to add to newlines. Also, the unzip -U switch (contrary to what the help text says), will be needed on newer versions of unzip to preserve case on filenames.
You may need to run the configure script, even if you used the rpm file. This will convert C serial headers to perl headers and (if you used the zip file) delete dos/windows only files, and 'chmod +x' on the files in the bin directory.
If you get a "could not find ioctl" message when starting MisterHouse, that indicates that an include file (or one of its dependencies) defining some of the serial port details could not be found. These definitions are in different files for different distributions and the configuration script has logic to look for many of them. Note that the configuration script may generate errors finding some files that are not actually needed and can be ignored. If MisterHouse does output "could not find ioctl" after running the configuration script then debug can be turned on (edit the mh/lib/site/Device/SerialPort.pm file and make $DEBUG=1) and the program will then output which files it cannot find when MisterHouse is run. Note that this may also generate errors for files that are not on your system and not required. Probably, only ONE of the files needs to be found. The needed file will have the same name but a .h extension rather than .ph. The .ph file can be generated from the .h file with h2ph. (need to put in a few more notes or a link to info on h2ph about where it should be run from and where it gets its input file and puts the output file) If the config script does not work properly on your system please report it to the list.
To allow non-root users to run the bin/set_clock function, run this command:
chmod ug+s /bin/dateThere are various examples of how to start/stop MisterHouse in mh/bin/misterhouse*.rc
Most, if not all, UNIX installations now have perl installed by default. If for some reason, yours does not or if it is an older version of perl, you can downloaded the latest from http://www.perl.com .
Run 'perl -v' to show your version ... anything at or above 5.8 should be fine.
If you want to use the Tk interface (used to display logs and various pop-up messages), make sure that the perl Tk package is installed as well. If the Tk is not installed, this test will fail: perl -e "use Tk". If you need it, you can download perl Tk from http://www.perl.com/CPAN/ . If you can also try the CPAN installer like this:
>su root
>perl -MCPAN -eshell
cpan> install Tk
cpan> install Tk::JPEG
cpan> install Tk::CursorControl
cpan> install DB_File
cpan> install Term::ReadKey
cpan> install Time::HiRes
cpan> install Audio::Mixer (if on Linux)
cpan> install GD
cpan> install Text::LevenshteinXS
cpan> install DBI (if you want to interface to a database server)
cpan> install DBD::mysql (if you want to interface with a mysql server)
cpan> exitThe first time you run the CPAN code, it creates a configuration file. The defaults (press enter a bunch of times) usually is good for all questions except the one that ones you to pick which site to download from.
You may need to type "export FTP_PASSIVE=1" before "perl -MCPAN -eshell". This is because by default the CPAN installer will generally try to use active ftp sessions which may fail if you are behind some firewalls and/or if your ISP caches ftp sessions. By exporting the FTP_PASSIVE variable prior to running the CPAN installer session, passive connections will be used instead.
Dependencies for above modules: Tk requires an X-server be installed DB_File requires Berkley DB be installed Audio::Mixer requires kernel sound support GD requires several libraries installed: GD library, zlib library, png library
The perl install files contain README files which explain their dependencies.
There are some example start/stop/restart .rc files in mh/bin/misterhouse*.rc
You can skip this step if you do not want to enable VR or TTS.
The simplest and fastest TTS engine is flite, available from http://www.speech.cs.cmu.edu/flite . After compiling, point to where the flite binary is with the voice_text_file parm and set voice_text = flite. If on Linux, you can pick up a copy (3 meg, 7 meg unziped) here: http://misterhouse.net/public/flite.gz
The Festival Speech engine is available from http://www.cstr.ed.ac.uk/projects/festival/download.html . There are various voices and languages available. Compiling Fesitval can be a little tricky, so if you can, you will probably want to use the RPM files.
Once you have downloaded in and installed or compiled Festival, you can test it with the following commands:
echo 'Hello from Festival' | ./festival --tts
./festival --tts ../examples/example.sable
./festival --server &
echo '(SayText "Hello from the festival client")' | ./festival_clientYou can also run the client, or a simple telnet, from a different box, but you first have to create a /usr/lib/festival/lib/siteinit.scm file with a list of boxes that you want to give authority to. (e.g. (set! server_access_list '("localhost" "house\\.isl\\.net")) ). See the festival documentation for more details.
Ricky Buchanan reports ESD and festival --server doe not work, and suggests to instead edit /etc/festival.scm and add these lines to the top:
(Parameter.set 'Audio_Method 'Audio_Command)
(Parameter.set 'Audio_Command "/usr/bin/esdcat -m -r $SR $FILE")Making sure that /usr/bin/esdcat points to the right spot for the esdcat program.
David L. reports that there is a different engine for festival called MBROLA at http://tcts.fpms.ac.be/synthesis/mbrola.html that has a very nice US english male and female voice. Other source for festival voices can be found here: http://festvox.org/contrib.html
Once you have the festival server running, you can enable MisterHouse to use it with mh.ini parms voice_text and festival_port.
To set the default voices, find your siteinit.scm file and have fun with the following:
(set! voice_default 'voice_us1_mbrola)
(set! voice_male1 'voice_kal_diphone)
(set! voice_male2 'voice_us2_mbrola)
(set! voice_female 'voice_kal_diphone)This depends upon which voices you have installed on your system. Some voices are don_diphone, kal_diphone, ked_diphone, rab_diphone, us1_mbrola, us2_mbrola, and us3_mbrola
Another good TTS engine is now available from Cepstral: http://www.cepstral.com . $30 per voice, for either Linux or Windows. Set mh.ini parm voice_text=swift and modify voice_text_swift to point to the swift binary.
Prior to 11/2002, for $150, you can get 2 nice voices with AT&T Natural Voices TTS Linux engine here: http://www.naturalvoices.com (additional voices cost $70), but for some reason, they no longer sell them from there. Have not tried it, but this site is selling Linux voices for $50 each: https://secure.wizzardsoftware.com/voice/wizzshop1/nvshoplinux2.asp
If you have the Linux binary, use the voice_text_naturalvoice parm to point to where you have it installed and set voice_text=naturalvoice.
If you only have the windows binary, you can now use Wine to run it from Linux. On my 1.2 GHz Celeron, time-to-speech is about 1 second, -vs- about .4 seconds for the native Linux binary. See bin/mh.ini for examples on these parms: voice_text=NaturalVoiceWine, voice_text_naturalvoice=path_to_windows_voices, wine_path=path_to_wine.
The IBM ViaVoice TTS and Voice Recognition engines is no longer available (as of 05/2002) from the IBM site ( http://www-4.ibm.com/software/speech/dev/sdk_linux.html ), but can still be found here: http://www.ecn.purdue.edu/~laird/Linux/ViaVoice/ The TTS engines can also be found here: ftp://people.redhat.com/jlamb/
To use it with MisterHouse, you need to install Brad Reed's ViaVoiceTTS.pm module from http://www.reednet.org/ViaVoiceTTS , then set your mh.ini voice_text=vv_tts or voice_text=viavoice (vv_tts is a bit fancier, queuing up speech and has more mh.ini options).
Download and install (as root) these rpms:
tar -xvf viavoice_asr_sdk_3.tar ( 3 MB)
tar -xvf viavoice_dict_rtk_3.tar (78 MB)
rpm -ivh ViaVoice_runtime-3.0-1.2.i386.rpm
rpm -ivh ViaVoice_sdk-3.0-1.1.i386.rpmNote for our usage, you can get by without the gui menus, so if rpm tells you that you have down level or missing libraries (e.g. libgdk), you can probably ignore that by adding the rpm --nodeps option.
As the *.txt instructions from the tar file state, you should probably run the viavoice code as non-root. Here is one way to allow non-root access to the microphone:
chmod go+rw /dev/dsp*
chmod go+rw /dev/audio*Make sure your microphone is selected as the recording source with this command:
aumix -m R (-l R for line, -c R for CDROM)Documentation is in /usr/doc/ViaVoice and test and example code is in /usr/lib/ViaVoice/samples. /usr/doc/ViaVoice/rt.readme.txt suggests creating a new userid with this java app:
/usr/bin/vvstartuserguruIf that doesn't work, you can add a user with this command:
source /usr/bin/vvsetenv
/usr/lib/ViaVoice/bin/vvuser -userid winter -setdefaultTo enable viavoice from MisterHouse, review the viavoice_* parms in the mh.ini file (defaults should work if you run MisterHouse on the same box as the server), set parm voice_cmd=viavoice, run mh/bin/viavoice_server_start, start MisterHouse and enable the viavoice_control.pl from the 'Select Code' ia5 MrHouse web menu. Use the Tk 'VR mode' button and/or the phrase(s) in viavoice_awake_phrase to enable the awake VR mode.
The viavoice SDK FAQ can be found here at http://www-4.ibm.com/software/speech/dev/faq_linux.html .
For Apple OS X users, here are some hints from Jon Boehm:
1. Install Xdarwin, remember the 10.2 patch if your running Jaguar.
2. Upgrade Perl to 5.8 http://developer.apple.com/internet/macosx/perl.html
3. Install Perl modules required by MisterHouse.
Some of the packages will not install nicely. If something fails you
will need to do Goggle searches like: "OSX GD" to get some help.Specifically for GD get the translated version of this page "Installazione di php+apache+mysql su OSX" and note the packages that need to be installed before GD. Note: make sure XDarwin is running before you run "make test' for GD
Edit bin/mh.ini and change the appropriate parms. It should run just fine with the default parms, although your sunrise/sunset times will be for Rochester, MN :)
If you decide to use MisterHouse, you will want to copy the parms you change to your own parm file and point to that with the mh_parm environmental variable (see the mh.ini header for details).
If you are on Windows you may need to edit the last record of the mh.bat file to point to the correct directories where Perl and the MisterHouse are installed.
Next, cd to \mh\bin and then type: mh hello_print.pl. This will load the \mh\code\common\hello_print.pl file which is a simple event that prints some uptime info every 30 seconds. Since we did not include the tk*.pl members, the tk interface will not be displayed
From the console window, hit the ENTER key to bring up a control menu, then select the "Exit menu" item to exit. Or use Ctl-C.
Next, if you have installed the speech engines, try the hello_speak.pl event (e.g. mh hello_speak.pl). This will speak the time and date once a minute. It also creates one VR command.
If you are a Windows user and have the VR engine installed, make sure the green MSVoice V icon is in the "Listening for Voice Commands" mode, try saying, "What time is it?" You can list all the available commands by right clicking on the V and picking "What can I say?"
To run the standard code in the mh/code/common directory, do not specify any files (e.g. just type mh). Here are a few of the commands enabled by the mh/code/common files:
"What is the trivia question?" and "What is the trivia answer?"
"Read the deep thought"
"Say something nice"
"Say something mean"
"Set a timer for 5 minutes"
"When will the sun set"
"Say hello to bruce"Try "Set the clock via the internet" to set your computer's clock according to an atomic clock.
To send a test email to yourself, try "Send test email". This requires that you fill out the net_mail parms in the mh.ini file.
To retrieve and display the latest top 10 list from Letterman's Late Night show, try "Get the top 10 list".
You can control any of your serial, X10, and voice items with a frames capable web browser by pointing it to http://localhost:8080 . Note, the port number is controllable via mh.ini http_port parm. If you do not have any other web server running, you may want to change it from the default of 8080 to 80 so that you can use a simpler address of http://localhost .
You can also tailor the web interface to your liking by creating a new member in the \mh\web\mh directory and changing the html_file mh.ini parm.
In addition to the voice and web interfaces, you can type these commands on the Tk "Enter Command" field or from the DOS command line using the house command. For example, from a DOS command prompt, try typing: 'house Show the top 10 list' You can also speak or display any arbitrary phrase or file with the commands "Display file" or "Speak phrase" (e.g. 'house speak hi there'). These commands are simple bat files that create commands in the "xcmd_file", whose location is controlled with a mh.ini parm. You can have your own program put commands in this file as well. Lastly, you can type all these commands via a telnet localhost session or via a socket port, if you have the telnet.pl member enabled.
Here is a summary of the different ways you can control MisterHouse:
With a voice command
Through a web browser and whatever html you want to set up.
By typing a command on the Tk Control Window
By typing "house command" from a dos box
By having whatever program you want create a command in the xcmd_file
By a TCP socket, for example, using telnet localhostUse your favorite editor to edit the example code in mh/code/test/my_test.pl. On the MisterHouse window, use the F1 key to re-load your changed code. If you introduced an error, it will sound a long beep, spit out some errata showing the error, and then it re-loads the old error-free code. There is lots of other code you can peruse in the mh\code\bruce directory. This is all the code that runs our house!
Without any interface hardware, MisterHouse is pretty limited. It can do some simple time of day based events and voice based events, but that is about it. Currently, MisterHouse supports the X10 CM11 (aka ActiveHome) and CM17 (aka Firecracker) interfaces and all the Weeder kits (analog, digital, x10, phone, available from from http://www.weedtech.com ). Other supported hardware is listed in http://misterhouse.net/mh.html#List_of_supported_hardware_inter .
Currently, the X10 guys have a $50 deal for an ActiveHome kit, which includes the CM11 interface. Check it out at http://www.x10.com . See FAQ question 6.5 for more info on X10.
If you want more than just X10, you may want to go with the Weeder X10 Kit. One advantage of the Weeder kits is they can all share the same serial port. The X10 kit, however, costs more ($40 + $25 for a TW523 module if you don't already have that, $10 for a serial and a phone cable), and doesn't support the extended X10 data that the CM11 does (e.g. preset dims).
After plugging in the Weeder X10 kit or a CM11 interface into a free serial port, update the Weeder_port or cm11_port parm in the mh.ini file to point to that port and try a simple example, like test_x10.pl in the test directory.
If you are getting 'bad checksum from cm11' messages, MisterHouse is having problems talking to your cm11. If on windows, make sure the X10 ActiveHome software works to verify you have the right port. If on unix, you can try heyu: http://heyu.tanj.com
Support for any serial port device can be coded by using the generic Serial_Item objects. For example, a ham radio enthusiast has interfaced to his GPS (Global Positioning Satellite) to keep track of his car's location (see his tracking.pl code in the code/Public directory)
Support for any device that speaks with sockets over your network can be added using the Socket_Item objects.
After you have played with the the default test code for a bit, you will want to start setting up your own code and data directories. Here is an example:
c:--+
+--misterhouse--+
+--mh.private.ini <--- my private mh.ini parms
+--code <--- my code
+--data <--- my data
+--sounds <--- my sounds
+--mh-----+ <--- mh installed here
+--bin
+--code
+--data
+--docs
+--lib
+--sounds
+--web
+--mh_123-+ <--- Old mh 123 version
+--bin
+--code
+--data
+--docs
+--lib
+--sounds
+--webAssuming you have MisterHouse installed in c:\misterhouse\mh, the steps might looks something like this (using the DOS commands, as I think unix guys can make the translation :):
mkdir c:\misterhouse\code
mkdir c:\misterhouse\data
mkdir c:\misterhouse\sounds
copy c:\misterhouse\mh\code\common\trivia.pl c:\misterhouse\code
copy c:\misterhouse\mh\bin\mh.example.ini c:\misterhouse\mh.private.ini
xcopy c:\misterhouse\mh\data c:\misterhouse\data /s
edit c:\misterhouse\mh.private.ini
- Delete all the records from your mh.private.ini that you don't change
since the default mh\bin\mh.ini will also be read.
- Change these entries (note: Forward slashes are best in perl)
code_dir = C:/misterhouse/code
data_dir = C:/misterhouse/data
sound_dir = C:/misterhouse/sounds
Note that you should use /, not \, on paths, on Windows, just like Unix.
On windows, add this to your autoexec.bat:
set mh_parms=c:\misterhouse\mh.private.ini
On unix, add this to /etc/profile or like place:
export mh_parms=/prog/misterhouse/mh.private.iniYou can add your own custom code files to your private \misterhouse\code directory. The first thing you will want to do is create an items.mht file that declares all your X10 items (see mh/code/bruce/items.mht for an example). Alternatively, you can declare each of your X10_items in any of the code members you use it in. In either case you can use the "List X10 items" command created in mh_control.pl to review all your X10 items.
To enabled password protection, run mh/bin/set_password command like this:
set_password -user family -password xyz1
set_password -user admin -password xyz2Note: only the first 8 characters are used. The admin password is required for controlling the MisterHouse web setup menus (e.g. item and code selection menus).
When you want to upgrade to a newer version of MisterHouse, follow these steps:
cd \misterhouse
rename mh mh_old
unzip \downloads\misterhouse_src_###.zip
unzip \downloads\misterhouse_win_###.zip