GETTING HELP WITH KTOOLS

KTOOLS is the parameter set editor, logger configuration, and 
data collection tool for Highland Technology, Inc. K series 
data loggers.  You use this program to edit parameter set files 
that get loaded to the data logger.  The parameter set controls
how the logger scales and records the signals from power
metering, analog, and digital channels.

Once the logger is configured and begins recording data, you can
use KTOOLS to view real-time data, acquire Time Series Records
(TSRs).


NEED HELP?


If the context sensitive help does not answer your question or if 
you have some problem or bug to report, you can contact the original 
author of KTOOLS via email at: 

mark@fishbaugher.com


BASIC THEORY OF OPERATION


KTOOLS uses four different kinds of files to organize the
configuration of loggers and data collected from your network.  
The types of files and a brief description of each type is 
shown below:

1) The Setup or System File:  There is only one setup file called
SETUP.DAT located in the root directory with the KTOOLS program. 
This file contains the path names (directory locations) used to
store different file types, hardware settings, and other high 
level setup preferences.  You use the Setup main menu item to 
make changes to this file.

2) Parameter Set Files:  Each logger can be configured in a variety
of ways involving different channel selections, time series record
selections, and integration periods.  You use the parameter set
number (found in the Edit/General Information form) to assign 
a parameter set ID number to each of the configurations.  What 
uniquely identifies a parameter set is the logger's
serial number and the parameter set ID sequence number.  

NO FILE NAMING CONVENTION IS ENFORCED. YOU MAY CALL THE CONTROL FILE,
PARAMETER SET FILES, AND TSR FILES WHATEVER SUITS YOU.  The only 
exception to this is when you add a new record to the control file.
It that instance, KTOOLS fills in a parameter set filename and TSR
filename that you can accept or replace.

Parameter set files are located in the Parameters Directory
specified in the Setup/Files form.  TSR files are located in the
TSR data path also specified in the Setup/Files form.

One important feature of the parameter set files is they can be
read from disk (the most common) OR directly from the logger.  When
you do a Operations/Write-All Configuration, a complete copy of
the ASCII parameter set file gets written into the logger's non-
volatile memory.  If you should happen to lose or damage your
parameter set files on disk, you'll always have another copy in the
logger!

3) Control File:  This is a network control file containing one 
record for each logger in your network.  The control file 
contains the information necessary to establish communications 
with the logger and keep track of which time series records have
been retrieved.  You can configure multiple copies of KTOOLS with
there own groups of loggers that they control, OR you can have a 
single control file (like on a network server) that all copies
of KTOOLS access.  A strict check-in and check-out method
is used to control access to records in the control file.

4) TSR (or Time Series Record) File:  This is the file that
contains the time series data from the logger.  The file gets
appended when you collect more TSR records.

The format of ALL FOUR types of files is simple, self descriptive
ASCII.  This makes the files suitable for processing and printing 
outside the KTOOLS program with any text editor or text processing
tools like AWK and PERL. Using KTOOLS forms is just a convenient 
method to track and edit the files with built-in error checking and 
automatic pick-list selections.


ACKNOWLEDGEMENTS


The KTOOLS Software and supporting materials were developed by 
Fishbaugher and Associates under contract with Highland  
Technology, Inc.


COPYRIGHT


This software is copyrighted and all rights are reserved by 
Highland Technology. Inc. Under the copyright laws, you may not 
copy or in any way reproduce the software or this help material 
without written permission from  Highland, except to make one
backup copy of the original software.


DISCLAIMER


HIGHLAND TECHNOLOGY, INC AND FISHBAUGHER AND ASSOCIATES
MAKE NO WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR
IMPLIED, WITH RESPECT TO THIS SOFTWARE AND USER'S MANUAL,
ITS QUALITY, PERFORMANCE OR CONTENTS. IN NO EVENT WILL
HIGHLAND TECHNOLOGY, INC. OR FISHBAUGHER AND ASSOCIATES
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE
SOFTWARE OR DOCUMENTATION. YOU, THE USER, ARE ASSUMING
THE FULL RISK FOR THE SOFTWARE AND DOCUMENTATION.


RELEASE NOTES


10/10/96 Corrected bug in parsing large NEGATIVE floating point 
scale factors that overflowed the field width on writing the 
parameter set file causing file corruption on subsequent reads.

