fixed up serial + UART + I2C chapters, cleaned up diagrams

The description of serial ports and serial communication was
pretty confusing: now it's much cleaner. The new chapter
name `Serial Port` should help, as it unambiguously
describes the thing we will actually be working with.

The I2C chapter had some slightly weird stuff going on that
was fixed up a bit.

The handling of figures was cleaned up. A Wikimedia Commons
diagram that was incorrectly copied instead of linked was
fixed. Figure background was added and slightly darkened
with additional CSS to work reasonably with dark-mode
reading.

Thanks much to Github @iampi31 for contributions and
feedback that became part of this PR.

closes #78, closes #79, closes #81

Author: BartMassey

.github/workflows/ci.yml

@@ -88,7 +88,7 @@ jobs:
 
       - name: Check book links
         working-directory: mdbook
-        run: linkchecker --ignore-url "print.html" book
+        run: linkchecker --ignore-url "print.html" book/html
 
       - name: Copy EPUB to html directory
         working-directory: mdbook

mdbook/book.toml

@@ -1,14 +1,13 @@
 [book]
 title = "Rust Embedded MB2 Discovery Book"
-description = "Discover the world of microcontrollers through Rust with the BB2 micro:bit v2"
+description = "Discover the world of microcontrollers through Rust with the BBC micro:bit v2"
 authors = ["Rust Embedded Resources Team"]
 language = "en"
 
 [output.html]
 git-repository-url = "https://github.com/rust-embedded/discovery-mb2/"
-additional-js = ["epub-link.js"]
-# additional-css = ["custom.css"]
-
+additional-js = ["src/assets/epub-link.js"]
+additional-css = ["src/assets/custom.css"]
 
 [output.epub]
 # Optional settings

mdbook/src/09-registers/README.md

@@ -3,7 +3,7 @@
 This chapter is a technical deep-dive. You can safely [skip it] for now and come back to it later if
 you like. That said, there's a lot of good stuff in here, so I'd recommend you dive in.
 
-[skip it]: ../10-serial-communication/index.html
+[skip it]: ../10-serial-port/index.html
 
 -----
 

mdbook/src/10-serial-communication/README.md

