1: MisterHouse operational questions

1.1: What OSes can it run on?

It has been tested on Windows >= XP. On Unix, it has been run on Linux (Ubuntu, Debian, Fedora and others), AIX, and Sun.

In theory, any OS that runs perl should be able to run mh. In practice, some platforms will likely have strange Serial Interfaces, so the Serial I/O related function would take some work.

1.2: How can I make it run faster and use less memory?

If you are happy with the Web interface and don't need the Tk interface, turn it off by editing the Tk mh.ini parm or run:

   mh -tk 0

If you want the tk window, but don't use the Command/Items/Group pull down menus, try:

   mh -tk_comands 0 -tk_items 0 -tk_groups 0

You can turn off the tk 'eye' that bounces back and forth by deleting the tk_eye.pl code file.

You can speed up / slow down mh, using more/less cpu, by mh.ini sleep_time parm.

Here are some memory stats:

  Linux
    10 Meg   <- mh -tk 0 mh_control.pl (run just one code file)
    12 Meg   <- mh -tk 0               (run all the default code)
    17 Meg   <- mh                     (run all the default code with tk gui on)
  Windows
    18 Meg   <- mh -tk 0 mh_control.pl (run just one code file)
    20 Meg   <- mh -tk 0               (run all the default code)
    27 Meg   <- mh                     (run all the default code with tk gui on)

1.3: How can I easily upgrade to the latest version of mh?

Point your mh.ini code_dir, data_dir, and html_dir parms to somplace other than your mh path. Then you should be able to rename your old mh directory and unzip the new one in its place without loosing anything. Also keep your mh.private.ini somewhere else (see next question).

1.4: How does mh.ini work?

All the entries in mh.ini are read on mh Startup and on a Reload. They are stored in the %config_parms array. So, for example, if you added:

  myparm1=a b c

Then, mh would set $config_parms{myparm1} = 'a b c';

These parms also defined what are legal startup values, so if you want to try a different value, instead of editing your mh.ini, you can run:

  mh -myparm1 'd e f'

Rather then edit the default mh.ini file, the best approach is to copy just the parms you want to change to your own .ini file (e.g. mh.private.ini), then set the environmental variable mh_parms to point where you keep that file (see the header of mh/bin/mh.ini for more detail).

While the %config_parms array IS refreshed on a mh Reload, some parms are only used on mh startup (e.g. http_port), so will only be reloaded when you re-start mh.

1.5: Can I run run mh in a 'fast debug mode'?

Funny you should ask :) Check out the time_start, time_stop, and time_increment parms in the mh.ini file. Here are some examples:

   mh -time_start 0 -time_stop 24 -tk 0 -voice_text 0
   mh -time_start "6 AM" -time_stop "11 PM"  -time_increment 1
   mh -time_start "5/14 7:10" -time_stop "5/15 10 PM" -time_increment 300

1.6: How are the X10 and Serial Items implemented, indpendent of the platform?

The user works with an X10_Item which reflects physical hardware and the state of that hardware. The user "loop" code deals with the state and conditions which alter it. This code is independent of OS and specific to mh.

X10_Items talk to Serial_Items which implement a software protocol required by the model and type of the actual hardware. The Serial_Items can use protocol translator modules such as CM11.pm, HomeBase.pm, and CM17.pm. But the output is platform-independent serial commands to the next layer. The protocol translator modules are publicly available outside mh and may be used by code other than Serial_Items. These modules will eventually be on CPAN. The code is still independent of OS. Other Serial_Item types, including "generic" read/write ports, also exist.

Win32::SerialPort.pm and Device::SerialPort.pm are CPAN modules which actually implement the serial command interface. Device::SerialPort is a clone of its Win32 cousin. These modules handle high-level OS issues including device names, configuration files, and validation of port settings.

Each also calls a CPAN module to handle low-level interfacing to the OS and the serial driver: Win32API::CommPort.pm or POSIX.pm (you guessed correctly ;-)

1.7: mh seems way too complicated. How can I run something simple?

Copy mh\code\test\test_x10.pl into your own code dir (e.g. c:\mh_code). Then run:

  mh -code_dir c:\mh_code

You can then use http://localhost:8080 for control. This will also run all the code in mh/code/common. To run JUST a specific code member(s), specify it on the command line. For example:

  mh test_x10.pl

1.8: Is there a way I can have direct X10 control with a simple perl script?

