====== INSTEON Commands (indigo.insteon.*) ======

Commands that are specific to INSTEON devices.

==== Send Scene Decrease ====

This command will send an INSTEON Scene Decrease (dim on dimmable loads) command to the specified PowerLinc scene. The value will decrease by 3% for each call.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneDecrease(11)</code>|
|<code>indigo.insteon.sendSceneDecrease(11, repeatCount=5)</code>|
|<code>indigo.insteon.sendSceneDecrease(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneDecrease(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneDecrease("working in office scene")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''repeatCount''//|  No  |  integer  |a value from 1-32 for the number of times to repeat the decrease (default is 1)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene Increase ====

This command will send an INSTEON Scene Increase (brighten on dimmable loads) command to the specified PowerLinc scene. The value will increase by 3% for each call.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneIncrease(11)</code>|
|<code>indigo.insteon.sendSceneIncrease(11, repeatCount=5)</code>|
|<code>indigo.insteon.sendSceneIncrease(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneDecrease(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneIncrease("working in office scene")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''repeatCount''//|  No  |  integer  |a value from 1-32 for the number of times to repeat the increase (default is 1)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene ON ====

This command will send an INSTEON Scene ON command using the specified PowerLinc scene.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneOn(11)</code>|
|<code>indigo.insteon.sendSceneOn(11)</code>|
|<code>indigo.insteon.sendSceneOn(11, sendCleanUps=False)</code>|
|<code>indigo.insteon.sendSceneOn(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneOn(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneOn("working in office scene")</code>|
|<code>indigo.insteon.sendSceneDecrease(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneOn("working in office scene", sendCleanUps=False)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''sendCleanUps''//|  No  |  boolean  |True if if cleanup messages should be sent to each device in the scene after the scene command - this will have the PowerLinc send each device a message to make sure it received the command. You might want to stop cleanup messages from being sent because it involves adding a lot of INSTEON traffic and might effect performance (particularly if a group has a lot of responders). But, of course, disabling it may reduce reliability of some modules receiving the scene command so it's usually best to ignore this setting. (default is True)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene OFF ====

This command will send an INSTEON Scene OFF command using the specified PowerLinc scene.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneOff(11)</code>|
|<code>indigo.insteon.sendSceneOff(11, sendCleanUps=False)</code>|
|<code>indigo.insteon.sendSceneOff(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneOff(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneOff("working in office scene")</code>|
|<code>indigo.insteon.sendSceneOff("working in office scene", sendCleanUps=False)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''sendCleanUps''//|  No  |  boolean  |True if if cleanup messages should be sent to each device in the scene after the scene command - this will have the PowerLinc send each device a message to make sure it received the command. You might want to stop cleanup messages from being sent because it involves adding a lot of INSTEON traffic and might effect performance (particularly if a group has a lot of responders). But, of course, disabling it may reduce reliability of some modules receiving the scene command so it's usually best to ignore this setting. (default is True)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene Fast ON ====

This command will send an INSTEON Scene Fast ON command using the specified PowerLinc scene.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneFastOn(11)</code>|
|<code>indigo.insteon.sendSceneFastOn(11, sendCleanUps=False)</code>|
|<code>indigo.insteon.sendSceneFastOn(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneFastOn(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneFastOn("working in office scene")</code>|
|<code>indigo.insteon.sendSceneFastOn("working in office scene", sendCleanUps=False)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''sendCleanUps''//|  No  |  boolean  |True if if cleanup messages should be sent to each device in the scene after the scene command - this will have the PowerLinc send each device a message to make sure it received the command. You might want to stop cleanup messages from being sent because it involves adding a lot of INSTEON traffic and might effect performance (particularly if a group has a lot of responders). But, of course, disabling it may reduce reliability of some modules receiving the scene command so it's usually best to ignore this setting. (default is True)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene Fast OFF ====

This command will send an INSTEON Scene Fast OFF command using the specified PowerLinc scene.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneFastOff(11)</code>|
|<code>indigo.insteon.sendSceneFastOff(11, sendCleanUps=False)</code>|
|<code>indigo.insteon.sendSceneFastOff(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneFastOff(11, updateStatesOnly=True)</code>|
|<code>indigo.insteon.sendSceneFastOff("working in office scene")</code>|
|<code>indigo.insteon.sendSceneFastOff("working in office scene", sendCleanUps=False)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''sendCleanUps''//|  No  |  boolean  |True if if cleanup messages should be sent to each device in the scene after the scene command - this will have the PowerLinc send each device a message to make sure it received the command. You might want to stop cleanup messages from being sent because it involves adding a lot of INSTEON traffic and might effect performance (particularly if a group has a lot of responders). But, of course, disabling it may reduce reliability of some modules receiving the scene command so it's usually best to ignore this setting. (default is True)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|
|//''updateStatesOnly''//|  No  |  boolean  |use if you only want Indigo's internal device state representation to be updated - no actual INSTEON command will be sent on RF or the power line (default is False)|

==== Send Scene Start Change ====

This command will tell the specified PowerLinc scene to begin increasing/decreasing in value. It will continue to ramp each device in the scene until either the corresponding [[#Send Scene Stop Change]] command is called or until the devices are at 100% for increase ramping or 0% for decrease ramping.

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneIncrease(11, increase=True)</code>|
|<code>indigo.insteon.sendSceneIncrease(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneIncrease("working in office scene")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''increase''//|  Yes  |  boolean  |True if you want to ramp up, False if you want to ramp down  |
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Send Scene Stop Change ====

This command will tell the specified PowerLinc scene to stop any ramping activity started by a [[#Send Scene Start Change]] command. 

^  Command Syntax Examples  ^
|<code>indigo.insteon.sendSceneIncrease(11)</code>|
|<code>indigo.insteon.sendSceneIncrease(11, suppressLogging=True)</code>|
|<code>indigo.insteon.sendSceneIncrease("working in office scene")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer or string  |either the scene number or the scene name - we encourage numbers since they won't change and the scene names can.|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Send Status Request ====

This command will send an INSTEON Status Request command to the specified address.

^  Command Syntax Examples  ^

|<code>reply = indigo.insteon.sendStatusRequest("0A.B9.DC")
indigo.server.log("reply success: %d, ack value: %02X" % (reply.cmdSuccess, reply.ackValue))</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  string  |the target INSTEON address as a hexidecimal string.|
|//''waitUntilAck''//|  No  |  boolean  |true if the caller wants to wait for the result. (default is True)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Send Raw ====

This command will send a raw INSTEON standard command.

^  Command Syntax Examples  ^

|<code>reply = indigo.insteon.sendRaw("0A.B9.DC", [0x10, 0x00])
indigo.server.log("reply success: %d, ack value: %02X" % (reply.cmdSuccess, reply.ackValue))</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  string  |the target INSTEON address as a hexidecimal string.|
|//''cmdBytes''//|  Yes  |  list  |a list of 2 integer bytes that represent the command to be sent.|
|//''waitUntilAck''//|  No  |  boolean  |True if the caller wants to wait for the result. (default is True)|
|//''waitForStandardReply''//|  No  |  boolean  |True if the caller wants to wait for a follow-up direct standard reply. (default is False)|
|//''waitForExtendedReply''//|  No  |  boolean  |True if the caller wants to wait for a follow-up direct extended reply. (default is False)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Send Raw Extended ====

This command will send a raw INSTEON extended command (command payload can be between 2 and 16 bytes).

^  Command Syntax Examples  ^

|<code># Get KeypadLinc info (LED states, brightness, etc.)
reply = indigo.insteon.sendRawExtended("11.7B.2E", [0x2E, 0x00], waitForExtendedReply=True)
if reply.cmdSuccess:
	indigo.server.log("     backlight brightness: %d" % (reply.replyBytes[10],))
	indigo.server.log("button toggle mode bitmap: 0x%02X" % (reply.replyBytes[11],))
	indigo.server.log("     button states bitmap: 0x%02X" % (reply.replyBytes[12],))</code>|
|<code># Change the Keypad LED brightness from dim to bright
setKeypadLedBrightness = [
	0x2E, 0x00,
	0x00,			# unused
	0x07,			# change LED backlight brightness
	0x11,			# brightness between 0x11 and 0x7F
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
]
for brightness in [0x07, 0x44, 0x66, 0x7F]:
	setKeypadLedBrightness[4] = brightness
	indigo.insteon.sendRawExtended("11.7B.2E", setKeypadLedBrightness)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  string  |the target INSTEON address as a hexidecimal string.|
|//''cmdBytes''//|  Yes  |  list  |a list of 2 to 16 integer bytes that represent the command to be sent.|
|//''calcCrc''//|  No  |  boolean  |automatically calculate 8 bit CRC byte for message (used by i2CS firmware). (default is True)|
|//''calc16bitCrc''//|  No  |  boolean  |automatically calculate 16 bit CRC byte for message (used by specific modules). (default is False)|
|//''waitUntilAck''//|  No  |  boolean  |True if the caller wants to wait for the result. (default is True)|
|//''waitForStandardReply''//|  No  |  boolean  |True if the caller wants to wait for a follow-up direct standard reply. (default is False)|
|//''waitForExtendedReply''//|  No  |  boolean  |True if the caller wants to wait for a follow-up direct extended reply. (default is False)|
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Send PowerLinc SET Button Press Message ====

This will command the PowerLinc to send its SET Button Press Message, which can be useful in some linking scenarios.

^  Command Syntax Examples  ^

|<code>reply = indigo.insteon.sendPowerLincSetButtonPress()</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|//''suppressLogging''//|  No  |  boolean  |True if if entries in the event log should be suppressed (default is False)|

==== Subscribe to Events ====
Use the lower-level //''subscribeToIncoming()''// and //''subscribeToOutgoing()''// methods in the //''indigo.insteon''// command space to see commands regardless of their effect on device state.

^  Low Level Commands  ^
|indigo.insteon.subscribeToIncoming()|
|indigo.insteon.subscribeToOutgoing()|

For example,
<code>
    def startup(self):
        self.logger.debug("startup called -- subscribing to all INSTEON commands")
        indigo.insteon.subscribeToIncoming()
        indigo.insteon.subscribeToOutgoing()

    ########################################
    def insteonCommandReceived(self, cmd):
        self.logger.debug(f"insteonCommandReceived: \n{str(cmd)}")

    def insteonCommandSent(self, cmd):
        self.logger.debug(f"insteonCommandSent: \n{str(cmd)}")
</code>