***************************************************************
	
        README.TXT TPS for Windows 2018

	Updated as of 21/10/2018 V5.03a

		** PLEASE READ ME FIRST **
	
	Email: info@microscitech.com

	TPS Copyright Micro SciTech Ltd. 1991-2018
***************************************************************

This is a free Version of TPS for Windows last formally developed and tested in 2009 under Windows XP, service pack 3.

Some limited testing on Windows 7 has also been performed, and it also seems to run on Windows 10, albeit it has not been tested other than checking the executable starts and displays its default screen page.

Suffice to note, it has been successfully used in several space, industrial and academic applications prior to 2010, most notably in the 1990s when both the European and US space agencies used it in a couple of projects.

As the product has ceased formal development for many years, it has been decided to release the application free to the public. Note that this free offer does not include the Application Programmers Interface (API). Please enquire further to sales@microscitech.com if interested in the API.

Micro SciTech will attempt to provide some limited support but reserve the right to withdraw or refuse support at any time.

The product is not available for resale.

----------
Disclaimer
----------

This product is supplied free, as is, without warranty.

Micro SciTech Ltd. do not accept any liability for its use.

Use of the product is entirely at the user's own risk.

Security is the user's responsibility.

TPS has the ability to receive and send data across the internet via TCPIP and UDP and therefore the users must be aware of all internet security issues  should they openly use it on the internet. Such usage is not recommended and all networks on which TPS runs should be local, 'intranet's (or 'LANS'), with a firewall preventing any inadvertent access to the internet.

There is no encryption on data transmission or receive.

Use of the product is acceptance of the disclaimer.

------------
Installation
------------

Installation is a straightforward unzip, file copying operation to the folder of your choice, e.g. C:\TPSOPEN or C:\TPSDIST, but it can be any folder on any suitable drive, e.g. D:\TEST\TPSOPEN. The executable is TPSOPEN.EXE, (but the distribution product is zipped in folder TPSDIST), just double-click it to start it up, once unzipped.

Once started, and having clicked OK to accept the disclaimer, you will see the default display page 10. Try the online help (menu item Help, TPS Help), or see the DOCS sub-folder. Just to get a very quick feel for the product, set test data running by selecting menu item Transfer, Test Data.

The online help, literature in the DOCS sub-folder, and sample displays and data in the SAMPLES sub-folder should be enough to get you started. We can offer some email support - email info@microscitech.com.

Multiple installations

You may also install to multiple different folders on the same PC. Multiple TPS installations will run simultaneously without problem, but you should ensure they each have their own folder, just to avoid file write conflicts, i.e. when two or more users write (save) to the same files, as can happen when editing the same page in the same folder simultaneously. Likewise, I/O conficts may occur if two or more versions write to the same output ports.

Installing over older installations

If you already have a TPS installation, you will need to recompile all your pages. The text pages PAGE*.TXT should be compatible and should compile with the 2018 compiler PGCKW.EXE. If not (currently no known cases), then the error message should indicate the failing line. Otherwise, providing TPS is reconfigured for legacy data, i.e. packet sync, length etc., then legacy packet data should be read ok, as before, in any of the existing formats - raw binary, ASCII hex, or compressed binary.

------------
File Content
------------

The ZIP file contains the following files:

README.TXT   - This README file.
TPSOPEN.EXE  - the executable TPS application
PGCKW.EXE    - the display page compiler (an offline, command line tool)
TPSOPEN.HLP  - the online help file (may also be read offline outside TPS)
CKALLPGS.EXE - a version of PGCKW.EXE to compile all pages at once
PAGE0000.TXT - system display page 0, source file
PAGE0010.TXT - default display page 10, source file
PAGE9998.TXT - examples display page 9998, source file
PAGE0000.TXT - system display page 9999, source file

PAGE0000.BIN - system display page 0, compiled binary file using PGCKw.EXE
PAGE0010.BIN - default display page 10, compiled binary file using PGCKw.EXE
PAGE9998.BIN - examples display page 9998, compiled binary file using PGCKw.EXE
PAGE0000.BIN - system display page 9999, compiled binary file using PGCKw.EXE

\DOCS - numerous short documents for quick reference and supplement the online help. Also includes the offline TOOLKIT User Guide.

\SAMPLES - Numerous display page examples and some example packet data for replay - See the README.TXT in this SAMPLES folder.

----------------------------------
C Application Progrmmers Interface
----------------------------------

The C programmers TPS API is available upon formal request to MST.

Following the release of TPS's V5.0 for Networks, the product was upgraded to process variable length packets (Version 5.02a). The  documentation supplied with this product does not include this feature, other than that information given further below, to which readers are referred.

---------------
DOCUMENTATATION
---------------

Online Help File (menu item HELP)

The online help is the major source of information and acts as a user guide. However, there are more documents in the \DOCS sub-folder. See the README.TXT in this folder for more information.

Note that the the online help feature does not appear to work on Windows 10, albeit Windows XP and Windows 7 appear ok. Windows 10 appears to access the web for .HLP files. This Windows 10 matter is currently under investigation.

