TMK IBM PCXT converter firmware

[hasu]

This won't be updated and supported actively anymore.
Use IBMPC converter instead. 2020-05-13
https://geekhack.org/index.php?topic=103648.0


TMK XT keyboard converter firmware is implemented carefully in conformity with design intention of original IBM XT keyboard interface to support virtually all of existent XT keyboards, I hope so at least..

The other day I used much time to look into XT keyboard protocol and believe I understand it enough now.
https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol

After the investigation I reimplemented TMK XT-USB converter and it needs to be tested with various XT keyboards you guys own. This firmware is compatible with Soarer's converter in terms of pin configuration, which uses PD0 for data line, PD1 for clock and PB7 for reset(optionally. Some keyboards needs.). In short you can use this firmware with Soarer's converter hardware.

Note
- This converter doesn't support external LEDs.

- Reset: Some keyboards like Zenith Z-150 need reset line to be initialized. In this case you have to connect keyboard into the converter before pluging it to host.

- You shouln't use this with Orihalcon's cable because it doesn't have flash button as far as I know.



REQUEST
Let me know by posting your result here! Thank you

what I want to know
- your keyboard identity
- whether it works or not
- whether reset line is connected to PB7 or not

when it doesn't work
1. Connect reset line to PB7 if not yet.
2. Post what 'hid_listen' shows. Refer these pages for 'hid_listen' tool.
https://www.pjrc.com/teensy/hid_listen.html
https://github.com/tmk/tmk_keyboard/wiki/FAQ#debug-console



REPORTS
Thank you for your support!
- Zenith Z-150: OK (Reset line is needed.)
- IBM PC/XT keyboard: OK
- Pravetz 16: OK


Firmware Download
You can download binary hex files for ATMega32u4 here. It should work on Teensy 2.0. (Pro Micro is NOT recomended for noobs because it has no pinout for PB7)

https://github.com/tmk/tmk_keyboard/tree/master/converter/xt_usb/binary


Source Code
https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/protocol/xt_interrupt.c
https://github.com/tmk/tmk_keyboard/tree/master/converter/xt_usb


Update
2018/04/17 New code is merged into master now.
2018/04/25 Keymap and scancode handling is changed.
2018/09/23 Update console print code and binary.
2018/10/06 Fix */PrtSc issue #552

[hasu]

anyone can help?

[jimirolln]

i recognized your tag from somewhere...it took a minute because i am new to keeb life but finally it came to me...the hasu controller...very impressive work and a major contribution to the community...a shining example that serving your community and community service are not the same...lulz

so i go checkn into this pcxt biz...bruh...i died...i know there are people into the vintage and i don't knock it...i just don't get it...thats ok...everything isn't for every body...and not to clown but if this is chilln in the collection for n e thing but nostalgia your in deep homie...god bless

for god sake someone with one of the relics help this man out

if this is wrong please forgive...much love...stay true

[hking0036]

I have an XT board lying around, unfortunately right now it's in pieces but when I get it back together I'll try it out (hopefully someone else gets on before then because it's still a while out, but I'll go ahead and start getting those springs back on the flippers now).

[pfoff]

