From 7c3b8af63b3a3aab83d12fd49452402924042301 Mon Sep 17 00:00:00 2001 From: Nitsud Date: Sun, 3 Mar 2013 00:47:16 -0500 Subject: [PATCH 1/2] POD added to ~_Items.pm --- lib/Acid.pm | 52 ++++++ lib/DSC_Alarm.pm | 208 +++++++++++++++++---- lib/Generic_Item.pm | 2 + lib/LCD.pm | 2 +- lib/Network_Item.pm | 2 +- lib/Process_Item.pm | 139 ++++++++++++++ lib/RCS_Item.pm | 57 ++++-- lib/RF_Item.pm | 70 +++++++ lib/Socket_Item.pm | 1 + lib/Text_Cmd.pm | 87 +++++++++ lib/Timer.pm | 157 ++++++++++++++++ lib/Voice_Cmd.pm | 110 ++++++++++- lib/Weather_Item.pm | 78 ++++++++ lib/X10_Items.pm | 440 ++++++++++++++++++++++++++++++++++++-------- 14 files changed, 1279 insertions(+), 126 deletions(-) diff --git a/lib/Acid.pm b/lib/Acid.pm index ac1ec5dd8..c0cd4d948 100644 --- a/lib/Acid.pm +++ b/lib/Acid.pm @@ -14,6 +14,33 @@ use IO::Socket; use IO::Select; package Acid; +=head1 NAME + +B + +=head1 SYNOPSIS + +NONE + +=head1 DESCRIPTION + +Sends callerid to Audrey acid program for dispaly. + +This is called from CID_Server, which is called from code/common/callerid.pl + +=head1 INHERITS + +NONE + +=head1 METHODS + +=over + +=item C + +=cut + + my $sel; my $udp_fh; my %clientList = (); @@ -111,3 +138,28 @@ sub CID_TYPE_ERROR_CALL {return(4);} # Same as of ICallerIDNotify.OnError() sub CID_TYPE_TEST{return(5);} # same syntax as subscribe (ping request) 1; + +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +Andrew Drummond on 01/2003 + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + diff --git a/lib/DSC_Alarm.pm b/lib/DSC_Alarm.pm index 4c765255d..a03cf63e0 100644 --- a/lib/DSC_Alarm.pm +++ b/lib/DSC_Alarm.pm @@ -1,47 +1,74 @@ -################################################################## -# Interface to DSC alarm system via DSC PC5400 Printer Module # -# # -# The PC5400 works with: PC5010, PC1555, PC580, PC5015, and # -# PC1575 main panels. # -# # -# Add these entries to your mh.ini file: # -# # -# DSC_Alarm_serial_port=COM2 # -# DSC_Alarm_baudrate=4800 # -# # -# Multiple instances may be supported by adding instance # -# numbers to the parms as in: # -# # -# DSC_Alarm:1_serial_port=COMx # -# DSC_Alarm:1_baudrate=4800 # -# # -# DSC programming location 801 subsection 01 set to: # -# 1-3---78 # -# 1 = Printer Enabled # -# 2 = Handshake from printer (DTR) # -# 3 = 80 Column Printer (off = 40 Column) # -# 4 = 300 Baud Enabled # -# 5 = 1200 Baud Enabled # -# 6 = 2400 Baud Enabled # -# 7 = 4800 Baud Enabled # -# 8 = Local clock displays 24hr time # -# DSC programming location 801 subsection 02 set to: # -# 01 = English # -# # -# See mh/code/public/Danal/DSC_Alarm.pl for more info/examples # -# # -# By: Danal Estes, N5SVV # -# E-Mail: danal@earthling.net # -# # -# Based on original code by Bill Sobel: # -# bsobel@vipmail.com # -# # -################################################################## - use strict; package DSC_Alarm; +=head1 NAME + +B + +=head1 SYNOPSIS + + mh.ini entry of 'DSC_Alarm_serial_port=com2' + + $DSC_Alarm = new DSC_Alarm; + if (my $log = said $DSC_Alarm) { + print_log "Alarm system data = $log\n"; + } + + mh.ini entry of 'DSC_Alarm:2_serial_port=com5' + + $DSC_test = new DSC_Alarm('DSC_Alarm:2'); + if (my $state = state $DSC_test) { + print_log "Alarm system state change, state = $state\n"; + } + +=head1 DESCRIPTION + +DSC_Alarm module supports the DSC PC5400 serial printer interface. This allows mh to be aware of events that DSC alarm systems log to their event buffers + +The PC5400 works with: PC5010, PC1555, PC580, PC5015, and PC1575 main panels. + + DSC programming location 801 subsection 01 set to: + 1-3---78 + 1 = Printer Enabled + 2 = Handshake from printer (DTR) + 3 = 80 Column Printer (off = 40 Column) + 4 = 300 Baud Enabled + 5 = 1200 Baud Enabled + 6 = 2400 Baud Enabled + 7 = 4800 Baud Enabled + 8 = Local clock displays 24hr time + DSC programming location 801 subsection 02 set to: 01 = English + +Logging: The internal support module for DSC_Alarm (DSC_Alarm.pm) maintains a log of all serial data received from the DSC PC5400 interface. This log is placed in /mh.ini parm data_dir/logs/$port_name.YYYY_MM.log; for example, the log entries shown below would be in file '/mh/data/logs/DSC_Alarm.2000_10.log'. This implies a new log will be started each month. + +DSC User Codes: + 40 = Master code (can arm/disarm, change codes, any keypad function) + 41 = Supervisor code (can arm/disarm, change codes) + 42 = Supervisor code (can arm/disarm, change codes) + 01-32 = User codes (can arm/disarm, can be associated to individual wireless keys) + 33 = Duress code (can arm/disarm + sends duress code to master station) + 34 = Duress code (can arm/disarm + sends duress code to master station) + +The above information derived from PC1555 master panel; please see the installer manual for your particular panel for further information. + +Duress code reporting is NOT reflected via states as of December 2000. Coming soon... + +Examples of typical DSC alarm system event/log entries: +Mon 10/09/00 17:09:00 DSC_Alarm.pm Initialized Mon 10/09/00 17:10:16 17:10 10/09/00 System [*1] Access by User Mon 10/09/00 17:12:28 17:12 10/09/00 System Partial Closing Mon 10/09/00 17:12:28 17:12 10/09/00 System Bypass Zone 1 Mon 10/09/00 17:12:28 17:12 10/09/00 System Bypass Zone 2 Mon 10/09/00 17:12:28 17:12 10/09/00 System Bypass Zone 4 Mon 10/09/00 17:12:29 17:12 10/09/00 System Closing by User Code 40 Mon 10/09/00 17:12:29 17:12 10/09/00 System Armed in Away Mode Mon 10/09/00 17:12:45 17:12 10/09/00 System Opening by User Code 2 Mon 10/09/00 17:14:42 17:14 10/09/00 System Closing by User Code 40 Mon 10/09/00 17:14:43 17:14 10/09/00 System Armed in Away Mode Mon 10/09/00 17:14:47 17:14 10/09/00 System Opening by User Code 40 Mon 10/09/00 17:22:28 17:22 10/09/00 System [*1] Access by User Mon 10/09/00 17:33:39 DSC_Alarm.pm Initialized Tue 10/10/00 09:47:38 09:47 10/10/00 System Closing by User Code 40 Tue 10/10/00 09:47:38 09:47 10/10/00 System Armed in Away Mode Tue 10/10/00 17:48:42 17:48 10/10/00 System Opening by User Code 40 Tue 10/10/00 23:37:33 23:37 10/10/00 System Closing by User Code 40 Tue 10/10/00 23:37:33 23:37 10/10/00 System Armed in Away Mode Wed 10/11/00 07:38:11 07:38 10/11/00 System Opening by User Code 40 + + +=head1 INHERITS + +B + +=head1 METHODS + +=over + +=cut + + @DSC_Alarm::ISA = ('Generic_Item'); my @DSC_Alarm_Ports; @@ -146,6 +173,12 @@ sub check_for_data # End of system functions; start of functions called by user scripts. # +=item C + +Where 'alarm-name' is the prefix used in the mh.ini entry 'DSC_Alarm_serial_port=xyz'. The 'alarm-name' argument defaults to 'DSC_Alarm' if not specified. + +=cut + sub new { my ($class, $port_name) = @_; $port_name = 'DSC_Alarm' if !$port_name; @@ -164,11 +197,24 @@ sub new { return $self; } +=item C + +Returns the last serial data received. Valid for 1 pass only. Important Note: Due to mh internals, the "said" method and the "state" method (and all "state" derived methods) lag each other's values by 1 pass through the user scripts. As such, any given script should use "said" or "state", but should NOT mix the two! + +=cut + + sub said { my $port_name = $_[0]->{port_name}; return $main::Serial_Ports{$port_name}{data_record}; } +=item C + +User number of last code used to arm/disarm system. If present, mh.ini parm DSC_Alarm_user_nn=xyz will cause "user" to return string "xyz" from the parm. + +=cut + sub user { my $instance = $_[0]->{port_name}; my $user = $_[0]->{user}; @@ -177,15 +223,37 @@ sub user { return $name; } +=item C + +True when system enters Alarm state. Valid for 1 pass only. + +=cut + sub alarm_now { return 'Alarm' eq $_[0]->{state_now}; } +=item C + +Zone number that caused Alarm. Valid only when alarm_now is true. + +=cut + sub zone { return if !alarm_now $_[0]; return $_[0]->{zone}; } +=item C + +Returns arming mode. Valid only when state = Armed. +Stay = System armed in stay mode; User pressed F1 key before arming. +Away = System armed in away mode; User pressed F2 key (or nothing) before arming + +Note: Most DSC systems will not arm in "Stay" mode unless at least one zone is defined as a "Stay/Away" zone. Also, even when "Away" mode is requested system will be in "Stay" mode unless a delay zone is violated during the exit delay. + +=cut + sub mode { return if 'Armed' ne $_[0]->{state}; return $_[0]->{mode}; @@ -194,3 +262,63 @@ sub mode { 1; +=back + +=head1 INHERITED METHODS + +=over + +=item C + +Returns last state of alarm system from following values: +Armed = System is closed and armed. +Disarmed = System is opened. +Alarm = System is alarming. + +=item C + +Same as state, but valid for 1 pass only. + + +=back + +=head1 INI PARAMETERS + + DSC_Alarm_serial_port=COM1 or /dev/ttys0 + DSC_Alarm_baudrate=4800 + +Multiple instances may be supported by adding instance numbers to the parms as in: + + DSC_Alarm:1_serial_port=COMx or /dev/ttysX + DSC_Alarm:1_baudrate=4800 + DSC_Alarm:2_serial_port=COMy or /dev/ttysY + DSC_Alarm:2_baudrate=4800 + +Optional mh.ini entries: + + DSC_Alarm_user_40=Jane Doe + DSC_Alarm_user_1=Bob Smith + +=head1 AUTHOR + +By: Danal Estes, N5SVV +E-Mail: danal@earthling.net + +Based on original code by Bill Sobel: +bsobel@vipmail.com + +=head1 SEE ALSO + +See mh/code/public/Danal/DSC_Alarm.pl for more info/examples + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + + diff --git a/lib/Generic_Item.pm b/lib/Generic_Item.pm index 094c4fb89..591db2ca0 100644 --- a/lib/Generic_Item.pm +++ b/lib/Generic_Item.pm @@ -1597,6 +1597,8 @@ sub android_xml_tag { return $xml_objects; } +=back + =head1 INI PARAMETERS =over diff --git a/lib/LCD.pm b/lib/LCD.pm index 6481afd28..4b062d17d 100644 --- a/lib/LCD.pm +++ b/lib/LCD.pm @@ -26,7 +26,7 @@ NONE =over -=item C $type: Either lcdproc or keyboard. $port: The ip:port of where lcdproc is running. diff --git a/lib/Network_Item.pm b/lib/Network_Item.pm index 9357cdce7..f8d91ebcb 100644 --- a/lib/Network_Item.pm +++ b/lib/Network_Item.pm @@ -40,7 +40,7 @@ B use IO::Socket qw(AF_INET SOCK_DGRAM SOL_SOCKET SO_BROADCAST); use Socket; -=item C $address: Ip address of the box you want to ping $interval: How often to ping (in seconds) diff --git a/lib/Process_Item.pm b/lib/Process_Item.pm index 0295c0581..94d65ffaf 100644 --- a/lib/Process_Item.pm +++ b/lib/Process_Item.pm @@ -2,8 +2,61 @@ use strict; package Process_Item; +=head1 NAME + +B - Object to run external programs. + +=head1 SYNOPSIS + + my $slashdot_news = "$Pgm_Root/data/web/slashdot_news.txt"; + $p_slashdot_news = new Process_Item("get_slashdot_news > $slashdot_news"); + start $p_slashdot_news if time_now('6:30 AM'); + display $slashdot_news if done_now $p_slashdot_news; + + $p_report_weblog = new Process_Item; + $p_report_weblog ->set_output("$config_parms{data_dir}/weblog_results.txt"); + if (time_now '2 AM') { + set $p_report_weblog "report_weblog /mh/data/logs/server.$Year_Month_Now.log"; + start $p_report_weblog; + } + +Example of multiple commands + + $test_process1 = new Process_Item; + set $test_process1 'sleep 1', 'sleep 2'; + add $test_process1 'sleep 1'; + +Example of running an internal mh subroutine + $v_test_ftp = new Voice_Cmd 'Test background ftp [get,put]'; + $p_test_ftp = new Process_Item; + if ($state = said $v_test_ftp) { + set $p_test_ftp "&main::net_ftp(file => '/tmp/junk1.txt', " . "file_remote => 'incoming/junk1.txt'," . "command => '$state')"; + set_timeout $p_test_ftpb 60*2; + start $p_test_ftpb; + } + print_log "Ftp command done" if done_now $p_test_ftp; + +More examples are in mh/code/examples/test_process.pl + +=head1 DESCRIPTION + +You can use this object to run external programs. On Win32 systems, the Win32::Process function is used. On Unix systems, the fork function is used. On either system, the following methods work in the same way: + +=head1 INHERITS + +NONE + +=head1 METHODS + +=over + +=cut + my (@active_processes, @done_processes); +=item C +=cut + sub new { my ($class, @cmds) = @_; my $self = {}; @@ -12,22 +65,44 @@ sub new { return $self; } +=item C +=cut + # Allow for multiple, serially executed, commands sub set { my ($self, @cmds) = @_; @{$$self{cmds}} = @cmds; } +=item C + + Process will timeout after $timeout seconds + +=cut + sub set_timeout { my ($self, $timeout) = @_; $$self{timeout} = $timeout; } + +=item C + +Program STDOUT errata goes to $output_file + +=cut + # Allow for process STDOUT to go to a file sub set_output { my ($self, $file) = @_; $$self{output} = $file; } +=item C + +Program STDERR errata goes to $errlog_file + +=cut + # Allow for process STDERR to go to a file sub set_errlog { my ($self, $file) = @_; @@ -39,6 +114,12 @@ sub set_killsig { $$self{killsig} = $killsig; } +=item C + +If you specify more than one program, they are run sequentially. done_now returns 1 after the last program is done. If program starts with &, then 'program arguments' is eval-ed as an internal mh function. Otherwise, 'program arguments' is run as an external command. On Windows, the &-> eval trick is supposed to work with perl 5.6+ (which has fork), but unfortunately, it causes perl to crash often, so is probably not useful yet. + +=cut + sub add { my ($self, @cmds) = @_; push @{$$self{cmds}}, @cmds; @@ -80,6 +161,11 @@ sub get_target { return $_[0]->{target}; } +=item C + +Starts the process with optional program arguements + +=cut sub start { my ($self, $cmd_override) = @_; @@ -224,17 +310,34 @@ sub restore_active { push(@active_processes, $self); } +=item C + +Returns the time (seconds since epoch) that the process finished. If the process has been started, but has not yet finished, it returns 0. + +=cut + sub done { my ($self) = @_; return ($$self{pid}) ? 0 : 1; } +=item C + +Returns the process id + +=cut sub pid { my ($self) = @_; return $$self{pid}; } +=item C + +Returns the time when the process timed out. done_now will still trigger for a timed_out process. + +=cut + sub timed_out { my ($self) = @_; return ($$self{timed_out}) ? 1 : 0; @@ -245,6 +348,12 @@ sub runtime { return $$self{runtime}; } +=item C + +Is true for the pass that the process finished on. + +=cut + sub done_now { $main::Respond_Target = $_[0]->{target}; return $_[0]->{done_now}; @@ -299,6 +408,12 @@ sub harvest { @active_processes = @active_processes2; } +=item C + +Stops the process. If called as a stand alone function (not as an object method), all active Process_Items are stopped. + +=cut + sub stop { my @process_list = @_; # If none specified, kill em all! @@ -347,6 +462,30 @@ sub nice_level { } } +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + # # $Log: Process_Item.pm,v $ # Revision 1.30 2005/10/02 23:53:39 winter diff --git a/lib/RCS_Item.pm b/lib/RCS_Item.pm index 55f45baef..d71172801 100644 --- a/lib/RCS_Item.pm +++ b/lib/RCS_Item.pm @@ -1,16 +1,26 @@ -################################################################### - package RCS_Item; - -# Copyright (c) 1999 Craig Schaeffer. All rights reserved. -# This program is free software. You may modify and/or -# distribute it under the same terms as Perl itself. -# This copyright notice must remain attached to the file. -# -# Protocol is documented here: -# http://www.resconsys.com/docs/X10%20BIDIRECTIONAL%20PROTOCOL%20REV13.pdf -#################################################################### +=head1 NAME + +B - + +=head1 SYNOPSIS + +NONE + +=head1 DESCRIPTION + +NONE + +=head1 INHERITS + +B + +=head1 METHODS + +UnDoc + +=cut @RCS_Item::ISA = ("Serial_Item"); @RCS_Item::Inherit::ISA = @ISA; @@ -153,6 +163,31 @@ sub list_by_type { 1; +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +Craig Schaeffer + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +# Copyright (c) 1999 Craig Schaeffer. All rights reserved. +# This program is free software. You may modify and/or +# distribute it under the same terms as Perl itself. +# This copyright notice must remain attached to the file. +# +# Protocol is documented here: +# http://www.resconsys.com/docs/X10%20BIDIRECTIONAL%20PROTOCOL%20REV13.pdf + +=cut + + # # Revision 1.1 1999/12/11 14:30:00 cschaeffer # - created. diff --git a/lib/RF_Item.pm b/lib/RF_Item.pm index b76b0e225..cc68c3530 100644 --- a/lib/RF_Item.pm +++ b/lib/RF_Item.pm @@ -57,6 +57,53 @@ use strict; package RF_Item; +=head1 NAME + +B - Receive states from X10 security devices and RF TV style remote through a W800RF32 module or an MR26A module + +=head1 SYNOPSIS + +RF items can be created in the items.mht in the following manner: + + RF, 68, keychain_remote, Security + RF, System, security_system, Security + RF, Sensor, security_sensors, Security + RF, 81, door_sensor, Security + RF, Remote, tv_remote, TV + +RF Items can be manually created in the following manner: + + $keychain_remote = new RF_Item('68' , 'keychain_remote' ); + $security_system = new RF_Item('system', 'security_system' ); + $security_sensors = new RF_Item('sensor', 'security_sensors'); + $door_sensor = new RF_Item('81' , 'door_sensor' ); + $tv_remote = new RF_Item('remote', 'tv_remote' ); + +The 2nd column the items.mht file (or the 1st parameter when manually creating a new RF_Item) is the 2 digit hexadecimal unit id of the particular transmitter or one of the following classes: + +system - Any device that change the state of the security system. States from any transmitters that go into this class are: armawaymin, armawaymax, armhomemin, armhomemax, disarm, panic +sensor - Any device that changes a sensor state. States from any transmitters that go into this class are: normal, normalmax, normalmin, alert, alertmin, alertmax +control - Any device that changes some general feature. States from any transmitter that go into this class are: lightson, lightsoff +remote - Any TV style remote control (UR51A, etc.). States from any transmitter that go into this class are: Power PC Title Display Enter Return Up Down Left Right Menu Exit Rew Play FF Record Stop Pause Recall 0 1 2 3 4 5 6 7 8 9 AB Ch+ Ch- Vol- Vol+ Mute + +Some transmitters have a min and max switch that cause the transmitter to send different states depending on that switch. If you don't care about the full detail of the state, you can do a test like: + + if (my $state = state_now $door_sensor =~ /^alert/) { ... } + +To determine what the 2 digit hexadecimal unit id for a particular security transmetter is, press the button on the transmitter (or open/close the sensor) and look at the misterhouse log to find the id that the unit transmitted. + +=head1 DESCRIPTION + +An RF_item is created to receive states from X10 security devices and RF TV style remote through a W800RF32 module or an MR26A module (the MR26A only passes TV remote style data through, it does not pass security data). + +To configure the W800 or MR26 interfaces, see the comments at the top of mh/lib/X10_MR26.pm and mh/lib/X10_W800.pm. + +=head1 INHERITS + +B + +=cut + @RF_Item::ISA = ('Generic_Item'); sub new { @@ -90,6 +137,29 @@ sub new { return $self; } +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + + # # $Log: RF_Item.pm,v $ # Revision 1.3 2004/02/01 19:24:35 winter diff --git a/lib/Socket_Item.pm b/lib/Socket_Item.pm index 11ed90905..797711e90 100644 --- a/lib/Socket_Item.pm +++ b/lib/Socket_Item.pm @@ -524,6 +524,7 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. =cut + 1; # diff --git a/lib/Text_Cmd.pm b/lib/Text_Cmd.pm index d92422654..e67348aa0 100644 --- a/lib/Text_Cmd.pm +++ b/lib/Text_Cmd.pm @@ -2,10 +2,58 @@ use strict; package Text_Cmd; +=head1 NAME + +B + +=head1 SYNOPSIS + +Create a widget for inputing text commands + $Text_Input = new Generic_Item; + &tk_entry("Text Input", $Text_Input, "tcmd1", $tcmd1); + + if ($state = state_now $Text_Input) { + my $set_by = get_set_by $Text_Input; + print_log "Text_Input set_by $set_by typed $state"; + run_voice_cmd($state, undef, $set_by); + } + +Create commands + $tcmd1 = new Text_Cmd('hi (a|b|c)'); + $tcmd2 = new Text_Cmd('bye *(.*)'); + $tcmd3 = new Text_Cmd('(hi.*) (bye.*)'); + +Fire events if the commands match text input + $tcmd1->tie_event('print_log "tcmd1 state: $state"'); + print_log "tcmd2 state=$state" if $state = state_now $tcmd2; + print_log "tcmd3 state=$state set_by=$tcmd3->{set_by}, target=$tcmd3->{target}" if $state = state_now $tcmd3; + +=head1 DESCRIPTION + +Use this object if you want to fire events based on text entered. Unlike the Voice_Cmd item, you can use Text_Cmd to capture arbitrary text, using a regular expression. + +Like Voice_Cmd items, all text passed to the run_voice_cmd and process_external_command functions will be tested against all Text_Cmd items. All items that match will fire their state_now methods. + +=head1 INHERITS + +B + +=head1 METHODS + +=over + +=cut + my ($hooks_added, @list_objects); @Text_Cmd::ISA = ('Generic_Item'); +=item C + +$re_string - is any valid regular expresion. Use the () grouping to pick the data that will be returned with the state_now method. + +=cut + sub new { my ($class, $text) = @_; my $self = {}; @@ -53,6 +101,45 @@ sub check_match { return undef; } +=back + +=head1 INHERITED METHODS + +=over + +=item C + +Returns the text from the () match in the $re_string. If there was not () grouping, it returns 1. If there is more than one () grouping, the resulting matches are concatonated together with | as a separator. + +=item C + +Returns the state that was received or sent in the current pass. + +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + + # # $Log: Text_Cmd.pm,v $ diff --git a/lib/Timer.pm b/lib/Timer.pm index dd7245126..cb02ec2cf 100644 --- a/lib/Timer.pm +++ b/lib/Timer.pm @@ -1,6 +1,53 @@ use strict; package Timer; +=head1 NAME + +B + +=head1 SYNOPSIS + + $timer_laundary = new Timer; + $v_laundary_timer = new Voice_Cmd('Laundary timer [on,off]'); + if ($state = said $v_laundary_timer) { + if ($state eq ON) { + play('rooms' => 'shop', 'file' => 'cloths_started.wav'); + set $timer_laundary 35*60, 'speak "rooms=all The laundary clothes done"', 4; + } + else { + speak 'rooms=shop The laundry timer has been turned off.'; + unset $timer_laundary; + } + } + +This example uses an anonymous subroutine + + $v_test_delay = new Voice_Cmd 'Test timer with [1,5,10] seconds'; + if ($state = said $v_test_delay) { + print_log "Starting $state second timer test"; + my $timer = new Timer; + set $timer $state, sub { + print_log "Ending $state second timer test"; + } + # set $timer $state, "print_log 'Ending $state second timer test'"; + } + +=head1 DESCRIPTION + +The Timer object can be used to run an action one or more times, at a specified interval. + +=head1 INHERITS + +B<> + +=head1 METHODS + +=over + +=cut + + + my ($class, $self, $id, $state, $action, $repeat, @timers_with_actions, $resort_timers_with_actions, @sets_from_previous_pass); @@ -60,6 +107,11 @@ sub delete_timer_with_action { } } +=item C + +Used to create the object. + +=cut sub new { my ($class, $id, $state) = @_; @@ -112,6 +164,14 @@ sub state_log { return @{$$self{state_log}} if $$self{state_log}; } +=item C + +$period is the timer period in seconds +$action (optional) is the code (either a string or a code reference) to run when the timer expires +$cycles (optional) is how many times to repeat the timer. Set to -1 to repeat forever. + +=cut + sub set { ($self, $state, $action, $repeat) = @_; @@ -164,6 +224,12 @@ sub resort_timers_with_actions { $resort_timers_with_actions = 1; } +=item C + +Unset the timer. 'set $my_timer 0' has the same effect. + +=cut + sub unset { ($self) = @_; undef $self->{expire_time}; @@ -176,6 +242,11 @@ sub delete_old_timers { undef @timers_with_actions; } +=item C + +Runs the timers action, even if the timer has not expired. + +=cut sub run_action { ($self) = @_; @@ -207,6 +278,12 @@ sub run_action { } } +=item C + +Returns true for the one pass after the timer has expired. + +=cut + sub expired { ($self) = @_; # print "db $self->{expire_time} $self->{pass_triggered}\n"; @@ -232,6 +309,12 @@ sub expired { } } +=item C + +These methods return the hours, minutes or seconds remaining on the timer. The _now methods only return the remaining time on the hour, minute, or second boundary. + +=cut + sub hours_remaining { ($self) = @_; return if inactive $self; @@ -294,6 +377,11 @@ sub seconds_remaining_now { } } +=item C + +Returns true if the timer is still running. + +=cut sub active { ($self) = @_; @@ -306,11 +394,24 @@ sub active { return 0; } } + +=item C + +Returns true if the timer is has expired or has not been set. + +=cut + sub inactive { ($self) = @_; return !&active($self); } +=item C + +Starts the timer + +=cut + # The reset of these methods apply to a countup/stopwatch type timer sub start { ($self) = @_; @@ -322,6 +423,12 @@ sub start { $self->{time_adjust} = 0; } +=item C + +Restarts the timer (start on an active timer does nothing) + +=cut + sub restart { ($self) = @_; $self->{time} = time; @@ -336,18 +443,36 @@ sub restart { } +=item C + +Stops a timer. + +=cut + sub stop { ($self) = @_; $self->{time} = undef; $self->{expire_time} = undef; } +=item C + +Pauses + +=cut + sub pause { ($self) = @_; return if $self->{time_pause}; # Already paused $self->{time_pause} = time; } +=item C + +Bet you can guess :) + +=cut + sub resume { ($self) = @_; return unless $self->{time_pause}; # Not paused @@ -355,6 +480,12 @@ sub resume { $self->{time_pause} = 0; } +=item C + +Returns the seconds on the timer. + +=cut + sub query { ($self) = @_; my $time = $self->{time}; @@ -367,6 +498,32 @@ sub query { 1; +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +See mh/code/bruce/timers.pl for more examples + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + + + # # $Log: Timer.pm,v $ # Revision 1.32 2004/11/22 22:57:26 winter diff --git a/lib/Voice_Cmd.pm b/lib/Voice_Cmd.pm index 2ae38a91d..160338d2c 100644 --- a/lib/Voice_Cmd.pm +++ b/lib/Voice_Cmd.pm @@ -1,5 +1,46 @@ - package Voice_Cmd; + +=head1 NAME + +B + +=head1 SYNOPSIS + + $v_backyard_light = new Voice_Cmd 'Backyard Light [on,off]'; + set $backyard_light $state if $state = said $v_backyard_light; + + $v_test1 = new Voice_Cmd '{turn,set} the {living,famliy} room {light,lights} [on,off]'; + $v_test2 = new Voice_Cmd '{Please, } tell me the time'; + $v_test3 = new Voice_Cmd '{What time is it,Tell me the time}'; + $v_fan = new Voice_Cmd 'Fan [on,off]', 'Ok, I turned the fan $v_indoor_fountain->{said}'; + $v_fan = new Voice_Cmd 'Fan [on,off]', 'Ok, I turned the fan %STATE%'; + +In addition to the said command on a specific object, you can use &Voice_Cmd::said_this_pass to detect which command was spoken this pass and &Voice_Cmd::noise_this_pass to detect if noise was detected this pass (this function currently only works with viavoice). + + if (my $speak_num = &Voice_Cmd::said_this_pass) { + my $text = &Voice_Cmd::text_by_num($speak_num); + print_log "spoken text: $speak_num, $text"; + } + + if (my $text = &Voice_Cmd::noise_this_pass) { + print_log "Noise detected" if $text eq 'Noise'; + } + +=head1 DESCRIPTION + +Use the Voice_Cmd object to create voice commands. Even without a Voice Recognition engine installed, this is useful as these commands can also be run from the Tk, web, telnet, and file interfaces. + +=head1 INHERITS + +B + +=head1 METHODS + +=over + +=cut + + @Voice_Cmd::ISA = ('Generic_Item'); use strict; @@ -442,6 +483,24 @@ sub voice_items { return sort {uc $a cmp uc $b} @cmd_list2; } +=item C + +$command - can be a simple string (e.g. 'What time is it') or it can include a list of 'states' (e.g. 'Turn the light [on,off]'). The state enumeration group is a comma delimited string surrounded with []. In addition to one state enumeration group, you can specify any number of phrase enumeration groups. These are comma delimited strings surrounded by {} (e.g. 'Turn the {family room,downstairs} TV [on,off]'). Use this when you have several different ways to describe the same thing. + +$response - is the text or wave file that will be played back when the VR engine detects this command. If not defined, the mh.ini parm voice_cmd_response parm is used (default is "Ok, %HEARD%"). You can put %STATE%, %HEARD%, or any variable in the response string and have it substituted/evaluated when the response is spoken. + +$confirm - is either 0 or 1 (default is 0). If set to 1, then mh will ask 'Confirm with a yes or a no'. If yes or no is not heard within 10 seconds, the command is aborted. + +$vocabulary - allows you to define multiple vocabularies. You can then use these functions to enable and disable the vocabularies: + + &Voice_Cmd::enablevocab($vocabulary) + &Voice_Cmd::disablevocab($vocabulary) + +Vocabularies are enabled by default. The default vocabulary is 'misterhouse'. See mh/code/bruce/viavoice_control.pl for examples. This code allows you to switch between 'awake', 'asleep', and 'off' VR modes. + +NOTE: Currently only the viavoice VR engine (mh.ini parm voice_cmd=viavoice) will use the $response, $confirm, and $vocabulary_name options. We may be able to create a viavoice_server for windows, but that would probably not be free like it is on linux. If you have a linux box on your network, you can have your windows mh use the linux viavoice_server process. + +=cut sub new { my ($class, $text, $response, $confirm, $vocab) = @_; @@ -623,6 +682,12 @@ sub _clean_text_string { return $text; } +=item C + +Contols the order that the commands are listed in web Category list. The default is alphabetically by file, then by name. + +=cut + sub set_order { return unless $main::Reload; my ($self, $order) = @_; @@ -742,6 +807,49 @@ sub android_xml { 1; +=back + +=head1 INHERITED METHODS + +=over + +=item C + +Is true for the one pass after the command was issued. If the command was built from a list of possible states, then said returns the state that matches. + +=item C + +Returns the same thing as said, except it is valid for all passes, not just the pass after the command was issued. + +=item C + +Point to the icon member you want the web interface to use. See the 'Customizing the web interface' section of this document for details. + +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +See mh/code/examples/Voice_Cmd_enumeration.pl for more Voice_Cmd examples +See mh/code/bruce/lcdproc.pl for more examples. + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + # # $Log: Voice_Cmd.pm,v $ # Revision 1.47 2004/07/18 22:16:37 winter diff --git a/lib/Weather_Item.pm b/lib/Weather_Item.pm index 7fa3cefcd..7b17f8960 100644 --- a/lib/Weather_Item.pm +++ b/lib/Weather_Item.pm @@ -2,6 +2,39 @@ use strict; package Weather_Item; +=head1 NAME + +B - This object can be used to track data stored in the global %Weather array. + +=head1 SYNOPSIS + + $WindSpeed = new Weather_Item 'WindSpeed'; + $WindSpeed-> tie_event('print_log "Wind speed is now at $state"'); + + $freezing = new Weather_Item 'TempOutdoor < 32'; + if (state_now $fountain eq ON and state $freezing) { + speak "Sorry fountains don't work too well when frozen"; + set $fountain OFF + } + + $Windy = new Weather_Item 'WindSpeed > 15'; + speak "Wind is gusting at $Weather{WindSpeed} mph" if state $Windy; + + # For current state, easiest to use it directly + speak "Outdoor temperature is $Weather{TempOutdoor} degrees"; + +=head1 DESCRIPTION + +=head1 INHERITS + +B + +=head1 METHODS + +=over + +=cut + # $w_x = new Weather_Item(TempIndoor); # returns e.g. 68/82/etc # $w_x = new Weather_Item('TempIndoor > 99') # returns evaluated expression if defined else return value undefined @@ -33,6 +66,12 @@ sub item_transform($) { ($_ =~ /^(and|or|not|eq|ne|clear|cloudy|sunny|partly|mostly)$/i)?"$_":"\$::Weather{$_}"; } +=item C + +$type is the name of the %Weather index you want to monitor. $type can also have a =<> comparison operator in it so you can make the object a true/false test. + +=cut + sub new { my ($class, $type) = @_; my @members; @@ -71,6 +110,12 @@ sub new { } +=item C + +Returns the last state, or 1/0 if $comparition and $limit were used. + +=cut + sub state { my ($self) = @_; my $valid; @@ -99,6 +144,39 @@ sub default_setstate { 1; +=back + +=head1 INHERITED METHODS + +=over + +=item C + +Returns the state only when the weather data changed. + +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +For examples on interface code that stores data into %Weather, see mh/code/bruce/weather_monitor.pl (uses mh/lib/Weather_wx200.pm), mh/code/public/iButton_ws_client.pl, and mh/code/public/weather_com.pl + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut # # $Log: Weather_Item.pm,v $ diff --git a/lib/X10_Items.pm b/lib/X10_Items.pm index 2ac1c3f0d..b8695edd9 100644 --- a/lib/X10_Items.pm +++ b/lib/X10_Items.pm @@ -3,8 +3,94 @@ package X10_Item; -#use strict; +=head1 NAME + +B - This item is for controling X10 lamp modules and light switches. It is derived from Serial_Item and the strings it sends are like Serial Items, except an 'X' prefix is prepended to indicate an X10 command. The X strings are converted by one of the various X10 interfaces into the appropriate commands for that interface. + +=head1 SYNOPSIS + +X10 items can be created in the items.mht in the following manner: + + X10I, A1, Test_light, Bedroom, cm11, preset resume=80 + +If a single character is used (e.g. X10_Item 'D'), commands apply to all X10_Items with that house code. The 'on' and 'off' states are translated to ALL_ON and ALL_OFF commands for that house code. For example: + + $v_test_lights = new Voice_Cmd 'All lights [on,off]'; + $test_lights = new X10_Item 'O'; + set $test_lights $state if $state = said $v_test_lights; + +The toggle and various brightness commands can be sent to a house code only item. The command will be sent to each X10_Item defined with the same house code. This might produce undesired results, particularly when changing brightness levels. See the Group item for a better way to do that. + +If you are using more than one X10 interface and you want to control an X10_Item with a specific interface, use the optional interface argument. For example, if you want to control the local module on a RF Transceiver, you can tell mh to use the RF CM17 interface, like this: + + $test_light = new X10_Item('A1', 'CM17'); + +The various brightness commands (60%, +20, -50%) all work even on dumb modules that only support on, off, dim, and brighten. X10_Item keeps track of changes it makes to the brightness level and converts any absolute brightness settings into relative changes. Since these dumb modules typically don't have two-way capability, the item will be out of sync if changes are made locally at the switch. Also, if the module was off, it will first be turned to full on, since the older modules can not be dimmed from an off state. + +After doing one or more bright/dim/on/off commands, you can query the current brightness level of a device with the level method. For example: + + if ($state = state_now $pedestal_light) { + my $level = level $pedestal_light; + print_log "Pedestal light state=$state, level=$level" + } + +It is much better to use one the newer (more expensive) direct dim and two-way capable modules, such as the X10 LM14A lamp module. The X10_Item supports both the newer extended data dim commands used by the LM14 and Leviton switches (64 brightness levels), and the older preset dim commands used by PCS and Switchlinc switches (32 brightness levels). + +Set the 3rd X10_Item parm to specify the option flags that correspond to your lamp module or switch. Valid flags are: + + 'lm14' - for X10 LM14, uses extended data dim commands, remembers dim level when off + 'preset' - same as lm14 + 'preset2' - same as lm14 and preset, except send on after direct dims, required by some Leviton switches + 'preset3' - same as lm14 and preset, except uses older preset dim commands, for Switchlinc and PCS + 'resume=##' - module resumes from off at ## percent + 'transmitter' - special case, see X10_Transmitter + +Option flags are case insensitive. Separate multiple option flags with a space. + +For example: + + $test_light2 = new X10_Item('O7', undef, 'preset resume=81'); + $v_test_light2 = new Voice_Cmd("Set test light to [on,off,bright,dim,5%,10%,20%,30%,40%,50%,60%,70%,80%,90%]"); + set $test_light2 $state if $state = said $v_test_light2; + +If the newer extended data dim commands are to be used, then the brightness level is converted into a &P## command and passed to the X10 interface. You can also use them directly, using &P## (## = 1->64) as shown in this example: + + $test_light1 = new X10_Item('O7', 'CM11', 'LM14'); + $v_test_light1 = new Voice_Cmd("Set test light to [on,off,bright,dim,&P3,&P10,&P30,&P40,&P50,&P60]"); + set $test_light1 $state if $state = said $v_test_light1; + +Note: not all of the X10 interfaces support this command. + +The older direct dim method used the two Preset Dim X10 commands. The 32 brightness levels are sent by combining a house code with one of the two Preset Dim commands, using the following table: + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 PRESET_DIM1 + M N O P C D A B E F G H K L I J + + 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 PRESET_DIM2 + M N O P C D A B E F G H K L I J + +Note: not all of the X10 interfaces support this command. + +Since this item is inherits from Generic_Item, you can use the set_with_timer method. For example, this event will turn on a on a warning light to 20% for 5 seconds: + + set_with_timer $watchdog_light '20%', 5 if file_unchanged $watchdog_file; + + + +=head1 DESCRIPTION + +=head1 INHERITS + +B + +=head1 METHODS + +=over + +=cut + + +#use strict; use X10_Interface; use Serial_Item; use Dummy_Interface; @@ -22,6 +108,16 @@ sub reset { @X10_Item::ISA = ('X10_Interface'); +=item C + +house code[unit number] - The first argument is required and is either a house code by itself or a house code and unit number. Note that the X10 unit code is numbered either 1->16 or 1->9,A->G. For example device 16 in house code P could be P16 or PG + +interface - Optional, specifies which X10 interface to use + +option flags - Optional, specifies one or more module options (see below) + +=cut + sub new { my ($class, $id, $interface, $type) = @_; @@ -189,6 +285,36 @@ sub property_changed { } } +=item C + +Sets the item to the specified state + + 'on' + 'off' + 'toggle' - toggles between on and off + 'brighten' + 'dim' + '+##' - increase brightness by ## points + '-##' - decrease brightness by ## points + '##%' - set brightness to ## percent + '+##%' - increase brightness by ## percent + '-##%' - decrease brightness by ## percent + 'double on' - on some modules this sets full brightness at ramp rate + 'double off' - on some modules this sets 0 brightness immediately + 'triple on' - same as double on, but immediate + 'triple off' - same as double off + 'status' - requests status from a two-way capable module + 'manual' - sends house code and unit number without a command + +These states are rarely used and provided for special cases + + '&P##', 'PRESET_DIM1', 'PRESET_DIM2', 'ALL_LIGHTS_OFF', 'HAIL_REQUEST', + 'HAIL_ACK', 'EXTENDED_CODE', 'EXTENDED_DATA', 'STATUS_ON', 'STATUS_OFF', 'Z##' + +Note: not all states are supported by all lamp modules and X10 interfaces. + +=cut + # Check for toggle data sub set { my ($self, $state, $set_by) = @_; @@ -287,6 +413,12 @@ sub set { } } +=item C + +Update the state and level when X10 commands are received + +=cut + sub set_receive { my ($self, $state, $set_by) = @_; @@ -295,6 +427,12 @@ sub set_receive { $self->{interface}->set_receive($state, $set_by); } +=item C + +Recalculates state whenever state is changed + +=cut + # Try to keep track of X10 brightness level sub set_x10_level { my ($self, $state) = @_; @@ -374,6 +512,12 @@ sub resume { return $_[0]->{resume}; } +=item C + +Returns the current brightness level of the item, 0->100 + +=cut + # This returns current brightness level ... see above sub level { # print "db2 l=$_[0]->{level} s=$_[0]->{state}\n"; @@ -423,8 +567,61 @@ sub set_by_housecode { } + +=back + +=head1 INHERITED METHODS + +=over + +=item C + +Returns the last state that was received or sent + +=item C + +Returns the state that was received or sent in the current pass + +=back + +=head1 INI PARAMETERS + +NONE + +=head1 AUTHOR + +UNK + +=head1 SEE ALSO + +NONE + +=head1 LICENSE + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +=cut + package X10_Appliance; +=head1 NAME + +B + +=head1 DESCRIPTION + +Same as X10_Item, except it has only has pre-defined states 'on' and 'off' + +=head1 INHERITS + +B + +=cut + @X10_Appliance::ISA = ('X10_Item'); sub new { @@ -465,6 +662,22 @@ sub new { package X10_Transmitter; +=head1 NAME + +B + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +Like an X10_Item, but will not be set by incoming X10 data. Simulates transmit only devices like keypads. Can be used in place of X10_Item if you have complicated code that might get into a loop because we are not ignoring incoming X10 data for transmit-only devices. + +=head1 INHERITS + +B + +=cut + @X10_Transmitter::ISA = ('X10_Item'); sub new { @@ -481,6 +694,16 @@ package X10_RF_Receiver; package X10_Garage_Door; +=head1 NAME + +B - For the Stanley Garage Door status transmitter. + +=head1 INHERITS + +B + +=cut + @X10_Garage_Door::ISA = ('X10_Item'); sub new { @@ -684,8 +907,29 @@ sub new { return $self; } +=head1 SEE ALSO + +See mh/code/public/Danal/Garage_Door.pl + +=cut + + package X10_IrrigationController; +=head1 NAME + +B + +=head1 DESCRIPTION + +For this sprinkler device: http://ourworld.compuserve.com/homepages/rciautomation/p6.htm which looks the same as the IrrMaster 4-zone sprinkler controller listed here: http://www.homecontrols.com/product.html?prodnum=HCLC4&id_hci=0920HC569027 + +=head1 INHERITS + +B + +=cut + # More info at: http://ourworld.compuserve.com/homepages/rciautomation/p6.htm # This looks the same as the IrrMaster 4-zone sprinkler controller # listed here: http://www.homecontrols.com/product.html?prodnum=HCLC4&id_hci=0920HC569027 @@ -933,24 +1177,50 @@ sub zone_delay return; } +=head1 SEE ALSO + +More info at: http://ourworld.compuserve.com/homepages/rciautomation/p6.htm This looks the same as the IrrMaster 4-zone sprinkler controller listed here: http://www.homecontrols.com/product.html?prodnum=HCLC4&id_hci=0920HC569027 +=cut package X10_Switchlinc; -@X10_Switchlinc::ISA = ('X10_Item'); +=head1 NAME -=begin comment +B - For the Switchlinc contrllers + +=head1 SYNOPSIS + + # Just picked this device to use to send the clear + $Office_Light_Torch->set("clear"); + # Send a command to each group member to make it listen + $SwitchlincDisable->set("off"); + # Just picked this device item to send the command + $Office_Light_Torch->set("disablex10transmit"); + +=head1 DESCRIPTION + +Inherts all the functionality from X10_Item and adds the following states: - # Example usage - # Just picked this device to use to send the clear -$Office_Light_Torch->set("clear"); - # Send a command to each group member to make it listen -$SwitchlincDisable->set("off"); - # Just picked this device item to send the command -$Office_Light_Torch->set("disablex10transmit"); + 'clear' + 'setramprate' + 'setonlevel' + 'addscenemembership' + 'deletescenemembership' + 'setsceneramprate' + 'disablex10transmit' + 'enablex10transmit' + +Also sets the 'preset3' X10_Item option which causes the older Preset Dim commands to be used for setting the brightness level directly. + +=head1 INHERITS + +B =cut +@X10_Switchlinc::ISA = ('X10_Item'); + sub new { my ($class, $id, $interface, $type) = @_; $type .= ' ' if $type; @@ -992,6 +1262,11 @@ sub new { return $self; } +=head1 SEE ALSO + +See the {state}"; -# } +B + +=head1 SYNOPSIS + + $Garage_TempLinc = new X10_TempLinc('P') + + request current temperature + $Garage_TempLinc->set(STATUS); + + handle temperature changes as reported by the sensor + if (state_now $Garage_TempLinc) + { + speak "The temperature in the garage is now $Garage_TempLinc->{state}"; + } + +=head1 DESCRIPTION + +This is smarthome.com part number 1625 it can be setup to request temperature with the STATUS state, or automatically send out temperature change it uses the same temperature translation that the RCS bi-directional thermostat uses. It should use its own house code because it needs unit codes 11-16 to be used to received the preset_dim commands for temperature degrees. However, in theory, (I haen't ried it yet), you could used the same house code with unit codes 1-10 if absolutely needed. + +=head1 INHERITS + +B + +=cut + +@X10_TempLinc::ISA = ('X10_Item'); sub new { @@ -1160,6 +1436,17 @@ sub new # Ote themostate from Ouellet Canada package X10_Ote; + +=head1 NAME + +B - Supports the OTE X10 themostat from Ouellet Canada. + +=head1 INHERITS + +B + +=cut + @X10_Ote::ISA = ('X10_Item'); sub new { my ($class, $id, $interface) = @_; @@ -1192,48 +1479,53 @@ sub new { } -## X10_Sensor -- by Ingo Dean -## -## Do you have any of those handy little X10 MS12A battery-powered motion sensors? -## -## Ever have the battery die and you didn't notice for weeks? -## -## Here's your answer - use the X10_Sensor instead of the Serial_Item when you define -## it, and your house will notice when your sensor hasn't been tripped in 24 hours, -## allowing you to check on the batteries. -## -## Sensor Item can be created with a type to specify the sensors properties. -## Ex: -## X10MS, CA, work_room_motion, Sensors|Motion_Sensors, Motion -## X10MS, CB, work_room_brightness, Sensors|Brighness_Sensors, Brightness -## or: -## X10MS, CA, work_room_sensors, Sensors, MS13 -## -## Ex: -## $work_room_motion = new X10_Sensor('CA', 'work_room_motion', 'Motion'); -## $work_room_brightness = new X10_Sensor('CB', 'work_room_brightness', 'Brightness'); -## or: -## $work_room_sensors = new X10_Sensor('CA', 'work_room_sensors', 'MS13'); -## -## The 'MS13' Sensor Item listens for x10 'CA' cmds for motion and x10 'CB' cmds for brightness -## state changes. The brighness state is saved in a 'dark' private variable and can be fetched -## with the dark() method. The 'MS13_Motion' type only listens for state changes on 'CA' cmds -## and 'MS13_Brightness' only listens for state changes for 'CB'. An advantage to using two -## X10 Sensor Items is that both states of the MS13 can be easily printed in log files: -## Ex: -## print_log "state of work_room_motion = ", state $work_room_motion; -## print_log "state of work_room_brightness = ", state $work_room_brightness; - - - - -## ## Todo: ## + make the countdown time configurable per sensor ## + make the action configurable per sensor package X10_Sensor; +=head1 NAME + +B + +=head1 SYNOPSIS + + $sensor_hall = new X10_Sensor('A4', 'sensor_hall', 'MS13'); + $work_room_motion = new X10_Sensor('CA', 'work_room_motion', 'motion'); + $work_room_bright = new X10_Sensor('CB', 'work_room_bright', 'brightness'); + +.mht table examples: + + X10MS, XA2AJ, sensor_bathroom, Sensors|Upstairs + X10MS, A4, sensor_hall, Sensors|Downstairs, MS13 + + X10MS, CA, work_room_motion, Sensors|Motion_Sensors, Motion + X10MS, CB, work_room_brightness, Sensors|Brighness_Sensors, Brightness + X10MS, CA, work_room_sensors, Sensors, MS13 # This detects both motion and brightness + +With MS13 specified, it will return states named motion,still,light, and dark. With Motion specified, it will return only the motion and still states. With Brightness specified, it will return only the light and dark states. In all cases, methods light and dark will return the current light/dark state. + +Examples: + + set_with_timer $light1 ON, 600 if $work_room_motion eq 'motion'; + + speak 'It is dark downstairs' if dark $sensor_downstairs; + +Without the MS13 or Brightness type, the light/dark codes will be ignored. + +=head1 DESCRIPTION + +Do you have any of those handy little X10 MS12A battery-powered motion sensors? Here's your answer - use the X10_Sensor instead of the Serial_Item when you define it, and your house will notice when your sensor hasn't been tripped in 24 hours, allowing you to check on the batteries. + +If you have an sensor that detects and sends codes for daytime and nighttime (light and dark levels), pass in a optional type MS13, Motion, or Brightness. For the id, you can use the 2 character, or 5 character X10 code. + +=head1 INHERITS + +B + +=cut + @X10_Sensor::ISA = ('X10_Item'); sub init { @@ -1356,7 +1648,11 @@ sub dark { return $_[0]->{dark}; } +=head1 AUTHOR +Ingo Dean + +=cut package X10_Scenemaster; From 88310c62009b430e3d46154a03073494af9385c9 Mon Sep 17 00:00:00 2001 From: Nitsud Date: Sun, 3 Mar 2013 10:10:20 -0500 Subject: [PATCH 2/2] faq.pod update by Vargester requested by Stovenour --- docs/faq.pod | 3840 +++++++++++++++++++++++--------------------------- 1 file changed, 1789 insertions(+), 2051 deletions(-) diff --git a/docs/faq.pod b/docs/faq.pod index d7f6b8194..b7292385b 100644 --- a/docs/faq.pod +++ b/docs/faq.pod @@ -1,2051 +1,1789 @@ -=pod - - -=head1 1: MisterHouse operational questions - - -=head2 1.1: What OSes can it run on? - -It has been tested on Windows 95, 98, NT 4.0, and 2K. On Unix, it has been run on -Linux, 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 (e.g. Mac?), so the Serial IO related -function would take some work. - -=head2 1.2: How can I make it run faster and use less memory? - -On my Celron 400 Mhz computer running Windows 98, using 60 code files with 6000 lines of code, -mh takes 10% the cpu, running at 9 passes per second and using about 30 MB of 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) - - - -=head2 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). - -=head2 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. - -=head2 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 - - -=head2 1.6: How are the X10 and Serial Items implemented, indpendent of the platform? - -This answer is authored by Bill Birthisel, author of the SerialPort and CommPort modules. - -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 ;-) - - -=head2 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 - - - -=head2 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. - - - -=head2 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. - - - -=head2 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" - - -=head2 1.12: How can I debug time 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 stoping your normal mh. - -=head2 1.13: What are the advantages/disadvantages to running the compiled versions of mh? - -Advantages: - -=over - -=item * - -You don't need the latest version of perl installed - -=item * - -You don't have to install additional perl modules - -=back - -Disadvantages: - -=over - -=item * - -For some reason, starting mh with the compiled versions is slower. On my windows box, it is 10 seconds -vs- 20 seconds. - -=item * - -You can apply quick patches to mh, -vs- downloading a larger, less frequently updated mh.exe file. - -=back - -The memory and cpu used, once mh is started, is the same. - - -=head2 1.14: 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. - - -=head2 1.15 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. - -=head2 1.16 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. - -=head2 1.17: How can I use Family Radios with MisterHouse? - -=begin html -There is seperate FAQ on the FRS topic in -mh/docs/faq_frs.html - -=end html - - -=head2 1.18: 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'; - } - - -=head2 1.19: How can I use an Internet Appliance with MisterHouse? - -=begin html -There is seperate FAQ on varous Internet Appliances in -mh/docs/faq_ia.html - -=end html - - -=head2 1.20: 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. - - - - -=head1 2: MisterHouse coding questions - -=head2 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. - -=head2 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'; - - -=head2 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. - - -=head2 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. - - -=head2 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 = ) { - $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") - } - - -=head2 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;"; - } - -=head2 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. - -=head2 2.8: Can I use mh to control other windows - -On Windows (95,98, NT), 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. - - - -=head2 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. - - -=head2 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; - - -=head2 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. - - -=head2 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". - - -=head2 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. - - -=head2 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. - - -=head2 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. - - -=head2 2.16: How are states set for each pass though the user code loop? - -From Bill Sobel on 02/2003: - -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 -no 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'. - - -=head2 2.17: Common Perl and mh coding errors - -=begin html -Clive Freedman sent in some useful tips on common coding errors in -mh/docs/faq_damnblast.html - -=end html - -=head2 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' - -=head1 3: Linux specific questions - -=head2 3.1: When I run Viavoice and festival at the same time I get "Can't open output file '/dev/dsp'" - -Answer complements of Brent L Johnson. - -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. - -From Dave Lounsberry and Denis Cheong on 10/2001: - -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 - - -=head2 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 - -=head2 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 - - - -=head2 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. - - -=head2 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) - - - -=head1 4: Windows specific questions - -=head2 4.1: mh seems to cause some windows to hang - -If you are experiencing problems with windows not popping -up when they should (e.g. control panel or install shield), -you will want to install DCOM 1.3, available from here: - - http://www.microsoft.com/com/dcom/dcom98/dcom1_3.asp - -Note, I had run all the 'Windows updates', including the Service Pack 2, but -I still had the problem until I installed the above. - -For Windows 95, the update is at: - - http://www.microsoft.com/com/dcom/dcom95/dcom1_3.asp - - -=head2 4.2: 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. - -=head2 4.3 How do I run MH when not logged in to Win2K or XP? - -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 peopld have Windows do an auto-login and add mh to the startup. - - -=head1 5: Perl questions - -=head2 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. - - -=head2 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." - -Bill Sobel sent a pointer to J: http://www.armedbear.org/. -"I was using notepad and switched to 'J' and open source development editor. -The author, Peter Graves, is a -coworker of mine and all around swell guy. This java based editor already -includes Perl syntax highlighting and Peter is pretty quick about -fixes/changes." - -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 " - -Doug likes $20 shareware CodeWhiz: http://www.incatec.com . Colored commands, auto indent, auto remark/unremark, line #s, etc. - - -=head2 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 - - -=head1 6: Misc questions - -=head2 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: href=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, - - -=head2 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 - -=head2 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. - - -=head2 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/ - - -=head2 6.5: How do I contribute additions or updates to the mh code? - -The MisterHouse code is maintained via a SVN repository on sourceforge. -Instructions on how to commit changes can are on the wiki here: -http://misterhouse.wikispaces.com/Subversion - -If you have minor changes and don't want to bother with a sourceforge ID, feel free to mail them to Bruce or the mailing list. - - -=head2 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 - - -=head2 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 - - -=head2 6.8 What sort of hardware do you have in your house? - -This is what is currently (04/2001) in Bruce's house (see mh/docs/mh.* 'List of supported hardware interfaces' for more info): - - - Mh running on a dual 600 PIII Win 2K box great for quick mh debugging :) - - SB Live Value sound card (supports simultaneous sound sources) - - PCI ByteRunner 8 port serial card - - PCI phone modem for callerid logging and announcements - - Linux box for hosting misterhouse.net - - 5 other networked computers for mp3 client/servers, - shoutcast server, games, writing, and work from home - - Radio Shack PA amp with a PA speaker in each room - - Wiring closet with 3 DIO weeder cards and 2 analog cards - - 16 relay card from jameco for PA speaker switch - - Home brew motor/relays for up/down control of 9 Window quilt curtains - - RF sensor in the mailbox across the steet - - WX200 weather station from Radio Shack - - Relays controling garage door and furnace heat and fan - - Digital input sensors on doors and garage door - - A few iButtons for testing - - X10 IR commander and CM17 for sending IR signals - - X10 CM11 with X10 consoles in each room for control - - X10 motion sensors, light, and appliance modules - - Matrix-orbital LCD keypad for local output and control - - WAP cell phone for remote queries and control - - A ham radio TNC for tracking 2 GPS APRS equipped cars - - NetGear router with mh monitored SYSLOG data for tracking internet traffic - - MSVoice VR via a Andrea Desktop Array microphone - -=head1 7.0: Setup Questions - -=head2 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/ - - -=head2 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. - - -=head2 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. - - - -=cut - - -# -# $Log: faq.pod,v $ -# Revision 1.48 2006/01/29 20:30:14 winter -# *** empty log message *** -# -# Revision 1.47 2005/05/22 18:12:57 winter -# *** empty log message *** -# -# Revision 1.46 2004/11/22 22:57:20 winter -# *** empty log message *** -# -# Revision 1.45 2004/07/18 22:16:33 winter -# *** empty log message *** -# -# Revision 1.44 2004/02/01 19:24:20 winter -# - 2.87 release -# -# Revision 1.43 2003/12/01 03:09:52 winter -# - 2.85 release -# -# Revision 1.42 2003/09/02 02:48:46 winter -# - 2.83 release -# -# Revision 1.41 2003/07/06 17:55:10 winter -# - 2.82 release -# -# Revision 1.40 2003/04/20 21:39:36 winter -# - 2.80 release -# -# Revision 1.39 2003/03/09 19:34:38 winter -# - 2.79 release -# -# Revision 1.38 2003/02/08 05:29:19 winter -# - 2.78 release -# -# Revision 1.37 2003/01/12 20:39:14 winter -# - 2.76 release -# -# Revision 1.36 2002/12/24 03:05:06 winter -# - 2.75 release -# -# Revision 1.35 2002/11/10 01:59:56 winter -# - 2.73 release -# -# Revision 1.34 2002/10/13 02:07:58 winter -# - 2.72 release -# -# Revision 1.33 2002/09/22 01:33:22 winter -# - 2.71 release -# -# Revision 1.32 2002/08/22 04:33:20 winter -# - 2.70 release -# -# Revision 1.31 2002/07/01 22:25:28 winter -# - 2.69 release -# -# Revision 1.30 2002/05/28 13:07:49 winter -# - 2.68 release -# -# Revision 1.29 2002/03/02 02:36:50 winter -# - 2.65 release -# -# Revision 1.28 2002/01/19 21:11:11 winter -# - 2.63 release -# -# Revision 1.27 2001/11/18 22:51:43 winter -# - 2.61 release -# -# Revision 1.26 2001/10/21 01:22:32 winter -# - 2.60 release -# -# Revision 1.25 2001/05/28 21:14:38 winter -# - 2.52 release -# -# Revision 1.24 2001/05/06 21:07:25 winter -# - 2.51 release -# -# Revision 1.23 2001/04/15 16:17:20 winter -# - 2.49 release -# -# Revision 1.22 2001/02/24 23:26:39 winter -# - 2.45 release -# -# Revision 1.21 2001/02/04 20:31:31 winter -# - 2.43 release -# -# Revision 1.20 2001/01/20 17:47:50 winter -# - 2.41 release -# -# Revision 1.19 2000/12/03 19:38:54 winter -# - 2.36 release -# -# Revision 1.18 2000/10/22 16:48:29 winter -# - 2.32 release -# -# Revision 1.17 2000/10/09 02:31:13 winter -# - 2.30 update -# -# Revision 1.16 2000/08/19 01:22:35 winter -# - 2.27 release -# -# Revision 1.15 2000/06/24 22:10:54 winter -# - 2.22 release. Changes to read_table, tk_*, tie_* functions, and hook_ code -# -# Revision 1.14 2000/05/27 16:40:09 winter -# - 2.20 release -# -# Revision 1.13 2000/05/06 16:41:43 winter -# - 2.15 release -# -# Revision 1.12 2000/04/09 18:03:19 winter -# - 2.13 release -# -# Revision 1.11 2000/03/10 04:09:01 winter -# - Add Ibutton support and more web changes -# -# Revision 1.10 2000/02/20 04:47:54 winter -# -2.01 release -# -# Revision 1.9 2000/02/12 06:11:36 winter -# - commit lots of changes, in preperation for mh release 2.0 -# -# Revision 1.8 2000/01/27 13:36:11 winter -# - update version number -# -# Revision 1.7 2000/01/13 13:36:34 winter -# - add useful links -# -# Revision 1.6 2000/01/02 23:38:23 winter -# - renumbered. Added 1.13 -# -# Revision 1.5 1999/12/12 23:51:34 winter -# - added 'too compiliated', 'simple perl', 'commands via email' -# -# Revision 1.4 1999/11/21 02:54:11 winter -# - add 'debug a problem', and 'stop telling time'. -# -# Revision 1.3 1999/11/08 02:11:28 winter -# - add all lights, and save on exit questions -# -# Revision 1.2 1999/09/27 03:09:39 winter -# - add pointer to DCOM 1.3 update -# -# Revision 1.1 1999/09/12 16:08:42 winter -# - Created -# -# +=pod + +=head1 1: MisterHouse operational questions + +=head2 1.1: What OSes can it run on? + +It has been tested on Windows 95, 98, NT 4.0, 2K, XP, Vista (!) and 7. +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. + +=head2 1.2: How can I make it run faster and use less memory? + +On my Celron 400 Mhz computer running Windows 98, using 60 code files with 6000 lines of code, mh takes 10% the cpu, running at 9 passes per second and using about 30 MB of 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) + + + +=head2 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). + +=head2 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. + +=head2 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 + + +=head2 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 ;-) + + +=head2 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 + + +=head2 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. + + + +=head2 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. + + + +=head2 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" + + +=head2 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. + +=head2 1.13: What are the advantages/disadvantages to running the compiled versions of mh? + +Advantages: + +=over + +=item * + +You don't need the latest version of perl installed + +=item * + +You don't have to install additional perl modules + +=back + +Disadvantages: + +=over + +=item * + +For some reason, starting mh with the compiled versions is slower. On my windows box, it is 10 seconds -vs- 20 seconds. + +=item * + +You can apply quick patches to mh, -vs- downloading a larger, less frequently updated mh.exe file. + +=back + +The memory and cpu used, once mh is started, is the same. + + +=head2 1.14: 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. + + +=head2 1.15 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. + +=head2 1.16 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. + +=head2 1.17: How can I use Family Radios with MisterHouse? + +=begin html +There is seperate FAQ on the FRS topic in +mh/docs/faq_frs.html + +=end html + + +=head2 1.18: 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'; + } + + +=head2 1.19: How can I use an Internet Appliance with MisterHouse? + +=begin html +There is seperate FAQ on varous Internet Appliances in +mh/docs/faq_ia.html + +=end html + + +=head2 1.20: 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. + + + + +=head1 2: MisterHouse coding questions + +=head2 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. + +=head2 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'; + + +=head2 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. + + +=head2 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. + + +=head2 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 = ) { + $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") + } + + +=head2 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;"; + } + +=head2 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. + +=head2 2.8: Can I use mh to control other windows + +On Windows (95,98, NT), 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. + + + +=head2 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. + + +=head2 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; + + +=head2 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. + + +=head2 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". + + +=head2 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. + + +=head2 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. + + +=head2 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. + + +=head2 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'. + + +=head2 2.17: Common Perl and mh coding errors + +=begin html +Clive Freedman sent in some useful tips on common coding errors in +mh/docs/faq_damnblast.html + +=end html + +=head2 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' + +=head1 3: Linux specific questions + +=head2 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. + + +=head2 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 + + +=head2 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 + +=head2 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 + + + +=head2 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. + + +=head2 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) + + + +=head1 4: Windows specific questions + +=head2 4.1: mh seems to cause some windows to hang + +If you are experiencing problems with windows not popping up when they should (e.g. control panel or install shield), you will want to install DCOM 1.3, available from here: + + http://www.microsoft.com/com/dcom/dcom98/dcom1_3.asp + +Note, I had run all the 'Windows updates', including the Service Pack 2, but +I still had the problem until I installed the above. + +For Windows 95, the update is at: + + http://www.microsoft.com/com/dcom/dcom95/dcom1_3.asp + + +=head2 4.2: 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. + +=head2 4.3 How do I run MH when not logged in to Win2K or XP? + +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. + + +=head1 5: Perl questions + +=head2 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. + + +=head2 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 " + +=head2 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 + + +=head1 6: Misc questions + +=head2 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, + + +=head2 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 + +=head2 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. + + +=head2 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/ + + +=head2 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. + + +=head2 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 + + +=head2 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 + + +=head1 7.0: Setup Questions + +=head2 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/ + + +=head2 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. + + +=head2 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. + + + +=cut + + +