/*
	+--------------------------------------------------

		WPS character stream / paper tape file format
				
			--------------------------------------------------+


Tom Jennings
mru 3 Mar 1999
Added A and X types, cleaned language. Tightened control char definitions. Completed ASCII chart.

new 17 Feb 1999

________________________________________________________________________________________

1.0	Link
1.1	Signals
1.3	Transmit character state machine
1.4	Electrical
2.0	Streams
2.1	Definitions
3.0	Control code functions
3.1	Defined record types
3.2	Table of ASCII characters

________________________________________________________________________________________

#1.0 LINK
A subset of RS-232 is assumed. 

#1.1 SIGNALS
Signals supported:

	(SOURCE)						(LOAD)
	DCE 			pin		pin		DTE
	Transmit data	TxD	2	-->	2	RxD	Receive data
	Receive data	RxD	3	<--	3	TxD	Transmit data
	Request to Send	RTS	5	<--	5	CTS	Clear to Send
      *	Data Term. Rdy	DSR	20	<--	20	DTR	Data Terminal Ready
	Signal ground		7	---	7		Signal ground


* Not supported on some devices; if DCE cares, it should pull up lightly, allow driving DTE device
to pull down.



#1.3 TRANSMIT CHARACTER, DCE to DTE


		DSR true ------------+--> RTS true --------> output TxD
	       false		     |   false
		 |		     |     |
		 |		     +-----+
		 V
	       ERROR



#1.4 ELECTRICAL

With PICs driving the signals, voltage levels are:

	MARKING		0V	"1"		Line resting state
	SPACING		+5V	"0"		Asynchronous start

Most assuredly line length and noise margins are for shit. This assumes all cables are "short".

PIC output pins should have 100 ohms in series.
PIC input pins should have 10K in series, and 100K to ground (avoids flapping signals).

Note that Win9x serial drivers don't support CTS/RTS properly.



________________________________________________________________________________________
#2.0 STREAM

Pure ASCII character serial data stream formats for WPS devices and systems, to allow
interchangability amongst the many devices, and allow mixed data types in a single 
stream or especially on paper tape.


The general format is:

	fill [record-type {data-record} {data-record} ... terminator] fill


ASCII NUL characters have a special absolute meaning; they always indicate "ground", or no-data.
Reception of a NUL at any time should cause the receiving program to terminate any process running,
and await the start of another record, if appropriate. NUL generation is not synchronous with
any state.

One or more NULs may be generated by any data-generating or pass-through device, for any reason;
tape ran out, operator abort, cable unplugged, other error, etc. Any number of NUL characters
at any rate may be generated (eg. single NUL or contiguous stream until the error condition is removed).

NULs may be used as a line keep-alive.



________________________________________________________________________________________
#2.1 DEFINITIONS:

Fill, Line fill:
	Any number of NULL characters outside of a file, specifically before the SOH or
	after the EOT. A NUL at any other time indicates a protocol error.

File:
	The entire contents of a paper tape or character stream.

Record type:
	SOH followed by a single ASCII character A-Z or a-z that indicates the type of 
	data records that follow.

Record:
	The data structure from the initial SOH to the terminating EOT, inclusive.

Data record:
	the subset of a character stream starting with an STX and ending with ETX. The type of
	data is determined by the file type.

Data:
	The ASCII character stream immediately following the STX and preceding the ETX. Only
	LINK, LINE and RECORD control characters, the printable characters, and DEL are allowed.
	The STREAM control characters are specifically not 

Terminator:
	ASCII EOT.


Example:

	NUL..NUL SOH type     STX data ETX    STX data ETX    [...]      EOT NUL..NUL
	[  1  ]  [2] [3]      [4] [5]  [6]    [4] [5]  [6]    [4, 5, 6]  [7]  [   1   ]

1.	Fill.
2, 3.	File type.
4.	Indicates start of text (data).(note 1)
5.	Any number of ASCII characters in the range 
6.	End of text. (note 2)
7.	End of file.

	...NUL NUL NUL SOH T STX "this is the title" ETX EOT NUL NUL NUL...
	...NUL NUL NUL SOH P STX *$$*$*@!)#(*$$)$(*$)(*023HJK$KJH@ ETX EOT NUL NUL NUL...
	...NUL NUL NUL SOH X STX 1201010102020203030300440822222020 ETX EOT NUL NUL NUL...




NOTES:
1. Use of STX/ETX allows for compatibly inserting additional data after the file-type, such as
filename. RESERVED.
2. Additional characters may appear between data records (eg. between ETX/STX) in the future.



________________________________________________________________________________________

#3.0 CONTROL CODE FUNCTIONS AND DEFINITIONS

PROTOCOL characters are reserved for stream operations, and can't appear in a data record.

	value		function	status
	0-6		STREAM		PROTOCOL	character stream protocol
	7-15		FORMAT		allowed		forms control, audible bell
	16-23		LINK		PROTOCOL	link-level control, eg. flow control
	24-31		LINE		allowed		considered end-user data

*/




