Skip to main content

Software installation

Before you begin​

You can expect the setup process to take 10-15 minutes.

info

Before you get started, you'll need to have the following:

  1. A Raspberry Pi (our list of preferred Raspberry Pis is here)
  2. A blank microSD card, at least 16GB. We like SanDisk and Samsung SD cards for their longevity.
  3. A suitable power cord for the Raspberry Pi. (If you look at the power rating, it should be about 5V and at least 2.25A).
  4. A computer with internet access and ability to read & write to a microSD card.

Setting up your Raspberry Pi​

We'll start your empty microSD card (or we'll reformat the card later if not empty).

  1. Download the Pioreactor leader & worker image file.
info

What is an image file? It's a file that contains all the required software preinstalled on it, including an operating system and our custom Pioreactor software. The image will be installed on the microSD card.

  1. Download the Raspberry Pi Imager for your operating system and install it.

  2. Open the newly-installed Raspberry Pi Imager.

  3. Click Choose OS. Click on Use custom towards the bottom: Click "Choose OS" Select the "Use custom" option Select the downloaded Pioreactor image from step 1.

    Screenshot of the local computer's directory, selecting the downloaded image

  1. Insert your microSD card to your computer. After your microSD card is recognized by your computer, click Choose Storage and select it. Click "Choose storage"

  2. Click the settings menu (Gear button in the bottom right). Settings menu

    1. Check Set hostname. Input a unique name for this Pioreactor. Some names that we use for our first Pioreactor: pioreactor1, or leader, or p1.

    2. Check Enable SSH, and select Use password authentication.

    3. Check Set username and password. Enter the following:

      • username: pioreactor
      • password: raspberry (you can change the password later).

    4. Check Configure wireless LAN and enter your network name into SSID network name, WiFi password, and country.

      note

      Alternative: instead of trying to connect to a difficult-to-access network, like at a university that may not easily allow Raspberry Pi's, there's a built-in solution for creating a local access point).

    5. Change timezone to your local timezone.

Your settings should look like this:

Screenshot of what your settings should look like

  1. Click Save to save and exit the dialog box.

  2. Click Write. Writing will take up to 5 minutes. Perfect time for a tea break.

  3. Once writing is complete, remove the microSD card, and place it (exposed copper side up) into the Raspberry Pi. Your Raspberry Pi's power should be unplugged before inserting the microSD card. The microSD slot is located on the PWM side of the Pioreactor, in the gap between the Raspberry Pi and the bottom faceplate. Reference the picture for the orientation.

    Insert the microSD card

  4. Plug power into your Raspberry Pi. LEDs onboard the Raspberry Pi may start to light up. After about three minutes, your Pioreactor HAT will briefly blink a blue LED for 2 seconds, telling us it is ready.

info

Waited, but didn't see a blue LED blink, or maybe you missed it? Try pressing on the onboard button, near the side labelled "PWM", and pictured above. If this lights up the blue LED, you're good to move on. Still not working? Try power-cycling the Raspberry Pi, or email us at hello@pioreactor.com.

  1. After observing the blue LED flashing, navigate to http://pioreactor.local in a web browser to visit the web interface. (Not working? Read Troubleshooting below).
  2. The Pioreactor is now ready for use! Follow this guide to set up your first experiment.

Adding additional workers to your cluster​

Workers are additional Pioreactors that you can control from a single UI. Together, a leader and workers form a Pioreactor cluster.

Step 1. Install the worker software​

  1. Follow the same instructions above, but use a Pioreactor Worker image instead.
note

Choose a hostname that isn't currently being used in your cluster, ex: worker1, worker2, etc.

  1. After the image is written to the microSD card, place the microSD card into the Raspberry Pi and power it on. The Pioreactor's blue LED won't blink, as it's not 100% ready yet.

  2. After a few minutes, connect the new Pioreactor worker to your cluster using the UI. See next steps.

Step 2. Add worker to cluster using the UI​

On the Pioreactors page in the web interface, click the "Add new Pioreactor" button in the top right:

Add new pioreactor

Provide the chosen hostname of the new worker Pioreactor:

Add new pioreactor modal

After a minute, the new Pioreactor should appear on the Pioreactors and Experiment Overview page. Refresh the page if it does not show up. Your new Pioreactor will also blink it's blue LED.

From the command line (Alternative)​

On the leader's command line, the command pio add-pioreactor <new name> will connect the new Pioreactor to the cluster.

tip

We recommend running a self-test on all Pioreactors after your initial setup to detect any hardware bugs at this point.

Troubleshooting​

My Pioreactor keeps flashing the blue LED​

On a successful start, the Pioreactor will flash its blue LED for about 4 seconds. If you observe the blue LED flashing for longer, something may be wrong. You can diagnose the problem by counting the number of flashes observed.

My RPi won't connect to my WiFi.​

  • If you are on a restrictive WiFi network (like at a university), and wish to avoid the network, creating a local access point may be a better option.
  • Some Raspberry Pis can't connect to Wifi natively, and some Raspberry Pis can only connect to 2.4GHz connections. See table below: Rpi and wifi
  • You may have mis-typed your WiFi credentials. To fix this, you'll need to restart the image installation from the Raspberry Pi Imager.
  • If connecting to a 5GHz WiFi connection, you need to supply a valid country code. See the list here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2/
  • Check out some other possibilities here.

I want to change the Pioreactor name on installation of leader​

Easiest solution is to start over: reflashing the OS onto the microSD card will remove all previous data, and you can try again.

pioreactor.local in a web browser is not showing up​

  • In your browser's address bar, add the http:// infront of the url, like so: http://pioreactor.local.
  • The UI is hosted on http, not https. Check if you are accessing http ://pioreactor.local, and not https ://pioreactor.local.
  • Try accessing using the url http://<the permanent name of your Pioreactor aka hostname>.local
  • If you know your Raspberry Pi's IP, try http://<IP address of your Raspberry Pi>
  • When pressing the button on the HAT, does the blue LED show up? If not, installation may have failed. Try installing the image again, and double check the settings.
  • In your Raspberry Pi Imager settings, confirm that you clicked "Set username and password", and used the username pioreactor. If not, try reinstalling the image.
  • Are you on an older Windows machine? You may need to install a DNS service, but also see workarounds here.