Generic_Item.pm

Generic_Item

SYNOPSIS

     $tv_grid = new Generic_Item;
     set $tv_grid 'channel 2 from 7:00 to 8:00 on 1/24 for This Old House';
     speak "tv set to $state" if $state = state_now $tv_grid;
  
     $wakeup_time = new Generic_Item;
     speak "Your wakeup time is set for $state" 
       if $state = state_now $wakeup_time;
     speak "Time to wake up" if time_now state $wakeup_time;
  
   # Since Voice_Cmd objects inherit Generic_Items methods, we can
   # use tie_items and tie_event like this:
  
     $indoor_fountain    = new X10_Appliance('OB');
     $v_indoor_fountain  = new Voice_Cmd 'Indoor fountain [on,off]';
     $v_indoor_fountain -> tie_items($indoor_fountain);
     $v_indoor_fountain -> tie_event('speak "Ok, fountain was turned $state"');
  
     if ($state = state_now $test_button) {
        my $ref = get_set_by $test_button;
        print_log "Test button's was set to $state by $ref->{object_name}" 
          if $ref;
     }
  
                           # This shows how to set states
    $TV  = new IR_Item 'TV';
    my  $tv_states = 'power,on,off,mute,vol+,vol-,ch+,ch-';
                           # causes $tv_states to be split into array
                           # values deliminated by ,
    set_states  $TV split ',', $tv_states;
    $v_tv_control = new  Voice_Cmd("tv [$tv_states]");
  
                           # This shows how to save persistant arbitrary data
    $Test = new Generic_Item;
    $Test->{junk_data1} = $Time_Now if $Reload;
    $Test->{junk_data2} = $Month    if $Reload;
    $Test->restore_data('junk_data1', 'junk_data2');
  
                           # Here are some tie* examples
    $fountain -> tie_filter('state $windy eq ON', ON,
                            'Overriding item1 ON command because of wind');
  
    $fountain -> tie_time('10PM', OFF, 'Fountain turned off');
  
                           # Disable an item when we are away
    $item1 -> tie_filter('state $status_away eq ON');
    $item1 -> tie_event('print_log "item1 toggled to $state"');
  
                           # Ignore RF sourced (e.g. W800 or MR26) X10 data
    $light1 -> tie_filter('$set_by eq "rf"', , 'Ignoring x10 rf data');
  
                           # Disable callerid announcements when we are not
                           # at home
    $cid_announce -> tie_filter('state $mode_occupied ne "home"');
    
                           # Set an item to multiple states, with a 5 second
                           # delay between states
    $test_set1  = new Generic_Item;
    $test_set1 -> set('0%~5~30%~5~60%~5~100%') if new_second 20;
    $test_set1 -> tie_event('print_log "test set $state"');
  
    print 'Item is idle' if $test_set1 -> time_idle('4 seconds');

See mh/code/examples/generic_item.pl for more examples, test_tie.pl for more examples on how to tie/untie items/events, and test_idle.pl for more examples on testing idle times.

DESCRIPTION

This is the parent object for all state-based mh objects, and can be used by itself.

You can use this object to store and query arbitrary data. This is more useful than 'my' variables, if you need to share data between code files, since 'my' variables are local to a code file. States of these items are also saved/restored when mh is stopped/started.

INHERITS

This item inherits nothing, but all other mh items that have states (e.g. X10_Item, Serial_Item, iButton, Voice_Cmd, Group) inherit all Generic_Item methods.

METHODS

new()

Instantiation method.

property_changed(property, new_value, old_value)

This method is called internally whenever a property (instance variable) is changed. It only logs the property, new_value, and old_value, but can be overridden to do more (see X10_Item).

set(state, set_by, respond)

Places the value into the state field (e.g. set $light on) at the start of the next mh pass.

(optional) set_by overrides the defeult set_by value.

(optional) respond overrides the defeult respond value.

set_now(state, set_by, respond)

Like set, except states are set when called, not on the next pass.

set_with_timer(state, time, return_state, additional_return_states)

Like set, but will return to return_state after time.

