iCE40/yosys - [no description]

	Commit message (Expand)	Author	Age	Files	Lines
*	Clean whitespace and permissions in techlibs/intel	Larry Doolittle	2017-10-05	1	-4/+4
*	Adding Cyclone IV (E, GX), Arria 10, Cyclone V and LPM functions (ALTPLL and ...	dh73	2017-10-01	1	-0/+65

# Hand-Wiring Guide ## Preamble: How a Keyboard Matrix Works (and why we need diodes) The collapsible section below covers why keyboards are wired the way they are, as outlined in this guide. It isn't required reading to make your own hand wired keyboard, but provides background information. <details> <summary>Click for details</summary> Without a matrix circuit each switch would require its own wire directly to the controller. Simply put, when the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press. The microcontroller will be setup up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example: Column 0 being scanned Column 1 being scanned x x col0 col1 col0 col1 | | | | row0 ---(key0)---(key1) row0 ---(key0)---(key1) | | | | row1 ---(key2)---(key3) row1 ---(key2)---(key3) The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column. When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected: Column 0 being scanned Column 1 being scanned x x col0 col1 col0 col1 | | | | x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1) | | | | row1 ---(key2)---(key3) row1 ---(key2)---(key3) We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is col0: 0b01 col1: 0b00 │└row0 └row1 A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious: Column 0 being scanned Column 1 being scanned x x col0 col1 col0 col1 | | | | x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1) | | | | x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3) Remember that this ^ is still connected to row1 The data we get from that is: col0: 0b11 col1: 0b11 │└row0 └row1 Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this; Column 0 being scanned Column 1 being scanned x x col0 col1 col0 col1 │ │ | │ (key0) (key1) (key0) (key1) ! │ ! │ ! | ! │ row0 ─────┴────────┘ │ row0 ─────┴────────┘ │ │ │ | │ (key2) (key3) (key2) (key3) ! ! ! ! row1 ─────┴────────┘ row1 ─────┴────────┘ In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|` Now when we press the three keys, invoking what would be a ghosting scenario: Column 0 being scanned Column 1 being scanned x x col0 col1 col0 col1 │ │ │ │ (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1) ! │ ! │ ! │ ! │ x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │ │ │ │ │ (key2) (┌─┘3) (key2) (┌─┘3) ! ! ! ! row1 ─────┴────────┘ x row1 ─────┴────────┘ Things act as they should! Which will get us the following data: col0: 0b01 col1: 0b11 │└row0 └row1 The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS. Further reading: - [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit) - [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix) - [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/) - [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) - [How keyboards work - QMK documentation](how_keyboards_work.md) </details> ## Parts list You will need: (where *x* is the number of keys on your planned keyboard) * QMK compatible microcontroller board (Teensy, Pro-Micro, QMK Proton C etc.) * *x* keyswitches (MX, Matias, Gateron, etc) * *x* through hole diodes * Keyboard plate and plate mount stabilisers * Wire * Soldering iron * Rosin-cored solder * Adequate ventilation/a fan * Wire cutters/snippers Optional but useful: * Wire strippers/a sharp knife * Tweezers and/or small needle nose pliers * Soldering station/Helping hands ## Starting the build There are many ways to hand wire a PCB matrix, this guide will describe the fundamentals as well as some recommended ways to go about it. As we are dealing with hand wiring, it is assumed that you already have a plate. If you are planning a completely custom layout, tools such as [ai03 Plate Generator](https://kbplate.ai03.me/) and [Swillkb Plate & Case Builder](http://builder.swillkb.com/) can help when designing one. Start by installing the switches and stabilisers in the plate. Depending on the thickness and material this may also involve hot gluing it in place. ## Planning the matrix If you are following a pre-existing handwire guide (e.g. for the keyboards in the [handwire firmware section](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired) you can skip this step, just ensure you wire the matrix as described. What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode) It is fairly simple to plan for an ortholinear keyboard (like a Planck). ![Example planck matrix](https://i.imgur.com/FRShcLD.png) Image from [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) But the larger and more complicated your keyboard, the more complex the matrix. [Keyboard Firmware Builder](https://kbfirmware.com/) can help you plan your matrix layout (shown here with a basic fullsize ISO keyboard imported from [Keyboard Layout Editor](http://www.keyboard-layout-editor.com). ![Example ISO matrix](https://i.imgur.com/UlJ4ZDP.png) Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller. So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro #### Common Microcontroller Boards | Board | Controller | # I/O | Pinout | | :------------ |:-------------:| ------:| ------ | | Pro Micro* | ATmega32u4 | 20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) | | Teensy 2.0 | ATmega32u4 | 25 | [link](https://www.pjrc.com/teensy/pinout.html) | | [QMK Proton C](https://qmk.fm/proton-c/) | STM32F303xC | 36 | [link 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C) | | Teensy++ 2.0 | AT90USB1286 | 46 | [link](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0) | *Elite C is essentially the same as a pro micro with a USB-C instead of Micro-USB There are also a number of boards designed specifically for handwiring that mount directly to a small number of switches and offer pinouts for the rest. Though these are generally more expensive and may be more difficult to get hold of. <img src="https://i.imgur.com/QiA3ta6.jpg" alt="Postage board mini mounted in place" width="500"/> | Board | Controller | # I/O | | :------------ |:-------------:| ------:| | [Swiss helper](https://www.reddit.com/r/MechanicalKeyboards/comments/8jg5d6/hand_wiring_this_might_help/) | ATmega32u4 | 20 | | [Postage board](https://github.com/LifeIsOnTheWire/Postage-Board/)| ATmega32u4| 25 | | [Postage board mini](https://geekhack.org/index.php?topic=101460.0)| ATmega32u4| 25 | ## Wiring the matrix There is no one right way to do this. What you want to achieve is good connection at all of the joints planned and no unintentional shorts. Established materials and techniques include: | Technique | Examples | Pros | Cons | Image | :-----------| :------- | :------ | :--- | :--- | Lengths of wire with stripped segments | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) and [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | Neat and tidy | Some effort in stripping the wire | ![Stripped wire](https://i.imgur.com/0GNIYY0.jpg) | Short lengths of wire | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | Easier to strip the wire | More difficult to place | ![individual wire lengths](https://i.imgur.com/mBe5vkL.jpg) | Magnet/Enamelled wire | [Brett Kosinski's handwired alpha](http://blog.b-ark.ca/Blog-2019-01-27) and [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | Can be directly soldered onto (insulation burns off with heat) | Appearance? | ![Magnet wire](https://i.imgur.com/b4b7KDb.jpg) | Bending the legs of the diodes for the rows | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | Fewer solder joints required | Uninsulated | ![Bent diode legs](https://i.imgur.com/aTnG8TV.jpg) | Using ridid wiring (e.g. brass tube) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) and [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | Very pretty | More difficult. No physical insulation | ![Hardline hand wire](https://i.imgur.com/CnASmPo.jpg) | Bare wire with insulation added after (e.g. kapton tape) | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | Easier (no wire stripping required) | Not as attractive | ![Bare wire](https://i.imgur.com/AvXZShD.jpg) | Copper tape | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | Very easy | Only really works when your plate/case aligns with the bottom of your switches | ![Copper tape](https://i.imgur.com/RFyNMlL.jpg) Note that these methods can be combined. Prepare your lengths of wire before moving on to soldering. ### A note on split keyboards If you are planning a split keyboard (e.g. Dactyl) each half will require a controller and a means of communicating between them (like a TRRS or hardwired cable). Further information can be found in the [QMK split keyboard documentation.](feature_split_keyboard.md) ### Soldering There are a lot of soldering guides and tips available elsewhere but here are some of the most useful and relevant for hand wiring: To ensure a strong solder joint you want a good amount of contact between the solder and the 2 peices of metal you are connecting, a good way of doing this (though not required) is looping around pins or twisting wires together before applying solder. <img src="https://i.imgur.com/eHJjmnU.jpg" alt="Looped around rod" width="200"/> <img src="https://i.imgur.com/8nbxmmr.jpg?1" alt="Looped diode leg" width="200"/> If your diodes are on a packaging strip and need a bend in them (either the start of a loop or for connecting to its neighbour) this can easily done by bending it over something straight like the edge of a box, table, or ruler. This also helps keep track of the direction of the diode as all the bends will be on the same side. <img src="https://i.imgur.com/oITudbX.jpg" alt="Bent diode legs" width="200"/> If your iron has temperature control, set it to 315ºC (600ºF). Once heated, tin your soldering iron - this means melting a small amount of solder on the end of the iron and then quickly wiping it off on a wet sponge or wire cleaning pad, leaving a shiny silvery coating on the end which helps keep oxidisation at bay and helps solder to flow.