Handwired + Teensy + QMK = Confused

User avatar
hellothere

02 Dec 2020, 20:03

So, I have three keyboards that use odd protocols. They're all former terminal keyboards. The recommendation made to me is to map out the keyboard matrix and use a Teensy in place of the onboard controller. I found this post for wiring, but I have several questions:

* Do I even need to do this? I would like to make any changes I make easily reversible.
* If I do have to do all the hand wiring, can I use all the switches in the keyboard as-is and just solder the new wires/diodes on top of them? I'm essentially asking if adding wires to the switches mounted in the keyboard would cause a problem (short, magic smoke escapes, death, etc.) because of the existing circuit traces.
* With the ribbon cable mentioned in the link, do you just wire one "line" on the ribbon cable to the Teensy, except the ones that the author says are not a good idea to wire to?
* How am I supposed to create the firmware? On the QMK websites, I see a bunch of entries for "handwired," but it only lists things like "handwired + dactyl."

Thanks for your time!

kelvinhall05

03 Dec 2020, 03:03

1. It's the easiest option unless you have the tools, knowledge, and experience to reverse engineer a protocol and write firmware to convert it.
2. You don't need to bypass the old matrix. That's extremely messy and always looks terrible and takes far too long. Instead, remove any old ICs and any other necessary components and wire your controller in there like this:
Spoiler:
IMG_20201104_174810.jpg
IMG_20201104_174810.jpg (2.14 MiB) Viewed 10250 times
3. N/A because his method is stupid and you should use the one I showed above.
4. Use kbfirmware.com if you want an easy but relatively slow GUI, or a text editor and fresh QMK config if you know how (will be faster if you know how, as is almost always the case with text editing/CLI methods over GUI ones).

Feel free to ask any questions. I've done several of these myself and helped with many others.

User avatar
hellothere

03 Dec 2020, 04:27

First, thanks for the reply. You've also commented on a couple other threads I was posting in.

I think I'm starting to understand what's going on with things like the post I referenced. I'm a lot better looking at physical components and going from there.

So, I have a photo attached of two random "columns" of switches and where they connect on the controller, highlighted in red dry-erase marker (I wiped it off after I was finished). Multimeter reads full continuity for each column. There are two places where there are soldered wires on the top of the PCB and there's a little "break" on the bottom of the PCB. Those are the little breaks in about the top middle and bottom.
Spoiler:
IMG_1306.JPG
IMG_1306.JPG (2.95 MiB) Viewed 10239 times
So, does that mean that I could then just attach a wire from the top ("north" side) of the board right to the Teensy? I think the existing controller has 40 leads. Maybe the problem I have is that I don't really see what needs to be connected to a Teensy to make the PCB I'm showing work.

============

I'd like to get QMK to work. I'm also struggling to get that up and running, but in the QMK case, I just have to find some directions that aren't 11 years old.

kelvinhall05

03 Dec 2020, 04:53

I will give more info tomorrow but you'd likely end up using 20-25 IO pins as the 40 on the main controller are not all used. Only a few will be for IO.


But you've mapped those two columns correctly. I can suggest some faster methods tomorrow morning. I could also help with QMK once you're at that step. Please send full pics of both sides of the PCB and any chips on it.

User avatar
hellothere

03 Dec 2020, 16:57

Thanks! Working on it.

User avatar
hellothere

03 Dec 2020, 17:13

Moar pics.
Spoiler:
IMG_1314a.JPG
IMG_1314a.JPG (2.44 MiB) Viewed 10175 times
IMG_1313a.JPG
IMG_1313a.JPG (2.44 MiB) Viewed 10175 times
IMG_1312 (2).JPG
IMG_1312 (2).JPG (852.62 KiB) Viewed 10175 times
IMG_1311a.JPG
IMG_1311a.JPG (3.54 MiB) Viewed 10175 times
IMG_1310a.JPG
IMG_1310a.JPG (2.86 MiB) Viewed 10175 times
IMG_1309a.JPG
IMG_1309a.JPG (2.89 MiB) Viewed 10175 times
IMG_1308a.JPG
IMG_1308a.JPG (2.64 MiB) Viewed 10175 times
IMG_1307 (3).JPG
IMG_1307 (3).JPG (1.25 MiB) Viewed 10175 times
IMG_1315a.JPG
IMG_1315a.JPG (2.52 MiB) Viewed 10175 times

