Skip to main content

Software installation

Let's install your Pioreactor's software

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


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, ideally 16GB size or larger.
  3. A suitable power cord for the Raspberry Pi. (If you look at the power rating, it should be about 5V and at least 2A).
  4. A computer with internet access and ability to read & write to a microSD card.

Setting up your Raspberry Pi

We'll start with an unused Raspberry Pi and empty microSD card (or we'll reformat the card later if not empty).

  1. Download the Pioreactor Leader image: this has all the required software preinstalled on it, including the latest version of Raspberry Pi OS and Pioreactor.

  2. Download the Raspberry Pi Imager for your operating system, install it and open the Raspberry Pi Imager.

  3. Click "Choose OS". Click on "Use custom" towards the bottom: Select the "Use custom" option Select the downloaded Pioreactor image from step 1. In the local computer's directory, select the downloaded image

  4. Connect your microSD card to your computer. Once your microSD card connected to your computer, select it under "Choose Storage".

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

    1. Set hostname as the desired name of this Pioreactor. Some names that we use for our first Pioreactor: pioreactor1, or leader, or p1.
    2. Check "Enable SSH".
    3. Add username: pioreactor and password: raspberry (you can change the password later)
    4. Check "Configure wireless LAN" and enter your network name into SSID, wifi password, and country. (Alternative: instead of trying to use a "restrictive" network, like at a university that may not allow Raspberry Pi's, here's a built-in solution for creating a local access point). Note: The Pioreactor cannot connect to a 5G network.
    5. Change timezone to your local timezone.
    6. Click "Save"
  6. Click "Write".

  7. Once writing is complete complete, remove the microSD card, and place it into the Raspberry Pi.

  8. Plug in the power cord into your Raspberry Pi. LEDs onboard the Raspberry Pi should start to light up.

  9. After a few moments, your Pioreactor will briefly flash a blue LED, signifying it is ready. Navigate to http://pioreactor.local in a web browser to visit the web interface. (Not working? See Troubleshooting below).

  10. The Pioreactor is now ready for use! Basic experiment instructions can be found here.

Adding workers to your cluster

From the Raspberry Pi Imager

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.

After you have installed the image, connecting the new Pioreactor to your cluster is simple.

From the web UI

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

Provide the chosen hostname of the new worker Pioreactor:

After a minute, the new Pioreactor should appear on the Pioreactors and Experiment Overview page. Refresh the page if it does not show up.

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.


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:
  • 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

  • The UI is hosted on http, not https. Check if you are accessing http ://pioreactor.local, and not https ://pioreactor.local.
  • Are you on an older Windows machine? You may need to install a DNS service, but also see workarounds here.
  • Try instead http://<the permanent name of your Pioreactor aka hostname>.local
  • Still not working? Try instead http://<IP address of your Raspberry Pi>