Raspberry PI is one of the most popular and well-known embedded systems platform in the world at this time, which contains connectivity (Bluetooth, wi-fi, ethernet), powerful computational resources and also is capable of running Linux distros (Raspbian, Ubuntu and a bunch of other distros). From personal computers to complex robotics systems, Raspberry PI fits very well as a cheap and small-size solution.

Considering its features, it makes sense to use Raspberry PI in the Internet of Things solutions, prototypes and products. This article will show you the first steps into the Internet of Things using Raspberry PI and the TagoIO IoT platform, in order for you to be able to make your projects come alive.

What will you need?

To get into the Internet of Things world and projects using Raspberry PI, TagoIO and Python, you’ll need:

• A Raspberry PI board, model 3B or newer (Zero W/ 3B+/ 4).

• A micro-SD card, with a minimum size of 4GB. It’s strongly recommended to use a 16GB class 10 micro-SD card, in order to maximize the Raspberry PI’s overall performance and to not suffer with mass storage memory running low everytime.

• Raspbian (a Linux distro specially design for the Raspberry PI) installed in a micro-SD card. It’s strongly recommended to install the latest Raspbian version available at https://www.raspberrypi.org/downloads/

• A Raspberry PI with Internet connectivity up and running (via wi-fi or ethernet).

• Python interpreter version 3.6 or newer.

As this article uses the Python (3.x version) programming language, any proficiency in Python programming is welcome here.

First things first: setting up your TagoIO account and creating a device

First of all, you need to create and access a TagoIO account, and you need to have a working device created too. For more details on how to do this, please read this tutorial: Getting Started

After creating a device on the platform, a corresponding device token is generated. it’ll be needed further on in this article.

How does Raspberry PI interact with TagoIO?

There are two approaches to interact with the TagoIO platform from a Raspberry PI board:

1. Using TagoIO’s Python SDK
2. Using a common / general purpose MQTT client (Paho MQTT client)

This article will show how to send and get data from TagoIO using both methods.

Approach - TagoIO Python SDK installation

Before proceeding to the TagoIO Python SDK installation, it’s strongly recommended to update your Raspbian version to the latest one. If you’re not sure if you have the latest Raspbian version installed in your Raspberry PI board, run the following commands in a Raspberry PI terminal session. This should take up to an hour to complete. After this, your Raspberry PI will reboot and you’ll be ready to go.

$ sudo apt update
$ sudo apt dist-upgrade
$ sudo apt clean
$ sudo reboot

To install the TagoIO Python SDK, simply use the following command in a Raspberry PI terminal:

$ sudo pip3 install -U tago

This installation should take up to 30 or 40 seconds. Afterwards, the TagoIO Python SDK will be installed and ready to use.

Sending your first set of data to the TagoIO IoT platform using TagoIO’s Python SDK

Once you’ve installed TagoIO’s Python SDK, you have everything needed to start sending your first set of data to TagoIO from a Raspberry PI. The data in this tutorial refers to temperature data.
To send your first set of data to TagoIO, first save the following Python source code to a folder on your Raspberry PI (e.g. your home folder) as send_first_data.py. Please, don’t forget to replace the ‘DEVICE_TOKEN_HERE’ string for the device token of the device you’ve created on the TagoIO platform.

import tago

my_device = tago.Device('DEVICE_TOKEN_HERE')

"""
The following code defines the set of data to be sent to TagoIO
data fields:
- variable name
- variable unit
- variable value
- Optional: desired data timestamp 
- Optional: lat/long location (associated to your data) 
"""
data = {
            'variable': 'temperature',                
            'unit'    : 'F',                                    
            'value'   : 55,                                                   
            'time'    : '2020-04-22 13:00:00',                           
            'location': {'lat': 42.2974279, 'lng': -85.628292}    
}

result = my_device.insert(data)
print(result)

To run this code, run the following command in a Raspberry PI terminal (in the same folder you’ve saved the Python source-code):

$ python3 send_first_data.py

You’ll get an output like the one shown in figure 1. The data sent status is highlighted in red.

If you receive this success result (as shown in figure 1), you’ve sent your first set of data to TagoIO!

Retrieving data previously sent to the TagoIO IoT platform

Now, it’s time to retrieve / receive the last set of data you’ve sent to TagoIO by using our Python SDK. To do that, first save the following Python source code to a folder on your Raspberry PI (e.g. your home folder) as retrieve_data.py. Please, don’t forget to replace the ‘DEVICE_TOKEN_HERE’ string for the device token of the device you’ve created on the TagoIO platform.

import tago

my_device = tago.Device('DEVICE_TOKEN_HERE')

"""
The following code defines a filter to retrieve data from TagoIO
Filter fields:
- variable to be retrieved
- query type
"""

filter = {
            'variable': 'temperature',                   
            'query': 'last_value',                         
}

result = my_device.find(filter)
print(result)

I’d like to talk a little more about the query field / parameter used in the source-code above. This parameter is defined as ‘last_value’, which means that only the most recent set of data will be retrieved from TagoIO. For more details on queries, please access this page from our documentation: Getting Data.

