From ff2305ee58d183eddd5a0efa3ba93e15abedf05a Mon Sep 17 00:00:00 2001 From: notplants Date: Mon, 29 Mar 2021 11:18:03 +0200 Subject: [PATCH] Add setup guides --- src/SUMMARY.md | 4 +- src/quick_deployment.md | 109 ---------------------- src/setup/index.md | 8 ++ src/setup/install_from_debian.md | 149 +++++++++++++++++++++++++++++++ src/setup/quick_deployment.md | 93 +++++++++++++++++++ 5 files changed, 253 insertions(+), 110 deletions(-) delete mode 100644 src/quick_deployment.md create mode 100644 src/setup/index.md create mode 100644 src/setup/install_from_debian.md create mode 100644 src/setup/quick_deployment.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3d6e554..6d8f8c8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,7 +4,9 @@ - [Story](./introduction/story.md) - [Design Principles](./introduction/design_principles.md) - [Features](./introduction/features.md) -- [Quick Deployment](./quick_deployment.md) +- [Setup](./setup/index.md) + - [Quick Deployment](./setup/quick_deployment.md) + - [Install From Debian](./setup/install_from_debian.md) - [Hardware](./hardware/index.md) - [Requirements](./hardware/requirements.md) - [GPIO Pinout](./hardware/gpio_pinout.md) diff --git a/src/quick_deployment.md b/src/quick_deployment.md deleted file mode 100644 index b64adb1..0000000 --- a/src/quick_deployment.md +++ /dev/null @@ -1,109 +0,0 @@ -# Quick Deployment - -[![GitHub logo](/assets/github_logo.png "peach-config GitHub repository")](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. - -Note: Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: - -```bash -wget https://raspi.debian.net/verified/20200831_raspi_3.img.xz -xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/mmcblk0 bs=64k oflag=dsync status=progress -``` - -On Mac OS, use the following command to flash the SD card: - -`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` - -Alternatively, use [Etcher](https://www.balena.io/etcher/). - -Note: if the above image link stops working, you can find the complete list of Raspberry Pi Debian images [here](https://raspi.debian.net/tested-images/). - -## 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 (by default raspberry debian requires no password, so we set the password for root here) -passwd -# set interface up (run command twice if you receive 'link is not ready' error on first try) -ip link set wlan0 up -# append ssid and password for wifi access point -wpa_passphrase > /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 ] - -```plaintext -ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wpactrl-user -update_config=1 -``` - -[ Save and exit ] - -```bash -# open network interfaces config -nano /etc/network/interfaces -``` - -[ Add the following lines to the file ] - -```plaintext -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. - -```bash -apt update -apt install git python -git clone https://github.com/peachcloud/peach-config.git -cd peach-config -# run the script with --i2c and --rtc flags to configure -python scripts/setup_dev_env.py -i -r ds3231 -``` - -Running the script with the `-h` flag shows the help menu: - -```bash -usage: setup_dev_env.py [-h] [-i] [-r {ds1307,ds3231}] user - -positional arguments: - user username for the default user account - -optional arguments: - -h, --help show this help message and exit - -i, --i2c configure i2c - -r {ds1307,ds3231}, --rtc {ds1307,ds3231} - configure real-time clock -``` - -A `` argument must be supplied to create a new system user. You will be prompted to enter a password for your newly created user. - -The script also allows optional configuration of I2C and real-time clock (RTC) modules. I2C configuration is necessary for the OLED display and physical interface to work correctly. RTC configuration is required for the real-time clock to work correctly. When passing the `-r` flag, the type of real-time clock module must be included (either ds1307 or ds3231). Selecting real-time clock configuration will not work if the I2C flag is not selected (in other words, the real-time clock requires I2C). - -Run the script as follows for a full installation and configuration with I2C and the ds3231 RTC module (username in this case is `peach`): - -`python scripts/setup_dev_env.py -i -r ds3231 peach` diff --git a/src/setup/index.md b/src/setup/index.md new file mode 100644 index 0000000..6d1a543 --- /dev/null +++ b/src/setup/index.md @@ -0,0 +1,8 @@ +# Setup + +The recommended way to install PeachCloud is from a PeachCloud disc image, +you can find a guide [here](./quick_deployment.md). + +Alternatively, you can also install PeachCloud onto a device already running Debian, +using the guide [here]('./install_from_debian.md'). + diff --git a/src/setup/install_from_debian.md b/src/setup/install_from_debian.md new file mode 100644 index 0000000..491cb2f --- /dev/null +++ b/src/setup/install_from_debian.md @@ -0,0 +1,149 @@ +# Installation From Debian Disc Image + +You can also setup PeachCloud by installing Debian onto an sd card, and then installing and running peach-config. +This is essentially how the PeachCloud disc image is created (see [peach-img-builder](https://github.com/peachcloud/peach-img-builder)). + +Here are the steps for installing peach-config on Debian. + +## Step 1: Flash The SD Card + +Download the latest Debian Buster preview image for RPi3 and flash it to an SD card. + +_Note:_ Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: + +```bash +wget https://raspi.debian.net/verified/20200831_raspi_3.img.xz +xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdb bs=64k oflag=dsync status=progress +``` + +On Mac OS, use the following command to flash the SD card: + +`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` + +Alternatively, use [Etcher](https://www.balena.io/etcher/). + +_Note:_ If the above image link stops working, you can find the complete list of Raspberry Pi Debian images [here](https://raspi.debian.net/tested-images/). + + +## Step 2: Connect To The Internet + +Use the following commands to connect to a local WiFi network over the `wlan0` interface (assuming `eth0` connection is not possible): + +```bash +# username +root +# password (by default raspberry debian requires no password, so we set the password for root here) +passwd +# set interface up (run command twice if you receive 'link is not ready' error on first try) +ip link set wlan0 up +# append ssid and password for wifi access point +wpa_passphrase > /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 ] + +```plaintext +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +``` + +[ Save and exit ] + +```bash +# open network interfaces config +nano /etc/network/interfaces +``` + +[ Add the following lines to the file ] + +```plaintext +auto lo +iface lo inet loopback + +auto eth0 +allow-hotplug eth0 +iface eth0 inet dhcp + +auto wlan0 +allow-hotplug 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 ] + +## Step 3: Install PeachCloud + + +You can run the following commands to add the PeachCloud apt repository and install PeachCloud: +``` bash +echo "deb http://apt.peachcloud.org/ buster main" > /etc/apt/sources.list.d/peach.list +wget -O - http://apt.peachcloud.org/pubkey.gpg | sudo apt-key add - +apt-get update +apt-get install -y python3-peach-config +peach-config setup -i -n -d peach +``` + + +#### Connecting + +Once the setup script has been run, connect to the system remotely over the local network using ssh or mosh: + +`ssh user@peach.local` or `mosh user@peach.local` + +There is a file with detailed instructions on how to connect via a direct ethernet cable located in `docs/direct-ethernet-setup.md` + + +#### Network + +Networking is handled by `wpa_supplicant` and `systemd-networkd`. + +The RPi connects to other networks with the `wlan0` interface and deploys an access point on the `ap0` interface. Only one of these modes is active at a time (client or access point). The RPi boots in client mode by default. + +To switch to access point mode: + +`sudo systemctl start wpa_supplicant@ap0.service` + +To switch to client mode: + +`sudo systemctl start wpa_supplicant@wlan0.service` + +_Note:_ No stopping of services or rebooting is required. + +To enable access point mode on boot: + +```bash +sudo systemctl disable wpa_supplicant@wlan0.service +sudo systemctl enable wpa_supplicant@ap0.service +``` + +A standalone networking configuration script is included in this repository (`scripts/setup_networking.py`). Network-related documentation can also be found in this repository (`docs`). + +This repository also contains a script for automatically starting an access point on `ap0` if the `wlan0` service is active but not connected (`scripts/ap_auto_deploy.sh`). The executable script is installed at `/usr/local/bin/ap_auto_deploy` and can either be run once-off or scheduled for repeated execution using a `systemd` service file and timer file (`conf/network/ap-auto-deploy.service` and `conf/network/ap-auto-deploy.timer`). When the timer is enabled for repeated execution, the script is automatically run 60 seconds after boot and every 180 seconds after that. + +To stop and disable the access point auto deploy service: + +```bash +sudo systemctl stop ap-auto-deploy.timer +sudo systemctl disable ap-auto-deploy.timer +``` + + +## Troubleshooting + +You may encounter DNS issues if your system time is inaccurate. Please refer to this [StackExchange answer](https://unix.stackexchange.com/a/570382/450882) for details. The steps to remedy the situation are offered here in brief: + +```bash +sudo -Es +timedatectl set-ntp 0 +# edit this line according to your current date & time +timedatectl set-time "2021-01-13 11:37:10" +timedatectl set-ntp 1 +exit diff --git a/src/setup/quick_deployment.md b/src/setup/quick_deployment.md new file mode 100644 index 0000000..e6bd9af --- /dev/null +++ b/src/setup/quick_deployment.md @@ -0,0 +1,93 @@ +# Quick Deployment + +This guide contains the steps for setting up PeachCloud on a raspberry pi using a PeachCloud disc image. + +## Step 1: Flash The SD Card + +Download the latest PeachCloud image from http://releases.peachcloud.org and flash it to an SD card. + +_Note:_ Be sure to use the correct device location in the `dd` command, otherwise you risk wiping another connected USB device. `sudo dmesg | tail` can be run after plugging in the SD card to determine the correct device location: + +```bash +wget http://releases.peachcloud.org/peach-imgs/20210225/20210225_peach_raspi3.img +sudo dd 20210225_peach_raspi3.img of=/dev/sdb bs=64k oflag=dsync status=progress +``` + +On Mac OS, use the following command to flash the SD card: + +`xzcat 20200831_raspi_3.img.xz | sudo dd of=/dev/sdcarddisc` + +Alternatively, use [Etcher](https://www.balena.io/etcher/). + +Your SD card now has a complete PeachCloud installation on it and is ready to use. + + +## Step 2: Connecting To The Internet + +#### Via access point + +When PeachCloud first starts it will start in access point mode. From your laptop or phone look for a wifi network +named "peach" and connect to it using the password "cloudless". + +Once you are connected, in your browser navigate to peach.local, +which should load the PeachCloud web interface. + +From the PeachCloud web interface, you can connect to the internet: +1. Settings -> Add Wifi Network (add your wifi credentials) +2. Click "Enable Wifi" + +This will take PeachCloud out of access point mode and into client mode. +If you connect to the same WIFI network as the peach, +you should now also be able to access the web interface via peach.local. + + +#### Via screen + +If you connect a screen and keyboard to the raspberry pi, you can login to the pi directly using +the following username and password: +``` +username: peach +password: peachcloud +``` + +You can then edit `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf` +and add your wifi credentials to the file: + +``` +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +network={ + ssid="your_ssid" + psk="your_wifi_password" +} +``` + +#### Via sd card + +If you create a file on the RASPIFIRM partition of the sdcard named `wpa_supplicant.conf`, +while PeachCloud is booting this file will be copied to `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf` +and used for connecting to wifi. + +This is a third way you can get the PeachCloud connected to the internet. + +``` +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +network={ + ssid="your_ssid" + psk="your_wifi_password" +} +``` + + +## Step 3: Getting Started + +You can then continue to configure your PeachCloud via the web interface (accessed by peach.local), +through the physical interface, or through ssh (`ssh peach@peach.local`). + +There is a file with detailed instructions on how to connect via a direct ethernet cable located [here](/software/operating_system/networking.md) + +TODO: link to PeachCloud caretaker guides for more detailed info on how to configure the device. + +When sshed into the device you can also configure and update the device using the peach-config CLI tool. +Documentation on how to use peach-config can be found [here](https://github.com/peachcloud/peach-config). \ No newline at end of file