Routines and a test program for querying controlling HAI's omnistat RC
line of programmable residential/industrial thermostats.

For more information on these thermostats, see Home Automation Inc's
web page at http://www.hai.com

By Steve Tell, tell@telltronics.org

In lieu of real documentation or a manual page, this file will serve
for now.

What's here:
- stc,  "stat control" a simple command-line program to query and control
Omnistat thermostats connected to a serial port.
- Functions in omnistat.c and regs.c that may be useful in writing
more comprehensive and friendly thermostat control programs and interfaces to
home automation systems.
- Generally useful serial I/O routines in tty.c
- a few miscellaneous general routines in misc.c

NAME

stc - simple query and control of RC-series communicating thermostats

SYNOPSIS

stc [-vcnV] [-l dev] [-a address] command [args]

stc [options] cmd cmdno data
stc [options] time
stc [options] stime
stc [options] readall
stc [options] writeall file
stc [options] getg
stc [options] scan startaddr endaddr

DESCRIPTION

The stc program is both a demonstration and test program for the
omnistat routines, and a rudimentary thermostat control program in its
own right.

OPTIONS

-a address
Control or query the thermostat at the specified address instead of the
default address of 0x01.  This option has no effect on the scan command.

-c 
Display all temperatures in celsius instead of fahrenheit, and expect
all temperatures read in to be in celsius.

-l dev
Use the specified serial port device instead of a compiled-in default.

-n
With the writeall command, don't actually do the writes.  Instead,
displays what byte values would be written.  Mostly useful for debugging.

-v
Verbose.  Enable verbose display of all packet data sent an received.

COMMANDS

Stc has several subcommands, listed here.

cmd c data
Send the numeric command c, with the specified hex or
decimal data.  Refer to the omnistat protocol spec for details on the
commands.  Caution: no checking is done on the command; it is possible
to send undocumented commands and to attempt writing to the reserved
"do not write" registers.

time
Get and print the thermostat's idea of the current day and time.

stime
Set the thermostat's clock and day.  Uses the current unix system time
and local time zone.

readall
Read and print the values of all non-reserved thermostat registers in
a convenient format to standard output.

writeall file
Read the specified file, and use that data to write values to the
thermostat's registers.  The file format is that written by the
readall command, so readall and writeall can be used to save and
restore thermostat settings.  Only registers both listed in the file
and known to the program as being writable and sensible to save and
restore are changed.  For example even though the current-time
registers are recorded by readall, they are never written by the
writeall command.

getg
Get and print the thermostat's "group 1 data" in a convenient format.

scan start-address end-address
Try successive address and see which thermostats respond.  The model
numbers of the thermostats that respond are printed.  See the omnistat
documentation for information about connecting multiple thermostats to
a single serial port and setting their addresses.

BUGS

Stc can't broadcast commands to all thermostats on a bus.

Farhenheit display may be off by one from that shown on thermostat's
LCD display.  I think this is because the thermostat rounds up when
the converted result is exactly NN.50, while standard C's
cast-to-integer does proper round-to-even.

readall output and writeall input should include the celsius flag
somehow.  Perhaps parse it in writeall (as a seperate keyword).  Or
else mark temperatures with °F and °C , and make conversion routines
handle that.  For now, either always specify -c, or always leave it out.

The low-level error messages, such as for communication timeouts, aren't
very informative.

There should be a flag to force the writeall command to write registers
that it normally won't.

DISCLAIMER

I have no association with Home Automation Inc other than purchasing
one of their products.  Use this software at your own risk.  As of
this writing, I've had the thermostat for a week, the software is a
few days old, and the thermostat has actually been installed on the wall and
controlling my house's HVAC system for only about 4 hours.  

UPDATE 

October 2003: The thermostat has been running for over 5 years.
More comprehensive homebrew home-automation software derived from this code
controls it daily, but this code is still used periodicly.

SEE ALSO
localtime(3)