kelvinhall05

03 Dec 2020, 20:05

Oh this is a really easy one. Rows are red, columns are blue. Remove all components on the board except for jumpers and diodes and then solder your Teensy in so that all the rows and columns go to io pins (making sure you note which row/column goes to which io pin).

You will also have to map matrix and find which key is on which row and column.
Spoiler:
IMG_1307 (3).JPG
IMG_1307 (3).JPG (2.93 MiB) Viewed 10147 times

User avatar
hellothere

03 Dec 2020, 23:18

If you don't mind, I'll try to map a row and column or two, just so you can check me before major component removal.

User avatar
hellothere

04 Dec 2020, 02:13

OK. Here's a continuity map. All those black circles and ovals are feeding off that first pin on the controller marked in blue. Did you get columns and rows backwards or am I looking at something incorrectly?

a. Yes, I erased part of the pic.
b. Yes, I know I have great talent in working with Microsoft 3D Paint.
Spoiler:
IMG_1307 (3) - Modified.jpg
IMG_1307 (3) - Modified.jpg (922.46 KiB) Viewed 10108 times

kelvinhall05

04 Dec 2020, 02:36

hellothere wrote:
04 Dec 2020, 02:13
OK. Here's a continuity map. All those black circles and ovals are feeding off that first pin on the controller marked in blue. Did you get columns and rows backwards or am I looking at something incorrectly?

a. Yes, I erased part of the pic.
b. Yes, I know I have great talent in working with Microsoft 3D Paint.
Spoiler:
IMG_1307 (3) - Modified.jpg
That looks good. Rows and columns aren't necessarily backwards, I just labeled them the way QMK does, if that makes sense. Point is that it doesn't matter, basically just there to differentiate them and potentially save you two seconds when testing firmware (as you might have to "reverse diode direction" in the firmware).

Also I made a slight mistake when colouring the pins you're supposed to use. The red pin circled in blue is not used for the matrix.
Spoiler:
Screenshot_20201203_203316.png
Screenshot_20201203_203316.png (235.46 KiB) Viewed 10102 times

User avatar
hellothere

04 Dec 2020, 17:12

No problem. You're being extremely helpful and this will definitely help other folks that want to get their esoteric keyboards up and running.

Anakey

04 Dec 2020, 19:04

That is almost the perfect board for replacing the controller in given it is mostly single sided and also has diodes so you will not have the keypress limit and also should have a fairly logical order. What i find helpful is to draw the layout of the board itself and the connections to the old controller then number the rows/columns starting at 0. As you test continuity between the switch pad and the trace where the controller is write down on the layout the row/column numbers, this way each key will have a different combination of row/column which can then be put into kbfirmware to then generate a working hex file to then flash to the new controller

kelvinhall05

04 Dec 2020, 19:22

Anakey wrote:
04 Dec 2020, 19:04
That is almost the perfect board for replacing the controller in given it is mostly single sided and also has diodes so you will not have the keypress limit and also should have a fairly logical order. What i find helpful is to draw the layout of the board itself and the connections to the old controller then number the rows/columns starting at 0. As you test continuity between the switch pad and the trace where the controller is write down on the layout the row/column numbers, this way each key will have a different combination of row/column which can then be put into kbfirmware to then generate a working hex file to then flash to the new controller
The vast majority of boards from this era used single-sided PCBs, and if they don't have diodes it takes two seconds to define MATRIX_HAS_GHOST or whatever in QMK. From my experience, OP has a fairly average board. Tiny bit worse than average because of the assumptions I had to make about the chips on it as I couldn't find a datasheet for the main chip (likely an Intel 8048/49/50 or clone/compatible, as were most of the boards from this era) and had trouble finding a decent datasheet for the decoder chip used for some of the columns.

User avatar
hellothere

05 Dec 2020, 17:15

I'm getting there!
Spoiler:
Rows.jpg
Rows.jpg (988.74 KiB) Viewed 9973 times
Thinking down the line a bit, is there a recommended controller? I know the Pro Micros that I have lying about for Soarer's Converters (I like IBM Model Ms) won't work.

