BaseInsteon.pm


Insteon::BaseObject

SYNOPSIS

Usage

In user code:

    $ip_patio_light = new Insteon_Device($myPLM,"33.44.55");
    $ip_patio_light->set("ON");

DESCRIPTION

Generic class implementation of an Insteon Device.

INHERITS

Generic_Item

METHODS

derive_link_state([state])

Takes the various states available to insteon devices and returns a derived state of either ON or OFF.

new()

Instantiates a new object.

initialize()

A former holdover from when MisterHouse used to ping devices to get their device category. May not be needed anymore.

interface([interface])

Used to store and return the associated interface of a device.

If provided, stores interface as the device's interface.

device_id([id])

Used to store and return the associated device_id of a device.

If provided, stores id as the device's id.

Returns device id without any delimiters.

group([group])

Used to store and return the associated group of a device.

If provided, stores group as the device group.

timeout_factor($float)

Changes the amount of time MH will wait to receive a response from a device before resending the message. The value set will be multiplied by the predefined value in MH. $float can be set to any positive decimal number. For example using 1.0 will not change the preset values; 1.1 will increase the time MH waits by 10%; and 0.9 will force MH to wait for only 90% of the predefined time.

This value is NOT saved on reboot, as such likely should be called in a $Reload loop.

max_hops($int)

Sets the maximum number of hops that may be used in a message sent to the device. The default and maximum number is 3. $int is an integer between 0-3.

This value is NOT saved on reboot, as such likely should be called in a $Reload loop.

min_hops($int)

Sets the minimum number of hops that may be used in a message sent to the device. The default and minimum number is 0. $int is an integer between 0-3.

This value is NOT saved on reboot, as such likely should be called in a $Reload loop.

default_hop_count([hops])

Used to track the number of hops needed to reach a device. Will store the past 20 hop counts for the device. Hop counts are added based on the number of hops needed for an incomming message to arrive. Additionally, any time a message is resent, a hop count equal to the prior default_hop_count + 1 is added.

If provided, stores hop as a new hop count for the device. If more than 20 hop counts have been stored, will drop the oldest hop count until only 20 exist.

Returns the highest hop count of the past 20 hop counts

engine_version([i1|i2|i2cs])

Used to store and return the associated engine version of a device.

If provided, stores the engine version of the device.

equals([object])

Returns 1 if object is the same as $self, otherwise returns 0.

set(state[,setby,response])

Used to set the device state. If called by device or a device linked to device, calls set_receive(). If called by something else, will send the command to the device.

is_acknowledged([ack])

If ack is true, calls set_receive(). If ack is false, clears awaiting_ack flag.

set_receive(state[,setby,response])

Updates the device state in MisterHouse. Triggers state_now, state_changed, and state_final variables to update accordingly. Which causes tie_events to occur.

If state was set to the same state within the last 1 second, then this is ignored. This prevents the accidental calling of state_now if duplicate messages are received.

set_with_timer(state, time, return_state, additional_return_states)

NOTE - This routine appears to be nearly identical, if not identical to the Generic_Item::set_with_timer() routine, it is not clear why this routine is needed here.

See full description of this routine in Generic_Item

derive_message([command,extra])

Generates and returns a basic on/off message from a command.

message_type_code(msg)

Takes msg, a text based msg type, and returns the corresponding text version of the hexadecimal message type.

message_type_hex(msg)

Takes msg, a text based msg type, and returns the corresponding message type as a hex.

message_type(cmd)

Takes cmd, text based hexadecimal code, and returns the text based description of the message code.

_is_info_request()

Used to process messages from the device which lack a command code. Currently the only known message like this is a response to a (19) Light Status Request. In these responses, C1 is the ALDB Delta of the device.

The get_engine_version check is out of place here, should be moved to _process_message

get_nack_msg_for(msg)

Takes msg, text based hexadecimal code, and returns the text based description of the NACK code.

failure_reason

Stores the resaon for the most recent message failure [NAK | timeout]. Used to process message callbacks after a message fails. If called with no parameter returns the saved failure reason.

Parameters:
reason: failure reason

Returns: failure reason

get_voice_cmds

Returns a hash of voice commands where the key is the voice command name and the value is the perl code to run when the voice command name is called.

Higher classes which inherit this object may add to this list of voice commands by redefining this routine while inheriting this routine using the SUPER function.

This routine is called by the Insteon::generate_voice_commands manpage to generate the necessary voice commands.

is_deaf()

Returns true if the device must be awake in order to respond to messages. Most devices are not deaf, currently devices that are deaf are battery operated devices such as the Motion Sensor, RemoteLinc and TriggerLinc.

