diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 501f93f..625dbf9 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/hardware/configuration.md b/src/hardware/configuration.md new file mode 100644 index 0000000..1515fc8 --- /dev/null +++ b/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. diff --git a/src/hardware/gpio_pinout.md b/src/hardware/gpio_pinout.md index c494bb1..95c5a35 100644 --- a/src/hardware/gpio_pinout.md +++ b/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 ``` diff --git a/src/hardware/requirements.md b/src/hardware/requirements.md index 2609aa7..237898f 100644 --- a/src/hardware/requirements.md +++ b/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.