No answer??? Sorry, I haven't seen this earlier.
Ok, I tested it with my IBM 1501101 XT Model F over a standard ProMicro(I have 1kOhm pullups on both channels, verified to work with my older tmk build and with soarer. It worked somehow, until I type faster. Than it goes out of control, when i type slower it seems to work reliably.
When it starts to fail some letters are missing and than it starts to behave undefinedly. It sends PgUp/Home and also ctrl key combinations that confused my screen session.
If you think I need bigger pullups I could try that also.
The hidlisten output is attached. 

[hasu]

Thanks for the test.
Did you use my prebuild binary or build it yourself?
When it is built with newer version of GCC it seems to go wrong for some reason.

1KOhm is enough strong, original XT host uses 4.7KOhm pull-ups afaik.

As for LED  its support will be added later in compatible with soarer's pin configuration. But it is not the time now. You can still use any unused pins to add LED and write code in led_set() of led.c. You can find sample code in gh60 or alps64 directories.

[pfoff]

I used your binary. But tomorrow(it's late in europe!) I can build it if you think that'd make a difference.
Forget about the leds, it was only ten lines to get them working, as your firmware has already all the states, great as always!!!
Btw: THNX for all the great work, almost all my keyboards run TMK now!

[hasu]

My binary was built with old stable GCC 4.9.2 and it works well for me.
But It didn't work for you so it should have a bug I missed somewhere.

[fer.real]

Hi Hasu,

I recently bought a couple of Zenith Z-150 keyboards off eBay.  One of them is the black label variant, which needs an active converter.  I searched for something that convert this XT-like protocal to USB and put a converter together on a breadboard with a teensy 2.0 and your binary.

The issue I'm having is that the keyboard with the converter will work initially, then gets a bit wonky.  After a short amount of use (about 30 seconds or so) I start getting repeated keystrokes.  Soon after that the controller will start sending keystrokes that I did not make.

I'm pretty sure I have the circuit set up correctly. I read that the Z-150 needs the reset line, so I have reset connected to B7.  I have 1K pull-up converters on Data, Clock and Reset pins.

The output of hid_listen is attached.  Please let me know if there is any more info that you need or if there is anything else I can do to help.

 hid_listen.txt (3.06 kB - downloaded 246 times.)

[hasu]

Thanks for testing.
Hmm, I can't see any useful info in the debug output unfortunately.

Can you try namato's converter and see diffrence? The converter hardware is compatible with this, you will be able to use its handy binary firmware.
https://github.com/namato/tmk_z150

[fer.real]

I am able to get the keyboard to work with Namato's fork.  Thanks for the help!

[hasu]

I am able to get the keyboard to work with Namato's fork.  Thanks for the help!

hmm, I guess handling start bit is cause of this problem, could you try attached firmeware and show hid_listen log taken when the converter goes bad?

Namato's is for Zenith and doesn't recoginise original XT keyboard unfortunately, and difference between his and my code is very very slight. My goal is to support both Zenith black and orignal IBM XT with one firmware build. It would be appreciated if you can help me!

Thanks

[fer.real]

Hi Again,

I've been using using the newest hex file you posted for a couple of days and I'm running into an issue.

The new firmware works great when I first plug the converter into the computer.  As long as the computer stays awake, I no longer have any of the random keypresses or repeating keys.

Problems start when my laptop wakes from sleep or hibernation.  As soon as it wakes up, the converter starts sending repeating keystrokes.  If I unplug and reattach the USB cable, the converter works fine again.

Attached is the output of hid_listen after the computer woke from sleep.
 hid_listen2.txt (0.84 kB - downloaded 231 times.)

Thanks again!

[catfud]

Hello there, I recently obtained a Zenith Z 150 XT and am reporting that your most recent hex file seems to work just fine. I am not experiencing issues with wake up from sleep like fer.real mentioned. FWIW I am on a Mac, and am using teensy with the reset pin wired in. I will test out the converter and report back if I notice anything. Just an fyi

Thanks for another awesome project hasu!

[hasu]

Hello there, I recently obtained a Zenith Z 150 XT and am reporting that your most recent hex file seems to work just fine. I am not experiencing issues with wake up from sleep like fer.real mentioned. FWIW I am on a Mac, and am using teensy with the reset pin wired in. I will test out the converter and report back if I notice anything. Just an fyi

Thanks for another awesome project hasu!

catfud, good to know, thanks for testing.
Though, I guess it goes wrong after long session in the end as fer.real and others reported. I'll have to fix firmware anyway.

Hi Again,

I've been using using the newest hex file you posted for a couple of days and I'm running into an issue.

The new firmware works great when I first plug the converter into the computer.  As long as the computer stays awake, I no longer have any of the random keypresses or repeating keys.

Problems start when my laptop wakes from sleep or hibernation.  As soon as it wakes up, the converter starts sending repeating keystrokes.  If I unplug and reattach the USB cable, the converter works fine again.

Attached is the output of hid_listen after the computer woke from sleep.
(Attachment Link)

Thanks again!

fer.real, sorry for very late response.
The console log is not from my firmware, it is probably log from namato's.

A few months ago I found verly likely culprit for missing signal from keyboard, it is 'console output' feature which can take long to process debug prints and block signal reading routine in the result. This depends a lot on timing of code execution and I think namato's suffers from same probelm too, even if it is rarely and diffrent appearance.

I will have to update 'console output' code to fix the issue on XT converter. I'll post here when I get some progress.

[hasu]

[Update firmeare]

I fixed TMK core code related to console output and updated binary of the converter. WIth this fix I think debug prints don't cause signal handling anymore, in fact in my test I didn't see any key drop or queerness so far.

You can download the latest binary here. Post your result here.
https://github.com/tmk/tmk_keyboard/tree/master/converter/xt_usb/binary

[catfud]

Awesome, thank you again Hasu! I've downloaded and will test again.

I haven't run into issues with your previous build but I do unplug my computer to use away from my desk frequently so possibly that is why. I will try to use for a longer period of time with the same computer.

[catfud]

Hi hasu,

I've started poking around a little more, and had a question about the keymap feature for xt_usb converter. I tried creating a new keymap like below, very simple just converting both 'LCTL' and 'LALT' to 'LGUI' as a test.
However when I run "make clean && make KEYMAP=test" and load the outputted xt_usb.hex onto my teensy, I don't see anything changed - LCTL and LALT are both functioning as LCTL and LALT.

Here is my keymap_test.c
https://github.com/lkjl/playground/blob/master/keymap_test.c

And here is the output of "make KEYMAP=test"
https://github.com/lkjl/playground/blob/master/out.txt

I am on a Zenith Z-150 XT running through a Teensy 2.0. Wondering if I missed a step somewhere?
Thank you in advance...

[hasu]

It seems to be correct as for building process, I guess you missed something when flashing.
With your keymap I confirmed compiled firmware works as you described.

Does the binary work with your Zenith?
https://github.com/tmk/tmk_keyboard/tree/master/converter/xt_usb/binary

[catfud]

Yes, your binary works just fine with my zenith and all the keys function as expected.

You were right about something missing when I was flashing, I just realized this "unreadable" error was showing up when I tried to load my modified hex file in the Teensy loader:


And actually I can't even load the hex file for the default version hex generated by "make" with no keymap. Possibly something's screwed up with my environment (ie. avr-gcc) so make is creating a bad hex? I have no issue loading your hex file via the teensy loader
Here's the output file
https://github.com/lkjl/playground/blob/master/xt_usb.hex

I pulled avr-gcc off of osx-cross tap via brew as per https://github.com/tmk/tmk_keyboard/wiki#build-on-mac though, and I don't see anything fishy in the console output.

[hasu]

Someone got trouble with newer GCC toolchain of Mac brew for some reason, it seems that homebrew tends to use too  bleeding edge version of GCC like 8, o_Owow.

https://github.com/tmk/tmk_keyboard/issues/576

You will be safe to stick with ollder version 5. I'm still sticking with too old 4.9.2  but I confirmed gcc 5 also works on ubuntu 18.04.

EDIT:
perhaps, you can install older version 5 like: $ brew install avr-gcc@5
https://github.com/osx-cross/homebrew-avr#installing-homebrew-avr-formulae

[catfud]

Wow, that's bingo! I grabbed avr-gcc@4 (so same major version as you) and the generated hex files loads to the teensy without problems now. I can get keymaps working too which is exciting.
Next steps, I'll try playing around with layers haha.

Thanks again hasu! I'll remember to look through the github issues pages next time I face an issue.

[catfud]

Good news, layers works just as expected for me!...for the most part.
I noticed that if I map the FN key to the Prt Sc key on my zenith (the right side of the split right shift key), the layer does not work.

Looking more closely, I noticed that even with the default keymap the Prt Sc is actually not even spitting out any scan codes. I've checked with the Key Codes mac app and on online keyboard testers, and it seems that pressing the key is not doing anything.
I don't think the switch is broken though, because the piezo beeper goes off when pressing down on the Prt Sc key (but I could be wrong).

Wondering what kind of data points I can provide to help investigate this. I found this thread but it doesn't seem to be the same issue.
https://github.com/tmk/tmk_keyboard/issues/552

[hasu]

Use 'hid_listen' to see scan codes from keyboard. See first post for the tool, plz.

Can you check scan code keyboard sends in following cases?
1) pressing Prt Sc
2) pressing Prt Sc with holding Shift
3) pressing Prt Sc with turning Numlock on


