Proteus sensor api integration

Hi there

I’m trying to get a ultrasonic level sensor to work with homeassistant and am failing with hacking everything into my configuration.yaml.

How should a working config.yaml look like?
The description of the API is found here: Proteus API

Looking forward to see any suggestions.

My current yaml looks like this:

  method: POST
    Content-Type: application/json
  payload: '{ "DeviceRequest": {"Username": "xyz", "Email": "xyz", "SecurityStamp": "xyz", "DeviceID": "xyz" }}'
  scan_interval: 60
    - name: "Oelstand"
      value_template: "{{ value_json.ActualVolume}}"
      json_attributes_path: "$.ActualVolume"
      - "ActualVolume"

Please keep us updated if you have any progress…
I’m also about to order one and was looking in integrating it. Will share how it goes when I get back to our Oel-Haus :slight_smile:

I can’t make it to work…

yaml looks like this atm:

  - platform: rest
    method: POST
      Content-Type: application/json
    payload: '{DeviceRequest: {"Username": "xy", "Email": "xy", "SecurityStamp": "xy", "DeviceID": "xy" }}'
    name: 'proteus level sensor'
    value_template: "OK"
    json_attributes_path: "$.deviceresponse"
      - DeviceID
      - DeviceName
      - Medium
      - LastUpdate
      - MaxVolume
      - ActualVolume
      - ActualVolumePercent
      - Battery
      - Temperature
    scan_interval: 120

Log shows the following error:

Source: components/rest/
Integration: RESTful (documentation, issues)
First occurred: 16:54:14 (1 occurrences)
Last logged: 16:54:14

JSON result was not a dictionary or list with 0th element a dictionary


Could it be the problems are caused by the response including backslashes for escaping? At least for me the response looks like


and so on.

There is a similar issue which sadly hasn’t been solved on github. It also includes some escaped chars.

if i make the request with postman i also get the response like you (with backslashes).
as this is the first time i’m trying something like this, I have no clue…

Same result with GetIt and Insomnia. I also have very limited experience but it’s the first time for me seeing this.

I’m seeing the same behaviour. The actual JSON string of the response is somehow re-encoded as JSON, ending up in a single string. To correct for this, you need to decode JSON twice. As far as I know this isn’t supported by the REST integration.

I’ve been toying with adding my own integration, but I’m struggling with the learning curve and Home Assistant’s somewhat lacklustre developer documentation.

So I have a basic integration working and I’m testing it now. I’m hoping to get it into good enough shape to submit to Home Assistant core, but I may have to make it available as a custom integration for now, if anyone else wants it.

It uses a proper config flow (no YAML editing) and knows how to work around the double-encoded JSON output from the E-Sensorix API.

If anyone wants to try it out, it’s here: GitHub - alexiosc/ecofrog: EcoFrog integration for Home Assistant


thank you for this, after integrationg it according to your manual it works!

first I tried setting your git as a repo for hacs and that did’nt worked out!

1 Like

Thank you! Good to know someone else tested this! I’m still learning HACS (which is why I don’t have the HACS banners etc. on the github page). I understand there’s some metadata that need to be added before the repo can be used directly from HACS, and I haven’t done that yet. Soon though!


First thank you for the efforts with the Integration.

Second I hope I that someone can help me with it as I am not using the e-Sensosrix one I use the EcoFrog from Protheus. This has a other API address and I can’t get it to work I have the API-Docimentation but I haven’t worked with API or programming. So maybe someone can assist me or show me the right path

