🚀 go-pugleaf

>
>>How do I read the joystick ports on the 520ST?
>
>
>Good Question!  I have asked it twice on the net already. If anyone
>knows please post the answer so that we will all know.
>

(You may be sorry you asked!)  There is quite a bit you have to know to
read thejoystick/mouse ports.  If you don't want to read all of this,
look for part 2 of this document - I'll include a sample source listing
to show you how to do it.

Both the joystick port and the mouse port are controlled by the
"Intelligent Keyboard" (ikbd) which (quoting Atari's documentation)
"communicates with the main processor over a high speed bi-directional
serial interface...", and, "...can function in a variety of modes to
facilitate different applications of the keyboard, joysticks, or mouse."



Keyboard
--------
The keyboard always returns key make/break (press/release)
codes.  The break (release) codes are obtained by ORing 0x80 with the
make (press) codes.  The key codes are defined as follows:

	Code Key		Code Key		Code Key
	--------		--------		--------
	 00   undefined(?)	 10   Q			 20   D
	 01   ESC		 11   W			 21   F
	 02   1			 12   E			 22   G
	 03   2			 13   R			 23   H
	 04   3			 14   T			 24   J
	 05   4			 15   Y			 25   K
	 06   5			 16   U			 26   L
	 07   6			 17   I			 27   ;
	 08   7			 18   O			 28   '
	 09   8			 19   P			 29   `
	 0A   9			 1A   [			 2A   LSHIFT
	 0B   0			 1B   ]			 2B   \
	 0C   -			 1C   RET		 2C   Z
	 0D   ==		 1D   CTRL		 2D   X
	 0E   BS		 1E   A			 2E   C
	 0F   TAB		 1F   S			 2F   V

	Code Key		Code Key		Code Key
	--------		--------		--------
	 30   B			 40   F6		 50   DOWN ARROW
	 31   N			 41   F7		 51   {not used}
	 32   M			 42   F8		 52   INS
	 33   ,			 43   F9		 53   DEL
	 34   .			 44   F10		 54   {not used}
	 35   /			 45   {not used}	 55   {not used}
	 36   RSHIFT		 46   {not used}	 56   {not used}
	 37   {not used}	 47   HOME		 57   {not used}
	 38   ALT		 48   UP ARROW		 58   {not used}
	 39   SPACE		 49   {not used}	 59   {not used}
	 3A   CAPS LOCK		 4A   KEYPAD - 		 5A   {not used}
	 3B   F1		 4B   LEFT ARROW	 5B   {not used}
	 3C   F2		 4C   {not used}	 5C   {not used}
	 3D   F3		 4D   RIGHT ARROW	 5D   {not used}
	 3E   F4		 4E   KEYPAD +		 5E   {not used}
	 3F   F5		 4F   {not used}	 5F   {not used}

	Code Key		Code Key
	--------		--------
	 60   ISO KEY		 70   KEYPAD 0
	 61   UNDO		 71   KEYPAD .
	 62   HELP		 72   KEYPAD ENTER
	 63   KEYPAD (
	 64   KEYPAD )
	 65   KEYPAD /
	 66   KEYPAD *
	 67   KEYPAD 7
	 68   KEYPAD 8
	 69   KEYPAD 9
	 6A   KEYPAD 4
	 6B   KEYPAD 5
	 6C   KEYPAD 6
	 6D   KEYPAD 1
	 6E   KEYPAD 2
	 6F   KEYPAD 3
   
Mouse
-----
There are 3 different ways ikbd can report mouse motion:
relative, absolute, and by converting mouse motion into cursor control
key equivalents.  The mouse buttons can either be treated as part of
the mouse or as additional keyboard keys.

Relative Position Reporting:
When a mouse event (mouse button pressed or released, or motion in
either axis) occurs, ikbd returns a three byte record containing:

	%111110xx	; mouse position record flag
	       ||
	       |------- ; right button state
	       -------- ; left button state
	%xxxxxxxx	; delta X (twos complement integer)
	%xxxxxxxx	; delta Y (twos complement integer)

NOTE - ikbd may return more than threshold delta X or Y since no
relative mouse motion events will be generated during certain
operations.  Also, if the accumulated motion exceeds +127..-128, then
the motion is broken into multiple packets.

Absolute Position Reporting:
Commands exist for reseting the mouse position, setting X & Y scaling,
and interrogating the current mouse position (see below).

Mouse Cursor Key Mode:
ikbd can translate mouse motion into the equivalent cursor keystrokes -
the number of "clicks" per keystroke being independently programable in
each axis.  Mouse motion produces the cursor key make (press) code
immediately followed by the break (release) code for the appropriate
cursor key.  The mouse buttons produce scan codes above those normally
assigned for the largest envisioned keyboard (i.e. LEFT=0x74, RIGHT=0x75).

Joystick
--------
As in mouse reporting, ikbd can report changes in the joystick
state in several different ways: joystick event reporting, joystick
interrogation, joystick monitoring, fire button monitoring, and
joystick key code equivalents.

Joystick Event Reporting:
ikbd will generate a record when the joystick undergoes a change of
state (i.e. when pressing forward, pulling back, or pressing the
trigger).  The event record consists of two bytes:

	%1111111x	; joystick event marker
	        |
	        ------- ; joystick number (0 or 1)
	%x000yyyy
	 |   ||||
	 |   ---------- ; stick position
	 -------------- ; trigger

Joystick Interrogation:
The current state of the joystick ports may be interrogated at any time
by sending the "Interrogate Joystick" command (see below) to ikbd.  The
response is a three byte report:

	0xFD		; joystick report header
	%x000yyyy	; joystick 0
	%x000yyyy	; joystick 1
			;  where x is the trigger
			;  and yyyy is the position

Joystick Monitoring:
It is possible to devote nearly all of the keyboard communications time
to reporting the state of the joystick ports, at a user specified rate
(see below).

Fire Button Monitoring:
A mode exists which permits monitoring a single input bit at the
maximum rate permitted by the serial communications channel.  ikbd
monitors joystick 1 and packs the data, 8 bits per byte for
transmission.

Joystick Key Code Mode:
ikbd may be commanded to translate the use of either joystick into the
equivalent cursor control keys.  Joystick events produce the make
(press) code, immediately followed by the break (release) code for the
appropriate cursor motion.  The trigger produces key scan codes above
those used used by the largest keyboard envisioned.

Power-up Mode
-------------
ikbd performs a number of self-test diagnostics on power-up.  If no
erros are detected, the code 0xF0 is returned.  (Actually, depending on
the version, you may get 0xF1, 0xF2, etc.)  ikbd defaults to mouse
position reporting with threshold unit of 1 in either axis, and the Y=0
origin at the top of the screen, and joystick event reporting mode for
joystick 1, with both buttons being logically assigned to the mouse.
After any joystick commands, ikbd assumes joysticks are connected to
both joystick ports.  Any mouse command (except "Mouse Disable") then
again causes port 0 to be scanned as if it were a mouse, and both
buttons are logically connected to it.

ikbd Commands
-------------
Commands may be sent to ikbdws using the Ikbdws() function (ikbd Write
String):

VOID	Ikbdws(cnt,ptr)
WORD	cnt;		/* number of bytes to send minus 1 */
LONG	ptr;		/* pointer to the string of bytes  */

Reset - return ikbd to power-up state

	0x80
	0x81

Set Mouse Button Action - select mouse button mode

	0x07
	%00000mss	; mouse button action
	      |||	; (m is presumed to be 1 when in 
	      |||	;  Mouse Keycode mode)
	      --------- ; 0wx	mouse button press or release
			;  ||	causes mouse position report
			;  ||	(wx only relevant if in
			;  ||    absolute mouse pos. mode)
			;  |--	1 -> mouse key press causes
			;  |         absolute pos. report
			;  ---  1 -> mouse key release causes
			;	     absolute pos. report
			; 100 = mouse buttons act like keys

Set Relative Mouse Position Reporting (default)

	0x08

Set Absolute Mouse Positioning

	0x09
	Xmsb		; X maximum (scaled mouse clicks)
	Xlsb
	Ymsb		; Y maximum (scaled mouse clicks)
	Ylsb

Select Mouse Keycode Mode

	0x0A
	deltax		; distance in X clicks to return
	deltay		; distance in Y clicks to return

Set Mouse Threshold

	0x0B
	X		; x threshold in clicks
	Y		; y threshold in clicks

Set Mouse Scale

	0x0C
	X		; horz. mouse ticks per internal X
	Y		; vert. mouse ticks per internal Y

Interrogate Mouse Position

	0x0D
returns:	0xF7		; abs. mouse pos. header
		%0000xxxx	; buttons
		     ||||
		     |||------- ; right button down
		     |||        ; since last interrogation
		     ||-------- ; right button up since last...
		     |--------- ; left button down since last...
		     ---------- ; left button up dince last...
		Xmsb		; X coordinate
	        Xlsb
		Ymsb		; Y coordinate
		Ylsb

That's about all I have time for now.  I'll finish up the list of
commands, and give an example (in C source) of how to put all of this
together in a couple of days.

Richard E. Sansom
{decvax,ucbvax,ihnp4}!trwrb!trwrba!sansom