[WIP] Import from the discovery book

books/embedded-rust-book/src/SUMMARY.md

@@ -3,6 +3,10 @@
 - [Introduction](./intro/introduction.md)
     - [Preconditions](./intro/preconditions.md)
     - [Installation](./intro/install.md)
+        - [Linux](./intro/install/linux.md)
+        - [MacOS](./intro/install/macos.md)
+        - [Windows](./intro/install/windows.md)
+        - [Verify Installation](./intro/install/verify.md)
     - [Tooling](./intro/tooling.md)
     - [Hardware](./intro/hardware.md)
 - [Blinking your first LED](./blinky/blinky.md)

books/embedded-rust-book/src/intro/hardware.md

@@ -1,9 +1,52 @@
-# Hardware
-
-> **This section should cover:**
+> **⚠️: This section contains exports from [Japaric's Discovery] book.**
 >
-> * Meet the hardware
+> Contents should be reviewed for consistency in the context
+> of this book before "publishing"
+
+[Japaric's Discovery]: https://japaric.github.io/discovery/
+
+# Meet your hardware
+
+Let's get familiar with the hardware we'll be working with.
+
+## STM32F3DISCOVERY (the "F3")
+
+<p align="center">
+<img title="F3" src="assets/f3.jpg">
+</p>
+
+We'll refer to this board as "F3" throughout this book.
+
+What does this board contain?
+
+- A STM32F303VCT6 microcontroller. This microcontroller has
+  - A single core ARM Cortex-M4F processor with hardware support for single precision floating point
+    operations and a maximum clock frequency of 72 MHz.
+
+  - 256 KiB of "Flash" memory. (1 KiB = 10**24** bytes)
+
+  - 48 KiB of RAM.
+
+  - many "peripherals": timers, GPIO, I2C, SPI, USART, etc.
+
+  - lots of "pins" that are exposed in the two lateral "headers".
+
+  - **IMPORTANT** This microcontroller operates at (around) 3.3V.
+
+- An [accelerometer] and a [magnetometer][] (in a single package).
+
+[accelerometer]: https://en.wikipedia.org/wiki/Accelerometer
+[magnetometer]: https://en.wikipedia.org/wiki/Magnetometer
+
+- A [gyroscope].
+
+[gyroscope]: https://en.wikipedia.org/wiki/Gyroscope
+
+- 8 user LEDs arranged in the shape of a compass
+
+- A second microcontroller: a STM32F103CBT. This microcontroller is actually part of an on-board
+  programmer and debugger named ST-LINK and is connected to the USB port named "USB ST-LINK".
+
+- There's a second USB port, labeled "USB USER" that is connected to the main microcontroller, the
+  STM32F303VCT6, and can be used in applications.
 
-> **This section should steal:**
->
-> * https://japaric.github.io/discovery/04-meet-your-hardware/README.html

books/embedded-rust-book/src/intro/install.md

@@ -1,6 +1,4 @@
-# Installation
-
-> **This section should cover:**
+> ❌: **This section should cover:**
 >
 > * Installing Rust, including a specific nightly version
 > * Installing any additional deps, like `arm-none-eabi-gcc`
@@ -9,6 +7,117 @@
 > * Installing `xargo` (for now)...
 > * Doing all of the above for Windows, Mac, and Linux
 
-> **This section should steal:**
+> ❌: **This section should steal:**
+>
+> * https://japaric.github.io/discovery/03-setup/README.html
+
+> **⚠️: This section contains exports from [Japaric's Discovery] book.**
+>
+> Contents should be reviewed for consistency in the context
+> of this book before "publishing"
+
+[Japaric's Discovery]: https://japaric.github.io/discovery/
+
+> **⚠️: This section still references `nightly` Rust**
 >
-> * https://japaric.github.io/discovery/03-setup/README.html
+> Contents should be updated to work on `stable` Rust when possible
+
+> **⚠️: This section has not been checked as of 2018-05-26**
+>
+> Contents should be checked to still be working with current `nightly`
+> or `stable` Rust
+
+# Setting up a development environment
+
+Dealing with microcontrollers involves several tools as we'll be dealing with an architecture
+different than your laptop's and we'll have to run and debug programs on a "remote" device.
+
+## Documentation
+
+Tooling is not everything though. Without documentation is pretty much impossible to work with
+microcontrollers.
+
+We'll be referring to all these documents throughout this book:
+
+*HEADS UP* All these links point to PDF files and some of them are hundreds of pages long and
+several MBs in size.
+
+- [STM32F3DISCOVERY User Manual][um]
+- [STM32F303VC Datasheet][ds]
+- [STM32F303VC Reference Manual][rm]
+- [LSM303DLHC]
+- [L3GD20]
+
+[L3GD20]: http://www.st.com/resource/en/datasheet/l3gd20.pdf
+[LSM303DLHC]: http://www.st.com/resource/en/datasheet/lsm303dlhc.pdf
+[ds]: http://www.st.com/resource/en/datasheet/stm32f303vc.pdf
+[rm]: http://www.st.com/resource/en/reference_manual/dm00043574.pdf
+[um]: http://www.st.com/resource/en/user_manual/dm00063382.pdf
+
+## Tools
+
+We'll use all the tools listed below. Where a minimum version is not specified, any recent version
+should work but we have listed the version we have tested.
+
+- Cargo & `rustc` >= nightly-2018-04-08
+
+- [`itmdump`] v0.2.1
+
+- OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
+
+- `arm-none-eabi-ld`. Tested version: 2.30
+
+- `arm-none-eabi-gdb`. Version 7.12 or newer highly recommended. Tested versions: 7.10, 7.11,
+  7.12 and 8.1
+
+- `minicom` on Linux and macOS. Tested version: 2.7. Readers report that `picocom` also works but
+  we'll use `minicom` in this text.
+
+- `PuTTY` on Windows.
+
+[`itmdump`]: https://crates.io/crates/itm
+
+If your laptop has Bluetooth functionality and you have the Bluetooth module, you can additionally
+install these tools to play with the Bluetooth module. All these are optional:
+
+- Linux, only if you don't have a Bluetooth manager application like Blueman.
+  - `bluez`
+  - `hcitool`
+  - `rfcomm`
+  - `rfkill`
+
+macOS / OSX / Windows users only need the default bluetooth manager that ships with their OS.
+
+Next, follow OS-agnostic installation instructions for a few of the tools:
+
+### `rustc` & Cargo
+
+Install rustup by following the instructions at [https://rustup.rs](https://rustup.rs).
+
+Then, install or switch to the nightly channel.
+
+``` console
+$ rustup default nightly
+```
+
+**NOTE** Make sure you have a nightly newer than `nightly-2018-04-08`. `rustc -V` should return a
+date newer than the one shown below:
+
+``` console
+$ rustc -V
+rustc 1.27.0-nightly (056f589fb 2018-04-07)
+```
+
+### `itmdump`
+
+``` console
+$ cargo install itm --vers 0.2.1
+```
+
+### OS specific instructions
+
+Now follow the instructions specific to the OS you are using:
+
+- [Linux](intro/install/linux.html)
+- [Windows](intro/install/windows.html)
+- [macOS](intro/install/macos.html)

books/embedded-rust-book/src/intro/install/linux.md

@@ -0,0 +1,155 @@
+> **⚠️: This section contains exports from [Japaric's Discovery] book.**
+>
+> Contents should be reviewed for consistency in the context
+> of this book before "publishing"
+
+[Japaric's Discovery]: https://japaric.github.io/discovery/
+
+> **⚠️: This section has not been checked as of 2018-05-26**
+>
+> Contents should be checked to still be working with current `nightly`
+> or `stable` Rust
+
+# Linux
+
+Here are the installation commands for a few Linux distributions.
+
+## REQUIRED packages
+
+- Ubuntu 16.04 or newer / Debian Jessie or newer
+
+``` console
+$ sudo apt-get install \
+  binutils-arm-none-eabi \
+  gdb-arm-none-eabi \
+  minicom \
+  openocd
+```
+
+- Fedora 23 or newer
+
+``` console
+$ sudo dnf install \
+  arm-none-eabi-binutils-cs \
+  arm-none-eabi-gdb \
+  minicom \
+  openocd
+```
+
+- Arch Linux
+
+``` console
+$ sudo pacman -S \
+  arm-none-eabi-binutils \
+  arm-none-eabi-gdb \
+  minicom \
+  openocd
+```
+
+## Optional packages
+
+- Ubuntu / Debian
+
+``` console
+$ sudo apt-get install \
+  bluez \
+  rfkill
+```
+
+- Fedora
+
+``` console
+$ sudo dnf install \
+  bluez \
+  rfkill
+```
+
+- Arch Linux
+
+``` console
+$ sudo pacman -S \
+  bluez \
+  bluez-utils \
+  rfkill
+```
+
+## udev rules
+
+These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e.
+`sudo`.
+
+Create these two files in `/etc/udev/rules.d` with the contents shown below.
+
+``` console
+$ cat /etc/udev/rules.d/99-ftdi.rules
+```
+
+``` text
+# FT232 - USB <-> Serial Converter
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", GROUP="uucp"
+```
+
+``` console
+$ cat /etc/udev/rules.d/99-openocd.rules
+```
+
+``` text
+# STM32F3DISCOVERY rev A/B - ST-LINK/V2
+ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", GROUP="uucp"
+
+# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1
+ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", GROUP="uucp"
+```
+
+Then reload the udev rules with:
+
+``` console
+$ sudo udevadm control --reload-rules
+```
+
+If you had any board plugged to your laptop, unplug them and then plug them in again.
+
+Finally, check if you are in the `uucp` group.
+
+``` console
+$ groups $(id -nu)
+(..) uucp (..)
+$ #  ^^^^
+```
+
+(`$(id -nu)` returns your user name. In my case it's `japaric`.)
+
+If `uucp` appears in the output. You are all set! Go to the [next section]. Otherwise, keep reading:
+
+[next section]: intro/install/verify.html
+
+- Add yourself to the `uucp` group.
+
+``` console
+$ sudo usermod -a -G uucp $(id -u -n)
+```
+
+- Check again the output of `groups`. `uucp` should be there this time!
+
+``` console
+$ groups $(id -nu)
+(..) uucp (..)
+$ #  ^^^^
+```
+
+You'll have to re-log for these changes to take effect. You have two options:
+
+You can reboot or log out from your current session and then log in; this will close all the
+programs you have open right now.
+
+The other option is to use the command below:
+
+``` console
+$ su - $(id -nu)
+```
+
+to re-log *only in the current shell* and get access to `uucp` devices *only on that shell*. Other
+shells *won't* have access to `uucp` devices unless you manually re-log on them with the same `su`
+command.
+
+Now, go to the [next section].

books/embedded-rust-book/src/intro/install/macos.md

@@ -0,0 +1,29 @@
+> **⚠️: This section contains exports from [Japaric's Discovery] book.**
+>
+> Contents should be reviewed for consistency in the context
+> of this book before "publishing"
+
+[Japaric's Discovery]: https://japaric.github.io/discovery/
+
+> **⚠️: This section has not been checked as of 2018-05-26**
+>
+> Contents should be checked to still be working with current `nightly`
+> or `stable` Rust
+
+# MacOS
+
+All the tools can be install using [Homebrew]:
+
+[Homebrew]: http://brew.sh/
+
+``` console
+$ brew cask install gcc-arm-embedded
+$ brew install minicom openocd
+```
+
+If the `brew cask` command doesn't work (`Error: Unknown command: cask`), then run `brew tap
+Caskroom/tap` first and try again.
+
+That's all! Go to the [next section].
+
+[next section]: 03-setup/verify.html

books/embedded-rust-book/src/intro/install/verify.md

@@ -0,0 +1 @@
+# Verify Installation