Commands

EMS-ESP has a command API which can be used to read and write values to EMS device and call specific commands.

There are 3 methods commands can be invoked:

• via the Console using Telnet CLI
• via HTTP using RESTful HTTP calls
• via MQTT via topics their payloads

Definitions~

First some important definitions.

Console~

• Commands can be executed using the call command
• You need to be admin to use the call command. First su and enter the password
• For a list of all available commands you can use show commands
• The syntax is call <device> <command> <data> <id>

For more information on how to use the Telnet Console see the Console section.

HTTP~

Things to note:

• The REST API follows the OpenAPI Specification
• The URL path always starts with http://<hostname>/api/
• <hostname> is either an IP address or the mDNS name, which default is ems-esp.local
• Some commands require can be dangerous and require security authentication, unless disabled via an EMS-ESP setting. The authentication is in the form of an Access Token which is generated from the WebUI's Security->Manage Users and then clicking on the key button for the admin user. The 152 character long string must be included in the HTTP header like "Authorization: Bearer {ACCESS_TOKEN}". The tokens have no expiry date
• With HTTP PUSH/PUT/PATCH commands an HTTP body may be required. This can be in the form of either plain text or as a JSON object <data>
• HTTPS with self-signed certificates are not yet supported

Reading and Writing EMS Device information~

The URL path is http://<hostname>/api/<device>/

Examples:

Fetching custom entities (EMS telegrams)~

The URL path is http://<hostname>/api/custom/

Fetching Temperature Sensor information~

The URL path is http://<hostname>/api/temperaturesensor/

Controlling the Analog Sensors~

The URL path is http://<hostname>/api/analogsensor/

System Commands~

The URL path is http://<hostname>/api/system/<endpoint>

Examples~

...via the command line~

# Most GETs do not need authentication
% curl http://ems-esp.local/api/thermostat/seltemp

# POSTs (with -d) need authentication tokens
% curl http://ems-esp.local/api/thermostat/seltemp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJ1c2VybmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWUsInZlcnNpb24iOiIzLjEuMWIwIn0.qeGT53Aom4rDYeIT1Pr4BSMdeWyf4_zN9ue2c51ZnM0' \
  -d '{ "value" : 22.5 }'

# GET with authentication using query parameter with token
% curl http://ems-esp.local/api/system/publish\?access_token\="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJ1c2VybmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWUsInZlcnNpb24iOiIzLjEuMWIwIn0.qeGT53Aom4rDYeIT1Pr4BSMdeWyf4_zN9ue2c51ZnM0"

# GET to restart EMS-ESP
curl http://ems-esp.local/api/system/restart -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJ1c2VybmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWUsInZlcnNpb24iOiIzLjEuMWIwIn0.qeGT53Aom4rDYeIT1Pr4BSMdeWyf4_zN9ue2c51ZnM0'

...using a Python script~

import requests
import json

url = "http://ems-esp.local/api/thermostat/temp"
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJ1c2VybmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWUsInZlcnNpb24iOiIzLjEuMWIwIn0.qeGT53Aom4rDYeIT1Pr4BSMdeWyf4_zN9ue2c51ZnM0"
body = json.dumps({ "value": 22.5 })
headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token }

response = requests.post(url, headers=headers, data=body, verify=False)

print(response.json())

MQTT~

MQTT uses the same format as the API.

The topic matches the URL path except the <hostname> is replaced with the MQTT Base name as defined in the Settings (default is ems-esp).

The payload is the same as the <data> as described above and used in the API.

Examples:

Publishing Commands~

EMS-ESP will MQTT 'subscribe' to specific topics depending on the EMS devices attached. For example boiler, thermostat etc.

Commands can be sent to EMS-ESP via these MQTT topics using the payload format:

{"cmd":"<cmd>", "data":<data>, "id":<n>}

where

• cmd is one of the commands listed in the Commands and must be enclosed in quotes as a String. The key entity may also be used instead of cmd.
• data (or value) holds the value for the command, and can be either a String or numeric value.
• id is used as an generic indicator. hc, wwc, ahs and hs are other suppoerted aliases. For example with hc it is used to indicated a specific Heating Circuit. A numeric value or String can be both used.

With Home Assistant, Thermostat commands can also be sent to control individual heating circuits via sending a mode string or temperature number to a topic thermostat_hc<n>.

Depending on mqtt-settings there are also direct subscriptions for each value like boiler/wwtemp, thermostat/hc1/daytemp, etc. Thermostats which supports only a single heating circuits will subscribe to /thermostat/daytemp.

You can also use MQTT to send a specific read request and the telegram response will be returned in a topic called response. For example sending the payload {"cmd":"send", "data":"0B 88 19 19 02"} to ems-esp/system will result in a topic response being published with the data {"src":"08","dest":"0B","type":"19","offset":"19","data":"7D 00","value":32000}.