Getting Started

Particle Pi Beta

Please read me!

Please note that the Raspberry Pi integration with the Particle Cloud is currently in beta. This means that, while the primary happy paths and use cases are tested, the software may still be a little rough around the edges in some areas.

The good news is that you're about to join a wonderful community of Particle developers who are here to help. If you need support and can't find the answer in our docs, head over to our community forums and chat with the Particle team. Find an issue? Log it in our open-source repository so we can fix it!

Have fun!

Quick install

If you've read this guide before and are just looking for the install command, we'll save you some scrolling:
bash <( curl -sL )

What You'll Need

In order to connect your Raspberry Pi to the Particle Cloud you'll need the following things. Note that these are all included in the Particle Pi Starter Kit with Raspberry Pi v3, which is available for purchase in the Particle Store.

  • Raspberry Pi (Raspberry Pi v2 and v3 preferred)
  • Power supply (5V, 2A+ preferred)
  • Micro SD card and SD adapter
  • Ethernet cable (for wired connections)

If you do not have access to a wired network cable, you will need to connect your Pi to an active Wi-Fi network, which will require the following:

  • Keyboard
  • Mouse
  • Monitor
  • HDMI Cable (to connect the Pi to your monitor)

Download and install Raspbian

Before you boot up your Pi for the first time, you'll need to make sure you have the latest Raspbian image from the Raspberry Pi Foundation. Note that flashing a fresh version of Raspbian Jessie with Pixel (GUI) can take as long as 10-15 minutes.

Do you already have a Pi with Raspbian installed? Click here to skip the download and setup steps and update your existing Raspbian image.

I don't have an SD card with Raspbian

If you don't already have an SD card with Raspbian on it, you'll need to follow these steps:

  1. Make sure your SD card is FAT32 formatted
  2. Install an operating system image on the SD card. We recommend Raspberry Pi's preferred operating system, Raspbian Jessie with Pixel, which you can download here.
  3. Install the operating system onto your SD card by following the Raspberry Pi Foundation's official installation instructions, here.

Note: There are many different tools and resources available on the Internet to make the process of burning a new image for your Raspberry Pi easier. If you have issues with the instructions above from the Raspberry Pi Foundation, has compiled a great list of alternatives for Mac, Windows, and Linux.
- Mac setup options
- Windows setup options
- Linux setup options

4. Insert the SD card into your Raspberry Pi, and apply power using a 5V, 2A+ power supply.

I have an SD card with Raspbian

If you already have a Pi set up, run the following commands from your Raspberry Pi's command line to update your OS to the most recent version of Raspbian:

  1. sudo apt-get update, which will update your local package database with the upstream one.
  2. sudo apt-get upgrade, which will actually upgrade your Raspbian image to the most recent from the Raspberry Pi Foundation.

Note that these steps may take up to 10 minutes to complete, so please have patience.

Connect your Pi to the Internet

There are two primary ways to connect your Raspberry Pi to the web--using a wired connection (Ethernet) or using a wireless connection (Wi-Fi preferred).

Connecting with a wired connection (Ethernet)

If your Raspberry Pi has an Ethernet port, connecting it to the Internet is as simple as plugging in a cable to the on-board RJ-45 jack on your Pi. The operating system should automatically work with your router to obtain an IP address and connect to the web.

You'll also want to add a blank file named ssh (open a text editor and hit Save as: ssh) to the boot drive of the SD card to allow connecting to your Raspberry Pi remotely.

Note: The Pi Zero does not have an on-board Ethernet port, but can be connected with a Ethernet --> USB adapter.

Connecting over Wi-Fi (headless setup)

You can put the Wi-Fi connection information to the SD card before starting the Raspberry Pi if you don't want to connect a monitor and keyboard.

  1. Insert the SD card into your computer.
  2. Open the drive called boot
  3. Add a file named wpa_supplicant.conf with this content:

  4. Add a blank file named ssh (open a text editor and hit Save as: ssh).

  5. Insert the SD card into your Raspberry Pi.

Connecting over Wi-Fi (GUI setup)

  1. Connect a USB keyboard, USB mouse and monitor to your Raspberry Pi.
  2. Click on the icon on the left of the volume symbol to scan for Wi-Fi networks and start the Wi-Fi configuration process.

  3. Enter your network's Wi-Fi password.

  4. When your Pi has successfully connected to the Wi-Fi network, you will see a blue Wi-Fi icon next to the volume icon at the top right hand corner of your screen.

Note that it's also possible to obtain the IP Address of your Raspberry Pi after you've connected it to the Internet. To do so, click on the black terminal icon at the top left hand side of your screen, and type ifconfig wlan0.