If return_state is not specified and state is 'off', it sets state to 'on' after time. If return_state is not specified and state is missing or something other than 'off', it sets state to 'on' after time. If return_state is 'previous', it returns to the previous state after time.

(optional) additional_return_states lets you specify one or more extra states to set after time (separate states with ';'). If set is called before the timer expires, the timer will be unset, and return_state not set..

You can also stack a series of set_with_timer calls with one set call like this:

    set('s1~t1~s2~t2...sn');

where s1, s2, ... sn are various states, and t1, t2 ... tn are the times to wait between states. See example below.

If you want to stack a set of states without delays, you use ; like this:

    set('on~2~random:on;repeat:on;play');

See mh/code/examples/test_states_stacked.pl for a complete example. Note, this is turnded off by default for Serial_Item objects.

To enable, run:

    $object -> state_overload(ON);
get_object_name()

Returns the object name.

set_by(set_by)

Allows setting a description of what caused the last state change. For example, motion, sunrise, manual, serial, etc. Any string is allowed. Value is returned by get_set_by below.

get_set_by()

Returns what caused this object to change. Standard values are web, tk, telnet, vr, xcmd, serial, xap, and xpl.

An example is in mh/code/examples/test_set_by.pl

set_target(target)

Sets the target instance variable to target.

get_target()

Returns the current target.

get_idle_time()

Returns number of seconds since the last state change.

time_idle(time)

Returns true when the object has had no state changes since the specified time. time can be be in seconds, minutes, hours, or days (e.g. '90 s' or '7 days'). Defaults to seconds. Only the first of the unit word is checked and it is case-insensitive.

(optional) time can also specify a spefic state (e.g. '4 m on')

restore_string()

This is called by mh on exit to save persistant data.

restore_data(vars)

Specifies which variables should be saved/restored between mh reload/restarts. The state var is always saved. Can only be run at startup or reload.

hidden(1/0)

If set to 1, the object will not show up on Tk or Web menus. Can only be run at startup or reload.

set_casesensitive()

By default, states are all lowercased, to allow for case insensitive tests. To avoid this (for example on Serial Interfaces that are case sensitive), call this method. Can only be run at startup or reload.

state()

Returns the state (e.g. on, off).

state_now()

Returns the current state only for one pass after object state is set. Unlike state_changed, will return the state even if the new state matches the previous one. Otherwise, returns null.

state_changed()

Returns the current state only for one pass after object state is set. Unlike state_now, will only return the state if the new state differs from the previous one. Otherwise, returns null.

state_final()

Returns the state the object will be in after all queued state changes have been processed, if there is at least one state pending. Otherwise, returns null.

respond()

This method sends a message back by whatever method was used to set this object. For example, if you use voice recognition to set an object than the message will be emailed back to you.

This method is almost always used by Voice_Cmd items, which inherit it. (maybe it should be moved there?)

No need to pass target parameter(s) to this method! (Targeting is automatic.) These are the targets derived from these set_by values:

    set_by    target
  
    default   none
    email     email
    im        im
    telnet    telnet
    time      none
    usercode  none
    voice     speak
    web       speak
    xap       xap
    xpl       xpl 

These are the parameters you can specify in the argument string:

    connected
    target       - override the target derived from set_by 
    important
    to
    pgm
    mode
    app
    no_chime
    force_chime
    text 
said()

Same as state_now().

state_log()

Returns the current state log.

state_overload()

TODO

set_icon(icon)

Point to the icon member you want the web interface to use. See the 'Customizing the web interface' section of the documentation for specific details. In short, this can be set to a file name such as 'light.gif' or to a prefix such as 'light.' If a prefix is used, MH will attempt to find icons that match a combination of the prefix and the device's state. Can only be run at startup or reload.

set_info(info)

Adds additional information. This will show up as a popup window on the web interface, when the mouse hovers over the command text. Can only be run at startup or reload.

incr_count()

TODO

reset_count()

TODO

set_count()

TODO

get_count()

TODO

set_label(label)

Specify a text label, useful for creating touch screen interfaces. Can only be run at startup or reload.

set_authority(who)

Sets authority for this object to who. Setting who to 'anyone' bypasses password control. Can only be run at startup or reload.

