Raspberry Pi

How to connect a Raspberry Pi to Xively

What you will learn

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 :hearts+: suggestions from you!

Hardware you will need

  • 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

Raspberry Pi 3 Model B

Software you will install during the tutorial

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

Step 1 of 6: Prepare your Raspberry Pi

  1. Place your NOOBS-loaded SD card into the SD card slot on the Raspberry Pi.

  2. Plug your keyboard and mouse into the USB ports on the Raspberry Pi.

  3. Make sure that your monitor or TV is turned on, and that you have selected HDMI as input.

  4. Connect your HDMI cable from your Raspberry Pi to your monitor or TV.

  5. 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.

Step 2 of 6: Install the Raspbian operating system

  1. 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:
  1. 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 Preferences > Mouse and Keyboard Settings. On the Keyboard tab, click the Keyboard Layout button to select your appropriate keyboard layout.

Step 3 of 6: Install the Python packages

This operation will install a Python package installer and the Xively Python library.

  1. From the Raspberry Pi taskbar at the top of the screen, start the default terminal application, Terminal.
    The following is an example of a terminal:
  1. 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:
pip3 install --user --pre xiPy

In some cases, users may need to use sudo to install the library:
sudo pip install --user --pre xiPy

Step 4 of 6: Set up your digital device

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!

Create a device template

This device template will represent the Raspberry Pi that we are using for this example.

  1. Click on Devices > Device templates.
  2. Click on Create new device template.
  3. Enter the template name (for example: "My Raspberry Pi").

Add a channel to the template

This operation will create a channel that the device will communicate over (talk and listen).

  1. In the Channels section, click on the + button.
  2. Enter "piMessage" as the channel name.
  3. Leave the other options as their default and click Save Channel.

Create an individual device

This individual device will represent the specific Raspberry Pi that you have physically connected for this example.

  1. On the device template page, click Create new device.
  2. 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).
  3. Click Create.

You created a device template and a digital device instance inside Xively to represent your physical Raspberry Pi device.

Get credentials for this 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.

  1. On the digital device page, click on Get password.
  1. In the pop-up window, click Download.
    A file named MQTTCredentials.txt gets 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.

Step 5 of 6: Prepare the Raspberry Pi client application

This step will prepare xiPy, our physical device's client, to manage communication to and from Xively.

  1. Go to your digital device page on the Xively management app and click on the Messaging tab.
  2. In the drop-down list labeled PUBLISH TO, select the piMessage channel.
  3. To copy the topic to clipboard, click on the blue area next to the drop-down list.
    The topic format looks as follows:
xi/blue/v1/<accountId>/d/<deviceId>/<topic>
  1. Open the file downloaded from Step 4, named MQTTCredentials.txt.
  2. On a new line, paste the topic you just copied from the Messaging tab.
  3. Click File > Save As..., navigate to the root directory (~/) and save it as xi_config.txt.
  4. Close the file.

Step 6 of 6: Prepare and run the sample application

Now you are going to download and run the example python scripts that publish and subscribe to Xively.

  1. Return to your terminal.

  2. Download the sample applications by running the following two commands:

wget https://s3.amazonaws.com/xipy-examples/xively_pub.py
wget https://s3.amazonaws.com/xipy-examples/xively_sub.py
  1. Make the digital device Messaging tab visible in your Raspberry Pi browser so you can see the messages coming through.

  2. 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:

  1. Go back to the terminal and terminate the previous command by pressing Ctrl+C.

  2. Subscribe to the MQTT topic. From the Raspberry Pi terminal, run the following command:

python xively_sub.py

This command executes the second example application you downloaded. Using the XiPy Library, the application subscribes to the MQTT topic you configured earlier.

  1. 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:

Congratulations!

YES! You did it! Now you have a Raspberry Pi connected to Xively.