If all you want to do is control X10 devices with a cron job or from your own cgi scripts, running mh is probably overkill. You can send X10 commands using either the ActiveHome interface (CM11, available from http://www.x10.com/automation/x10_ck11a_d.htm ) or the cheaper Firecracker interface (CM17, available from http://www.x10.com/automation/firecracker_d.htm ) using the modules and documentation found in mh/lib/site/ControlX10 or download them from CPAN. Examples can be found in mh/lib/site/test_cm11.pl and test_cm17.pl.

1.9: Can I send mh commands from other programs?

You can send mh commands (Voice_Cmd text strings) from other programs in many ways:

- Write commands to the file specified in the mh.ini xcmd_file parm. By default this is mh/house_cmd.txt. See mh/bin/house and mh/bin/house.bat for examples.

- Use mh/bin/mhsend to send commands via sockets (can be over the internet). If you have run mh/bin/set_password, the mhsend -password parm is required. Some examples:

  mh/bin/mhsend -host ip.A -run "All Lights On"
  mhsend -p password -run "turn living room light on"

Where ip.A is computer A's ip address (or name if you have a HOST file setup to alias a name to an ip address). mhsend is a stand alone perl script, so you do not need mh running there (although it will not hurt). The code that allows this is in mh/code/common/mhsend_server.pl. An example of mh code to act as a client to different mh box is in mh/code/examples/test_server2.pl

- You can also control mh remotely via email (see faq question 'Can do I send mh comands via email?'), telnet sessions (if running mh/code/common/telent.pl), and via the built in web server. An example url for the web server is:

  http://192.168.1.10:8080/RUN;last_response?turn_living_room_light_on

- If you are runing IM client (if running code file internet_im.pl) like AOL AIM, MSN, or Jabber, you can any voice command to MisterHouse if you give Misterhouse its own account to logon with.

1.11: How can I debug a problem?

Lots of debug errata can be controled with the mh -debug switch. Most of this code is probably meaningful only if you dig into the source code, so most people probably will not use it unless you are generating debug to send to the author. To create a log file with debug in it, run:

  mh -log debug.log -debug xyz

Where xyz can be any of the following:

  x10
  serial
  socket
  startup
  homebase
  misc
  http
  port_name of socket port

You can also stack debug flags, using ; as a separator. fro example:

  mh -debug "serial;x10"

1.12: How can I debug timed event problem?

One way is to create a code member that contains just the event you are trying to debug, then run mh on just that one member. For example, create a member called \temp\test_time.pl with this code:

  print "min=$Minute\n" if $New_Minute;
  print "hour=$Hour\n"  if $New_Hour;
  print "debug1 it is now $Time_Now\n" if time_now "11:59 PM";
  print "debug2 it is now $Time_Now\n" if time_now "23:59";
  print "debug3 it is now $Time_Now\n" if time_now "12:00 AM";
  print "debug4 it is now $Time_Now\n" if time_now "00:00";

Then run mh using these parameters:

  mh -code_dir \temp -tk 0 -time_start '12/15 11:58 pm' -time_start '12/16 12:01 am'

Note, you can run this test mh quickly without stopping your normal mh.

1.13: How does mh read and use the user code in code_dir

Each time mh is started or a Reload is done, mh will re-read all the .pl code members in the code_dir directory (this is a mh.ini parm) and the file data_dir/mh_temp.user_code is created. All of the objects and global variables (see FAQ question 2.4), are put at top of this file, and everything else is put in seperate subroutines, one for each file read. A &loop_code subroutine is also created (at the very bottom of mh_temp.user_code), that calls each member subroutine.

After creating this file, mh runs the perl eval function on its contents. This re-creates all the objects, global variables, and code_dir member subroutines. Then mh goes back into its normal loop where it queries various input data (e.g. serial, tcp/ip, voice, time), updates objects and variables, evals the &loop_code code (it does an eval, rather then execute it directly, so we can trap errors and not kill mh), sleeps for a bit, then repeats.

1.14 How can I control mh from a non-mh web server like Apache?

You can think of the built in mh web server as 2 parts:

 - The part that auto-generates web pages that reflect your items and commands.
 - The part that responds to commands you give it via URLs.

You don't really have to use the first part. Some mh users custom generate their own mh pages, to be served by the mh server or by a different server. This allows for full control of what is on the web control page and how it looks.

There is more (probably not so easy to read) documentation on how to do this under 'Customizing the Web Interface' in mh/docs/mh.html

You can also use something like mh/code/common/mhsend_server.pl and then read/write to sockets directly from non-mh web server cgi scripts. Or have the web server script simply call mh/bin/mhsend to run mh commands.

1.15 Is there a front-end tool for defining/editing mh items/events?

Not yet, but you can now define items/events in a table-like format. This should allow us to enable a gui or web based front end tools for editing.

Currently we have defined just one format defined, creativly named A, but other formats (e.g. XML) should be easy to implement.

To use, create one or more *.mht (mh table) files in your code directory, specifying the table format with Format=A at the top of the table. Then mh will process (on starup and reload) each record with mh/lib/read_table_A.pl, to create *.mhp (mh processed) files, which are then processed with all your other mh *.pl code files.

Examples are in mh/code/bruce/*.mht and mh/code/test/*.mht. If you want to create another table format, all you need to do is create a mh/lib/read_table_xyz.pl member, then set Format=xyz.

1.16: How can I use Family Radios with MisterHouse?

There is seperate FAQ on the FRS topic in mh/docs/faq_frs.html

1.17: Is there a way to tell if MH is shutdown correctly or not?

On windows, mh/bin/mh.bat checks errorlevel and on linux, mh/bin/mhl finds the return code via $?. Both of these shells will restart mh unless they detect a normal exit (rc=1).

This code in mh/code/common/mh_control.pl will detect an abnormal restart:

 if ($Startup and $Save{mh_exit} ne 'normal') {
    display "MisterHouse auto restarted: $Save{mh_exit}", 0;
 }

If you want to detect a power outage and you have a CM11, code in mh/code/common/mh_control.pl will set $Power_Supply, so you can do something like this:

 if (state_now $Power_Supply eq 'Restored') {
    speak 'You should have bought a ups';
 }

1.18: How can I use an Internet Appliance with MisterHouse?

There is seperate FAQ on varous Internet Appliances in mh/docs/faq_ia.html

1.19: Where is perl program code located?

From Harald Koch on 2/2002.

There are (at least) three different locations for scripts:

/mh/bin - standalone programs (such as get_weather, get_tv_grid); they are called from the main MH process via "run" or a Process_Item; they do not get any environment or variables from the main MH program, and typically return results to MH by writing output files which MH later reads.

    MH typically looks for external programs here, and also programs
    here typically assume they're being run from this directory; they
    try to find files in ../lib, for example.

$config_parms{code_dir} - scripts in this directory are (after some parsing) loaded into the middle of the MH event loop, and the commands in them run constantly. They run within the MH environment, and can use all the variables available there.

$config_parms{html_dir} - scripts in this directory are run by the HTTP server, and are expected to return blobs of HTML. They too run inside the MH process, and can access all variables, subroutines, etc.

Each script directory has a different purpose, and programs in one are generally not terribly useful in another. My weather processing, for example, has scripts in all three places; mh/bin/get_weather_ca is the standalone that fetches/parses HTML, code/weather_ec.pl is the script that creates and processes voice commands and timer events, and then I have scripts in /web/weather/ that format the HTML for display.


2: MisterHouse coding questions

2.1: How do I debug syntax errors in my code?

If there are syntax errors in your code, most of them will be caught on startup or reload. The error, and (hopefully) relevant code member and/or line number, will show up in your console, and if running Tk, in a Tk window on reload.

When you go to write new code, first start mh with old code that works, then edit or copy in your new code and do a mh Reload. Fixing errors with code Reloads is much quicker than trying to fix them on mh startup. You can add/delete the .pl suffix on code members between reloads to enable/disable them.

Some errors (e.g. too few/many {} around code) will point to a misleading line number. In these cases, if you can not find the file with the error, you can try a new option: mh -error_by_file 1 . This will try loading one file at a time untill the error is found, but it runs pretty slow and may not work with members that have # noloop directives.

Some errors will only show up after mh triggers events. The first time this happens, a console/tk message will be displayed, and a message spoken. Since these errors might happen on sequential passes of mh, subsequent errors are only listed in the console window. If more than 10 occur, another window is displayed, and the code member there error was in is disabled.

All of these on-the-fly errors are logged in the file mh_temp.error_log in your code directory. This is useful if you are not running tk and the error has scrolled out of your console window.

You can enable the perl diagnostics module (same as perl -w) to get additional warnings on potential coding errors. Either use mh -diagnostics 1 or set diagnostics=1 in your mh.ini. This takes about 1 meg more of memory and causes mh to run about 10% slower, but the messages it displays often point to valid problems. To simplify coding, the 'uninitialized value' warnings disabled in the user code processing.

2.2: How should I code events that should occur only at infrequently, or only at Startup?

You can use the $Startup or $Reload variables for events that should only occur when mh is Started, or when code is Reloaded. Note that $Reload is also true when $Startup is true.

To run events infrequently, you can use the modulus operator (%), $New_Second/Hour/Day/Month/Year variables, or the Time_Now/Time_Cron functions to control events.

The $New_xxx variables are 1 (true) for each pass that the xxx variable gets incremented, and 0 for all other passes. For example, $New_Hour is true for one pass when $Hour changes from one hour to another.

Here are some examples:

  print_log "Only at startup" if $Startup;
  print_log "Every 5 minutes" if $New_Minute and !($Minute % 5);
  print_log "At 10:05 pm" if time_now '10:05 PM';
  print_log "Every weekday at 2:15 am" time_cron '2 15 * * 1-5';

2.3: How should I structure my Perl code?

Pretty much anyway you want! You may want to put object definitions all in one member (e.g. mh/code/Bruce/items.pl) so you can easily change device codes, or you may want to define the objects in the file members you use them in.

If the same object is defined in multiple members, it will still work ok, although some object types (e.g. Voice_Item) will warn about duplicate names.

2.4: Can I create global variables that can be shared between code members?

Yep. All objects definitions (e.g. $light = new X10_Item('C5')) are always shared. They are pulled out of the member loop by mh.

All other variable declarations must be made using with 'my' or 'use vars':

   my ($my_var1, $my_var2);
   use vars '$my_var1', '$my_var2';
   use vars qw($my_var1 $my_var2);

The last example uses the qw function (Quote Words) to save you from the ' and , punctuation.

If you code a 'my' or 'use var' record that starts in column 1, mh will pull these records out of the member loop code (as it did with object definitions), so that the variable can now be shared with other code members.

If the 'my' or 'use var' record does not start in column 1, the variable declaration is left in with the rest of the member code and is local to that member.

If you want to use the variable with any mh/web/*.pl script when creating mh web pages, you must use 'use vars', as 'my' variables can not be shared with the server.

2.5: How can I move code out of the loop code?

Sometimes you may need to have mh run code out of the loop code. For example, if you want to create a Voice_Cmd object that has states that are read from a file. Since objects are moved out of the loop code by mh, we need to also move any other code used to define that object.

You can tell mh to do this using '# noloop=start/stop' comments. For example:

   # noloop=start
   my $mp3names;
   while ( my $mp3name = <d:/songs/*.mp3> ) {
      $mp3name =~ s#^.*/##;  # remove path
      $mp3name =~ s#\..*$##; # remove extension
      $mp3names .= "," if $mp3names;
      $mp3names .= $mp3name;
   }
  # noloop=stop
  $v_play_music = new Voice_Cmd("Play [$mp3names]");
  if ($state = said $v_play_music) {
     speak "Playing song $state";
     run("winamp d:/songs/$state.mp3")
  }

2.6: How can I add my own subroutines?

You can add your own subroutines anywhere in any of your code files. These can then be called by that member or any other member. Here is a couple of examples:

   print_log &mysub1(9990, 9);
   sub mysub1 {
      my ($a, $b) = @_;
      my $c = $a + $b;
      return "The answer is: $a + $b = $c";
   }
   $v_bedroom_curtain  = new  Voice_Cmd('[open,close] the bedroom curtains');
   &curtain_on('bedroom', $state) if $state = said $v_bedroom_curtain;
   sub curtain_on {
       my($room, $action) = @_;
       set $curtain_updown  $action;
       eval "set \$curtain_$room ON;";
   }

2.7: What other special global variables are there?