10/10/96 Corrected bug where fields on the recorder type form 
were set to default values when you switched the recorder type

12/10/96 Corrected a bug in the parameter set build code. This was
a serious bug that effected the way the recorder references voltages
to the current transformers.  If you have a version of KTOOLS prior
to 12/10/96, it should be updated.

1/17/97 Added the Binary File option under the File main menu.  This
menu item writes the 256 byte binary parameter block to a disk file.
It is used for diagnostic and debugging purposes.

1/17/97 Corrected bug introduced in the 12/10/96 version. That version
did not assign power register numbers correctly and should not be 
used.

2/5/97 With the new TSR and waveform capabilities, we really needed
a new name because the program is not just about setting 
parameters (PARSET).  The software has been rename KTOOLS and the
executable is KT.EXE.

2/18/97 First version of KTOOLS with TSR data collection and Real
time data viewer.

3/5/97 Added free form comments up to 3K in size to the parameter
set data.  The comments are stored on the disk AND are written to 
the logger when configured with the 'Write All' option.

3/5/97 Added a complete editor for the logger control file containing
phone numbers and the like.  This includes an explicit 'check-out'
method for support of operation on networks.

3/13/97 Fixed bug where File/DOS Shell caused the program to fail if
you changed directories from the KTOOLS root.

3/24/97 Fixed bug where KTOOLS gets a floating point divide by zero
when converting a TSR record with a zero integration counter.  A zero
integration record is written on recovery from a power failure.

3/24/97 Added kt.pif and kt.ico for installation as an icon under
Windows 3.1 or Windows95

7/29/97 Added the clock SYNC_SEC parameter to the SETUP.DAT file for
testing the synchronization of logger clocks with the host clock.  Added
automatic checks of the clock and CRCs on each connection.

8/4/97 Corrected bug in the handling of parameter set files.  Versions
prior to this date likely had file corruption problems when more than
one or two parameter set files were read/written in a single session
of running KTOOLS.  ANY VERSIONS PRIOR TO THIS DATE SHOULD BE CONSIDERED
SERIOUSLY FLAWED AND DISCARDED.

1/21/98 Fixed minor bug where the File/Erase menu was not listing
all of the available parameter set files.

1/27/98 Fixed weakness in the code that loaded the configuration area
of the K20 that contains a copy of the ASCII parameter set file.  Previous
versions would give up on the first bad packet transmission.  The new
code includes some re-try logic for better noise immunity on all 
commands

1/27/98 Fixed problem with TSR indexing at the end of the K20 wrap
around buffer.  Version prior to this date will not be able to collect
the last TSR in the K20 TSR buffer.

2/4/98 Fixed problem where K20-8 loggers had unused power register 
readings (due to ciruit noise) added to power register 0.

2/4/98 Fixed millenium bug on roll over to 1/1/2000.  All years are now
presented in 4 digits except the logger read time date reading which
shows a two digit year 00 = 2000.  KTOOL TSR conversion now good until
2038.

2/23/98 Version 1.2 Added the strip chart feature under the 'Operations'
main menu.

2/26/98 V1.2.1 The timeout setting for writing the Config. Area was too
short causing some problems with configuring loggers.  The time out 
was increased in this version from 2.0 to 4.0 seconds.

2/26/98 V1.2.1 Released

3/4/98 Improved the strip chart making lighter grid lines so the
data is easier to view.

4/9/98 The File|Print Binary option now create two output files.  The first
is the paramter set block and the second is the factor table.  These
files are useful for debugging puposes only and are not used by KTOOLS.

4/9/98 Versions prior to this date had a bug with the conversion units
of RTD sensors with 'snap shot' type data collection.  RTD are not usually
sampled in this way, so this correction should not effect anyone.

4/9/98 Previous versions limited the number of significant figures of the
different scaling factors.  The current version allows up to 5 significant
figures in scale factors limited in range from 0.0001 to 999999.  Future 
versions my have an exponential format available as well for factors
outside this range.

4/9/98 Changed alignment of data in tables within the parameter set
and other files.  Floating point numbers and enumerations are now LEFT 
aligned in table to be consistent with other field types.  Cosmetic 
change only.

4/15/98 Changed the algorithm for collecting TSRs.  It uses multi-TSR 
record collection in a way that is more efficient and more imune to line
noise.  KTOOLS and KDUMP now use the same retry algorithm.

