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 or Serial
- via HTTP using RESTful API calls
- via MQTT via topics and their payloads
Definitions~
First some important definitions.
Important
<device>
is the short-name. It can be either 1. an EMS Device and supported devices include:boiler
thermostat
mixer
heatpump
solar
gateway
switch
controller
pump
generic
heatsource
ventilation
- the EMS-ESP system itself identified assystem
- the Dallas temperature sensors astemperaturesensor
- any custom Analog sensors asanalogsensor
- any EMS telegram custom entities ascustom
<command>
is the name of either - a generic command, or - an EMS device entity also referred to as an<entity>
. See the Supported Devices page 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 as any type (integer, float, string or boolean) or a JSON object {} string containing multiple key/values pairs as: - "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.
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
Console~
- 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 a complete list of commands use
call <device> commands
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 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 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
- For a complete list of commands use
http://<hostname>/api/<device>/commands
Reading and Writing EMS Device information~
The URL path is http://<hostname>/api/<device>/
endpoint | HTTP method | action | authentication required? | post 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 command entities to call | no | |
entities | GET | lists all enabled entities | 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 | post 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 |
Fetching custom entities (EMS telegrams)~
The URL path is http://<hostname>/api/custom/
endpoint | HTTP method | action | authentication required? | post body |
---|---|---|---|---|
blank or info | GET | outputs all custom entities and their values | no | |
<name> | GET | outputs all characteristics for a specific custom entity | no |
Fetching Temperature Sensor information~
The URL path is http://<hostname>/api/temperaturesensor/
endpoint | HTTP method | action | authentication required? | post body |
---|---|---|---|---|
blank | GET | outputs connected Dallas temperature sensor names and readings | no | |
info | GET | outputs all details on the connected Dallas temperature sensors | no | |
<name> | GET | outputs all characteristics for a specific temperature sensors | no |
Controlling the Analog Sensors~
The URL path is http://<hostname>/api/analogsensor/
endpoint | HTTP method | action | authentication required? | post body |
---|---|---|---|---|
blank | GET | outputs analog sensors and their readings | no | |
info | GET | outputs all details on the connected analog sensors | no | |
<name> | GET | outputs all characteristics for a specific analog sensors | 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>} |
System Commands~
The URL path is http://<hostname>/api/system/<endpoint>
endpoint | HTTP method | action | authentication required? | post body |
---|---|---|---|---|
info or blank | GET | outputs current system information | no | |
fetch | GET | forces at refresh of all device values | no | |
restart | GET | restarts EMS-ESP | yes | |
format | GET | factory reset's EMS-ESP | yes | |
commands | GET | lists the available system commands | no | |
send | POST | send telegram to the EMS bus | yes | "XX XX...XX" |
message | POST | send a message to the log and MQTT | yes | ".." |
publish | POST | MQTT publish all values, and optional HA-configuration or specific for a device | no | [ha] \| [device] |
watch | POST | watch incoming telegrams | no | <on \|off \| raw \| <type-id(hex)> |
values | GET | outputs all values in short format | no | |
read | GET | queries a specific EMS device and a typeID | yes | <deviceID> <type ID> [offset] [length] |
response | GET | outputs the last response from EMS-ESP | no | |
entities | GET | lists all enabled entities | no | |
mqtt/enabled | GET | enable/disable MQTT | yes | <bool> |
ap/enabled | GET | enable/disable Access Point | yes | <bool> |
settings/analogenabled | GET | enable/disable analog sensor | yes | <bool> |
settings/hideled | GET | enable/disable LED | yes | <bool> |
settings/showeralert | GET | enable/disable shower alert | yes | <bool> |
settings/showertimer | GET | enable/disable shower timer | yes | <bool> |
syslog/enabled | GET | enable/disable syslog | yes | <bool> |
Examples~
...via the command line~
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
|
...using a Python script~
1 2 3 4 5 6 7 8 9 10 11 |
|
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:
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 degrees 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 |
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:
1 |
|
where
cmd
is one of the commands listed in the Commands and must be enclosed in quotes as a String. The keyentity
may also be used instead ofcmd
.data
(orvalue
) 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
andhs
are other suppoerted aliases. For example withhc
it is used to indicated a specific Heating Circuit. A numeric value or String can be both used.
Some more examples:
topic | payload | action |
---|---|---|
ems-esp/boiler | {"cmd":"heatingactivated", "data":"on"} | turn on heatingactivated in boiler |
ems-esp/boiler/heatingactivated | {"data":"on"} | turn on DHW disinfecting in boiler (equivalent to command above) |
ems-esp/boiler | {"cmd":"dhw.disinfecting", "data":"on"} | turn on DHW disinfecting in boiler |
You can check the log in Status - System Log if the command was accepted by EMS-ESP.
The first command in the table above was valid and thus accepted:\ Topic:ems-esp/boiler
Command/payload: {"cmd":"heatingactivated", "data":"on"}
1 |
|
And the following bogus command is not accepted:\ Topic:ems-esp/boiler
Command/payload: {"cmd":"heatingactivated", "data":"5000"}
1 2 |
|
You can easily test the MQTT commands with MQTT Explorer. Just connect to the MQTT broker and publish the payload to the topic.
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}
.