As the Integration from @alexiosc hasent worked for me as i have the “same” Sensor from ad different seller ( . Below a working yaml code.
Enter this in you configuration.yaml and change the credentials in the payload line.

  - platform: rest
    scan_interval: 86400
    name: ecofrog
      - DeviceID
      - DeviceName
      - Medium
      - LastUpdate
      - MaxVolume
      - ActualVolume
      - ActualVolumePercent
      - Battery
      - Temperature
      - MessData
    payload: '{DeviceRequest: {"Username": "[email protected]", "accountID": "12345", "SecurityStamp": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "DeviceID": "xxxxxxx" }}'
    value_template: "OK"
  - platform: template
        friendly_name: "Eco_DeviceID"
        value_template: "{{ state_attr('sensor.ecofrog', 'DeviceID') }}"
        friendly_name: "Eco_Name"
        value_template: "{{ state_attr('sensor.ecofrog', 'DeviceName') }}"
        friendly_name: "Eco_Medium"
        value_template: "{{ state_attr('sensor.ecofrog', 'Medium') }}"
        friendly_name: "Eco_LastUpdate"
        value_template: "{{ state_attr('sensor.ecofrog', 'LastUpdate') }}"
        friendly_name: "Eco_MaxVolume"
        value_template: "{{ state_attr('sensor.ecofrog', 'MaxVolume') }}"
        unit_of_measurement: "L"
        friendly_name: "Eco_ActualVolume"
        value_template: "{{ state_attr('sensor.ecofrog', 'ActualVolume') }}"
        unit_of_measurement: "L"
        friendly_name: "Eco_ActualVolumePercent"
        value_template: "{{ state_attr('sensor.ecofrog', 'ActualVolumePercent') }}"
        unit_of_measurement: "%"
        friendly_name: "Eco_Battery"
        value_template: "{{ state_attr('sensor.ecofrog', 'Battery') }}"
        unit_of_measurement: "V"
        friendly_name: "Eco_Temperature"
        value_template: "{{ state_attr('sensor.ecofrog', 'Temperature') }}"
        unit_of_measurement: "°C"
        friendly_name: "Eco_MessData"
        value_template: "{{ state_attr('sensor.ecofrog', 'MessData') }}"
        unit_of_measurement: "cm"

After entering and restarting you have new sensors called Eco.XXX

Hope this helps someone

1 Like

Hi, thank you for your example. I have also purchased the sensor from Can you please explain me some more things about your example?
payload: ‘{DeviceRequest: {“Username”: “[email protected]”, “accountID”: “12345”, “SecurityStamp”: “xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx”, “DeviceID”: “xxxxxxx” }}’
accountID = Password?
SecurityStamp where do I get GUID from?
DeviceID = Serial number?

Thanks a lot

I made it work. Mail to [email protected].

1 Like

@4Nemo :
Sorry havent had seen your post. Glad that it work with my script. but i think i made some changes because the API request is to often so. i killed this and made an automation to fetch the data

In the Config Change scan_Interval to 31536000.

Then Make an Automation that reloads the Restful at a given time:

alias: Fetch EcoFrog
description: ""
  - platform: time
    at: "07:26:00"
condition: []
  - service: rest.reload
    data: {}
mode: single


i purchased the same sensor from Hardwarewise it is exactly the same sensor. I also was in contact with proteus-support. They can reconfigure the API for my device to their servers.

But i want to achieve a “cloudfree” solution. So the device should only communicate within my local network. Did someone have experience with this?

Im able to decrypt the JSON which was send from the device. And i also create a smal “man-in-the-middle” (which is just a local DNS-Record) which routes the traffice send by the device to one of my local IPs. But im not really experienced with python…

1 Like


i dont think that this will work.
The Data you recive from there API are not the same as the ones that are send to their site.

Best to archive a cloud-free version would be to ask them for support.

Maybe they are open for this idea

Hello, I have been using the Ecofrog for several months now. However, it looks a little different than when I started. About every 20 liters I see a change in consumption. Therefore, a daily consumption calculation is not really possible. However, it is quite sufficient for a rough estimate of the supply in order to reorder oil in time.

I now follow a different approach: I have installed a Shelly PM1 on my heating system. This measures the current flow reliably. As a result, I can now see exactly to the second when the burner is switched on and when it is switched off again. On the nozzle you can read the flow per hour. Also when the water pumps are connected to the shelly, I can see the start and stop of the burner. I then use this data to calculate the consumption. It’s not 100% accurate, but it certainly comes closer to actual consumption than the Ecofrog.

1 Like

this is not directly a flaw. this is normal as the EcoFrog is a ultrasonic device. it measures the distance between the sensor and the surface with a tolerance from +/- 1-2cm. and 1 cm is around 40 liters in a tank (in my case with a 6000 Liter Tank.
With only a Shelly PM1 its not possibly to mesure the flow so i assume you have put a flow meter in the oil line?

Yes, I know that it is with the ultrasound. For me, 1 cm corresponds to about 20 liters. However, it does not allow you to accurately calculate the daily consumption. With the current temperatures, the tank capacity fluctuates around the 20 liters, which additionally leads to some inaccuracy.

I only use the Shelly. It says on the nozzle how many gallons per hour it passes. The Shelly is very reliable in indicating when the burner activates and when it stops. It’s not 100 percent accurate, but it’s more accurate than ultrasound.

what is your setup exactly with the Shelly i’m interested how measure the flow rate with a Shelly 1PM