/* 
#3.1 DEFINED RECORD TYPES */

#define ATYPE ('A')	/* ASCII text */
#define PTYPE ('P')	/* Phoneme (story teller) */
#define TTYPE ('T')	/* title (paper tape human-readable header) */
#define XTYPE ('X')	/* XYZ data (motion command output from Postscript) */

*/


/* 
#3.2 Standard ASCII control codes P=Protocol (reserved) -=Data (end-user data) */

/*	0x00					0x20		0x40		0x60 */
#define NUL  0	/* P null 		       sp 32		@ 64		`  96 */
#define SOH  1	/* P start of header 		! 33		A 65		a  97 */
#define STX  2	/* P start of text 		" 34		B 66		b  98 */
#define ETX  3	/* P end of text		# 35		C 67		c  99 */
#define EOT  4	/* P end of tape (record)	$ 36		D 68		d 100 */
#define ENQ  5	/* P enquire 			% 37		E 69		e 101 */
#define ACK  6	/* P acknowledge (positive)	& 38		F 70		f 102 */
#define BEL  7	/* - bell 			' 39		G 71		g 103 */
#define BS   8	/* P backspace 			( 40		H 72		h 104 */
#define HT   9	/* - horizontal tab		) 41		I 73		i 105 */
#define LF  10	/* - line feed (newline)	* 42		J 74		j 106 */
#define VT  11	/* - vertical tab 		+ 43		K 75		k 107 */
#define FF  12	/* - form feed 			, 44		L 76		l 108 */
#define CR  13	/* - carriage return 		- 45		M 77		m 109 */
#define SO  14	/* - shift out 			. 46		N 78		n 110 */
#define SI  15	/* - shift in 			/ 47		O 79		o 111 */
#define DLE 16	/* P device something enable 	0 48		P 80		p 112 */
#define DC1 17	/* P device control 1, aka XON	1 49		Q 81		q 113 */
#define DC2 18	/* P device control 2 		2 50		R 82		r 114 */
#define DC3 19	/* P device control 3, aka XOF 	3 51		S 83		s 115 */
#define DC4 20	/* P device control 4 		4 52		T 84		t 116 */
#define NAK 21	/* P acknowledgement (negative)	5 53		U 85		u 117 */
#define SYN 22	/* P I forget 			6 54		V 86		v 118 */
#define ETB 23	/* P I forget 			7 55		W 87		w 119 */
#define CAN 24	/* - cancel 			8 56		X 88		x 120 */
#define EM  25	/* - I never knew 		9 57		Y 89		y 121 */
#define SUB 26	/* - substitute 		: 58		Z 90		z 122 */
#define ESC 27	/* - escape 			; 59		[ 91		{ 123 */
#define FS  28	/* - I never knew 		< 60		\ 92		| 124 */
#define GS  29	/* - I never knew 		= 61		] 93		} 125 */
#define RS  30	/* - I never knew 		> 62		^ 94		~ 126 */
#define US  31	/* - I never knew 		? 63		_ 95	      del 127 */
/*	  0x1f					0x3f		0x5f		 0x7f */