Offline Help documents in \HELP2018 sub-folder

To supplement any online help deficiencies, the help files are supplied in rich text format (file extension '.RTF'), which can be read using Microsoft Word et al.

Offline PDF documents

More documents can be found in the \DOCS and \DOCS\V501998 sub-folders.

----------
Windows 10
----------

Some noted Windows 10 limitations

Online help does not appear to work - Windows insists on going to the Web, see above.

Screen resizing on Windows 10 appears problematic. In particular, the screen may be only resized once, and then appear to block any further resizing, albeit minimise and maximise work ok. Exiting TPS will clear the problem. Deleting the file tpsvid.cfg will also reset TPS to its default display size. We suggest you always use TPS in maximised screen mode given modern hardware goes above 1924 x 1024 pixels and beyond.

Note that nearly all display pages have been developed for much smaller screens, starting with DOS 80x25 command window in 1991. The default TPS home page 10 was enlarged in 1998, but it is still smaller than the currnet maximum size of 200 columns by 80 rows (1600 x 960 pixels).

----------------
V5.0 TPS Network
----------------

TPS Version 5.0 is the first version of TPS to facilitate the exchange of data between PCs across an ethernet local area network or globally across the Internet using TCPIP or UDP protocols.

Please see the Installation and Release Notes for details on proceeding with TPS in the \DOCS\V501998 sub-folder.

!! IMPORTANT !!

RS232 Serial I/O

Up to 1996, RS232 serial I/O communications, via the PCs 'COM' ports, i.e. COM1, COM" etc., was the main form of wired communications, and TCPIP/UDP, i.e. ethernet communications, was added for 1997 and 1998. As such, much of the older documentation assumes serial communications rather than ethernet.

Samples
-------

See the README.TXT file in the Samples folder for all details.


Version 5.02a Variable Length Packet Processing
-----------------------------------------------

This special version comes pre-configured to handle variable length telemetry packets according to the ESA PSS-104-06 specification.

Before reading any packets - you must set the TPS sync to recognise the first two bytes of the packet (the Application ID) to match those of the packet. To do this, select the Transfer, Pkt format menu item and modify the sync accordingly. DO NOT change the length from 0 - this is a new setting which effectively tells TPS that the incoming data is variable length. See the notes below for some general details:

Once the sync (Application Id) is configured, TPS is ready to read PSS variable length packets - simply replay the data as for standard fixed length packets.

See Page 34 on the Samples disk for CCSDS packet header displays - all bit fields extracted.

Page 10 (and every page), now shows (top left) a blue-background view-port with mnemonic 'Total_Packet_Length'. This will read '7' when first starting TPS, after a PSS packet is replayed, it will show the packet length as extracted from the current packet.

Although this special V5.02a TPS has been pre-configured to read PSS packets, it can read any form of variable length packet by online re-configuration. This configuration information is not available as yet, please contact Micro SciTech from May 18th 1998 onwards for further information.

Some general information is given below which may help.

General Information
-------------------

TPS reads variable length packets by determining the packet length as each packet is read. The packet length is extracted from a view-port which, normally, the user must configure. (Because this special version 5.02a is pre-configured for PSS, a view-port has already been added to page 9999 - this ensures it is displayed on EVERY page).

The view-port must display the packet parameter showing the variable length information. For PSS, this is a 16-bit (short integer) starting at byteindex 4, the m.s.byte is at byte 4 and the l.s.byte is at byteindex 5. TPS reads a packet by reading all the bytes up to and including the packet parameter showing the total length. For PSS packets, TPS first reads 6 bytes (the entire header) - the last two bytes being the length of the data which follows it in the packet. It will extract this length value and add an offset, as explained following, to determine the complete packet length.

The variable length packet parameter should actually display the total packet length, not just the number of bytes which follow in the remainder of the packet so, invariably, you must configure your view-port with a polynomial to add an offset to account for the number of bytes already read.

For PSS, this is fixed at 6 for the 6-byte header. However, since the length information is actually reduced by 1, e.g. it has a value of 127 if 128 bytes follow the 6-byte header, you must also add an additional 1 to the 6 figure. Thus, the total packet length, as displayed in the view-port, has an offset of 7 added to it (poly coefficient a0 = 7).

Once a view-port is configured, you must then configure the TPS packet format to now recognise this view-port as supplying the length information - use the Transfer, Pkt format menu item.

The Transfer, Pkt format menu item pops up a dialog box showing the packet sync and length - set the length to 0.This informs TPS that the packets do not have a predefined length. Immediately a value of 0 is entered for the length,
a list box appears showing selected parameters on the current page or page 9999. From this list, you select that view-port pre-configured to display the packet length.

It is best to have this view-port properly configured when selecting the parameter because you will not be able to edit it thereafter, unless you set the packet length back to a fixed, non zero value (any non-zero length will do).

