Skip to content

Insteon Devices Quirks and Hints

Jump to bottom Edit New page
jsiddall edited this page Apr 21, 2021 · 3 revisions
  • NOTES
  • This page has not been editted in quite some time and contains some significantly out of date information. If you are new to Misterhouse and Insteon please stick to the rather detailed Insteon page for the time being. It has been significantly revised to make it more accurate

Table of Contents

Other Insteon Pages

include component="pageList" hideInternal="true" tag="insteon" limit="10"

Getting Help

If you didn't start from there, go read the main Insteon setup page first.

There exist many opportunities for encountering problems as insteon devices are integrated into misterhouse. Make sure that the first action that you take is to set debug=insteon in your mh.ini file; this setting will allow more detailed logging of insteon actions. You should inspect the log file for any information that might provide immediate clues to allow you to resolve the problem without assistance. In addition, be sure to read all of the insteon-related wiki pages before proceeding to ask help through the list. After you have attempted all self-diagnosis actions, then request assistance through the misterhouse list. You must provide the following information as part of your request if you expect others to be able to provide useful responses to your request for help:

  1. current mh release/version; in general, you must be current to the latest svn. Ensure that you have updated to the latest before asking for help.
  2. all pertinent mht declarations; if in doubt include the entire items.mht (or related) file(s)
  3. all pertinent user code files; these *.pl files include any references to insteon items
  4. a copy of the log file that includes portions of the log several minutes (ideally) prior to the perceived problem as well through several seconds following the problem
  5. a description of any manual linking or any other linking operations that you have performed
  6. the output of "log link table" for the PLM as well as all applicable devices

KeypadLinc

Using PLM Scenes with KPLs

KeypadLinc (KPL) buttons cannot themselves be directly controlled. That is you can't do the following*: 

# Insteon.mht
INSTEON_KEYPADLINC, 01.02.03:01, kpl_button_A, All_Lights #

# User Code
kpl_button_A->set(ON);

If you try and do this, MisterHouse will throw an error.

  • If you really want to do this, it can be done using the "surrogate" feature discussed below, which requires a few extra steps of preparation.

However, a KPL button can be added to a scene. If a member of a scene, the KPL button will turn on and off when the scene is controlled. So for example, you can create a scene called "myscene" that when turned on, will turn on both a light and the button light on the KPL. To do that you would put the following entries in your insteon.mht file: 

# Define the KPL Button
INSTEON_KEYPADLINC, 01.02.03:02, kpl_button_A, All_Lights  #

# Define the Light
INSTEON_SWITCHLINC, 04.05.06, light, All_Lights            #

# Define a PLM Scene
INSTEON_ICONTROLLER, 10, myscene, All_Scenes

# Define the KPL Button and the Light to be members of the PLM Scene
SCENE_MEMBER, light, myscene, 80%, 2s
SCENE_MEMBER, kpl_button_A, myscene               # no level or ramp for a button

# Create local links between the light and the KPL.

# Add the light as a member of the KPL Button
SCENE_MEMBER, light, kpl_button_A, 100%, 2s

# Add the KPL button as a member of the light
SCENE_MEMBER, kpl_button_B, light

Now, if you turn myscene on, such as "$myscene->set(ON);" both the light and the KPL button will turn on. You can associate more than one keypadlinc button to a given scene, either from the same or multiple keypadlincs. If the scene includes more than one KeypadLinc button or light, all of the KeypadLinc buttons are properly set via the scene or any KeypadLinc button or local light controller if they are all included in the scene.

You then just have to remember to use 'myscene' instead of 'light' everywhere in your MH code and via the web interface, or else you are just controlling the individual device directly and not the scene. (One way to clean up the web interface is to name the kitchen light something like 'kitchen_device', name the scene what you would normally name the light, such as 'kitchen', and put the 'kitchen_device' in the group 'hidden' so it does not appear in the web interface. Then only the full scene 'kitchen' will appear in the web interface.)

Similarly, if you manually press the KPL button B, the light will turn on. Also, if you manually press the light switch, the KPL button will adjust accordingly.

One problem with this basic scene definition is that if you use the KPL button or activate the light at the controller itself, then the MH scene will not reflect that change due to a limitation in MH. For a solution to that, see the next section.

Tying Local Control of a Light to PLM Scenes

When a light is controlled locally, MH does not update the state of any scenes it may be in because most scenes contain more that just one light and MH does not do the analysis to determine when the simple solution below can be automatically triggered. If you do have a simple scene and want to ensure the MH scene state stays properly in sync with local changes, you can tie your light to a function to update the scene when local control is triggered. Beginning with the simple configuration directly above, the following code in program.pl will do the necessary tie to keep the device and scene in sync for local control.