At the BaseObject level all devices are defined as not deaf. Objects which inherit BaseObject should redefine is_deaf as necessary.

is_controller()

Returns true if the device is a controller.

is_responder([1|0])

Stores and returns whether a device is a responder.

INI PARAMETERS

Insteon_PLM_max_queue_time

Was previously used to set the maximum amount of time a message could remain in the queue. This parameter is no longer used in the code but it still appears in the initialization. It may be removed at a future date. This also gets set in Insteon::BaseDevice as well for some reason, but is not used there either.

AUTHOR

Gregg Liming / gregg@limings.net, Kevin Robert Keegan, Michael Stovenour

NOTES

Special thanks to:
Brian Warren for significant testing and patches
Bruce Winter - MH

SEE ALSO

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.


Insteon::BaseDevice

DESCRIPTION

Generic class implementation of a Base Insteon Device.

INHERITS

Insteon::BaseObject

METHODS

new()

Instantiates a new object.

initialize()

A former holdover from when MisterHouse used to ping devices to get their device category. May not be needed anymore.

rate([rate])

Used to store and return the associated ramp rate of a device.

If provided, stores rate as the device's ramp rate in MisterHouse.

link_to_interface([group,data3])

If a controller link from the device to the interface does not exist, this will create that link on the device.

Next, if a responder link from the device to the interface does not exist on the interface, this will create that link on the interface.

The group is the group on the device that is the controller, such as a button on a keypad link. It will default to 01.

Data3 is optional and is used to set the Data3 value in the controller link on the device.

link_to_interface_i2cs([group,data3])

Performs the same task as link_to_interface however this routine is designed to perform the initial link to I2CS devices. These devices cannot be initially linked to the PLM in the normal way. This process requires more steps than the normal routine which will take longer to perform and therefore is more prone to faile. As such, this should likely only be used if necessary.

unlink_to_interface([group])

Will delete the contoller link from the device to the interface if such a link exists.

Next, will delete the responder link from the device to the interface on the interface, if such a link exists.

The group is the group on the device that is the controller, such as a button on a keypad link. It will default to 01.

enter_linking_mode(group, success_callback, failure_callback)

Places an i2 object into linking mode as if you had held down the set button on the device. i1 objects will not respond to this command. This is needed to link i2CS devices that will not respond without a manual link.

This process is included as part of the link_to_interface voice command and should not need to be called seperately.

Returns: nothing

set_operating_flag(flag)

Sets the defined flag on the device.

get_operating_flag()

Requests the device's operating flag and prints it to the log.

writable(cmd)

Appears to set and or return the "writable" state. Does not appear to be used in the Insteon code, but may be necessary for supporting other classes?

is_locally_set(cmd)

Returns the is_locally_set variable. Doesn't appear to be used in Insteon code. Likely was used to test whether setby was equal to the device itself. May not always be properly updated since it appears unused.

is_root()

Returns true if the object is the base object, generally group 01, on the device.

get_root()

Returns the root object of a device.

has_link(link_details)

If a device has an ALDB, passes link_details onto one of the has_link() routines within Insteon::AllLinkDatabase. Generally called as part of delete_orphan_links().

add_link(link_params)

If a device has an ALDB, passes link_details onto one of the add_link() routines within Insteon::AllLinkDatabase. Generally called from the "sync links" or "link to interface" voice commands.

update_link(link_params)

If a device has an ALDB, passes link_details onto one of the update_link() routines within Insteon::AllLinkDatabase. Generally called from the "sync links" voice command.

delete_link([link details])

If a device has an ALDB, passes link_details onto one of the delete_link() routines within Insteon::AllLinkDatabase. Generally called by delete_orphan_links().

scan_link_table()

Scans a device link table and caches a copy.

log_aldb_status()

Prints a human readable description of various settings and attributes associated with a device including:

Hop Count, Engine Version, ALDB Type, ALDB Health, and Last ALDB Scan Time

remote_set_button_tap([repeat])

In theory, would have the same effect as manually tapping the set button on the device repeat times.

WARN: Testing using the following does not produce results as expected. Use at your own risk. [GL]

request_status([requestor])

Requests the current status of the device and calls set() on the response. This will trigger tied_events.

get_engine_version

Queues a get engine version insteon message using the Insteon::BaseObject::_send_cmd manpage and sets a message failure callback to the Insteon::BaseDevice::_get_engine_version_failure manpage. Message response is processed in the Insteon::BaseObject::_is_info_request manpage

Returns: nothing

_get_engine_version_failure

