From f474a3e8dc5c2ed899d456ad6fc6da31bdc74b22 Mon Sep 17 00:00:00 2001 From: kdmukai Date: Sun, 12 Mar 2023 12:17:19 -0500 Subject: [PATCH 1/4] Update manual_installation.md --- docs/manual_installation.md | 46 +++++++++++++++++++++++++++++-------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/manual_installation.md b/docs/manual_installation.md index 236d77c46..bec76f2c0 100644 --- a/docs/manual_installation.md +++ b/docs/manual_installation.md @@ -58,12 +58,40 @@ passwd You will be prompted to enter the current password ("raspberry") and then to enter a new password twice. In our prepared release image, the password used is `AirG@pped!`. +### Install python3.10 +```bash +# install compiler dependencies +sudo apt update && sudo apt install -y build-essential zlib1g-dev \ + libncurses5-dev libgdbm-dev libnss3-dev openssl libssl-dev \ + libreadline-dev libffi-dev wget + +# Grab the python3.10 source +wget https://www.python.org/ftp/python/3.10.10/Python-3.10.10.tgz +tar -xzvf Python-3.10.10.tgz +cd Python-3.10.10 + +# configure takes ~6 minutes to check what is available +./configure --enable-optimizations + +# compiling takes ~80 minutes(!!) on the Pi Zero 1.3 +sudo make altinstall + +# cleanup +cd .. +rm -rf Python-3.10.10* + +# Make python3.10 the default version +sudo update-alternatives --install /usr/bin/python python /usr/local/bin/python3.10 1 +sudo update-alternatives --install /usr/bin/python3 python3 /usr/local/bin/python3.10 1 +``` + + ### Install dependencies Copy this entire box and run it as one command (will take 15-20min to complete): ``` -sudo apt-get update && sudo apt-get install -y wiringpi python3-pip \ - python3-numpy python-pil libopenjp2-7 git python3-opencv \ - python3-picamera libatlas-base-dev qrencode +sudo apt update && sudo apt install -y wiringpi python3-pip \ + python3-numpy python-pil libjpeg-dev zlib1g-dev libopenjp2-7 \ + git python3-opencv python3-picamera libatlas-base-dev qrencode ``` ### Install `zbar` @@ -103,7 +131,7 @@ sudo rm -rf bcm2835-1.60 ### Set up `virtualenv` ``` -pip3 install virtualenvwrapper +python -m pip install virtualenvwrapper ``` Edit your bash profile with the command `nano ~/.profile` and add the following to the end: @@ -117,7 +145,7 @@ Then `CTRL-X` and `y` to exit and save changes. Now create the python virtualenv for SeedSigner with these two commands: ``` source ~/.profile -mkvirtualenv --python=python3 seedsigner-env +mkvirtualenv seedsigner-env ``` For convenience you can configure your `.profile` to auto-activate the SeedSigner virtualenv when you ssh in. Once again `nano ~/.profile` and add at the end: @@ -166,16 +194,16 @@ where `pr_123` is any name you want to give to the new branch in your local repo ### Install Python `pip` dependencies: -``` -pip3 install -r requirements.txt +```bash +pip install -r requirements.txt ``` #### `pyzbar` -Note: The `requirements.txt` installs a fork of the python `pyzbar` repo (for now pointing to the fork in Keith's `kdmukai` github account [https://github.com/kdmukai/pyzbar](https://github.com/kdmukai/pyzbar)). +Note: The `requirements.txt` installs a fork of the python `pyzbar` repo. The fork is required because the main `pyzbar` repo has been abandoned. This [github issue](https://github.com/NaturalHistoryMuseum/pyzbar/issues/124#issuecomment-971967091) discusses the changes needed in order to support reading binary data from `zbar`, which is required for our `CompactSeedQR` format which writes byte data instead of strings. The changes specifically reference the following PRs which have already been merged into Keith's fork: * [PR 76](https://github.com/NaturalHistoryMuseum/pyzbar/pull/76/files): enables scanning to continue even when a null byte (`x\00`) is found. -* [PR 82](https://github.com/NaturalHistoryMuseum/pyzbar/pull/82): enable `zbar`'s new binary mode. Note that this PR has a trivial bug that was fixed in Keith's fork. +* [PR 82](https://github.com/NaturalHistoryMuseum/pyzbar/pull/82): enable `zbar`'s new binary mode. Note that this PR has a trivial bug that was fixed in our fork. ### Configure `systemd` to run SeedSigner at boot: ``` From a4ba719062ba0997d78e989981844407679d1215 Mon Sep 17 00:00:00 2001 From: kdmukai Date: Sun, 12 Mar 2023 14:19:19 -0500 Subject: [PATCH 2/4] Add sqlite3 for `coverage` compatibility --- docs/manual_installation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/manual_installation.md b/docs/manual_installation.md index bec76f2c0..3fcdc6bad 100644 --- a/docs/manual_installation.md +++ b/docs/manual_installation.md @@ -61,9 +61,11 @@ You will be prompted to enter the current password ("raspberry") and then to ent ### Install python3.10 ```bash # install compiler dependencies +# openssl, libssl-dev: ssl support when pip fetches packages +# libsqlite3-dev: required by `coverage` sudo apt update && sudo apt install -y build-essential zlib1g-dev \ libncurses5-dev libgdbm-dev libnss3-dev openssl libssl-dev \ - libreadline-dev libffi-dev wget + libreadline-dev libffi-dev wget libsqlite3-dev # Grab the python3.10 source wget https://www.python.org/ftp/python/3.10.10/Python-3.10.10.tgz From 5abd9fadf29c713d0e8c555fb0dc231513603ef6 Mon Sep 17 00:00:00 2001 From: kdmukai Date: Sun, 4 Jun 2023 11:32:21 -0400 Subject: [PATCH 3/4] Update manual_installation.md --- docs/manual_installation.md | 191 +++++++++++++++++++++++------------- 1 file changed, 125 insertions(+), 66 deletions(-) diff --git a/docs/manual_installation.md b/docs/manual_installation.md index 3fcdc6bad..00f0f5c46 100644 --- a/docs/manual_installation.md +++ b/docs/manual_installation.md @@ -15,11 +15,12 @@ For the following steps you'll need to either connect a keyboard & monitor to th ### Configure the Pi First things first, verify that you are using the correct version of the Raspberry Pi Lite operating system by typing the command: -``` +```bash cat /etc/os-release ``` + The output of this command should match the following text: -``` +```bash PRETTY_NAME="Raspbian GNU/Linux 10 (buster)" NAME="Raspbian GNU/Linux" VERSION_ID="10" @@ -33,7 +34,7 @@ BUG_REPORT_URL="http://www.raspbian.org/RaspbianBugs" ``` Now launch the Raspberry Pi's System Configuration tool using the command: -``` +```bash sudo raspi-config ``` @@ -45,6 +46,8 @@ Set the following: * `Locale`: arrow up and down through the list and select or deselect languages with the spacebar. * Deselect the default language option that is selected * Select `en_US.UTF-8 UTF-8` for US English + * Use the `TAB` button to select `Ok` and press `ENTER` + * On the next screen select `en_US.UTF-8` for the default locale * You will also need to configure the WiFi settings if you are using the #1 option above to connect to the internet When you exit the System Configuration tool, you will be prompted to reboot the system; allow the system to reboot and continue with these instructions. @@ -52,7 +55,7 @@ When you exit the System Configuration tool, you will be prompted to reboot the ### Change the default password Change the system's default password from the default "raspberry". Run the command: -``` +```bash passwd ``` You will be prompted to enter the current password ("raspberry") and then to enter a new password twice. In our prepared release image, the password used is `AirG@pped!`. @@ -60,7 +63,7 @@ You will be prompted to enter the current password ("raspberry") and then to ent ### Install python3.10 ```bash -# install compiler dependencies +# install compiler dependencies; takes ~1 minute on a Pi Zero 1.3 # openssl, libssl-dev: ssl support when pip fetches packages # libsqlite3-dev: required by `coverage` sudo apt update && sudo apt install -y build-essential zlib1g-dev \ @@ -72,26 +75,33 @@ wget https://www.python.org/ftp/python/3.10.10/Python-3.10.10.tgz tar -xzvf Python-3.10.10.tgz cd Python-3.10.10 -# configure takes ~6 minutes to check what is available +# configure takes ~6 minutes on a Pi Zero 1.3 to check what is available ./configure --enable-optimizations -# compiling takes ~80 minutes(!!) on the Pi Zero 1.3 +# compiling takes ~80 minutes(!!) on a Pi Zero 1.3 sudo make altinstall # cleanup cd .. -rm -rf Python-3.10.10* +sudo rm -rf Python-3.10.10* # Make python3.10 the default version sudo update-alternatives --install /usr/bin/python python /usr/local/bin/python3.10 1 sudo update-alternatives --install /usr/bin/python3 python3 /usr/local/bin/python3.10 1 ``` +Manually re-install `python3-apt` to avoid error messages in later steps: +```bash +sudo apt remove --purge python3-apt -y +sudo apt autoremove -y +sudo apt install python3-apt -y +``` + ### Install dependencies Copy this entire box and run it as one command (will take 15-20min to complete): -``` -sudo apt update && sudo apt install -y wiringpi python3-pip \ +```bash +sudo apt update && time sudo apt install -y wiringpi python3-pip \ python3-numpy python-pil libjpeg-dev zlib1g-dev libopenjp2-7 \ git python3-opencv python3-picamera libatlas-base-dev qrencode ``` @@ -102,17 +112,17 @@ sudo apt update && sudo apt install -y wiringpi python3-pip \ SeedSigner requires `zbar` at 0.23.x or higher. Download the binary: -``` +```bash curl -L http://raspbian.raspberrypi.org/raspbian/pool/main/z/zbar/libzbar0_0.23.90-1_armhf.deb --output libzbar0_0.23.90-1_armhf.deb ``` And then install it: -``` +```bash sudo apt install ./libzbar0_0.23.90-1_armhf.deb ``` Cleanup: -``` +```bash rm libzbar0_0.23.90-1_armhf.deb ``` @@ -120,7 +130,7 @@ rm libzbar0_0.23.90-1_armhf.deb This library "provides functions for reading digital inputs and setting digital outputs, using SPI and I2C, and for accessing the system timers." Run each of the following individual steps: -``` +```bash wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.60.tar.gz tar zxvf bcm2835-1.60.tar.gz cd bcm2835-1.60/ @@ -132,12 +142,12 @@ sudo rm -rf bcm2835-1.60 ``` ### Set up `virtualenv` -``` +```bash python -m pip install virtualenvwrapper ``` Edit your bash profile with the command `nano ~/.profile` and add the following to the end: -``` +```bash export WORKON_HOME=$HOME/.envs export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 source /home/pi/.local/bin/virtualenvwrapper.sh @@ -145,58 +155,27 @@ source /home/pi/.local/bin/virtualenvwrapper.sh Then `CTRL-X` and `y` to exit and save changes. Now create the python virtualenv for SeedSigner with these two commands: -``` +```bash source ~/.profile mkvirtualenv seedsigner-env ``` For convenience you can configure your `.profile` to auto-activate the SeedSigner virtualenv when you ssh in. Once again `nano ~/.profile` and add at the end: -``` +```bash workon seedsigner-env ``` -Optional: If you're going to be testing new code on the SeedSigner, you'll find yourself often needing to kill the SeedSigner code that automatically runs at startup (we'll be configuring this further down). As an extra convenience you can list the process id so that you can then kill it from the terminal: -``` -ps aux | grep main.py -``` - -Save your changes with `CTRL-X` and `y`. - -Now when you `ssh` in you'll see something like: -``` -pi 297 65.4 9.7 74096 36736 ? Rsl 09:26 10:29 /home/pi/.envs/seedsigner-env/bin/python main.py -pi 857 0.0 0.4 7332 1876 pts/0 S+ 09:42 0:00 grep --color=auto main.py -``` - -The top line is our SeedSigner code running. To stop it, run: -``` -kill 297 -``` -Where `297` is the process id listed in the output above (it'll be different each time). - ### Download the SeedSigner code: -``` +```bash git clone https://github.com/SeedSigner/seedsigner cd seedsigner ``` -If you want to run a specific branch within the main SeedSigner repo, switch to it with: -``` -git checkout yourtargetbranch -``` - -And if you want to test a pull request (PR), for example PR #123: -``` -git fetch origin pull/123/head:pr_123 -git checkout pr_123 -``` - -where `pr_123` is any name you want to give to the new branch in your local repo that will hold the PR. - ### Install Python `pip` dependencies: ```bash +# Takes 1hr 45min on a Pi Zero 1.3 pip install -r requirements.txt ``` @@ -207,13 +186,37 @@ The fork is required because the main `pyzbar` repo has been abandoned. This [gi * [PR 76](https://github.com/NaturalHistoryMuseum/pyzbar/pull/76/files): enables scanning to continue even when a null byte (`x\00`) is found. * [PR 82](https://github.com/NaturalHistoryMuseum/pyzbar/pull/82): enable `zbar`'s new binary mode. Note that this PR has a trivial bug that was fixed in our fork. -### Configure `systemd` to run SeedSigner at boot: + +### Finish configuring the virtualenv +Set the SeedSigner `src/` directory as the project directory for the virtualenv (this is where the virtualenv will take you when you activate it): +```bash +cd src +setvirtualenvproject ``` + +Test it out: +```bash +# exit the virtualenv +deactivate + +# change dirs to somewhere else +cd ~ + +# activate the virtualenv +workon seedsigner-env + +# you should now be back in the SeedSigner src/ directory +pwd +``` + + +### Configure `systemd` to run SeedSigner at boot: +```bash sudo nano /etc/systemd/system/seedsigner.service ``` Add the following contents to the text file that was created: -``` +```ini [Unit] Description=Seedsigner @@ -229,46 +232,96 @@ WantedBy=multi-user.target _Note: For local dev you'll want to edit the `Restart=always` line to `Restart=no`. This way when your dev code crashes it won't keep trying to restart itself. Note that the UI "Reset" will no longer work when auto-restarts are disabled._ -_Note: Debugging output is completely wiped via routing the output to `/dev/null 2>&1`. When working in local dev, you're better off disabling the `systemd` SeedSigner service and just directly running the app so you can see all the debugging output live._ +_Note: Debugging output is completely wiped via routing the output to `/dev/null 2>&1`. When working in local dev, you'll `kill` the `systemd` SeedSigner service and just directly run the code on demand so you can see all the debugging output live._ Use `CTRL-X` and `y` to exit and save changes. Configure the service to start running (this will restart the seedsigner code automatically at startup and if it crashes): -``` +```bash sudo systemctl enable seedsigner.service ``` Now reboot the Raspberry Pi: -``` +```bash sudo reboot ``` After the Raspberry Pi reboots, you should see the SeedSigner splash screen and the SeedSigner menu subsequently appear on the LCD screen (note that it can take up to 60 seconds for the menu to appear). + +#### Optional: kill `systemd` SeedSigner process on login +If you're going to be testing new code on the device, you'll find yourself often needing to kill the SeedSigner instance that `systemd` automatically runs at startup. + +You can configure your `~/.profile` to find and kill the SeedSigner process when you ssh in. + +`nano ~/.profile` and add at the end: +```bash +# Find the SeedSigner process and kill it +kill $(ps aux | grep '[m]ain.py' | awk '{print $2}') +``` + + ### Further OS modifications Disable and remove the system's virtual memory / swap file with the commands: -``` + +```bash sudo apt remove dphys-swapfile -y sudo apt autoremove -y sudo rm /var/swap ``` +## Manually start the SeedSigner code +```bash +# activate the virtualenv if you haven't already +workon seedsigner-env + +# You should now be in the SeedSigner src/ directory. List its contents: +ls + +# You should see the main.py file. Run it: +python main.py +``` + + ## Local testing and development -For those who will use the SeedSigner installation for testing/development, it can be helpful to change the system's host name so it doesn't potentially conflict with other Raspberry Pis that may already be present on your network. (For those who don't plan to use the installation for testing or development, you can skip this portion of the process.) To change the host name first edit the "hostname" with the command: + +### Run specific branches or PRs +The default branch is `dev`. If you want to run a specific release tag or a specific branch: +```bash +# release tag for v0.6.0: +git checkout 0.6.0 ``` -sudo nano /etc/hostname + +And if you want to test a pull request (PR), for example PR #123: +```bash +git fetch origin pull/123/head:pr_123 +git checkout pr_123 ``` -and change "raspberrypi" to "seedsigner" (or another name). Use `CTRL-X` and `y` to exit and save changes. You'll also need to edit the "hosts" file with the command: + +where `pr_123` is any name you want to give to the new branch in your local repo that will hold the PR. + + +### Change the host name +For those who will use the SeedSigner installation for testing/development, it can be helpful to change the system's host name so it doesn't potentially conflict with other Raspberry Pis that may already be present on your network. (For those who don't plan to use the installation for testing or development, you can skip this portion of the process.) To change the host name first edit the "hostname" with the command: + +```bash +sudo nano /etc/hostname ``` + +and change "raspberrypi" to "seedsigner" (or another name). Use `CTRL-X` and `y` to exit and save changes. + +You'll also need to edit the "hosts" file with the command: +```bash sudo nano /etc/hosts ``` + and change "raspberrypi" to "seedsigner" (or the other name you previously chose). Use `CTRL-X` and `y` to exit and save changes. ### Set a static IP Your local machine that `ssh`s into the SeedSigner can sometimes get confused if you're connecting to different SeedSigners that are all identified as `pi@seedsigner.local`. In this case it helps to set a static ip and just `ssh` directly to that instead. First find your current `nameserver`: -``` +```bash sudo cat /etc/resolv.conf ``` @@ -290,21 +343,26 @@ static domain_name_servers=192.168.1.254 `CTRL-X` and `y` to save changes. After your next reboot, access this SeedSigner using its new static ip: -``` +```bash +# Use the static ip you set above: ssh pi@192.168.1.200 + +# But the hostname will still work, too: +ssh pi@seedsigner.local ``` ### More convenient `ssh` access: Power SeedSigner devs will find themselves connecting to a lot of different SeedSigners. This can cause headaches with `ssh`'s built-in protections; a different device that uses the same `ssh` credentials is normally a potential spoofing attack. But we're doing this to ourselves on purpose and so we can carve out exceptions. On your local machine, run `nano ~/.ssh/config` and add to the end: -``` +```conf host seedsigner.local StrictHostKeyChecking no UserKnownHostsFile /dev/null User pi LogLevel QUIET +# Set this to the static ip you set above: host 192.168.1.200 StrictHostKeyChecking no UserKnownHostsFile /dev/null @@ -323,7 +381,7 @@ The second entry does the same for a specific static ip; you'll want this if you You can also configure the SeedSigner so that you don't have to enter the `pi` password when you `ssh` in. run `ssh-copy-id` with the same values that you connect via `ssh`: -``` +```bash ssh-copy-id pi@seedsigner.local # or if you're connecting over static ip, something like: @@ -337,7 +395,7 @@ _Note: If you don't have any ssh keys on your local machine, you'll need to crea ## Disable wifi/Bluetooth when using other Raspi boards If you plan to use your installation on a Raspberry Pi that is not a Zero version 1.3, but rather on a Raspberry Pi that has WiFi and Bluetooth capabilities, it is a good idea to disable the following WiFi & Bluetooth, as well as other relevant services (assuming you are not creating this installation for testing/development purposes). Enter the followiing commands to disable WiFi, Bluetooth, & other relevant services: -``` +```bash sudo systemctl disable bluetooth.service sudo systemctl disable wpa_supplicant.service sudo systemctl disable dhcpcd.service @@ -346,12 +404,13 @@ sudo systemctl disable networking.service sudo systemctl disable dphys-swapfile.service sudo ifconfig wlan0 down ``` + Please note that if you are using WiFi to connect/interact with your Raspberry Pi, the last command will sever that connection. You can now safely power the Raspberry Pi off from the SeedSigner main menu. If you do not plan to use your installation for testing/development, it is also a good idea to disable WiFi and Bluetooth by editing the config.txt file found in the installation's "boot" partition. You can add the following text to the end of that file with any simple text editor (Windows: Notepad, Mac: TextEdit, Linux: nano): -``` +```ini dtoverlay=disable-bt dtoverlay=pi3-disable-wifi ``` From e64c2dc5ba14f71720e50e4a15c5900556e5d3ad Mon Sep 17 00:00:00 2001 From: kdmukai Date: Sun, 4 Jun 2023 11:42:19 -0400 Subject: [PATCH 4/4] Update manual_installation.md --- docs/manual_installation.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/manual_installation.md b/docs/manual_installation.md index 00f0f5c46..addba92c6 100644 --- a/docs/manual_installation.md +++ b/docs/manual_installation.md @@ -64,8 +64,8 @@ You will be prompted to enter the current password ("raspberry") and then to ent ### Install python3.10 ```bash # install compiler dependencies; takes ~1 minute on a Pi Zero 1.3 -# openssl, libssl-dev: ssl support when pip fetches packages -# libsqlite3-dev: required by `coverage` +# * openssl, libssl-dev: ssl support when pip fetches packages +# * libsqlite3-dev: required by `coverage` sudo apt update && sudo apt install -y build-essential zlib1g-dev \ libncurses5-dev libgdbm-dev libnss3-dev openssl libssl-dev \ libreadline-dev libffi-dev wget libsqlite3-dev @@ -75,7 +75,7 @@ wget https://www.python.org/ftp/python/3.10.10/Python-3.10.10.tgz tar -xzvf Python-3.10.10.tgz cd Python-3.10.10 -# configure takes ~6 minutes on a Pi Zero 1.3 to check what is available +# Takes ~6 minutes on a Pi Zero 1.3 to check what is available ./configure --enable-optimizations # compiling takes ~80 minutes(!!) on a Pi Zero 1.3 @@ -90,7 +90,7 @@ sudo update-alternatives --install /usr/bin/python python /usr/local/bin/python3 sudo update-alternatives --install /usr/bin/python3 python3 /usr/local/bin/python3.10 1 ``` -Manually re-install `python3-apt` to avoid error messages in later steps: +Manually re-install `python3-apt` to avoid error messages in later steps (though, ironically, you will see the "ModuleNotFoundError: No module named 'apt_pkg'" error message during the `apt remove` step): ```bash sudo apt remove --purge python3-apt -y sudo apt autoremove -y @@ -99,9 +99,9 @@ sudo apt install python3-apt -y ### Install dependencies -Copy this entire box and run it as one command (will take 15-20min to complete): +Copy this entire box and run it as one command (will take a while to complete): ```bash -sudo apt update && time sudo apt install -y wiringpi python3-pip \ +sudo apt update && sudo apt install -y wiringpi python3-pip \ python3-numpy python-pil libjpeg-dev zlib1g-dev libopenjp2-7 \ git python3-opencv python3-picamera libatlas-base-dev qrencode ``` @@ -154,7 +154,7 @@ source /home/pi/.local/bin/virtualenvwrapper.sh ``` Then `CTRL-X` and `y` to exit and save changes. -Now create the python virtualenv for SeedSigner with these two commands: +Now create the virtualenv for SeedSigner: ```bash source ~/.profile mkvirtualenv seedsigner-env @@ -280,6 +280,8 @@ ls # You should see the main.py file. Run it: python main.py + +# To kill the process, use CTRL-C ```