Insteon.pm

Insteon

DESCRIPTION

Provides the basic infrastructure for the Insteon stack, contains many of the startup routines.

INHERITS

None

VOICE COMMANDS

PLM

Complete Linking as Responder

If a device is first placed into linking mode, calling this command will cause the PLM to complete the link, thus making the PLM the responder. The Link To Interface device voice command is likely an easier way to do this, but this may be need for hard to reach devices or deaf devices.

Initiate Linking as Controller

Call this first, then press and hold the set button on a device that you wish to have the PLM control. The Link To Interface device voice command is likely an easier way to do this, but this may be need for hard to reach devices or deaf devices. This is also needed for i2cs devices in which the first link must currently be manually created this way.

Cancel Linking

Cancel either of the above two commands without completing a link.

This does nothing and shoudl be removed.

This will scan and output to the log only the PLM link table.

This will output only the PLM link table to log.

Misterhouse will review the state of all of the links in your system, as it knows them without any additional scanning. If any of these links are not defined in your mht file or the links are only half links (controller with no responder or vice versa) MisterHouse will delete these links.

It is usually best to:

1. Run Scan Changed Device Link Tables first unless you know that the information in MisterHouse is up-to-date.

2. Run AUDIT Sync All Links and verify that what is being added is correct.

3. Run Sync All Links to add the links

4. Run AUDIT Delete Orphan Links first to see what will happen.

5. If everything looks right, run Delete Orphan Links to clean up the old links

Deleting the orphan links will make your devices happier. If you have unintended links on your devices, they can run slower and may unnecessarily increase the number of messages sent on your network.

Note: This command will not run on deaf devices such as motion sensors or remotelincs. These devices need to be "awake" to receive commands. So please run this same command on deaf devices directly.

Does the same thing as Delete Orphan Links but doesn't actually delete anything instead it just prints what it would have done to the log.

Scans the link tables of the PLM and all devices on your network. On a large network this can take sometime. You can generally run Scan Changed Device Link Tables which is much faster without any issue.

Scans the link tables of the PLM and all devices whose link tables have changed on your network.

Similar to Delete Orphan Links exccept this adds any links that are missing. This is helpful when adding a bunch of new devices, new scenes, or cleaning things up.

See the workflow described in Delete Orphan Links.

Note: This command will not run on deaf devices such as motion sensors or remotelincs. These devices need to be "awake" to receive commands. So please run this same command on deaf devices directly.

Same as Sync All Links but prints what it would do to the log, without doing anything else.

Prints the message stats for all devices plus a summary of the entire network stats. For full details on what is contained in this printout please see the description for the print message stats voice command under the device heading below.

reset all message stats

Resets all the message stats for all devices including the Unk_Error stat.

stress test All devices

Performs a 5 count stress test on all devices on the network. See the description of what a stress test is under the device voice commands.

ping test All devices

Performs a 5 count ping test on all devices on the network. See the description of what a ping test is under the device voice commands.

Log All Device ALDB Status

Logs some details about each device to the log. See log_all_ADLB_status()

Enable Monitor Mode

Places the PLM into "Monitor Mode." The documentation is a little unclear on what this does. In practice, this enables the PLM to receive Broadcast messages from devices which are in the PLM's link database. So far, I have encountered two important broadcast messages, 1) EZFlora (EZRain) can send out broadcast messages whenever a valve changes state, 2) Each device will send out a broadcast message whenever you hold down the set button for 10 seconds. Within MisterHouse this message is used to mark a deaf device as awake for 4 minutes. If Monitor Mode is not enabled, MisterHouse will not see either of these messages.

Please be warned, since the documentation is rather vague on what this setting does, please consider this setting a Beta feature. Other users with other setups or devices may discover problems with this setting, but at least for me I do not see a downside to enabling this feature.

Disable Monitor Mode

Disables Monitor Mode defined above.

Devices

on

Turns the device on.

off

Turns the device off.

Similar to Sync All Links above, but this will only add links that are related to this device. Useful when adding a new device.

On deaf devices, this command will perform its tasks the next time the device is awake. You can awaken a device temporarily by triggering it (walk in front of a motion sensor, press a button on a remotelinc). Or you can place the device in awake mode for a longer period of time. See Mark as Manually Awake

Will create the controller/responder links between the device and the PLM.

Will delete the controller/responder links between the device and the PLM. Useful if you are removing a device from your network.

Status

Requests the status of the device.

Get Engine Version

Requests the engine version of the device. Generally you would not need to call this, but every now and then it is needed when a new device is installed.

This will scan and output to the log only the link table of this device.

Log Links

Will output to the log only the link table of this device.

Initiate Linking as Controller

Generally only available for PLM Scenes. This places the PLM in linking mode and adds any device which the set button is pressed for 4 seconds as a responder to this scene. Generally not needed.

Cancel Linking

Cancels the above linking session without creating a link.

Run Stress Test

Simulates a read of a 5 link addresses from the device. This routine is meant to be used as a diagnostic tool.

This is also similar to the ping test, however, rather than simply requesting an ACK, this requests a full set of data equivalent to a link entry. Similar to ping this should be used with print_message_log to diagnose issues and try different settings.

Run Ping Test

Sends 5 ping messages to the device. A ping message is a basic message that simply asks the device to respond with an ACKnowledgement. For i1 devices this will send a standard length command, for i2 and i2cs devices this will send an extended ping command. In both cases, the device responds back with a standard length ACKnowledgement only.

Much like the ping command in IP networks, this command is useful for testing the connectivity of a device on your network. You likely want to use this in conjunction with the print_message_log routine. For example, you can use this to compare the message stats for a device when changing settings in MisterHouse.

Prints message statistics for this device to the print log.

Reset Message Stats

