Add GPIO pin-out info for RTC, add config for RTC and internal pull-ups

src/SUMMARY.md

@@ -5,6 +5,7 @@
   - [Requirements](./hardware/requirements.md)
   - [GPIO Pinout](./hardware/gpio_pinout.md)
   - [Physical Interface](./hardware/physical_interface.md)
+  - [Configuration](./hardware/configuration.md)
 - [Software](./software/index.md)
   - [Operating System](./software/operating_system/index.md)
     - [Networking](./software/operating_system/networking.md)

src/hardware/configuration.md

@@ -0,0 +1,66 @@
+# Configuration
+
+### Real-Time Clock (RTC)
+
+Additional configuration is required for Debian Buster ARM64 before I²C devices can function correctly. The following steps are required for the DS1338 module / DS1307 chip:
+
+Run an I²C scan to verify that the module is correctly wired to the Pi:
+
+```
+sudo apt-get install python-smbus i2c-tools
+sudo modprobe i2c-dev
+sudo i2cdetect -y 1
+```
+
+The final command in the sequence prints an array to the console, with `68` denoting the presence of the RTC module. This is a sign that the device is properly wired and connected.
+
+Next, append `dtoverlay=i2c-rtc,ds1307` and `dtparam=i2c_arm=on` to `/boot/firmware/config.txt` and `i2c-dev` to `/etc/modules`.
+
+The device tree must be patched in order to set the clock frequency for I²C devices:
+
+Copy `/boot/firmware/bcm2837-rpi-3-b.dtb` from the Pi microSD card to a computer running Linux. Run the following commands:
+
+```
+sudo apt-get install device-tree-compiler
+cd /place/where/dtb/file/was/pasted
+dtc -I dtb -O dts > bcm2837-rpi-3-b.dts
+```
+
+The third command outputs a human-readable decompiled device tree (`dts`). The clock frequency must be manually added to the generated `dts` file (line 570):
+
+`clock-frequency = <0x186a0>`
+
+Once patched, recompile the `dts` to binary blob format:
+
+`dtc -O dtb -o bcm2837-rpi-3-b.dtb bcm2837-rpi-3-b.dts`
+
+Copy the resulting `dtb` onto the Pi microSD card and overwrite `/boot/firmware/bcm2837-rpi-3-b.dtb`.
+
+Finally, run the following commands to complete the process:
+
+```
+sudo modprobe i2c-bcm2835
+su
+echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-1/new_device
+exit
+sudo modprobe rtc-ds1307
+```
+
+Run `sudo i2cdetect -y 1` to confirm RTC initialization.
+
+### OLED Bonnet
+
+A device tree overlay is required to activate the internal pull-up resistors on the Pi. Without this overlay, some of the buttons on the OLED bonnet will not work.
+
+Begin by downloading the device tree overlay file: `mygpio.dtbo` (TODO: add download link...maybe add the file to one of the repos). Then run the following commands to apply the overlay:
+
+```
+sudo mkdir /boot/firmware/overlays
+sudo cp mygpio.dtbo /boot/firmware/overlays/
+```
+
+Append the following line to `/boot/firmware/config.txt`:
+
+`device_tree_overlay=overlays/mygpio.dtbo`
+
+Reboot to apply the changes. All buttons on the OLED bonnet should now function correctly.

src/hardware/gpio_pinout.md

@@ -1,16 +1,17 @@
 # GPIO Pinout
 
-### OLED Bonnet
+The OLED bonnet (with buttons) and DS138 RTC module are connected to the Pi via GPIO pins.
 
 ```
-3v3 Power                       -   1
-BCM 2       (SDA)               -   3
-BCM 3       (SCL)               -   5
-BCM 4       (joystick center)   -   7
-BCM 17      (joystick up)       -   11
-BCM 27      (joystick left)     -   13
-BCM 22      (joystick down)     -   15
-BCM 23      (joystick right)    -   16
-BCM 5       (button A)          -   29
-BCM 6       (button B)          -   31
+3v3 Power                       -   1       // used by oled bonnet & rtc
+BCM 2       (SDA)               -   3       // used by oled bonnet & rtc
+BCM 3       (SCL)               -   5       // used by oled bonnet & rtc
+Ground                          -   6       // used by oled bonnet & rtc
+BCM 4       (joystick center)   -   7       // used by oled bonnet
+BCM 17      (joystick up)       -   11      // used by oled bonnet
+BCM 27      (joystick left)     -   13      // used by oled bonnet
+BCM 22      (joystick down)     -   15      // used by oled bonnet
+BCM 23      (joystick right)    -   16      // used by oled bonnet
+BCM 5       (button A)          -   29      // used by oled bonnet
+BCM 6       (button B)          -   31      // used by oled bonnet
 ```

src/hardware/requirements.md

@@ -2,9 +2,13 @@
 
 Minimal hardware component requirements for prototyping and development:
 
- - Raspberry Pi 3B+ / 4
+ - Raspberry Pi 3B+ / 4 (or similar spec single-board computer)
  - OLED display
    - 128 x 64 pixels
    - SSD1306-compatible
  - Buttons
    - 7 push-buttons _or_ 2 push-buttons and 1 5-direction joystick
+ - Real-Time Clock (RTC)
+   - DS1338 or DS1307
+
+Note: these peripherals do not work out-of-the-box with Debian Buster ARM64. You will need to patch the device tree and run additional configuration steps. See the Hardware Configuration section of the documentation for further information.