├── en ├── images │ ├── .keep │ ├── banner.png │ ├── octapi.png │ ├── terminal.png │ ├── click-wifi.png │ ├── enable-ssh.png │ ├── enable-ssh1.png │ ├── router-dhcp.png │ ├── router-ssid.png │ ├── octapi-system.png │ ├── router-lan-ip.png │ ├── set-dhcp-range.png │ ├── type-password.png │ ├── connect-to-wifi.png │ ├── octapi-screenshot.png │ ├── router-screenshot.png │ └── Build-An-OctaPi-TILE.png ├── resources │ └── .keep ├── step_9.md ├── meta.yml ├── step_2.md ├── step_6.md ├── step_10.md ├── step_1.md ├── step_7.md ├── step_4.md ├── step_8.md ├── step_11.md ├── step_3.md ├── step_5.md └── step_12.md ├── .gitignore ├── .editorconfig ├── README.md ├── LICENCE.md └── CONTRIBUTING.md /en/images/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /en/resources/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /en/images/banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/banner.png -------------------------------------------------------------------------------- /en/images/octapi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/octapi.png -------------------------------------------------------------------------------- /en/images/terminal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/terminal.png -------------------------------------------------------------------------------- /en/images/click-wifi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/click-wifi.png -------------------------------------------------------------------------------- /en/images/enable-ssh.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/enable-ssh.png -------------------------------------------------------------------------------- /en/images/enable-ssh1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/enable-ssh1.png -------------------------------------------------------------------------------- /en/images/router-dhcp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/router-dhcp.png -------------------------------------------------------------------------------- /en/images/router-ssid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/router-ssid.png -------------------------------------------------------------------------------- /en/images/octapi-system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/octapi-system.png -------------------------------------------------------------------------------- /en/images/router-lan-ip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/router-lan-ip.png -------------------------------------------------------------------------------- /en/images/set-dhcp-range.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/set-dhcp-range.png -------------------------------------------------------------------------------- /en/images/type-password.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/type-password.png -------------------------------------------------------------------------------- /en/images/connect-to-wifi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/connect-to-wifi.png -------------------------------------------------------------------------------- /en/images/octapi-screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/octapi-screenshot.png -------------------------------------------------------------------------------- /en/images/router-screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/router-screenshot.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # ignore files generated by https://github.com/CodeClub/slash-learning-content-preview 2 | */preview-*.html 3 | .DS_Store 4 | -------------------------------------------------------------------------------- /en/images/Build-An-OctaPi-TILE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/build-an-octapi/HEAD/en/images/Build-An-OctaPi-TILE.png -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 2 6 | end_of_line = lf 7 | charset = utf-8 8 | trim_trailing_whitespace = true 9 | insert_final_newline = true 10 | 11 | [*.md] 12 | trim_trailing_whitespace = false 13 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Build an OctaPi 2 | 3 | ![Build an OctaPi](/en/images/banner.png) 4 | 5 | Find the project online at [projects.raspberrypi.org/en/projects/build-an-octapi](https://projects.raspberrypi.org/en/projects/build-an-octapi) 6 | 7 | ## Contributing 8 | See [CONTRIBUTING.md](CONTRIBUTING.md) 9 | 10 | ## Licence 11 | See [LICENCE.md](LICENCE.md) 12 | -------------------------------------------------------------------------------- /LICENCE.md: -------------------------------------------------------------------------------- 1 | # Licence 2 | 3 | Build an OctaPi by [GCHQ](https://www.gchq.gov.uk/) and the Raspberry Pi Foundation is licensed under a Creative Commons Attribution 4.0 International Licence. 4 | Based on a work at https://github.com/raspberrypilearning/build-an-octapi 5 | 6 | **Code and scripts** 7 | Copyright: [Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) 8 | License: [Apache 2](https://www.apache.org/licenses/LICENSE-2.0) 9 | -------------------------------------------------------------------------------- /en/step_9.md: -------------------------------------------------------------------------------- 1 | ## OctaPi physical set-up 2 | 3 | - Decide how you will power your OctaPi. You could simply power each of the eight Raspberry Pi computers separately using eight standard power supplies, or you may find it more convenient to use a USB hub or charger in order to power them centrally. 4 | 5 | **Note:** It is essential that there is sufficient power to provide 2.4A to each Raspberry Pi 3. Not all USB hubs/chargers can power 2.4A on every port, so make sure to check this carefully. 6 | 7 | - If you are using the Unicorn HATs, install a HAT onto the GPIO connector of each of the servers. 8 | 9 | - If you wish, you can mount the eight Raspberry Pi 3s onto a backboard. Alternatively, there are cases for multiple Raspberry Pis available for purchase, or you can simply leave them laid out - they will work as a cluster even if they aren't attached to anything. 10 | 11 | ![OctaPi System](images/octapi-system.png) 12 | -------------------------------------------------------------------------------- /en/meta.yml: -------------------------------------------------------------------------------- 1 | --- 2 | title: Build an OctaPi 3 | hero_image: images/banner.png 4 | description: Make a distributed computer system 5 | theme: green 6 | interests: cybersecurity-and-cryptography, big-project 7 | duration: 3 8 | curriculum: 3, design-0, programming-3, phys-comp-1, manufacture-0, community-0 9 | listed: true 10 | ingredient: false 11 | technologies: raspberry-pi, python 12 | hardware: raspberry-pi 13 | software: python 14 | site_areas: projects 15 | version: 4 16 | last_tested: 2017-01-01 17 | steps: 18 | - title: Introduction 19 | - title: What you will need 20 | - title: Set up the wireless router 21 | - title: Set up the OctaPi client 22 | completion: 23 | - engaged 24 | - title: Set up one OctaPi server 25 | - title: Set up the server on the OctaPi network 26 | - title: Set up the client on the OctaPi network 27 | - title: Check that it works 28 | - title: OctaPi physical set-up 29 | - title: Using the completed OctaPi 30 | - title: Controlling the cluster 31 | completion: 32 | - internal 33 | - title: Troubleshooting 34 | completion: 35 | - external 36 | 37 | -------------------------------------------------------------------------------- /en/step_2.md: -------------------------------------------------------------------------------- 1 | ## What you will need 2 | 3 | ### Hardware 4 | 5 | - 9 x Raspberry Pi 3 6 | - 8 x Unicorn HAT (optional) 7 | - 8 x short Micro USB cables 8 | - Wireless router 9 | - [Power hub](https://www.amazon.co.uk/Universal-professional-charging-2-4amps-simultaneously/dp/B01DZKOUS4/ref=lp_11206805031_1_1?srs=11206805031&ie=UTF8&qid=1488288887&sr=8-1){:target="_blank"} 10 | - Ethernet cable 11 | 12 | You need nine Raspberry Pi 3 computers in total, because eight of these will form the OctaPi cluster. Only the final one will need the usual peripherals to act as the client machine. 13 | 14 | You may wish to mount your OctaPi cluster on a perspex board with standoffs as shown in the photographs. 15 | 16 | We do not recommend using a router which is repurposed from a broadband service provider. Whilst using such a router might work, features may be locked down in the router or set to non-default conditions to suit the service provider's requirements. This could affect its use with the OctaPi. 17 | 18 | ### Software 19 | 20 | The OctaPi will make use of the following software packages. Details for how to install them are provided in the resource. 21 | 22 | - Python 3 `dispy` 23 | - Python 3 `nmap` 24 | - Python 3 `psutil` 25 | - Python 3 `unicornhat` 26 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | All contributions are assumed to be licensed under the same licence as the source, i.e. [CC BY-SA](http://creativecommons.org/licenses/by-sa/4.0/). This licence must remain in all derivatives of this work. 4 | 5 | ## Issues 6 | 7 | If you find a mistake, bug or other problem, please [open an issue](https://github.com/raspberrypilearning/build-an-octapi/issues) in this repository. 8 | 9 | ## Pull Requests 10 | 11 | All edits to a resource should be made to the draft branch, or to a fork of the repo. These patches can then be submitted as a pull request. 12 | 13 | If you fix a mistake, bug or problem or have something to contribute, please create a pull request for each modification. Please consider grouping modifications sensibly, i.e. don't bundle typo fixes in the same pull request as code changes, instead file them separately. 14 | 15 | Please note that sometimes things are done for pedagogical reasons so changes which make sense from a software engineering perspective (reducing duplication or making use of more advanced programming language features) may not be suitable to maintain the intended educational value. 16 | 17 | ## Derivatives 18 | 19 | See [LICENCE.md](LICENCE.md) for content licence. The licence must remain in all derivatives of this work. 20 | -------------------------------------------------------------------------------- /en/step_6.md: -------------------------------------------------------------------------------- 1 | ## Set up the server on the OctaPi network 2 | 3 | Still using the **server** Raspberry Pi, we need to switch from the internet-connected network to the OctaPi network. Ensure your OctaPi WiFi router is powered up and fully booted. 4 | 5 | - Click on the WiFi symbol at the top of the desktop and select the 'OctaPi' network 6 | 7 | ![Click on the Wifi symbol](images/click-wifi.png) 8 | 9 | - Enter your router's network password (which you noted down earlier) to join the network. 10 | 11 | ![Enter the password](images/type-password.png) 12 | 13 | Having done this, the server will remember the WiFi credentials and log onto your dedicated 'OctaPi' network each time it boots. 14 | 15 | - We need to remove any previous WiFi information to avoid confusion. 16 | 17 | In a terminal window, type the following command to edit the `wpa_supplicant.conf` file: 18 | 19 | ```bash 20 | sudo nano /etc/wpa_supplicant/wpa_supplicant.conf 21 | ``` 22 | 23 | The file contents look like this 24 | 25 | ```bash 26 | ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev 27 | update_config=1 28 | country=GB 29 | 30 | network={ 31 | ssid="OctaPi" 32 | psk="mynetworkpassword" 33 | key_mgmt=WPA-PSK 34 | } 35 | ``` 36 | 37 | Remove any 'network { }' sections for other networks, press `Ctrl` + `o` to save and `Ctrl` + `x` to exit. 38 | 39 | **Note:** If alternative WiFi networks are not removed, your server may log into the wrong network and not be available to the client. 40 | 41 | - When finished, shut down the server Raspberry Pi. 42 | -------------------------------------------------------------------------------- /en/step_10.md: -------------------------------------------------------------------------------- 1 | ## Using the completed OctaPi for the first time 2 | 3 | - Ensure that the dedicated WiFi router, client, and OctaPi servers are all powered up. It's best to power up the WiFi router well in advance so that you can be sure it is fully booted before the OctaPi client and servers attempt to log into it. 4 | 5 | - On the client machine, open a terminal. 6 | 7 | ![Open a terminal](images/terminal.png) 8 | 9 | - Try running the `compute.py` example software again by typing the following command: 10 | 11 | ```bash 12 | sudo python3 compute.py 13 | ``` 14 | 15 | If the OctaPi is working correctly, at the end of the run all the servers used to execute the job will be listed in the table. The result should look similar to this. 16 | 17 | ```bash 18 | 19 | Node | CPUs | Jobs | Sec/Job | Node Time Sec 20 | ------------------------------------------------------------------------------ 21 | 192.168.1.49 (raspberrypi) | 4 | 4 | 16.040 | 64.160 22 | 192.168.1.202 (raspberrypi) | 4 | 2 | 12.031 | 24.062 23 | 192.168.1.191 (raspberrypi) | 4 | 2 | 13.029 | 26.058 24 | 192.168.1.223 (raspberrypi) | 4 | 0 | 0.000 | 0.000 25 | 192.168.1.116 (raspberrypi) | 4 | 2 | 10.025 | 20.050 26 | 192.168.1.27 (raspberrypi) | 4 | 2 | 15.535 | 31.070 27 | 192.168.1.167 (raspberrypi) | 4 | 4 | 14.537 | 58.148 28 | 192.168.1.50 (raspberrypi) | 4 | 0 | 0.000 | 0.000 29 | 30 | Total job time: 223.548 sec, wall time: 20.245 sec, speedup: 11.042 31 | ``` 32 | 33 | 34 | - Try running the `compute_pi_efficient.py` example software: 35 | 36 | 37 | ```bash 38 | sudo python3 compute_pi_efficient.py 1000 100000 39 | ``` 40 | 41 | If the OctaPi is working properly, you can start to do useful calculations, like this estimation of the value of pi using the 'dartboard' method. 42 | 43 | ![Pi calculation on OctaPi](images/octapi-screenshot.png) 44 | -------------------------------------------------------------------------------- /en/step_1.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | In this resource you will make a distributed computer system using: 4 | 5 | - Eight Raspberry Pi 3 computers acting as **servers** 6 | - Another Raspberry Pi 3 acting as **client** which controls the servers 7 | 8 | ![OctaPi system](images/octapi-system.png) 9 | 10 | ### What you will make 11 | 12 | This system is known as a **cluster computer**, a kind of cloud computer. The power of the eight server CPUs (32 cores) will allow you to execute computations from the client CPU much faster than the client could perform them on its own. Once you complete this project, you will be able to develop applications in Python 3 on the client and run them on your cluster. 13 | 14 | There are three steps you will need to take to make an OctaPi: 15 | 16 | - Create a Wi-Fi network for the cluster using a dedicated router 17 | - Create a client machine 18 | - Create eight servers 19 | 20 | **NOTE:** You don't actually need eight servers, as the cluster will work with any number of servers up to limits determined by the performance of your WiFi router. If you don't have enough Raspberry Pis available to make an OctaPi, why not make a HexaPi (6) or a TetraPi (4)? 21 | 22 | If you want to make your cluster look pretty, you can fit Pimoroni Unicorn HAT 8x8 LED arrays to each server. A bash control script on the client machine can be used to change the patterns on the Unicorn HATs. 23 | 24 | ### What you will learn 25 | 26 | This project covers elements from the following strands of the [Raspberry Pi Digital Making Curriculum](http://rpf.io/curriculum){:target="_blank"}: 27 | 28 | + [Apply higher-order programming techniques to solve real-world problems](https://curriculum.raspberrypi.org/programming/maker/){:target="_blank"} 29 | 30 | + [Create automated systems to solve complex real-world problems](https://curriculum.raspberrypi.org/physical-computing/maker/){:target="_blank"} 31 | 32 | ## Licence 33 | 34 | Build an OctaPi by [GCHQ](https://www.gchq.gov.uk/) and the Raspberry Pi Foundation is licensed under a Creative Commons Attribution 4.0 International Licence. 35 | Based on a work at [https://github.com/raspberrypilearning/rpi-python-build-an-octapi](https://github.com/raspberrypilearning/rpi-python-build-an-octapi) 36 | 37 | **Code and scripts** 38 | Copyright: [Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) 39 | License: [Apache 2](https://www.apache.org/licenses/LICENSE-2.0) 40 | -------------------------------------------------------------------------------- /en/step_7.md: -------------------------------------------------------------------------------- 1 | ## Set up the client on the OctaPi network 2 | 3 | - Connect a monitor, keyboard, and mouse and power up a Raspberry Pi containing the **client** SD card you created earlier. 4 | 5 | - Repeat the instructions from the previous step on this computer, logging into the 'OctaPi' network and removing any alternative WiFi details from `wpa_supplicant` file. 6 | 7 | - Keeping the client switched on, boot up a single **server** Raspberry Pi with only a power lead connected. 8 | 9 | - Open a terminal window on the **client** Raspberry Pi. 10 | 11 | - Type the following command to find the IP address of the **client** Raspberry Pi: 12 | 13 | ```bash 14 | hostname -I 15 | ``` 16 | 17 | - Type the following command to find out the IP address of the **server** Raspberry Pi: 18 | 19 | ```bash 20 | nmap -sP 192.168.1.* 21 | ``` 22 | 23 | Make a note of the **server** IP address (you should see the router's address, which will be `192.168.1.1`, and the client's address listed, too). 24 | 25 | **Note:** The `nmap` software scans the network to find the IP addresses of the devices connected to it. We need to do this on our local network so that the client machine can communicate with the Raspberry Pi computers which form the OctaPi cluster. **Do not run nmap on a network that is connected to the internet.** `nmap` is a powerful piece of software and using it to scan a network you do not own may be considered hacking, and in some countries may even be illegal. 26 | 27 | - On the **client**, run `ssh-keygen` in the terminal to create a key for authenticating the client with the server. 28 | 29 | ```bash 30 | ssh-keygen 31 | ``` 32 | 33 | Press **Enter** when asked where to save the key, and press **Enter** again twice when asked for a passphrase, leaving it empty. 34 | 35 | This key is used to help the `cluster_action.sh` script (provided with the client software) to run with the servers. 36 | 37 | - Find where you noted down the IP address of the server machine, and run this command in a terminal on the **client** to copy the key to the server (replace `` with the **server's** IP address): 38 | 39 | ```bash 40 | ssh-copy-id -i ~/.ssh/id_rsa.pub 41 | ``` 42 | 43 | You will be asked if you want to continue connecting. Type `yes` and press **Enter**. You will be asked for the server Pi's password which will be the default password of `raspberry`. 44 | 45 | This completes preparation of the client and server. We now need to check everything is correct and working properly with a single server. 46 | -------------------------------------------------------------------------------- /en/step_4.md: -------------------------------------------------------------------------------- 1 | ## Set up the OctaPi client 2 | 3 | One of the Raspberry Pi computers will be used as the **client machine** giving access to the servers in the OctaPi cluster. You will need to connect the usual peripherals (monitor, keyboard, mouse) to this Raspberry Pi in order to use it to control the OctaPi. 4 | 5 | - On your micro SD card, install the latest version of Raspbian by following the [software guide instructions](https://www.raspberrypi.org/learning/software-guide/quickstart/){:target="_blank"}. 6 | 7 | - Using this micro SD card, boot up the Raspberry Pi 3 with a keyboard, screen, and mouse connected. 8 | 9 | - Ensure the Raspberry Pi is also connected to the internet. 10 | 11 | - Open a terminal window. 12 | 13 | ![Open a terminal](images/terminal.png) 14 | 15 | - Install `dispy` by typing this command into the terminal: 16 | 17 | ```bash 18 | sudo pip3 install dispy 19 | ``` 20 | 21 | Dispy is a distributed Python implementation that will allow you to write code on the client and run it across the servers. 22 | 23 | Further information is available from [dispy: Distributed and Parallel Computing with/for Python](http://dispy.sourceforge.net/index.html){:target="_blank"}. 24 | 25 | - Install `nmap` by typing this command into the terminal: 26 | 27 | ```bash 28 | sudo apt-get install nmap 29 | ``` 30 | 31 | Nmap is used to discover the IP addresses of the Raspberry Pi servers forming the OctaPi cluster, so that they can be shut down or rebooted as needed. 32 | 33 | - If you are using the optional Unicorn HATs, install the software for them by typing this command into the terminal: 34 | 35 | ```bash 36 | curl https://get.pimoroni.com/unicornhat | bash 37 | ``` 38 | 39 | You will need to reboot your Pi after installing this. 40 | 41 | - Make sure you are in the `/home/pi` directory, then download the OctaPi client software by typing this command into the terminal: 42 | 43 | ```bash 44 | git clone https://github.com/raspberrypilearning/octapi-setup.git 45 | ``` 46 | The client software contains source code examples in Python 3 and a bash control script for rebooting and shutting down the cluster. The control script can be used with the Unicorn HAT as well. 47 | 48 | - Move all of the files from the `client` folder you just downloaded into the `/home/username` folder. Don't forget to use your actual username: 49 | 50 | ```bash 51 | mv /home/pi/octapi-setup/client/* /home/username 52 | ``` 53 | 54 | - Shut down your new OctaPi client for the time being and set aside the client SD card in a safe place. 55 | -------------------------------------------------------------------------------- /en/step_8.md: -------------------------------------------------------------------------------- 1 | ## Check that it works 2 | 3 | - Make sure your dedicated 'OctaPi' router is powered on and fully booted up, the **client** is booted with peripherals attached, and the **server** is booted with only a power lead attached. 4 | 5 | - Open a terminal on the **client**. 6 | 7 | ![Terminal](images/terminal.png) 8 | 9 | - Make sure you are in the `/home/pi` directory and type the following command to run the `compute.py` example software provided with the client software examples you downloaded earlier: 10 | 11 | ```bash 12 | sudo python3 compute.py 13 | ``` 14 | The `compute.py` Python script runs 15 jobs on your server. They are all just random delays before returning. If the OctaPi is working correctly, the jobs will complete in about a minute and a table showing the statistics for the application will be shown in the terminal. You should see a result similar to this: 15 | 16 | ```bash 17 | Node | CPUs | Jobs | Sec/Job | Node Time Sec | Sent | Rcvd 18 | --------------------------------------------------------------------------------- 19 | raspberrypi | 4 | 16 | 13.2 | 211.5 | 2.8 K | 3.9 K 20 | 21 | Total job time: 211.545 sec, wall time: 59.484 sec, speedup: 3.556 22 | ``` 23 | 24 | 25 | If the `compute.py` script does not work, review your steps one by one and check that client, server, and router are all set up correctly and working properly. 26 | 27 | - If the test worked, use the client to manually shut down the server (replacing `` with the IP address of the server you noted down earlier): 28 | 29 | ```bash 30 | ssh 31 | sudo shutdown -HP now 32 | ``` 33 | 34 | You may need to use `nmap` again to find the server IP address if it changed when the WiFi router rebooted. 35 | 36 | In future we will be using the `cluster_action.sh` script to do this. 37 | 38 | - Once the server is shut down, remove its micro SD card. 39 | 40 | - Using an SD card duplicator or a computer which is able to read SD cards, create seven more identical copies of this SD card and insert them into the other servers so that you have a total of eight. 41 | 42 | **Note:** It is also possible (but time-consuming) to create your eight SD cards by following the server setup instructions eight times. If you choose to use this method instead, you must run the `ssh-copy-id` command on the client once per server to copy the key across to each server separately. **DO NOT** use the `ssh-keygen` command to regenerate the key. Refer back to the client setup instructions for how to copy the key from the client to the server. 43 | -------------------------------------------------------------------------------- /en/step_11.md: -------------------------------------------------------------------------------- 1 | ## Controlling the cluster 2 | 3 | Now that you have checked your OctaPi is set up and running correctly, you can use the `cluster_action.sh` script to control it. 4 | 5 | The `cluster_action.sh` script runs on the client and uses SSH to administer the servers (that's why we used `ssh-keygen` to authenticate the client with the servers). It relies on the correct IP addresses of the servers being listed in the `ip_list` file. It is a good idea to delete the `ip_list` file when booting the cluster for the **first time** so that the list is regenerated. 6 | 7 | - From a terminal, type the following command to remove the `ip_list` file: 8 | 9 | ```bash 10 | rm ip_list 11 | ``` 12 | 13 | ### Setting up the cluster_action script 14 | - On the client machine, open a terminal. 15 | 16 | - Make sure you are in the `/home/pi` directory by typing in `cd /home/pi`. 17 | 18 | - Set the permissions for the cluster action script so that you can run it by typing this command: 19 | 20 | ```bash 21 | chmod u+x ./cluster_action.sh 22 | ``` 23 | 24 | ### Ensure the client can recognise each server SSH key 25 | The first time you use the cluster, you may need to connect to each server via SSH with the client so that it recognises each server's SSH key properly (be sure to replace `` with the actual server IP address). 26 | 27 | ```bash 28 | ssh 29 | ``` 30 | 31 | If at all, doing this will only be needed once. 32 | 33 | ### Options for the cluster_action script 34 | 35 | The following parameters are accepted by the script: 36 | 37 | `reboot` – reboots all the servers (the client and router are ignored) 38 | 39 | Example: 40 | 41 | ```bash 42 | ./cluster_action.sh reboot 43 | ``` 44 | 45 | `shutdown` – shuts down each server and places it into a safe state. If a server is not shut down correctly, it may cause the micro SD card to be corrupted and lead to the processor failing to boot when next used. 46 | 47 | Example: 48 | 49 | ```bash 50 | ./cluster_action.sh shutdown 51 | ``` 52 | 53 | `date` – distributes the client date and time (to the nearest minute) to each server. The Raspberry Pi 3 does not have a real-time clock, so the correct time will need to be set on the client first. 54 | 55 | Example: 56 | 57 | ```bash 58 | sudo date -s "11 Apr 2017 12:42" 59 | ./cluster_action.sh date 60 | ``` 61 | 62 | `unicorn` – invokes the `start_unicorn.sh` script on each server and passes it the name and location of a Pimoroni Python script as a parameter. For this to work you need to have `start_unicorn.sh` in `/home/pi` on each server as described earlier. 63 | 64 | Example: 65 | 66 | ```bash 67 | ./cluster_action.sh unicorn /home/pi/Pimoroni/unicornhat/examples/random_sparkles.py 68 | ``` 69 | -------------------------------------------------------------------------------- /en/step_3.md: -------------------------------------------------------------------------------- 1 | ## Set up the wireless router 2 | 3 | The processors in your OctaPi cluster will communicate via a dedicated local WiFi network established by a wireless router. The router does **not** need to be connected to the internet for operation of the cluster, nor does it need to be online for set-up. 4 | 5 | We will assume you are using a brand-new router or have reset your router to its default settings. 6 | 7 | - Power on your wireless router. 8 | 9 | - Connect a computer to the router using an Ethernet cable. You can use any computer system that has a web browser, including a working Raspberry Pi 3. 10 | 11 | - Follow the set-up instructions that came with the router. This normally involves opening a web browser and navigating to your router's 'admin' page to start changing the router settings. The 'admin' login credentials will have been provided by your WiFi router manufacturer. 12 | 13 | - Look for a page which allows you to set the WiFi network name (also called SSID) and change it to 'OctaPi'. For example, the page may look like this: 14 | 15 | ![Set the SSID](images/router-ssid.png) 16 | 17 | **Note:** Raspberry Pi 3 computers only work with 2.4 GHz WiFi, so you can either ignore 5GHz settings or disable 5GHz WiFi in your router. 18 | 19 | - Now look for the LAN IP settings, which may be under the 'LAN' settings. Change the IP address of your router to `192.168.1.1` - again, each router's administrator interface will be different, but here is an example of what you might see: 20 | 21 | ![Set the router's IP address](images/router-lan-ip.png) 22 | 23 | You may need to reboot your router and log back in as 'admin' after this step. 24 | 25 | - Set the WiFi network password, which may be under 'Wireless security' or similar. 26 | 27 | **Important:** Make sure you write down the password so that you can use it to log into your dedicated 'OctaPi' network. 28 | 29 | - Look for the DHCP settings. DHCP is a protocol used for issuing IP addresses automatically. The client and servers will use this to determine their IP addresses. The settings for DHCP may be under 'LAN'. Make sure DHCP is enabled and set the DHCP address range to something that provides a useful range of addresses; we chose `192.168.1.2` to `192.168.1.254`. Using this particular range is not critical but using a different one here will mean the IP addresses you see will differ from those shown in this guide. Only change it if you know what you are doing. 30 | 31 | ![Set the DHCP range](images/router-dhcp.png) 32 | 33 | - If there is a setting for the IP lease time, make this number as large as possible. 34 | 35 | The lease time is the length of time before DHCP reallocates IP addresses - you need it to be long to avoid interrupting the connection between the client and servers. 36 | 37 | - Reboot your WiFi router so that all the changes come into effect. 38 | -------------------------------------------------------------------------------- /en/step_5.md: -------------------------------------------------------------------------------- 1 | ## Set up one OctaPi server 2 | 3 | Each of the Raspberry Pi 3 computers in the cluster needs to have its own micro SD card prepared. However, as each card is identical, you can set up just one server, check it's working, and then replicate the SD card for the other servers. 4 | 5 | - On a new micro SD card, install the latest version of Raspbian by following the [software guide instructions](https://www.raspberrypi.org/learning/software-guide/quickstart/){:target="_blank"}. 6 | 7 | - Boot up a Raspberry Pi 3 or 4 using this SD card with a keyboard, screen, and mouse connected. 8 | 9 | - Ensure the Raspberry Pi is connected to the internet. 10 | 11 | - Open a terminal. 12 | 13 | ![Open a terminal](images/terminal.png) 14 | 15 | - As with the client, install `dispy` by typing this command into the terminal: 16 | 17 | ```bash 18 | sudo pip3 install dispy 19 | ``` 20 | 21 | - Install `psutil` by typing this command into the terminal: 22 | 23 | ```bash 24 | sudo pip3 install psutil 25 | ``` 26 | 27 | `dispy` uses `psutil` for reporting CPU usage of the servers in the cluster. 28 | 29 | - Ensure you are in the `/home/pi` directory by typing `cd /home/pi`. 30 | 31 | - If you are using the Unicorn HATs, install the software for them by typing this command into the terminal: 32 | 33 | ```bash 34 | curl https://get.pimoroni.com/unicornhat | bash 35 | ``` 36 | 37 | You will need to restart your Pi afterwards. 38 | 39 | Then, reopen the terminal and make sure you are in the `/home/pi` folder by typing `cd /home/pi`. 40 | 41 | Download the `start_unicorn.sh` bash script for installation on the server using this command: 42 | 43 | ```bash 44 | wget https://raw.githubusercontent.com/raspberrypilearning/octapi-setup/master/server/start_unicorn.sh 45 | ``` 46 | 47 | Make the script executable by typing this command: 48 | 49 | ```bash 50 | chmod u+x ./start_unicorn.sh 51 | ``` 52 | 53 | - Next you need a script to start a dispynode, running at boot on the server. In your terminal type the following: 54 | 55 | ```bash 56 | nano start_dispynode.sh 57 | ``` 58 | 59 | - When nano starts you can add the following lines of code: 60 | 61 | ```bash 62 | #!/bin/sh -e 63 | sleep 30 64 | _IP=$(hostname -I | awk '{print $1}') 65 | dispynode.py -i $_IP --daemon 66 | ``` 67 | 68 | This script will: 69 | 1. sleep for 30 seconds to allow the server to connect to the network 70 | 2. fetch the server's IP address 71 | 3. start a dispynode daemon that will listen out for instructions from your client. 72 | 73 | - Press `Ctrl` + `o` to save your changes, then `Ctrl` + `x` to exit the nano editor. 74 | 75 | - Make the script executable. 76 | 77 | ```bash 78 | chmod +x start_dispynode.sh 79 | ``` 80 | 81 | Now you need this script to start when the server boots. To do this you can use `crontab` 82 | 83 | - In a terminal type: 84 | 85 | ```bash 86 | crontab -e 87 | ``` 88 | 89 | - Scroll to the bottom of the file and then add the following line. Don't forget to change `username` to the username you are using. 90 | ```bash 91 | @reboot sudo /home/username/start_dispynode.sh 92 | ``` 93 | 94 | - Check that remote login via SSH is enabled so that remote command line access to your server is possible. In the **Preferences** menu, select **Raspberry Pi Configuration**. 95 | 96 | ![Enable SSH](images/enable-ssh1.png) 97 | 98 | Then click on the **Interfaces** tab and make sure that SSH is enabled. 99 | 100 | ![Enable SSH](images/enable-ssh.png) 101 | 102 | -------------------------------------------------------------------------------- /en/step_12.md: -------------------------------------------------------------------------------- 1 | ## Troubleshooting 2 | 3 | ### When I try and run the cluster_action.sh script, I get 'permission denied'. 4 | This file is a bash script and requires execute permission. The error probably occurs because the execute permission is not set for some reason. 5 | 6 | - Make sure you are in the `/home/pi` directory by typing `cd /home/pi` in a terminal window. 7 | 8 | - Type the following command to make the script executable (there is no need to use `sudo`). 9 | 10 | ```bash 11 | chmod u+x cluster_action.sh 12 | ``` 13 | 14 | ### The ip_list file only has the router IP and client IP addresses listed - where are the servers? 15 | If you are seeing unexpected content, or missing content, this is most likely because the client machine is not logged into the OctaPi network when `cluster_action.sh` is run. This can happen if you did not remove other WiFi networks from `/etc/wpa_supplicant/wpa_supplicant.conf`. The client will log into the best available WiFi network, which may not be the OctaPi network. 16 | 17 | - To edit the `wpa_supplicant.conf` file, use nano as follows: 18 | 19 | ```bash 20 | sudo nano /etc/wpa_supplicant/wpa_supplicant.conf 21 | ``` 22 | 23 | - The file contents should look like this: 24 | 25 | ```bash 26 | ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev 27 | update_config=1 28 | country=GB 29 | 30 | network={ 31 | ssid="OctaPi" 32 | psk="itsasecret" 33 | key_mgmt=WPA-PSK 34 | } 35 | ``` 36 | 37 | Remove any 'network { }' sections for other networks, press `Ctrl` + `o` to save your changes and then `Ctrl` + `x` to exit nano. Reboot the client for the changes to take effect. 38 | 39 | ### I get messages saying there is 'no route to host' when using the cluster_action.sh script. 40 | This can happen if the network connection is unreliable and causes the router to drop an IP address. It can also happen if you have more servers connected to your router than it can handle. Network reliability is affected by how close the router is to the rest of the system and by how many other WiFi networks are present. Try moving the OctaPi router to within a couple of metres of the OctaPi system and/or moving away from other WiFi routers. 41 | 42 | ### I get 'host key verification failed' messages when I run the cluster_action.sh script. 43 | This may happen the first time you run the script because the client hasn't seen the server IP addresses before when performing an SSH login. To fix this, do the following. 44 | 45 | - Open a terminal and type in this command to list the IP addresses allocated to your servers: 46 | 47 | ```bash 48 | cat ip_list 49 | ``` 50 | 51 | - Type the following command to find the client's IP address. 52 | ```bash 53 | hostname -I 54 | ``` 55 | 56 | - Ignore '192.168.1.1', as this is the 'OctaPi' router, and ignore the client IP address. From the client machine, log in via SSH to the servers one by one using the other IP addresses listed. When you are prompted, say 'yes' to proceed, then type `exit` again. 57 | 58 | ```bash 59 | ssh 60 | (say 'yes' to continue) 61 | exit 62 | ``` 63 | 64 | `` is one of the server addresses in the `ip_list` file. You will need to type 'yes' in full. Repeat this for all of the servers. 65 | 66 | ### The application I am running freezes after a while. 67 | If something goes wrong on a server, either with the operating system or with the Python code running, it can disrupt operation of the whole cluster. This can happen if the jobs running are quite large or if there is a lot of network traffic. Try rebooting the server cluster with `./cluster_action.sh reboot` before defining smaller jobs in your client code. 68 | 69 | ### The application I am running says 'Ignoring invalid reply for job...' 70 | This can happen if the client and one or more servers have got out of sync, which can be caused by the client code crashing or being interrupted by pressing `Ctrl`+ `c`. It can also happen if one of the servers crashes while in operation. 71 | 72 | To fix this, try to determine which bit of code has the error and fix that first. Then reboot the cluster with the `cluster_action.sh` script. 73 | 74 | ```bash 75 | ./cluster_action reboot 76 | ``` 77 | 78 | The servers should all reboot into the same state and be ready to accept jobs from the client. Depending on the condition of the client following a crash, it may also need rebooting. 79 | 80 | ### When I run my application on the client, I get a message saying a network port is already in use. 81 | This may happen following an error in the client Python code or an exit from the dispy software without closing the cluster. It is caused by a dispy process remaining active on the client (which is capturing the TCP port used for communications with the servers). To correct this problem, reboot the client so that dispy can be cleanly restarted. 82 | 83 | ### How do I debug Python code running on the servers? 84 | The code you are running is defined on the client and distributed to the servers at run time. However, once the code is on the servers, any errors don't get reported back to the client. If there is a bug in the code once it is running on the server, this can cause the whole cluster to fail. To debug, develop all the code on the client for standalone operation and test it thoroughly before adding the `dispy` code to distribute it to the servers. 85 | 86 | ### How do I install new Python modules on the OctaPi servers? 87 | If you have installed new Python modules on the client that are needed for the code distributed to the servers, make sure you have also installed the module on every server before attempting to run your code. The `import` statement needs to be inside the function that you will be distributing. 88 | 89 | ### Will the OctaPi work with a WiFi router that was provided by my broadband service provider? 90 | You need to use a dedicated router to avoid conflicting with other devices. Repurposing a broadband service provider's router can work, but the router might be set to non-default conditions or have locked down features to suit the provider's requirements. This could affect its use with the OctaPi. If you think you may be experiencing networking problems with a repurposed router, try switching to a new WiFi router. We have used a variety of routers, starting at a price around £20, without problems. The router should be able to handle at least nine simultaneous connections if you have a single OctaPi module. The specific router used to test this resource was a TP-LINK TL-WR841N. 91 | 92 | ### I get networking problems with very large clusters (more than one OctaPi module). 93 | Your WiFi router needs to be able to handle large numbers of simultaneous connections. If it is not, you may start to experience dropped connections to the servers ('no route to host'). In extreme cases, the router may even freeze or reboot unexpectedly. Modern routers for domestic use, even high-performance gaming routers, are not designed for large numbers of simultaneous connections. However, we have observed reliable network performance for two OctaPi modules (17 simultaneous connections) with a router in a £20 price range, and for up to four to five OctaPi modules (max. 41 simultaneous connections) with a gaming router. Beyond that, WiFi networking becomes impractical. 94 | --------------------------------------------------------------------------------