Build docs with mdBook

.gitignore

@@ -4,3 +4,5 @@ Cargo.lock
 *.bin
 *.dfu
 target/
+book/
+todo.txt

Makefile

@@ -9,9 +9,16 @@ build:
 dfu: build
 	./scripts/generate_dfu.sh
 
+docs:
+	mdbook build
+
+serve:
+	mdbook serve
+
 clean:
 	$(XARGO) clean
 	rm -f anne-key.bin
 	rm -f anne-key.dfu
+	rm -rf book/
 
-.PHONY: all build clean
+.PHONY: all build clean docs serve

book.toml

@@ -0,0 +1,5 @@
+[book]
+title = "Anne Pro Internals"
+description = "How the Anne Pro Keyboard really works"
+authors = []
+src = "docs"

docs/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Hardware](./hardware.md)
+- [Software](./software.md)

docs/chapter_1.md

@@ -0,0 +1 @@
+# Chapter 1

docs/introduction.md

@@ -0,0 +1,17 @@
+Anne Pro Internals
+==================
+
+<img src="images/ferris.png" width=30%/> <img src="images/anne.jpg" width=50%/>
+
+[GitHub project](https://github.com/ah-/anne-key)
+
+
+Contributing to this documentation
+----------------------------------
+
+Please help out documenting how the Anne Pro works to help others get started!
+
+To do so edit these Markdown files and send a Pull Request on GitHub.
+
+You can preview your changes locally by building the docs with [mdBook](https://github.com/rust-lang-nursery/mdBook).
+Just run `make serve` in the root folder and go to [http://localhost:3000/](http://localhost:3000/).

docs/software.md

@@ -0,0 +1,44 @@
+Software
+========
+
+Bootloader
+----------
+
+Usually an STM32 starts execution via the vector table at `0x0800_0000`, but our user code only starts at `0x0800_4000` as you can see in the `memory.x` file.
+
+This is due to the factory bootloader that lives at `0x0800_0000`. The bootloader checks on startup if the escape key is pressed, and if so it puts the Anne Pro into DFU mode. Otherwise it jumps to our code at `0x0800_4000`.
+
+The bootloader on the main Keyboard STM32 also handles flashing the LED controller. If you're flashing LED, the commands are first sent to the keyboard controller, which forwards them.
+
+It also advertises support for flashing the Bluetooth chip, but this seems to be broken.
+
+### Memory Map
+```
+Address
+
+             .......................... 
+             .                        . 
+             .          ...           .
+             .                        .
+             +------------------------+
+             |                        |
+             |          RAM           |
+             |                        |
+0x2000_0000  +------------------------+
+             .                        .
+             .          ...           .
+             .                        .
+             .                        .
+             +------------------------+
+             |                        |
+             |         FLASH          |
+             |    (Rust lives here)   |
+             |                        |
+0x0800_4000  +------------------------+
+             |       BOOTLOADER       |
+0x0800_0000  +------------------------+
+             .                        .
+             .          ...           .
+             .                        .
+0x0000_0000  ..........................
+```