I think this is identical to the issue you linked, it seems that I missed something and failed to fix for PrtSc/* key.

[catfud]

Sorry, should have rtfm. Here is what I see, using the latest binary you shared:

1) "37 B7"
2) "36 37 B7 B6"
3) "45 C5 37 B7"

[hasu]

Sorry, should have rtfm. Here is what I see, using the latest binary you shared:

1) "37 B7"
2) "36 37 B7 B6"
3) "45 C5 37 B7"

Thank you for the info!
I just pushed this commit to github repo to fix the issue, can you try new binary(or source)?
https://github.com/tmk/tmk_keyboard/commit/594d7d85da35637b3757fc0948e007358b57c72f
https://github.com/tmk/tmk_keyboard/tree/master/converter/xt_usb/binary

With default keymap the */PrtSc key should send 'Keypad *' now.

[catfud]

Worked like magic 
The Prt Sc key now sends * with the default keymap, and I can remap it to a FN0 layer key. Working as expected!

Thanks again for being so quick and responsive with my questions. I am excited to be typing away on a fully enabled Zenith Z-150.

[hasu]

catfund,
Great. Thank you for your support!

[hasu]

It confirmed that the converter work with Pravetz 16 keyboard!
https://github.com/tmk/tmk_keyboard/pull/578#issuecomment-433504608

