Altair SmartWorks - | developers | tutorials | raspberrypi carriots

How to Connect a Raspberry to Altair SmartWorks and a Relay

0. Introduction
1. Project Schema
2. Raspberry Pi. Connections description
3. Altair SmartWorks Project and Device Registration
4. Data Transferred from Raspberry Pi to Altair SmartWorks
5. Code implemented on Raspberry Pi
6. Checking Data is collected in Altair SmartWorks
7. Creating an Alert with Altair SmartWorks Listeners
8. From here on: Enhancing the project

0. Introduction

This tutorial will help you build a system that checks whether an electrical circuit is open or closed.
For this, we need a Raspberry PI able to generate a small electric field and make the change of state of a relay.
In this project you will learn how to:

Connect a Raspberry Pi to Altair SmartWorks to send data streams using Altair SmartWorks HTTP REST API
Build an Alert App on Altair SmartWorks by programming a Listener to send an email using the SDK

Difficulty:

Ingredients

1 x Raspberry Pi. An alternative is to use an Arduino Uno
1 x Tiny Breadboard
2 x Resitance. Value of 330KΩ
1 x Led
1 x Transistor NPN
1 x Relay

TOP

1. Project Schema

This Project is a quick way to create an alarm app and understand the basics of combining Raspberry PI and Altair SmartWorks.

Here is overall diagram of the project:

Schema

Raspbery Pi is programmed to send a data stream to Altair SmartWorks and close or open the light circuit.

All the data streams sent by Raspberry Pi are collected and stored in Altair SmartWorks. Altair SmartWorks is a huge database that collects all the information that your sensors send.

In addition to storing data, the true power of Altair SmartWorks is to let you build Apps very quickly with few lines of Groovy code. In this scenario we are going to build a very simple Alert App that sends an email to you in case that Raspberry Pi detects light.

With Altair SmartWorks you can build very complex Apps to support all the logic of your product on the cloud and integrate it with other devices and IT systems. But for now let’s keep it simple.

TOP

2. Raspberry Pi. Connections description

The connections in Raspberry Pi are extremely simple. You can see in the diagram below.

Device Diagram

Circuit Diagram

Connections

TOP

3. Altair SmartWorks Project and Device Registration

Device

If youre registered in Altair SmartWorks, you have a default device already created for you.
Check your control panel and see what it looks like.
Basically you need the device id_developer that might be something like defaultDevice@myusername.
But if you want, you can create a new device and use it in this example.

Apikey

Now, go to your control panel “My account menu” and check your Apikey.
Its a big alphanumeric token like:
98346673a6377ef1fde2357ebdcb0da582b150b00cabcd5a0d83045425407ab4.
You need this number to complete the example.

TOP

4. Data Transferred from Raspberry Pi to Altair SmartWorks

From Raspberry Pi you have to build a HTTP request and send the data.

HTTP request
POST /streams HTTP/1.1
Host: api.altairsmartcore.com
Accept: application/json
User-Agent: RaspberryPi-SmartCore
Content-Type: application/json
Apikey: YOUR APIKEY HERE
Content-Length: YOUR CONTENT LENGTH HERE
Connection: close
Data
{
"protocol":"v2",
"device":"YOUR DEVICEs ID_DEVELOPER HERE",
"at":"now",
"data":{"light":"YOUR DATA HERE"}
}

TOP

5. Code implemented on Raspberry Pi

This is the Python code installed in the Raspberry Pi. Note that some values should be replaced by your own values.

# -*- coding: utf-8 -*-

"""
    Run.py
    AltairSmartCore.com
    Created 08 Oct 2016
"""

#!/usr/bin/python
from urllib2 import urlopen, Request
from json import dumps, loads
import RPi.GPIO as GPIO
import json

GPIO_pin = 24
ON = 'ON'
OFF = 'OFF'

class Carriots (object):
    api_url = "http://api.altairsmartcore.com/"

def __init__(self, account, api_key, client_type='json'):
        self.client_type = client_type
        self.api_key = api_key
        self.account = account
        self.content_type = "application/vnd.altairsc.api.v2+%s" % self.client_type
        self.headers = {'User-Agent': 'Raspberry-SmartCore',
                        'Content-Type': self.content_type,
                        'Accept': self.content_type,
                        'Apikey': self.api_key}
        self.payload = None
        self.response = None

def set_device(self, device):
        self.device = device + "@" + self.account + "." + self.account

