Skip to content
ggodart edited this page Jan 2, 2021 · 2 revisions

Insteon

See original

DESCRIPTION

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

INHERITS

INI PARAMETERS

insteon_menu_states

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

VOICE COMMANDS

PLM

Command Meaning
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.
Delete Link with PLM This does nothing and should be removed.
Scan Link Table This will scan and output to the log only the PLM link table.
Log Links This will output only the PLM link table to log.
Delete Orphan Links 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.
AUDIT Delete Orphan Links 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.
Scan All Device Link Tables 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.
Scan Changed Device Link Tables Scans the link tables of the PLM and all devices whose link tables have changed on your network.
Sync All Links Similar to Delete Orphan Links except 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.
AUDIT Sync All Links Same as Sync All Links but prints what it would do to the log, without doing anything else.
print all message stats 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

Command Meaning
on Turns the device on.
off Turns the device off.
Sync Links 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
Link to Interface Will create the controller/responder links between the device and the PLM.
Unlink with Interface 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.
Scan Link Table 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.
Print Message Stats Prints message statistics for this device to the print log.
In - The number of incoming messages received
Corrupt - The number of incoming corrupt messages received
%Corrpt - Of the incoming messages received, the percentage that were corrupt
Dupe - The number of duplicate messages that have been received from this device.
%Dupe - The percentage of duplilicate incoming messages received.
Hops_Left - The average hops left in the messages received from this device.
Max_Hops - The average maximum hops in the messages received from this device.
Act_Hops - Max_Hops - Hops_Left, this is the average number of hops that have been required for a message sent from the device to reach MisterHouse.
Out - The number of unique outgoing messages, without retries, sent.
Fail - The number times that all retries were exhausted without a successful delivery of a message.
%Fail - Of the outgoing messages sent, the percentage that failed.
Retry - The number of retry attempts that have been made to deliver a message. Ideally this is 0, but Sends/Msg is a better indication of this parameter.
AvgSend - The average number of send attempts that must be made in order to successfully deliver a message. Ideally this would be 1.0.
NOTE: If the number of retries exceeds the value set in the configuration file for Insteon_retry_count, MisterHouse will abandon sending the message. As a result, as this number approaches Insteon_retry_count it becomes a less accurate representation of the number of retries needed to reach a device.<br/>Avg_Hops - The average number of hops that have been used by MisterHouse when sending messages to this device.<br/>Hop_Count - The current hop count being used by MH. This count is dynamically controlled by MH and is not reset by calling reset_message_stats`
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.
(AUDIT) Sync Links 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

Method Description
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.
sync_all_links() 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:
Hop Count, Engine Version, ALDB Type, ALDB Health. ALDB Scan Time
print_all_message_stats 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:
Unk_Error - The number of messages which have arrived at the PLM which cannot be associated with any know device.
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

AUTHOR

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

InsteonManager

DESCRIPTION

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

INHERITS

Class::Singleton

INI PARAMETERS

# debug=insteon or debug=insteon:level 
debug=insteon

For debugging where level is 1-4.

METHODS

Method Description
_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.

AUTHOR

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

SEE ALSO

None

Clone this wiki locally