@@ -0,0 +1,38 @@
+# Serial Port
+
+The closest thing to a universal I/O standard for modern day embedded boards is the "serial port". Pretty much every microcontroller has a way to talk serial on its pins, and pretty much every microcontroller board has these pins made easily accessible. The MB2 is no exception.
+
+In this chapter, we will describe what a serial port even is. We will then show you how to set up your computer with a "virtual serial port" using USB and use that virtual port with "terminal software" to talk to a serial port on the MB2.
+
+So what's this [serial port]? It's a place where two devices exchange data one bit at a time (*serially*) using one data line in each direction (*full-duplex*) plus a common ground. The serial port originated as "RS-232": see the history later in this chapter for details. However, the protocol spoken on the transmit and receive lines doesn't have an official name I'm aware of — it's just "serial" or maybe "async serial" or "UART serial".
+
+Serial port communication is *asynchronous* in the sense that none of the shared lines carries a clock signal. Instead, both parties must agree on roughly how fast data will be sent along the wire *before* the communication occurs. A peripheral called a Universal Asynchronous Receiver/Transmitter (UART) sends bits at the specified rate on its output wire, and watches for the start of bits on its input wire.
+
+<p align="center">
+<img class="white_bg" height="100" title="Serial Protocol" src="../assets/serial-proto.svg" />
+</p>
+
+The serial-port communications protocol works with frames, each carrying a byte of data. Each frame has one *start* bit, 5 to 9 bits of payload data (sent lsb-to-msb; modern applications very rarely send a 9-bit byte; 7 or fewer bits in a frame will be left-padded to an 8-bit byte with zeros) and 1 to 2 *stop bits*.  In the diagram above, an ASCII 'E' character is sent using 8 data bits and 1 stop bit.
+
+The speed of the protocol is known as *baud rate* and it's quoted in bits per second (bps). (If you're thinking that this sounds wrong — it is. "Baud" is supposed to be *symbols* per second; a symbol should correspond to a frame; even if a data bit is regarded as the "symbol" they aren't sent at this rate because of the rest of the protocol. It's a convention, and doesn't have to make sense.) Historically common baud rates for UART serial are 9600bps, 19200bps, and 115200bps, but it is not uncommon in our modern world to send data at 921,600bps.
+
+With the "normal" configuration of 1 start bit, 8 bits of data, 1 stop bit and a bit rate of 921.6K bps we can send and receive 92.16K bytes per second — fast enough to transmit single-channel uncompressed CD audio. At the bit rate of 115,200 bps that we'll be using, we can send and receive 11.52K bytes per second. This is fine for most purposes.
+
+We'll be using a serial port (indirectly) to exchange data between the MB2 and your computer. Now you might be asking yourself: why exactly aren't we using RTT for this like we did before? RTT is a protocol that is meant to be used solely for debugging. You will not find devices that use RTT to communicate with other devices. However, serial communication is used quite often. For example, some GPS receivers send the position information they receive via serial. In addition RTT, like many debugging protocols, is slow compared to serial transfer rates.
+
+<p align="center">
+<img class="white_bg" height="500" title="Serial" src="../assets/serial.svg" />
+</p>
+
+Today's computers don't usually have a serial port, and even if they do the voltage they use (+5V on a modern serial port, ±12V on an ancient RS-232 port) is outside the range that the MB2 hardware will accept and may result in damaging it. *You can't directly connect your computer to the microcontroller.*  You *can* buy very inexpensive (typically under US$5) USB←→serial converters that will support the +3.3V inputs of most modern microcontroller boards. We will be talking to the MB2 serial port through its built-in USB port. However, if you want to connect directly to a hardware serial port, on the MB2 or some other board, a serial converter is the way to go.
+
+A separate USB channel on the MB2's USB port can be used to talk to the MB2's built-in USB←→serial converter. (This is the right-hand path in the figure above.) This USB←→serial conversion is implemented using the "communications microcontroller" of the MB2: the communications microcontroller exposes a serial interface to the microcontroller and a virtual USB serial interface to your computer. The computer presents a virtual serial interface via the USB CDC-ACM ("Communications Device Class - Abstract Control Model", ugh) device class. The MB2 microcontroller will see your computer as a device connected to its hardware serial port; your computer will see the MB2 serial port as a virtual serial device.
+
+Now, let's get familiar with the USB serial port interface that your OS offers. Pick a route:
+
+- [Linux/UNIX](nix-tooling.md)
+- [Windows](windows-tooling.md)
+
+For MacOS check out the Linux documentation, although your experience may differ somewhat.
+
+[serial port]: https://en.wikipedia.org/wiki/Serial_port

mdbook/src/10-serial-communication/nix-tooling.md

@@ -0,0 +1,69 @@
+# Linux USB←→serial tooling
+
+The MB2's USB emulated serial device shows up in Linux when you connect the MB2 to a Linux USB
+port.
+
+## Connecting the MB2 board
+
+If you connect the MB2 board to your computer you should see a new TTY device appear in
+`/dev`.
+
+``` console
+$ sudo dmesg -T | tail | grep -i tty
+[63712.446286] cdc_acm 1-1.7:1.1: ttyACM0: USB ACM device
+```
+
+This is the USB←→serial device. On Linux, it's named `tty` (for "TeleTYpe", believe it or not).  It
+should show up as `ttyACM0`, or maybe `ttyUSB0`. If other "ACM" devices are plugged in, the number
+will be higher.  (On Mac OS `ls /dev/cu.usbmodem*` will show the serial device.)
+
+But what exactly is `ttyACM0`? It's a file of course!  Everything is a file in Unix:
+
+```
+$ ls -l /dev/ttyACM0
+crw-rw----+ 1 root plugdev 166, 0 Jan 21 11:56 /dev/ttyACM0
+```
+
+Note that you will need to be either running as `root` (not advised) or a member of the group that
+appears in the `ls` output (usually `plugdev` or `dialout`) to read and write this device. You can
+then send out data by simply writing to this file:
+
+``` console
+$ echo 'Hello, world!' > /dev/ttyACM0
+```
+
+You should see the orange LED on the MB2, right next to the USB port, blink for a moment,
+whenever you enter this command.
+
+## minicom
+
+We'll use the program `minicom` to interact with the serial device using the keyboard.  We will use
+the default settings of modern `minicom`: 115200 bps, 8 data bits, one stop bit, no parity bits, no
+flow control. (115200 bps happens to be a rate that will work with the MB2.)
+
+``` console
+$ minicom -D /dev/ttyACM0
+```
+
+This tells `minicom` to open the serial device at `/dev/ttyACM0`.  A text-based user interface
+(TUI) will pop out.
+
+<p align="center">
+<img title="minicom" src="../assets/minicom.png" />
+</p>
+
+You can now send data using the keyboard! Go ahead and type something. Note that
+the text UI will *not* echo back what you type. If you pay attention to the yellow LED
+on top of the MB2 though, you will notice that it blinks whenever you type something.
+
+## `minicom` commands
+
+`minicom` exposes commands via keyboard shortcuts. On Linux, the shortcuts start with `Ctrl+A`. (On
+Mac, the shortcuts start with the `Meta` key.) Some useful commands below:
+
+- `Ctrl+A` + `Z`. Minicom Command Summary
+- `Ctrl+A` + `C`. Clear the screen
+- `Ctrl+A` + `X`. Exit and reset
+- `Ctrl+A` + `Q`. Quit with no reset
+
+> **NOTE** Mac users: In the above commands, replace `Ctrl+A` with `Meta`.

