This tutorial will teach you how to connect a Raspberry Pi device to Xively using the xiPy Client.
Scan this tutorial to get familiar with it. Then complete each step in a sequential manner. Each step builds upon the previous one.
Be a good sport!
Help us make this tutorial a breeze! If you hit rough spots, please take a moment to contribute by clicking on the link titled SUGGEST EDITS at the top right-hand region of this page. We absolutely suggestions from you!
- Raspberry Pi 3 Model B
Optional: Instead of Raspberry Pi 3 Model B, you can use a Raspberry Pi 2, but it needs extra hardware for Wi-Fi connectivity.
- SD Card 8GB preloaded with NOOBS, a Raspbian operating system installer
You can purchase one or you can create one by following the Raspberry Pi instructions.
- Micro USB 5V power adapter or 2A micro-B USB power supply
- USB keyboard
- USB mouse
- HDMI to HDMI video output cable
- Monitor or TV with HDMI
Raspberry Pi 3 Model B
- Raspbian - the official Raspberry Pi operating system
- python-pip - Python package management
- python-dev - the header files needed to build Python extensions
- xiPy - the official pythonic library for the next-gen Xively platform
Maybe you can take a shortcut?
If you have a Raspberry Pi that is already loaded with Raspbian, connected to hardware (monitor, keyboard, mouse) and a Wi-Fi network, go to Step 3 Install the Python packages.
Place your NOOBS-loaded SD card into the SD card slot on the Raspberry Pi.
Plug your keyboard and mouse into the USB ports on the Raspberry Pi.
Make sure that your monitor or TV is turned on, and that you have selected HDMI as input.
Connect your HDMI cable from your Raspberry Pi to your monitor or TV.
Once you are sure that you have plugged all the cables and SD card in correctly, connect the micro USB power supply.
Your Raspberry Pi is turned on and booted.
- Follow on-screen instructions to connect Wi-Fi and install Raspbian as an operating system.
This may take 20-30 minutes. The following is a short preview of what you should see:
- Connect your Wi-Fi by selecting your network from the top right-hand corner, then entering the Wi-Fi password.
Check your default keyboard layout settings!
The installer may default to a UK Keyboard layout, which you may find out when you try to type certain characters only to get other ones. To change this, click on the Raspbian icon in the top left and select
Mouse and Keyboard Settings. On the
Keyboard tab, click the
Keyboard Layout button to select your appropriate keyboard layout.
This operation will install a Python package installer and the Xively Python library.
- From the Raspberry Pi taskbar at the top of the screen, start the default terminal application,
The following is an example of a terminal:
- Install the Xively Python library to your Pi by entering the following commands:
sudo apt-get install -y python-dev python-pip
pip install --user --pre xiPy
Make sure it installs the library correctly
If you get the following error:
ImportError: No module named 'xiPy'
make sure that it installed the xiPy library correctly.
If you're using Python 3, you'll need to install it using
pip3 install --user --pre xiPy
In some cases, users may need to use
sudo to install the library:
sudo pip install --user --pre xiPy
Make sure your account has at least one group created (
All groups >
+ Add new).
Did you know? Your device lives in two worlds!
In the Internet of Things (IoT), every physical thing has a matching digital representation. Accordingly, Xively keeps data structures that capture the digital life of your physical device. While the physical device (Raspberry Pi hardware) is in your hands, the digital device lives on the Xively infrastructure, ready to provide valuable information about its present, past and, soon enough, its future through predictive analytics.
Before connecting a physical device to Xively, create its digital representation in the system. On your Raspberry Pi's browser, log into the Xively management app to complete the following steps.
It's much easier if you do this step from within the Raspberry Pi's browser so you can easily copy credentials and do not have to manually type anything in!
This device template will represent the Raspberry Pi that we are using for this example.
- Click on
- Click on
Create new device template.
- Enter the template name (for example: "My Raspberry Pi").
This operation will create a channel that the device will communicate over (talk and listen).
- In the Channels section, click on the
- Enter "piMessage" as the channel name.
- Leave the other options as their default and click
This individual device will represent the specific Raspberry Pi that you have physically connected for this example.
- On the device template page, click
Create new device.
- In the pop-up window, do the following:
- Select the device template you have just created (it is selected by default).
- Select "Single" as the mode of creating devices (it is selected by default).
- Enter any serial number (for example: "My Xively Raspberry Pi").
- Associate device with a group (optionally).
You created a device template and a digital device instance inside Xively to represent your physical Raspberry Pi device.
In order for your device to securely talk to Xively, it needs credentials that it will use to authenticate itself as a valid device within your account.
- On the digital device page, click on
- In the pop-up window, click
A file named
MQTTCredentials.txtgets downloaded. It contains the device credentials that will be used in the next step. The file contains two data items:
- The first line is the Xively Device Secret.
- The second line is the Xively Device Id.
Now you have a provisioned digital device on Xively that your physical device (your Raspberry Pi) will connect as.
This step will prepare
xiPy, our physical device's client, to manage communication to and from Xively.
- Go to your digital device page on the Xively management app and click on the
- In the drop-down list labeled
PUBLISH TO, select the
- To copy the topic to clipboard, click on the blue area next to the drop-down list.
The topic format looks as follows:
- Open the file downloaded from Step 4, named
- On a new line, paste the topic you just copied from the
Save As..., navigate to the root directory (
~/) and save it as
- Close the file.
Now you are going to download and run the example python scripts that publish and subscribe to Xively.
Return to your terminal.
Download the sample applications by running the following two commands:
Make the digital device
Messagingtab visible in your Raspberry Pi browser so you can see the messages coming through.
Publish a message from the physical device. From the Raspberry Pi terminal, run the following command:
python xively_pub.py --message 'Hello there, digital device!'
This command executes the example application you downloaded. Using the XiPy Library, the application publishes an encrypted message to the MQTT topic you configured earlier.
The physical device terminal displays the message:
The digital device MQTT tab displays the message:
Go back to the terminal and terminate the previous command by pressing
Subscribe to the MQTT topic. From the Raspberry Pi terminal, run the following command:
This command executes the second example application you downloaded. Using the XiPy Library, the application subscribes to the MQTT topic you configured earlier.
- Publish a message from the digital device. Go to the digital device MQTT tab and send the message
Hey, physical! How are you?.
The physical device terminal displays the message:
YES! You did it! Now you have a Raspberry Pi connected to Xively.