Items Light_Item

Light_Item

See original

SYNOPSIS

Input states:

      From a Light_Restriction_Item:
         light_ok: Light can be turned on (light will immediately turn on
            if room is occupied AND no other restrictions are active)
         no_light: Light can not be turned on (will not affect current state)
      From a Presence_Monitor:
         occupied: Turns on light if photocell object(s) say it is dark
            and there are no active restrictions.
         vacant: Light will turn off after the delay set by delay_off() unless
            the Presence_Monitor has a delay that was set by delay_off() in
            which case that delay is used.
         predict: If prediction is enabled (with predict(1)), then the light
            will turn on if photocell object(s) say it is dark and there are
            no active restrictions.  Light will turn off after delay set by
            predict_off_time() or the default of 60 seconds unless something
            else (presence, motion, etc) causes light to remain on.
      From a Motion_Item or a Door_Item:
         on: Turns on light if photocell object(s) say it is dark
            and there are no active restrictions.  Light will turn off after
            delay set by predict_off_time() or the default of 60 seconds
            unless something else (presence, motion, etc) causes light to
            remain on.  EXCEPTION: Light will not turn off if there is an
            attached Presence_Monitor that indicates somebody is present.
      From a Photocell_Item:
         dark: Indicates that it is dark in the room, which could allow the
            light to be turned on.  No immediate action will be taken unless
            there are no Motion_Items, Door_Items, AND Presence_Monitors
            attached to the light, in which case the light will imediately
            turn on if there are no active restrictions (Light_Restriction_Item)
      From internal timer object:
         When this internal timer object triggers, if the light is supposed to
         be off, then it will be re-set to off to make sure it really is off.

Output states:

      'off': Light is off
      'on': Light is on (note: if set_on_state() was called then this will
         instead be whatever state specified in that function call)

DESCRIPTION

An abstract object that represents a light that can be automatically controlled by Door_Items, Motion_Items, Presence_Monitors, Photocell_Items, Light_Restriction_Items, and Light_Switch_Items.

Often times, Door_Items and Motion_Items are also used by the Occupancy Monitor which in turn manages the state of the Presence_Monitor objects.

INHERITS

Base_Item

INI PARAMETERS

None

Items.mht

Defined in items.mht as

# define your actual light object:
X10I,      H2,     x10_hallway_lights
#  define the Light_Item and attach the real object:
LIGHT, x10_hallway_lights, hallway_light

Finally, in your user code, you need to add one or more objects that will determine how the light is controlled. You can attach objects of type: Door_Item, Motion_Item, Photocell_Item, Presence_Item, and Light_Restriction_Item. You used the add() function:

  $om_auto_hall_bath_light->add($om_motion_hall_bath,
  $om_presence_hall_bath, $only_when_home);

METHODS

Method	Description
delay_off()	How long the light should remain on after the last event (i.e. door, motion, occupancy) occurs. The light will not turn off as long as occupancy remains true. If this is set to 0, the light will never turn off based on a timer (but could still turn off because of a Photocell_Item/Light_Restriction_Item or if door_auto_off() is enabled.
x10_sync()	Pass in a 1 to enable x10 sync, 0 to disable. Currently this will make sure lights that are supposed to be off really are off around once per hour. The default is enabled.
set_on_state()	Pass in another state besides the default of ON to use when turning "on" the light. Set to empty ('') to prevent this light from turning on automatically (but it will still turn off automatically).
set_predict_off_time()	You can override the default 60-second off time when a light is predictively turned on but nobody actually enters the room.
door_auto_off(X)	Turn off this light X seconds after all attached doors are closed UNLESS an attached occupancy monitor has a state of 'occupied'. In that case, when the room is no longer occupied and if all doors are closed the light will immediately turn off. Set this to 0 to disable (default) or a number of seconds to wait to establish occupancy before the light is turned off.
door_always_on()	This light should always be on whenever an attached door is open, assuming any attached photocell items say it is dark in the room and unless a light restriction item says otherwise.
delay_on()	The room must be continuously occupied for the specified number of seconds before the light will come on. Note that you do NOT want to attach door objects and motion objects to the object if using this feature -- just attach the presence object(s) and any light restriction objects (and possibly a Light_Switch_Object).
manual(X,time_on,time_off)	Set X to 1 to set the light into a full manual mode where it will never be turned on or off automatically unless optional time_on or time_off are set. Set X to the physical light to ensure that the light_item tracks the state of the physical light while in manual mode. Assign time_on and optionally time_off to time in secs for manual mode to be set until resuming to automatic mode. time_off is assigned to time_on if uninitialized.
always_set_state(X)	set X to 0 to only set state when the state changes value. The default is 1 and allows any number of sets with the same value.
restrict_off(X)	set X to 0 to prevent any attached light restriction items from preventing off states. The default is "0".
save_state(X)	set X to 1 to force Light_Item states to be saved and restored across a restart. The default is "0".

AUTHOR

Jason Sharpee - jason@sharpee.com

Kirk Bauer - kirk@kaybee.org

Special Thanks to: Bruce Winter - MH

SEE ALSO

None