get_authority()

TODO

get_type()

Returns the class (or type, in Misterhouse terminology) of this item.

set_fp_location()

TODO

get_fp_location()

TODO

set_fp_nodes()

TODO

get_fp_nodes()

TODO

set_fp_icons(%icons)

Sets the icons used by the floorplan web interface. The %icons hash contains the list of icons stored in the web/graphics directory. Each key is a state of the object with the value being the icon filename. Can only be run at startup or reload.

get_fp_icons()

Returns the hash of icons for use by the floorplan web interface that were set by set_fp_icons.

set_fp_icons_set(name)

Sets the icons group used by the IA7 floorplan web interface. The name contains the group name of icons that can be found in /web/ia7/graphics. Can only be run at startup or reload.

get_fp_icons()

Returns the name of the icon set used by the floorplan IA7 web interface that were set by set_fp_icon_set.

set_states(states)

Sets valid states to states, which is a list or array. Can only be run at startup or reload. TODO

add_states(states)

Adds states to the list of valid states. Can only be run at startup or reload.

get_states()

Returns the list of valid states.

set_states_for_this_pass()

TODO

set_states_for_next_pass()

TODO

set_state_log(state, set_by, target)

When a state is set, it (along with a timestamp and who set it) are logged to the state_log array by this method. The number of log entries kept is set by the max_state_log_entries ini parameter.

reset_states2()

TODO

xAP_enable()

TODO. Can only be run at startup or reload.

xPL_enable()

TODO. Can only be run at startup or reload.

tie_event(code, state, log_msg)

If the state of the generic_item changes, then code will trigger, with the lexical variables $state and $object getting set. The code is a string that will be eval'd and the variables are available to it, but not to any subroutines called by it unless you pass them. You can also set the state variable explicitly since you usually know the item. The code is a string that will be eval'd.

(optional) Setting state limits this tied code to run only when the given state is set.

(optional) Setting log_msg causes the message to be logged when this tied code is run.

untie_event(code, state)

Remove the tie to code. If you don't specify a code string, all tied code is removed.

(optional) Setting state removes the tied code previously associated with that state.

tie_items(item)

If the state of the generic_item changes, then the state of $item will be set to that same state.

untie_items(item, state)

Remove the tie to item. If you don't specify an item, all tied items are removed.

(optional) Setting state removes the tied item and state combination.

tie_filter(filter, state, log_msg)

Use this to disable control of the item whenever filter returns true. Variables $state and $set_by can be used in the filter test.

(optional) Setting state limits this tied filter code to run only when the given state is set.

(optional) Setting log_msg causes the message to be logged when this filter is run.

untie_filter(filter, state)

Remove the tie to filter. If you don't specify a filter, all tied filters are removed.

(optional) Setting state removes the tied filter and state combination.

tie_time(time, state, log_msg)

Sets item to state if the time string evaluates true. state defaults to 'on' if undefined. time can be in either time_cron or time_now format.

(optional) Setting log_msg causes the message to be logged when the time string evaluates true.

untie_time(time, state)

Remove the tie to time. If you don't specify a time, all tied times are removed.

(optional) Setting state removes the tied time and state combination.

set_web_style(style)

Contols the style of we form used when displaying states of this item on a web page. Can be 'dropdown', 'radio', or 'url'. See mh/code/examples/test_web_styles.pl

get_web_style

Returns the web style associated with this item.

user_data

Returns the user data associated with this item.

debuglevel([level], [debug_group])

Returns 1 if debug_group or this device is at least debug level 'level', otherwise returns 0.

sort_order($ref_list_of_member_names)

Used to store an ordered list of object names. The purpose of which is to be used to arrange the list of member objects in a specific order.

NOTE: This routine does not verify that the objects are in fact members of this object.

PACKAGE FUNCTIONS

delete_old_tied_times()

TODO

recently_changed()

TODO

reset_states()

TODO

INI PARAMETERS

Debug: Include set and store in the comma seperated list of debug keywords to produce debugging output from this item.

AUTHOR

Bruce Winter

SEE ALSO

None

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.

 Generic_Item.pm