Add development-related documentation

DEVELOPMENT.md

@@ -0,0 +1,71 @@
+# Development Notes
+
+
+## Development Firmware
+
+### Update Key
+
+Development firmware has a common update key for the 128kB and 256kB MCU sizes (its separate for production).
+Key can be found in `pubkey_bootloader.c`.
+
+### Compatibility
+Both 128kB and 256kB variants use the same firmware, but with user data region placed differently, always 40kB from the end of the MCU's flash. Thus 128kB variant will work on both MCUs, while 256kB firmware will not work on the smaller die.
+
+It's possible to unify firmware for both models in the future by choosing dynamically the user flash region accordingly to the read MCU's model.
+
+### Build
+
+#### Automatic, all editions
+
+Firmware can be built in a Docker container by calling:
+```text
+make docker-build-toolchain
+make docker-build-all
+```
+
+This will run builds as specified in `in-docker-build.sh` file: debug and release builds for each 128kB and 256kB MCU hardware models, and additionally a single development self-confirming touchbutton firmware for 128kB/256kB.
+
+#### By hand
+
+Required software:
+- ARM GCC
+- pynitrokey
+
+```text
+$ cd targets/stm32l432/
+# development build for 256kB variant, self-confirming touch button (HWREV==0)
+$ make debug-release-buildv RELEASE=0 PAGES=128 HWREV=0
+
+# release build for the 128kB variant, latest HW revision (HWREV==3)
+$ make release-buildv RELEASE=1 PAGES=64 HWREV=3
+```
+
+Note: development firmware does not fit to the smaller 128kB MCU at the moment (42kiB overflow)
+
+### Update
+Required software:
+- pynitrokey (tested v0.4.5)
+
+
+1. Switch to bootloader mode by calling pynitrokey
+    ```text
+   $ nitropy fido2 util program aux enter-bootloader
+    ```
+2. Device starts blinking, touch it - it should start blinking faster
+      - after 5-10 seconds touch is confirmed
+      - device enters bootloader mode (USB product string contains `Bootloader`)
+      - bootloader mode can be left any time with power-cycle
+3. Run update command with the auto-signed development firmware
+   ```text
+   $ nitropy fido2 util program bootloader nitrokey-fido2-firmware-256kB-dev-2.4.1.nitrokey-30-g1346baa.json
+   ```
+   - update takes less than 1 minute; if interrupted, a power cycle might be needed to restart the operation
+   - due to the different firmware keys it is not possible to use production  release or "locking") firmware - it will be simply rejected by bootloader
+   - bootloader will start each time the firmware is not accepted
+   - if error is shown at the end of the command, then firmware has not passed the signature check - update process has to be repeated with different file.
+
+In case development firmware with different hardware revision set is flashed, touch button might not work, and with it possibility to update the firmware through the bootloader. In that case update through the debug adapter is the only way to reinstate the working state.
+
+### Helpers
+- `make flash-firmware` - updates device through with the last built development firmware
+- `make flash` - flashes the last built firmware with debug adapter

MAINTAINERS.md

@@ -1,7 +1,10 @@
 ## Firmware release process
+
+Procedure for the firmware release is as follows:
+
 1. Tag the commit to be released with the next firmware version
-1. Build the firmware using Docker
-2. Sign the binary firmware
-3. Upload signed binary to the Github releases
-4. Bump ./STABLE_RELEASE file with latest version
-5. Run update script on the update server (if needed)
+3. Build the firmware using Docker
+4. Sign the binary firmware
+5. Upload signed binary to the Github releases
+6. Bump ./STABLE_RELEASE file with the latest version
+7. Run update script on the update server (if needed)