![pi0_title.jpg](https://cdn.steemitimages.com/DQmUYMPJC2mXddTdk6Y3DvTtpyJ9cvLMyW3w8oLoa1ifZdw/pi0_title.jpg) #### Repository https://github.com/SubstratumNetwork/SubstratumNode https://github.com/humicro/sub_node_pi_oled_ui.git #### What Will I Learn? - You will learn essential knowledge of Raspberry Pi Zero, Virtualbox, Xubuntu, Arch Linux and Substratum Node - You will learn how to install Xubuntu inside a virtual machine - You will learn how to install Arch Linux on a Raspberry Pi Zero, with a working Wi-Fi upon initial boot - You will learn how to compile a Rust project under Xubuntu - You will learn how to cross compile a Rust project for ARM-based devices - You will learn how to run Substratum Node in Raspberry Pi Zero - You will learn how to install a mini OLED screen on Raspberry Pi - You will learn how to use Python to create a user interface for the OLED screen on Raspberry Pi to control Substratum Node #### Requirements - Raspberry Pi Zero W (or WH) - Compatible charger (5V, at least 1A) - Micro SD card with a capacity of at least 2 GB - USB SD card reader, and an adapter for micro SD card - Personal computer running Windows, Linux or MacOS - Wireless router with internet access - (Optional) Adafruit® 128x64 OLED Bonnet for Raspberry Pi #### Difficulty Intermediate #### Tutorial Contents [**Substratum**](https://substratum.net/), *the foundation of the decentralized web*, is under active development. **Node** **`0.3.4`**, a new beta release featuring a refreshed UI, is just around the corner at the time of the publication of this article. > Substratum is developing an open-source foundation for the decentralized web, providing free, unrestricted, and uncensored access to content for a new Web 3.0. > The Substratum Network is a worldwide collection of nodes that uses industry-leading cryptography to deliver secure content anywhere, all without the need for VPNs or Tor. > -- Substratum While waiting for the **Node** **`0.5.0`** enabling *decentralization* and *monetization*, as well as the launch of **CryptoPay** and the exciting **"Project 3"**, why don't we do something interesting by using materials at hand? How about running a Node on the $5 Raspberry Pi Zero W, an extremely lightweight computer board? By following this guide, you will be able to: 1. Install Xubuntu inside a virtual machine 2. Deploy Linux file system to SD card under Windows/Linux/MacOS 3. Install Arch Linux on $5 Raspberry Pi Zero W 4. Get the Wi-Fi working upon initial boot 5. Cross compile Substratum Node for ARM-based devices 6. Run and test Substratum Node on Raspberry Pi Zero W 7. Install a mini OLED screen on Raspberry Pi Zero W 8. Use Python to create a user interface on an OLED screen to control Substratum Node As a sequel to the previous [Hitchhiker's Guide to Substratum Node on Raspberry Pi](https://steemit.com/utopian-io/@microoo/hitchhiker-s-guide-to-substratum-node-on-raspberry-pi), this guide introduces lots of new stuff: 1. By using a universal way to deploy Arch Linux file system to SD card via a virtual machine, all three major systems (Windows, Linux and MacOS) are supported. You don't have to rely on a native Linux system any more to follow this guide. 2. Wi-Fi on Raspberry Pi works upon the initial boot. 3. Easier ways to find the IP address of Raspberry Pi. 4. Instead of native compilation, Substratum Node is now cross compiled to support more ARM architectures - not only the 64-bit aarch64, but also 32-bit armv6 and armv7, and potentially even more systems. The compiled binary works on not only the 64-bit Arch Linux ARM operating system, but also the popular Raspbian, and any other Linux on ARM. 5. Raspberry Pi Zero is much lighter weight than Raspberry Pi 3, and it costs only $5. 6. It introduces a fun way to interact with Substratum Node via a mini OLED screen bearing physical buttons via a Python script. > "If you've done six impossible things this morning, why not round it off with breakfast at Milliways, the Restaurant at the End of the Universe." > -- The Restaurant at the End of the Universe, Douglas Adams Don't panic! If you managed to follow this guide, you are overqualified to enjoy a breakfast at *Milliways, the restaurant at the end of the universe* (**SUB** accepted ðŸš€). Just relax and enjoy [Abram](https://twitter.com/abramcookson)'s [*SUB & Coffee*](https://www.pscp.tv/abramcookson) and [Justin](https://twitter.com/overridepro)'s [*Insights*](https://www.youtube.com/channel/UCxUJoTH0XLERKl55zGnFI6g). ##### 0. What hardware do you need? ![pi0_hardware.jpg](https://cdn.steemitimages.com/DQmbi59TWZAVC7EpqmSZpBsyafuYaJ5VUBxZzuwBeTv6s1i/pi0_hardware.jpg) * **Raspberry Pi Zero W (or WH)** You need a Raspberry Pi Zero, which is the most lightweight computer board in the Raspberry Pi family. It comes with four flavors so far: Raspberry Pi Zero, Raspberry Pi Zero 1.3, Raspberry Pi Zero W, and Raspberry Pi Zero WH. Please note only the ones featuring a **W** have built-in Wi-Fi support, so make sure you have the **W** or **WH** version. **WH** version is basically the same as **W**, except that it has pre-soldered headers, making it convenient to connect to an add-on board. If you'd like to use the mini OLED screen but don't want to solder the headers by yourself, go with the **WH** version, which is a little bit more expensive at $13.99. The **W** version is truly $5. You can pick up one at this unbelievable price at [Micro Center](http://www.microcenter.com/product/486575/zero_w) (pun intended). ![pi0_pi_family.jpg](https://cdn.steemitimages.com/DQmQcV3uuywj2jMTP2pVk3typB6ea5VnVPhywjo6HUXe6Wc/pi0_pi_family.jpg) * **Power cord** You need a 5V power cord bearing a micro USB connector compatible to the Pi Zero. Pi Zero is tiny and consumes very little power, so 1A is enough to support the board itself and the additional OLED display. If you happen to have the 2A or higher version for Raspberry Pi 3, no worries, it works, as long as it is 5V. * **Micro SD card** You need a micro SD card of at least 2G capacity. The Arch Linux ARM system takes less than 1G space. However, it might be quite a challenge nowadays to find an SD card smaller than 8 GB. ðŸ˜‚ I recommend getting the SD card of a reputable brand to avoid data loss. * **USB SD card reader, and a micro SD card adapter** For Xubuntu *inside a virtual machine* to access your SD card to deploy file system, you may have to use a USB SD card reader, since a native SD card slot embedded in a laptop may not be recognized by the guest system. (Of course, if you are running a native Linux instead of a virtual machine, as in my previous guide, the native SD card reader still works.) * **Personal computer running 64-bit Windows, Linux or MacOS** Anyone who has a personal computer running Windows, Linux or MacOS will be able to follow this guide, since all steps are done in the Xubuntu guest system inside a virtual machine. In addition to deploying Linux system to an SD card, and connecting to Raspberry Pi via `ssh`, this computer will also be used for cross compiling, so make sure it's running a 64-bit system. If you have a Linux running natively on your computer, that's even better. I'm sure you will also be able to follow this guide, with modifications at certain steps. * **Wireless router connected to internet** Raspberry Pi Zero W doesn't have an Ethernet port, so you have to use a Wi-Fi router. * (Optional) **Adafruit 128x64 OLED Bonnet for Raspberry Pi** This is a fancy add-on for your Raspberry Pi Zero W, but I promise you will like it once installed. ##### 1. Install Xubuntu to a virtual machine To deploy Linux system to an SD card, to connect to Raspberry Pi via `ssh`, and to cross compile, you'd better have a Linux system. But what if you don't have one at hand? Don't panic! You are covered by this guide. You will install and run an full featured Linux Desktop system inside a virtual machine on your computer. * For virtualization, there are various ways and tools, such as [Cygwin](https://en.wikipedia.org/wiki/Cygwin), [Hyper-V](https://en.wikipedia.org/wiki/Hyper-V), [VMware Workstation](https://en.wikipedia.org/wiki/VMware_Workstation), [Parallels Desktop](https://en.wikipedia.org/wiki/Parallels_Desktop_for_Mac), and the now famous [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux). Here I choose the classic and free option: [**Virtualbox**](https://en.wikipedia.org/wiki/VirtualBox). * As of Linux distributions, I originally chose the most popular Ubuntu so even absolute beginners can catch up. However, during the writing of this tutorial, I found out Ubuntu 18.04 ran *unbearably slow* inside Virtualbox after the installation of the required Guest Additions package, possibly due to certain bug in Ubuntu that caused `GNOME` desktop environment visuals extreamly slow. So I then chose the derived **Xubuntu** distribution, which uses the lightweight `XFCE` desktop environment. It runs so much faster! ###### a. Install Virtualbox Download Virtualbox for your operating system from [here](https://www.virtualbox.org/wiki/Downloads) and install. In addition to the main package, you'd better also install the *Oracle VM VirtualBox Extension Pack* to support USB 2.0 & 3.0. Your USB SD card reader may not be recognized without the extension package. The installation is trivial so I won't describe it here. Tutorial video in this section shows steps *c - e* only. ###### b. Download Xubuntu image file Download the Xubuntu image file from [the official website](https://xubuntu.org). Of course you want the newest version (*18.04 Bionic Beaver* at the time of writing) and *64-bit*. The *Desktop* and *LTS* version is recommended for a user-friendly and stable system. Go to the download page and get the corresponding `iso` image file. At the time of writing, you should be able to get **`xubuntu-18.04.1-desktop-amd64.iso`**. ###### c. Create a virtual machine for Xubuntu Let's create a new virtual machine. 1. Open Virtualbox. 2. Click "Machine" -> "New". 3. Create a name for your virtual machine. If you use "Xubuntu" as the name, the software automatically chooses the correct Type (Linux) and Version (Ubuntu 64-bit) for you. Once done, click "Next". 4. Allocate a suitable memory size according to your system availability. Make sure you leave enough memory for your host system. Once done, click "Next". 5. Keep the default "Create a virtual hard disk now". Click "Create". 6. Keep the default "VDI (Virtualbox Disk Image)". Click "Next". 7. Keep the default "dynamically allocated". Click "Next". 8. Set a suitable disk space. You don't have to worry about that it may occupy too much of your hard disk space. It only takes up what it needs and will dynamically expand over actual usage. I usually set a size large enough (like 500 GB) in case it is needed in future. Once done, click "Create". 9. Ok, the virtual machine is now created and ready for use. In addition, I would suggest you to do more optimization in the settings. Keep the "Xubuntu" virtual machine selected, and click "Machine" -> "Settings": * In "General" -> "Advanced", set "Shared Clipboard" and "Drag 'n Drop" both to "Bidirectional", so you can easily share clipboard and files between guest and host. * In "System" -> "Motherboard", uncheck "Floppy". Who still uses floppy? * In "System" -> "Processor", allocate multiple CPUs for guest system according to your system availability. I have a quadcore CPU with Hyper-Threading (meaning 8 virtual cores), so I allocate 4 virtual cores for guest system. Since you will be doing cross compilation in the guest system, this parameter may greatly affect your compilation speed. * In "System" -> "Acceleration", make sure you have "VT-x/AMD-v" enabled if your CPU supports. This can make the guest system run much faster. * In "Display" -> "Screen", allocate enough "Video Memory" for your guest system according to the availability of your video card, and check "Enable 3D Acceleration". * **[Required]** In "Storage" -> "Storage Devices" -> "Controler: IDE", select "Empty", and load your Xubuntu image file (**xubuntu-18.04.1-desktop-amd64.iso**) by clicking the disk icon. This loads the Xubuntu CD image into the virtual CD drive. * In "Audio", uncheck "Enable Audio" to disable audio, because you don't need it... * **[Important]** In "USB", select the correct version (1.1, 2.0 or 3.0) matching your physical USB ports. * Click "OK" to save the setting. ###### d. Install Xubuntu inside the virtual machine Your physical computer is the **HOST**, and we are going to install a **GUEST** operating system inside the virtual machine. 1. By double clicking the "Xubuntu" virtual machine, or by selecting "Xubuntu" virtual machine and click "Machine" -> "Start" -> "Normal Start", you start the installation process of Xubuntu guest. 2. It boots into the Xubuntu live system on the CD. Click "Install Xubuntu" when available. 3. Keep the default "Keyboard layout", and click "Continue" 4. Keep the default "Download updates while installing Xubuntu". Mostly you don't need any additional third-party software. Click "Continue". 5. Keep the default "Erase disk and install Xubuntu" and click "Install Now". A warning message pops up, confirming that the disk will be formatted. Don't panic! It will only erase the content of the virtual disk file, not your physical disk. Click "Continue". 6. Set the time zone. Click "Continue". 7. Provide your "Name", "Computer's name", "Username" and "Password". In future, you will login using your "User name" and "Password". "Computer's name" is the name of your virtual machine that others in the network can see. Click "Continue". 8. The automatic installation process begins. Be patient. 9. Once the installation is complete, Click the "Restart Now" button. 10. It gives you a message "Please remove the installation medium, then reboot". So, let's check if the installation medium is still in the virtual CD drive. Click "Devices" -> "Optical Drives". None of the medium is selected in my case, since the system has already ejected the image. Now click "Machine" -> "Reset" to reboot. 11. Guest system restarts, and boot into your newly installed Xubuntu. 12. Click user name, enter password, and log in. ###### e. Essential settings of Xubuntu 1. Important programs We will use mainly the "Terminal Emulator" in this guide. You may also want to use "File Manager" and "Mousepad" text editor. Click topleft icon to open the start menu. You can clean up your favorates, by removing unnecessary icons and placing the most important applications. 2. Update system Open Terminal Emulator, and run the following commands to update your system ``` sudo apt update sudo apt upgrade ``` (Important) If a new kernel is installed, you need to reboot Ubuntu. 3. Install Guest Additions If you open up a text editor inside and outside the virtual machine, and try copying & pasting between host and guest, you will find out that it doesn't work yet. To make clipboard sharing work, and more importantly to get USB devices work, you need to install "Guest Additions". * First, install required packages for building kernel modules. ``` sudo apt install build-essential module-assistant dkms ``` * Second, prepare your system to build kernel module. ``` sudo m-a prepare ``` * Third, insert Guest Additions Image. Click "Devices" on virtualbox toolbar, and click "Install Guest Additions Image". The "VBox_GAs" image will be mounted, and the "VBox_GAs" folder is automatically opened. * Fourth, install. Right click in the folder, and choose "Open Terminal Here". Then in the terminal, enter the following command to start the installation. ``` sudo ./autorun.sh ``` Wait till it's done. Press ENTER key to exit. * Finally, eject the image, and reboot Right click the CD icon on your desktop, click "Eject Volume" to eject the installation image. Open start menu to "Restart". Clipboard sharing and other features should be working after boot up. 4. Trivial Settings * Terminal Emulator Open the Terminal Emulator, click "Edit" -> "Preferences" -> "Appearence", and set a larger font size. * Mousepad Open the Mousepad, click "View" and check the "Line Numbers", making it convinient to identify lines in the editor. In "View" -> "Select Font", you can set a larger font size. ##### 2. Deploy Linux system to SD card under Xubuntu in a virtual machine Now let's deploy Arch Linux (ARMv6 version) to your micro SD card, which will be used as system drive by Raspberry Pi Zero. It is based on the instruction from [archlinuxarm.org](https://archlinuxarm.org/platforms/armv6/raspberry-pi). The steps are mostly the same as in my previous guide. Make sure you download the correct version of Arch Linux (according to the specific hardware architecture of your Raspberry Pi), and perform the additional Wi-Fi setting. Here are the detailed steps for Raspberry Pi Zero W: ###### a. Insert micro SD card While running Xubuntu in Virtualbox, plug the USB reader (containing micro SD card) into your computer. ###### b. Make SD card available to Xubuntu On the status bar at the bottom of your Virtualbox, right click the USB icon, and select the "reader" to make it available to Xubuntu. If you encounter an error, USB setting is possibly wrong. In this case, power off Xubuntu, click "Machine" -> "Settings" -> "USB", and select the USB version matching the USB port connecting to the reader. Then redo steps *a - b*, and Xubuntu system should be able to detect the SD card reader. ###### c. Deploy Arch Linux ARM system to SD card Open up the Terminal application. Time for commands! 1. Create partitions on SD card ``` lsblk ``` Run this command to list the drives on your computer (the guest system inside virtual machine, precisely), and find the **disk name corresponding to your SD card**. In my case, it's labeled as `sdb`. Yours can be different. Double check the displayed capacity to make sure it matches your micro SD card. Let's use `fdisk` to work on your SD card's partition. Make sure you use the specific disk name (instead of `sdb`) corresponding to your SD card for the following command. ``` sudo fdisk /dev/sdb ``` As instructed, at the fdisk prompt, do the following: Type **`o`**. This will clear out any partition on the drive. Type **`p`** to list partitions. There should be no partition left. Type **`n`**, then **`p`** for primary, **`1`** for the first partition on the drive, press **ENTER** to accept the default first sector, then type **`+100M`** for the last sector. Type **`t`**, then **`c`** to set the first partition to type W95 FAT32 (LBA). Type **`n`**, then **`p`** for primary, **`2`** for the second partition on the drive, and then press **ENTER twice** to accept the default first and last sector. Write the partition table and exit by typing **`w`**. 2. Format and mount the two partitions Make sure you use `lsblk` to find the names for the newly created partitions on SD card. Replace `sdb1` and `sdb2` in the following commands with these actual names accordingly. ``` lsblk sudo mkfs.vfat /dev/sdb1 mkdir boot sudo mount /dev/sdb1 boot sudo mkfs.ext4 /dev/sdb2 mkdir root sudo mount /dev/sdb2 root ``` 3. Download Arch Linux ``` wget http://os.archlinuxarm.org/os/ArchLinuxARM-rpi-latest.tar.gz ``` 4. Gain root status From now on, you need to run the commands as root, but not via `sudo`. However, before a root account can be used in Xubuntu, a root password needs to be set first via the following command: ``` sudo passwd root ``` Choose your root password wisely. Note it's a new password different from your user password. (You will use this root password mostly for `su` command. You still use your user password for `sudo`) Now you can run `su` and enter root password to acquire root status. ``` su ``` 5. Extract the filesystem For this step, you need `bsdtar`, which is not installed in Xubuntu by default. Run the following command to install it. ``` apt install libarchive-tools ``` To extract the filesystem: ``` bsdtar -xpf ArchLinuxARM-rpi-latest.tar.gz -C root ``` And to make sure everything is written into SD card: ``` sync ``` 6. Setup Wi-Fi Copy the following multiline commands, and run it in Terminal in one shot. It basically creates a wireless network interface that obtains IP automatically from router. ``` cat << EOF >> root/etc/systemd/network/wlan0.network [Match] Name=wlan0 [Network] DHCP=yes EOF ``` Use your own Wi-Fi access information in following commands, by replacing *WIFI_ACCESS_POINT* and *WIFI_PASSWORD* with the actual strings. This command stores your encrypted Wi-Fi password in a configuration file. ``` wpa_passphrase WIFI_ACCESS_POINT WIFI_PASSWORD > root/etc/wpa_supplicant/wpa_supplicant-wlan0.conf ``` Create a system service so the wireless network interface is enabled on boot. ``` ln -s /usr/lib/systemd/system/wpa_supplicant@.service root/etc/systemd/system/multi-user.target.wants/wpa_supplicant@wlan0.service ``` 7. Double check the host name of Arch Linux ARM system ``` cat root/etc/hostname ``` The default name `alarmpi` (standing for Arch Linux ARM Pi) should show up. If not, please remember the actual name. This will be the host name of your Raspberry Pi Zero. (The `aarch64` system in my previous guide uses `alarm` as the default host name) 8. Get `boot` partition ready, unmount and exit ``` mv root/boot/* boot umount boot root exit ``` Yes, `exit` as soon as you don't need root privilege, to be safe :) ###### d. Disconnect SD card from Xubuntu Right click the USB icon at the bottom of Virtualbox, and unselect the "reader" to make it completely unmounted from Xubuntu. ##### 3. Connect to Raspberry Pi Zero W ###### a. Boot up Insert micro SD card to your Raspberry Pi Zero W, and connect the power cord. Your Pi Zero should boot up within half a minute. ###### b. Find IP address of your Pi Zero You need to find out the IP address of your Pi Zero for connection. There are various ways to do so. Try any one of the following methods: * (Option 1) Get the host name resolved by your router If both of your host and guest systems' DNS were automatically obtained, you may be able to get your Pi's IP address by simply asking your router :) From the Terminal in your Xubuntu, run the following command to search for the IP address of a computer named `alarmpi` (or the actual hostname you recorded in section `2.c.7`): ``` host alarmpi ``` If you are lucky enough, you may find the desired IP address in the form of *x.x.x.x* from the returned result. This is the simplest way that I know to find the assigned IP address of a Raspberry Pi! No more guessing, external display, or peeking in the wireless router page! The mighty power of a Linux command! * (Option 2) Peek in router's setting page Read router's user manual, and you will know how to get into your router's setting page. For example, it can be like visiting `http://192.168.1.1` from a browser and logging in with a specific pair of username and password. The information is different for each brand. The page may list all the devices connected to the router. Find the device named `alarmpi` (or the actual name if different) and record the IP address. * (Option 3) The powerful `nmap` If you know that your host computer is assigned with an IP of `192.168.1.x`, then your Pi connected to the same router is probably assigned with an IP address in a similar form: `192.168.1.y`. In the Terminal of Xubuntu, simply use `nmap` command to scan a range of IPs. ``` nmap 192.168.1.* ``` * (Option 4) 3rd party tools You can try a 3rd party tool like [Angry IP Scanner](https://angryip.org), though I still recommend using native commands whenever possible. * (Option 5) Manual Well, you can still guess the IP address out by manually try the addresses one by one: `192.168.1.2`, `192.168.1.3`, ... ###### c. Connect to your Pi from Xubuntu From the Terminal in your Xubuntu, run following command using the actual *IP_ADDRESS* of your Raspberry Pi Zero, and enter password `alarm`. ``` ssh alarm@IP_ADDRESS ``` In the Arch Linux ARM system of your Raspberry Pi Zero, the default user is `alarm` with password `alarm`, which stands for `Arch Linux ARM`. The root user is `root` with password `root`. You need to type `yes` and hit **ENTER** key upon initial connection. Now you are remotely controlling your Raspberry Pi Zero from Xubuntu Terminal. The command line prompt has changed to **`[alarm@alarmpi ~]$`**, indicating user `alarm` at home path (**`~`**) on host `alarmpi`. Make sure you always keep an eye on this part to know whether you are running the command for Xubuntu, or for Raspberry Pi Zero. ##### 4. Essential configuration of Arch Linux on Raspberry Pi Zero W Now that you are logged in as user `alarm` (password `alarm`) via `ssh` from Xubuntu, several configurations are needed for your newly installed Arch Linux on Raspberry Pi Zero. First you need to run `su` and enter password `root` to acquire root privilege. `sudo` is not available yet. ``` su ``` Second, Initialize the pacman keyring and populate the Arch Linux ARM package signing keys, per Arch Linux ARM instruction. ``` pacman-key --init pacman-key --populate archlinuxarm ``` Third, install `sudo` ``` pacman -S sudo ``` Fourth, allow `sudo` ``` EDITOR=nano visudo ``` You are now reading the text via nano editor. Find the line `# %wheel ALL=(ALL) ALL`. Delete the `#` at the line head. `Ctrl+O` to save the file, press `ENTER` key to confirm, and `Ctrl+X` to exit the editor. Now you can quit the risky root account, and go back to the normal account `alarm`. ``` exit ``` From now on, you can run `sudo` as user `alarm`. So, let's update the system. ``` sudo pacman -Syu ``` Yes, this is the first time you run `sudo` in this system. You get a friendly warning :) Reboot. ``` sudo reboot now ``` In the next section, we will go back to run commands in Xubuntu locally. To exit from remote Raspberry Pi Zero, run: ``` exit ``` The command line prompt should have changed back to **`YOUR_USER_NAME@YOUR_COMPUTER_NAME:~$`**. ##### 5. Compile Substratum Node under Xubuntu Before performing the anticipated cross compilations, let's first test the regular native compilation of Substratum Node in a 64-bit Xubuntu system. You can of course use any 64-bit Linux operating system, as long as you've installed all the corresponding packages. Please run following commands step by step in the Terminal of Xubuntu. Note: The commands are for Xubuntu itself, not the remotely controlled Raspberry Pi Zero! If you happen to be still in a `ssh` session, use command `exit` to disconnect from the remote Raspberry Pi Zero. ###### a. Development requirements First, make sure the system is up-to-date. You may want to reboot afterward if there is a kernel update. ``` sudo apt update sudo apt upgrade ``` Second, install essential development packages for Substratum Node compilation. ``` sudo apt install build-essential git libssl-dev pkg-config cmake curl ``` Third, install Rust via the following command: ``` curl https://sh.rustup.rs -sSf | sh ``` when asked, type `1` and hit **ENTER** to choose the "Proceed with installation (default)" option. Once done, log out and log back in. Rust is now ready to use. ###### b. Get source code of Substratum Node Download Substratum Node source code from [official repository on GitHub](https://github.com/SubstratumNetwork/SubstratumNode) by following command: ``` git clone https://github.com/SubstratumNetwork/SubstratumNode.git ``` And get into the directory. ``` cd SubstratumNode ``` ###### c. Modify source code The compilation will be done sequentially for multiple components - TEST_UTILS, SUB_LIB, ENTRY_DNS, NEIGHBORHOOD, HOPPER, PROXY SERVER, PROXY CLIENT, NODE, DNS UTILITY and NODE UI. In this guide, we will setup DNS manually, and run Node in a headless mode, so we don't really need DNS UTILITY and NODE UI. Modify file `ci/all.sh` to skip the compilation of the two components. Use either `nano ci/all.sh` in command line, or a Text Editor to comment out the lines corresponding to DNS UTILITY & NODE UI by appending `#` at the head of each line. The modified lines will appear as follows: ``` ... ... ... #echo "*** DNS UTILITY HEAD ***" #cd "$CI_DIR/../dns_utility" #ci/all.sh "$PARENT_DIR" #echo "*** DNS UTILITY TAIL ***" #echo "*********************************************************************************************************" #echo "*********************************************************************************************************" #echo "*** NODE UI HEAD ***" #cd "$CI_DIR/../node_ui" #ci/all.sh #echo "*** NODE UI TAIL ***" #echo "*********************************************************************************************************" #echo "*********************************************************************************************************" ``` Save the file. ###### d. Compilation Now, go back to Terminal, under path `~/SubstratumNode`, start the compilation. ``` ci/all.sh ``` (You may be asked to enter your password for the integration test in the end.) Your compiled `SubstratumNode` binary will appear at `~/SubstratumNode/node/target/release/SubstratumNode` OK, it worked, proving that our compilation setup is functional. I won't perform any test run here. Go straight ahead to the exciting cross compilation in the next section! ##### 6. Cross compile Substratum Node under Xubuntu From 64-bit Xubuntu system on x64 architecture hardware, you can compile a Rust project to not only the same architecture target (x64), but also others, including ARM systems. You can read more about cross compilation of Rust projects at [`rust-cross`](https://github.com/japaric/rust-cross). ###### a. List supported targets By running the following command in Terminal, you can get a list of supported compilation targets: ``` rustc --print target-list | pr -tw100 --columns 3 ``` The ones that may interest you include `arm-unknown-linux-gnueabihf`, `armv7-unknown-linux-gnueabihf` and `aarch64-unknown-linux-gnu`. `hf` stands for hard-float, which makes use of hardware for faster computation. Arch Linux ARM website lists supported [platforms](https://archlinuxarm.org/platforms), where you can find architectures of different flavors of Raspberry Pi. * Pi and Pi Zero are `ARMv6`, corresponding to the `arm-unknown-linux-gnueabihf`target. * Pi 2 is `ARMv7`, requiring `armv7-unknown-linux-gnueabihf`. * Pi 3 is `ARMv8`, supporting both 32 and 64-bit. Based on the installed operating system, it needs either the 32-bit `ARMv7` (`armv7-unknown-linux-gnueabihf`) or the 64-bit `AARCH64` (`aarch64-unknown-linux-gnu`). Great! We now know that we need to compile Substratum Node to the `arm-unknown-linux-gnueabihf` target for Raspberry Pi Zero! ###### b. Skip tests Substratum Node source code contains lots of unit and integration tests, which doesn't work natively on your 64-bit Xubuntu, due to different hardware architectures. We'd better skip those tests during cross compilation. In Terminal, under `~\SubstratumNode` path, run following command to list all the files containing test commands. ``` grep -r "cargo test --release" ``` You will see those commands come in different flavors, in the result output as follows: ``` -- --nocapture _integration -- --nocapture --skip _integration -- --nocapture -- --nocapture _integration -- --nocapture --skip _integration ... ``` You need to replace each line with "cargo build --release". You can either do it manually, file by file, or simply use the following one-line command: ``` grep -rl "cargo test --release" ./ | xargs sed -i "s/cargo test --release.*/cargo build --release/g" ``` You can double check the result: ``` grep -r "cargo test --release" grep -r "cargo build --release" ``` Again, the mighty power of a Linux command! ###### c. Cross compile Node for Raspberry Pi Zero We have learned that Raspberry Pi Zero has `ARMv6` architecture. You may check it by yourself by login to your remote Raspberry Pi Zero, and run `uname -a`. It will show you `armv6l`. In Xubuntu Terminal, do the following preparation: * Install *GNU C cross-compiler for the armhf architecture* ``` sudo apt install gcc-arm-linux-gnueabihf ``` * Install Rust target ``` rustup target add arm-unknown-linux-gnueabihf ``` * Configure compilation target Edit file `~/.cargo/config` to tell Rust compilation what target and linker to use. ``` nano ~/.cargo/config ``` Add the following text: ``` [target.arm-unknown-linux-gnueabihf] linker = "arm-linux-gnueabihf-gcc" [build] target = "arm-unknown-linux-gnueabihf" ``` `Ctrl+O` to save the file, press `ENTER` key to confirm, and `Ctrl+X` to exit the editor. Again, under `~/SubstratumNode` path, start the compilation: ``` ci/all.sh ``` Your compiled SubstratumNode binary for `ARMv6` should appear at path `~/SubstratumNode/node/target/arm-unknown-linux-gnueabihf/release/SubstratumNode` You may use `file` command to confirm it's for 32-bit ARM. ``` file ~/SubstratumNode/node/target/arm-unknown-linux-gnueabihf/release/SubstratumNode ``` **[Important]** Please see part **e** for troubleshooting if you encounter any issue. ###### d. (Optional) Cross compile for other systems You can keep the cross compilation carnival going on. * For `ARMv7` (Raspberry Pi 2, or Raspberry Pi 3 bearing a 32-bit operating system, or 32-bit Android Tablet/Phone) You use the same *GNU C cross-compiler for the armhf architecture*, but need to add a new Rust target: ``` rustup target add armv7-unknown-linux-gnueabihf ``` Edit the `~/cargo/config` file to the following: ``` [target.armv7-unknown-linux-gnueabihf] linker = "arm-linux-gnueabihf-gcc" [build] target = "armv7-unknown-linux-gnueabihf" ``` And run the compilation. ``` ci/all.sh ``` * For `AARCH64` (Raspberry Pi 3 bearing a 64-bit operating system, or new 64-bit Android Tablet/Phone) Install *GNU C cross-compiler for the arm64 architecture* ``` sudo apt install gcc-aarch64-linux-gnu ``` Install Rust target ``` rustup target add aarch64-unknown-linux-gnu ``` Edit the `~/cargo/config` file to the following: ``` [target.aarch64-unknown-linux-gnu] linker = "aarch64-linux-gnu-gcc" [build] target = "aarch64-unknown-linux-gnu" ``` And run the compilation. ``` ci/all.sh ``` From one single system (64-bit Xubuntu), you've compiled Substratum Node to multiple ARM-based systems. That's what we call **AWESOME**. ###### e. **[Important]** Troubleshooting * A. The compiled Substratum Node binary doesn't run on Raspberry Pi The cross compilation procedure above uses the toolchain provided by Ubuntu/Xubuntu, which is supposed to work! However, according to my experience, it may fail. The above compilation succeeded weeks ago when I tried it, but suddently stopped working. The compiled Node claimed "segmentation failure" when running on Raspberry Pi Zero. It's possible that some recent update breaking the toolchain. So you may succeed or fail, purely depend on what version of packages you get from Ubuntu's repository at the time. In case the compiled binary doesn't work, please use the following procedure: * First, remove the SubstratumNode directory. ``` sudo rm -r ~/SubstratumNode ``` * Second, repeat what you've done before to get Substratum Node source code ready: Download source code: ``` git clone https://github.com/SubstratumNetwork/SubstratumNode.git ``` Enter directory: ``` cd SubstratumNode ``` Modify `ci/all.sh`, and comment out the lines corresponding to DNS UTILITY & NODE UI by appending `#` at the head of each line. ``` nano ci/all.sh ``` Skip tests: ``` grep -rl "cargo test --release" ./ | xargs sed -i "s/cargo test --release.*/cargo build --release/g" ``` * Third, download Raspberry Pi toolchain to $HOME ``` cd ~ git clone https://github.com/raspberrypi/tools ``` * Fourth, make Raspberry Pi toolchain available for the following cross compilation instance ``` export PATH="$(pwd)/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin:${PATH}" ``` * Fifth, make sure you have `~/.cargo/config` modified, and Rust arm target installed, as previously described * Sixth, compile ``` cd ~/SubstratumNode ci/all.sh ``` * B. Some compilation error related to `sccache` Modify `ci/all.sh`, and comment out the lines corresponding to sccache by appending `#` at the head of each line. ``` nano ci/all.sh ``` The result should look like the following: ``` # Remove these two lines to slow down the build #cargo install sccache || echo "Skipping sccache installation" # Should do significant work only once #export RUSTC_WRAPPER=sccache ``` ##### 7. Run Substratum Node on Raspberry Pi Zero W ###### a. Transfer Substratum Node binary from Xubuntu to Raspberry Pi Zero W Use `scp` command to send cross compiled Node binary to user `alarm`'s `$HOME` path on Raspberry Pi Zero W. Run the following command in Xubuntu Terminal by replacing `x.x.x.x` with the actual IP address of Pi Zero W. ``` scp ~/SubstratumNode/node/target/arm-unknown-linux-gnueabihf/release/SubstratumNode alarm@x.x.x.x:~ ``` ###### b. Log into Raspberry Pi Zero Use the actual IP address of Pi Zero W. ``` ssh alarm@x.x.x.x ``` You may check if the Node file exists: ``` ls ``` ###### c. Install a browser for testing We will use `lynx`browser that runs in terminal for testing, as we did in the previous guide. ``` sudo pacman -S lynx ``` Try browsing the famous httpbin.org ``` lynx https://httpbin.org ``` It works! Press **q** to exit, and **y** to confirm. ###### d. Close port `53` Substratum Node uses port [`53`](https://github.com/SubstratumNetwork/SubstratumNode/blob/master/node/docs/PORT_53.md), so we need to make sure it's not occupied by others. Use `ss` to list all opened ports. (FYI, the `netstat` command has been deprecated in favor of the faster, more human-readable `ss` command.) ``` ss -lntup ``` You see the port `53` in use? Don't panic! Not an issue in Arch Linux. Run the following command to stop the resolving service. ``` sudo systemctl stop systemd-resolved ``` The `53` port is gone. See it for yourself. ``` ss -lntup ``` ###### e. Set DNS "Serving" and "consuming" features could be set to on/off indivudually prior to Node version `0.3.4`. Node `0.3.4` simplifies the UI into three modes: **"off"**, **"serving"**, and **"consuming"**. When "serving" or "consuming", Node routes network requests from/to neighbors as designed. Note that neighborhood hasn't been fully implemented yet as of version `0.3.4`. When "consuming", Node in addition routes local requests through itself so that you can enjoy "VPN" feature. We will use "consuming" mode to test if Node can route local network traffic through itself. Again, "VPN" feature isn't implemented yet. All the tests we are going to perform have nothing to do with any remote Node. "DNS Utility" component is officially designed to switch the "consuming" mode on/off. On Linux, we have a simpler straightforward way to do so, by directly changing the DNS address to `localhost`. In Arch Linux, you can simply edit `resolv.conf` ``` sudo nano /etc/resolv.conf ``` Change the IP address to `127.0.0.1` Basically, the only functional line should be `nameserver 127.0.0.1` `Ctrl+O` save, `ENTER` confirm, and `Ctrl+X` exit. ###### f. Run and Test Node Open up two Terminal windows on Xubuntu, both remotely logged into Raspberry Pi Zero. We use one to run Substratum Node (Terminal 1), and the other one for testing (Terminal 2). * With the Node off, run `lynx` and `ss` in Terminal 2. ``` ss -lntup ``` Take a look at the opened ports ``` lynx https://httpbin.org ``` lynx cannot get to the webpage without Node * Turn on Node, and do tests Run Node on Terminal 1 by the following command. You can use any DNS server address for testing. ``` sudo ./SubstratumNode --dns_servers 1.1.1.1 ``` Awesome, node is up and running. Every time you run, Node generates a new public address. That's for clandestine routing in future. Now in Terminal 2, run `lynx` and `ss` again for testing. ``` ss -lntup ``` Yes, Node opened up several ports. ``` lynx https://httpbin.org ``` Yes, lynx can view webpage now. Request is routed through Node. Congratulations, you have a Substratum Node running smoothly on your $5 Raspberry Pi Zero W! * Turn off Node You can kill Node by `Ctrl+C` in Terminal 1 where Node is running in. To set DNS back to normal, you can simply turn the resolving service back on: ``` sudo systemctl start systemd-resolved ``` You can see default DNS is back in `/etc/resolv.conf` ``` cat /etc/resolv.conf ``` ##### 8. Install a mini OLED screen on Raspberry Pi Zero W So far, we've been controlling Node on Raspberry Pi Zero in a headless way, without any locally installed screen. It would be cool to have a tiny screen attached to display Node status. In the following sections, I will show you how to install an [**Adafruit® 128x64 OLED Bonnet for Raspberry Pi**](https://www.adafruit.com/product/3531) to achieve this. What's more exciting? You will be able to use *physical buttons* to control Node! In this section, we will get the OLED screen installed on and recognized by Raspberry Pi Zero. You may refer to the [official guide](https://learn.adafruit.com/adafruit-128x64-oled-bonnet-for-raspberry-pi/usage) for this screen, as well as the [I/O setup for Pi on Arch Linux ARM](https://archlinuxarm.org/platforms/armv6/raspberry-pi) (you need to click "Wiki" tab on the page). Here are the specific steps for *Arch Linux ARM on Raspberry Pi Zero*. ###### a. Setup I2C I2C (Inter-Integrated-Circuit) is a multi-device bus used to connect low-speed peripherals to computers and embedded systems. This interface is available on Raspberry Pi's [GPIO](https://www.raspberrypi.org/documentation/usage/gpio/) header. To enable the I2C interface, do the following: Install `i2c-tools` and `lm_sensors` packages. ``` sudo pacman -S i2c-tools lm_sensors ``` Configure the bootloader to enable the i2c hardware, by editing file `/boot/config.txt`: ``` sudo nano /boot/config.txt ``` Append the following line to the end of the file: ``` dtparam=i2c_arm=on ``` `Ctrl+O` save, `ENTER` confirm, and `Ctrl+X` exit. Configure the `i2c-dev` and `i2c-bcm2708` to be loaded at boot in `/etc/modules-load.d/raspberrypi.conf`: ``` sudo nano /etc/modules-load.d/raspberrypi.conf ``` Append the following lines to the end of the file: ``` i2c-dev i2c-bcm2708 ``` `Ctrl+O` save, `ENTER` confirm, and `Ctrl+X` exit. ###### b. Physically install the screen to Pi Shut down the Raspberry Pi Zero ``` sudo shutdown -h now ``` Disconnect the power cord. Physically connect the OLED screen to Raspberry Pi Zero W. ###### c. Continue I2C setup Reconnect the power cord to power on Pi Zero. Log back in to Pi Zero via Xubuntu Terminal: ``` ssh alarm@x.x.x.x ``` Issue the following command to get the hardware address: ``` sudo i2cdetect -y 1 ``` You should see `3c`. That's the default hardware address of this OLED screen. In case it's not `3c`, use the actual address found. To instantiate the device, use hardware address found in the previous step with '0x' as prefix (**`0x3c`** for this screen) and choose a device name (I'm calling it *OLED_128x64* here). Note you need root status here for the operation. ``` su echo OLED_128x64 0x3c >/sys/class/i2c-adapter/i2c-1/new_device exit ``` Check dmesg for a new entry: ``` dmesg ``` It shows a message `i2c i2c-1: new_device: Instantiated device OLED_128x64 at 0x3c`. Success! ###### d. Setup GPIO To use Python programming language to control the [GPIO](https://www.raspberrypi.org/documentation/usage/gpio/) on Raspberry Pi, you need to install Python and the RPi.GPIO library. Packages installed here include the programming language `python`, Python's library manager `python-pip`, `base-devel` for compilation, and `git` for downloading git repositories. ``` sudo pacman -S base-devel git python python-pip ``` When asked `Enter a selection (default=all):`, simply press ENTER key to select the default. The RPi.GPIO library is installed via `pip` instead of `pacman`. ``` sudo pip install rpi.gpio ``` ###### e. Install libraries for the OLED screen You also need to install a specific library for the `SSD1306` chip controlling the OLED display. ``` git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git cd Adafruit_Python_SSD1306 sudo python setup.py install ``` (BTW, now you have seen three different methods of installing Python library packages: `pacman`, `pip` and `setup.py` ) ###### f. Light the screen up You can now run several demos for this screen, existing at `~/Adafruit_Python_SSD1306/examples`: ``` cd ~/Adafruit_Python_SSD1306/examples ls ``` These demos require an additional Python image library `python-pillow` ``` sudo pacman -S python-pillow ``` Pick any demo, `animate.py` for example, and run in Python under path `~/Adafruit_Python_SSD1306/examples` ``` sudo python ./animate.py ``` Awesome animation, right? To stop, use key combination `Ctrl+C`. Then you can try another demo. These official demos from Adafruit are not optimized for our specific setup, so you may see some bugs. If you know how to program in Python, you can easily modify them. You can learn more about Python at [official tutorial](https://docs.python.org/3.6/tutorial), [learnpython](https://www.learnpython.org) and other resources. You may also read useful comments in demo files to make use of your OLED screen. ##### 9. Create a user interface on OLED screen for Node ###### a. Write a Python script To save time, I've created a script for you, otherwise you will have to spend time in learning Python, libraries and more to be able to do this. Download the script and related files from my [GitHub repository](https://github.com/humicro) via `git`, and copy the needed files in home path. ``` cd ~ git clone https://github.com/humicro/sub_node_pi_oled_ui.git cp sub_node_pi_oled_ui/node.py ./ cp sub_node_pi_oled_ui/sub_logo_128_64.ppm ./ rm -r sub_node_pi_oled_ui ``` ###### b. Download a font I use a pixel font called **PixelMix** in my script, `8 px` in size. Due to licence matter, you have to download it from [https://www.dafont.com/pixelmix.font](https://www.dafont.com/pixelmix.font) by yourself for **personal use**. You can download via a browser in Xubuntu. Once downloaded, extract out the font file `pixelmix.ttf` from the downloaded `pixelmix.zip`. Still in Xubuntu, place the file in home folder, and use `scp` to send the font file to Raspberry Pi Zero. ``` scp ~/pixelmix.ttf alarm@x.x.x.x:~ ``` You can actually find lots of pixel fonts at [dafont](https://www.dafont.com/bitmap.php). You can download and display these fonts on OLED screen with simple modification of the script. (If you really love those fonts or would like to use for commercial, please donate or purchase to support the font authors.) ###### c. Install `freetype2` To be able to handle the font, you need to install `freetype2` in Arch Linux ARM system ``` sudo pacman -S freetype2 ``` ###### d. Run Now you can simply run the script to start the OLED interface of Substratum Node. You need to run it with `sudo`. ``` sudo python node.py ``` ##### 10. Auto-start Substratum Node on boot ###### a. Requirements for `node.py`: * Make sure each file path inside `node.py` is absolute path (instead of relative path), because it will be run by root instead of the regular user `alarm`. * Set `node.py` as executable ``` chmod +x node.py ``` ###### b. Setup a system service Create a `node.service` inside `/etc/systemd/system/` ``` sudo nano /etc/systemd/system/node.service ``` Add the following text ``` [Unit] Description=Substratum Node Service [Service] ExecStart=/home/alarm/node.py Type=simple [Install] WantedBy=multi-user.target ``` `Ctrl+O` save, `ENTER` confirm, and `Ctrl+X` exit. Enable this service so it will be started on boot ``` sudo systemctl enable node.service ``` ###### c. Reboot ``` sudo reboot now ``` If you have done it correctly and you are lucky, you should be able to see Substratum Logo and then Node status on OLED screen upon boot. Use the three buttons to switch between "off", "serving" and "consuming" modes. Now the Pi Zero Node can live by itself. No need for remote control from Xubuntu. Hooray! Enjoy your Pi Zero Node, and a breakfast at Milliways! #### Curriculum 1. [Hitchhiker's Guide to Substratum Node on Raspberry Pi](https://steemit.com/utopian-io/@microoo/hitchhiker-s-guide-to-substratum-node-on-raspberry-pi) 2. [Run Substratum Node on a $5 Raspberry Pi Zero and Enjoy Breakfast at Milliways]() 3. Substratum Node, the Phone and Everything *(Coming soon)* #### Proof of Work Done https://github.com/humicro/sub_node_pi_oled_ui.git #### Credits [Substratum Network](https://substratum.net) [Raspberry Pi](https://www.raspberrypi.org) [Arch Linux ARM](https://archlinuxarm.org) [Xubuntu](https://xubuntu.org/) [Oracle VM VirtualBox](https://www.virtualbox.org) [Adafruit Industries](https://www.adafruit.com) [Python](https://www.python.org) [Bastiaan's original video guide for Substratum](https://www.youtube.com/channel/UCcLXZ4t4vz1FlG7mj3wx5kw/videos) [Rust-Cross](https://github.com/japaric/rust-cross) [PixelMix Font](https://www.dafont.com/pixelmix.font) by Andrew Tyler [*The Restaurant at the End of the Universe*](https://en.wikipedia.org/wiki/The_Restaurant_at_the_End_of_the_Universe) by Douglas Adams #### Dislaimer * This is a fan-made project for educational purpose. The author is not affliated to Substratum, Adafruit, or any mentioned companies. * The guide intentionally avoids providing any unofficially pre-compiled binaries. You will have to double check the source code, and compile them by yourself. It's a fun and safe process. I suggest that you never ever download or run any *unofficial* Substratum Node binary provided by 3rd party! * At the time of writing, Node doesn't have the clandestine routing feature implemented yet, and you cannot make any earnings by running a Node. This guide doesn't enforce any specific treatment of security. Please practice on a safe network. #### License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.