Skip to content

lagarto

Jump to bottom Edit New page
Daniel Berenguer edited this page Jan 4, 2016 · 9 revisions

This page describes the old TCP/IP interface provided by older versions of lagarto. ZeroMQ is no longer used by lagarto (lagarto-swap) and lagarto-max has been deprecated. Instead, lagarto implements MQTT and relies on third-party software such as node-red for the decisional part and the integration with other third-party solutions

Introduction

Lagarto is an open platform designed to automate physical tasks in homes, buildings and industrial plants. Lagarto provides the necessary communication tools and computing infrastructure to build complex networking applications, capable to integrate resources from very different technologies and present them in an homogeneous way.

Architecture

Lagarto is a networked application written in Python. It consisting of two different types of processes:

  • Lagarto servers : servers connect the Lagarto infrastructure with external physical networks. Lagarto-SWAP is the reference implementation for this kind of component. Integrating Lagarto with other physical networks requires developing a custom Lagarto server.
  • Lagarto clients : clients are data consumers. They receive events from servers and send commands to them in a bi-directional way. Lagarto clients are typically implemented by computing services, scripting engines and graphical interfaces.

Communication between servers and clients are simple and efficient. Every Lagarto server provides a HTTP GET/POST interface used to control values from clients or any other application providing HTTP client capabilities (Web browser, javascript, Flash). Thus, Lagarto servers are very easily integrated into any Web-based platform through local network or the Internet. Besides, Lagarto servers use a common ZeroMQ Publishing socket used to notify events to clients so that clients have not to continuously poll for changes from the physical networks. This dual communication mechanism (ZeroMQ + HTTP) results in a powerful bi-directional solution whilst covering two major requirements: cross-platform and cross.network.

Compared to other automation solutions, Lagarto introduces a small but important difference: it does not require a controller or central piece of software. Lagarto servers are autonomous processes whilst clients can access them in a direct way. No need for a main daemon to be running all the time. Thus, we may say that Lagarto's architecture is totally distributed. Another important feature is that Lagarto processes can run in a common platform or be distributed across multiple computers, locally (LAN) or globally (Internet).

In order to make Lagarto servers really autonomous, they provide their own embedded Web server for the configuration tasks and also for basic monitoring purposes.

Available lagarto processes

  • Lagarto-SWAP: lagarto server for SWAP networks and panStamps
  • Lagarto-MAX: lagarto server/client (broker) providing event management and connectivity to cloud data services

Protocol

Lagarto uses a custom JSON-based communication protocol between servers and clients. The following message is an example:

{
  "lagarto":
  {
    "procname": "SWAP network",
    "httpserver": "192.168.1.34:8001",
    "status":
    [
      {
        "id": "10.12.0",
        "location": "SWAP",
        "name": "Temperature",
        "value": 15.0,
        "unit": "C",
        "type": "num",
        "direction": "inp",
        "timestamp": "19 Feb 2012 16:15:17"
      },
      {
        "id": "10.12.1",
        "location": "SWAP",
        "name": "Humidity",
        "value": 20.0,
        "unit": "%",
        "type": "num",
        "direction": "inp",
        "timestamp": "19 Feb 2012 16:15:17",
      }
    ]
  }
}

Web interface

Lagarto processes provide a web interface for configuration and basic monitoring purposes. Every process binds to a different port number, allowing the existence of multiple servers on the same computer.

The HTTP port number is set from lagarto/Lagarto-Server/config/lagarto.xml. In the case of Lagarto-SWAP, the default HTTP port is 8001.

HTTP GET-POST interface

SWAP values can be queried and controlled through Lagarto-SWAP using simple HTTP commands. Lagarto servers accept both GET and POST methods for retrieving and setting values. HTTP requests must comply with one of the following formats, depending whether the endpoint is referenced by its unique ID or by its location/name strings:

Using the ID to identify the endpoint:

http://ip_address:port/values?id=endpoint_id&value=endpoint_value

Using location and name to identify the endpoint:

http://ip_address:port/values?location=endpoint_location&name=endpoint_name&value=endpoint_value

HTTP "READ" requests do not have to include the "value" field.

Time to read something

Let's say that we want to read a temperature value:

Request -> http://localhost:8001/values?location=garden&name=temperature5

Response ->
{
  "lagarto":
  {
    "procname": "SWAP network",
    "httpserver": "192.168.1.34:8001",
    "status":
    [
      {
        "id": "10.12.0",
        "location": "garden",
        "name": "temperature5",
        "value": 15.0,
        "unit": "C",
        "type": "num",
        "direction": "inp",
        "timestamp": "19 Feb 2012 16:15:17"
      }
    ]
  }
}

If we want to read the whole SWAP network from a single HTTP GET request then we have to send this request:

http://localhost:8001/values?

Then a complete list of values will be returned, following the same format as in the previous example.

Time to control something

Now let's control a relay:

Request -> http://localhost:8001/values?location=garden&name=relay1&value=on

Response ->
{
  "lagarto":
  {
    "procname": "SWAP network",
    "httpserver": "192.168.1.34:8001",
    "status":
    [
      {
        "id": "10.12.0",
        "location": "garden",
        "name": "relay1",
        "value": "ON",
        "type": "bin",
        "direction": "out",
        "timestamp": "19 Feb 2012 16:15:17"
      }
    ]
  }
}

Installation

The simplest way to install lagarto is by downloading and installing the Python tools. There is currently an installation script for Debian-like OS's (Debian, Ubuntu, Raspbian) that simplifies the process very much.

Once the installation completed, send a first message to your Twitter account from PTT's command-line tool:

# twitter [email protected] Hello world!

This will set your Twitter account as the default one on your computer so that Lagarto-MAX won't have to worry about your account details.

Finally run the necessary Lagarto processes. You can run both lagarto-max and lagarto-swap with a single call:

# python lagarto/lagarto.py

This way lagarto.py will take care of the necessary sequence and timing between the calls to lagarto-max and lagarto-swap. Otherwise, they could be individually launched as follows:

For lagarto-max:

# python lagarto/lagarto-max/lagarto-max.py

And for lagarto-swap:

# python lagarto/lagarto-swap/lagarto-swap.py

Screenshots

Supported web browsers

Mozilla Firefox and Google Chrome have proven to work well with lagarto's web pages. Internet Explorer is able to display most pages except for the ones running AJAX (device and endpoint browsers).

panStamp - Wireless miniatures

Anti Swap

API for Anti Swap

Clone this wiki locally