mdbook/src/10-serial-port/README.md

@@ -0,0 +1,32 @@
+## RS-232
+
+This is for sure an optional section, but you might find it useful to know this stuff when talking with folks about serial in the future.
+
+The earliest standard serial ports I am aware of were around 1960, when a standard called [RS-232] (Revised Standard 232; there does not appear to be an "unrevised" version of this standard). It would be interesting to look at the [RS-232 Standard]: if you have US$65 lying around you are itching to give to the Telecommunications Industry Association, by all means go for it. (Industry associations tend to compeletely miss the concept of "shame". Sigh.)
+
+RS-232 was a way to hook Data Communications Equipment (DCE; a MODEM) to Data Terminal Equipment (DTE; a terminal) using just one wire to send data in each direction: the protocol used for data is described elsewhere in this chapter.  Data rates were adjustable: it was typical to use the data rate of a MODEM when one was connected, so "standard" RS-232 rates tended to also be "standard" MODEM rates — 300bps, 600bps, 1200bps, 2400bps, 9600bps etc.
+
+RS-232 also supported some other wires to do hardware "handshaking" (each end could signal that it was not taking data right now because it was busy) and various phone functions ("Is the phone ringing?", "Take the phone off hook", etc). RS-232 used a 25-pin "D" connector; signalling voltages were -12V for high and +12V for low, an old phone company standard.
+
+<a href="https://en.wikipedia.org/wiki/File:DB-25_male.jpg">
+<p align="center">
+<img height="240" title="Standard serial port connector DB-25" src="https://upload.wikimedia.org/wikipedia/commons/8/8f/DB-25_male.jpg" />
+</p>
+</a>
+
+When computers got into the mix, RS-232 became awkward. Big computers tended to be wired as DCE to talk to terminals, microcomputers tended to be wired DTE to talk to modems.
+
+The IBM-PC AT popularized a smaller 9-pin connector (DE-9, often referred to as DB-9) version of the RS-232 port.
+
+<a href="https://en.wikipedia.org/wiki/File:Serial_port.jpg">
+<p align="center">
+<img height="240" title="Standard serial port connector DE-9" src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/ea/Serial_port.jpg/800px-Serial_port.jpg" />
+</p>
+</a>
+
+Eventually, it became common to drop most or all of the out-of-band wires on serial ports, reducing them to a 3-wire interface (transmit-receive-ground). It also became common for 0V/+5V and later 0V/+3.3V to be the signaling levels, to avoid "weird" voltages and interface issues.
+
+Microsoft deliberately designed USB as a standard to replace RS-232; with its clunky wiring, various connectors, various voltages and transmit rates, it was far too difficult for the least-common-denominator consumer to use to connect devices to their PC. Because most MODEMs were still RS-232 at the time USB came out, Microsoft designed a USB "device class", CDC-ACM, specifically to talk to RS-232 adapters used with these MODEMs.
+
+[RS-232]: https://en.wikipedia.org/wiki/RS-232
+[RS-232 Standard]: https://store.accuristech.com/standards/tia-rs-232?product_id=2591953