4/21/98 Correct some misspellings in the message list files

4/21/98 V1.2.2 Released

5/21/98 Analog RTD type channels now make use of the scale and offset 
values in the parameter set.  Previous versions forced scale = 1.0 and
offset = 0.0.  Scale should still be 1.0 and offset 0.0 if you don't 
need to apply any corrections to the temperature data

5/21/98 The serial number from the reply packet is now displayed in the
communications window rather the serial number from the parameter set. This
allows you to dial up a site using serial number 0 (assuming there is
only one logger at the site) and read the correct serial number in the
communictions window.  You can then update the serial number in the Edit/
Logger Type form.  If you have single logger sites, AND you always 
configure the sites with the Write/ALL option, then you only need the
phone number and a copy of KTOOLS to communicate with the site.

5/21/98 V1.2.3 Released

5/22/98 Previous versions sometimes failed to write the logger's 
factor table due to a premature timeout for an expected logger response
packet within 2 seconds.  The timeout length for this command was 
extended to 4 seconds.  Other command timeouts were increased as well.

5/22/98 Added the Fast TSR data collection feature which complements the
strip chart recorder feature implemented in V1.2.1  Now you can collect
standard format TSRs every 12 seconds.  See the on-line help for more 
details.

5/22/98 V1.2.4 Released

7/1/98 Updated the autobaud function timing. Prior versions may have
done improper autobaud sequences to loggers resulting in failures to 
communicate with a logger after a modem connection.

7/1/98 Update the reinitialize timing.  Prior versions waited too long
after a reinitialization (50 seconds) rather than the required 20 seconds

7/1/98 Added another command line parameter -DEBUG.  If included on the 
command line, KTOOLS will create and append to POLLNN.LOG files where NN 
is the command number.  The log files will be appended with the contents
of the polling packets.  This is useful for communications debugging only.
Command line parameters must be preceeded with a '-' character can can be
either lower or upper case.

7/1/98 V1.2.5 Released

7/2/98 The Show Logger Status command now shows the status of all option
and logger status bits in english.  Prior versions only showed the options 
or status bits that were set with codes for the command status bits.

7/3/98 Prior versions had a problem when you switched the serial number
in the editor. The symptom was that it did not handle the control file
correctly.  When you change serial numbers, the old control file record
is checked back in, and a new record is opened with the new serial
serial number.  NOTE: you will have to edit the new control record since
information is not automatically copied from the previous record.  You
will also want to manually delete any old control records that no 
longer apply.

7/3/98 The control file is now sorted in order of ascending logger
serial numbers rather than by the name of the parameter set file.

7/3/98 Previous versions that timed out before making a modem connection
did not handle the modem correctly possibly leaving a modem connection
open.

7/3/09 Fixed a problem with the TSR collection routines that may have 
caused some indexing problems when collecting from TSR indexes above 32k or
when more that 127 simultaneous records will fit in a single 1500 byte 
transmitt buffer.  This is only the case for loggers with LOTS of memory
configured to collect just a few channels of data.

7/3/98 Added uniform 6 minute integration periods as a selection.

7/3/98 Added the RATE type to the digital channel form.

7/9/98 Fixed problem where the program was terminating incorrectly
in cases where there was no modem detected on the specified serial
port.  Prior versions may have crashed DOS on exit from the program
in these circumstances.

7/9/98 V1.2.6 Released

7/17/98 Fixed bug with Read TSRs command where the last record specified
in the get TSR range was not being collected.  KTOOLs was stopping one record
short of the specified end range.

7/17/98 Added output format specification to the Setup/Other and the 
Operations/Read TSR form.  You can now choose from exponential or fixed
floating point representations with or without the K20 TSR indicies printed
with the data.  The TSR flags field has now been changed to a quoted string
of characters rather than a string of characters or dashes.  This should
make it easier to import to spreadsheets.  The second floating point format
is compatible with older data collection software.  Both formats are now
supported by both KTOOLS and KDUMP

7/17/98 V1.2.7 Released

7/22/98 Updated the printing features of KTOOLS. Now when you are in the
KTOOLS editor screen and press the 'Print' button, KTOOLS does a system
command to copy the file to the printer (PRN: device).  This should 
result in more reliable printing when KTOOLS is hosted under Win95 or
WinNT.