To run this code, run the following command in a Raspberry PI terminal (in the same folder you’ve saved the Python source-code):

$ python3 retrieve_data.py

You’ll get an output like the one shown in figure 2. The main data sent (location, value and unit) are highlighted in red.

If you get an output like the one shown in figure 2, you’ve successfully retrieved your first set of data from TagoIO using our Python SDK.

Alternatively, you can add start_time and end_time parameters / fields to your filter. This makes the data retrieving process look only for the data comprised between the time and date indicated in these parameters.
For example, let’s suppose that you want to retrieve the most recent set of data sent (temperature variable), considering the time period between 2020-04-23 00:00:00 and 2020-04-23 23:59:59. In this case, your filter should look like the one below:

filter = {
            'variable': 'temperature',                   
            'query': 'last_value',                          
            'end_date': '2020-04-23 00:00:00',   
            'start_date': '2020-04-23 23:59:59'   
}

This kind of feature is very useful, mainly when you have a lot of device data and want to retrieve a specific set of data for further analysis, making the work in edge / client-side / Raspberry PI side a lot quicker and easier.

Approach - using a common MQTT client to send and receive data from the TagoIO platform

By now, you should be able to send and receive data from TagoIO using our Python SDK. It’s a very useful manner to do this, mainly when you’re looking for the most neat and efficient code for your project.

Unfortunately, you might come across a situation that you cannot use TagoIO’s Python SDK for due to severe computational resource restrictions (hardware, software and/or network), for instance. Well, the good news is that you have an alternative: to implement a regular / common MQTT client to send and receive data from TagoIO. Considering a MQTT client demands very low computational resources to work; it can be a lifesaver when you need to interact with TagoIO while only using the least possible amount of your computational resources.

From this point on, you’ll learn how to send and receive data from the TagoIO platform using a MQTT client that you will implement in Python.

Installing the needed library

To get started, you’ll need to install a needed library to make it possible for your Raspberry PI to turn into an MQTT client (using the Python programming language). A good choice for this is to install the Paho-MQTT Client Python library (paho-mqtt · PyPI), a very good MQTT client library for Python, maintained by the Eclipse Foundation.

To install this library, use the following command in a terminal session on your Raspberry PI:

$ sudo pip3 install paho-mqtt

This should take up to 30 or 40 seconds to complete. After this, the Paho-MQTT Client Python library will be available for you to use.

Sending a set of data to TagoIO using an MQTT client

Once you’ve installed the Paho-MQTT Client Python library, you should have all of the tools needed to send (and receive) a set of data to the TagoIO platform using MQTT. Here, you’ll also need the device token of your device from TagoIO (as seen in Approach ).

The following Python source-code does the trick: it sends a set of data to a device at TagoIO, using a random number as a temperature value. This data is sent to the TagoIO platform in JSON format, as specified in MQTT.

import paho.mqtt.client as mqtt
import sys
import random
import time
import json

#Definitions
#put here your device token
device_token = 'DEVICE_TOKEN_HERE' 
    
broker = "mqtt.tago.io"
broker_port = 1883
mqtt_keep_alive = 60
    
#MQTT publish topic must be tago/data/post
mqtt_publish_topic = "tago/data/post" 

#put any name here, TagoIO doesn't validate this username.    
mqtt_username = 'mqtt_client' 

#MQTT password must be the device token (TagoIO does validate this password)
mqtt_password = device_token 

#Callback - MQTT broker connection is on
def on_connect(client, userdata, flags, rc):
        print("[STATUS] Connected to MQTT broker. Result: " + str(rc))

#Main program
print("[STATUS] Initializing MQTT...")
client = mqtt.Client()
client.username_pw_set(mqtt_username, mqtt_password)
client.on_connect = on_connect
client.connect(broker, broker_port, mqtt_keep_alive)

#Generate a random temperature to send to TagoIO (from 32 to 86F)
temperature = random.randint(32,86)
txt_temperatue="Random temperature generated: {rand_temp}F"
print(txt_temperature.format(rand_temp=temperature) )

#Format data into JSON
temperature_json = {"variable": "temperature", "unit": "F", "value": temperature}
temperature_json_string = json.dumps(temperature_json)

#Send data to TagoIO using MQTT
client.publish(mqtt_publish_topic, temperature_json_string)
print("Data sent to TagoIO platform")

You’ll get an output like the one shown in figure 3.

This means that your data has been sent and is now available on the TagoIO platform for further processing and usage. If you create a simple dashboard to display this variable value, you can see the random / fake temperature sent as shown in figure 4.

Retrieving data from your device on the TagoIO IoT platform using an MQTT client

Once you’ve sent some data from your device to the TagoIO platform, they can be retrieved from the platform using an MQTT client too, in order to make data retrieving also possible without using TagoIO’s Python SDK.

However, this procedure here works a little bit different from how it has previously using our Python SDK. The difference lies in how and when data is sent to an MQTT client. To retrieve data from TagoIO using an MQTT client, an Action must be implemented at TagoIO to redirect just-received data sent in a variable to a custom MQTT message. This means that only when new data is received at TagoIO, it can be sent in custom MQTT messages; it is not possible to receive previous / past messages from this device.

