The following requires

    1. a Raspberry Pi (our list of preferred Raspberry Pis is here)
    2. a blank microSD card, ideally more than 16GB size. 
    3. a suitable power cord for the Raspberry Pi. (If you look at the rating, it should be 5V and at least 2.5 amps).
    4. a computer with internet access and ability to read & write to a microSD card.

Setting up your Raspberry Pi

If your Raspberry Pi is already functional, you can skip this step and move to Setting up the Pioreactor software on the Raspberry Pi below.

  1. Download the Raspberry Pi Imager for your operating system. 
  2. Hold down the key sequence "ctrl-shift-x" to bring up the settings menu. 
    1. check "Enable SSH" and add a password (we'll need this password in a later step)
    2. check "Configure wifi" and enter your network name into SSID, password, and country.
    3. Optional: change timezone to your local timezone.
    4. Click "Save"
  3. Select the Raspberry Pi OS Lite operating system:

    Click on Raspberry Pi OS (other):

    Then click on Raspberry Pi OS Lite:

  1. Write to your microSD card. Here's a short video on how to do this (note we are using a different OS choice though).
  2. Eject the microSD card, and place it into the Raspberry Pi.
  3. Plug the power cord into your Raspberry Pi in. Both LEDs should start to light up if successfully connected to the Wifi. 

Setting up the Pioreactor software on the Raspberry Pi

If you are looking to add your new Pioreactor to an existing cluster of Pioreactors, see section below. To start a new cluster (even a cluster of a single Pioreactor!), start below:

Initial setup of your cluster

After a few minutes or so, your Raspberry Pi should be successfully connected to your Wifi network.

      1. If using your computer's command line, type ssh pi@raspberrypi.local. When prompted for a password, enter the password you used above (Note: since it is a password, it won't show up when you type characters - that's normal) - or if using PuTTY, enter the following. port: 22, and host name: raspberrypi.local. When prompted, used the credentials user: pi, password: your password.
        💡 If experiencing problems with above, see Troubleshooting below.

        If shown a new command line - congrats! You've successfully logged into your new Raspberry Pi!

      2. You can decide on your Pioreactor cluster - it may be helpful to review the different clusters here. During the installation (next step), you will be prompted to enter a new permanent hostname for the Pioreactor. For this initial Pioreactor (which will default to be the leader), we suggest either leader, pioreactor, or pioreactor1. We also suggest not having spaces, apostrophes, or dashes in your hostname. Note that this new hostname means that instead of raspberrypi.local to connect for SSH/PuTTy, you'll use <your new hostname>.local to connect in the future.

      3. Copy and paste one of the following into your Raspberry Pi's command line, depending on your choice of cluster in step 2:
        • Leader, and is also a worker: use this option if you want to use Pioreactor hardware with this RaspberryPi.

          bash <(wget -qO-
        • Leader only: this option is if you plan to have other RaspberryPi(s) use the Pioreactor hardware.

          bash <(wget -qO-
      4. After installation completes, the Raspberry Pi will close connection and reboot. After a few moments, your Pioreactor will flash a blue LED and now is ready to go. Navigate to http://pioreactor.local in a web browser to visit the PioreactorUI. (Not working? See Troubleshooting below). 

Adding workers to your cluster

From the web UI

After you have an initial Pioreactor, adding new Pioreactors to your cluster is simple. On the Pioreactors page in the PioreactorUI, click the "Add new Pioreactor" button in the top right:

Follow the instructions in the dialog that appears (the first part mimics the instructions above). At the end, choose a permanent name for the new Pioreactor worker. This should be a name that isn't currently in the cluster. Click the Install button to finish the installation.

After a few minutes, the new Pioreactor should appear on the Pioreactors and Experiment Overview page.

From the command line

On the leader, the command pio add-pioreactor <new name> should install the software onto the computer named raspberrypi.local on the network.


My Rpi won't connect to my Wifi.

  • 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
  • If connecting to a 5GHz wifi connection, you need to supply a valid country code. See the list here:
  • is your Wifi hidden? Within the brackets { ... } of the wpa_supplicant.txt file, add a new line scan_ssid=1, so it may look like:
     ssid="<network name>"
  • Check out some other possibilities here.

I accidentally missed the prompt to enter a Pioreactor name on installation of leader (or I want to change it)

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>

What's an appropriate text editor?

From friends at the OctoPrint forum:

Some text editors, including Apple's TextEdit (included with macOS) and WordPad (included with Windows) make changes to the files you edit which render them unusable by the Pi's Raspian operating system. (I've heard that Windows NotePad can also cause problems, but have not personally verified that). There are several good, free options out there you can download with will avoid these problems.

For the Mac, I use Sublime Text 3 (free)

For Windows, one of the more popular choices is NotePad++  (also free)

Note that if the file has already been edited with an inappropriate text editor, your best bet is starting over with a clean, unedited copy of that file. Simply editing it again with the correct editor is unlikely to fix the damage.

← Back to all documentation