--- plmtools-imeter Summary ---

The insteon shell script is suggested for high-level scripting using
insteon devices. The plm programs are lower-level and interact with
devices using the binary insteon protocol.

plmcat - reads data from the PLM and outputs in ASCII hexadecimal notation
plmsend - send hex data to PLM and wait for response or timeout
plmtty - interactive PLM communication program
x10toinst - example shell script to convert X10 messages into insteon
insteon - script for issuing human-readable commands (wrapper for plmsend)

--- Using the insteon script ---

To use the insteon script, first create /etc/insteon.conf and customize
if for your devices.  See insteon.conf.example for an example.  After you
have created a config file, use:

	insteon device_name command [argument]

such as (if kitchen is a dimmable switch):

	insteon kitchen on 33

or (if kitchen is an iMeter):

  insteon kitchen meter

Supported commands are "on, off, bright, dim, ping, status, level, meter".
Only the 'on' command takes an optional argument. Level returns the current
'on' level on a scale of 0 to 100. Future versions may revert to a scale of
0 to 255 because "insteon foo on 33; insteon foo level" returns 32, which
may complicate scripting.

--- iMeter Querying ---

The 'meter' command allows you to query the current power draw reported 
by an iMeter Solo. This is reported as the number of watts the connected
device is currently consuming. Note that the "meter" command gives undefined
output if used on non-iMeter devices. Additionally, do not use the "level"
command on an iMeter device - this will always return 0, and does NOT 
(necessarily) indicate that the connected device is off.

--- Decoupling Input and Output ---

By default, the insteon script will send the command, then fetch and display
the expected output from the PLM. This will interfere with plmcat if it is
running, since both will be attempting to read from the PLM.

Passing the -q flag to insteon will prevent the script from waiting for or
fetching command output (thus also suppressing all output). This can be used
for two purposes: (1) sending rapid commands, since the command will return
very quickly after sending the command, and (2) asynchronously sending commands
to the PLM and collecting all incoming output from the PLM on a separate
plmcat process. Note that when sending many commands, you should be careful
to not overwhelm the limited amount of bandwidth available, as this will result
in collisions and garbled packets received on the PLM.

Passing the -v flag to plmcat will annotate incoming packets with human-readable
info about their contents, which may be helpful in debugging.

--- Miscellaneous ---

The current insteon script allows you to specify a smaller number of ONLEVELS
for bright/dim commands than the default 32.  Since some signals may get
dropped, it may take an unacceptably long time to get to the desired
brightness.  You might want to set ONLEVELS to an odd number to prevent
having a level of exactly 50% which is the most wasteful of power.  Also,
having a large value for ONLEVELS would put several of them close to 50%.

To use the x10toinst script, first create /etc/x10toinst.conf and customize
it for your devices.  See x10toinst.conf.example for an example.  Run it as
you would any other script.

However, terminating x10toinst can leave an orphaned plmcat running that will
continue to run until new data comes in on the PLM.  x10toinst tries to kill
these plmcat processes, but it may miss some.

Incidentally, none of these programs mind at all if you have an x10 
firecracker connected on the same port as the PLM.  Bottlerocket will
continue to work fine.

Try calling your customized insteon script from within a cron job.  I have
mine set up to automatically turn on several lights 30 minutes before
sunset with data retrieved from online.

Currently, plmtty will interfere with the operation of the other
programs and scripts. It is intended to be used for debugging only.

Copyright (2012) University of Massachusetts Amherst
Contact Sean Barker (sbarker@cs.umass.edu)

Copyright (2008) by Matthew Randolph (mcr@umd.edu)

