lagarto
- Introduction
- Architecture
- Protocol
- Web interface
- HTTP GET/POST interface
- Raw format
- JSON format
- Installation
- Available lagarto processes
- Screenshots
- Supported web browsers
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.
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.
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",
}
]
}
}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.
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. Depending on the syntax of the HTTP request, values returned will present one of the following formats:
Raw format is a simple string containing the the endpoint value and unit. In order to get this format, the following syntax must be used:
http://ip_address:port/values/endpoint_location/endpoint_name/?value=endpoint_value*
For a SWAP endpoint containing temperature data, with location = "SWAP" and name = "temperature" we should use this url in the HTTP GET request:
Request -> http://localhost:8001/values/SWAP/temperature/
Response -> 25.6 C
Now if we want to control an output:
Request -> http://localhost:8001/values/SWAP/relay5/?value=on
Response -> on
The raw format is good for basic applications since data returned may be directly used by the consumer without much work. However, in some other situations we may want to retrieve or control multiple endpoints at the same time. In this case, we need to use the JSON method:
http://ip_address:port/values/?location=endpoint_location&name=name_location&...*
Not let's assume that we want to read a couple of temperature and humidity values:
Request -> http://localhost:8001/values/?location=garden&name=temperature5&location=bathroom&name=humidity1
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"
},
{
"id": "10.12.1",
"location": "bathroom",
"name": "humidity1",
"value": 20.0,
"unit": "%",
"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 just run:
http://localhost:8001/values
and a complete list of values will be returned, following the same format as the above example.
And now we are going to control a couple of relays:
Request -> http://localhost:8001/values/?location=garden&name=relay1&value=on&location=garden&name=relay2&value=off
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"
},
{
"id": "10.12.1",
"location": "garden",
"name": "relay2",
"value": "OFF",
"type": "bin",
"direction": "out",
"timestamp": "19 Feb 2012 16:15:17",
}
]
}
}
Before installing Lagarto you need to install pyserial, ZeroMQ with the Python bindings and Barrel.
1- Download pyserial and install it by running this command:
# python setup.py install
To install ZeroMQ just download the necessary package from here and follow the provided instructions. Most popular OS's also provide pre-packaged installers. Then follow these instructions for the Python bindings Barrel is the middleware used to provide HTTP Basic Authentication for the HTTP services. Download teh latest version from here, untar the package and complete the installation using the following command:
# python setup.py install
Now, if you want to run Lagarto-SWAP, you need to install pyswap. At the moment of writing this tutorial there was no setup script do you will have to do the followng:
- Download our Python toolbox for panStamp and SWAP.
- Enter the pyswap directory and install the package using this command:
# python setup.py install
If you want to run Lagarto-MAX, you need to install PyEphem first. Download the PyEphem? package and run this command:
# python setup.py install
And also install the Python Twitter Tools:
# easy_install twitter
After installing PTT, 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.
And finally run the necessary Lagarto processes. For Lagarto-SWAP:
# python lagarto/lagarto-swap/lagarto-swap.py
For Lagarto-MAX:
# python lagarto/lagarto-max/lagarto-max.py
- Lagarto-SWAP: lagarto server for SWAP networks and panStamps
- Lagarto-MAX: lagarto client providing event management and connectivity to cloud data services
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).