Items Generic_Item

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.

Items.mht

Defined in `items.mht as

#GENERIC,Item_name,Groups e.g.
GENERIC, log_heating, Variable

METHODS

Method	Description
`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 default set_by value. (optional) respond overrides the default 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 turned 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 specific state (e.g. '4 m on')
`restore_string()`	This is called by MisterHouse on exit to save persistent 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.
`logger()`	TODO
`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.
`logger_enable()`	Will start logging state changes to a historical log file
`logger_disable()`	Will stop logging state changes to a historical log file
`logger_mintime()`	Set the minimum number of seconds to log updates. Useful to 'throttle' noisy objects such as AD2 motion sensors
`get_logger_status()`	Returns 1 if logger is enabled on the object. Otherwise 0.
`get_logger_data(epoch,days back)`	Returns logged data at date, back days number of days Date format is epoch
`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

Function	Description
`delete_old_tied_times()`	TODO
`recently_changed()`	TODO
`reset_states()`	TODO

INI PARAMETERS

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

AUTHOR

Bruce Winter

Provide feedback

Saved searches

Use saved searches to filter your results more quickly