Here are a few:

  $Pgm_Path is the directory that that mh/bin/mh is found in.
  $Pgm_Root is one directory above $Pgm_Path
  $OS_win is true on windows, false otherwise.  $^O will reflect the OS name.

2.8: Can I use mh to control other windows

On Windows you can use the SendKeys to send keystrokes to other windows. See mh.html for details.

If anyone knows of an equivalent function for linux, let me know. Linux is usually clever enough to have command line options, so there is less of a need here.

2.9: What data is saved when mh is exited and restarted?

The state of all objects (Timer Serial_Item X10_Item X10_Appliance File_Item Generic_Item) and all the $Save variables.

Every 5 minutes while mh is running, and whenever mh is exited, the state of these variables are saved to your code directory in a member called mh_temp.saved_states. When you start mh, this member is run to restore the states.

You can make up any members to the $Save array. For example, you can use $Save{sleeping_cat} to track whenever your cat is asleep.

2.10: How can I turn a bunch of lights on/off all at once?

You can turn all the lights on a single house code on/off by specifying just the house code letter. For example:

   $v_bedroom_lights = new Voice_Cmd('Bedroom lights [on,off]');
   $bedroom_lights   = new X10_Item('P');
   set $bedroom_lights $state if $state = said $v_bedroom_lights;

You can also create a group of X10 items. Here is an example that would turn all lights on/off in several rooms.

  $all_lights_bed    = new X10_Item('P');
  $all_lights_living = new X10_Item('O');
  $all_lights  = new Group($all_lights_bed, $all_lights_living);
  $v_lights_all = new  Voice_Cmd('All lights [on,off]');
  set $all_lights $state if $state = said $v_lights_all;

2.11: How do I get mh to stop telling the time each minute?

Out of the box, mh defaults to running most of the code in the mh/code/common directory and all the code in mh/code/test. Members test_tagline.pl and the hello_speak.pl members are the main sources of the periodic test speech. Once you have played around with the example code, you will want to use http://localhost:8080/bin/code_select.pl menu (avaliable on the web ia5 MrHouse menu 'Select Code' button) and select only the code files you find useful.

See the FAQ question 'How does mh.ini work' on how to modify the code_dir parm to point to your new code directory.

2.12: Can do I send mh comands via email?

Set the mh.ini net_mail_command_code parm to a secret code, and copy mh/code/common/internet_mail.pl into your code directory. Now you can send email with the following string either in the subject or the body of your email:

  command:your command    code:your_code

The internet_mail.pl code periodicaly runs the get_email process and then scans for the above string. If found, it will send a confirmation email saying either "command run", "command not found", or "command not authorized".

2.13: How can I control Command Categories

All Voice_Cmd objects are listed in the Tk Command pull down and Web Category list. These lists are organize by Category, which is specified with a Category=value comment in the user code. For example:

  # Category=Timers

This can be specified multiple times in the same file, with the most recent specification appling to all subsequent Voice_Cmd entries.

If a file does not have a # Category record, the file name will be used.

2.14: How can I measure time between two nearly spaced events?