Pravetz 16 is Bulgarian IBM PC/XT clone computer. Its keyboard has two specific keys for Cyrillic support. The keys marked as 'C/L Lock' and 'C/L' spits out 0x55 and 0x54 rescpectively.




Still need more tests with various XT keyboards to improve its firmware. I'd  appreciate if you can help. Check first post. Thanks.

[youxiaojie]

dear author , I got a keyboard and use oscilloscope to analyze the signal and find it use xt protocol but with a different scancode set, how to change your code ? thanks .
BTW, is your code suitable for teensy 2?

[hasu]

dear author , I got a keyboard and use oscilloscope to analyze the signal and find it use xt protocol but with a different scancode set, how to change your code ? thanks .
BTW, is your code suitable for teensy 2?

what's your keyboard model number? Posting your keyboard pics would be appreciated.
Yes, Teensy 2 works with this firmware. Try it first and see what happens.

EDIT: And can you rephrase how different its scancodes are? It seems to me to be normal XT scancodes.

[youxiaojie]

it is a lk201-like keyboard
the make scancode by oscilloscope as follows
down edge trigger

keys   wave      (bin)   (hex)
f1.png   01110111   0111011   3B
f2.png   01111001   0111100   3C
f3.png   01111011   0111101   3D
f4.png   01111101   0111110   3E
f5.png   01111111   0111111   3F
f6.png   10000001   1000000   40
f7.png   10000011   1000001   41
f8.png   10000101   1000010   42
f9.png   10000111   1000011   43
f10.png   10001001   1000100   44
f11.png   00000011   0000001   01
f12.png   11001001   1100100   64
f13.png   11001011   1100101   65
f14.png   11001101   1100110   66
top-help.png   11001111   1100111   67
top-do.png   11010001   1101000   68
f15.png   11010011   1101001   69
f16.png   11010101   1101010   6A
f17.png   11010111   1101011   6B
f18.png   11011001   1101100   6C
         
