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:
<device>
is the short-name of either- an EMS Device such as
boiler
,thermostat
,mixer
,heatpump
,solar
orgateway
- the EMS-ESP system itself as
system
- the Dallas temperature sensors as
dallassensor
- an EMS Device such as
<command>
is the name of either- a generic command, or
- an EMS device entity also referred to as an
<entity>
. See the table below for the complete list
<id>
is an optional identifier and has different meanings depending on the context<data>
is used to represent the value to read or write. It can be either:- a single value. This can be of any type; integer, float, string or boolean
- as a JSON object containing the following optional key/values:
- "cmd" is the
<command>
. The key "cmd" may also be substituted for "entity". - "value" is the value and can be either a text string in quotes, an integer, float of boolean. "data" is an alias that can also be used instead for the key.
- "hc", "wwc" and "id" are all are used to represent a value or in the context of an EMS Device a heating or warm water circuit.
- "cmd" is the
Note: A boolean value can be represented in many forms:
- as a True value, "TRUE", "yes", true, "true", "on", 1
- as a False value, "FALSE", "no", false, "false", "off", 0
- Commands can be executed using the
call
command - You need to be admin to use the
call
command. Firstsu
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.
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 isems-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 Web UI's Security tab. 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
The URL path is http://<hostname>/api/<device>/
endpoint | HTTP method | action | authentication required? | body |
---|---|---|---|---|
info |
GET | outputs current EMS device information in verbose | no | |
values |
GET | outputs current EMS device information in short format | no | |
(empty) | GET | same as values above |
no | |
commands |
GET | lists the available commands or entities to call | no | |
entities |
GET | lists the matching Home Assistant entities (HA only) | no | |
{entity} |
GET | outputs details of a specific entity, for reading | no | |
{entity}/{hc} |
GET | same as the read command above but for a specific heating circuit | no | |
{entity} |
POST | updates a entity value, for writing | yes | <data> |
{entity}/{hc} |
POST | same as the write command above but for a specific heating circuit | yes | <data> |
Examples:
URL | body | action |
---|---|---|
http://ems-esp.local/api/thermostat/temp |
22 |
sets the selected room temperature of the master thermostat on heating circuit 1 |
http://ems-esp.local/api/thermostat |
{"cmd":"mode", "data":"auto"} |
sets the thermostat mode to auto for heating circuit 1 |
http://ems-esp.local/api/thermostat |
{"cmd":"seltemp", "data":23, "hc":3} |
sets the room temperature to 23 degrees for for heating circuit 3 |
http://ems-esp.local/api/thermostat/hc2 |
{"cmd":"seltemp", "data":20.5} |
sets the room temperature to 20.5 degrees for for heating circuit 2 |
The URL path is http://<hostname>/api/system/<endpoint>
endpoint | HTTP method | action | authentication required? | body |
---|---|---|---|---|
info |
GET | outputs current system information | no | |
fetch |
GET | forces at refresh of all device values | no | |
restart |
GET | restarts EMS-ESP | yes | |
commands |
GET | lists the available system commands | no | |
send |
POST | send telegram to the EMS bus | yes | "XX XX...XX" |
publish |
POST | MQTT publish all values, and optional HA-configuration or specific for a device | yes | [ha] | [device] |
watch |
POST | watch incoming telegrams | yes | <on |off | raw | <type-id(hex)> |
syslog_level |
POST | set syslog level | yes | <level> |
The URL path is http://<hostname>/api/dallassensor/
endpoint | HTTP method | action | authentication required? | body |
---|---|---|---|---|
info |
GET | outputs connected Dallas sensors and readings | no |
The URL path is http://<hostname>/api/analogsensor/
endpoint | HTTP method | action | authentication required? | body |
---|---|---|---|---|
info |
GET | outputs configured analog sensors and readings | no | |
commands |
GET | lists the available system commands | no | |
setvalue |
POST | set value/offset of counter or output pin, +/- sign corrects value | yes | {"value":<val>, "id":<gpio>} |
The tables below list the available commands (or entities) for each specific EMS device. These replace the <entity>
in the URL.
[!NOTE] The boiler commands below will vary depending on boiler type/brand and system configuration Some commands will not work because they are overwritten by controller or thermostat. In this case there are thermostat commands for this setting.
command | data | id | comments |
---|---|---|---|
comfort |
<hot |eco | intelligent> |
||
flowtemp |
<degrees> |
Limited to heatingtemp, set by thermostat if present | |
wwsettemp |
<degrees> |
Only if thermostat does not manage it | |
boilhyston |
<degrees> |
Start burner below flowtemp (negative value), allowed range depends on boiler type | |
boilhystoff |
<degrees> |
Stop burner above flowtemp (positive value), allowed range depends on boiler type | |
burnperiod |
<minutes> |
||
burnminpower |
<%> |
Changeable only for modulated burners | |
burnmaxpower |
<%> |
Changeable only for modulated burners | |
pumpdelay |
<minutes> |
||
wwactivated |
<off | on> |
||
wwtapactivated |
<off | on> |
Special function working in boiler test-mode | |
wwonetime |
<off | on> |
Overwritten by some thermostats, see thermostat commands | |
wwcircpump |
<off | on> |
||
wwcirc |
<off | on> |
Overwritten by some thermostats, see thermostat commands | |
wwcircmode |
<n> |
(1=1x3min, .. 6=6x3min, 7=on) | |
wwflowtempoffset |
<degrees> |
Offset to boiler temperature while preparing warm water | |
wwmaxpower |
<%> |
Maximum power for warm water heating | |
heatingactivated |
<off | on> |
Not changeable for some systems. i.g. Set by MC10 rotary control | |
heatingtemp |
<degrees> |
Upper limit for flowtemp, not changeable for some systems or overwritten (MC10) | |
maintenance |
<off | <hours> | <dd.mm.yyyy> | reset> |
set maintenance to date or time or reset message | |
pumpmodmin |
<%> |
Changeable only for modulated pumps | |
pumpmodmax |
<%> |
Changeable only for modulated pumps | |
reset |
<error | maintenance> |
Use reset error only if there is an active error! |
[!NOTE] The actual thermostat commands below will vary depending on which Thermostat brand and model you have.
command | data | id | comments |
---|---|---|---|
datetime |
<ntp | dd.mm.yyyy-hh:mm:ss-dw-dst> |
RC35, RC100, RC300, dw :day of week: 0-mo,.. dst :daylight saving 0/1 |
|
wwmode |
<off | on | auto> |
RC100, RC300, RC30, RC35 | |
wwsettemp |
<degrees> |
RC100, RC300 | |
wwsettemplow |
<degrees> |
RC100, RC300 | |
wwcircmode |
<off | on | auto | own> |
RC30, RC35, RC100, RC300 | |
wwonetime |
<off | on> |
RC100, RC300 | |
clockoffset |
<seconds> |
RC30 | |
language |
<n> |
RC30 (0=de, 1=nl, 2=fr, 3=it) | |
display |
<n> |
RC30 (0=int temp, 1= int set, 2=ext temp, 3=burner, 4=ww, 5=mode, 6=time, 7=date, 8=smoke) | |
minexttemp |
<degrees> |
RC30, RC35, RC100, RC300 | |
calinttemp |
<degrees> |
RC30, RC35 | |
building |
<light | medium | heavy> |
RC30, RC35, RC100, RC300 | |
temp |
<degrees> |
heating circuit | actual setpoint depending on mode |
mode |
<auto | night | day | nofrost | heat | eco> |
heating circuit | |
manualtemp |
<degrees> |
heating circuit | RC100, RC300 |
ecotemp |
<degrees> |
heating circuit | RC100, RC300, Junkers |
heattemp |
<degrees> |
heating circuit | Junkers |
comforttemp |
<degrees> |
heating circuit | RC100, RC300 |
summermode |
<winter | auto | summer> |
heating circuit | RC100, RC300 |
summertemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
nighttemp |
<degrees> |
heating circuit | RC20, RC30, RC35 |
daytemp |
<degrees> |
heating circuit | RC20, RC30, RC35 |
daytemp2 |
<degrees> |
heating circuit | RC20 |
daytemp3 |
<degrees> |
heating circuit | RC20 |
daytemp4 |
<degrees> |
heating circuit | RC20 |
nofrosttemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300, Junkers |
remotetemp |
<degrees> |
heating circuit | RC30, RC35 |
control |
<off | RC20 | RC3x> |
heating circuit | RC30, RC35 (roomcontrol for hc) |
pause |
<hours> |
heating circuit | RC30, RC35 |
party |
<hours> |
heating circuit | RC30, RC35 |
holiday |
<dd.mm.yyyy-dd.mm.yyyy | dd.mm.yyyy+dd.mm.yyyy> |
heating circuit | RC30, RC35, use - for 'away from home', + for 'at home' |
designtemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
offsettemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
holidaytemp |
<degrees> |
heating circuit | RC30, RC35 |
roominfluence |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
minflowtemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
maxflowtemp |
<degrees> |
heating circuit | RC30, RC35, RC100, RC300 |
flowtempoffset |
<degrees> |
heating circuit | RC30, RC35 |
program |
<0 - 10 | 1 - 9 | 1 - 2> |
heating circuit | RC30, RC35, RC20, RC100, RC300 |
controlmode |
<room | outdoor> |
heating circuit | RC30, RC35, RC100, RC300 |
reducemode |
<nofrost | reduce | room | outdoor> |
heating circuit | RC30, RC35 |
roomtemp |
<degrees> |
heating circuit | only v2.2: fake HA-thermostat roomtemp, use -1 to clear |
switchtime |
<nn.d.o.hh:mm> |
heating circuit | only v3: set one of the programs switch times, nn=number(00-42), d=day(0-6), o=on(0,1), hh:mm=time, d=7 or o=7 clears |
# GETs do not need authentication
% curl http://ems-esp.local/api/thermostat/temp
# POSTs (with -d) need authentication tokens
% curl http://ems-esp.local/api/thermostat/temp \
-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'
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 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:
topic | payload | action |
---|---|---|
ems-esp/system/send |
"XX XX...XX" |
send raw ems-command |
ems-esp/thermostat/seltemp |
fetches the seltemp entity values and publishes it in the topic ems-esp/response |
|
ems-esp/thermostat/seltemp |
23 |
change the selected setpoint temperature to 23 degreees on the master thermostat on hc1 |
ems-esp/thermostat/mode |
"auto" |
sets the thermostat mode to auto for hc1 |
ems-esp/thermostat |
{\"cmd\":\"mode\",\"value\":\"heat\",\"id\":1} |
sets the thermostat mode to heat for hc1 |