How to activate an electrovalve from my website through Carriots.

0. Introduction

This simple tutorial helps you to control an electrovalve from your personal website.
We will use Carriots functionality to verify that the device is active and to discover the last known IP address.
In this project you will learn how to:

  • Use status streams to verify that the device is active
  • Running cron jobs on Raspberry Pi
  • Create device properties
  • Create a Carriots rules to know a device's last known IP address
  • Send data streams to Carriots using PHP

Difficulty:

Ingredients

  • 1 x Raspberry Pi
  • 1 x Tiny Breadboard
  • 1 x Resitance. Range between 200KΩ and 10KΩ
  • 1 x Transistor
  • 1 x Diode
  • 1 x Relay (5V & 4 pines)
  • A handful of wires

Music to listen: Carriots - flowmeter

TOP

1. Project Schema

This project is a quick way to control an electrovalve through your personal web page using Carriots.

Here is overall project diagram:

  • Schema

Raspberry Pi is programmed to send an alive message to Carriots (status stream) every 20 minutes. When Carriots receives this message, it collects the IP address from where is sent.

If Carriots does not receive a message every 20 minutes, it means that the device is not working properly.

We use a personal website to open and close a remote electrovalve. To do this, we send streams to Carriots using PHP language. Carriots retrieves the last known IP address and sends the streams to open/close the electrovalve.

TOP

2. Carriots Project and Device Registration

Device

If youre registered in Carriots, 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

3. Raspberry Pi. Connections description

To open and close the electrovalve, we use a Raspberry Pi.
The connections in Raspberry Pi are extremely simple. You can see in the diagram below.

  • Diagram

TOP

4. Send status stream

In this example, our device will send a status stream every 20 minutes (with uptime) to indicate that it is alive.

From Raspberry Pi you have to build an HTTP request and send the status. The request format should be as follows:

  • HTTP request
    POST /status HTTP/1.1
    Host: api.carriots.com
    Accept: application/json
    User-Agent: RaspberryPi-Carriots
    Content-Type: application/json
    carriots.apikey: YOUR APIKEY HERE
    Content-Length: YOUR CONTENT LENGTH HERE
    Connection: close
  • Data
    {
    "protocol":"v2",
    "device":"YOUR DEVICEs ID_DEVELOPER HERE",
    "at":"now",
    "data":{"uptime":"YOUR DATA HERE"}
    }

Code implemented on Raspberry Pi

We will create a file named "status.php", this is the PHPs code of that file.

Aviso Remember you must have installed PHP on your Raspberry Pi.
Aviso Note that some values should be replaced by your own values.

Running cron jobs on Raspberry Pi every 20 minutes

To send status streams every 20 minutes, we will schedule a Cron on Raspberry Pi. Cron jobs are used to execute specific actions at pre-configured times.

All cron jobs are defined in crontab file and you can specify multiple of them, each on its own line. To edit your crontab, type in your console ~$ crontab -e or type ~$ crontab -l to show the content.

Type crontab -e in the Raspberry Pi console, and include the next line:

This file will run every 20 minutes sending a status stream.

Aviso If you want to know more about this, visit the following link http://en.wikipedia.org/wiki/Cron

TOP

5. Using a Carriots rule to find the electrovalve IP address

A rule is some custom Groovy code, a script, stored in Carriots that can be used in any listener. It’s useful for reusing code in different listeners.

In this tutorial we will create a new rule, which will store device's IP address in a device property.

Creating a device property

We need to create a new property to store the IP address that we are going to rescue with our rule.

To create a property go to the control panel, then to “Device management” → “Devices”. Locate your device and click on "Actions" → "Edit". Then click on "Add another property". We call this new property "last_IP".

Creating a rule

Now, we need to create the rule that will retrieve the IP address from the received status stream.

To create a rule go to the control panel, then to “Rules management” → “Rules” and then click on the new button.

Fill the fields with the following values and save the new rule.

  • Name: The name that you prefer
  • Description: The description that you prefer
  • Script:
    my_device = context.envelope.device;
    my_ip = context.meta.he.X-Real-Ip;
    import com.carriots.sdk.Device;
    def device = Device.find(my_device) ;
    device.device_properties.last_IP = my_ip;
    device.update();
  • Be sure to have your rule enabled

Using this rule in a listener