Resets the message stats back to 0 for this device.

Mark as Manually Awake

Flags the device as being awake for 4 minutes. Only applicable to deaf devices such as motion sensors and remotelincs. You must first press and hold the set button for 10 seconds on the device to put it into awake mode. Then tell MisterHouse that you have done this by using this command. Alternatively, if you enable Monitor Mode on the PLM, MisterHouse will see when you press the set button of a device for ten seconds, and automatically mark it as awake for you.

Only available on deaf devices such as motion sensors and remotelincs. Similar to AUDIT Sync All Links above in the PLM, but this will only report links that would be added to this device should you run Sync Links.

(AUDIT) Delete Orphan Links

Only available on deaf devices such as motion sensors and remotelincs. Similar to AUDIT Delete Orphan Links above in the PLM, but this will only report links that would be deleted from this device should you run Delete Orphan Links.

Delete Orphan Links

Only available on deaf devices such as motion sensors and remotelincs. Similar to Delete Orphan Links above in the PLM, but this will only delete links from this device that are unnecessary or no longer used.

On deaf devices, this command will perform its tasks the next time the device is awake. You can awaken a device temporarily by triggering it (walk in front of a motion sensor, press a button on a remotelinc). Or you can place the device in awake mode for a longer period of time. See Mark as Manually Awake

METHODS

stress_test_all(count, [is_one_pass])

Sequentially goes through every Insteon device and performs a stress_test on it. See Insteon::BaseDevice::stress_test for a more detailed description of stress_test.

Parameters: Count: defines the number of stress_tests to perform on each device. is_one_pass: if true, all stress_tests will be performed on a device before proceeding to the next device. if false, the routine loops through all devices performing one stress_test on each device before moving on to the next device.

scan_all_linktables()

Walks through every Insteon device calling the device's scan links command. Does not output anything but will recreate the device's aldb from the actual entries in the device.

_get_next_linkscan_failure()

Called if a the scanning of a device fails. Logs the failure and proceeds to the next device.

_get_next_linkscan()

Gets the next device to scan.

Initiates a process that will walk through every device that is a Insteon::InterfaceController calling the device's sync_links() command. sync_all_links() loads up the module global variable @_sync_devices then kicks off the recursive call backs by calling _get_next_linksync.

Paramter audit_mode - Causes sync to walk through but not actually send any commands to the devices. Useful with the insteon:3 debug setting for troubleshooting.

_get_next_linksync()

Calls the sync_links() function for each device in the module global variable @_sync_devices. This function will be called recursively since the callback passed to sync_links() is this function again. Will also ask sync_links() to call _get_next_linksync_failure() if sync_links() fails.

_get_next_linksync()

Called by the failure callback in a device's sync_links() function. Will add the failed device to the module global variable @_sync_device_failures.

ping_all([count)

Walks through every Insteon device and pings it as many times as defined by count. See Insteon::BaseDevice::ping for a more detailed description of ping.

log_all_ADLB_status()

Walks through every Insteon device and logs:

Walks through every Insteon device and prints statistical information about its message handling, as well as a summary average of the entire network. See Insteon::BaseDevice::print_message_stats for more detailed information.

This command adds the following extra data points:

reset_all_message_stats

Walks through every Insteon device and resets the statistical information about its message handling.

init()

Initiates the insteon stack, mostly just sets the trigger.

generate_voice_commands()

Generates and sets the voice commands for all Insteon devices.

Note: At some point, this function will be pushed out to the specific classes so that each class can have its own unique set of voice commands.

add(object)

Adds object to the list of insteon objects that are managed by the stack. Makes the object eligible for linking, scanning, and global functions.

find_members(name)

Called as a non-object routine. Returns the object named name.

get_object(p_id[, p_group])

Returns the object identified by p_id and p_group. Where p_id is the 6 digit hexadecimal address of the object without periods and group is a two digit representation of the group number of the device.

Insteon Scenes are identified by p_id=='000000', p_group==scene_id

Returns undef if there is no matching object

active_interface(p_interface)

Sets p_interface as the new active interface. Should likely only be called on startup or reload.

check_all_aldb_versions()

Walks through every Insteon device and checks the aldb object version for I1 vs. I2

INI PARAMETERS

insteon_menu_states

A comma seperated list of states that will be added as voice commands to dimmable devices.

AUTHOR

Gregg Limming, Kevin Robert Keegan, Micheal Stovenour, many others

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.

InsteonManager

DESCRIPTION

Provides the basic infrastructure for the Insteon stack, contains many of the startup routines.

INHERITS

Class::Singleton

METHODS

_new_instance()

Defines a new instance of the class.

_active_interface()

Sets and returns the active interface. Likely should only be caled on startup or reload. It also sets all of the hooks for the Insteon stack.

add()

Adds a list of objects to be tracked.

add()

Adds an object to be tracked.

remove_all_items()

Removes all of the Insteon objects.

add_item_if_not_present()

Adds an item to be tracked if it is not already in the list.

remove_item()

Removes the Insteon object.

is_member()

Returns true if object is in the list.

find_members(p_type)

Find and return all tracked objects of type p_type where p_type is an object class.

INI PARAMETERS

debug

For debugging debug=insteon or debug=insteon:level where level is 1-4.

AUTHOR

Bruce Winter, Gregg Liming, Kevin Robert Keegan, Michael Stovenour, many others

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.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 145:

'=item' outside of any '=over'

Around line 164:

'=item' outside of any '=over'

Around line 258:

Unknown directive: =over8

Around line 260:

'=item' outside of any '=over'

Around line 715:

Unknown directive: =over8

Around line 717:

'=item' outside of any '=over'

Around line 798:

Unknown directive: =over8

Around line 800:

'=item' outside of any '=over'

 Insteon.pm