EasyProtocols

From Let's Control It
Jump to navigation Jump to search

Since version 2 ESP Easy supports several protocols to communicate with Home Automation controllers or webservices.

Only the first controller can be a MQTT capable controller.

List of protocols

Domoticz HTTP

This is the protocol that we have used to start building ESP Easy. And probably the most widely used in combination with ESP Easy. The protocol is supported by Domoticz out of the box so you don't need a special setup.

The ESP communicates with Domoticz on it's default port 8080, but of course that can be changed.

Sample configuration:

EasyConfigDomoticzHTTP.png


Domoticz MQTT

Only the first controller can be a MQTT capable controller.

This Domoticz protocol is a more recent development on Domoticz. You need to add this hardware: "MQTT Client Gateway with LAN interface" before you can use it.

Currently only receiving sensor data is supported on Domoticz MQTT. Switching actuators is not supported

Domoticz does not have a build-in MQTT broker. You can install Mosquitto quite easily if you have Domoticz running on a Raspberry-PI. The ESP communicates with a MQTT Broker on it's default port 1883, but of course that can be changed. The MQTT broker distributes all messages between connected nodes (systems that have a subscription to this broker).

Sample configuration:

EasyConfigDomoticzMQTT.png

When using a MQTT protocol, do not forget to set the ESP Unit number to a non-zero value, not conflicting with other ESP units.

OpenHAB MQTT

Only the first controller can be a MQTT capable controller.

Preliminary support. It has been tested with one device and seemed to work.

OpenHAB does not have a build-in MQTT broker. You can install Mosquitto quite easily if you have OpenHAB running on a Raspberry-PI. The ESP communicates with a MQTT Broker on it's default port 1883, but of course that can be changed. The MQTT broker distributes all messages between connected nodes (systems that have a subscription to this broker).

Sample configuration:

EasyConfigOpenHABMQTT.png

When using a MQTT protocol, do not forget to set the ESP Unit number to a non-zero value, not conflicting with other ESP units.


PiDome MQTT

Only the first controller can be a MQTT capable controller.

Preliminary support. It has been tested with one device and seemed to work. PiDome itself is still in alpha stage, but looks promising...

PiDome has a build-in MQTT broker. The ESP communicates with this MQTT Broker on it's default port 1883, but of course that can be changed. The MQTT broker distributes all messages between connected nodes (systems that have a subscription to this broker).

Sample configuration:

EasyConfigPiDomeMQTT.png

When using a MQTT protocol, do not forget to set the ESP Unit number to a non-zero value, not conflicting with other ESP units.


Nodo Telnet

We have build this support because there was no other way to get data into this controller. It does work, but it's not really a nice solution to the problem.

A Nodo Mega with Ethernet module (or NES Board) listens on the default telnet port (23). There can be only one concurrent session, so also this is limited. Using multiple ESP units with this protocol has not been tested and may lead to conflicts.

Sample configuration:

EasyConfigNodoTelnet.png


ThingSpeak

Simple webservice. Could be usefull if you don't have fancy Home Automation running like Domoticz. You could still get your home temperature onto the public internet with just a simple ESP module.

The ThingSpeak web service works with API Keys. Before you can use ThingSpeak, you must create an account, setup a channel and get the Write API-Key. This key has to be entered into the ESP controller password field.

Sample configuration:

EasyConfigThingSpeak.png

For ThingSpeak, you need to set Message Delay to 15000 to have multiple sensor readings working. This can be set under Tools/Advanced settings.

Extra information

  • Set the IDX/Variable for each task to the corresponding chart number in ThingSpeak. For instance, if you have "1" entered for the Uptime task. This is how the data is routed to the correct chart.
  • If you have two readings for a given sensor, Temp will go the chart that matches the DHT IDX/Variable and Humidity will go to the IDX+1 chart. For instance, if you have DHT11 set as IDX 5. In ThingSpeak, Temperature is displayed on chart 5 and Humidity on chart 6.

EmonCMS

Simple webservice. Could be usefull if you don't have fancy Home Automation running like Domoticz. You could still get your home temperature onto the public internet with just a simple ESP module.

