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