Because view-ports are page specific, it might seem that every page must display the view-port or TPS will not be able to read the packet. In fact, if you add the view-port to system page 9999 (done offline), it need only be configured once and will then appear on every page. For PSS, this has already been done. If you inspect the page text file PAGE9999.TXT, you will see a block of text at the end
as follows:

[valueport]
	enable = no
	databasekey = "Total_Packet_Length"
	view = packetheader
	byteindex = 4
	datatype = "%hu"
	row = 1
	column = 1
	mnemonic = "Total_Packet_Length"
	displayrate = "F01ST01"
	backgroundcolor = blue
	bordercolor = white
	titlecolor = white
	valuecolor = yellow
	border = off
	varpktlen = on
	[calibration]
		function = polynomial
		[polynomial]
			function = integerbyteswap
			a4 = 0
			a3 = 0
			a2 = 0
			a1 = 1
			a0 = 7

* IMPORTANT *
 To use this, you must re-enable this viewport by  changing the line 'enable = no' to 'enable = yes'.  Alternatively, you can simply delete the line. This was generated as follows (overview only):

ONLINE generation of a view-port 'Total_Packet_length'
 on a test page. This view-port showing the total PSS
 packet length  (see line a0 = 7 which adds the 7-byte
 offset as mentioned above).

 In fact, this was a modified version of the view-port
 'source_Packet_Length' found on CCSDS packet page 34
 on the Samples disk.

Save the test page.

OFFLINE, using a text editor, copy the view-port
 specification to PAGE9999.TXT and then delete the text
 from the test page.

OFFLINE recompilation of the test page and page9999 to generate
 PAGE9999.BIN - which is read by TPS when first starting TPS.

For full details on offline page configuration, see
the manual 'PGCKW and Offline Configuration' - supplied
in Word 6 format as PGCKW.DOC, or MS Write format PGCKW.WRI on
the documentation disk. Note, you will have to expand the
document first - details given in the README.TXT file also
on the doucmentation disk.


Whre to find information on packet format configuration
state of TPS...

Several sources:

1) Select Transfer, Newtork Menu item

	Shows packet sync and length

2) Every page

	Top left, blue-background view-port

	Total_Packet_Length'

	This will show '7' when first starting TPS,
	after a PSS packet is replayed, it will
	show the packet length as extracted
	from the current packet.

3) Page 10
	Above hex pkt dump on left are two view-ports:

	PKTSYNC	    packet sync (PSS app. Id)
	PKTLENGTH = 0 variable length pkts
		  = non-zero fixed length pkts (shows
		    fixed length pkt size).

	Var_Pkt_Length

	See the grey background block, headed
	'General' to find this parameter - it is at the foot of the
	block. The grey block shows various TPS configuration state
	including this new variable packet length ON/OFF state.
	When using fixed length packets, i.e. a non-zero length
	value in the packet format dialog box, 'Var_pkt_length'
	shows the OFF state. It shows ON when the packet length
	is variable, i.e. the packet format dialog box
	shows a packet length of 0. 


4) See Page 34 on the Samples disk for CCSDS packet header
displays - all bit fields extracted.

5) Select Options, Info menu item and press the 'Var. Pkt Length' button. When using variable length pkts, this will tell you which mnemonic (parameter, view-port) is being used to retrieve the
length information.


-----------
Telecommand
-----------

The telecommands tce and tcs, which send telecommands to the dispatcher, for output to the ethernet and serial ports respectively, will not generate an immediate error if the network or serial output is not enabled, and it will appear to work ok, even if they are closed. However, it is the telecommand 'dispatcher' that will generate an error, with the error message appearing in the 'TCD>' message bar toward the bottom left on page 10.

------------------------
Online Help Corrrections
------------------------

Telecommand information on 'page 14' is now page 10, with 'Telecommand Output' shown at the bottom of the display area. The two view-ports 'TCP>' and 'TCD>' start on the far left.

-------------------
Miscellaneous Notes
-------------------

The Current working folder

Both TPS and PGCKW default to opening files in the folder that was last accessed by the user within TPS, known as the current folder. E.g, if you open a page in another folder, say SAMPLES, TPS will go to that folder the next time any page is opened or, indeed, any file or parameter recorded and, more gnerally, any operation that presents the user with a dialog box allowing them to change folders. This is also true even after exiting TPS. When restarted, it will remember the current folder upon exit, and default to that when restarting and opening files. This action is controlled by Windows, and not TPS. TPS does not keep a record of the current folder when exiting.

Windows 10. Screen resizing problems have been reported in so far as after a few resizes, it may no longer allow resizing. It is not knwon whether this is a driver problem related to the machine, or a Windows OS problem. It does not occur on Windows 7 and earlier, e.g. XP. Exiting and re-entering TPS will cure the problem but, of course, it means you have to disrupt operation. Maximising the screen still works, but restoring to its original size then returns the problem. In fact, maximising the screen does not allow the user to change the size, thereafter, other than toggling the maximise so that it returns to its oringal size, pre-maximise.

--------------------------------------------------------------------------------
01234567890123456789012345678901234567890123456789012345678901234567890123456789
         1         2         3         4         5         6         7         8
