Redox w firmware instructions (mattdibi#16)

* Added udev rules for ST-Link debugger * Added first draft of the instructions * Added some more screenshots * Added ST-Link debugger wiring pic
LucidityCrash · Feb 16, 2019 · d0b0d29 · d0b0d29
1 parent f2497f3
commit d0b0d29
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 7 deletions.
diff --git a/img/redox-w-firmware-2.png b/img/redox-w-firmware-2.png
diff --git a/img/redox-w-firmware-3.jpg b/img/redox-w-firmware-3.jpg
diff --git a/img/redox-w-firmware-4.png b/img/redox-w-firmware-4.png
diff --git a/img/redox-w-firmware-5.jpg b/img/redox-w-firmware-5.jpg
diff --git a/redox-w/README.md b/redox-w/README.md
@@ -191,26 +191,184 @@ You'll need to upload the firmware to the corresponding MCUs as per the followin
 
 Note that you'll need to upload the firmware for the YJ-14015 only once. Everything related to the keymap is handled by the Arduino Pro Micro and QMK Firmware, that's what you will need to modify to update the keymap.
 
+### Step-by-step firmware upload guide
+
+#### Arduino Pro Micro Firmware upload
+
+Let's start by uploading the QMK firmware on the Arduino, this will help us in diagnosing problems early on. The Redox uses QMK for its firmware, follow the QMK installation instructions [here](https://docs.qmk.fm/#/getting_started_build_tools), then compile and burn the firmware as follows:
+
+```sh
+$ cd path/to/qmk_firmware
+$ make redox_w:default:avrdude
+```
+
+You can find the code for the Redox here: [QMK - Redox Wireless keyboard](https://github.com/mattdibi/qmk_firmware/tree/redox_wireless/keyboards/redox_w).
+
+In the [Redox Wireless Keyboard firmware repository](https://github.com/mattdibi/redox-w-firmware/tree/master/precompiled) I added some pre-built hex files with the default keymap for testing purpose.
+
 #### Nordic MCUs Firmware upload
 
-Follow the instruction in the [Redox Wireless Keyboard firmware repository](https://github.com/mattdibi/redox-w-firmware). You'll need only to flash the pre-built `.hex` files to the corresponding MCUs, for this you'll need an STLinkV2 debugger.
+You'll need only to flash the pre-built `.hex` files to the corresponding MCUs, for this you'll need an STLinkV2 debugger.
 
 <p align="center">
 <img src="../img/st-link-v2-programmer.jpg" alt="ST-Link v2 programmer" width="300"/>
 </p>
 
-#### Arduino Pro Micro Firmware upload
+*Note*: Tested on Ubuntu 16.04 and 18.04 but you should be able to find alternatives on all distros.
+
+##### Setup
 
-The Redox uses QMK for its firmware, follow the QMK installation instructions [here](https://docs.qmk.fm/#/getting_started_build_tools), then compile and burn the firmware as follows:
+###### Install OpenOCD (Open On-Chip Debugger)
 
 ```sh
-$ cd path/to/qmk_firmware
-$ make redox_w:default:avrdude
+sudo apt install openocd
 ```
 
-You can find the code for the Redox here: [QMK - Redox Wireless keyboard](https://github.com/mattdibi/qmk_firmware/tree/redox_wireless/keyboards/redox_w).
+###### Download the repository
 
-In the [Redox Wireless Keyboard firmware repository](https://github.com/mattdibi/redox-w-firmware/tree/master/precompiled) I added some pre-built hex files with the default keymap for testing purpose.
+Open a terminal and download this repository wherever you want. We'll need the `redox-w/firmware` folder content.
+
+```sh
+git clone https://github.com/mattdibi/redox-keyboard.git
+```
+
+or
+
+```sh
+wget https://github.com/mattdibi/redox-keyboard/archive/master.zip
+```
+
+###### Install the udev rules
+
+```sh
+cd path/to/repository/redox-keyboard/redox-w/firmware/
+sudo cp 49-stlinkv2.rules /etc/udev/rules.d/
+```
+
+##### Programming the receiver
+
+###### Hook up the receiver
+
+Hook up the ST-Link debugger to the receiver board you assembled without the Arduino. You need to connect only the `VCC`, `GND`, `SWDIO` and `SWCLK` pins of the receiver board like this:
+
+| ST-Link Debugger | Receiver board |
+|------------------|----------------|
+| 3.3V | VCC |
+| GND | GND |
+| SWCLK | SWCLK |
+| SWDIO | SWDIO |
+
+<p align="center">
+<img src="../img/redox-w-firmware-5.jpg" alt="ST-Link debugger wiring." width="600"/>
+</p>
+
+Then plug in the ST-Link debugger into your PC.
+
+###### Launch a OpenOCD server session
+
+In a new terminal window launch an OpenOCD server session by issuing the following command:
+
+```sh
+openocd -s /usr/local/Cellar/open-ocd/0.8.0/share/openocd/scripts/ -f interface/stlink-v2.cfg -f target/nrf51.cfg
+```
+
+This should give the following output:
+
+```sh
+Info : nrf51.cpu: hardware has 4 breakpoints, 2 watchpoints
+```
+
+Leave this terminal window open.
+
+###### Receiver firmware flashing
+
+We can now issue the flashing commands. Open a terminal in the redox-w firmware folder.
+
+```sh
+cd path/to/repository/redox-keyboard/redox-w/firmware/
+```
+
+From the factory, these chips need to be erased:
+
+```sh
+echo reset halt | telnet localhost 4444
+echo nrf51 mass_erase | telnet localhost 4444
+```
+
+You should be seeing some movement in the OpenOCD terminal window, and you desktop should be looking somewhat like this:
+
+<p align="center">
+<img src="../img/redox-w-firmware-2.png" alt="Receiver firmware flashing." width="900"/>
+</p>
+
+Now we can upload the receiver firmware onto the MCU.
+
+```sh
+echo reset halt | telnet localhost 4444
+echo flash write_image `readlink -f precompiled-basic-receiver.hex` | telnet localhost 4444
+echo reset | telnet localhost 4444
+```
+
+You should be looking at something like this:
+
+<p align="center">
+<img src="../img/redox-w-firmware-4.png" alt="Receiver firmware flashing." width="900"/>
+</p>
+
+
+Now close the OpenOCD session (use `Ctrl-C`) and you're done with the receiver. Repeat these steps for the two halves of the keyboard and you should be set.
+
+##### Programming the two halves
+
+###### Hook up the transmitter
+
+Hook up the ST-Link programmer with the transmitters using the programming pins, and plug the debugger in you PC.
+
+<p align="center">
+<img src="../img/redox-w-firmware-3.jpg" alt="Transmitters programming pins." width="600"/>
+</p>
+
+Start a OpenOCD session as seen above and start flashing the firmware.
+
+###### Left hand firmware flashing
+
+From another terminal window issue the following commands. Again from the factory, these chips need to be erased:
+
+```sh
+echo reset halt | telnet localhost 4444
+echo nrf51 mass_erase | telnet localhost 4444
+```
+
+Upload the left hand firmware.
+
+```sh
+cd path/to/repository/redox-keyboard/redox-w/firmware/
+echo reset halt | telnet localhost 4444
+echo flash write_image `readlink -f precompiled-basic-left.hex` | telnet localhost 4444
+echo reset | telnet localhost 4444
+```
+
+###### Right hand firmware flashing
+
+After having hooked up the right hand to the ST-Link debugger and started a new OpenOCD session we can upload the right hand firmware.
+
+Again from the factory, these chips need to be erased:
+
+```sh
+echo reset halt | telnet localhost 4444
+echo nrf51 mass_erase | telnet localhost 4444
+```
+
+Upload the right hand firmware.
+
+```sh
+cd path/to/repository/redox-keyboard/redox-w/firmware/
+echo reset halt | telnet localhost 4444
+echo flash write_image `readlink -f precompiled-basic-right.hex` | telnet localhost 4444
+echo reset | telnet localhost 4444
+```
+
+Congratulations! You flashed the Redox-W firmware.
 
 ## Battery usage
 

diff --git a/redox-w/firmware/49-stlinkv2.rules b/redox-w/firmware/49-stlinkv2.rules
@@ -0,0 +1,12 @@
+# stm32 discovery boards, with onboard st/linkv2
+# ie, STM32L, STM32F4.
+# STM32VL has st/linkv1, which is quite different
+
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", \
+ MODE:="0666", \
+ SYMLINK+="stlinkv2_%n"
+
+# If you share your linux system with other users, or just don't like the
+# idea of write permission for everybody, you can replace MODE:="0666" with
+# OWNER:="yourusername" to create the device owned by you, or with
+# GROUP:="somegroupname" and mange access using standard unix groups.