Items Insteon_PLM

Insteon_PLM

See original

SYNOPSIS

DESCRIPTION

This is the base interface class for Insteon Power Line Modem (PLM)

INHERITS

Serial_Item
Insteon::BaseInterface

INI PARAMETERS

Prameter	Comment
Insteon_PLM_serial_port	Identifies the port on which the PLM is attached. Example: Insteon_PLM_serial_port=/dev/ttyS4
Insteon_PLM_use_TCP	Setting this to 1, will enable MisterHouse to use a networked PLM such as the Insteon Hub. This functionality seems fairly stable, but has not been extensively tested. You will also need to set values for Insteon_PLM_TCP_host and Insteon_PLM_TCP_port. There are a few quirks when using a networked PLM, they include: The communication may be slightly slower with the network PLM. In order to prevent MisterHouse from clobbering the device it is recommended that you set the Insteon_PLM_xmit_delay to 1 second. Testing may reveal that slightly lower delays are also acceptable. Changes made using the hub's web interface will not be understood by MisterHouse. Device states may become out of sync. (It is possible that future coding may be able to overcome this limiation)
Insteon_PLM_TCP_host	If using a network PLM, set this to the IP address of the PLM. See Insteon_PLM_use_TCP.
Insteon_PLM_TCP_port	If using a network PLM, set this to the port address of the PLM. Generally, the port number is 9761. See Insteon_PLM_use_TCP.
Insteon_PLM_xmit_delay	Sets the minimum amount of seconds that must elapse between sending Insteon messages to the PLM. Defaults to 0.25.
Insteon_PLM_xmit_x10_delay	Sets the minimum amount of seconds that must elapse between sending X10 messages to the PLM. Defaults to 0.50.
Insteon_PLM_disable_throttling	Periodically, the PLM will report that it is too busy to accept a message from MisterHouse. When this happens, MisterHouse will wait 1 second before trying to send a message to the PLM. If this is set to 1, downgrades the delay to only .3 seconds. Most of the issues which caused the PLM to overload have been handled it is unlikely that you would need to set this.
Insteon_PLM_reconnect_count	The PLM acknowledges the receipt of a command from MisterHouse with an ACK message. It is very rare for a well functioning PLM to fail to send the ACK message. In many cases, the failure to receive an ACK message from the PLM is a sign that the connection between MisterHouse and the PLM (Serial or USB) has died. This setting defines the number of missed ACK messages that must occur for MisterHouse to deem the PLM connection lost. The number of missed ACK messages must all occur while sending a single Insteon command. So if you want this to do anything, this number needs to be less than or equal to the Insteon_retry_count. Once the number of missed ACK messages occurs, MisterHouse will attempt to reconnect the PLM. For some people, the reconnect routine causes errors, so you may want to test this out by manually pulling the connection cable to the PLM to see how your system will react. By default, this is set to 99, essentially disabling an automatic restart.>br/>Note the ACK messages discussed here refer to PLM ACK messages not the ACK messages received from an Insteon device in response to a command.

METHODS

Method	Description
serial_startup()	Creates a new serial port connection.
serial_restart()	Attempt to restart/reconnect the serial port connection. `
new()	Instantiates a new object.
corrupt_count_log([type]	Sets or gets the number of corrupt message that have arrived that could not be associated with any device since the last time reset_message_stats was called. These are generally instances in which the from device ID is corrupt. If type is set, to any value, will increment corrupt count by one. Returns: current corrupt count.
reset_message_stats	Resets the retry, fail, outgoing, incoming, and corrupt message counters.
restore_string()	This is called by mh on exit to save the cached ALDB of a device to persistent data.
check_for_data()	Called once per loop. This checks for any data waiting on the serial port, if data exists it is sent to _parse_data. If there is no data waiting, then this checks to see if the timers for any previous commands have expired, if they have, it calls retry_active_message(). Else, this checks to see if there is any timeout preventing a transmission right now, if there is no timeout it calls process_queue().
set()	Used to send X10 messages, generates an X10 command and queues it.
complete_linking_as_responder()	Puts the PLM into linking mode as a responder.
log_alllink_table()	Causes MisterHouse to dump its cache of the PLM link table to the log.
scan_link_table()	Causes MisterHouse to scan the link table of the PLM only.
initiate_linking_as_controller([p_group])	Puts the PLM into linking mode as a controller, if p_group is specified the controller will be added for this group, otherwise it will be for group 00.
initiate_unlinking_as_controller([p_group])	Puts the PLM into unlinking mode, if p_group is specified the PLM will try to unlink any devices linked to that group that identify themselves with a set button press.
cancel_linking()	Cancels any pending linking session that has not completed.
_aldb()	Returns the PLM's aldb object.
_send_cmd()	Causes a message to be sent to the serial port.
_parse_data()	This routine parses data comming in from the serial port. In many cases multiple messages or fragments of messages may arrive at once. This routine attempts to parse this string of data into individual messages, unfortunately the PLM does not have a unique message delimiter. Instead, all PLM messages start with 02XX where XX is a two digit code corresponding to the message type. The one caveat, is that the PLM may send simple 15 to indicate that it is busy. This routine uses a First-In-First-Out (FIFO) style for processing the data stream by following this procedure: 1. Prepend any prior data fragment left over from the last run 2. Trim off any PLM busy messages 3. Locate the first valid PLM prefix in the message 4. Look for PLM ACK, NACK and BadCmd Responses 5. Look for known Insteon message types 6. Dispose of stale data that doesn't match known message types 7. Save whatever data fragments remain for the next pass Based on the type of message, it is then passed off to higher level message handling routines.
_next_valid_prefix()	Looks for the first instance of a valid PLM prefix is a string of data and returns that prefix and all subsequent data.
add_id_state()	Dummy sub required to support the X10 integrtion, does nothing.
firmware()	Stores and returns the firmware version of the PLM.
link_data3	Returns the data3 value that should be used when creating a link for this device. This sub was modivated by the need to return unique values for data3 on responder links for group 01. The PLM will store the responder's devcat data for controller entries. That's fundamentally hard so just do the same as for other devices for now. Can make this smarter in the future if needed.

NOTES

Special Thanks to:

Brian Warren for significant testing and patches

Bruce Winter - MH

AUTHOR

Jason Sharpee / [email protected], Gregg Liming / [email protected], Kevin Robert Keegan, Michael Stovenour

SEE ALSO

For more information regarding the technical details of the PLM: Insteon PLM Dev Guide