Installation

There are links to specific installation notes for the popular platforms in the table below, however this page is intended to give the reader an overview of the steps involved and to help when things go wrong.

Platform	Installation notes
Raspberry Pi	Raspberry Pi
Windows	Active state perl install
Ubuntu	Ubuntu
BeagleBone Black	BeagleBone Black
Embedded devices	NSLU2 and Linksys WRT160NL
Sheeva plug	Sheeva plug

Overview of installation

The following steps are needed to install MisterHouse:

Get MisterHouse and install perl
Set up directory structure
Run MisterHouse for the first time
Check for missing perl modules
Take a look around
Add your devices
Add your perl code
Post install steps

Getting MisterHouse

The MisterHouse code base is maintained in the git repository that accompanies this wiki. You have the option to either download a release version or to checkout a version from the git repository. The option you choose depends on your goal: if you want just to download a file and to get started, you can download a release. On the other hand, if you want to be able to easily apply changes made by other developers, checking out the git repository is the way to go.

Whatever option you choose, the idea is to install the MisterHouse main code in a subfolder that is separated from your local code and settings. The reason to do so is that it is then easy to replace MisterHouse with a newer version without losing your local modifications.

To download a release version, head here and clone the repo or download the stable zipfile
To download the latest unstable development version get this zip archive
To clone the git repository, see the documentation here
To co-operate on the source code as a developer, see here

Finally check you have perl working with perl -version if this fails, or the version os older than 5.8, you will need to install perl for your environment. ActiveState has been tested on Windows with MisterhHouse.

Recommended MisterHouse directory structure

Note: the instructions below are the opinion of a single user. Other 'intro' articles on getting started with MisterHouse exist and are linked to at the bottom of this page.

The idea is to create a folder that can keep your local settings, and a folder that contains the MisterHouse base code. You already got a copy of that code from the previous step. Now, how to setup the system:

create the folder that will contain all Misterhouse code and custom settings, e.g. 'mrhouse'
cd into the folder
create a subfolder called 'misterhouse' and copy the content of the tgz file into it, or perform a git clone as described above.
create a folder called 'local'. This folder will contain your settings.
create a folder called 'data' and a folder called 'code' under local. Those folders will be used to store data and code for running MisterHouse.

The directory structure is now:

  mrhouse
   +-> misterhouse
   +-> local
        +-> code
        +-> data

Create a file called 'mh.private.ini' in the folder 'local'. This file will contain your custom settings to control certain settings of misterhouse.

A basic initial version of the mh.private.ini file should look like this:

code_dir=$Pgm_Root/../local/code
data_dir=$Pgm_Root/../local/data
gd=0
tk=0

Run MisterHouse for the first time

Unix systems

Create in the mrhouse folder a script file with this content:

export mh_parms=<absolute path to>/mrhouse/local/mh.private.ini
cd misterhouse/bin
./mhl

Windows

open a cmd window and navigate to where you pit the Misterhouse bin directory and run mh.bat, this will call mhe.exe if it exists or perl mh if not.

These script do the following: they tell MisterHouse where to find your custom settings, and then start the MisterHouse program.

If all goes well, you should be able to navigate to the web interface on http://youripaddress:yourport' substituting the IP address of your MisterHouse machine for youripaddress` and the port you set in your 'mh.private.ini' or 80.

Check for missing perl modules

If you get an error like

Can't locate Net/MQTT/Constants.pm in @INC (you may need to install the Net::MQTT::Constants module)

This means you need to install the missing perl module e.g. ppm install Net::MQTT::Constants or sudo cpan install Net::MQTT::Constants

You need to have installed all of the required modules before MisterHouse will start properly.

Take a look around

Navigate your browser to http://youripaddress:yourport and see the default functionality. 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://youripaddress:yourport/bin/code_select.pl menu or 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.txt

To use less memory and cpu, or if you get graphics related errors, you can run without the tk 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).

Adding your first devices

Devices are added in your items.mht file which is placed in the code_dir that you defined in your mh.private.ini file as described above and in this page. Please visit the Protocols and Interfaces and Items and methods pages to see how to define your devices to MisterHouse.

Post Install steps

The following steps may need to be done after you've got the basics working;

Install a speech engine
Make it Automatically run after boot
Develop a backup strategy
Implement a Watchdog. Note these instructions are for unix systems.
Add Resilience
Adding RRD to create graphs

Add your code

Create your perl code in the code_dir that you defined in your mh.private.ini. Its a good idea now to look at the distributed code_dir\bin\mh.ini file to see if there are any parameters you wish to override, e.g.;

data_dir               = /home/pi/mh/mydata
password_allow_clients = 127\.0\.0\.1,192\.168\.100\..+
password_protect       = all
tk                     = 0
http_port              = 8088
latitude               = 52
longitude              = 1
time_zone              = 0
time_format            = 24
date_format            = ddmmyyyy
time_format_log        = 12
default_temp           = Celsius
speak_engine           = festival
voice_text             = festival
voice_text_festival    = /usr/bin/festival
festival_host          = localhost
festival_port          = 1314
speak_volume           = 90
speak_voice            = us1_mbrola
sound_program          = omxplayer
sound_error            = error.wav
sound_reload           = hello.wav

When you restart MisterHouse, these new parameters will be loaded and it will attempt to eval your code to create $data_dir\mh_temp.user_code. If it detects an error and you cannot see where it is happening, the line numbers of the error refer to $data_dir\mh_temp.user_code.

If things go wrong

This article is a short overview of how to get MisterHouse up and running. If you want to get the details of it, info can be found elsewhere in this wiki, or, if you get stuck, you can ask the friendly people at the mailing list [email protected] for help.