lagarto swap
- Introduction
- Configuration
- Installing lagarto-swap
- Running lagarto-swap
- Control and monitoring page
- Packet format
- HTTP GET-POST interface
- MQTT interface
Lagarto-SWAP is a daemon process written in Python that interacts between any SWAP network and the IP world. This process relies on pyswap and takes advantage of the whole functionality provided by the python library. On the IP side, lagarto-swap provides HTTP and MQTT interfaces so the process can talk to almost any automation software and GUI available nowadays.
lagarto-swap runs on any Linux machine supporting Python and requires very little memory to work. It has been tested on multiple Raspberry-Pi platforms, Beaglebone Black and conventional computers running Linux, Windows and OSX. It also works on small Linux computers running OpenWRT.
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. For any other OS please refer to the README file
The only Python modules that need to be installed are paho-mqtt, pyserial, cherrypy, pycrypto. All these modules can be installed with easy_install or pip install (python-setuptools). Besides, pyswap needs to be installed with "python setup.py install". Pyswap is already included in the Python-tools folder.
lagarto-swap can be easily launched with the following command:
# python [relative path to the lagarto directory]/lagarto/lagarto.py
After running the process, lagarto-swap will start downloading the Device Definition Files for each developer/manufacturer documented in devices.xml. This process needs to be completed at least once in order to do a first update of the definition files. Later, if you feel that this process is taking too long you can disable it in lagarto/lagarto-swap/config/settings.xml (set update to False)
Lagarto-SWAP is almost entirely configured from the web interface. Default HTTP port is 8001 so in order to access the web interface we have to open the following URL:
http:\\ip_address:8001
This page lets us define the location for the different configuration files and remote repositories. Debug level can be configured from this page as well. You can leave the default parameters.
Every lagarto process needs some configuration parameters to be edited from this page:
- Process name: name of the lagarto process. This name has to be unique in case that multiple lagarto processes are running in the same network.
- MQTT server: IP address of the MQTT broker. At least one MQTT broker needs to be running in the IP network.
- MQTT port: MQTT port used by the broker. This port is usually 1883 in most applications.
- HTTP server port: unique for each lagarto process running in the same machine.Default value is 8001.
Serial port and speed of the SWAP modem connected to the Lagarto-SWAP computer. panStamps running the modem application use 38400 bps as the default serial speed.
Configuration of the wireless network settings. Refer to the description page of the SWAP protocol for an explanation about the config settings appearing on this web page.
This web page provides a simple interface for viewing and controlling SWAP values. It also lets us configure endpoints (location, name, units).
Devices can also be configured from an independent page:
Lagarto uses a special JSON format for any packet containing endpoint and network information. This format is used by both the HTTP and MQTT interfaces. 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 HTTP 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. 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.
With this simple HTTP interface, lagarto-swap can be integrated with other third-party applications supporting continuous HTTP polling. Continuous polling is generally something that has to be avoided, and this is why lagarto-swap provides MQTT, a TCP/IP interface better suited for asynchronous connections. However, sometimes HTTP is the only mechanism available on other controllers and continuous polling is the only way to monitor values in pesudo-real-time.
Let's say that we want to read a temperature value:
Request -> http://localhost:8001/values?location=garden&name=temperature5
Response ->
{
"lagarto":
{
"procname": "Lagarto-SWAP",
"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.
Now let's control a relay:
Request -> http://localhost:8001/values?location=garden&name=relay1&value=on
Response ->
{
"lagarto":
{
"procname": "Lagarto-SWAP",
"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"
}
]
}
}
MQTT provides TCP/IP connectivity and interoperability between IP devices. Lagarto-SWAP can connect to a MQTT broker (Mosquitto, Mosca, etc) and then start communicating with a long list of automation software, including node-red, OpenHAB, Domoticz, Home Asistant, HomeSeer, etc.
Lagarto-SWAP publishes and subscribes to two main MQTT channels:
Inbound topic (status received from lagarto-swap): [lagarto-swap process name]/simple/status/[endpoint location]/[endpoint name] Outbound topic (control packet sent to lagarto-swap): [lagarto-swap process name]/simple/control/[endpoint location]/[endpoint name]
The endpoint is identified in the topic by means of its location and name, which need to be configured from lagarto-swap's web interface. The message body simply contains the value of the endpoint. This packet format is simpler to handle and very straightforward to integrate with other third-party software. We recommend using this format instead of the JSON channel unless you need more detailed data such as time stamp, endpoint id or unit information.
Example: temperature received from SWAP network Packet received from topic Lagarto-SWAP/simple/status/garden/temperature5
15.0
Example: control relay Packet sent to topic Lagarto-SWAP/simple/control/garden/relay1
"ON"
Inbound topic (status received from lagarto-swap): [lagarto-swap process name]/json/status Outbound topic (control packet sent to lagarto-swap): [lagarto-swap process name]/json/control
No endpoint data is appended to the topic. Endpoint information, including location and name, is included in the message body following the JSON format already detailed. However, only the necessary information to identify the endpoint and set the new value is necessary.
Example: temperature received from SWAP network Packet received from topic Lagarto-SWAP/json/status
{
"lagarto":
{
"procname": "Lagarto-SWAP",
"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"
}
]
}
}
Example: control relay Packet sent to topic Lagarto-SWAP/json/control
{
"lagarto":
{
"status":
[
{
"location": "garden",
"name": "relay1",
"value": "ON",
}
]
}
}
Node-red supports MQTT messaging out-of-the-box. The following a is a basic example of a temperature value coming from our SWAP network (through lagarto-swap) and being injected into an existing node-red flow:
The above flow uses a MQTT node to inject temperatures coming from a panStamp sensor. Configuring the MQTT node is very straightforward:
Pay attention to the endpoint location-name duple included in the MQTT topic (Simple raw format). Following this technique any SWAP endpoint managed by lagarto-swap can be inserted into node-red in a matter of seconds.