From 5a9f7b21890728f78930145dd1fc63c21c698697 Mon Sep 17 00:00:00 2001
From: phga <phga@posteo.de>
Date: Sat, 28 Jun 2025 00:39:28 +0200
Subject: [PATCH] docs: Add information about flashing

---
 README.org           | 90 +++++++++++++++++++++++++++++++++++++++++++-
 qmk/snappy/README.md |  2 +
 2 files changed, 91 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index a291cc1..25c99a8 100644
--- a/README.org
+++ b/README.org
@@ -418,7 +418,95 @@ You'll need the *10cm & 20cm enameled wire pieces* for this step
 
 [[file:assets/instructions/019_done.png]]
 
+* How to Flash the Firmware
+
+
+*Required repositories*
+- https://g.phga.de/phga/snappy-public (keymaps & general definitions for Snappy)
+- https://github.com/qmk/qmk_firmware (firmware base)
+
+*Documentation for all available keycodes of the firmware*
+- https://docs.qmk.fm/keycodes
+
+** How to Flash the Firmware
+
+If you want a more "user-friendly" experience: [[*Flash via Via (Use Via)][Flash via Via (Use Via)]]
+
+The process is also partially documented in ~snappy-public/qmk/snappy/README.md~
+Since Snappy has yet to be released to the official QMK repo--for now--additional steps are necessary.
+
+1. Copy the folder ~snappy-public/qmk/snappy~ (snappy-public) to ~qmk_firmware/keyboards/snappy~ (the qmk project -- firmware)
+2. Keep the "innermost" key pressed, while plugging in the half you want to flash
+   - Innermost means the key in the first row (the one with the OLED display) that is furthest from the OLED display.
+   - NOTE: Both halves SHOULD be flashed with the same version of the firmware
+3. Mount the blockdevice (~lsblk~) of the ~rp2040~ to ~/media/snappy~ (this allows for automatic upload of the img)
+4. Either choose an existing layout or create your own by e.g. copying the an existing one
+   - ~cp snappy-public/qmk/snappy/rev3_5/keymaps/qwertz snappy-public/qmk/snappy/rev3_5/keymaps/my_cool_layout~
+   - The folder name is than used in the ~make~ command for flashing to select the layout
+   - You can adjust the ~keymap.c~ file as needed (either check out the code or use the qmk documentation)
+   - For ~QWERZ~ users, check section [[*OS Layouts: Note on QWERTZ][OS Layouts: Note on QWERTZ]]
+5. Navigate in the root directory of the ~qmk_firmware~ folder and run the following commands
+
+#+begin_src sh :results output scalar
+# REV3_5 (promicro rp2040)
+# RIGHT Half
+sudo make snappy/rev3_5:$MY_LAYOUT_FOLDER_NAME:uf2-split-right
+# LEFT Half
+sudo make snappy/rev3_5:$MY_LAYOUT_FOLDER_NAME:uf2-split-left
+
+# OTHER Layouts (example with QWERTZ layout REV3_5)
+sudo make snappy/rev3_5:qwertz:uf2-split-right
+sudo make snappy/rev3_5:qwertz:uf2-split-left
+
+# Make sure to mount the RP2040 drive to /media/snappy for automatic copying of the .uf2 file
+#+end_src
+
+*NOTE:* After the flash was successful, the ~rp2040~ automatically reboots with the new firmware
+
+* Flash via Via (Use Via)
+
+Navigate to using a ~Chrome~ based browser (firefox might not work):
+1. https://usevia.app/
+2. Settings > Show Design tab
+3. Design Tab > Load Draft Definition
+   - ~snappy-public/qmk/etc/rev3/snappy_rev3_via_keyboard_definition.json~
+4. *On GNU/Linux:*
+   1. Navigate to ~chrome://device-log~ find hidrawXYZ (or allow ~rw~ for any hidraw device)
+   2. ~sudo chown $USER /dev/hidrawXYZ~
+5. Configure > [Authorize device +]
+6. Start configuring
+
+*NOTE:* For ~QWERZ~ users, check section [[*OS Layouts: Note on QWERTZ][OS Layouts: Note on QWERTZ]]
+
+* OS Layouts: Note on QWERTZ
+
+Keycodes in QMK are aliased with ~QWERTY~ keycodes. Thus, if you are using a ~QWERTZ~ layout
+on your device you have to mentally translate the ~QWERTY~ keycodes to the related ~QWERTZ~
+outputs of your OS-Layout when configuring your keyboard.
+
+*EXAMPLE:* The keycode ~KC_Z~ / ~Z~ will output a ~Y~ while using ~QWERTZ~ as your OS-Layout.
+
+To easily find all the keys you need, consult the internet, a LLM or use a ~QWERTZ~ keyboard
+and set your OS-Layout to ~QWERTY~ and type all the umlauts/etc. you need and take note
+which character appears (aka. reverse mapping)
+
+** Table of Most Common Keys
+
+| QWERTY      | QWERTZ     |
+|-------------+------------|
+| z           | y          |
+| y           | z          |
+| -           | ß          |
+| ;           | ö          |
+| '           | ä          |
+| [           | ü          |
+| @ (shift+2) | "          |
+| ???         | @ (ralt+q) |
+
 * Additional Resources
 
 - For another visualization of the liatris pins see:
-  https://docs.splitkb.com/product-guides/liatris/pinout
+  - https://docs.splitkb.com/product-guides/liatris/pinout
+
+- All QMK keycodes:
+  - https://docs.qmk.fm/keycodes
diff --git a/qmk/snappy/README.md b/qmk/snappy/README.md
index 341f485..22a775f 100644
--- a/qmk/snappy/README.md
+++ b/qmk/snappy/README.md
@@ -10,6 +10,8 @@
 
 Make example for this keyboard (after setting up your build environment):
 
+**IMPORTANT:** Run these commands in the root directory of the qmk_firmware repository
+
     make snappy:default
 
     # REV1 & REV2 (elite c)