(Note that this is not the solution you want if you want more fine-grained control of the KPL button state, such as turning on a KPL button when any one of several lights in the scene are locally controlled; for that, see the 'surrogate' support below.) 

# When an 'event' happens to $lamp, call the tied function with the arguments shown; in
# this case, supply the light that changed and the scene that should be sync'd with it.
$light->tie_event('sync_kpl_lights($light, $myscene)'); # noloop

# Repeat the line above for all controllers in scenes.

# Every time a switch is toggled locally, or every time you run
# get_status or on receipt of remote activations, also update the
# scene containing the light to keep them in sync.
sub sync_kpl_lights
{
    my ($ref_light, $kpl_scene) = @_;
    # avoid unnecessary traffic, like a get_status where status hasn't changed.
    if ($ref_light->state_changed) {
        print_log "MYLOGKPL: sync_kpl_lights called for state_changed on ".
            $ref_light->get_object_name." to ".$ref_light->state." for ".
            $kpl_scene->get_object_name." set kpls in 1sec";
        # delay is to avoid collisions. In case we're in this code path
        # due to a remote toggle instead (you pushed the switch), that switch
        # could already be running a scene and you don't want to conflict with it
        # (for local state changes, this is not an issue).
        $kpl_scene->set_with_timer('', 1, $ref_light->state);
    }
}

Now, anytime light's state changes, the PLM scene is also updated.

Controlling KPL Buttons Directly using 'surrogate'

As noted above. You cannot directly control the state of a KPL button; for example, you cannot do $kpl_button_B->set(ON) with a basic definition like above. And controlling the KPL directly using it's address will only control the light wired to it (i.e. on button A).

However, if you really want to do this, MH can create a surrogate scene allowing you to control the KPL button's light. To do this setup the following: 

# Initial Definition of the KPL and its Button
INSTEON_KEYPADLINC, 01.02.03, kpl, All_Lights # the main KPL
INSTEON_KEYPADLINC, 01.02.03:02, kpl_A, All_Buttons # KPL button A; note the :02

# Define the Surrogate PLM Scene
# You likely want to use hidden, to hide this scene in the web interface.
INSTEON_ICONTROLLER, 88, surrogate_button_A, hidden

# Add the KPL Button as a member of the scene
# Use the special surrogate flag to tell MH to use this scene
# to control the light behind the button
SCENE_MEMBER, kpl_A, surrogate_button_a, surrogate

Note the special use of the keyword "surrogate" that replaces the on-level in the SCENE_MEMBER definition. It is important that **only one surrogate** exist and be paired for **each individual keypadlinc button.** Now, you can do things like the following from within MH to directly control the LED: 

$kpl_A->set(ON);
Note that we appear to be directly controlling the button, but in fact it is MH's internal knowledge of a what a surrogate scene is used for that enables this. This method is the only way you're able to directly set a KPL button's state with an MH command.

Adding Multiple KPL Buttons to a Single Surrogate

Note that if you have 4 eight-button KPLs, it may sound like you need to create 28 scenes just to access all the buttons, but in real life you are unlikely to need the ability to control each KPL's buttons separately because they'll all reflect the same state, so you'll typically only need as many surrogate scenes as you have items you are trying to reflect in the state of the KPL buttons.

For example, if you use 4 buttons on each KPL device to indicate the state of 4 things within MH, you only need 4 surrogate scenes (each of which includes all 4 KPLs) and NOT 16 scenes. Each surrogate scene would include a button from each of the KPL devices, and controlling that single surrogate from within MH would affect all 4 KPLs. For example: 

#Define the KPL Buttons
INSTEON_KEYPADLINC, 11.11.11:02, kpl_1_button_A, All_Lights
INSTEON_KEYPADLINC, 22.22.22:02, kpl_2_button_A, All_Lights
INSTEON_KEYPADLINC, 33.33.33:02, kpl_3_button_A, All_Lights
INSTEON_KEYPADLINC, 44.44.44:02, kpl_4_button_A, All_Lights

#Define the Surrogate Scene
INSTEON_ICONTROLLER, plm:A0, surrogate_button_A, hidden, plm

#Add each button as a member of that single scene
SCENE_MEMBER, kpl_1_button_A, surrogate_button_A, surrogate
SCENE_MEMBER, kpl_2_button_A, surrogate_button_A, surrogate
SCENE_MEMBER, kpl_3_button_A, surrogate_button_A, surrogate
SCENE_MEMBER, kpl_4_button_A, surrogate_button_A, surrogate