kelvinhall05

05 Dec 2020, 17:19

hellothere wrote:
05 Dec 2020, 17:15
I'm getting there!
Spoiler:
Rows.jpg
Thinking down the line a bit, is there a recommended controller? I know the Pro Micros that I have lying about for Soarer's Converters (I like IBM Model Ms) won't work.
Teensy 2.0. 32u4-based so it'll be super easy to get QMK on it, and it has all the IO you need. It's overpriced as fuck (28 CAD, whatever that is in USD) unless you're willing to wait 28 years for one to arrive from China. If you want it soon, I'd grab it from Digikey and fill your cart with other stuff while you're there, as is tradition (for me anyway).

User avatar
hellothere

06 Dec 2020, 16:49

kelvinhall05 wrote:
05 Dec 2020, 17:19
hellothere wrote:
05 Dec 2020, 17:15
I'm getting there!
Spoiler:
Rows.jpg
Thinking down the line a bit, is there a recommended controller? I know the Pro Micros that I have lying about for Soarer's Converters (I like IBM Model Ms) won't work.
Teensy 2.0. 32u4-based so it'll be super easy to get QMK on it, and it has all the IO you need. It's overpriced as fuck (28 CAD, whatever that is in USD) unless you're willing to wait 28 years for one to arrive from China. If you want it soon, I'd grab it from Digikey and fill your cart with other stuff while you're there, as is tradition (for me anyway).
I purchased two from Adafruit. $16 US each with $11 shipping. The ones from Digikey were $19 a piece. I was surprised that there weren't ones on Amazon. There were a lot of Pro Micro clones, tho.

I'm still working on mapping. The numeric keypad and a section of switches immediately to the right of that is giving me some problems.

User avatar
Quartz64

06 Dec 2020, 20:25

Good news: your PCB is quite easily traceable and has 8x16 matrix with diodes (ROW2COL direction in terms of QMK).
Bad news: you need 16+8=24 IO pins to drive it. Pro Micro has only 18 and Teensy 2.0 has 21 (AFAIR). The good choise for this project would be WeAct STM32F401. It's supported by QMK, has enough IO, USB Type C, ready to use DFU bootloader and it costs less than $5.

If you already know where your columns and rows go, then you don't need to trace every key in matrix. Use matrix debug mode in QMK. So all this conversion can be done quite quickly. Just desolder all the ICs, capacitors and resistor arrays.

If you aren't familiar with 'layout', 'keymap' and other basic concepts of QMK, I can help with the firmware and specific MCU. Do you have a photo with keycaps installed?
Edit: matrix is 16x8, not 15x8
Last edited by Quartz64 on 07 Dec 2020, 16:04, edited 1 time in total.

kelvinhall05

06 Dec 2020, 20:29

Quartz64 wrote:
06 Dec 2020, 20:25
Good news: your PCB is quite easily traceable and has 8x15 matrix with diodes (ROW2COL direction in terms of QMK).
Bad news: you need 15+8=23 IO pins to drive it. Pro Micro has only 18 and Teensy 2.0 has 21 (AFAIR). The good choise for this project would be WeAct STM32F401. It's supported by QMK, has enough IO, USB Type C, ready to use DFU bootloader and it costs less than $5.

If you already know where your columns and rows go, then you don't need to trace every key in matrix. Use matrix debug mode in QMK. So all this conversion can be done quite quickly. Just desolder all the ICs, capacitors and resistor arrays.

If you aren't familiar with 'layout', 'keymap' and other basic concepts of QMK, I can help with the firmware and specific MCU. Do you have a photo with keycaps installed?
The teensy has 26 io pins and running qmk on an stm32 is a pita iirc. It costs less than $5 if you're willing to wait for it to ship from China. I have yet to find one readily available in NA for that little.

User avatar
Quartz64

06 Dec 2020, 20:44

Sorry, my memory fails me. Teensy 2.0 will suit fine then

User avatar
hellothere

06 Dec 2020, 20:50

Don't scare me like that, dude! :D

User avatar
hellothere

06 Dec 2020, 20:58

