docs: Build instructions

README.org

@@ -1,3 +1,8 @@
+# Local Variables:
+# org-html-checkbox-type: 'html
+# End:
+
+#+OPTIONS: toc:nil title:nil
 * Snappy
 
 Snappy is a custom, QMK-based split keyboard designed for simplicity, with a focus on portability and repairability.
@@ -26,8 +31,8 @@ following requirements that I deemed important:
 - [ ] PCB version
 - [ ] Wireless version
   - This version might feature a battery in place of the OLED display
-- [X] Some Accessories
-  - [X] Carrying case
+- [-] Some Accessories
+  - [ ] Carrying case
     - Features a dual function cable holder / connector for halves
   - [X] Portable mini tilt kit
   - [X] Stationary tilt kit(s)
@@ -74,12 +79,12 @@ Preis vom Filament für die gesamte Tastatur + Case + Tiltkit auf ca 10 € runt
 - 80x Hotswap Socket für *Kailh V1/V2* Switches (ca. 10 €)
   + [[https://www.aliexpress.com/item/1005003575767699.html?spm=a2g0o.order_list.order_list_main.17.cfce5c5fLYcFbY][Beispielhaftes Produkt]]
 - 80x 1N 4148 Schalt-Diode, 100 V, 150 mA, DO-35 (ca. 1 €)
-  + [[https://www.reichelt.de/schalt-diode-100-v-150-ma-do-35-1n-4148-p1730.html?nbc=1][Beispielhaftes Produkt]]
+  + [[https://www.reichelt.de/de/de/shop/produkt/schalt-diode_100_v_150_ma_do-35-1730][Beispielhaftes Produkt]]
 - 2x OLED Display 128x64 (i2c -> GND,VCC,SCK,SDA) (ca. 3 €)
   + [[https://www.aliexpress.com/item/1005006301661292.html?spm=a2g0o.order_list.order_list_main.251.cfce5c5fLYcFbY][Beispielhaftes Produkt]]
 - 2x TRRS Jack (ca. 1 €)
   + [[https://www.aliexpress.com/item/33029465106.html?spm=a2g0o.order_list.order_list_main.277.cfce5c5fLYcFbY][Beispielhaftes Produkt]]
-- 1x 0,3mm - 0,6mm TRRS Kabel (Am besten 90deg Winkel) (ca. 2 €)
+- 1x 30cm - 60cm TRRS Kabel (Am besten 90deg Winkel) (ca. 2 €)
   + [[https://www.aliexpress.com/item/4000104350398.html?spm=a2g0o.order_detail.order_detail_item.5.3dc76368Gtofi4][Beispielhaftes Produkt]]
   + [[https://de.aliexpress.com/item/1005005658552365.html][Custom Cable]]
     + In die Notiz vor dem Kauf schreiben: 90 TRRS to 90 TRRS, straight type, 30CM, Inner Color: 32 (Black) + Outer Color: Red, Black heatshrink.
@@ -136,4 +141,286 @@ Preis vom Filament für die gesamte Tastatur + Case + Tiltkit auf ca 10 € runt
 
 * Build Instructions
 
-TODO: Nice guide how to build Snappy
+** Required Tools
+
+*Hardware:*
+- Tweezers
+- Wire cutter
+- Soldering iron
+- Solder
+- Fume extractor
+- Usb-C cable: for testing & transfer of the firmware
+- Skrewdriver suitable for the selected skrews
+
+*Software:*
+- Clone of the QMK Repository
+  - https://github.com/qmk/qmk_firmware
+
+** Check Bill of Materials (Keyboard)
+
+Check if you have all required parts from the BOM.
+
+*Snappy v3 Tastatur (with Hotswap):*
+- [ ] 80x Kailh V1 (Choc) compatible *keycaps*
+- [ ] 80x Kailh V1 *keyswitch*
+- [ ] 2x *RP2040* Pro Micro 16M || 2x Liatris || 2x 0xCB Helios - *microcontroller*
+- [ ] 80x *Hotswap socket* for Kailh V1/V2 switches
+- [ ] 80x 1N 4148 *diodes*, 100 V, 150 mA, DO-35
+- [ ] 2x *OLED display* 128x64 (i2c -> GND,VCC,SCK,SDA)
+- [ ] 2x *TRRS jack*
+- [ ] 1x 30mm - 60mm *TRRS cable*
+- [ ] 28x *Heat insert M2* (OD3.2mm, H3mm oder 4mm)
+- [ ] 28x *M2 skrews* H6mm
+- [ ] 10x 7mm x 3mm *neodym magnets*
+- [ ] 8x 8mm x 2mm *rubber feet*
+- [ ] 14x 40cm, *enameled wire* Ø 0,30mm - 0,40mm
+- [ ] 8x 20cm, *enameled wire* Ø 0,30mm - 0,40mm
+- [ ] 12x 15cm, *enameled wire* Ø 0,30mm - 0,40mm
+- [ ] 8x 10cm, *enameled wire* Ø 0,30mm - 0,40mm
+
+** Ensure Microcontroller Functionality
+
+- Flash the snappy v3_5 QMK firmware onto both MCs
+  - https://github.com/qmk/qmk_firmware
+- Check with ~lsusb~ if there is a device ~cafe:1337 phga snappy v3.5~
+- Take some tweezers or a wire and try to activate some keys
+
+** Prepare Both Bottom Halves
+
+[[file:assets/instructions/001_hotswap.png]]
+
+- Insert all hotswap sockets into the holders of the two bottom halves.
+  - There *IS* a correct orientation (you can't insert them otherwise)
+
+[[file:assets/instructions/001_heat_inserts.png]]
+
+- Also insert the heat inserts into both bottom halves
+  - Make sure to insert them with the soldering iron set to 250°C
+  - Try to insert them as straight as possible
+
+** Prepare Both Top Halves
+
+[[file:assets/instructions/002_top_halves.png]]
+
+- Place the top plates onto the bottoms halves with the hotswap sockets
+- Insert all keyswitches through the top plate into the hotswap sockets
+  - Be mindful because the pins on the keyswitch easily bend
+  - The silver pin usually is a bit more rigid than the bronze one (try using the silver
+    one as a guide)
+
+** Get Ready to Solder
+
+[[file:assets/instructions/003_ready_to_solder.png]]
+
+- Remove the top halves from the bottom halves
+  - The hotswap sockets should stay attached to the keyswitches & thus the top halves
+
+[[file:assets/instructions/004_diodes.png]]
+
+- Prepare your diodes by shortening the side *WITHOUT* the black (anode) mark as seen in the picture
+- The goal is to shorten the anode of the diodes not too much
+  - Later we want to be able to archive similar results as shown in the following picture
+
+[[file:assets/instructions/005_diodes_soldered.png]]
+
+** General Notes on Soldering
+
+- Standard range: 315-380°C for hand soldering
+  - Enameled wire: 370-400°C (to burn through the enamel coating)
+- Starting point: 260°C, adjust as needed
+- Lead-free solder: Requires higher temperatures around 260°C
+- Contact time: 2-5s, adjust as needed
+- Cold/Bad Joints: Dull, whitish, frosted appearance
+- Good Joints: Shiny, smooth finish
+
+** Soldering the Rows
+
+[[file:assets/instructions/006_first_solder.png]]
+
+[[file:assets/instructions/006_second_solder.png]]
+
+1. Identify which half you are soldering right now
+   - The cutout for the the OLED-display marks the column to start with
+2. Put a bit of solder onto the connector of the hotswap socket that is on the same side
+   as the OLED-cutout of this half (when looking at it from the top)
+3. Reheat the solder and insert the shorter lead without the black stripe (anode) into the
+   connector of the hotswap socket
+4. Bend the longer leads, as shown in the picture, to form a connected line from the first
+   column (OLED-cutout) to the last column
+5. Solder the overlapping leads to establish electrical connectivity
+   - Cut off excess leads
+
+*TAKE NOTE BEFORE SOLDERING ANYTHING ON BOTH HALVES*
+
+[[file:assets/instructions/007_solder_right.png]]
+
+- *Right side* (OLED-cutout on the left)
+  - The last two hotswap sockets in the first row MUST be connected like this to leave
+    enough space for the TRRS jack
+
+[[file:assets/instructions/007_solder_right_2.png]]
+
+- *Right side* (OLED-cutout on the left)
+  - The first two hotswap sockets in the third row MUST be connected like this to leave
+    enough space for a skrew that holds the top plate
+
+[[file:assets/instructions/007_solder_left.png]]
+
+- *Left side* (OLED-cutout on the right)
+  - The last two hotswap sockets in the first row MUST be connected like this to leave
+    enough space for the TRRS jack
+
+*⟲ Repeat the same steps for the other side*
+
+*After this stage*, both sides should look something like this picture of the *right* side
+- The left side only has the one special joint in the top left corner (TRRS Jack)
+- The right side with two special joints is shown in the following picture
+
+[[file:assets/instructions/008_solder_stage_1.png]]
+
+** Soldering the Columns
+
+You'll need the *40cm enameled wire pieces* for this step
+
+[[file:assets/instructions/009_col_solder_1.png]]
+
+1. Wrap one end of the enameled wire around the bottom most hotswap socket of a column and
+   establish a solder joint to hold it in place
+2. Use a pair of tweezers or something pointy to wrap the wire around every hotswap socket
+   in this column
+3. Establish a solder joint on every hotswap socket / wire connection in this column
+   - *NOTE:* Starting with the top most connection secures the wire in place
+
+*⟲ Repeat the same steps for every column on both halves*
+
+[[file:assets/instructions/010_col_top_end.png]]
+
+- Make sure that the rest of the wire from each column is long enough to reach the
+  OLED-cutout with some extra wire left
+
+** Extending the Rows
+
+You'll need the *15cm enameled wire pieces* for this step
+
+[[file:assets/instructions/011_row_connections.png]]
+
+- Solder one end of each wire to each "intersection" of each row and the first column on
+  the side of the OLED-cutout
+  - Make sure to solder on the cathode side (with black mark) of the first diode
+  - Make sure that you do not destroy the connection of the row itself
+  - It is easier to first wrap the wire around the intersection and then solder
+
+*⟲ Repeat the same steps for the other side*
+
+*After this stage*, both sides should look something like this picture of the *right* side
+
+[[file:assets/instructions/012_after_col_row.png]]
+
+** Prepare & Solder the Rest of the Components
+
+You'll need the *10cm & 20cm enameled wire pieces* for this step
+
+[[file:assets/instructions/013_trrs_oled.png]]
+
+[[file:assets/instructions/013_rest_of_comps.png]]
+
+*The following diagrams are from the schematics pdf and should be used as a reference during the rest of the soldering.*
+
+[[file:assets/instructions/015_trrs_oled.png]]
+
+1. Solder the ends of the 8x 10cm wire pieces to the OLED displays
+2. Solder the ends of the 8x 20cm wire pieces to the TRRS jacks
+
+[[file:assets/instructions/014_liatris.png]]
+
+[[file:assets/instructions/016_matrix.png]]
+
+1. *Make sure to ask if anything during this phase is not described clearly enough or if you are unsure what to do*
+2. Place your microcontroller on top of the OLED-cutout
+   - Make sure that the controller is oriented correctly (look at the following pictures)
+
+*COLUMNS*
+1. Neatly route your column cables in between row0 and row1 to the microcontroller
+2. Carefully insert each column wire into the respective pin on the microcontroller (see
+   diagram & next pictures)
+   - Insert the cables from below. The cables must later be in between the OLED display
+     and the microcontroller
+   - Make sure that the controller is positioned with some "slack" of the wires in mind
+     (not too much slack though; this part is crucial and somewhat fiddly; re-adjust after
+     every newly inserted wire)
+*ROWS*
+1. Neatly route your row cables in between col0 and col1 to the microcontroller
+2. Carefully insert each row wire into the respective pin on the micro controller (see diagram & next pictures)
+   - Insert the cables from below. The cables must later be in between the OLED display
+     and the microcontroller
+   - Make sure that the controller is positioned with some "slack" of the wires in mind
+     (not too much slack though; this part is crucial and somewhat fiddly; re-adjust after
+     every newly inserted wire)
+*TRRS JACKS*
+1. Neatly route the 4 wires of each TRRS Jack to the microcontroller
+2. Carefully insert each TRRS jack wire into the respective pin on the micro controller
+   (see diagram & next pictures)
+   - Insert the cables from below. The cables must later be in between the OLED display
+     and the microcontroller
+   - When inserting the TRRS jack wires into to the microcontroller make sure to alternate
+     the R1/R2 pins for the left & right side.
+     - Snappy uses a full duplex connection between both halves
+     - To be compatible with other Snappy halves, use the same wiring as shown in the diagram
+       - Left: Hole > GP0 > GP1 > VCC > GND (sleeve)
+       - Right: Hole > GP1 > GP0 > VCC > GND (sleeve)
+*OLED DISPLAY*
+4. Place the OLED display into the slot underneath the microcontroller and route the wires
+   into the microcontroller (see diagram & next pictures)
+   - Insert the cables from below. The cables must later be in between the OLED display
+     and the microcontroller
+5. Place some strips of capton tape over the OLED display to protect it from shorts with
+   the microcontroller (This could be enhanced in future versions but space is very
+   limited)
+
+*For the last time make sure that the microcontroller is in the right spot (see picture below as a reference)*
+- Notice how it is a bit outside to the right there: This ensures, that the USB port fits neatly into the cutout in the bottom shell
+- *Dry fit the top half to the bottom half to see if the cable routing/length is sufficient*
+  - Cables sholud not be too long but also not too short
+  - The microcontroller should snap into its place and the USB-C connector should fit into
+    its cutout
+
+*Start to solder all wires to the micro controller*
+- When in doupt, ask for help when soldering the MC, if the MC is fried, we cant reverse it
+- Make sure to place the tip of the soldering iron:
+  - on the metal of the microcontroller pin
+  - touch the wire at the same time
+  - add some solder to help distribute the heat to the wire so that its coating can burn
+    easier
+
+[[file:assets/instructions/017_routing.png]]
+
+[[file:assets/instructions/018_working.png]]
+
+** Putting it All Together
+
+*MAGNETS*
+1. Ask for the correct orientation of the magnets
+   - Only necessary if you want to be compatible with others
+2. Insert the magnets into the slots of one bottom half
+3. Secure the top half onto the bottom half so that the magnets are seated securely
+4. Take a stack of magnets and test the correct orientation for the other half by
+   attaching the stack to the first half
+   - Take note of the correct orientation
+
+*⟲ Repeat the same steps for the other half & make sure your halves are attracted to each other*
+
+*TEST FUNCTIONALITY*
+1. Connect both halves with your TRRS cable
+2. Plug any half into a computer
+3. Check if the other half is also powered and if both halves send keycodes to your computer
+
+*SKREWS*
+- When both halves work as expected put in the rest of the skrews
+
+*If you did everything correctly, you should now have a "working" Snappy (:*
+
+[[file:assets/instructions/019_done.png]]
+* Additional Resources
+
+- For another visualization of the liatris pins see:
+  https://docs.splitkb.com/product-guides/liatris/pinout