1 ====================================
2 Intelligent Keyboard (ikbd) Protocol
3 ====================================
9 The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard
10 controller that is flexible enough that it can be used in a variety of
11 products without modification. The keyboard, with its microcontroller,
12 provides a convenient connection point for a mouse and switch-type joysticks.
13 The ikbd processor also maintains a time-of-day clock with one second
15 The ikbd has been designed to be general enough that it can be used with a
16 variety of new computer products. Product variations in a number of
17 keyswitches, mouse resolution, etc. can be accommodated.
18 The ikbd communicates with the main processor over a high speed bi-directional
19 serial interface. It can function in a variety of modes to facilitate
20 different applications of the keyboard, joysticks, or mouse. Limited use of
21 the controller is possible in applications in which only a unidirectional
22 communications medium is available by carefully designing the default modes.
27 The keyboard always returns key make/break scan codes. The ikbd generates
28 keyboard scan codes for each key press and release. The key scan make (key
29 closure) codes start at 1, and are defined in Appendix A. For example, the
30 ISO key position in the scan code table should exist even if no keyswitch
31 exists in that position on a particular keyboard. The break code for each key
32 is obtained by ORing 0x80 with the make code.
34 The special codes 0xF6 through 0xFF are reserved for use as follows:
36 =================== ====================================================
38 =================== ====================================================
40 0xF7 absolute mouse position record
41 0xF8-0xFB relative mouse position records (lsbs determined by
44 0xFD joystick report (both sticks)
47 =================== ====================================================
49 The two shift keys return different scan codes in this mode. The ENTER key
50 and the RETurn key are also distinct.
55 The mouse port should be capable of supporting a mouse with resolution of
56 approximately 200 counts (phase changes or 'clicks') per inch of travel. The
57 mouse should be scanned at a rate that will permit accurate tracking at
58 velocities up to 10 inches per second.
59 The ikbd can report mouse motion in three distinctly different ways. It can
60 report relative motion, absolute motion in a coordinate system maintained
61 within the ikbd, or by converting mouse motion into keyboard cursor control
63 The mouse buttons can be treated as part of the mouse or as additional
66 Relative Position Reporting
67 ---------------------------
69 In relative position mode, the ikbd will return relative mouse position
70 records whenever a mouse event occurs. A mouse event consists of a mouse
71 button being pressed or released, or motion in either axis exceeding a
72 settable threshold of motion. Regardless of the threshold, all bits of
73 resolution are returned to the host computer.
74 Note that the ikbd may return mouse relative position reports with
75 significantly more than the threshold delta x or y. This may happen since no
76 relative mouse motion events will be generated: (a) while the keyboard has
77 been 'paused' ( the event will be stored until keyboard communications is
78 resumed) (b) while any event is being transmitted.
80 The relative mouse position record is a three byte record of the form
81 (regardless of keyboard mode)::
83 %111110xy ; mouse position record flag
84 ; where y is the right button state
85 ; and x is the left button state
86 X ; delta x as twos complement integer
87 Y ; delta y as twos complement integer
89 Note that the value of the button state bits should be valid even if the
90 MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard.
91 If the accumulated motion before the report packet is generated exceeds the
92 +127...-128 range, the motion is broken into multiple packets.
93 Note that the sign of the delta y reported is a function of the Y origin
96 Absolute Position reporting
97 ---------------------------
99 The ikbd can also maintain absolute mouse position. Commands exist for
100 resetting the mouse position, setting X/Y scaling, and interrogating the
101 current mouse position.
103 Mouse Cursor Key Mode
104 ---------------------
106 The ikbd can translate mouse motion into the equivalent cursor keystrokes.
107 The number of mouse clicks per keystroke is independently programmable in
108 each axis. The ikbd internally maintains mouse motion information to the
109 highest resolution available, and merely generates a pair of cursor key events
110 for each multiple of the scale factor.
111 Mouse motion produces the cursor key make code immediately followed by the
112 break code for the appropriate cursor key. The mouse buttons produce scan
113 codes above those normally assigned for the largest envisioned keyboard (i.e.
114 LEFT=0x74 & RIGHT=0x75).
119 Joystick Event Reporting
120 ------------------------
122 In this mode, the ikbd generates a record whenever the joystick position is
123 changed (i.e. for each opening or closing of a joystick switch or trigger).
125 The joystick event record is two bytes of the form::
127 %1111111x ; Joystick event marker
128 ; where x is Joystick 0 or 1
129 %x000yyyy ; where yyyy is the stick position
130 ; and x is the trigger
132 Joystick Interrogation
133 ----------------------
135 The current state of the joystick ports may be interrogated at any time in
136 this mode by sending an 'Interrogate Joystick' command to the ikbd.
138 The ikbd response to joystick interrogation is a three byte report of the form::
140 0xFD ; joystick report header
141 %x000yyyy ; Joystick 0
142 %x000yyyy ; Joystick 1
143 ; where x is the trigger
144 ; and yyy is the stick position
149 A mode is available that devotes nearly all of the keyboard communications
150 time to reporting the state of the joystick ports at a user specifiable rate.
151 It remains in this mode until reset or commanded into another mode. The PAUSE
152 command in this mode not only stop the output but also temporarily stops
153 scanning the joysticks (samples are not queued).
155 Fire Button Monitoring
156 ----------------------
158 A mode is provided to permit monitoring a single input bit at a high rate. In
159 this mode the ikbd monitors the state of the Joystick 1 fire button at the
160 maximum rate permitted by the serial communication channel. The data is packed
161 8 bits per byte for transmission to the host. The ikbd remains in this mode
162 until reset or commanded into another mode. The PAUSE command in this mode not
163 only stops the output but also temporarily stops scanning the button (samples
166 Joystick Key Code Mode
167 ----------------------
169 The ikbd may be commanded to translate the use of either joystick into the
170 equivalent cursor control keystroke(s). The ikbd provides a single breakpoint
171 velocity joystick cursor.
172 Joystick events produce the make code, immediately followed by the break code
173 for the appropriate cursor motion keys. The trigger or fire buttons of the
174 joysticks produce pseudo key scan codes above those used by the largest key
175 matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75).
180 The ikbd also maintains a time-of-day clock for the system. Commands are
181 available to set and interrogate the timer-of-day clock. Time-keeping is
182 maintained down to a resolution of one second.
187 The current state of ikbd modes and parameters may be found by sending status
188 inquiry commands that correspond to the ikbd set commands.
193 The keyboard controller will perform a simple self-test on power-up to detect
194 major controller faults (ROM checksum and RAM test) and such things as stuck
195 keys. Any keys down at power-up are presumed to be stuck, and their BREAK
196 (sic) code is returned (which without the preceding MAKE code is a flag for a
197 keyboard error). If the controller self-test completes without error, the code
198 0xF0 is returned. (This code will be used to indicate the version/release of
199 the ikbd controller. The first release of the ikbd is version 0xF0, should
200 there be a second release it will be 0xF1, and so on.)
201 The ikbd defaults to a mouse position reporting with threshold of 1 unit in
202 either axis and the Y=0 origin at the top of the screen, and joystick event
203 reporting mode for joystick 1, with both buttons being logically assigned to
204 the mouse. After any joystick command, the ikbd assumes that joysticks are
205 connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE
206 DISABLE) then causes port 0 to again be scanned as if it were a mouse, and
207 both buttons are logically connected to it. If a mouse disable command is
208 received while port 0 is presumed to be a mouse, the button is logically
209 assigned to Joystick1 (until the mouse is reenabled by another mouse command).
214 This section contains a list of commands that can be sent to the ikbd. Command
215 codes (such as 0x00) which are not specified should perform no operation
226 N.B. The RESET command is the only two byte command understood by the ikbd.
227 Any byte following an 0x80 command byte other than 0x01 is ignored (and causes
228 the 0x80 to be ignored).
229 A reset may also be caused by sending a break lasting at least 200mS to the
231 Executing the RESET command returns the keyboard to its default (power-up)
232 mode and parameter settings. It does not affect the time-of-day clock.
233 The RESET command or function causes the ikbd to perform a simple self-test.
234 If the test is successful, the ikbd will send the code of 0xF0 within 300mS
235 of receipt of the RESET command (or the end of the break, or power-up). The
236 ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found
237 closed will cause the break scan code to be generated (the break code arriving
238 without being preceded by the make code is a flag for a key matrix error).
240 SET MOUSE BUTTON ACTION
241 -----------------------
246 %00000mss ; mouse button action
247 ; (m is presumed = 1 when in MOUSE KEYCODE mode)
248 ; mss=0xy, mouse button press or release causes mouse
250 ; where y=1, mouse key press causes absolute report
251 ; and x=1, mouse key release causes absolute report
252 ; mss=100, mouse buttons act like keys
254 This command sets how the ikbd should treat the buttons on the mouse. The
255 default mouse button action mode is %00000000, the buttons are treated as part
256 of the mouse logically.
257 When buttons act like keys, LEFT=0x74 & RIGHT=0x75.
259 SET RELATIVE MOUSE POSITION REPORTING
260 -------------------------------------
266 Set relative mouse position reporting. (DEFAULT) Mouse position packets are
267 generated asynchronously by the ikbd whenever motion exceeds the setable
268 threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse
269 key mode, mouse position reports may also be generated when either mouse
270 button is pressed or released. Otherwise the mouse buttons behave as if they
273 SET ABSOLUTE MOUSE POSITIONING
274 ------------------------------
279 XMSB ; X maximum (in scaled mouse clicks)
281 YMSB ; Y maximum (in scaled mouse clicks)
284 Set absolute mouse position maintenance. Resets the ikbd maintained X and Y
286 In this mode, the value of the internally maintained coordinates does NOT wrap
287 between 0 and large positive numbers. Excess motion below 0 is ignored. The
288 command sets the maximum positive value that can be attained in the scaled
289 coordinate system. Motion beyond that value is also ignored.
291 SET MOUSE KEYCODE MOSE
292 ----------------------
297 deltax ; distance in X clicks to return (LEFT) or (RIGHT)
298 deltay ; distance in Y clicks to return (UP) or (DOWN)
300 Set mouse monitoring routines to return cursor motion keycodes instead of
301 either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate
302 cursor keycode after mouse travel exceeding the user specified deltas in
303 either axis. When the keyboard is in key scan code mode, mouse motion will
304 cause the make code immediately followed by the break code. Note that this
305 command is not affected by the mouse motion origin.
313 X ; x threshold in mouse ticks (positive integers)
314 Y ; y threshold in mouse ticks (positive integers)
316 This command sets the threshold before a mouse event is generated. Note that
317 it does NOT affect the resolution of the data returned to the host. This
318 command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds
319 default to 1 at RESET (or power-up).
327 X ; horizontal mouse ticks per internal X
328 Y ; vertical mouse ticks per internal Y
330 This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode.
331 In this mode, the specified number of mouse phase changes ('clicks') must
332 occur before the internally maintained coordinate is changed by one
333 (independently scaled for each axis). Remember that the mouse position
334 information is available only by interrogating the ikbd in the ABSOLUTE MOUSE
335 POSITIONING mode unless the ikbd has been commanded to report on button press
336 or release (see SET MOSE BUTTON ACTION).
338 INTERROGATE MOUSE POSITION
339 --------------------------
345 0xF7 ; absolute mouse position header
347 0000dcba ; where a is right button down since last interrogation
348 ; b is right button up since last
349 ; c is left button down since last
350 ; d is left button up since last
356 The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE
357 POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
367 XLSB ; (in scaled coordinate system)
371 This command allows the user to preset the internally maintained absolute
381 This command makes the origin of the Y axis to be at the bottom of the
382 logical coordinate system internal to the ikbd for all relative or absolute
383 mouse motion. This causes mouse motion toward the user to be negative in sign
384 and away from the user to be positive.
393 Makes the origin of the Y axis to be at the top of the logical coordinate
394 system within the ikbd for all relative or absolute mouse motion. (DEFAULT)
395 This causes mouse motion toward the user to be positive in sign and away from
396 the user to be negative.
405 Resume sending data to the host. Since any command received by the ikbd after
406 its output has been paused also causes an implicit RESUME this command can be
407 thought of as a NO OPERATION command. If this command is received by the ikbd
408 and it is not PAUSED, it is simply ignored.
417 All mouse event reporting is disabled (and scanning may be internally
418 disabled). Any valid mouse mode command resumes mouse motion monitoring. (The
419 valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET
420 ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. )
421 N.B. If the mouse buttons have been commanded to act like keyboard keys, this
422 command DOES affect their actions.
431 Stop sending data to the host until another valid command is received. Key
432 matrix activity is still monitored and scan codes or ASCII characters enqueued
433 (up to the maximum supported by the microcontroller) to be sent when the host
434 allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode,
435 joystick events are also queued.
436 Mouse motion should be accumulated while the output is paused. If the ikbd is
437 in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the
438 normal threshold limits to produce the minimum number of packets necessary for
439 transmission when output is resumed. Pressing or releasing either mouse button
440 causes any accumulated motion to be immediately queued as packets, if the
441 mouse is in RELATIVE MOUSE POSITION REPORTING mode.
442 Because of the limitations of the microcontroller memory this command should
443 be used sparingly, and the output should not be shut of for more than <tbd>
444 milliseconds at a time.
445 The output is stopped only at the end of the current 'even'. If the PAUSE
446 OUTPUT command is received in the middle of a multiple byte report, the packet
447 will still be transmitted to conclusion and then the PAUSE will take effect.
448 When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON
449 MONITORING mode, the PAUSE OUTPUT command also temporarily stops the
450 monitoring process (i.e. the samples are not enqueued for transmission).
452 SET JOYSTICK EVENT REPORTING
453 ----------------------------
459 Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a
460 joystick switch or trigger causes a joystick event record to be generated.
462 SET JOYSTICK INTERROGATION MODE
463 -------------------------------
469 Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK
470 INTERROGATE commands to sense joystick state.
479 Return a record indicating the current state of the joysticks. This command
480 is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK
483 SET JOYSTICK MONITORING
484 -----------------------
489 rate ; time between samples in hundredths of a second
490 Returns: (in packets of two as long as in mode)
491 %000000xy ; where y is JOYSTICK1 Fire button
492 ; and x is JOYSTICK0 Fire button
493 %nnnnmmmm ; where m is JOYSTICK1 state
494 ; and n is JOYSTICK0 state
496 Sets the ikbd to do nothing but monitor the serial command line, maintain the
497 time-of-day clock, and monitor the joystick. The rate sets the interval
498 between joystick samples.
499 N.B. The user should not set the rate higher than the serial communications
500 channel will allow the 2 bytes packets to be transmitted.
502 SET FIRE BUTTON MONITORING
503 --------------------------
508 Returns: (as long as in mode)
509 %bbbbbbbb ; state of the JOYSTICK1 fire button packed
510 ; 8 bits per byte, the first sample if the MSB
512 Set the ikbd to do nothing but monitor the serial command line, maintain the
513 time-of-day clock, and monitor the fire button on Joystick 1. The fire button
514 is scanned at a rate that causes 8 samples to be made in the time it takes for
515 the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate).
516 The sample interval should be as constant as possible.
518 SET JOYSTICK KEYCODE MODE
519 -------------------------
524 RX ; length of time (in tenths of seconds) until
525 ; horizontal velocity breakpoint is reached
526 RY ; length of time (in tenths of seconds) until
527 ; vertical velocity breakpoint is reached
528 TX ; length (in tenths of seconds) of joystick closure
529 ; until horizontal cursor key is generated before RX
531 TY ; length (in tenths of seconds) of joystick closure
532 ; until vertical cursor key is generated before RY
534 VX ; length (in tenths of seconds) of joystick closure
535 ; until horizontal cursor keystrokes are generated
536 ; after RX has elapsed
537 VY ; length (in tenths of seconds) of joystick closure
538 ; until vertical cursor keystrokes are generated
539 ; after RY has elapsed
541 In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes.
542 On initial closure, a keystroke pair (make/break) is generated. Then up to Rn
543 tenths of seconds later, keystroke pairs are generated every Tn tenths of
544 seconds. After the Rn breakpoint is reached, keystroke pairs are generated
545 every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint
547 Note that by setting RX and/or Ry to zero, the velocity feature can be
548 disabled. The values of TX and TY then become meaningless, and the generation
549 of cursor 'keystrokes' is set by VX and VY.
558 Disable the generation of any joystick events (and scanning may be internally
559 disabled). Any valid joystick mode command resumes joystick monitoring. (The
560 joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK
561 INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and
562 SET JOYSTICK KEYCODE MODE.)
564 TIME-OF-DAY CLOCK SET
565 ---------------------
570 YY ; year (2 least significant digits)
577 All time-of-day data should be sent to the ikbd in packed BCD format.
578 Any digit that is not a valid BCD digit should be treated as a 'don't care'
579 and not alter that particular field of the date or time. This permits setting
580 only some subfields of the time-of-day clock.
582 INTERROGATE TIME-OF-DAT CLOCK
583 -----------------------------
589 0xFC ; time-of-day event header
590 YY ; year (2 least significant digits)
597 All time-of-day is sent in packed BCD format.
605 ADRMSB ; address in controller
606 ADRLSB ; memory to be loaded
607 NUM ; number of bytes (0-128)
610 This command permits the host to load arbitrary values into the ikbd
611 controller memory. The time between data bytes must be less than 20ms.
619 ADRMSB ; address in controller
620 ADRLSB ; memory to be read
624 { data } ; 6 data bytes starting at ADR
626 This command permits the host to read from the ikbd controller memory.
634 ADRMSB ; address of subroutine in
635 ADRLSB ; controller memory to be called
637 This command allows the host to command the execution of a subroutine in the
638 ikbd controller memory.
645 Status commands are formed by inclusively ORing 0x80 with the
646 relevant SET command.
649 0x88 (or 0x89 or 0x8A) ; request mouse mode
651 0xF6 ; status response header
652 mode ; 0x08 is RELATIVE
655 param1 ; 0 is RELATIVE
656 ; XMSB maximum if ABSOLUTE
658 param2 ; 0 is RELATIVE
659 ; YMSB maximum if ABSOLUTE
661 param3 ; 0 if RELATIVE
664 param4 ; 0 if RELATIVE
670 The STATUS INQUIRY commands request the ikbd to return either the current mode
671 or the parameters associated with a given command. All status reports are
672 padded to form 8 byte long return packets. The responses to the status
673 requests are designed so that the host may store them away (after stripping
674 off the status report header byte) and later send them back as commands to
675 ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the
678 Valid STATUS INQUIRY commands are::
680 0x87 mouse button action
684 0x8B mnouse threshold
686 0x8F mouse vertical coordinates
687 0x90 ( returns 0x0F Y=0 at bottom
689 0x92 mouse enable/disable
690 ( returns 0x00 enabled)
695 0x9A joystick enable/disable
696 ( returns 0x00 enabled
699 It is the (host) programmer's responsibility to have only one unanswered
700 inquiry in process at a time.
701 STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING
702 mode or FIRE BUTTON MONITORING mode.
708 The key scan codes returned by the ikbd are chosen to simplify the
709 implementation of GSX.
711 GSX Standard Keyboard Mapping
projects / mirror_ubuntu-hirsute-kernel.git / blob