*******************************************************************************
*                                                                             *
*	X2REG  -  Control program for X-tal doubler regulator		      *
*                                                                             *
*******************************************************************************
*                                                                             *
*	(C) Copyright 1988, 1989 by Rijksuniversiteit Leiden                  *
*                                                                             *
*                                                                             *
*	Assembler        : X6805                                              *
*	Hardware system  : PC                                                 *
*       Operating system : MS-DOS                                             *
*                                                                             *
*       Version : 0.15                                                        *
*       Date    : 4 Mar 1996                                                  *
*       Disk    : X2-REG                                                      *
*                                                                             *
*******************************************************************************
*                                                                             *
*	Description                                                           *
*       -----------                                                           *
*                                                                             *
*       This is the program for the X-tal doubler regulator                   *
*                                                                             *
*       The aim is to stabilize the X-tal temperature and to  keep            *
*       the desired temperature  changes  within  a  predetermined            *
*       rate of change ('C/minute).                                           *
*                                                                             *
*       The regulator consists of a MC68705R3 single chip computer            *
*       with  three  thumbwheel switches, a  Pt100-inputcircuit, a            *
*       quad 8-bit DAC  and  three error LED's.   The  thumbwheels            *
*       determine the doubler X-tals final temperature.  The regu-            *
*       lator  setvalue   (temperature)  is  periodically   incre-            *
*       mented or decremented until it reaches the temperature  as            *
*       indicated  by  the  thumbwheel switches.   At  RESET,  the            *
*       set-value   is  made  equal  to  the  current  Pt100-value            *
*       (temperature),   so  regulation  starts  at  the   current            *
*       temperature of the X-tal.                                             *
*                                                                             *
*       Thus a slow change of X-tal temperature is attained.                  *
*                                                                             *
*       Further the regulator gain and integrationtime are adjustab-          *
*       le by means of a potentiometer.                                       *
*                                                                             *
*******************************************************************************

	SUBTITLE [ x2reg.history ]		Version's history
	PAGE
*******************************************************************************
*                                                                             *
*   Versions history:                                                         *
*                                                                             *
*   X2REG  V 0.00  	Setup of program                                      *
*   X2REG  V 0.10  	Adaption to actual hardware setup                     *
*                                                                             *
*   X2REG  V 0.11	Problem:  when the connector to the heater-mount      *
*                                 is inserted while the rack is already on,   *
*                                 the regulator starts regulating at the      *
*                                 maximum temperature.                        *
*			Solution: after a hardware error occurred and         *
*                                 disappeared,the regulator is re-initialized,*
*                                 so the temperature setvalue is set to the   *
*                                 current Pt100 temperature again and the     *
*                                 regulator starts regulating at the current  *
*                                 temperature.                                *
*									      *
*   X2REG  V 0.12       Problem:  irregular repeating restarts of regulation  *
*                       Cause  :  incidently, Error $01 appears during runtime*
*                                 causing a regulator restart.                *
*                       Solution: increase acceptation windows for ADC test   *
*                                                                             *
*   X2REG  V 0.13       Problem:  same as above,                              *
*                       Cause  :  same as above,                              *
*                       Solution: same as above: 7E -> 7D, 01 -> 02           *
*                                                                             *
*   X2REG  V 0.14       Problem:  what is `it' doing?,                        *
*                       Cause  :  no indication,                              *
*                       Solution: LED0 blinks while destination temperature   *
*                                 not yet reached.                            *
*                                                                             *
*   X2REG  V 0.15       Problem:  starting regulating from 20'C,              *
*                       Cause  :  <= 20'C is handled as shorted sensor,       *
*                       Solution: lower lowest temperature to 10'C            *
*                                                                             *
*******************************************************************************

	SUBTITLE [ x2reg.spec ]				System specification
	PAGE
*******************************************************************************
*
*
*	System specification
*	====================
*	
*
*	Inputs
*	------
*	
*	o Thumbwheel 
*	  . 4 bit input                               ( TWX_PRT )
*	  . 2 bit multiplexer selection signal        ( TWS_PRT )
*	  . Range: 0..999
*	  . Error: 0..19, 121..999
*	
*	o Regulator error signal
*	  . 1 line analog input                       ( RES_PRT )
*	  . Range: -128..+127
*	
*	o Regulator PTC signal
*	  . 1 line analog input                       ( PTC_PRT )
*	  . Range: 0..255 <=> 20..120 'C 
*	
*	o Regulator gain adjust signal
*	  . 1 line analog input                       ( RGA_PRT )
*	  . Range: 0..255 <=> 0..255/GAINMAX times
*	
*	o Regulator integrationtime adjust signal
*	  . 1 line analog input                       ( RIA_PRT )
*	  . Range: 0..255 <=> TINTMAX/0..255 [s]
*	  
*	
*	Outputs
*	-------
*	
*	o LED's
*	  . ready                                  (      VSET )
*	  . no lock                                ( >  TALARM )
*	  . invalid                  ( < TTMBMIN ) ( > TTMBMAX )
*	
*	o DAC for reference signal and regulator output signal
*	  . 8 bit dataport                           ( DDA_PRT )
*	  . 2 bit selection signals                  ( DAD_PRT )
*	  . 1 bit read/write signal                  ( DWR_PRT )
*	
*	o Testpin for foreground program
*	  . 1 bit output                             ( TPF_PRT )
*	
*	o Testpin for background program
*	  . 1 bit output                             ( TPB_PRT )
*	
*	o Serial communication line		     ( SER_PRT )
*	  . 1 bit output
*
*******************************************************************************

	SUBTITLE [ x2reg.dsgn ]				Program design
	PAGE
*******************************************************************************
*	
*
*	Program design
*	==============
*	
*
*	o User stack
*	
*	This module  creates an user stack for the MC68705  single 
*	chip   microcomputer.   It  simulates   some   MC6802-like 
*	instructions (LDS, STS, TSX, TXS, DECS, INCS, PSHA,  PULA) 
*	and  provides  a couple of extra instructions  like:  TSA, 
*	TAS, PSHX, PULX, PSHAX, PULAX.
*	Some basic differences exist between the MC6802 stack  and 
*	the MC68705 user stack: 
*	- the user stackpointer is only 8-bits wide
*	- the user stackpointer points to the last pushed item
*	- the  user  stackpointer  exists in RAM, not  in  a  real 
*	  register
*	- the user stackpointer must be initialized (INISTK).
*	
*
*	o Runtime test facility
*	
*	Two testpins configured as output are available for  test-
*	purposes.   One  pin  is used to track  execution  of  the 
*	foreground  program  (TPF) and one pin is  used  to  track 
*	execution  of the background program (TPB). There are  two 
*	macro's  for  each pin to set (SETTPF,  SETTPB)  or  clear 
*	(CLRTPF,  CLRTPB)  it.  Place these macro's  anywhere  you 
*	like to test execution of the program.
*	
*
*	o Initialize
*	
*	This  module contains all code to initialize  the  system.  
*	It executes as follows:
*	- clear RAM
*	- set input/output lines direction
*       - blink LED's three times (600 ms)
*	- perform hardware test
*	- initialize stack-module
*	- initialize interrupt-module
*	- initialize error-module
*	- wait for PTC-inputcircuit to stabilize (400 ms)
*	- initialize regulator-module
*	- enables interrupt
*	
*
*	o Hardware test
*
*	Thió  modulå testó (parô of© thå interfacå  hardware®   Iô
*	testó  thå ADÃ anä voltagå-reference¬ thå PTÃ  connection¬ 
*	thå  erroò-amplifieò  anä  referencå  DAÃ  anä  thå  threå 
*	thumbwheels.
*	
*
*	o Serial interface
*
*	This module contains the routines to write a character  to 
*	the terminal and to print a number of 1, 2 or 3 bytes long 
*	in hexadecimal format.  Printing of strings is handled  by 
*	the fstser-routine of the fast process. 
*
*
*	o Hardware
*	
*	This  module contains the low-level routines to  read  the 
*	three thumbwheels and the four ADC-channels and to control 
*	the quad DAC and the three LED's.
*	
*
	PAGE
*	o Input/output
*	
*	This  module  forms  the  system-level  interface  to  the 
*	hardware-module.
*	
*	It contains the following routines to read:
*	- triple-thumbwheel setting
*	- regulator gain-adjust value
*	- regulator integrationtime-adjust value
*	- regulator errorsignal
*	- PTC-value
*	
*	and to control:
*	- regulator output DAC
*	- regulator reference DAC
*	
*
*	o Miscellaneous
*	
*	This  module contains the start-up code (blink LED's three 
*	times) and code to control the error-status flag.
*	
*
*	o Regulate
*	
*	This   module  contains  a  routine  to   initialize   the 
*	regulator,  a routine that forms a P-regulator, a  routine 
*	that  forms a PI-regulator and a routine to clamp a  value 
*	on  the user-stack to a certain maximum or minimum  value.  
*	The   PI-regulator  algorithm  prevents  oveflow  of   the 
*	integrator.  The P-regulator algorithm is selected if the 
*	integrationtime-adjust setting is zero volt, otherwise the 
*	PI-regulator algorithm is selected.  This property can  be 
*	used to calibrate the regulator gain parameter.
*	
*
*	o Main control
*
*	The main control module features six processes in a  loop.  
*	One process for the regulator computations, one process to 
*	determine  the current regulator setvalue, one to  service 
*	all  hardware input/output, a process  for  second-related 
*	actions, one for minute-related actions and a process  for 
*	hour-related  actions.    The hardware  i/o  process  also 
*	handles  the error-status.  Each process is controlled  by 
*	it's own timer.  The timing is provided by the  interrupt-
*	module. Communication between the interrupt-module and the 
*	six processes is done via process-bound mailboxes.
*
*
*	o Interrupt
*	
*	The interrupt-module contains a routine to initialize  the 
*	interrupt system, a routine to service the external inter-
*	rupt  and a routine to service the  timer-interrupt.   The 
*	external interrupt is used to select a calibration-routine 
*	to  calibrate  the PTC amplifier offset  and  gain.   This 
*	routine copies the thumbwheel setting after scaling to the 
*	reference DAC.  The timer-interrupt manages the timing for 
*	the six processes mentioned above.
*	
*
*	o Math
*	
*	This  module contains routines to add, subtract,  multiply 
*	and  devide (div and mod) for both 2-byte integers and  3-
*	byte  integers.  Further it contains routines  to  convert 
*	between  (un)signed character data and  (un)signed  2-byte 
*	integer  data and between 2-byte integer data  and  3-byte 
*	integer data.
*	
*
*	o PTC-conversiontable
*
*	This table contains the PTC temperature to voltage charac-
*	teristic in a normalized form:
*	- temperature: 0..$ff, 256 entries
*	- voltage    : 0..$ff, size of entry is one byte.
*	The  table is used to convert the setvalue temperature  to 
*	setvalue output voltage (function PUTREF).
*
*******************************************************************************

	SUBTITLE [ x2reg.sys ]				System Guide
*	PAGE
*******************************************************************************
*
*
*	System guide
*	============
*	
*
*	o Configuration
*	
*	In order to adapt the X2reg progam to your hardware  the 
*	following constants can be changed:
*
*	- Tsample [100 ms]: sample time                           *) ( 1..512 )
*	- Gainmax [      ]: maximum regulator gain value             ( 1..256 )
*	- Tintmax [    s ]: maximum regulator integrationtime        ( 1..256 )
*	- Timset  [    s ]: time between 1'C change of               ( 1..255 )
*	                    regulator setvalue
*	- Talarm  [    C ]: alarm if abs(Tptc-Tset) > Talarm 'C      ( 0..127 )
*	- Ttmbmax [    C ]: maximum allowed thumbwheel setting       ( 0..2^16)
*	- Ttmbmin [    C ]: minimum allowed thumbwheel setting       ( 0..2^16)
*
*	- Enable_setprs   : 1. regulator setvalue changes slowly
*	                    0. regulator setvalue = thumbwheel setvalue
*
*       *) Tsample,max is ca. 0.2 x Tintmax
*
*
*	o Expansion
*
*	The  process in the main loop for hour-related actions  is 
*	free to use for future expansion.
*
*******************************************************************************

	SUBTITLE [ x2reg.usr ]				User Guide
	PAGE
*******************************************************************************
*
*
*	User guide
*	==========
*	
*
*	o Calibration
*	
*	PTC-amplifier
*	-------------
*	To calibrate the PTC-amplifier offset and gain do the 
*	following:
*	
*	- apply jumper to IRQ-jumper 
*	  ( this selects the calibration routine )
*	
*	- apply a known low temperature to PTC
*	- set thumbwheels to this temperature
*	- measure errorvoltage  ( tp5 - tp4 )
*	- calibrate PTC-amplifier offset to get zero errorvoltage
*	
*	- apply a known high temperature to PTC
*	- set thumbwheels to this temperature
*	- measure errorvoltage  ( tp5 - tp4 )
*	- calibrate PTC-amplifier gain to get zero errorvoltage
*	
*	- remove IRQ-jumper
*	
*
*	Regulator
*	---------
*	To calibrate the regulator gain and integrationtime do the 
*	following:
*	
*	- set integrationtime-adjust to 0 [V] ( Testpoint tp3 )
*	  ( this selects the P-regulator algorithm )
*	- find gain-adjust setting that gives a response to a 
*	  temperature step without overshoot
*	  ( Utp2 = gain / GAINMAX * 5  [V] )
*	- set integrationtime-adjust setting to the system time-
*	  constant (tau)
*	  ( Utp3 = tau / TINTMAX *  5  [s / s * V] = [V] )
*	
*
*	
*	o Normal usage
*	
*	For normal usage note the following:
*	
*	- jumper in IRQ-jumper removed
*	- thumbwheel setting in accordance with the desired final 
*	  temperature
*	- regulator gain-adjust setting (potmeter) in accordance 
*	  with the desired gain
*	- regulator integrationtime-adjust (potmeter) in accordance
*	  with the desired integrationtime
*	
*******************************************************************************

*------------------------------------------------------------------------------
*  End of X2REG.DES
*------------------------------------------------------------------------------


	SUBTITLE	[ x2reg.cfg ]			Hardware configuration
	PAGE
*------------------------------------  M O D U L E   hardware configuration ---
*
*  Module hardware configuration
*
*
*  Version: 0.01
*  Date   : 22 Mar 1989
*
*------------------------------------------------------------------------------
*
*  Routines in this module:
*
*  - none
*
*------------------------------------------------------------------------------

*------------------------------------------------------------------------------
*
*  Front layout
*  ------------
*
*
*	+---------------------------+
*	|                           |
*	|   TEMPERATURE   CONTROL   |
*	|                           |
*	|                           |
*	|              ready   O    |    ( green )
*	|			    | 
*	|            no lock   O    |    ( yellow )
*	|                           |
*	|            invalid   O    |    ( red )
*	|                           |
*	|                           |
*	|      temperature set      |
*	|       ==   ==   ==        |
*	|       __   __   __        |
*	|      |  | |  | |  |       |
*	|      |--| |--| |--|       |
*	|      |__| |__| |__|       |
*	|                           |
*	|       ==   ==   ==        |
*	|                           |
*	|                           |
*	|          heater           |
*	|         ________          |
*	|        /        \         |
*	|       |          |        |
*	|       |          |        |
*	|       |          |        |
*	|        \________/         |
*	|                           |
*	+---------------------------+
*
*
*------------------------------------------------------------------------------
	PAGE
*------------------------------------------------------------------------------
*
*  Simplified schematic of the logic controller
*  -------------------------------------------
*
*
*                        TMX_PRT
*        +---+     +------+    +----------------+
*        | 9 |--/--|      |-/--|                |-----     
*        +---+   4 |      |  4 |                |  :   none free 
*    	           |      |    |                |-----      
*        +---+     | PAL  |    |                |
*        | 9 |--/--|      |    |    68705R3     | LED0_PRT
*        +---+   4 | 16L8 |    |                |---===---|<|---o +  ready
*                  |      |    |                |
*        +---+     |      |    |                | LED1_PRT                
*        | 9 |--/--|      |-/--|                |---===---|<|---o +  no lock
*        +---+   4 +------+  2 |                |
*                      TWS_PRT |                | LED2_PRT
*                              |                |---===---|<|---o +  invalid
*                              |                |
*                ^             |                |
*                |     RGA_PRT |                | TPF_PRT    2
*               [ ]<-----------|                |-----------/---o    testpins
*                |             |                | TPB_PRT
*           ^   ---            |                |            
*           |          RIA_PRT |                | SER_PRT    1
*          [ ]<----------------|                |-----------/---o    serial   
*           |                  |                |                    interface
*          ---                 |                |
*                              |                |          +-----+          
*                              |                | DDA_PRT  |     |       
*                              |                |----------| DACA|-----o Uout 
*           Uptc       PTC_PRT |                |     :    |     |            
*     |\   +-------------------|                |----------| DACB|-----o Uref
*   --| \  |                   |                |          |     |    
*     |  >-+-===-+-|\          |                |          | DACC|--        
*   --| /        | |-\ RES_PRT |                | DAD_PRT  |     |       
*     |/   +-===-+ |  >--------|                |----/-----| DACD|--  
*          |       |+/ Uerr    |                | DWR_PRT  |     |    
*          |     +-|/          |                |          +-----+    
*    Uref  |     |             +----------------+                     
*   o------+     +---o Ucc/2                                               
*  
*  
*------------------------------------------------------------------------------

*------------------------------------------------------------------------------
*
*  Regulator setup
*  ---------------  
*
*    thumb                                 regin / regout  DACout
*    wheel
*   2  1  0     +-----+             +         +-----+     +-----+ 
*               | 1'C |<--->[Uset]--->|\      |     |     |     | Rheater
*  [9][9][9]--->| min |               | >---->| Reg |---->| D/A |---===---|
*               | D/A |      Uptc  +->|/      |     |     |     |    O
*  20..120'C    +-----+            |-         +-----+     +-----+    | PTC
*                  ^               |                                 |
*                  | Tptc          |                                 |
*                  +---------------+---------------------------------+
* 
*------------------------------------------------------------------------------