TransKey History, Technology and Modern TK-II Usage
So what is this TK-II thing anyway?
It started life back in 1990 as the TransKey, and was probably the first commercial product for the Atari 8-Bit computer to allow use of a IBM keyboard in place of the stock keyboard that came with the Atari from the factory. In that early design, it was a rather bulky thing being based on a 6502 variant (6504 CPU), a Peripheral Interface Adapter (6520 PIA), an EPROM (2732), and a Static RAM (6116), as well as a couple of glue logic chips. It worked, although it was quirky and was a hit or miss proposition when it came to compatibility with a given keyboard.
Original 1990 TransKey-I Design Drawings
So fast forward 25 years, where advances in technology has made everything smaller, faster, and cheaper. The new TransKey which is known as the TK-II, is now based upon a single microcontroller chip made by MicroChip called the PIC16F1847. Everything that used to be made up of individual chips, now resides within a very small mini-DIP 18-pin integrated circuit package. It still does the same thing as it's much older cousin, but now takes up a lot less room, power, and cost. Also it's code is much less finicky about your choice of keyboards, other then it should be some flavor of PS/2.
TK-II V2.6 Firmware PS/2 Keyboard Map
TK-II Classic version 2.6 firmware will only work on TK-II hardware that looks at the entire Pokey key scan counter, including the embedded applications as done for the 1088XEL and 1088XLD motherboard projects. When dual PS/2 keyboard capability is required, and assuming the hardware has the necessary circuitry to support it, this is the firmware version to use. And it can swap out that ability in order to support the Mouse Select and Next Disk features of the 1088XLD. It also provides a Delayed Reset feature to hold off the Atari boot process until the PS/2 keyboard has had time to fully initialize, thereby letting held keys (e.g., START and RESET) to be seen during the power-up cycle. However this will only work with certain Atari computer systems, dependent upon the reset circuit they employ, and it isn't required for the 1088 series units.
Works In: TK-II-STEREO, TK-II-XEGS, TK-II-GS, TK-II-PB, 1088XEL, 1088XLD --- NOT FOR 576NUC+
TK-II V2.7J Firmware PS/2 Keyboard Map
This newest Universal firmware version works on any of the TK-II hardware, with the exception of the 576NUC+. Although it does sacrifice dual PS/2 keyboard functionality as a result. However it makes up for that by adding some very cool new features, and fine tuning other aspects of operation.
Works In: TK-II-STEREO, TK-II-XEGS, TK-II-GS, TK-II-PB, 1088XEL, 1088XLD, TK-II-PBJ, ARROW2JOY-XLD --- NOT FOR 576NUC+
F-Key EMU Mode Selection
This new feature allows for two different selectable function key mapping schemes. One that maintains the classic TK-II standard, and the other supporting the DarkAKI alternative used in Lotharek's AKI PS/2 Keyboard interface. The AKI F-Key mapping scheme as it pertains to the console and reset key assignments is identical to what's also being used in the Altirra Atari 8-bit Emulator (exception: HELP key mapping). I refer to this new TK-II feature as F-Key EMU, with EMU really just being a short hand way of saying emulation. It can be toggled between F-key emulation modes by using the key press combination CTRL+ALT+E, which is a non-volatile selection that will be restored between power cycles (ALT+E will show you what the present setting is without changing it).
Does the AKI EMU mode selection eliminate the 1200XL keys?
Arrow to Joystick Mode and more...
When coupled with the correct hardware, an 'Arrows to Joystick' mode is also supported. Thus allowing the keyboard to stand in for a joystick for any application that only requires X and Y joystick movements, which is the case for many games. Best part of all is that those games an applications don't need to be 'Arrow to Joystick' aware, since to the Atari it looks no different then if it were a real joystick. And finally, when using the same hardware that supports the joystick mode, there are also three Auxiliary (general purpose) open collector outputs with a momentary action (sustained for the length of the activating key press). These additional outputs are controlled by pressing ALT+1-3.
To activate or deactivate the 'Arrows to Joystick' mode, ALT+J toggles it. This is a volatile selection, and will revert to normal arrow mode following a power cycle. When in the joystick mode, CTRL+Arrows will send the normal non-controlled, non-shifted symbol that exists on the Atari counterpart. Using SHIFT+CTRL+Arrows will give you cursor controlled movement same as using just control on the Atari keyboard. ALT+A reverses this relationship. If you are using the joystick mode in conjunction with a U1MB upgrade, be sure to enable navigational control to joystick port1 for both the U1MB Setup and the Loader. When in joystick mode, this allows a single key press of an arrow key to move you through the menus, and the emulated trigger (Left-Win or Keypad Enter) will execute a selection.
What else has changed in V2.7J vs. V2.6?
Well for one, the Break key will also break you out of any activity that's listing something to the screen, such as ALT+F2 which displays the current TK-II configuration settings, or a macro that has a long time delay inserted.
I also tightened up the timing when it comes to those listings, so that no more dropped characters occur, and you should no longer see the U1MB setup menu briefly appear when pressing F11 to launch into the U1MB Loader. Basically I went through the firmware and removed a bunch of residual non-essential and no longer needed code left over from previous firmware revisions that was beginning to create issues with essential routines.
Both V2.6 and V2.7J have had corrections made to what key code is now being sent for CTRL+SHIFT+Arrow keys. In all previous TK-II firmware releases this key combination was sending the incorrect key codes. Also there was a bug discovered that was causing interference with the CTRL, SHIFT, and Break keys on the stock Atari keyboard, which has now been corrected in the latest firmware versions.
Why two different firmware versions for download?
Unfortunately due to the memory constraints of the PIC embedded processor, as well as inefficiencies in the code produced by the development software (FlowCode), it wasn't possible to have an all-in-one version of firmware that incorporated absolutely everything. And since some of the TK-II hardware depends upon certain features being there, a choice is offered to stay with what is working with specific features of your hardware, or to give up some of those things in order to have new functionality that better suits the end user. Thus the reason why there are two firmware versions being talked about, and available for download from the main TK-II page.
The main things you give up when upgrading from 2.6 to 2.7J is dual PS/2 keyboard capability and the optional delayed reset following power-up. There is some other stuff, but it's very minor and probably won't be missed. Version 2.7J is also required for enabling the arrow to joystick mode on some of the newer hardware such as the TK-II-PBJ and the ARROW2JOY-XLD upgrade, as well as being an absolute requirement for those boards to work due to their unique method of interfacing to the Pokey chip. However if you don't need those particular features, it is recommended that you upgrade to the 'J' version firmware because that will continue to see better down the road support and improvements.
So now let's talk more in depth about some of the individual features...
The keyboard diagrams above reveals how the 'special' key assignments are being mapped on a typical 104-key PS/2 keyboard, based on the latest TK-II Firmware versions.
Lets get into how these special key assignments are utilized, and specifically what they will do for your Atari 8-Bit computer.
Also in that diagram you'll see that the modifier keys ALT, CTRL, and SHIFT have been highlighted in 3 different colors (RED, BLUE, GREEN). Since a lot of the extra functionality requires the use of at least one modifier key being pressed in combination with another key, these colors are being used to show which modifier key is linked to what 'function' key in order to activate or access a given feature.
The table to the right lists the special key assignments and their specific functions, giving definitions for each. And in the following paragraphs some of the more involved assignments will be talked about in greater detail.
Macros store a collection of key presses that can be recalled by pressing ALT plus the corresponding macro key. This will automatically send the stored key presses out as if you had typed them yourself, although usually at a much faster rate. This can be very useful for often repeated commands.
TK-II has two kinds of macro keys. A 'hard-coded' macro is one that has it's definition fixed in the firmware, and cannot be changed. The other is a 'programmable' macro which can be changed through user intervention.
When recording macros, most any key press can be stored. For instance if you wish to start your macro with a clear screen each time (highly recommended), then it's simply a matter of pressing SHIFT+Home at the beginning of your recording (this will clear the screen, but no worries the macro is still recording, so enter whatever you want following this). When the macro is subsequently played back, the screen will first be cleared before continuing with any other recorded key presses.
Macro recording is initiated by pressing a function key (F5-F8) in combination with CTRL+ALT. So for instance if I want to assign a macro to F9, I would press CTRL+ALT+F9 and then release. You should see the Caps Lock LED light up, indicating that you are in record mode. Keep in mind only 30 key presses can be stored for a given macro key (SHIFT and CTRL are not included as part of this limit). If you try to exceed 30 key presses, a buzzer will sound, and you will not be allowed to continue entering key presses, however you can still back space and change what you previously typed. When you have completed your macro, press CTRL+ALT+F9 and the Caps Lock LED should extinguish, indicating that recording has stopped. Your F9 macro should now be saved for later recall (ALT+F9 will let you use it).
If at any point in the recording process you change your mind, pressing CTRL+ALT+Escape will abort the recording, while leaving the original macro intact.
There are three CTRL key combinations that enter special flag symbols into the macro that control the action of your macro as it plays out. Each flag counts as one key in your macro, with one of them (pause command) counting as two keys. So use them wisely, since they will eat up your macro key allocation.
This can be toggled ON or OFF by pressing ALT+Insert in the navigation keys (not on the Num Pad). When activated, the Scroll Lock LED will be lit.
What this mode does, is to create a more PC like experience when editing Basic and Assembler Editor source code files. For example; It allows you to cursor into the middle of a line of text, and then begin typing, with the text to the right automatically getting pushed forward to make space for the new text being entered. Also when back spacing within a line of text, characters to the right will automatically be pulled left as the character under the cursor is rubbed-out.
It is recommended that this mode only be turned on when needed for the stated purpose. Keep in mind that any application that performs a similar function as part of its programming, will simply get confused. So in other words; when running something like the "The Last Word" or "Atari Writer" please turn off the Insert Mode.
Keys With Special Codes
There are 3 keys that are mapped to unused cells in the keyboard matrix (4 if you are using an ISO keyboard). These keys will output a unique code either by themselves, or when pressed in combination with SHIFT and/or CTRL. These unique codes were intentionally mapped to PS/2 keys that have no equivalent on the Atari stock keyboard. They can be used for whatever you wish in a self written program, or may eventually find use in a commercial application.
XEGS/XEL/XLD Mode (7800 XM included)
When the TK-II was originally developed, it wasn't known at the time that certain motherboards were missing the pull-up resistors associated with the key response (KR) inputs of the Pokey chip. Without these resistors, ghost key presses are possible. Normally this isn't a problem if the stock keyboard is still attached, but this would not be the case for the XEGS version. So in order to correct this, a mode was created that would change from a floating output for the KR lines coming from the TK-II, into something more like a TTL output that had both a high and a low output state. Since the first system encountered that needed this fix was an XEGS, this was the reason it initially got called the XEGS Mode.
Note: If the stock keyboard is to be used in parallel with the TK-II, then the XEGS Mode should be set to OFF. This feature is toggled by pressing CTRL+ALT+X, with the last setting retained in non-volatile memory.
Later on it was discovered that a 1200XL without it's stock keyboard attached was also missing the KR pull-up resistors for Pokey. So if you plan on using the TK-II on your 1200XL without it's stock keyboard, you should toggle this feature ON (CTRL+ALT+X toggles it).
When the 1088XEL and the much newer 1088XLD were being developed, this mode was also employed to simplify the design and minimize the component count.
U1MB Enhanced Features
There are 3 function keys specifically designed to interact with the U1MB upgrade, and if present, the XEL-CF IDE board or it's XLD on-board equivalent. F9 when pressed inside of the Loader, will execute a hardware reset of the CF card attached to the system. The purpose of this is to reinitialize a 'Hot Plugged' CF card. Outside of the Loader, Reset (F8)+F9 will do the same thing (be sure to release F9 following the release of F8, and not before).
F11 will launch the Loader, and F12 will launch the U1MB Setup Menu where you can reconfigure the basic functionality of the U1MB upgrade. Also if F10 (Help) is pressed during the U1MB boot-up splash screen, this will also enter the Setup Menu.
1088XLD Enhanced Features
The TK-II firmware will automatically sense what kind of hardware the chip is being used in, and if it doesn't detect a 2nd keyboard port, it will revert to 1088XLD mode and use that port for other purposes. Meaning that the two extra bits normally associated with a 2nd PS/2 keyboard, are now used for Mouse Port selection and the Swap Disk function built into the U1MB 1088 BIOS and the Loader. For more information about the Swap Disk feature, check out flashjazzcat's U1MB User Manual listed on his U1MB 1088 page.
Navigation Keys (Arrows, Home, End, ect.)
Refer to this BLOG entry for more information.
Special Keys and Functions
*Normally keys that require CTRL+ALT to change their setting, are retained in non-volatile memory, to be restored upon power-up. However there is one exception in CTRL+ALT+A which only clears all arrow related settings instead.
Delayed Reset Release Feature V2.4 - V2.6 ONLY
If set to ON (toggled by CTRL+ALT+D), the reset is held for a extended period (measured in seconds) when the unit is first powered up, giving enough time for the PS/2 keyboard to fully initialize, and thereby have it's key presses registered by the Atari OS following the release of the extended reset. A useful aspect of this in action, is to disable internal Basic on an XL/XE system when powering up by holding Option (F7).
This feature is not required by either the 1088XEL or 1088XLD, and not even available from the later.
Option Boot/Game Boot
When these features are set to ON, they invoke an automatic held Option and/or Select key press during the power-up sequence. Option Boot will automatically disable Basic, and Game Boot (held Select key) will automatically switch to the built-in game on an XEGS.
The settings for these features are stored in non-volatile memory, and restored each time the system is subsequently powered on.
XL/XE Extended Key Map
When the 1200XL was introduced in 1982, it also came with a new OS that supported additional keys not present in the 400/800 series (F1-F4, and the Help key). The Function keys not only provided single key cursor control, but when used in combination with CTRL and SHIFT, they also added some very useful features.
1200XL OS Additional Keys
Although the 1200XL was a short-lived product, remnants of it's OS lived on into the size reduced XL and XE series machines. This also included the 1200XL's additional key assignments, which have found renewed use in the TK-II. Making it possible to support the PS/2 keyboard's navigation keys (Page Up, Page Down, Home, End). The Last Word an Atari 8-bit 80-column word processor fully supports these special navigation keys.
TK-II Electrical Details
The PIC16F1847 MCU is connected to POKEY's 6-Bit scan counter (K0-K5) and the Key Response lines (KR1-KR2), with the intention of synchronizing key events coming from the PS/2 keyboard with the POKEY key matrix scan counter.
The protocols are completely different, with PS/2 being a serial protocol, and POKEY an 8x8 switch matrix yielding 64 possible key codes, plus modifiers (SHIFT, CTRL, Break). The state of POKEY's counter when the KR1 line goes low, determines what switch in the matrix is closed. To a lesser degree this also applies to the modifier keys when KR2 goes low.
So the MCU monitors the POKEY's key scan counter as well as the PS/2 port, and when it has determined that a particular key has been pressed on the PS/2 keyboard, it waits for the count that matches this same key on the Atari, and brings the appropriate KR line low. Essentially acting as if it were a mechanical switch closure on an Atari keyboard. Due to the differences in mapping between the PS/2 keyboard vs. the Atari keyboard especially where symbols are concerned, requires that a bit of juggling be carried out to match things up properly.
Because of an early design concept that later got changed, up to two PS/2 keyboards can get connected, thus forming a very simple network. If the system also has the original stock keyboard attached, this will be seen in parallel to the TK-II via the same POKEY key scan lines, and be usable as one more keyboard in the network, allowing a maximum of three keyboards to access the same computer.
The diode connected across the CLK lines allows a common interrupt input to sense activity on either PS/2 port. Once activity has been sensed, the interrupt routine will then individually analyze each CLK line and focus attention on whichever one went low (PS/2 CLK and Data lines are open collector active low signals). When the MCU first powers up, it performs a test to see if the diode is present. If it's not, then the system will be reconfigured as a single PS/2 port, with the other two I/O lines now available for use by a 1088XLD (reference: 1088XLD Enhanced Features in the previous section).
Console and Reset Switches
There are four I/O pins on the MCU that control these functions. They get connected to the physical switches on the computer, preferably after the inline resistor that ultimately connects them to their destination. F5-F8 control these pins, with F5 = Start, F6 = Select, F7 = Option, and F8 = Reset. When not being pressed the outputs are floated, so as not to interfere with the original console and reset keys.