Your Pi's IP Address should be displayed next to the label, inet addr and look something like 192.168.X.XXX.

Install Particle Pi software

Now that your Pi is online, it's finally time to download and install the Particle Pi software. If your Pi has a monitor and keyboard connected, you can skip directly to Install the Particle Agent. If would like to install the Particle Pi software without using a monitor and keyboard, please read the following section, Instructions for headless setup.

Instructions for headless setup

Note that if you are using a wired connection without a monitor and keyboard (headless) you will have to SSH (secure shell) into your Pi in order to install the Particle software. If you are using a keyboard and monitor, you can head directly to Install the Particle Agent.

  • The first step is to obtain the IP address for your Raspberry Pi once it is connected to the Internet. You can find instructions for obtaining your Pi's IP address using Raspberry Pi's official tutorial, here.

The easiest method find your Raspberry Pi's IP address and SSH into it is to use its mDNS hostname followed by .local. The default hostname for your Pi is raspberrypi, so on macOS and Linux, you can simply SSH into your Pi by running the following command in your computer's terminal:

ssh pi@raspberrypi.local
  • If you are using Windows, you can download and use PuTTY to SSH into your Pi.

The default password for Raspberry Pi is raspberry. We strongly recommend you change the default password. You can do so by running the following command inside of your Raspberry Pi's terminal:


If your want to change the hostname of your Raspberry Pi to something more meaningful, or if you have multiple Raspberry Pi's on your network, you can do so by running the following command inside of your Pi's terminal:

echo newHostname | sudo tee /etc/hostname
  • You will need to reboot your Pi for the new hostname to be used.

An alternate method for finding the IP address in a headless setup configuration is to ensure that your computer is connected to the same network as your Raspberry Pi device, and to run the following command in your computer's terminal:

arp -a | grep b8:27:eb | grep -Eo '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}'

As it turns out, the Raspberry Pi Foundation has their own range of MAC addresses all to themselves. The command above will scan your network for devices whose MAC address starts with the prefix, b8:27:eb and report their IP address. Assuming you only have one Raspberry Pi connected to the network, you should be able to easily identify your Pi's network address and SSH into it in the next step.

- Once you have your Pi's IP address, you can connect to your Pi through a secure shell (SSH). If you are using macOS or Linux, you can simply create an SSH tunnel using your Terminal application. If you are using Windows, download PuTTY.

- SSH into your Pi using the following command, where 192.168.X.XXX is the IP address of your Pi.
ssh pi@192.168.X.XXX

Install the Particle Agent

You will not be able to complete this step of the process if you have not already received your beta activation email. If that's the case, hang tight--you'll receive your email in the upcoming weeks as we expand access to the Raspberry Pi provisioning endpoint. For more information, visit

To connect your Raspberry pi to the Particle Cloud, you need to install the Particle Agent. The Particle Agent is a software service that runs in the background on the Raspberry Pi and allows you to write and run firmware (software that interacts with the GPIO pins on the Pi).

Install the agent by pasting this command in a terminal on your Raspberry Pi, either while connected remotely through SSH or locally with a keyboard and monitor.

bash <( curl -sL )

The installation process should look like this:

When the installation is over, the Particle Agent setup will ask you to sign in to your Particle account. If you don't have one yet, create a Particle account at

Once the Particle Agent is installed, you will have a number of commands available to you to start firmware, stop firmware, and manage your connection to the Cloud. For a full list of available particle-agent commands, type particle-agent help into your terminal.

particle-agent setup

This is a super useful command! If you find yourself in an unknown or unintended device state at any point in development, you can type this command to reset your device and return it to "factory conditions" running Tinker, our default device firmware. The Pi will remain claimed to your Particle account.

When you have successfully completed setup of your Pi, you will see the following confirmation message:

If you see the message above, congratulations! You've successfully connected your Pi to the Particle Cloud!

Development Resources

Great work so far! In case you ever find yourself in a pickle, here's a list of resources that can help you through the next steps of your journey. Please make a note of them, and remember that you can always send us a note via our Support Portal if you get stuck!

Technical Documentation

Projects and Examples

Forums and Support

Next steps

Connecting your Pi is only the beginning. Check out the other topics in our Getting Started guide for the Raspberry Pi, which will show you how to:

  • Use Tinker, our mobile application, to control your Pi
  • Write and flash code to your Pi with our Web IDE
  • Publish sensor values to the Internet
  • Remotely execute scripts on your Raspberry Pi
  • Leverage your Pi's powerful processor
Tinker and Mobile App >