Callback failure for the Insteon::BaseDevice::get_engine_version manpage; called for NAK and message timeout. Will force engine_version to I2CS which will also remap the aldb version if the device responds with a NAK. Does nothing for timeouts except print a message.

Returns: nothing

ping([count])

Sends the number of ping messages defined by count. 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.

Parameters:
count = the number of pings to send.

Returns: Nothing.

set_led_status()

Used to set the led staatus of SwitchLinc companion leds.

restore_string()

This is called by mh on exit to save the cached ALDB of a device to persistant data.

restore_states()

Obsolete / do not use.

Function should remain so that upgrading users will not have issues starting MH from previous versions that referenced this function in the mh_temp.saved_states file.

restore_aldb()

Used to reload the aldb of a device on restart.

devcat()

Sets and returns the device category of a device. Devcat can be requested by calling get_devcat().

get_devcat()

Requests the device category for the device. The returned value can be obtained by calling devcat().

firmware()

Sets and returns the device firmware version. Value can be obtained from the device by calling get_devcat().

states()

Sets and returns the available states for a device.

delete_orphan_links(audit_mode)

Reviews the cached version of all of the ALDBs and based on this review removes links from this device which are not present in the mht file, not defined in the code, or links which are only half-links.

If audit_mode is true, prints the actions that would be taken to the log, but does nothing.

log_alllink_table()

Prints a human readable form of MisterHouse's cached version of a device's ALDB to the print log. Called as part of the "scan links" voice command or in response to the "log links" voice command.

engine_version

Sets or gets the device object engine version. If setting the engine version, will also call check_aldb_version to map the aldb correctly for I2 devices.

Parameters:
p_engine_version: [I1|I2|I2CS] to set engine version

Returns: engine version string [I1|I2|I2CS]