def send_stream(self, data):
        payload = {"protocol": "v2", "device": self.device, "at": "now", "data":data}
        self.payload = dumps(payload)
        request = Request(self.api_url + "streams", self.payload, self.headers)
        self.response = urlopen(request)
        return self.response

def get_value_property(self, key_property):
        self.payload = None
        request = Request(self.api_url + "devices/" + self.device, self.payload, self.headers)
        self.response = urlopen(request)
        return json.loads(self.response.read()).get("properties").get(key_property)

def main():
    GPIO.setmode(GPIO.BCM)

GPIO.setup(GPIO_pin, GPIO.OUT)

# Altair SmartWorks parameters
    account = 'YOUR ACCOUNT HERE'
    apikey = 'YOUR APIKEY HERE'
    device = 'YOUR DEVICE HERE'

# Instance object Carriots
    carriots = Carriots(account, apikey)

carriots.set_device(device)

history_value_device = OFF

print "n> :: Welcome...n"

while True:
        value_device = carriots.get_value_property('state')  # In this example, we use 'state' text

if value_device != history_value_device:
            if value_device == ON:
                GPIO.output(GPIO_pin, GPIO.HIGH)
            else:
                GPIO.output(GPIO_pin, GPIO.LOW)

print "> Property value of device: " + str(value_device) + "n"
            history_value_device = value_device

if __name__ == '__main__':
    main()

TOP

6. Checking Data is collected in Altair SmartWorks

It's time to test that data is correctly collected in Altair SmartWorks. You can use any API-Rest client to send test streams

Example API-Rest client

Example API-Rest client response

To test our control panel and check if we have new streams go to “Data management” → “Data streams” and you will see your data.

Data Stream list

TOP

7. Creating an Alert with Altair SmartWorks Listeners

We have enhanced the listener creation process with our Flow Tool.

A listener in Altair SmartWorks can be associated to any hierarchy entity, from Project to Device. If you associate a listener to a project, all devices below the services of that project will be affected. If you associate a listener to service, all devices below the groups of that services will be affected. And so on.

In this example, we create a listener associated with our device. This listener waits for an event to occur in the context of the device and then evaluate the content.

To create a listener go to the control panel, then to “Rules” → “Listeners” and click on the new button. Select "Device" as "entity type" and select your device on the "Id" field.

Fill the fields with the following values and continue to the next step.

Name: The name that you prefer
Description: The description that you prefer
Entity type: Device
Entity id: Your device id_developer (defaultDevice@example.example)
Event to listen: "Event Data Persisted"
Be sure to have your listener enabled if you want it to be executed
Click on the "Next Step: design the code" button to visually design the listener functionality

Listener creation

In the Flow editor we'll need to follow these steps:

Step 1: Drag and drop in the editor workspace a "switch" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "If lights ON"
If condition: select "if" and fill in the following field with the code context.data.light=="ON"
Else condition: click on the button "+ add" and select "else"
Click on the button "Done" to apply the changes

Flow designer Step 1: Switch node

Step 2: Drag and drop in the editor workspace a "send email" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "Send ON email"
To: [[Your Email Here]]
Subject: Light ON
Message: Select "$ variable" in the drop-down and type "Electric circuit closed, status of light: " + context.data.light
Click on the button "Done" to apply the changes
Step 3: Drag and drop in the editor workspace a "send email" node and Double-click it to configure it with the values:
Label: descriptive name of the node in the editor view. For example "Send OFF email"
To: [[Your Email Here]]
Subject: Light OFF
Message: Select "$ variable" in the drop-down and type "Electric circuit open, status of light: " + context.data.light;
Click on the button "Done" to apply the changes
Step 4: Connect the "if" node ports to their corresponding "send email" node. From left to right, the ports correspond to the conditions added in the first step from top to bottom.

Flow designer Step 2, 3 and 4: Node Send Email configuration and connections

Step 5: Click on the "Save" button and check the listener data in the "Show" screen. You can have a look at the generated source code and use it later for debugging purposes.

Flow designer Step 5: Resulting listener + source code

Its time to test our listener. Send a data stream to this device, check your control panel and your email!

TOP

8. From here on: Enhancing the project

Now you know how to connect a Raspberry Pi device to send data to Altair SmartWorks and how to create a simple App with a single Listener and some SDK programing in Groovy. But you can enhance this project in many ways:

Try to control the electric energy of a room no matter where you are.
Create a control panel to manage the above suggestion.

TOP