Add dev env setup docs and background info
This commit is contained in:
mycognosist
parent
dbe7033349
commit
32e6370115
|
|
@ -1,6 +1,9 @@
|
|||
# Summary
|
||||
|
||||
- [Introduction](./introduction.md)
|
||||
- [Story](./introduction/story.md)
|
||||
- [Design Principles](./introduction/design_principles.md)
|
||||
- [Quick Deployment](./quick_deployment.md)
|
||||
- [Hardware](./hardware/index.md)
|
||||
- [Requirements](./hardware/requirements.md)
|
||||
- [GPIO Pinout](./hardware/gpio_pinout.md)
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 238 KiB |
|
|
@ -1 +1,6 @@
|
|||
# Contributor's Guide
|
||||
|
||||
Please contact @glyph on Scuttlebutt or via email if you're excited about PeachCloud and wish to discuss potential contributions.
|
||||
|
||||
SSB: `@HEqy940T6uB+T+d9Jaa58aNfRzLx9eRWqkZljBmnkmk=.ed25519`
|
||||
Email: <glyph@mycelial.technology>
|
||||
|
|
|
|||
|
|
@ -1,63 +1,102 @@
|
|||
# Configuration
|
||||
|
||||
### Real-Time Clock (RTC)
|
||||
This page contains the detailed, step-by-step software configuration instructions required to ensure that all the hardware works correctly. Skip to the quick deployment section for the scripted deployment instructions.
|
||||
|
||||
**GPIO**
|
||||
|
||||
GPIO (General Purpose Input Output) appears to be working out-of-the-box, but be aware that all pin numbers are offset by 458 for Debian on the Raspberry Pi 3 (as mentioned in the [Debian RaspberryPi3 wiki](https://wiki.debian.org/RaspberryPi3)).
|
||||
|
||||
**RTC over I²C**
|
||||
|
||||
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:
|
||||
_Tested with DS1338 RTC module._
|
||||
|
||||
```bash
|
||||
sudo apt-get install python-smbus i2c-tools
|
||||
sudo modprobe i2c-dev
|
||||
sudo i2cdetect -y 1
|
||||
```
|
||||
Ensure `i2c-tools` and `python-smbus` Debian packages have been installed. Then run the following to ensure the RTC is correctly wired and connected to the Pi:
|
||||
|
||||
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.
|
||||
`sudo modprobe i2c-dev`
|
||||
`sudo i2cdetect -y 1`
|
||||
|
||||
Next, append `dtoverlay=i2c-rtc,ds1307` and `dtparam=i2c_arm=on` to `/boot/firmware/config.txt` and `i2c-dev` to `/etc/modules`.
|
||||
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.
|
||||
|
||||
The device tree must be patched in order to set the clock frequency for I²C devices:
|
||||
Append the following two lines to `/boot/firmware/config.txt`:
|
||||
|
||||
Copy `/boot/firmware/bcm2837-rpi-3-b.dtb` from the Pi microSD card to a computer running Linux. Run the following commands:
|
||||
`dtoverlay=i2c-rtc,ds1307`
|
||||
`dtparam=i2c_arm=on`
|
||||
|
||||
```bash
|
||||
sudo apt-get install device-tree-compiler
|
||||
cd /place/where/dtb/file/was/pasted
|
||||
dtc -I dtb -O dts > bcm2837-rpi-3-b.dts
|
||||
```
|
||||
Append the following line to `/etc/modules`:
|
||||
|
||||
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):
|
||||
`i2c-dev`
|
||||
|
||||
`clock-frequency = <0x186a0>`
|
||||
Patch the device tree in order to set the clock frequency for I²C devices:
|
||||
|
||||
Once patched, recompile the `dts` to binary blob format:
|
||||
_Note: the steps below can be shortened by downloading the [pre-patched `dtb` file](https://github.com/peachcloud/peach-config/raw/main/conf/bcm2710-rpi-3-b.dtb) from the [peach-config repo](https://github.com/peachcloud/peach-config) and using it to replace the `dtb` file on the Pi's SD card._
|
||||
|
||||
`dtc -O dtb -o bcm2837-rpi-3-b.dtb bcm2837-rpi-3-b.dts`
|
||||
Copy the existing `dtb` (device tree blob) from the Pi microSD card to a more powerful computer running Linux (exact location is up to you). You will find the `dtb` in the following location:
|
||||
|
||||
Copy the resulting `dtb` onto the Pi microSD card and overwrite `/boot/firmware/bcm2837-rpi-3-b.dtb`.
|
||||
`/boot/firmware/bcm2710-rpi-3-b.dtb`
|
||||
|
||||
_Note: the file may be named `bcm2837-rpi-3-b.dtb`. In that case, replace all instances of `bcm2710` in these instructions with `bcm2837`._
|
||||
|
||||
Once it has been copied to your Linux computer, run the following commands (on the Linux machine):
|
||||
|
||||
Install the compiler / decompiler:
|
||||
|
||||
`sudo apt-get install device-tree-compiler`
|
||||
|
||||
Change into the direction where you copied the `dtb` from the Pi:
|
||||
|
||||
`cd /place/where/dtb/file/was/pasted`
|
||||
|
||||
Generate a human-readable decompiled device tree (`dts`):
|
||||
|
||||
`dtc -I dtb -O dts > bcm2710-rpi-3-b.dts`
|
||||
|
||||
Open the `dts` in a text editor and add the clock-frequency property (line 570):
|
||||
|
||||
`clock-frequency = <0x186a0>;`
|
||||
|
||||
Save and exit the document. Recompile the patched `dts` to binary blob format:
|
||||
|
||||
`dtc -O dtb -o bcm2710-rpi-3-b.dtb bcm2710-rpi-3-b.dts`
|
||||
|
||||
Copy the resulting `dtb` onto the Pi microSD card and overwrite the old `dtb` file (you may wish to backup the old `dtb` first):
|
||||
|
||||
`cp bcm2710-rpi-3-b.dtb /boot/firmware/bcm2710-rpi-3-b.dtb`
|
||||
|
||||
Finally, run the following commands to complete the process:
|
||||
|
||||
```bash
|
||||
sudo modprobe i2c-bcm2835
|
||||
su
|
||||
echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-1/new_device
|
||||
exit
|
||||
sudo modprobe rtc-ds1307
|
||||
```
|
||||
`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.
|
||||
Run the `i2cdetect` tool to ensure the RTC kernel driver is working:
|
||||
|
||||
### OLED Bonnet
|
||||
`sudo i2cdetect -y 1`
|
||||
|
||||
A `UU` entry in the output arrays denotes success. If you still see `68` or similar, the module is not being controlled by the kernel driver.
|
||||
|
||||
Ensure no `i2c could not read clock-frequency property` errors persist in the kernel logs (`/var/log/kern.log`).
|
||||
|
||||
_Note: This Scuttlebutt dev-diary post by @glyph documents the process step-by-step (%aEVy1gyTSl4qrbazrwrgnrLs4pRVobELwQjH/TUtsAc=.sha256)._
|
||||
|
||||
**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:
|
||||
Begin by downloading the device tree overlay file: `mygpio.dtbo`.
|
||||
|
||||
```bash
|
||||
sudo mkdir /boot/firmware/overlays
|
||||
sudo cp mygpio.dtbo /boot/firmware/overlays/
|
||||
```
|
||||
`wget https://github.com/peachcloud/peach-config/raw/main/conf/mygpio.dtbo`
|
||||
|
||||
Create an `overlays` directory on the Pi filesystem:
|
||||
|
||||
`sudo mkdir /boot/firmware/overlays`
|
||||
|
||||
Copy the overlay file into the `overlays` directory:
|
||||
|
||||
`sudo cp mygpio.dtbo /boot/firmware/overlays/`
|
||||
|
||||
Append the following line to `/boot/firmware/config.txt`:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,21 @@
|
|||
# Requirements
|
||||
|
||||
Minimal hardware component requirements for prototyping and development:
|
||||
Development is currently taking place with the following hardware:
|
||||
|
||||
- Raspberry Pi 3B+ / 4 (or similar spec single-board computer)
|
||||
- Raspberry Pi 3B+
|
||||
- Adafruit 128x64 1.3" OLED Bonnet ([product page](https://www.adafruit.com/product/3531))
|
||||
- DS1338 Real-Time Clock (RTC) module ([datasheet](http://www.hobbytronics.co.uk/datasheets/DS1338-RTC.pdf))
|
||||
|
||||
A breadboard and male-to-female jumper wires are also recommended for prototyping.
|
||||
|
||||
If the exact parts specified above are not available, substitutes can be used - provided they conform the following specifications:
|
||||
|
||||
- OLED display
|
||||
- 128 x 64 pixels
|
||||
- SSD1306-compatible
|
||||
- Buttons
|
||||
- 7 push-buttons _or_ 2 push-buttons and 1 5-direction joystick
|
||||
- 7 x push-buttons _or_ 2 x push-buttons and 1 x 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.
|
||||
Note: the hardware peripherals listed on this page do not work out-of-the-box with Debian Buster ARM64. You will need to patch the device tree and run additional configuration steps (patches are applied automatically if following the 'quick deployment' method using install scripts). See Configuration in the Operating System section of this document for further information.
|
||||
|
|
|
|||
|
|
@ -2,4 +2,6 @@
|
|||
|
||||
PeachCloud is a low-power, lightweight hardware device designed to facilitate peer-to-peer communication across social networks. We aim to return (cloud) computing back into our homes and local communities in a way which fosters increased trust in one another and the socio-technical systems we inhabit.
|
||||
|
||||
|
||||
This guide is intended to comprehensively document the PeachCloud project. It includes information about the hardware and software which comprises the device, as well as insight into the goals and design principles the project has grown from.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,40 @@
|
|||
# Design Principles
|
||||
|
||||
The following design principles were created through collaborative story-telling and visioning at the start of the PeachCloud project. While not strictly technical in nature, this information is shared here to give future contributors and peers a feel for the guiding spirit behind this work. Implementation details should always be made in service of this underlying vision.
|
||||
|
||||
- Better communication infrastructure for local communities
|
||||
- Able to store the long-tail data (the niche content that isn’t mass popular but nevertheless important to support libraries of local culture and knowledge)
|
||||
- Able to support real-time media-rich interactions
|
||||
- Not just text, but also voice and video mail!
|
||||
- Able to transport your data with you as you move locations
|
||||
- Create local network topologies and local data centers to match our local social topologies
|
||||
- Less dependence on external networks, external data centers, etc
|
||||
- Accessible to users
|
||||
- Easy to get started for you and your community
|
||||
- Easy for non-technical people to use
|
||||
- The system is a teacher to guide you on your journey
|
||||
- Invite less technical people to become more technical
|
||||
- Simple on the surface, powerful under the hood
|
||||
- Example: more like Excel spreadsheets, less like Apple interfaces
|
||||
- The interface should embody the underlying system
|
||||
- Let all the internals leak out for you to see
|
||||
- A living system of activity playing on the physical lights
|
||||
- Allow users to look at the firehouse of logs, usage, metrics, etc
|
||||
- Easy to grok what is happening
|
||||
- Physical lights should give you the status at a glance
|
||||
- Friendly automation
|
||||
- Your personal robot friend, your home computer
|
||||
- No surprises, any automation should be upfront and clear
|
||||
- Be helpful, but don’t try to guess what the user wants
|
||||
- Give the user the power tools to automate their own desires
|
||||
- Accessible to contributors
|
||||
- Modules are well-documented
|
||||
- Code follows best practices
|
||||
- Focus on being accessible and maintainable, not being clever and complicated
|
||||
- Focus on being boring and just working, not being shiny and perfect
|
||||
- Provide an opinionated foundation to build flexible ecosystem
|
||||
- Frame is restrictive and has constraints, enables scope and freedom to play inside
|
||||
- “Bondage sets you free”
|
||||
- Contributions are more than tech
|
||||
- Living cultural documentation
|
||||
- Peer production as a deployment strategy
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
# Story
|
||||
|
||||
Below are excerpts from Scuttlebutt private messages exchanged between @dinosaur (Michael Williams) and @glyph (Andrew Reid) at the start of their collaboration in early-2018. These conversations helped tell the story of what PeachCloud was to become:
|
||||
|
||||
@dinosaur
|
||||
|
||||
> for me, i know at least one story in my mind, which relates to the story i told you about solarpunk trailer parks.
|
||||
|
||||
> in the book Walkaway, i was struck by how computers were portrayed. every home had a computer system to help automate the household. and not just physical automation as we know it today (automated cooking, automation fabrication, etc), but so much was social automation, group resource coordination, task planning and management. that’s what i find most exciting.
|
||||
|
||||
> so for me, PeachCloud is part of a larger story about every household having a home computer, which helps them connect with others, which helps them communicate with others, which helps them coordinate shared resources with others, which helps them get shit done with others.
|
||||
|
||||
> then, if every home (and the corresponding infrastructure) itself is modular, portable, reproducible, and enjoyable, then our home computers can support us in this ever-evolving lifestyle. i find this future very exciting!
|
||||
|
||||
@glyph
|
||||
|
||||
> I love the vision you put forward of the houeshold as facilitator of connecting, communicating, coordinating and acting.
|
||||
|
||||
> Perhaps it’ll come as no surprise, but I couldn’t help thinking of mycelium while reading your messages. I think this connects beautifully with what you shared about your Spirit-Being / Creature being a Tree: nurturing, calm, stable, sensorially-opened and receptive, deeply-rooted, seasonally-responsive. This also seems like a great metaphor for the household. Who wouldn’t want to dwell in a tree?! So then, perhaps PeachCloud could be envisioned as part of the rhizosphere of the household; the digital access-point to the Reciprocity Transport Layer (RTL) [fundamentally about sharing with one another and growing together].
|
||||
|
||||
> Here’s a little sketch I did this morning, inspired by your thoughts (there are some mixed metaphors / concerns in there but I think it’ll make sense to you). I took a high-level pass at thinking about measures of project success…will think-feel into this more deeply as we go. I also used the tree metaphor as a way to think about the layering of the interface:
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
# Quick Deployment
|
||||
|
||||
[](https://github.com/peachcloud/peach-config)
|
||||
|
||||
The instructions, configuration files and scripts referred to in this section can all be found in the [peach-config repo](https://github.com/peachcloud/peach-config).
|
||||
|
||||
## Prerequisite Steps
|
||||
|
||||
Download the latest Debian Buster preview image for RPi3 and flash it to an SD card (card is located at `/dev/mmcblk0` in this case):
|
||||
|
||||
`wget https://people.debian.org/~gwolf/raspberrypi3/20190628/20190628_raspberry-pi-3_buster_PREVIEW.img.xz`
|
||||
`xzcat 20190628_raspberry-pi-3_buster_PREVIEW.img.xz | sudo dd of=/dev/mmcblk0 bs=64k oflag=dsync status=progress`
|
||||
|
||||
## Setup
|
||||
|
||||
Quick setup commands to connect to a local WiFi network over the `wlan0` interface (assuming `eth0` connection is not possible):
|
||||
|
||||
```bash
|
||||
# username
|
||||
root
|
||||
# password
|
||||
raspberry
|
||||
# set interface up
|
||||
ip link set wlan0 up
|
||||
# append ssid and password for wifi access point
|
||||
wpa_passphrase <SSID> <PASS> > /etc/wpa_supplicant/wpa_supplicant.conf
|
||||
# open wpa_supplicant.conf
|
||||
nano /etc/wpa_supplicant/wpa_supplicant.conf
|
||||
```
|
||||
|
||||
[ Add the following two lines to top of file ]
|
||||
|
||||
```bash
|
||||
ctrl_interface=/run/wpa_supplicant
|
||||
update_config=1
|
||||
```
|
||||
|
||||
[ Save and exit ]
|
||||
|
||||
```bash
|
||||
# open network interfaces config
|
||||
nano /etc/network/interfaces
|
||||
```
|
||||
|
||||
[ Add the following lines to the file ]
|
||||
|
||||
```
|
||||
auto lo
|
||||
iface lo inet loopback
|
||||
|
||||
allow-hotplug wlan0
|
||||
auto wlan0
|
||||
iface wlan0 inet dhcp
|
||||
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
|
||||
```
|
||||
|
||||
[ Save and exit ]
|
||||
|
||||
`reboot now`
|
||||
|
||||
[ Pi should now be connected to the WiFi network ]
|
||||
|
||||
## Scripts
|
||||
|
||||
The `setup_dev_env.py` script can be executed once your Pi is internet-connected and `git` and `python` have been installed. It takes a `<USER>` argument to create a new system user. You will be prompted to enter a password for your newly created user. The script will install system requirements and copy configuration files relating to networking, I2C and RTC.
|
||||
|
||||
_TODO: Add flags to (de)select I2C, RTC and Rust install & config. Flags should also be added which allow the installer to choose between development environment and release environment configuration._
|
||||
|
||||
`apt update`
|
||||
`apt install git python`
|
||||
`git clone https://github.com/peachcloud/peach-config.git`
|
||||
`cd peach-config`
|
||||
`python scripts/setup_dev_env.py <USER>`
|
||||
|
||||
**IMPORTANT: Please do not forget to set a new password for the root user!**
|
||||
|
|
@ -1,7 +1,15 @@
|
|||
# Operating System
|
||||
|
||||
## Images
|
||||
|
||||
PeachCloud runs an _unofficial_ [preview image](https://people.debian.org/~gwolf/raspberrypi3/20190628/) of Debian 10 (Buster). Kernel version: 4.19.0-5-arm64.
|
||||
|
||||
Tested images are now available via the [Raspberry Pi Debian images](https://raspi.debian.net/) page on the Debian wiki. According to [Gunnar Wolf](https://gwolf.org/), project maintainer and Debian developer, the page: "should serve as a go-grab-it destination for regularly autobuilt images for the Raspberry Pi family". Note that these images are considered unofficial, ie. they are not part of an official Debian project.
|
||||
|
||||
## Why Debian?
|
||||
|
||||
In order to be flexible in supporting single-board computers beyond the Raspberry Pi alone, and to take full advantage of 64-bit support on ARMv8 devices, development for PeachCloud is being targeted at Debian ARM64.
|
||||
|
||||
Debian was chosen over the Raspbian operating system for several reasons:
|
||||
|
||||
- Full ARM64 support, unlike Raspbian which uses 32 bit mode
|
||||
|
|
|
|||
Loading…
Reference in New Issue