retry_count_log([type]

Sets or gets the number of message retries that have occured for this device since the last time reset_message_stats was called.

If type is set, to any value, will increment retry log by one.

Returns: current retry count.

fail_count_log([type]

Sets or gets the number of message failures that have occured for this device since the last time reset_message_stats was called.

If type is set, to any value, will increment fail log by one.

Returns: current fail count.

outgoing_count_log([type]

Sets or gets the number of outgoing message that have occured for this device since the last time reset_message_stats was called.

If type is set, to any value, will increment output count by one.

Returns: current output count.

stress_test(count)

Simulates a read of a link address from the device. Repeats this process as many times as defined by count. This routine is meant to be used as a diagnostic tool. It is similar to scan_link_table, however, if a failure occurs, this process will continue with the next iteration. Scan link table will stop as soon as a single failure occurs.

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.

Note: This routine can create a lot of traffic if count is set very high. Try setting it to 5 first and working your way up.

outgoing_hop_count([type]

Sets or gets the number of hops that have been used in all outgoing messages since the last time reset_message_stats was called.

If type is set, to any value, will increment output count by that value.

Returns: current hop count.

incoming_count_log([type]

Sets or gets the number of incoming message that have occured for this device since the last time reset_message_stats was called.

If type is set, to any value, will increment incoming count by one.

Returns: current incoming count.

dupe_count_log([type]

Sets or gets the number of duplicate message that have arrived from this device since the last time reset_message_stats was called.

If type is set, to any value, will increment corrupt count by one.

Returns: current duplicate count.

hops_left_count([type]

Sets or gets the number of hops_left for messages that arrive from this device since the last time reset_message_stats was called.

If type is set, to any value, will increment corrupt count by one.

Returns: current hops_left count.

max_hops_count([type]

Sets or gets the number of max_hops for messages that arrive from this device since the last time reset_message_stats was called.

If type is set, to any value, will increment corrupt count by one.

Returns: current duplicate count.

reset_message_stats

Resets the retry, fail, outgoing, incoming, and corrupt message counters.

print_message_stats

Prints message statistics for this device to the print log. The output contains:

check_aldb_version

Because of the way MH saves / restores states "after" object creation the aldb must be initially created before the engine_version is restored. It is therefore impossible to know the device is i2 before creating the aldb object. The solution is to keep the existing logic which assumes the device is peek/poke capable (i1 or i2) and then delete/recreate the aldb object if it is later determined to be an i2 device.

There is a use case where a device is initially I2 but the user replaces the device with an I1 device, reusing the same object name. In this case the object state restore will build an I2 aldb object. The user must manually initiate the 'get engine version' voice command or stop/start MH so the initial poll will detect the change.

This is called anytime the engine_version is queried (initial startup poll) and in the Reload_post_hooks once object_states_restore completes

get_voice_cmds

Returns a hash of voice commands where the key is the voice command name and the value is the perl code to run when the voice command name is called.

Higher classes which inherit this object may add to this list of voice commands by redefining this routine while inheriting this routine using the SUPER function.

This routine is called by the Insteon::generate_voice_commands manpage to generate the necessary voice commands.

link_data3

Returns the data3 value that should be used when creating a link for this device. This sub provides the default for all Insteon devices. Individual device definitions can override this sub to return something unique. This sub was modivated by the need to return unique values for data3 on responder links for group 01. Most Insteon devices will learn 00 for the data3 responder link value, however the In-LineLinc Relay learns 01 when manually linking and requires that value when creating the links programmatically.

INI PARAMETERS

Insteon_PLM_max_queue_time

Was previously used to set the maximum amount of time a message could remain in the queue. This parameter is no longer used in the code but it still appears in the initialization. It may be removed at a future date. This also gets set in Insteon::BaseObject as well for some reason, but is not used there either.

AUTHOR

Gregg Liming / gregg@limings.net, Kevin Robert Keegan, Michael Stovenour

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.


Insteon::MultigroupDevice

DESCRIPTION

Contains functions which are unique to insteon devices which have more than one group. This includes, KeyPadLincs, RemoteLincs, FanLincs, Thermostats (i2 versions).

INHERITS

Nothing.

This package is meant to provide supplemental support and should only be added as a secondary inheritance to an object.

METHODS

sync_all_links(audit_mode)

Syncs all links on the object, including all subgroups such as additional buttons.

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 identified by sync_all_link. 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.

AUTHOR

Kevin Robert Keegan

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.


Insteon::BaseController

DESCRIPTION

Generic class implementation of an Insteon Controller.

INHERITS

Generic_Item

METHODS

new()

Instantiates a new object.

add(object[,on_level, ramp_rate])

Adds object as a responder to the device. If on_level and ramp_rate are specified they will be used, otherwise 100% .1s will be used.

sync_links(audit_mode)

Causes MisterHouse to review the list of objects that should be linked to device and to check to make sure these links are complete. If any link is not complete MisterHouse will add the link.

If audit_mode is true, MisterHouse will print the actions it would have taken to the log, but will not take any actions.

The process does the following 5 checks in order:

 1. Does a controller link exist for Device-> PLM
 2. Does a responder link exist on the PLM

it then loops through all of the links defined for a device and checks:

 3. Does the responder link exist
 4. Is the responder link accurate
 5. Does the controller link on this device exist
set_linked_devices(state)

Checks each linked member of device. If the linked member is a light_item, then sets that item to state. If the linked member is a Insteon::BaseObject then call set_receive for the member.

set_with_timer(state, time, return_state, additional_return_states)

NOTE - This routine appears to be nearly identical, if not identical to the Generic_Item::set_with_timer() routine, it is not clear why this routine is needed here.

See full description of this routine in Generic_Item

update_members()

This appears to be a depricated routine that is no longer used. At a cursory glance, it may throw an error if called.

initiate_linking_as_controller()

Places the interface in linking mode as the controller. To complete the process press the set button on the responder device until it beeps. Alternatively, you may be able to complete the process with Insteon::BaseDevice::enter_linking_mode().

find_members([type])

Returns a list of objects that are members of device. If type is specified, only members of that type are returned. Type is a package name, for example:

    $member->find_members('Insteon::BaseDevice');
has_member(object)

Returns true if object is a member of device, else returns false.

AUTHOR

Gregg Liming / gregg@limings.net, Kevin Robert Keegan, Michael Stovenour

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.


Insteon::DeviceController

DESCRIPTION

Generic class implementation of an Device Controller.

INHERITS

Insteon::BaseController

METHODS

new()

Instantiates a new object.

request_status([requestor])

Requests the current status of the device and calls set() on the response. This will trigger tied_events.

AUTHOR

Gregg Liming / gregg@limings.net, Kevin Robert Keegan, Michael Stovenour

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.


Insteon::InterfaceController

DESCRIPTION

Generic class implementation of an Interface Controller. These are the PLM Scenes.

INHERITS

Insteon::BaseController, Insteon::BaseObject

METHODS

new()

Instantiates a new object.

get_root()

Returns the root object of a device, in this case the interface.

get_voice_cmds

Returns a hash of voice commands where the key is the voice command name and the value is the perl code to run when the voice command name is called.

Higher classes which inherit this object may add to this list of voice commands by redefining this routine while inheriting this routine using the SUPER function.

This routine is called by the Insteon::generate_voice_commands manpage to generate the necessary voice commands.

AUTHOR

Gregg Liming / gregg@limings.net, Kevin Robert Keegan, Michael Stovenour

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.

 BaseInsteon.pm