Quartz64 wrote:
06 Dec 2020, 20:25
If you aren't familiar with 'layout', 'keymap' and other basic concepts of QMK, I can help with the firmware and specific MCU. Do you have a photo with keycaps installed?
I'm very shaky on the whole thing. So, I don't mind more info.

Keyboard pic attached.
Spoiler:
DSC_0272S.jpg
DSC_0272S.jpg (242.01 KiB) Viewed 9879 times

User avatar
Quartz64

07 Dec 2020, 12:04

So, here is the firmware (my fork of QMK repo, the code is in keyboards/handwired/cumulus) and brief guide:
  1. Install QMK toolchain (docs), and use my QMK branch from the above link.
  2. Teensy 2.0 mounting position, view from the bottom side of the PCB. Columns 0–9 and rows 0–3 are already aligned nicely to the pins of the Teensy. You need some additional wire bridges to connect the last six columns (A–F) from another area of the board and 4 rows.
  3. Build debug firmware first:

    Code: Select all

    make handwired/cumulus:debug
    It has LAYOUT_debug macro (see cumulus.h) which describes 16x8 matrix with all positions active. On top of it there is keymaps/default/keymap.c (logical layout). All keys in this keymap don't output any keycodes (they all set to KC_NO), but there is debugging code in process_record_user function that prints row and column numbers of a pressed key to a console.
    Flash this FW to the Teensy, launch QMK Toolbox and start pressing keys. You should see something like this:

    Code: Select all

    HID console connected: Hellothere Cumulus
    > row 5, col: 4, pressed: 1
    > row 5, col: 4, pressed: 0
    > row 2, col: 6, pressed: 1
    > row 2, col: 6, pressed: 0
    
  4. Find LAYOUT macro in the beginning of cumulus.h file and replace rows and column keys (K00, K01, etc.) in first half of the macro with real key coordinates from the console. Example: row 5, col: 4 corresponds to K54; row 2, col 11 corresponds to K2B, etc.
  5. Edit the second part of the macro (enclosured in curly braces): replace every key definition which is absent in the 1st part with XXX. The meaning of this: 16x8 matrix has 128 keys, but our keyboard has 111 keys, so we must exclude keys which doesn't have any position in the matrix.
  6. Open config.h, find Bootmagic Lite key configuration section on the bottom of this file and write row and column of the top left key of your keyboard (the one with Reset/Break legend). You can use this to reset your Teensy to the bootloader (normally you use the button on the Teensy for this): to trigger the bootloader, you hold this key down when plugging the keyboard in.
  7. Compile and flash the normal FW:

    Code: Select all

    make handwired/cumulus:default
  8. Use keymaps/default/keymap.c as a template to create your own keymap
Edit: typos

User avatar
hellothere

08 Dec 2020, 22:26

QMK, if there was such a thing as Deskthority Gold, I'd send some your way.

Question that's probably an obvious answer, but I want to make sure, anyway: a VirtualBox Linux VM is OK to use, right? I do have a couple other machines that I could install a full version of Linux, if necessary.

Second, because I was confusing myself when doing rows and columns, I numbered the key "holes" on the PCB: 114. I don't think that changes #5. It just means I have fewer exclusions, right?

I'm about 75% finished coming up with the rows and columns. The number pad and some keys surrounding that are giving me fits.

kelvinhall05

08 Dec 2020, 22:30

hellothere wrote:
08 Dec 2020, 22:26
QMK, if there was such a thing as Deskthority Gold, I'd send some your way.

Question that's probably an obvious answer, but I want to make sure, anyway: a VirtualBox Linux VM is OK to use, right? I do have a couple other machines that I could install a full version of Linux, if necessary.

Second, because I was confusing myself when doing rows and columns, I numbered the key "holes" on the PCB: 114. I don't think that changes #5. It just means I have fewer exclusions, right?

I'm about 75% finished coming up with the rows and columns. The number pad and some keys surrounding that are giving me fits.
Don't do it with a text editor for your first time making a custom QMK config. It will be frustrating and confusing. Use kbfirmware.com or just post a keyboard layout editor .json here along with your wiring and matrix map.

User avatar
hellothere

08 Dec 2020, 22:40