So, given the scene defined here, calling $surrogate_button_B->set(ON) will turn on button B on all four KPLs. Similarly, calling $kpl_1_button_A->set(ON) will cause the buttons on all 4 devices to turn on.

Creating a Scene with a Light and Multiple KPLs

If you have several KPLs linked to a device, keeping all the LEDs in sync can cause the scene creation to be a bit tedious; you have to list every relationship between every device (it's bigger than n^2, as each additional KPLs linked doubles the number of SCENE_MEMBER links you need). For example, here is a scene with 1 real light, controlled by a KPL (wired to it, so controlled by button A) and 3 auxiliary KPLs with different buttons on each controlling the same 'kitchen' light. Compare the example above with one light and one KPL (which has 1 device+1 KPL = 2^2 = 4 SCENE_MEMBER links) to this one (which has 1 device +3 KPLs = 2^4 = 16 SCENE_MEMBER links). 

# KPL #1's main button
IPLL,    0E.09.12:01,    kitchen_kpl,      All_Lights,          PLM   # button A, note the :01

# KPLs 2-4 secondary buttons we need to keep in sync
IPLL,    0E.07.49:02,    fmr_kpl_B,        fmr_kpl|buttons,     PLM   # button B, note the :02
IPLL,    09.9E.68:02,    dining_kpl_B,     dining_kpl|buttons,  PLM   # button B, note the :02
IPLL,    09.94.25:04,    lvr_kpl_D,        lvr_kpl|buttons,     PLM   # button D, note the :04

# the scene that controls the 'kitchen' light
IPLL,    PLM:52,         kitchen,          All_Lights,          PLM

# so that the scene controls every KPL (including the main device wired to the light)
SCENE_MEMBER, kitchen_kpl,    kitchen,       100%, 0.1s
SCENE_MEMBER, fmr_kpl_B,      kitchen
SCENE_MEMBER, dining_kpl_B,   kitchen
SCENE_MEMBER, lvr_kpl_D,      kitchen

# so that the main KPL device controls each secondary KPL button (multi-way linking)
SCENE_MEMBER, fmr_kpl_B,      kitchen_kpl
SCENE_MEMBER, dining_kpl_B,   kitchen_kpl
SCENE_MEMBER, lvr_kpl_D,      kitchen_kpl

# so that each secondary KPL button controls the main KPL device (multi-way linking)
SCENE_MEMBER, kitchen_kpl,    fmr_kpl_B,     100%, 0.1s
SCENE_MEMBER, kitchen_kpl,    dining_kpl_B,  100%, 0.1s
SCENE_MEMBER, kitchen_kpl,    lvr_kpl_D,     100%, 0.1s

# now we need inter-KPL button ties so that each secondary KPL button controls every
# other secondary KPL button (we already scene linked the main KPL just above)
SCENE_MEMBER, dining_kpl_B,   fmr_kpl_B
SCENE_MEMBER, lvr_kpl_D,      fmr_kpl_B

SCENE_MEMBER, fmr_kpl_B,      dining_kpl_B
SCENE_MEMBER, lvr_kpl_D,      dining_kpl_B

SCENE_MEMBER, fmr_kpl_B,      lvr_kpl_D
SCENE_MEMBER, dining_kpl_B,   lvr_kpl_D

# now just remember to use the 'kitchen' scene from within MH to control everything
# together. you may also want to read the section above on tie'ing local control to
# the MH scene, for which you would need to add 1 tie of the kitchen_kpl device to
# the 'kitchen' scene in your program.pl, as:
#
#   $kitchen_kpl->tie_event('sync_kpl_lights($kitchen_kpl, $kitchen)'); # noloop
#
# (remember to include the sync_kpl_lights() function from above in your program.pl!)

Controlling the Intensity of the Backlighting

The backlighting of a KeypadLinc (KPL) can be adjusted to one of: high, low or off. In addition, it is possible to programmatically set the 8 vs 6 button mode. The syntax for doing this in program.pl is: 

$my_kpl_1->update_flags($flags);

# where $flags should be set to:
#
# '0a' - 8 button; backlighting dim
# '06' - 8 button; backlighting off
# '02' - 8 button; backlighting normal
#
# '08' - 6 button; backlighting dim
# '04' - 6 button; backlighting off
# '00' - 6 button; backlighting normal

Setting Local Properties

A dimmable device has a local onlevel and ramprate that is used if local control occurs or non-linked (scene) control is initiated via the PLM. These may be set manually via the device or via code as shown below. 

$some_light->local_onlevel('50%');
$some_light->local_ramprate(2);

# Now, to change them (i.e., commit to device memory):

$some_light->update_local_properties();

# make sure that these commands are only invoked via some voice command or similar menu capability
# ex: define a voice command item such as Insteon_Local_Properties, for example "Set Insteon local properties"
# then add code such as this to a user code file:
if (said $Insteon_Local_Properties) {
     $some_light->local_onlevel('50%');
     $some_light->update_local_properties();
}

If you are doing this to a dimmable KeypadLinc, then the changes should be immediate. If you are applying the changes to a LampLinc or SwitchLinc, then you'll have to apply a power reset. For a LampLinc, remove from power or throw the circuit breaker for up to 10 seconds. For a SwitchLinc, throw the circuit breaker or "gap" the switch (pull out the reset switch and then barely push back in--being careful not to do a factory reset) for up to 10 seconds. I've not tried on an InlincLinc; presumably, you'd have to throw the breaker.

Blending Local Control and Automation

The fact that you are reading this suggests that you have interest in automating some aspect of your Insteon devices, and that most often includes lighting. But, problems with automation occur when a human expects some form of override over the automation. For example, let's suppose you press a switch that controls a light to make it turn on. What you don't expect is for the light to turn off 5 seconds later due to some automation. So, the first hint involves knowing if the light is locally controlled: 

if ($bathroom_light->state_now)
{
  if (ref $bathroom_light->get_set_by && $bathroom_light->get_set_by eq $bathroom_light)
  {
    # mask automation because the bathroom light was locally controlled
  }
}

Let's walk through this. The check for state_now detects some state update on the light (it may be different or the same). The next checks refer to get_set_by. The first check ensures that it was an object (and not some bit of user code) and the subsequent one determines if the object that set bathroom_light was itself. If you are wondering how fast this detection occurs--the answer is usually less than one second (i.e., virtually instantaneous) as status is not polled but rather intercepted from the light. This is really quite useful as the Insteon code always propagates the controller of some light (responder) via the get_set_by method. If you have more than one way of controlling a light (perhaps more than one controller is linked), then you can perform similar checks against each of the controllers (and, optionally, individual buttons).

Now, suppose that you are using Light_Items--the abstraction of lighting as part of the Occupancy, Motion, Presence (OMP) set of "smart" objects. It is now possible to use the "manual" method to setup timers to determine how long to assume "masked" automation as a result of local control. Let's revisit the above with some slight changes (focusing now on bathroom_light_item vice bathroom_light): 

if ($bathroom_light_item->state_now)
{
  if (ref $bathroom_light_item->get_set_by && $bathroom_light_item->get_set_by eq $bathroom_light)
  {
    $bathroom_light_item->manual($bathroom_light,'1200:auto',15);
  }
}

The manual method is actually doing a lot of sophisticated functioning in one compact statement. The first argument, $bathroom_light, is needed for state tracking so that any continued change to bathroom_light can be reflected in the state of $bathroom_light_item. The next two arguments specify the on and off timers. So, if the light is turned off, then the timer is set to 1200 seconds (20 minutes); otherwise, it is set to 15 seconds. The "auto" qualifier means that the light item will track the automation state the entire time that it is in manual mode and revert to that state on completion of the timer. That is, the light light items keeps track of what the state would have been if it were in full automation mode and then sets the state of the light item on expiration of the timer.

6 Device Models

The only difference between the 6 and 8 button KPLs are the faceplate and a NVRAM bit (both end user changable)

In an 8 button config :01 is local load, and 2-8 are "scene B" through "scene H" with 09 being a virtual button on the newer units.

In 6 button mode 01 is still local load but scene A-D are really just mapped to 03-06 and 02,07, and 08 are disabled, which becomes clear if you know how 8 button mode is layed out. 

   #MHT example for 6 button
   INSTEON_KEYPADLINC,     xx.xx.xx:01,    kpl_light,  All_Lights
   INSTEON_KEYPADLINC,     xx.xx.xx:03,    kpl_a, All_Buttons
   INSTEON_KEYPADLINC,     xx.xx.xx:04,    kpl_b, All_Buttons
   INSTEON_KEYPADLINC,     xx.xx.xx:05,    kpl_c, All_Buttons
   INSTEON_KEYPADLINC,     xx.xx.xx:06,    kpl_d, All_Buttons

Last Steps

In order for the device and MH to know all about the responders and controllers, you must; 

  - Scan the link table on the KPL device
  - On each KPL button select 'Sync Links'
  - If you are using surrogates for web control, you also need to 'Sync Links' on the surrogate items

Main page

Add a custom sidebar
Clone this wiki locally