REST API
Query and control the sensor directly over HTTP, for scripts and other systems
Besides the web interface, every Eco sensor has a REST API. With it you read readings and switch or adjust things directly via the sensor's IP address, without the cloud and without Home Assistant. Any system that can send HTTP requests can use it: scripts (curl, Python), Node-RED, ioBroker, openHAB, FHEM and many others.
The API is part of ESPhome and built into every Eco sensor, there is nothing to switch on. The sensor's own web page uses it too.
Which interface for what?
| REST API | Home Assistant API | ecosensors.cloud | |
|---|---|---|---|
| For | your own scripts and any system | Home Assistant | dashboard, history, notifications |
| Range | local network only | local network only | from anywhere |
| Protection | access password, unencrypted (http) | own key, encrypted | your account |
Prerequisites
- The system that queries the sensor is in the same network as the sensor.
- You know the sensor's address (name or IP address, see Find the sensor). Set up a fixed IP address for the sensor in your router, otherwise your integration breaks as soon as the router hands out a new address. The examples below use
192.168.1.95. - The credentials are the same as for the web interface: user
adminand the sensor's password. The API asks for an HTTP login (called "Digest" in ESPhome). On the EcoMBR1 no password is set at the factory, so the API needs none either: set an access password anyway.
How a request is built
Every value and every control of a sensor is an entity with a fixed address:
http://<address>/<type>/<name>
The name is written exactly as the sensor knows it (English, e.g. Grid Frequency). Write spaces as %20, i.e. Grid%20Frequency. Which entities your sensor has is shown by the event stream. The type says what kind of entity it is:
| Type | Meaning | Example | value in the response |
|---|---|---|---|
sensor |
reading | Grid Frequency | number |
binary_sensor |
state with two values | Relay Override | true / false |
text_sensor |
text | Tibber Price Level | text |
switch |
switch | Relay 1 | true / false |
number |
adjustable number | Grid Relay ON | number as text, e.g. "-500" |
button |
triggers an action | Restart | (no response with a value) |
Which entities exist depends on the sensor; the examples here come from the EcoMBR1.
Reading values
A value is read with a simple GET request, in a browser just as with curl:
curl http://192.168.1.95/sensor/Grid%20Frequency
{"id":"sensor/Grid Frequency","value":50.01,"state":"50.0 Hz"}
value is the value for further processing, state the same value as text with its unit, as the web interface shows it. More examples:
curl http://192.168.1.95/switch/Relay%201
# {"id":"switch/Relay 1","value":false,"state":"OFF"}
curl http://192.168.1.95/text_sensor/Tibber%20Price%20Level
# {"id":"text_sensor/Tibber Price Level","value":"EXPENSIVE","state":"EXPENSIVE"}
If an access password is set, pass the credentials along. --anyauth lets curl pick the login method itself:
curl --anyauth -u admin:YourPassword http://192.168.1.95/sensor/Grid%20Frequency
Switching and adjusting
Everything that changes something is a POST request. The action goes at the end of the address:
# Switch: on, off, toggle
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_on
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_off
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/toggle
# Set a number (here: switch-on point of the grid power control)
curl -X POST -d '' "http://192.168.1.95/number/Grid%20Relay%20ON/set?value=-500"
# Press a button (here: restart)
curl -X POST -d '' http://192.168.1.95/button/Restart/press
The response is 200 without content; read the new state with GET as above. The -d '' matters: the sensor rejects a POST request without content and without a length with error 411. Other tools need the same: an empty request with Content-Length: 0.
On the EcoMBR1 the relay can only be switched by hand as long as no control (grid power, Tibber) is switched on, see Setting the relay. A switched-on control decides the relay itself.
All values and live updates
There is no separate address listing all entities. Instead the sensor provides an event stream (Server-Sent Events) at /events: right after connecting it sends all entities with their current value, afterwards every change immediately.
curl -N http://192.168.1.95/events
event: state
data: {"id":"sensor/Phase A Voltage","domain":"sensor","name":"Phase A Voltage","value":234,"state":"234.0 V","uom":"V", ...}
The id field is exactly the part you append to the sensor's address. This is how you find out which entities exist, and you get changes without constant polling. If you only need a value now and then, simply query it regularly with GET.
A sensor is a small microcontroller and tolerates only a few simultaneous connections. Do not query faster than every few seconds, and close an event stream when you no longer need it.
Examples for your own applications
Python (with the requests library):
import requests
from requests.auth import HTTPDigestAuth
auth = HTTPDigestAuth("admin", "YourPassword") # leave out if the sensor has no password
base = "http://192.168.1.95"
power = requests.get(f"{base}/sensor/Grid%20Active%20Power", auth=auth, timeout=5).json()["value"]
print(power, "W")
if power < -500: # feeding in: relay on
requests.post(f"{base}/switch/Relay%201/turn_on", data="", auth=auth, timeout=5)
Node-RED, ioBroker, openHAB and similar systems: You need a block that sends HTTP requests (in Node-RED the http request node, in other systems it is named similarly), with Digest login if a password is set. For values, enter the GET address and read the value field from the JSON response. To switch, send a POST request to the address ending in turn_on, turn_off or toggle.
Security
Without an access password, anyone on your WiFi can read values and operate the sensor (e.g. switch the relay). The connection is not encrypted (http): the password does not travel in plain text, but a determined attacker in the same network is not stopped by it.
- Do not make the API reachable from the internet (no port forwarding in the router). For access on the move, use the dashboard on ecosensors.cloud or a VPN into your home network.
- Do not store the password in plain text in scripts you pass on.
- The Home Assistant API is a separate, encrypted interface, see Home Assistant.