Gotcha. Thanks.

User avatar
Quartz64

09 Dec 2020, 08:51

hellothere wrote:
08 Dec 2020, 22:26
a VirtualBox Linux VM is OK to use, right? I do have a couple other machines that I could install a full version of Linux, if necessary.
Linux isn't necessary to compile QMK, Windows with MSYS2 works without any problem.
hellothere wrote:
08 Dec 2020, 22:26
Second, because I was confusing myself when doing rows and columns
I have swapped columns and rows, i.e. I treat the pins marked "columns" on your photo as rows and vice versa, just for convenience
hellothere wrote:
08 Dec 2020, 22:26
I numbered the key "holes" on the PCB: 114. I don't think that changes #5. It just means I have fewer exclusions, right?
Take a look at the the photo from the front side. Your keyboard has 111 keys in this particular layout. Those additional mounting holes.are for other layouts. E.g.: your actual bottom row has 9 keys, but has 11 switch mounting holes on the PCB.
hellothere wrote:
08 Dec 2020, 22:26
I'm about 75% finished coming up with the rows and columns. The number pad and some keys surrounding that are giving me fits.
When you have found row/column pins you don't need to trace every switch on a PCB with graphical editor or multimeter. All you need to do is use matrix debug facility of QMK (see my previous answer). Exclusions: 1) Extremely messy PCB layout 2) Some layout modifications needed (e.g. changing a connection of some keys to a matrix) 3) Adding diodes (for that you need to know which pin of a switch connected to row or column.

Just flash the "debug" firmware first, open the console, press every key row by row, write down their row and column numbers to cumulus.h, to the 1st half of #define LAYOUT) and exclude row/col matrix positions which aren't used by your keyboard from the 2nd part of this macro by replacing a corresponding "Kxx" with "KC_NO" or "XXX".

User avatar
Quartz64

09 Dec 2020, 09:05

P.S. Multi-unit vertical keys (2U "Tab" and 3U "=" on this keyboard's numpad) are considered to be on the same row with their top part. E.g. 3U "=" key is placed in the same logical row as "4", "5", "6" and "," keys (see cumulus.h).
P.P.S. Precompiled debug firmware.

User avatar
hellothere

12 Dec 2020, 20:54

I just got in the Teensys. Teensies? Something like that.

User avatar
hellothere

16 Dec 2020, 23:33

Regardless of whether it's really needed or not, I did ~ mostly ~ finish up mapping row and column matrices. It's got a couple problems, but it took a rather long time to even get to this far, so ...
Spoiler:
Rows-Final.jpg
Rows-Final.jpg (1.08 MiB) Viewed 9393 times
Columns-Final.jpg
Columns-Final.jpg (1.01 MiB) Viewed 9393 times
KeyI.jpg
KeyI.jpg (1.05 MiB) Viewed 9393 times
KeyII.png
KeyII.png (686.92 KiB) Viewed 9393 times
a) Forget about the "handwritten" rows and columns notations. I did it the other way around, as mentioned in an above post.
b) Key #2 is for more columns.

Quartz64, if I understand you correctly, it's only necessary to know that something like pin A on the controller maps to row A, right? If that's the case, that makes life an awful lot easier.

User avatar
Quartz64

17 Dec 2020, 16:09

Update:
Looks like this "Cumulus" keyboard represents the case when there is real need to trace all the matrix manually (visually). I've done this in Photoshop (file) and here are my findings:
  • Matrix is 17x9, not 16x8 as we expected from the initial brief look.
  • There are two pairs of keys that connected in parallel: "Shift" and "Extend Char". It will be good to separate them.
Good news: three columns and one row are almost empty, so we can move some of the keys to a new positions in the matrix and pack it in 14x8. There is 111 physical keys, new matrix gives us 14x8=112 positions, so it fits perfectly.
Five keys need to be moved to another rows/colums: Ctrl (the key between Caps and A), Left Shift, Left Ext Char, Right Shift, Right Ext Char.

I have updated cumulus.h, take a look at it. Tomorrow I'm going to add some additional layers to that Photoshop file with proposed Teensy 2.0 pinout and where to cut/reconnect the traces.

Post Reply

Return to “Keyboards”