A listener in Carriots can be associated to any hierarchy entity, from Project to Device. If you associate a listener to a project, all devices associated with 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 device context 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 save the new listener

  • Name: The name that you prefer
  • Description: The description that you prefer
  • Entity type: Device
  • Entity id: Your id device
  • Event to listen: data_persisted
  • If expression: context.envelope._t=="sta"
    (Only if received status stream)
  • Then expression: leave empty
  • Then rule: Select your rule
  • Else expression: leave empty
  • Else rule: leave empty
  • Be sure to have your listener enabled if you want it to be executed

Its time to test our listener. Wait to receive a status stream and check the device property named "last_IP". You should have the IP address from which you received the status!!!

TOP

6. Raspberry Pi as a server to open/close the electrovalve

The next step will be to prepare the Raspberry Pi to receive GET requests and open or close the electrovalve.
To do this, we need to start a PHP server on Raspberry Pi and create a PHP file for processing requests.

Raspberry Pi PHP server

In this example, we will use the embedded PHP server.
As of PHP 5.4.0, the CLI SAPI provides a built-in web server. This web server is designed for developmental purposes only, and should not be used in production.

In your Raspberry Pi console, type the following sentences:

  • Create the folder where the server is running:
    $ mkdir -p public_html
    $ cd public_html
  • Run the server on port 8080:
    $ php -S YOUR RASPBERRY IP:8080 &
Aviso Note that some values should be replaced by your own values.

Now the server is running and waiting for requests!

Process PHP request

To open or close the electrovalve, our Raspberry Pi has to be prepared to receive HTTP GET requests.
If the request is something like "electrovalve.php?status=on" then the electrovalve will open and if you get something else, will close.

Create a PHP file named "electrovalve.php" with the following code:

Right now your device would be ready to receive requests and open/close the electrovalve!

TOP

7. Building the website to control the electrovalve

The next step will be to control the electrovalve from our personal website, for that we will include two buttons, one to open and one to close.

Creating our personal web page

If we knew the electrovalve IP address, we could send requests directly (remember that we have a server listening), but lets assume that the IP address can change and that we do not know it.

To solve this problem, we will send the requests to Carriots and it will do the job via a listener.

The example in a couple of PHP files would be:

  • index.html
  • send.php
Aviso Note that some values should be replaced by your own values.

And the result will be something like this:

  • Webpage

Creating the listener

We are finishing up, we just have to prepare a listener in Carriots!

This listener, will have to retrieve the last known IP address and send the request to our electrovalve.

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 save the new listener

  • Name: The name that you prefer
  • Description: The description that you prefer
  • Entity type: Device
  • Entity id: Your id device
  • Event to listen: data_persisted
  • If expression: context.data.valve=="on"
  • Then expression:
    import com.carriots.sdk.utils.BasicHttp;
    import com.carriots.sdk.Device;
    def basicHttp = new BasicHttp();
    def device = Device.find("YOUR DEVICEs ID_DEVELOPER HERE");
    def IP = device.device_properties.last_IP;
    basicHttp.url = "http://"+IP+":8080/electrovalve.php";
    basicHttp.params=["status":"on"];
    basicHttp.send();
  • Then rule: leave empty
  • Else expression:
    import com.carriots.sdk.utils.BasicHttp;
    import com.carriots.sdk.Device;
    def basicHttp = new BasicHttp();
    def device = Device.find("YOUR DEVICEs ID_DEVELOPER HERE");
    def IP = device.device_properties.last_IP;
    basicHttp.url = "http://"+IP+":8080/electrovalve.php";
    basicHttp.params=["status":"off"];
    basicHttp.send();
  • Else rule: leave empty
  • Be sure to have your listener enabled if you want it to be executed

Note that in some case the obtained IP address is the public IP address, so if your electrovalve is in a subnet, you have to use Network Address Translation (NAT).

Network Address Translation (NAT) is the process where a network device, usually a firewall, assigns a public address to a computer (or group of computers) inside a private network.

Aviso If you want to know more about NAT, visit the following link https://en.wikipedia.org/wiki/Network_address_translation

TOP

8. From here on: Enhancing the project

Now you know how to use status stream to verify that the device is active, create rules to know the last known IP address, send data to Carriots and how to create a simple App with Listeners and some SDK programming in Groovy.

But you can enhance this project in many ways.

Can you imagine the possibilities?

TOP