`.png   01010011   0101001   29
1.png   00000101   0000010   02
2.png   00000111   0000011   03
3.png   00001001   0000100   04
4.png   00001011   0000101   05
5.png   00001101   0000110   06
6.png   00001111   0000111   07
7.png   00010001   0001000   08
8.png   00010011   0001001   09
9.png   00010101   0001010   0A
0.png   00010111   0001011   0B
-.png   00011001   0001100   0C
=.png   00011011   0001101   0D
backspace.png   00011101   0001110   0E
tab.png   00011111   0001111   0F
q.png   00100001   0010000   10
w.png   00100011   0010001   11
e.png   00100101   0010010   12
r.png   00100111   0010011   13
t.png   00101001   0010100   14
y.png   00101011   0010101   15
u.png   00101101   0010110   16
i.png   00101111   0010111   17
o.png   00110001   0011000   18
p.png   00110011   0011001   19
[.png   00110101   0011010   1A
].png   00110111   0011011   1B
return.png   00111001   0011100   1C
ctrl.png   00111011   0011101   1D
lock.png   01110101   0111010   3A
a.png   00111101   0011110   1E
s.png   00111111   0011111   1F
d.png   01000001   0100000   20
f.png   01000011   0100001   21
g.png   01000101   0100010   22
h.png   01000111   0100011   23
j.png   01001001   0100100   24
k.png   01001011   0100101   25
l.png   01001101   0100110   26
;.png   01001111   0100111   27
'.png   01010001   0101000   28
backslash.png   01010111   0101011   2B
shift-l.png   01010101   0101010   2A
less-than.png   01101111   0110111   37
z.png   01011001   0101100   2C
x.png   01011011   0101101   2D
c.png   01011101   0101110   2E
v.png   01011111   0101111   2F
b.png   01100001   0110000   30
m.png   01100011   0110001   31
n.png   01100101   0110010   32
,.png   01100111   0110011   33
..png   01101001   0110100   34
slash.png   01101011   0110101   35
shift-r.png   01101101   0110110   36
compose.png   10101001   1010100   54
space.png   01110011   0111001   39
         
edit-find.png   10101011   1010101   55
edit-insert.png   10101101   1010110   56
edit-remove.png   10101111   1010111   57
edit-select.png   10110001   1011000   58
edit-prevscr.png   10110011   1011001   59
edit-nextscr.png   10110101   1011010   5A
arrow-u.png   10110111   1011011   5B
arrow-l.png   10111001   1011100   5C
arrow-d.png   10111011   1011101   5D
arrow-r.png   10111101   1011110   5E
         
num-0.png   10100101   1010010   52
num-1.png   10011111   1001111   4F
num-2.png   10100001   1010000   50
num-3.png   10100011   1010001   51
num-4.png   10010111   1001011   4B
num-5.png   10011001   1001100   4C
num-6.png   10011011   1001101   4D
num-7.png   10001111   1000111   47
num-8.png   10010001   1001000   48
num-9.png   10010011   1001001   49
num-pf1.png   10111111   1011111   5F
num-pf2.png   11000001   1100000   60
num-pf3.png   11000011   1100001   61
num-pf4.png   11000101   1100010   62
num-dot.png   10100111   1010011   53
num-enter.png   11011011   1101101   6D
num-,.png   11000111   1100011   63
num--.png   10010101   1001010   4A

[youxiaojie]

the  guoguang (国光 ) is xt can be used with tmk xt to USB.
 the scancode is differ from the first which brand as "start" . Edit area arrow keys and function keys.later paste it.

[youxiaojie]

btw,I want to use xt keyboard and ps2 122key in raspberry pi with gpio, can you help me?give a thought?

[hasu]

You probably read wave forms wrongly. The  pics of oscope you posted show exactly valid XT signals, release A(8E) and release Z(AC). To learn XT protocol see wiki page on GitHub you can find in the first post.

The keyboard should work with this converter, try it.

BTW, does the keyboard have any label which shows model number?

Tapatalk を使用して私の WAS-LX2J から送信

[hasu]

btw,I want to use xt keyboard and ps2 122key in raspberry pi with gpio, can you help me?give a thought?

I don't think it is preferable due to its voltage but it is possible and you can do what you want.
I don't  know raspberry pi and have no time to help you for that, though.

[youxiaojie]

"You probably read wave forms wrongly. "? NO,I am sure, take a's wave for example, the leftest 1 on wave is the signal 1,only one bit, and the the rightest 1 is for release and 0 for press so the picture is release wave code , written down direction-reversely,  is "(0or1)00111101" (last significant bit send first) and the true 8bit is 00011110,so 1E for make.
 I mean do help compose etc keys' code is not standard.how to deal?
and the soarer's converter does not recognise single start bit, it eat additional 1 bit from data.

[youxiaojie]

the keyboard has no model, but the pcb has, start is hy05b, 国光(guoguang) is hy5001 both are 4 wires no reset wire

[youxiaojie]

this start (shida in chinese) works but the edit area and arrows are malfunction. is there method to remap the function? and, is there method to add external light control?

the guoguang(国光)'s special scancode differ from start
GUOGUANG

 
pf1 61 E1
pf2 62 E2
pf3 63 E3
pf4 64 E4
editfind 65 E5
editinst 66 E6
editremo 67 E7
editsele 68 E8
editprvs 69 E9
editnxts 6A EA
f1 6B EB
f2 6C EC
f3 6D ED
f4 6E EE
f5 6F EF
f6 70 F0
f7 71 F1
f8 72 F2
f9 73 F3
f10 74 F4
f11 75 F5
f12 76 F6
f13 77 F7
f14 78 F8
help 79 F9
do 7A FA
f17 7B FB
f18 7C FC
f19 7D FD
f20 7E FE

, 54 D4
. 55 D5
less-than 56 D6
compose 59 D9
NUM-, 5A DA
NUM-ENTER 5F DF
arrow-u 5B DB
arrow-l 5E DE
arrow-d 5C DC
arrow-r 5D DD

[hasu]

So you mean the converter can recognize signals from  both START and 国光 keyboard while the keyboards use different or special scan codes for some keys?

Great. You can edit unimap.c and build with Makefile.unimap to remap the keys.

Reffer unimap-common.h to know which scan codes map to a key in unomap.c. For instance scan codes 7E is recognized as PCMM(keypad comma) and you can remap it with editing PCMM part in unimap.c.

[youxiaojie]

thanks.  Do you expert in tmk  terminal to USB converter? why it changes PD0 PD1 to PD2PD5? Is there precompiled hex file? Thanks

[youxiaojie]

thanks.sure the xt converter recognize it.I try it as you said later.Do you expert in tmk  terminal to USB converter? why it changes PD0 PD1 to PD2PD5? Is there precompiled hex file? Thanks