If you are on Windows, or on Unix with the Time::HiRes module installed, a call to get_tickcount will give sub-second resolution (returns milliseconds). For example, to 'debounce' a doorbell button, (i.e. don't trigger it twice within a 250 millisecond time):

  my $doorbell_time;
  if (state_now $doorbell) {
    play 'doorbell' if get_tickcount - $doorbell_time > 250;
    $doorbell_time = get_tickcount;
  }

If you are on unix without Time::HiRes, you can use $LoopCount and count number of passes through the loop code.

2.15: What is the format of MisterHouse X10 codes?

At a low level MH sends and receives X10 data in character strings (called Serial Items) that start with the letter X. It is usually easier to create an X10 Item (or similar) for each X10 device you have and manipulate those instead of using X10 strings. Most of the functionality descibed here is available in various items in easy to use states.

Here is format of Misterhouse X10 strings: X10 strings always begin with an uppercase X (all letters in X10 strings must be uppercase.) The X is followed by one or more token pairs that are either a housecode and unitcode, or a housecode and command.

A housecode is a letter in the range A through P.

A unitcode is a number in the range 1 through 16. Unitcodes above 9 can be specified as two digit numbers or their hex equivalent A through G. Okay, there is no such thing as hex G, but X10 unitcodes start at 1, not 0. A note to X10 interface module developers: the Serial_Item module converts unitcodes above 9 to their hex equivalent before passing them to the interface module.

The following four basic X10 commands are the most common and are supported by all the interface modules. Each command is listed here followed by the corresponding X10 command that is sent or received, plus any notes about its use:

    J    - ON
    K    - OFF
    L    - Brighten
    M    - Dim

These commands are less common and are not supported by all the interface modules:

    O                - All Lights ON
    P                - All Units OFF
    STATUS           - accepted by some 2-way X10 devices to request status
    PRESET_DIM1      - these are the original direct dim commands specified but never used by X10
    PRESET_DIM2      - still used by some X10 venders, including PCS, SwitchLinc and RCS
    +#               - increase brightness by # percent, not used for receive
    -#               - decrease brightness by # percent, not used for receive
                       Serial_Item rounds # to a multiple of 5 before it's passed to the interface module,
                       the interface module calculates the number of Bright/Dim commands to send
                       by multiplying # by 22/100, since there are 22 standard dim levels
    &P#              - send an extended direct dim command accepted by some X10 devices,
                       # is the brightness level in the range 0 through 63
    #%               - same as &P command, but # is a percentage in the range 0 through 100,
                       Serial_Item converts this to a &P command before it's passed to the interface module,
                       neither &P nor % are currently used for receive
    Z##              - intended for sending and receiving EXTENDED_CODE commands with arbitrary extended
                       hex ## bytes appended, but appears only receive is implemented by the CM11 module,
                       no other tokens may follow this command

These commands are rarely used and only supported for completeness by a few interface modules:

    ALL_LIGHTS_OFF   - reported as P on receive
    HAIL_REQUEST
    HAIL_ACK
    EXTENDED_CODE    - see Z above     EXTENDED_DATA
    STATUS_ON
    STATUS_OFF

Here are examples of valid X10 strings and what they do:

    XM1MK            - turn off M1
    XC1C2C3CJ        - turn on C1, C2, and C3 simultaneously
    XI6IJIKIJIK      - flash I6 twice

For more examples, take a look at mh/lib/X10_Items.pm.

Many of the X10 interface modules expect only a housecode/unitcode pair and a housecode/command pair, like the first example above. This makes it impossible to send more complicated strings like the other examples, and is therefore discouraged. This can't be avoided with interfaces like the CM17 and BX24 that transmit using the X10 wireless protocol, since it combines housecode, unitcode, and command in one transmission.

2.16: How are states set for each pass though the user code loop?

Misterhouse works on a multipass system where a state becomes 'new' for one (and only) one pass thru the system. The actually timing of the passes varies (based on the machine, the load, the code, etc) but you generally can presume multiple passes will occur per second (I'm getting about 19 per second with fairly light load on a 400mhz laptop). I ran into an early problem where MH didn't handle multiple states being set during one pass (each subsequent state would 'overwrite' the previous one). As an example if my object read from a device and noticed that both the volume and treble setting on my mixer changed, it would generate a volume state and a treble state. The treble state when overwrite the volume state.

To fix this Bruce introduced a queue of states. So, when a module sets a state, it gets set for the 'next' *available* pass thru the system. In the example above (presuming no other states are outstanding) the volume state would be 'new' during currentpass+1 and the treble state would be 'new' during currentpass+2.

The reason the 'current' pass is never effected is that you don't always know where you are in the list of code looking at the time you make the change. If your in the 'middle' and set a state, code that already ran during that pass wouldn't have a chance to 'see' it before the pass ended. By making states always start at the beginning of the next pass, we can insure that all modules see a coherent state in the system. When the states becomes valid, if effects the tied_items (that is when they fire) as well as calls to 'state_now'.

2.17: Common Perl and mh coding errors

Clive Freedman sent in some useful tips on common coding errors in mh/docs/faq_damnblast.html

2.18: What's the difference between 'on', 'ON' and ON?

In MisterHouse, the state of many objects comes down to a question of whether they are on or off. As this is a common situation, it is important to know exactly how to ask whether something is on or off.

First, it is important to know that case matters. PERL is a case sensitive language, so 'On' does not equal 'on'. Second, by default, everytime that the state of an item is set, mh converts that state to its lowercase equivalent. Hence, setting a light 'ON' actually sets it 'on'. Third, the correct operator to check for string equality is eq, not == or =.

Now, MisterHouse adds a little twist to the situation. As 'on' and 'off' are common states, MisterHouse defines the PERL constants ON and OFF. N.B. that there are no dollar signs ($) at the beginning of the constants. Whenever MisterHouse code encounters ON and OFF as bare words (not within strings), they are replaced with 'on' and 'off' (both are lowercase). This means:

if (($state=$myLight->state_now) eq 'ON') # always fails as 'ON' is uppercase

if (($state=$myLight->state_now) eq 'on') # could be true if light just turned on

if (($state=$myLight->state_now) eq ON) # could be true as ON is the same as 'on'


3: Linux specific questions

3.1: Problem: When I run Viavoice and festival at the same time I get "Can't open output file '/dev/dsp'"

The problem is, festival or another sound program, is locking your dsp device. The sound drivers that come stock in the Linux kernel do not allow more than one program to access the /dev/dsp at one time. If you are using RedHat, you can use ESD to multiplex the soundcard usage. The problem is, not all sound programs are esd aware. Festival and Viavoice do not directly support esd. ESD does have a workaround that _sometimes_ works with non-esd aware programs. Try starting your sound programs, festival and viavoice under esddsp. For example: "esddsp festival --server &". I had some success with this route but it doesn't always work because of sampling rates and such.

The best fix would be to replace OSS with ALSA. http://www.alsa-project.org. The ALSA drivers directly support multiplexing the dsp devices. The only problem is they currently support fewer cards than the OSS drivers that come with the Linux kernel. Check out the web page and see if your card is supported. If it is, the best avenue would be replacing OSS with ALSA.

3.1.1: Problem: The speech stutters and then stops half way through, and I end up with 'hung' vv_tts.pl processes that do not complete.

Solution: You need to use ViaVoice_Outloud 5.0 with "any" ALSA driver. ViaVoice Outloud 5.1 does not work with ALSA, but it seems that downgrading to 5.0 fixes it. You can get the it here: http://dittos.yi.org/automation/ViaVoice_Outloud_rtk-5.0-1.0.i386.rpm

The older version ViaVoiceTTS that supports the older ViaVoice Outloud can be foudn at Brad's website: http://www.reednet.org/ViaVoiceTTS/ViaVoiceTTS-0.02.tar.gz

3.2 How can I set the default volume level for Festival?

This might work... it has not been tested.

You can globally increase the volume of all waveforms generated by festival by adding the following to your siteinit.scm. Put that in the festival/lib directory, (where all the other .scm files are) probably /usr/lib/festival/lib if you used the standard rpms. Add the following

    (set! default_after_synth_hooks
          (list
            (lambda (utt)
              (utt.wave.rescale utt 1.0 t))))

This will maximises the volume within a wavefrom, this wont necessary make all voices the same loudness (though it will be close).

Alternatively

    (set! default_after_synth_hooks
          (list
            (lambda (utt)
               (utt.wave.rescale utt 4.0))))

will mutiply the waveform by 4 but this has the problem that it may overflow.

If you want X% of the maximum without overflow use the first example and lower the 1.0 until you get an acceptable volume

3.3 How do I add a multi-port serial card in linux?

From Dave Lounsberry on 1/1/2002

First make sure you have the device nodes for the extra serial ports. You should have /dev/ttyS[16..23]. If not:

  # cd /dev
  # ./MAKEDEV ttyS16  (repeat for each device)

Next you need to run setserial to setup the board. The kernel defaults to only two serial ports. Put the following in a file called /etc/rc.serial and make sure it runs each boot.

  ---- clip here -----------------------------------------------
  #!/bin/sh
  setserial /dev/ttyS16 port 0x180 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS17 port 0x188 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS18 port 0x190 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS19 port 0x198 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS20 port 0x1a0 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS21 port 0x1a8 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS22 port 0x1b0 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS23 port 0x1b8 irq 4 uart 16550A ^fourport
  setserial /dev/ttyS16 set_multiport port1 0x1c0 mask1 0xff match1 0xff
  # chown to dbl (runs misterhouse)
  for a in 16 17 18 19 20 21 22 23
  do
        chown dbl.wheel /dev/ttyS${a}
  done
  ----- clip here ----------------------------------------------

Note that I am using irq 4 for my byterunner. Be careful that you don't have one of the built in serial ports on the same IRQ.

You can probably take out the for loop in the bottom if you are running MH as root.

Here is a link explaining the settings and jumpers (in more depth). http://www.mail-archive.com/linux-hardware%40senator-bedfellow.mit.edu/msg01897.html

Another good resource is always the Linux HOWTOs. The serial HOWTO can be found at http://www.ibiblio.org/mdw/HOWTO/Serial-HOWTO.html#toc5

Here is a followup from Nigel Titley:

I have found that the linux serial card driver doesn't like the serial card to be on a shared interrupt (I assume your Byterunner is a PCI card and not ISA). I had exactly this problem and worked around it by using the BIOS to move interrupts around until the serial card set itself up on an unshared IRQ. Everything then worked. This does seem to be a Linux issue, and I haven't taken the plunge yet and tried to find out where in the serial port driver the bug exists (I guess I am hoping that someone else will do it).

Here is some useful serial info from Bob Hughes:

Here is another way to look at the current serial port settings

  setserial -a /dev/ttySX  where "X" is the port

To set the serial port baud rate 9600

  setserial /dev/ttyS0 baud_base 9600

You can use setserial -G to get a list of current setting and have them in a format that can be fed back into setserial...

  setserial -G /dev/ttyS0

You can put setserial setting in /etc/rc.local so the port is ready for your interface program once boot up is complete

3.4: How do I get Mister House to start up automatically when my linux box boots

Check out various .rc startup scripts in mh/bin/*.rc

Here is a good tutorial note from Mike Bruno on 4/2002

OK, here's the quick and dirty on startup scripts.

(You also may wish to check out http://www.linux-mandrake.com/en/doc/82/en/ref.html/sysv.html which is where I pulled some of the stuff you'll find below)

Just for reference, there's two methodologies that are used for bringing up Unix systems: BSD and SysV. Mandrake uses SysV. BSD is initially simpler, but the SysV method is more flexible. The names of the methods and their merits should not really concern you at the moment, its just background in case someone jumps out of the woods and asks you.

I should also mention that there may be some sort of fancy graphical interface into all this. But its much more satisfying to get your hands dirty and roll your own solution.

The boot scripts are located in /etc/rc.d. If you look in there, you'll find several subdirectories named init.d and rc0.d -> rc6.d. The rc?.d directories correspond directly to the various runlevels that Unix supports. Runlevel is a set of predefined modes that define what the system does. Mandrake has the runlevels defined as

 0: complete machine stop;
 1: single-user mode; to be used in the event of major
    problems or system recovery;
 2: multi-user mode, without networking;
 3: Multi-user mode, but this time with networking;
 4: unused;
 5: like 3, but also launches the graphical login interface;
 6: restart.

If your machine comes up and immediately goes into an X-Window interface, then its default runlevel is 5.

When you say 'reboot' or 'shutdown -r now', what you are really doing is putting the system into runlevel 6.

When things have gone completely to shreds (typically after hardware failure or severe operator error ;), you want to get the machine into runlevel 1 - there are minimal services running and only one person can be logged in at a time.

Now, on to the nitty-gritty.

The init.d subdirectory is where all the startup/shutdown scripts are kept. They are all text files, and you can get a good idea of their format by cracking one open (I'd recommend a short one) and looking at it. You don't need to be an expert in shell programming to get the gist of it.

These scripts are called with one arguement (more on how that arguement gets supplied later). Virtually all scripts have the start and stop arguement, most have a restart, and then some have all sorts of custom ones. Lets look at a quick example.

This is an init script for starting up Apache. Most are more cluttered, but not really more complicated.

 -----------------
 #!/bin/sh
 #
 # Start the Apache web server
 #
 case "$1" in
    'start')
       /usr/sbin/apachectl start ;;
    'stop')
       /usr/sbin/apachectl stop ;;
    'restart')
       /usr/sbin/apachectl restart ;;
    *)
       echo "usage $0 start|stop|restart" ;;
 esac
 -----------------

Anything after a # is a comment, except for the first line. If that is #!, then the shell starts up the command interpreter specified (in this case another /bin/sh) and sends all the following commands through that. (Don't know how far into Linux you are yet, but suffice it to say that shell scripts are like batch files on steroids).

Moving down, we get to the first line of code. This is just like a case statement in C, except for the syntax (case block ends with a esac, which, of course, is case backwards). $x are the positional parameters of the program ($0 is the name of the program, $1 is the first arguement, etc.)

The rest of the script is pretty self-explanatory. This particular one is easy as all the complicated parts are handled by apachectl.

So that's all well and good, but how and when does it get called? OK, lets go back to the rc0.d -> rc6.d directories. Looking in there, you can see a bunch of files that start with K or S and a number. If you're using a color ls, then you'll notice that they are a different color and there might even be a @ after the name. That's because these are all symlinks to the real files in the init.d directory.

When the system enters a runlevel, it goes into the appropriate /etc/rc.d/rc?.d directory and begins executing the files in there. If the file begins with a K, then the symlink gets called with a stop (kill) arguement; if it starts with an S the symlink is called with a start arguement.

So if rc5.d has these links in it

 K15postgresql@  K60atd@      S15netfs@   S60lpd@        S90xfs@
 K20nfs@         K96pcmcia@   S20random@  S60nfs@        S99linuxconf@
 K20rstatd@      S05apmd@     S30syslog@  S66yppasswdd@  S99local@
 K20rusersd@     S10network@  S40crond@   S75keytable@
 K20rwhod@       S11portmap@  S50inet@    S85gpm@
 K30sendmail@    S12ypserv@   S55named@   S85httpd@
 K35smb@         S13ypbind@   S55routed@  S85sound@

the system is going to kill off postgress, nfs, rstatd, etc first (in that order). Then its going to start apmd, network, portmap, etc. (in that order).

OK, so now you have a rough background in how the system starts. So how do you get mh working in it?

The easiest way is to go into init.d, copy an existing file, and edit that. (Remember, you're root. Type carefully)

 cp httpd mh
 vi mh

and change the lines so that they look something like this

 -----------------
 #!/bin/sh
 #
 # Start mh
 #
 set mh_parms=/home/house/misterhouse/mh.private.ini
 case "$1" in
    'start')
       /home/house/misterhouse/mh/mh & ;;
    'stop')
       killall mh ;;
    'restart')
       killall mh
       sleep 5
       /home/house/misterhouse/mh/mh & ;;
    *)
       echo "usage $0 start|stop|restart" ;;
 esac
 -----------------

This is very, very sloppy, but you get the idea.

Before you go further, TEST IT! Just call it by hand from the command line like

 /etc/rc.d/init.d/mh start
 /etc/rc.d/init.d/mh stop

etc.

(you'll need to include the full path as init.d is not in your PATH and neither is the currect directory for root)

Once you've gotten all the bugs worked out and its working the way you like it, figure out which runlevels you want this to be running in. I'd guess 3 and 5, but its up to you.

Change into rc3.d. Figure out when you want mh to start compared to all the other programs. I'd guess you'd want to let everything else go first, then light up mh. So we'll give it a number of 99, effectively going last. Make the symlink like this

 ln -s /etc/rc.d/init.d/mh S99mh

Do the same thing in rc5.d

Now, you'll also want to have a good clean shutdown. So you'll have to take care of runlevels 0 and 6. Here, you'll want mh to get killed off early in the process, so give it a low number, say 01.

 ln -s /etc/rc.d/init.d/mh K01mh

You'll also want to do the same in rc1.d

Another option is to use a package called daemontools, available at

 http://cr.yp.to/daemontools.html

His take on why you should use it is at

 http://cr.yp.to/daemontools/faq/create.html

Its essentially inetd with the features it should have.

When the system comes up, the daemontools program svscan starts and then starts up any programs you've asked it to. Those programs are then monitored and get restarted if they die. The good part here is that you can control any program from the command line without editing files

 svc -h /service/yourdaemon: sends HUP
 svc -t /service/yourdaemon: sends TERM, and
        automatically restarts the daemon after it dies
 svc -d /service/yourdaemon: sends TERM, and leaves the service down
 svc -u /service/yourdaemon: brings the service back up
 svc -o /service/yourdaemon: runs the service once

-------------------------

The following is from Harald Koch on 04/2002

I'll offer an alternate method. Neither is really better or worse; it depends on your environment and requirements.

I have a strong preference for running mission critical software directly from init, instead of from startup scripts; init will automatically restart software that crashes. I do this with misterhouse, SSH, and a database that I run.

init is controlled from a file called (usually) /etc/inittab. Here's my MH entry from inittab:

 mh:2345:respawn:/home/mhouse/mhinit

This tells init to run "/home/mhouse/mhinit" when the computer is in any multi-user mode (see Mike's message for a definition of runlevels), and to run it again when it exits.

And here's my script:

 ----- /home/mhouse/mhinit -----
 #!/bin/sh
 mhhome=/home/mhouse
 cd ${mhhome}
 exec >> error_log 2>&1
 export PATH=${mhhome}/mh/bin:${mhhome}/bin:$PATH
 export mh_parms=${mhhome}/mh.ini
 # rotate logs
 /bin/mv log.3 log.4
 /bin/mv log.2 log.3
 /bin/mv log.1 log.2
 /bin/mv log.0 log.1
 /bin/mv log   log.0
 # start
 exec ${mhhome}/mh/bin/mh -log_file ${mhhome}/log
 ----- /home/mhouse/mhinit -----

This method *does* make it harder to stop MH, because you have to edit /etc/inittab, change the "respawn" to "off", and then run "telinit q" to tell init to re-read the config file.

On the other hand, it means that MH will restart itself automatically even if it exits due to bad code, which does happen to me occaisionally.

3.4: How do get Linux to play more than one sound at the same time

Posted by Richard Phillips and Sean Walker on 03/2003

FYI This is a bit of a "head's up" for those people who may be trying/struggling to get misterhouse to - for example - play music and also at the same time be able to speak under linux. You may find, for example, that misterhouse is silent whilst playing music and only after stopping (say) xmms your misterhouse server starts speaking all the queued up messages.

There are a number of different ways to enable your linux server to multiplex sound, and many different theories as to which way is better. Some people prefer to use ALSA because it's not proprietary as opposed to ARTS which is installed by default under many distributions such as Redhat. The trouble with alsa at the moment is it can be a bit fiddly to configure as it is not currently part of the linux kernel used in most distributions (it will be when 2.5 is released). Anyhow, even after successfully getting alsa installed, there can be some issues with getting multiple applications to use the sound card concurrently - this is because not all alsa sound card drivers support multiplexing.

So.....

If you want to use alsa, good for you. I won't get involved in which system is better, and of course there are some other commercial alternatives out there that a number of people also use and swear by. Anyhow, I'll just describe what can be done to get things working with arts IF you are using it AND are also having problems.

1. Install your distribution as you would normally, and ensure that arts is also installed/configured. As previously noted, many distros such as Redhat use arts by default so you won't have to do anything special - everything should be automagically detected. If you open up a terminal session and type "ps -ef | grep artsd" you should see a line showing the details of the artsd daemon. 2. Install flite - again depends on distro. With gentoo you can just do an "emerge flite". If you don't have a package available for your distro, you can get the source from http://www.speech.cs.cmu.edu/flite/ and try to build it yourself. There are other speech engines you can use of course, but this is probably the easiest to get running so it's what I'll use in this demonstration. 3. From a command prompt type "flite -t hello -o play" - you should hear a very bad hello from your computer 4. Fire up an application such as a music player that can use arts. If you use something like xmms, make sure that it is actually using arts (with xmms, go into options/preferences and check that the outplut plugin being used is the "aRts driver"). Now load up a playlist, put it on repeat, and start playing music. 5. Now try step 3 again - you'll probably find that it appears to hang. Just kill it with a "ctrl c" 6. Now try "artsdsp flite -t hello -o play" instead - you should hear music AND a bad "hello".

Why is it so? Well, by default flite - and a number of other applications - when trying to create sound directly access the sound device (usually something like /dev/dsp). By using the wrapper "artsdsp" before running an application such as flite, any calls to the sound device by the program are trapped and redirected to the arts server - basically it forces the application to "play nice" and not grab exclusive use of the sound device.

So how do I now use flite and misterhouse? Well, you just need to change the line in your ini file that tells misterhouse where flite is located. Go to a command prompt and type "which artsdsp". This will let you know exactly where the artsdsp program is located. Do the same for flite (eg "which flite"). Now change your mh.private.ini file as follows:

voice_text = flite voice_text_flite = /usr/kde/3.1/bin/artsdsp /usr/bin/flite

(Naturally, change the program locations depending on where your programs live).

Now, restart misterhouse and keep xmms (or whatever) running and playing music. You should now be able to do something like go to the ia5 web interface, select misterhouse, then misterhouse home, then browse mr house, and then click on the "what is your up time" and be able to hear mister house talking whilst music is also a happening thing!

Of course, as noted before you can use the same wrapper for other programs that may not directly support arts - for example if you install festival, you can test it by typing something like "echo 'Hello from Festival'| artsdsp festival --tts".

The same also works for using esd as well as artsd. You can use JACK, I'm sure, but I haven't tried it yet. Also, you can configure festival to use any play program directly instead of using the artsdsp or esddsp hacks. Those are hacks and will not work with all programs, just for reference. To configure festival use something like this in your siteinit.scm file (located in the festival root directory):

  (Parameter.set 'Audio_Required_Format 'snd)
  (Parameter.set 'Audio_Command "esdplay -s localhost:5001 $FILE")
  (Parameter.set 'Audio_Method 'Audio_Command)

In the Audio_Command line, the only thing critical is the $FILE You can use any player that you want in place of esdplay in the above, but it must be compatible with the audio formats that festival can produce. These, coming from the docs, are as follows: The default is unheadered raw, but this may be any of the values supported by the speech tools (including nist, esps, snd, riff, aiff, audlab, raw and, if you really want it, ascii).

More information can be found in the festival doc files festival_6.html and festival_23.html wherever your festival documentation is installed, including the handy:

  (Parameter.set 'Audio_Required_Rate 16000)
  (Parameter.set 'Audio_Device "/dev/dsp2")

These parameters can be specified in alternative methods as well. We should be able to tell festival which sound card to use or modify other settings on the fly as well. I haven't looked into that yet.

By default festival should be asynchronous and you should be able to start playing from the file even before the file if finished writing. At least that is what I gathered out of the doc files. Setting synchronous or asynchronous modes are as easy as (audio_mode sync) or (audio_mode async)


4: Windows specific questions

4.1: How do I set setup networking between Windows boxes

You need to have the TCP/IP protocol enabled for your Networking Interface Card (NIC). If you use a modem to reach the internet, you already have TCP/IP enable for the dial up adaptor, but you need to seperately enable it for your NIC card, using the control panel Network icon.

You can find instuctions on how to do this at: http://win98central.acauth.com/inside98/networking.htm .

IP addresses that start with 10. (e.g. 10.0.0.1) are reserved for internal lans, so you can use 10.0.0.1, 10.0.0.2, etc.

4.2 How do I run MH when not logged in Windows?

You can run any program as a service, using a program called srvany.exe, available in the Resource Kit, or from here:

 http://www.electrasoft.com/srvany/srvany.htm

Here is an example of registry entries after configuring my to run with srvany:

 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MisterHouse\Parameters AppDirectory  REG_SZ    c:\mh\bin
 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MisterHouse\Parameters Application   REG_SZ    c:\perl\bin\perl.exe -S c:\mh\bin\mh

Rather than call mh as a service, many people have Windows do an auto-login and just add mh to the startup.


5: Perl questions

5.1: Whats the best way to learn perl?

Using MisterHouse ;-) Much more fun that trying to code up that report generator at work! Some good books are referenced in mh.html.

5.2 What are good editors to use with perl?

Codeing perl is much easier and less error prone if you use an programing editor that automatically highlights and indents code.

One very popular and powerful (and free) editor is Emacs: http://www.gnu.org/software/emacs/. A pre-compiled windows version can be found here: http://www.gnu.org/software/emacs/windows/ntemacs.html

Alan Jackson liks vim: http://www.vim.org. "Does syntax highlighting quite nicely for perl"

Kieran Ames likes UltraEdit32: http://www.ultraedit.com. "I swear by UltraEdit32 available at It works fully functional for 30 days and then expires. Registration goes for around $30. I'm coding Perl all day long and would die without it! Fairly thin and goes the distance with just about any language you'd want to use."

Mark Yocom writes "I myself have grown fond of PrimalSCRIPT, which handles Perl, Java (and JScript & JavaScript), HTML, ASP, LotusScript, Livewire, Python, SQL, Tcl, REXX, VBScript, and good old fashioned .BAT/.CMD files. In addition to the obligatory syntax coloring, it also has a number of other handy features. It's spendy, but a trial version is available at their website: http://www.sapien.com/PrimalSCRIPT.htm "

5.3 When are you supposed to use '=>' as opposed to '->' ?

You can use => for a synatically pretty way to seperate entries in a list. When creating a hash, you can pass it a set of key/value pairs via a list, so instead of this:

  %hash = ('key1', 'value1', 'key2', 'value2');

You can use => instead of a , to make it look pretty:

 %hash = ('key1' => 'value1', 'key2' => 'value2');

Now to really confuse you, I'll try to explain how -> is used for dereferencing pointers. All mh objects can be viewed as pointers, and the state of an object is stored in a hash key of {state}, so there are 4 ways to get the current object state:

 $state = state $light;    # Use the state method to get {state}
 $state = $light->state;   # Dereference with -> to get the state method
 $state = $light->{state}; # Dereference with -> to get the state hash
 $state = $$light{state};  # Dereference object with an extra


6: Misc questions

6.1: Misterhouse Timeline

Here is a rough timeline of MisterHouse development:

 - 12/96 Coded a predecessor called House_Menu
 -  8/98 Re-wrote everything, called it MisterHouse
 -  9/98 Uploaded to the web
 - 10/98 Created compiled version.
 - 11/98 First known user.
 - 01/99 Started a mailing list at onelist.com
 - 02/99 Ported mh to Unix/Linux
 - 03/99 Article in Popular Home Automation
 - 04/99 Posted to comp.home.automation
 - 05/99 Registered misterhouse.net domain name.
 - 06/99 Added CM17 & HomeBase support
 - 06/99 Article in HomeToys: http://hometoys.com/htinews/jun99/articles/winter/winter.htm
 - 08/99 Mailing list reaches 100 members
 - 09/99 Added LCDproc and IRman support
 - 10/99 Article in Circuit Cellar Ink: http://www.circuitcellar.com/pastissues/articles/winter111/winter.pdf
 - 11/99 Linux VR using IBM's ViaVoice
 - 11/99 HomeVision support
 - 11/99 Mailing list reaches 200 members
 - 01/00 Moved the mailing list and CVS repostitory to sourceforge.net
 - 02/00 Re-worked the web interface
 - 03/00 Added support for iButtons
 - 04/00 Added support for X10's IR Commander transmiter
 - 05/00 Added voice modem, ISDN modem, and Compool support.
 - 05/00 Article in The Perl Journal #17
 - 06/00 Mailing list reaches 300 members
 - 06/00 Added support for table item/event input and tie_items/tie_events.
 - 08/00 Enable perl -w checks, .jpg and .gif, and Slinke support.
 - 08/00 Added rpm and tarballs, NetGear router support
 - 09/00 Added ViaVoiceTTS.pm, Jabber, and Applied Digital cpuxad support
 - 10/00 Added barcode scanner and MS Agent support
 - 11/00 Support for ical, rrd, html email access, WAP, and VXML for phone access via tellme.com
 - 12/00 wx200d and wunderground personal weather project support, new add_sound function.
 - 01/00 SMS and snnp messaging, improved iButton and benchmarking support.
 - 01/01 Mailing list reaches 400 members
 - 02/01 2 way AOL AIM messaging, earthquake and satellite tracking.
 - 03/01 Backup program and menu templates for WAP, VXML, and LCD displays.
 - 05/01 Audible menus, X10 Mr26 support, linux volume control.
 - 07/01 Browser dependent web pages, zap2it tv support, call waiting callerid.
 - 09/01 Audrey support, more MS TTS controls.
 - 10/01 Web mh.ini editing, remote browse TTS support, zap2it tv pages.
 - 11/01 New web interface, Audrey pictureframes, multiple sound cards.
 - 12/01 Wireless wmr968 and Ultimeter2000 weather stations, Lynx10 X10 support.
 - 01/02 Xmms, audrey callerid, Linksys rounter, TTS flite engine, standard CGIs.
 - 03/02 GD on-the-fly web buttons, support for comics, xmms, redrat.
 - 04/02 Added web calendar, contact, todo list, and tk photo slideshow
 - 05/02 Improved TTS support, TWiki web site, and support for DSS units, BX24 interface, and MSN,
 - 05/02 Rewrote web menu interface, added AudioTron support and improved im support.
 - 06/02 Registered misterhouse.com domain name.
 - 08/02 Caddx alarm, iButton humidity sensor, undo, light/dark hawkey sensor
 - 09/02 Proxy mh, improved %cpu used, Group member and idle_time methods, Linux NaturalVoice, Clipsal CBUS
 - 10/02 Enabled web based code selection, file based alarms, palm reader, and Mac OSX support.
 - 11/02 UIRT2 control, better im control, web interface for triggers and items
 - 12/02 Improved callerID, new respond and Text_Item functions, xAP support.
 - 01/03 Mailing list reaches 500 members.
 - 02/03 Addex xPL support, stacked and overloaded states, and multi-user logon.
 - 03/03 Linux NaturalVoiceWine, web based TV and photo setup, improved Lynx X10 support.
 - 04/03 Compiled mhe for linux, support for X10 W800, CallerID Identifier, USB-UIRT, and more iButton modules.
 - 07/03 Improved web floorplan, DBI interface, xAP news and weather interfaces.
 - 09/03 Cepstral TTS engine support, a new PA room object, improved proxy support.
 - 11/03 Support for Sphinx2 VR, myHTPC tv menus, Asterisk phone interface, SMTP authentication, and a xAP command server.
 - 12/03 Code for RCS TR40 theormostate, phone xAP.
 - 01/04 Code for rrd weather graphs, v4lctl.
 - 04/04 Code for ER1 robot, switched to the par compiler, improved mp3 Jukebox.
 - 06/04 Code for Musica whole house audio, rss feeds, xAP Slimserver
 - 07/04 Code for ICQ, vocp, tivo, Alpha LED displays, xAP IR for RedRat, RoboSapien.
 - 08/04 Mailing list reaches 600 members.
 - 09/04 Support for SVG floorplans, mp3 ripping, ebay monitoring, siteplayer, irc.
 - 11/04 Support for servo motors, the ESRA robot, cell phone minutes monitoring, motherboard monitoring.
 - 03/05 Support for serving multimedia files, cell phone minute monitors, shopping lists.
 - 05/05 Support for distributed xAP speech, bluetooth proximity detection.
 - 10/05 Support for xAP BCS, ssh, osd232, vocp, Wish x10, and EIB.
 - 01/06 New spam free Wiki, support for azureus, Insteon iplcs, ical, k8055, TI103.
 - 04/06 Moved from CVS to SVN, support for Xantrex power inverter, spanish web pages, french EDF power rates, DSC5401, xAP asterisk,

6.2: Who is that Bruce guy anyway?

Bruce was the the original author of MisterHouse, but can no longer claim much authorship credit as it is now truly a group effort with many contributors. He has a day job with IBM in Rochester, Minnesota, designing integrated circuits. Lots of stuff of interest only to family and aliens at http://brucewinter.net

6.3: Why open source?

Because open source only has 3 syllables, and proprietary has 5.

That and MisterHouse has developed much faster with the help of a wider user base and help from other coders than it would have if it were proprietary.

Plus it feels good to give stuff back to the growing open source community.

6.4: Misc Home Automation links

Here are some useful/related Home Automation links:

  Dan Hoehnens most excellent collection of HA links:
    http://my.ohio.voyager.net/~dhoehnen/ha/list.html
  Mark Henrichs has a great 'Home Wiring Guide' site here:
    http://www.wildtracks.cihost.com/homewire/
  Over 500 links on about everything with HA:
    http://home-automation.org/
  Lots of good tutorials and articles are here:
    http://hometoys.com/
  X10 has many of its products documented here:
    http://www.x10.com/support/support_manuals.htm
  Lots of good X10 data/ideas can be found here:
    http://www.geocities.com/ido_bartana/toc.htm
    http://www.x10ideas.com
    http://www.x10.com/automation/homeautomation_e.htm
  Dave Houston has some good X10 info (e.g. causes of CM11A lockups) here:
     http://www.laser.com/dhouston/
  Europeans can get X10 stuff distributers listed here:
    http://www.x10.com/x10euro.htm
  Some examples are:
    http://www.intellihome.be
    http://www.marmitek.com/
  Neil Cherry has created a home for linux related Home Automation programs at
    http://linuxha.sourceforge.net
  Rene Mueller has a nice set of web pages with lots of info on HomeAppliances at
    http://the-labs.com/HomeNetwork/
  Jay Archer recommends this free Windows mail server and mult-platform web server:
    http://www.argosoft.com
    http://www.xitami.com
  Nokia sponsered open source site for home entertainment devices.
    http://www.ostdev.net/

6.5: How do I contribute additions or updates to the mh code?

The MisterHouse code is maintained via a GitHub repository. Instructions on how to commit changes can are here: https://github.com/hollie/misterhouse/wiki/Contributing

If you have minor changes and don't want to bother with a sourceforge ID, feel free to mail them to the mailing list.

6.6 What is X10?

The people at http://www.x10.com sell affordable devices that communicate with each other over normal household power lines. Manuals for many of there devices are listed at http://www.x10.com/support/support_manuals.htm . They have their home automation product slited here: http://www.x10.com/automation/homeautomation_e.htm/#homeautomation

The most common modules are the Lamp module and the Appliance module. Both sell for around $10-$15. The lamp module has can turn up to 300 watt lamps on, off, and various levels of bright. The appliance module is an on/off relay.

The 2 most popular X10 PC interfaces are the $50 ActiveHome/CM11 and the $6 Firecracker/CM17.

The CM17 is a transmit only interface. In addition to being almost free, another advantage is it is wireless. It is a small, 1 inch box that just dangles off of your serial port and transmits to a receiver that plugs into the wall. The other advantage to the CM17 is gives instant ON/OFF control to the relay built into the wireless receiver. All other X10 devices have about a 1/2 second delay to send and receive the protocol over the power lines.

The CM11 is a 2 way interface, so you can program mh events to react to X10 motion sensor and button pushes from various X10 controlers (e.g. keychain and palmpads). Some of the newer, more expensive modules, like the $35 LM14A lamp module, allow you to query their status, so you can determine it status even if it were manually turned on or off.

If decide you splurge for the CM11 activehome kit, you might as well also get the Firecracker kit. For the extra $6, you also get a few extra modules and mh can support both the CM11 and the CM17 on the same port.

There is lots of great X10 info at http://www.geocities.com/ido_bartana , including information on using and buying X10 hardward outside of the US.

Here is some more info, copied from a misterhouse-users post by Kevin Olalde.

The firecracker hardware, CM17 which plugs into the PC, can only send radio frequency (RF) commands to devices. With the kit you will also get a transceiver, TM751, that receives commands from the CM17 and relays commands for the house code it's set to via your power lines. You also get a lamp module, LM465, which can be control with via the transceiver. With the PalmPad or the CM17 you send RF commands to the TM751, those commands are then relayed to the lamp module (or other power line receiver modules, like light switches). All of this is one way communications, the LM465 lamp module and the TM751 transceiver are not capable of reporting status. The TM751 doubles as an appliance module hard coded to unit 1. You can only control it though RF commands, it does not respond to power pline commands.

The next step I took was to order the Active Home kit. With it you get (among other stuff), another transceiver, RR501, and another computer interface, CM11A. The RR501 works like the TM751, in that it receives RF commands, and relays then on to the power line. A difference is that the RR501 can report it's status. The computer interface, CM11A, can send power line commands (you use computer software to tell the interface what commands to send), 'sees' all commands being sent over the power line (and reports those commands to computer software), and can ask modules for their status. The RR501 also doubles as an appliance module, it can be set to unit code 1 or 9, and can be controlled with both RF and power line commands.

The majority of the devices, lamp modules, appliance modules, wall switches, ..... are one way devices, they can only receive. I have no historical perspective, but it looks as though that was the way the original X10 spec went, one way only.

There are devices that can report their current status to something like the CM11A, but I haven't used any of then (except for the RR501), since that are much more expense.

  http://www.x10.com/products/x10_lm465.htm  one way lamp module from X10, $13
  http://www.x10.com/products/x10_lm14a.htm  two way lamp module from X10, $33

Bill Bass sent in these links to a bunch of links from Phil Kingery's great series of X10 articles at http://hometoys.com

  Which One Should I Use?
  http://www.hometoys.com/htinews/dec96/articles/kingery/kingery.htm
  Controlling Motors and Transformers
  http://www.hometoys.com/htinews/apr97/articles/kingery/kingery2.htm
  120/240v Residential Coupling
  http://www.hometoys.com/htinews/jun97/articles/kingery/kingery3.htm
  Complex Residential Coupling with Considerations for Dim/Bright
  http://www.hometoys.com/htinews/aug97/articles/kingery/kingery4.htm
  Dim/Bright Commands and Coupler-Repeaters
  http://www.hometoys.com/htinews/oct97/articles/kingery/kingery5.htm
  Three-Way Switch Circuits
  http://www.hometoys.com/htinews/dec97/articles/kingery/kingery6.htm
  More Three-Way and Four-Way Switch Circuits
  http://www.hometoys.com/htinews/feb98/articles/kingery/kingery7.htm
  Troubleshooting Three-Way and Four-Way Switch Circuits
  http://www.hometoys.com/htinews/apr98/articles/kingery/kingery8.htm
  Noise and Filtering
  http://www.hometoys.com/htinews/jun98/articles/kingery/kingery9.htm

6.7 What do I need to use the iButtons?

Ray Dzek created a how to get started with iButton guide at http://www.solarbugs.com/home/ibutton.htm

Here is a post from Clay Jackson

Right now, I've got 3 sensors (DS1822, in the three-lead package, inside an epoxy filled soda straw) at the end of 150' of Radio Shack "flat" cable, talking to a DS9097U (the U is CRITICAL) with no problems. On the bench, I had another 2 sensors on the end of a 50' cable (for a total of 5 sensors). When I strung the 50' cable, I must have crimped a lead, because it now meters "closed" and when it was plugged into the "net", I got no readings.

I also have an HA5 from Point-Six; that I'm gonna play with soon. The code Bruce did is for the 9097U, so that's why I started there (and, it's cheaper). The 9097U has all the "passive" pull-up stuff the data sheets talk about (courtesy of a DS2048 inside the DB9); so I'm hoping it will do the trick. Anyway, I'll keep the list posted as things progress.

Bottom line - all I needed was Bruce's code, a 9097U from Dallas, the sensors and some Radio Shack "phone" cable.

One more thing to watch - as best I can tell, Dallas has not standardized their thermal devices with respect to their outputs. For example, the DS1820 and DS1920 both return a 9 bit value that's basically an integer. However, the DS1822 returns a VARIABLE length value (12 bits by default), with a binary point between the 3rd and 4th digits. According to someone else on the list, the ThermoCRON iButton is different yet again.

Here is another post from Jeff Pagel (06/2002).

The Dallas '1-wire' bus for the ibutton family is actually 2 wires(there are only 2 connecting points on the devices). 1 for signal and power, the other for ground. They talk about cat-5, which has 8 conductors, a lot because the signal charactoristics of it are very good for the '1-wire' bus, twisted pairs, size of the wire, etc.. Of the 8, you only need to use 2. Theoretically, the other 6 could be used for something else.

So, back to the original problem, you would need to run a twisted pair, like cat5 or cat3, from your mh machine to the garage. I have cat5 runs of over 500 feet that work fine without any special conditioning.

The cool part about the 1-wire bus is that you just need to run 1(ok actually 2,but usually in 1 bundle) wire(s) around your house. It's like a 'multi-drop' system. One connects to the other, to the other, etc., in parallel.

 In this case, you would run a line, from 1 spool of wire, to the bedroom
to the living room to the kids room back to the computer.  If this is a
pre-existing structure, you will face some wiring issues.  It's much easier
for new construction.  For each ibutton, you would connect 'across' each
line.  Just solder plus to plus, minus to minus and keep the wire going.
Think of a railroad track as the 'wire' and the railroad ties as the
ibutton devices.

The 1-wire bus is fairly restrictive on how you wire it vs how long the runs are. You should avoid 'star' type configurations. They are ok, but only for short runs, the stars introduce reflections of the signal.

Here will be a really bad ascii representation:

 Host +   -----------------------------------------------------
                     |                  |                     |
                  ibutton1           ibutton2             ibutton3
                     |                  |                     |
 Host -   ----------------------------------------------------

From Yannick Moussette (06/2002)

The DS1820 Temp sensors come in 2 models: iButton and TO-220 (transistor-type casing).

The Ibutton has a total of 2 connections, ground and signal. It functions in "parasitic" mode to draw its power from the signal connections (kinda of like what X10 modules do to piggyback signals on powerlines...).

Where things that may confuse you on Dallas's Website site, is the TO-220 format of this same sensor which has 3 leads (connections). 1 for power, 1 for ground and 1 for signal(data). The power lead may be omitted, in which case the sensor will work exactly like its iButton counterpart: Through parasitic powering.

Here is a link with some detailed electronic info: http://www.maxim-ic.com/1st_pages/tb1.htm

Kieran Ames has a nice writeup on how he used iButtons to log and plot his pond temperatures: http://ames.homeip.net:81/pages/My_iButtonVenture.htm


7.0: Setup Questions

7.1: Password Management

To password protect Misterhouse, you can set passwords for different users via set_password. The 'admin' link from the main page is only for logging in once you have setup a password.

To enable password protection, run mh/bin/set_password command like this:

     set_password -user family -password xyz1
     set_password -user admin  -password xyz2
    Note: only the first 8 characters are used. The admin password is
    required for controling the mh web setup menus (e.g. item and code
    selection menus).(Unix or Windows)

This will create a file pointed to with the mh.ini password_file parm (e.g. mh/data/.password). To further extend which user can do what see password_allow in mh/data/

7.2: Customizing the TV guide

To set the MisterHouse TV Today so it will display listings relevant to your area and provider Start by finding your tv_provider ID, run this command (located in mh/bin):

  get_tv_grid -zip your_zipcode -get_provider

Then edit your mh.ini and set the tv_provider_name parm. Listed below are two examples or related parms, one that uses sat_ and one that is tv_. You can copy these tv_* parms as another set of sat_* or cable_* or or whatever_*, then run get_tv_grid multiple times to support multiple sets of tv schedules. For example:

   get_tv_grid -db tv   (-db tv is the default)
   get_tv_grid -db sat
  sat_provider = 128772
  sat_provider_name = DirectTV Washington
  sat_name =SAT               @ Used to give a useful label on the web pages
  sat_hours=all                                 @ Which hours to get.  Use all for all hours
  sat_label=SATELLITE         @ Which web link name.  Use none to disable,
  sat_channels_keep=          @ Which channels to keep
  sat_channels_skip=          @ Which channels to skip
  sat_channel_min=0           @ Keep only channels above this number
  sat_channel_max=99999
  tv_provider_name = Charter Communications - Rochester
  tv_name = TV                @ Used to give a useful label on the web pages
  tv_hours=02,06,10,14,18,22  @ Which hours to get.  Use all for all hours
  tv_label=VCR                @ Which web link name.  Use none to disable,
  tv_channels_keep=           @ Which channels to keep
  tv_channels_skip=           @ Which channels to skip
  tv_channel_min=0            @ Keep only channels above this number
  tv_channel_max=99999        @ Keep only channels below this number

Use mh/common/tv_grid.pl to do daily call get_tv_grid to update your tv database and web pages. and mh/code/common/tv_info.pl to search and announce shows. If you change your tv_provider, you can use get_tv_grid -reget to refresh the tv/*.html files.

When I first setup MH it took me three weeks to figure out that my providerID had changed since install (matter of a week) and thats why the tv listings came up broken. So if you have a problem, and you think the syntax in the mh.ini is correct, try re-checking your provider ID.

7.3: How can I point MisterHouse to a custom web interface?

From David Norwood on 10/2001

Here's a way to configure Misterhouse so you can have your own custom web interface AND still have access to web pages that are introduced with new releases (like the Audrey pages).

Let's assume your misterhouse distribution is in /misterhouse/mh and your custom html files are in /misterhouse/web/custom. Set these private.ini parameters:

 html_dir=$Pgm_Root/web
 html_file=/custom/index.html
 html_alias_custom=/custom       /misterhouse/web/custom

Now your custom web pages will come up by default, but you will still have access to the latest and greatest "mh4" and "ia*" interfaces. Your pages will not be over-written by new releases. If you need another directory for, say, your audrey interface, just add another html_alias_whatever parameter.

You can now also override just specific pages from an existing web interface. For example, create your own web/ia5 and web/ia5/security directories, then add this mh.ini parm to point to it:

 html_alias2_ia5    = /misterhouse/web/ia5

For example, you can change the ia5 Security menu to point to different webcams or floorplan images by creating your own web/ia5/security directory with just the files you want to modify.