7/23/98 Fixed problem with upward compatability of setup, control, and '
parameter files between versions.  Previous versions would report 'missing
fields' in the files without assigning default values to those fields.
Now, whenever you read an old file with a new version, you received a notice
about new fields in the format, and when you save the file, it's format is
automatically updated.

7/23/98 V1.2.8 Released

7/30/98 Various user response improvements.  A polling retry counter was
implemented to automatically retry commands and now the ESC works correctly
to cancel the polling retries.

7/30/98 Fixed a problem with the TSR read logic that was preventing KTOOLS 
from collecting TSR records if the logger clock did not get set properly.  
KTOOLS can now read records from any position in the TSR buffer regardless
if it has a valid timestamp or is a valid record, just as long as the
K20 has be configured with the parameter.  See the new online help material
for the Read TSR menu item.

7/30/98 V1.2.9 Released

8/6/98 A new file output option was added for cases where the ASCII file
config area of the recorder is blank.  If the program is started with the
-debug command line parameter, it produces the PARAM.BIN and TABLE.BIN files
by reading the parameter set area and factor table area of the logger.  These
files are in binary format and are useful for debugging only.

8/6/98 Added a reminder message to reset the logger's clock after a complete
reinitialize command is issued since the reinit also resets the real time 
clock.

8/6/98 Removed the commands to individually set the parameter set, factor
table, and ASCII upload area.  There is now a single 'Write Logger Config.'
command which does all three.

8/6/98 V1.2.10 Released

10/15/98 Added a Raw Binary as one of the output format options.  Now you
can collect unconverted TSRs from the K20 and write the data to disk.  This
is only useful for debugging purposes.

10/15/98 TSR header labels are now consistent with the View TSR structure 
report for both output formats.  The previous version had non-standard 
headers for the fixed decimal output format that was confusing.

10/15/98 V1.2.11 Released

10/27/98 Bug with the selection of Digital RunTime channels corrected. 
V1.2.6 through V1.2.11 did not allow setting the digital channels to 
collect run time information.

10/27/98 V1.2.12 Released

10/28/98 Bug with analog interlocks to digital channels corrected. 

10/28/98 V1.2.13 Released

1/27/99 COM3 and COM4 support was added.  These comm ports were in the pick
list of in the hardware setup, but were not supported by the low level 
serial communication library until version 1.3.0

1/27/99 V1.3.0 Released

2/1/99 Bug with TSR index fixed.  Prior verions reported the last TSR index
incorrectly on the TSR collection form.  The number was base 1 showing one
record too many.  TSRs in the K20 are stored with base 0 numbering from 0
to the LI (Last Index) number.  The symptom of this bug in prior versions
was continual wrapping of the data collection past the end of buffer.

2/1/99 V1.3.1 Released

4/21/99 Added a 'View It' button to the TSR collection form.  Now you can
view the TSR data file directly from the collection form using the KTOOLS
scrolling editor form or the 'Preferred Editor' specified on the Setup form.

5/19/99 Fixed bug with real-time display table that caused scaling errors 
if power aggregation channels did not correspond to one of the contributing
CT channels.  Also fixed scaling bug -- so all local displays are in kW with
a floating decimal point.

5/19/99 Added a command to clear the KWH/KVAH registers on the logger.

5/19/99 Other minor clean-ups and added documentation (TSR flag meaning)

5/24/99 Added support for older C180 style data loggers as an explicit 
data logger type.  These loggers represent a smaller sub-set of the K20
features but are fully supported with their own parameter set editor 
screens, real-time data reads, TSR data collection, and strip-chart 
recording.  Older C180s:
1) No kWh or kVAh channels
2) No analog channel interlocks
3) No 16 character parameter set descriptor string 
4) No fast TSR mode
If you try to use one of these features, KTOOLS will give you a message
that the feature is unsupported for the particular logger type selected.

5/25/99 V1.3.2 Released

1/3/00  Fixed clock comparison Y2K bug.  Symptom is that clock comparisons
off by 100 years on dialup.

1/3/00 V1.3.3 Released

2/23/00 Fixed the problem with older C180 digital channels TSR readings
being off by a factor of 16.  Older C180 equipment used an FFP format to
store digital channel readings.  When the C180e was introduced, this was
changed to a simpler 16 bit accumulator.

2/23/01 V1.3.4 Released

8/17/01 Fixed problem with older C180 power channels that were not 
referencing voltage channel C


