821 lines · plain
1====================================2Intelligent Keyboard (ikbd) Protocol3====================================4 5 6Introduction7============8 9The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard10controller that is flexible enough that it can be used in a variety of11products without modification. The keyboard, with its microcontroller,12provides a convenient connection point for a mouse and switch-type joysticks.13The ikbd processor also maintains a time-of-day clock with one second14resolution.15The ikbd has been designed to be general enough that it can be used with a16variety of new computer products. Product variations in a number of17keyswitches, mouse resolution, etc. can be accommodated.18The ikbd communicates with the main processor over a high speed bi-directional19serial interface. It can function in a variety of modes to facilitate20different applications of the keyboard, joysticks, or mouse. Limited use of21the controller is possible in applications in which only a unidirectional22communications medium is available by carefully designing the default modes.23 24Keyboard25========26 27The keyboard always returns key make/break scan codes. The ikbd generates28keyboard scan codes for each key press and release. The key scan make (key29closure) codes start at 1, and are defined in Appendix A. For example, the30ISO key position in the scan code table should exist even if no keyswitch31exists in that position on a particular keyboard. The break code for each key32is obtained by ORing 0x80 with the make code.33 34The special codes 0xF6 through 0xFF are reserved for use as follows:35 36=================== ====================================================37 Code Command38=================== ====================================================39 0xF6 status report40 0xF7 absolute mouse position record41 0xF8-0xFB relative mouse position records (lsbs determined by42 mouse button states)43 0xFC time-of-day44 0xFD joystick report (both sticks)45 0xFE joystick 0 event46 0xFF joystick 1 event47=================== ====================================================48 49The two shift keys return different scan codes in this mode. The ENTER key50and the RETurn key are also distinct.51 52Mouse53=====54 55The mouse port should be capable of supporting a mouse with resolution of56approximately 200 counts (phase changes or 'clicks') per inch of travel. The57mouse should be scanned at a rate that will permit accurate tracking at58velocities up to 10 inches per second.59The ikbd can report mouse motion in three distinctly different ways. It can60report relative motion, absolute motion in a coordinate system maintained61within the ikbd, or by converting mouse motion into keyboard cursor control62key equivalents.63The mouse buttons can be treated as part of the mouse or as additional64keyboard keys.65 66Relative Position Reporting67---------------------------68 69In relative position mode, the ikbd will return relative mouse position70records whenever a mouse event occurs. A mouse event consists of a mouse71button being pressed or released, or motion in either axis exceeding a72settable threshold of motion. Regardless of the threshold, all bits of73resolution are returned to the host computer.74Note that the ikbd may return mouse relative position reports with75significantly more than the threshold delta x or y. This may happen since no76relative mouse motion events will be generated: (a) while the keyboard has77been 'paused' ( the event will be stored until keyboard communications is78resumed) (b) while any event is being transmitted.79 80The relative mouse position record is a three byte record of the form81(regardless of keyboard mode)::82 83 %111110xy ; mouse position record flag84 ; where y is the right button state85 ; and x is the left button state86 X ; delta x as twos complement integer87 Y ; delta y as twos complement integer88 89Note that the value of the button state bits should be valid even if the90MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard.91If the accumulated motion before the report packet is generated exceeds the92+127...-128 range, the motion is broken into multiple packets.93Note that the sign of the delta y reported is a function of the Y origin94selected.95 96Absolute Position reporting97---------------------------98 99The ikbd can also maintain absolute mouse position. Commands exist for100resetting the mouse position, setting X/Y scaling, and interrogating the101current mouse position.102 103Mouse Cursor Key Mode104---------------------105 106The ikbd can translate mouse motion into the equivalent cursor keystrokes.107The number of mouse clicks per keystroke is independently programmable in108each axis. The ikbd internally maintains mouse motion information to the109highest resolution available, and merely generates a pair of cursor key events110for each multiple of the scale factor.111Mouse motion produces the cursor key make code immediately followed by the112break code for the appropriate cursor key. The mouse buttons produce scan113codes above those normally assigned for the largest envisioned keyboard (i.e.114LEFT=0x74 & RIGHT=0x75).115 116Joystick117========118 119Joystick Event Reporting120------------------------121 122In this mode, the ikbd generates a record whenever the joystick position is123changed (i.e. for each opening or closing of a joystick switch or trigger).124 125The joystick event record is two bytes of the form::126 127 %1111111x ; Joystick event marker128 ; where x is Joystick 0 or 1129 %x000yyyy ; where yyyy is the stick position130 ; and x is the trigger131 132Joystick Interrogation133----------------------134 135The current state of the joystick ports may be interrogated at any time in136this mode by sending an 'Interrogate Joystick' command to the ikbd.137 138The ikbd response to joystick interrogation is a three byte report of the form::139 140 0xFD ; joystick report header141 %x000yyyy ; Joystick 0142 %x000yyyy ; Joystick 1143 ; where x is the trigger144 ; and yyy is the stick position145 146Joystick Monitoring147-------------------148 149A mode is available that devotes nearly all of the keyboard communications150time to reporting the state of the joystick ports at a user specifiable rate.151It remains in this mode until reset or commanded into another mode. The PAUSE152command in this mode not only stop the output but also temporarily stops153scanning the joysticks (samples are not queued).154 155Fire Button Monitoring156----------------------157 158A mode is provided to permit monitoring a single input bit at a high rate. In159this mode the ikbd monitors the state of the Joystick 1 fire button at the160maximum rate permitted by the serial communication channel. The data is packed1618 bits per byte for transmission to the host. The ikbd remains in this mode162until reset or commanded into another mode. The PAUSE command in this mode not163only stops the output but also temporarily stops scanning the button (samples164are not queued).165 166Joystick Key Code Mode167----------------------168 169The ikbd may be commanded to translate the use of either joystick into the170equivalent cursor control keystroke(s). The ikbd provides a single breakpoint171velocity joystick cursor.172Joystick events produce the make code, immediately followed by the break code173for the appropriate cursor motion keys. The trigger or fire buttons of the174joysticks produce pseudo key scan codes above those used by the largest key175matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75).176 177Time-of-Day Clock178=================179 180The ikbd also maintains a time-of-day clock for the system. Commands are181available to set and interrogate the timer-of-day clock. Time-keeping is182maintained down to a resolution of one second.183 184Status Inquiries185================186 187The current state of ikbd modes and parameters may be found by sending status188inquiry commands that correspond to the ikbd set commands.189 190Power-Up Mode191=============192 193The keyboard controller will perform a simple self-test on power-up to detect194major controller faults (ROM checksum and RAM test) and such things as stuck195keys. Any keys down at power-up are presumed to be stuck, and their BREAK196(sic) code is returned (which without the preceding MAKE code is a flag for a197keyboard error). If the controller self-test completes without error, the code1980xF0 is returned. (This code will be used to indicate the version/release of199the ikbd controller. The first release of the ikbd is version 0xF0, should200there be a second release it will be 0xF1, and so on.)201The ikbd defaults to a mouse position reporting with threshold of 1 unit in202either axis and the Y=0 origin at the top of the screen, and joystick event203reporting mode for joystick 1, with both buttons being logically assigned to204the mouse. After any joystick command, the ikbd assumes that joysticks are205connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE206DISABLE) then causes port 0 to again be scanned as if it were a mouse, and207both buttons are logically connected to it. If a mouse disable command is208received while port 0 is presumed to be a mouse, the button is logically209assigned to Joystick1 (until the mouse is reenabled by another mouse command).210 211ikbd Command Set212================213 214This section contains a list of commands that can be sent to the ikbd. Command215codes (such as 0x00) which are not specified should perform no operation216(NOPs).217 218RESET219-----220 221::222 223 0x80224 0x01225 226N.B. The RESET command is the only two byte command understood by the ikbd.227Any byte following an 0x80 command byte other than 0x01 is ignored (and causes228the 0x80 to be ignored).229A reset may also be caused by sending a break lasting at least 200mS to the230ikbd.231Executing the RESET command returns the keyboard to its default (power-up)232mode and parameter settings. It does not affect the time-of-day clock.233The RESET command or function causes the ikbd to perform a simple self-test.234If the test is successful, the ikbd will send the code of 0xF0 within 300mS235of receipt of the RESET command (or the end of the break, or power-up). The236ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found237closed will cause the break scan code to be generated (the break code arriving238without being preceded by the make code is a flag for a key matrix error).239 240SET MOUSE BUTTON ACTION241-----------------------242 243::244 245 0x07246 %00000mss ; mouse button action247 ; (m is presumed = 1 when in MOUSE KEYCODE mode)248 ; mss=0xy, mouse button press or release causes mouse249 ; position report250 ; where y=1, mouse key press causes absolute report251 ; and x=1, mouse key release causes absolute report252 ; mss=100, mouse buttons act like keys253 254This command sets how the ikbd should treat the buttons on the mouse. The255default mouse button action mode is %00000000, the buttons are treated as part256of the mouse logically.257When buttons act like keys, LEFT=0x74 & RIGHT=0x75.258 259SET RELATIVE MOUSE POSITION REPORTING260-------------------------------------261 262::263 264 0x08265 266Set relative mouse position reporting. (DEFAULT) Mouse position packets are267generated asynchronously by the ikbd whenever motion exceeds the setable268threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse269key mode, mouse position reports may also be generated when either mouse270button is pressed or released. Otherwise the mouse buttons behave as if they271were keyboard keys.272 273SET ABSOLUTE MOUSE POSITIONING274------------------------------275 276::277 278 0x09279 XMSB ; X maximum (in scaled mouse clicks)280 XLSB281 YMSB ; Y maximum (in scaled mouse clicks)282 YLSB283 284Set absolute mouse position maintenance. Resets the ikbd maintained X and Y285coordinates.286In this mode, the value of the internally maintained coordinates does NOT wrap287between 0 and large positive numbers. Excess motion below 0 is ignored. The288command sets the maximum positive value that can be attained in the scaled289coordinate system. Motion beyond that value is also ignored.290 291SET MOUSE KEYCODE MODE292----------------------293 294::295 296 0x0A297 deltax ; distance in X clicks to return (LEFT) or (RIGHT)298 deltay ; distance in Y clicks to return (UP) or (DOWN)299 300Set mouse monitoring routines to return cursor motion keycodes instead of301either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate302cursor keycode after mouse travel exceeding the user specified deltas in303either axis. When the keyboard is in key scan code mode, mouse motion will304cause the make code immediately followed by the break code. Note that this305command is not affected by the mouse motion origin.306 307SET MOUSE THRESHOLD308-------------------309 310::311 312 0x0B313 X ; x threshold in mouse ticks (positive integers)314 Y ; y threshold in mouse ticks (positive integers)315 316This command sets the threshold before a mouse event is generated. Note that317it does NOT affect the resolution of the data returned to the host. This318command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds319default to 1 at RESET (or power-up).320 321SET MOUSE SCALE322---------------323 324::325 326 0x0C327 X ; horizontal mouse ticks per internal X328 Y ; vertical mouse ticks per internal Y329 330This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode.331In this mode, the specified number of mouse phase changes ('clicks') must332occur before the internally maintained coordinate is changed by one333(independently scaled for each axis). Remember that the mouse position334information is available only by interrogating the ikbd in the ABSOLUTE MOUSE335POSITIONING mode unless the ikbd has been commanded to report on button press336or release (see SET MOUSE BUTTON ACTION).337 338INTERROGATE MOUSE POSITION339--------------------------340 341::342 343 0x0D344 Returns:345 0xF7 ; absolute mouse position header346 BUTTONS347 0000dcba ; where a is right button down since last interrogation348 ; b is right button up since last349 ; c is left button down since last350 ; d is left button up since last351 XMSB ; X coordinate352 XLSB353 YMSB ; Y coordinate354 YLSB355 356The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE357POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.358 359LOAD MOUSE POSITION360-------------------361 362::363 364 0x0E365 0x00 ; filler366 XMSB ; X coordinate367 XLSB ; (in scaled coordinate system)368 YMSB ; Y coordinate369 YLSB370 371This command allows the user to preset the internally maintained absolute372mouse position.373 374SET Y=0 AT BOTTOM375-----------------376 377::378 379 0x0F380 381This command makes the origin of the Y axis to be at the bottom of the382logical coordinate system internal to the ikbd for all relative or absolute383mouse motion. This causes mouse motion toward the user to be negative in sign384and away from the user to be positive.385 386SET Y=0 AT TOP387--------------388 389::390 391 0x10392 393Makes the origin of the Y axis to be at the top of the logical coordinate394system within the ikbd for all relative or absolute mouse motion. (DEFAULT)395This causes mouse motion toward the user to be positive in sign and away from396the user to be negative.397 398RESUME399------400 401::402 403 0x11404 405Resume sending data to the host. Since any command received by the ikbd after406its output has been paused also causes an implicit RESUME this command can be407thought of as a NO OPERATION command. If this command is received by the ikbd408and it is not PAUSED, it is simply ignored.409 410DISABLE MOUSE411-------------412 413::414 415 0x12416 417All mouse event reporting is disabled (and scanning may be internally418disabled). Any valid mouse mode command resumes mouse motion monitoring. (The419valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET420ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. )421N.B. If the mouse buttons have been commanded to act like keyboard keys, this422command DOES affect their actions.423 424PAUSE OUTPUT425------------426 427::428 429 0x13430 431Stop sending data to the host until another valid command is received. Key432matrix activity is still monitored and scan codes or ASCII characters enqueued433(up to the maximum supported by the microcontroller) to be sent when the host434allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode,435joystick events are also queued.436Mouse motion should be accumulated while the output is paused. If the ikbd is437in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the438normal threshold limits to produce the minimum number of packets necessary for439transmission when output is resumed. Pressing or releasing either mouse button440causes any accumulated motion to be immediately queued as packets, if the441mouse is in RELATIVE MOUSE POSITION REPORTING mode.442Because of the limitations of the microcontroller memory this command should443be used sparingly, and the output should not be shut of for more than <tbd>444milliseconds at a time.445The output is stopped only at the end of the current 'even'. If the PAUSE446OUTPUT command is received in the middle of a multiple byte report, the packet447will still be transmitted to conclusion and then the PAUSE will take effect.448When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON449MONITORING mode, the PAUSE OUTPUT command also temporarily stops the450monitoring process (i.e. the samples are not enqueued for transmission).451 452SET JOYSTICK EVENT REPORTING453----------------------------454 455::456 457 0x14458 459Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a460joystick switch or trigger causes a joystick event record to be generated.461 462SET JOYSTICK INTERROGATION MODE463-------------------------------464 465::466 467 0x15468 469Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK470INTERROGATE commands to sense joystick state.471 472JOYSTICK INTERROGATE473--------------------474 475::476 477 0x16478 479Return a record indicating the current state of the joysticks. This command480is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK481INTERROGATION MODE.482 483SET JOYSTICK MONITORING484-----------------------485 486::487 488 0x17489 rate ; time between samples in hundredths of a second490 Returns: (in packets of two as long as in mode)491 %000000xy ; where y is JOYSTICK1 Fire button492 ; and x is JOYSTICK0 Fire button493 %nnnnmmmm ; where m is JOYSTICK1 state494 ; and n is JOYSTICK0 state495 496Sets the ikbd to do nothing but monitor the serial command line, maintain the497time-of-day clock, and monitor the joystick. The rate sets the interval498between joystick samples.499N.B. The user should not set the rate higher than the serial communications500channel will allow the 2 bytes packets to be transmitted.501 502SET FIRE BUTTON MONITORING503--------------------------504 505::506 507 0x18508 Returns: (as long as in mode)509 %bbbbbbbb ; state of the JOYSTICK1 fire button packed510 ; 8 bits per byte, the first sample if the MSB511 512Set the ikbd to do nothing but monitor the serial command line, maintain the513time-of-day clock, and monitor the fire button on Joystick 1. The fire button514is scanned at a rate that causes 8 samples to be made in the time it takes for515the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate).516The sample interval should be as constant as possible.517 518SET JOYSTICK KEYCODE MODE519-------------------------520 521::522 523 0x19524 RX ; length of time (in tenths of seconds) until525 ; horizontal velocity breakpoint is reached526 RY ; length of time (in tenths of seconds) until527 ; vertical velocity breakpoint is reached528 TX ; length (in tenths of seconds) of joystick closure529 ; until horizontal cursor key is generated before RX530 ; has elapsed531 TY ; length (in tenths of seconds) of joystick closure532 ; until vertical cursor key is generated before RY533 ; has elapsed534 VX ; length (in tenths of seconds) of joystick closure535 ; until horizontal cursor keystrokes are generated536 ; after RX has elapsed537 VY ; length (in tenths of seconds) of joystick closure538 ; until vertical cursor keystrokes are generated539 ; after RY has elapsed540 541In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes.542On initial closure, a keystroke pair (make/break) is generated. Then up to Rn543tenths of seconds later, keystroke pairs are generated every Tn tenths of544seconds. After the Rn breakpoint is reached, keystroke pairs are generated545every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint546feature.547Note that by setting RX and/or Ry to zero, the velocity feature can be548disabled. The values of TX and TY then become meaningless, and the generation549of cursor 'keystrokes' is set by VX and VY.550 551DISABLE JOYSTICKS552-----------------553 554::555 556 0x1A557 558Disable the generation of any joystick events (and scanning may be internally559disabled). Any valid joystick mode command resumes joystick monitoring. (The560joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK561INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and562SET JOYSTICK KEYCODE MODE.)563 564TIME-OF-DAY CLOCK SET565---------------------566 567::568 569 0x1B570 YY ; year (2 least significant digits)571 MM ; month572 DD ; day573 hh ; hour574 mm ; minute575 ss ; second576 577All time-of-day data should be sent to the ikbd in packed BCD format.578Any digit that is not a valid BCD digit should be treated as a 'don't care'579and not alter that particular field of the date or time. This permits setting580only some subfields of the time-of-day clock.581 582INTERROGATE TIME-OF-DAT CLOCK583-----------------------------584 585::586 587 0x1C588 Returns:589 0xFC ; time-of-day event header590 YY ; year (2 least significant digits)591 MM ; month592 DD ; day593 hh ; hour594 mm ; minute595 ss ; second596 597 All time-of-day is sent in packed BCD format.598 599MEMORY LOAD600-----------601 602::603 604 0x20605 ADRMSB ; address in controller606 ADRLSB ; memory to be loaded607 NUM ; number of bytes (0-128)608 { data }609 610This command permits the host to load arbitrary values into the ikbd611controller memory. The time between data bytes must be less than 20ms.612 613MEMORY READ614-----------615 616::617 618 0x21619 ADRMSB ; address in controller620 ADRLSB ; memory to be read621 Returns:622 0xF6 ; status header623 0x20 ; memory access624 { data } ; 6 data bytes starting at ADR625 626This command permits the host to read from the ikbd controller memory.627 628CONTROLLER EXECUTE629------------------630 631::632 633 0x22634 ADRMSB ; address of subroutine in635 ADRLSB ; controller memory to be called636 637This command allows the host to command the execution of a subroutine in the638ikbd controller memory.639 640STATUS INQUIRIES641----------------642 643::644 645 Status commands are formed by inclusively ORing 0x80 with the646 relevant SET command.647 648 Example:649 0x88 (or 0x89 or 0x8A) ; request mouse mode650 Returns:651 0xF6 ; status response header652 mode ; 0x08 is RELATIVE653 ; 0x09 is ABSOLUTE654 ; 0x0A is KEYCODE655 param1 ; 0 is RELATIVE656 ; XMSB maximum if ABSOLUTE657 ; DELTA X is KEYCODE658 param2 ; 0 is RELATIVE659 ; YMSB maximum if ABSOLUTE660 ; DELTA Y is KEYCODE661 param3 ; 0 if RELATIVE662 ; or KEYCODE663 ; YMSB is ABSOLUTE664 param4 ; 0 if RELATIVE665 ; or KEYCODE666 ; YLSB is ABSOLUTE667 0 ; pad668 0669 670The STATUS INQUIRY commands request the ikbd to return either the current mode671or the parameters associated with a given command. All status reports are672padded to form 8 byte long return packets. The responses to the status673requests are designed so that the host may store them away (after stripping674off the status report header byte) and later send them back as commands to675ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the676ikbd.677 678 Valid STATUS INQUIRY commands are::679 680 0x87 mouse button action681 0x88 mouse mode682 0x89683 0x8A684 0x8B mnouse threshold685 0x8C mouse scale686 0x8F mouse vertical coordinates687 0x90 ( returns 0x0F Y=0 at bottom688 0x10 Y=0 at top )689 0x92 mouse enable/disable690 ( returns 0x00 enabled)691 0x12 disabled )692 0x94 joystick mode693 0x95694 0x96695 0x9A joystick enable/disable696 ( returns 0x00 enabled697 0x1A disabled )698 699It is the (host) programmer's responsibility to have only one unanswered700inquiry in process at a time.701STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING702mode or FIRE BUTTON MONITORING mode.703 704 705SCAN CODES706==========707 708The key scan codes returned by the ikbd are chosen to simplify the709implementation of GSX.710 711GSX Standard Keyboard Mapping712 713======= ============714Hex Keytop715======= ============71601 Esc71702 171803 271904 372005 472106 572207 672308 772409 87250A 97260B 07270C \-7280D \=7290E BS7300F TAB73110 Q73211 W73312 E73413 R73514 T73615 Y73716 U73817 I73918 O74019 P7411A [7421B ]7431C RET7441D CTRL7451E A7461F S74720 D74821 F74922 G75023 H75124 J75225 K75326 L75427 ;75528 '75629 \`7572A (LEFT) SHIFT7582B \\7592C Z7602D X7612E C7622F V76330 B76431 N76532 M76633 ,76734 .76835 /76936 (RIGHT) SHIFT77037 { NOT USED }77138 ALT77239 SPACE BAR7733A CAPS LOCK7743B F17753C F27763D F37773E F47783F F577940 F678041 F778142 F878243 F978344 F1078445 { NOT USED }78546 { NOT USED }78647 HOME78748 UP ARROW78849 { NOT USED }7894A KEYPAD -7904B LEFT ARROW7914C { NOT USED }7924D RIGHT ARROW7934E KEYPAD +7944F { NOT USED }79550 DOWN ARROW79651 { NOT USED }79752 INSERT79853 DEL79954 { NOT USED }8005F { NOT USED }80160 ISO KEY80261 UNDO80362 HELP80463 KEYPAD (80564 KEYPAD /80665 KEYPAD *80766 KEYPAD *80867 KEYPAD 780968 KEYPAD 881069 KEYPAD 98116A KEYPAD 48126B KEYPAD 58136C KEYPAD 68146D KEYPAD 18156E KEYPAD 28166F KEYPAD 381770 KEYPAD 081871 KEYPAD .81972 KEYPAD ENTER820======= ============821