This Action works by doing the following: when anything is received in a variable of your device on the TagoIO platform, it’ll be published in an MQTT message, using a custom topic name you choose, with a payload filled with a JSON-formatted string containing data sent to the device.

Therefore, the MQTT client in this case isn’t able to query for data: it just subscribes to a custom MQTT topic and waits for data to come, which will happen just after TagoIO receives new data from a chosen variable and device.

Implementing an Action to redirect data received to an MQTT message

To do this, follow the step-by-step procedure below:

1. Click on the Actions button, as shown in figure 5.

Figure 5 - Actions button

2. Click on the Add Action button, as shown in figure 6.

3. The “Add Action” screen will pop-up. On this screen, fill the information as described below, and after that click on the Create My Action button.

- Name: put any desired name for this Action (in my case, “mqtt_redirect”)
- Type of trigger: Variable
- Type of Action: Publish to MQTT
- Publish to the devices linked to: here, select your device in TagoIO platform (in my case, “temperature_test_device”)
- Topic: here, type a custom topic name you want to use (in my case, “mqtt_temp_test_device”)
- Payload: here, fill with the following content, which corresponds to a JSON-formatted response to be sent as MQTT payload.

{
        "variable": "$VARIABLE$",
        "unit": "$UNIT$",
        "value": "$VALUE$"
}

This screen with all the information filled up should resemble what’s shown in figure 7.

4. Then, a new screen will show up and more information on your Action will be required. On this screen, select your device name in the Select the device combo box, select “temperature” on the Trigger variable combo box and select “Anything” on the Trigger condition combo box. Your screen will look similar to what’s shown in figure 8.

Then click on the Save button.

5. That’s it! Your Action is now complete.

Implementing an MQTT client to get data sent via MQTT message

Now, you must implement an MQTT client to get data sent / redirected from the TagoIO platform. This MQTT client must be able to subscribe to the custom MQTT topic you’ve chosen and wait for new data to come.
To implement this MQTT client, use the Python source-code below. Data is sent in MQTT payload, being formatted as a JSON-format string, as specified in MQTT.
Save the following Python source code to a folder on your Raspberry PI (e.g your home folder) as receive_data_mqtt.py. Please, don’t forget to replace the ‘DEVICE_TOKEN_HERE’ string for the device token of the device you’ve created at TagoIO.

import paho.mqtt.client as mqtt
import random
import json

# Definitions
# put here your device token
device_token = 'TeslaMate'

broker = "mqtt.tago.io"
broker_port = 1883
mqtt_keep_alive = 60

# MQTT publish topic must be tago/data/post
mqtt_publish_topic = "test"

# put any name here, TagoIO doesn't validate this username.
mqtt_username = 'tagoio'

# MQTT password must be the device token (TagoIO does validate this password)
mqtt_password ='device-token'

# Callback - MQTT broker connection is on


def on_connect(client, userdata, flags, rc):
    print("[STATUS] Connected to MQTT broker. Result: " + str(rc))
  # Generate a random temperature to send to TagoIO (from 32 to 86F)
    temperature = random.randint(32,86)
    txt_temperature="Random temperature generated: {rand_temp}F"
    print(txt_temperature.format(rand_temp=temperature) )

    # Format data into JSON
    temperature_json = {"variable": "temperature", "unit": "F", "value": temperature}
    temperature_json_string = json.dumps(temperature_json)

    # Send data to TagoIO using MQTT
    y = client.publish(mqtt_publish_topic, temperature_json_string)
    print(y.rc)
    print(y.is_published())
    print("Data sent to TagoIO platform")
    client.disconnect();
    client.loop_stop()

def on_publish(client, userdata, result):
    print("Message published")
# Main program

def on_message(client, userdata, message):
    print("Received message '" + str(message.payload) + "' on topic '"
        + message.topic + "' with QoS " + str(message.qos))

print("[STATUS] Initializing MQTT...")
client = mqtt.Client(protocol=mqtt.MQTTv31)
client.username_pw_set(mqtt_username, mqtt_password)
# client.tls_set_context()
client.on_connect = on_connect
client.on_publish = on_publish
client.on_message = on_message

x = client.connect(broker, broker_port)

try:
    client.loop_forever()
except KeyboardInterrupt:
    pass

client.disconnect()
client.loop_stop()

To test it, I used two different Raspberry Pi terminal sessions: one to send data to the device on the TagoIO platform, and another to receive the data redirected from a device at TagoIO. This test’s outputs can been seen in figure 9, where the send data Raspberry Pi terminal session is on the left and the receive data Raspberry Pi terminal session is on the right.

Reviewing what you’ve learned

Raspberry PI is one of the most developed boards / embedded platforms in the world, being used in a great sort of projects. Considering Raspberry PI has great connectivity to Internet (wireless and using Ethernet cable), this board is suitable for IoT projects as well. This tutorial has shown you how to use Raspberry to send and retrieve data from the TagoIO platform, using both TagoIO’s Python SDK and a “pure” MQTT client implemented in the Python programming language.