The EmonCMS web service works with API Keys. Before you can use EmonCMS, you must create an account, setup a channel and get the Write API-Key. This key has to be entered into the ESP controller password field.

Sample configuration:

EasyConfigEmonCMS.png

Generic HTTP

Many systems provide a simple HTTP API where data can be changed using a GET request with a properly constructed querystring.

Something like: http://www.homeserver.local/update.php?name=demosensor&id=12345&value=23.5

You can setup a template and have this kind of request as a result.

Generic HTTP Advanced

Many systems provide a simple HTTP API where data can be changed using a HTTP request with a properly constructed querystring.

This Controller allows you to send HTTP GET, POST and PUT Requests to the given webserver.

For every device you have to choose to which Controllers it is sending its data. When configuring the Controller you can access this data and use them to generate your querystring.

You can use this placeholders in http header and in the http body:

 %systime% will be replaced with the local system time
 %vcc% will be replaced with the power supply voltage (if enable in this build)
 %ip% will be replaced with the local ip adress
 %sysload% will be replaced with the system load
 %uptime% will be replaced with the system uptime
 %CR% will be replaced with "\r"
 %LF% will be replaced with "\n" (newline)
 %sysname% will be replaced with the system name
 %tskname% will be replaced with the name of the device which is sending data to this controller
 %id%
 %vname1% will be replaced with Valuename 1
 %vname2% will be replaced with Valuename 2
 %vname3% will be replaced with Valuename 3
 %vname4% will be replaced with Valuename 4
 %val1% will be replaced with the value 1 of the device which is sending data to this controller
 %val2% will be replaced with the value 2 of the device which is sending data to this controller

You can also write things like this:

 %1%_some_text_and_placeholder_%/1%  everything between %1% and %/1% will only print when there is a value 1

An Example how to use this is the "virtual" Protocol for (Influxdb)

InfluxDB HTTP Api (via Generic HTTP Advanced)

works only with newest mega version!!

Select the Generic HTTP Advanced Controller and use this values to send your data to an InfluxDB HTTP Api:

Http controller influxdb.jpg

HTTP URI:

 write?db=testdb

HTTP Header:

 Content-Type: application/x-www-form-urlencoded

HTTP Body:

 %1%%vname1%,Standort=%tskname%
 Wert=%val1%%/1%%2%%LF%%vname2%,Standort=%taskname%
 Wert=%val2%%/2%%3%%LF%%vname2%,Standort=%taskname%
 Wert=%val3%%/3%%4%%LF%%vname2%,Standort=%taskname%
 Wert=%val4%%/4%

Nettemp HTTP Api (via Generic HTTP Advanced)

works only with newest mega version!!

untested but should work with something like this:

 /receiver.php?device=ip&type=%1%%vname1%%/1%%2%;%vname2%%/2%%3%;%vname3%%/3%%4%;%vname4%%/4%&value=%1%%val1%%/1%%2%;%val2%%/2%%3%;%val3%%/3%%4%;%val4%%/4%

FHEM HTTP

Supports the HTTP api for FHEM home automation. To unleash the full power of espeasy devices in FHEM, you definatly should have a look at the 3rd party module available here: https://github.com/ddtlabs/ESPEasy. Things may become unnecessary complicated without it.

Generic UDP

For Home Automation controllers that can process simple UDP messages. You can use a template for the UDP message payload.

Features per protocol

Many of these are still a work in progress and not every ESP Easy feature is supported on every protocol. The following table presents current development status:

Output GPIO on Domoticz MQTT can be done using the "Output - Domoticz MQTT helper" device.
Feature Protocols
Domoticz HTTP Domoticz MQTT OpenHAB MQTT PiDome MQTT Nodo Telnet ThingSpeak
Dallas Temperature Sensor YES YES YES YES YES YES
DHT Temp + Hum Sensor YES YES YES YES YES YES
Input switch YES YES YES YES YES YES
Output GPIO YES YES YES YES NO NO
Output MCP23017 YES NO YES YES NO NO