Plošná ryba Hladina (PR-HLADINA)

Device page · Flash firmware from the browser

Measures the water level in a tank, well or cistern with ultrasound from above and calculates the volume in litres and the fill level in percent from the tank shape. Runs on a battery and sleeps between measurements. Sends data to Home Assistant over WiFi.

• DYP-A02YYUW sensor, waterproof (IP67), range 3 to 450 cm
• Tank shapes: vertical cylinder, horizontal cylinder, box, custom table
• Alarm when the level drops below a set percentage
• Measurement interval and tank dimensions are set from Home Assistant

What is in the box#

• Jádro board in a waterproof enclosure
• DYP-A02YYUW ultrasonic sensor on a cable, routed through the PG7 gland and connected inside the enclosure at the factory
• 18650 cell holder inside the enclosure, wired to the board (the cell is not included, see below)
• Card with a link to this guide

You do not thread or crimp any cables. You only mount the enclosure and the sensor.

Enclosure#

To stay waterproof, the enclosure has no external USB-C port and no access to the buttons. The top face has no holes, the lid is held by two screws on the underside. The status LED shines through a thin spot in the lid. USB-C and the BOOT and RESET buttons are reachable after loosening both screws and taking the lid off.

Status LED: on while the device is not connected to WiFi (waiting for setup). A short flash every 2 s means Maintenance mode, the device does not sleep. Off in normal operation.

18650 cell#

Batteries are not included. Put a common 18650 Li-ion cell with 2500 to 3500 mAh from a known brand into the holder. Both button top and flat top cells fit. Buy cells from a reputable seller. Offers like "9900 mAh" are fakes with a much lower real capacity.

Insert the cell following the + and - marks in the holder. If you put it in the wrong way round, nothing gets damaged, the board has reverse polarity protection and the device just does not start.

Charging: either swap the cell for a charged one (keeping a charged spare is handy, the swap takes a minute: two screws on the underside), or take the lid off and charge the device over USB-C indoors. Never charge a Li-ion cell below 0 °C.

First start#

Best done at home on the table, before you mount the enclosure:

1. Loosen the two screws on the underside and take the lid off.
2. Insert the cell into the holder. The device starts, the status LED is on and it waits 5 minutes for WiFi setup.
3. Set up WiFi (see below) and add the device to Home Assistant.
4. Put the lid back on and tighten the screws.

If 5 minutes are not enough, take the cell out and put it back, or press RESET.

Connecting to WiFi#

Pick one way:

• From the browser over USB: open https://plosnaryba.cz/firmware in Chrome or Edge, connect the board with a USB-C cable, click Connect and enter your WiFi name and password (Improv).
• Over Bluetooth in Home Assistant: if HA has Bluetooth (an adapter or an ESPHome Bluetooth proxy), it offers the new device for WiFi setup. Click it, enter the details and confirm the pairing by pressing the BOOT button on the board. Without the BOOT press the device does not accept WiFi credentials, so nobody can set it up without having it in hand.

The device has no fallback WiFi network and no default password. Only 2.4 GHz WiFi is supported.

Adding to Home Assistant#

1. Open Settings, Devices and services. The ESPHome device Plošná ryba Hladina is listed as discovered. Click Add.
2. Confirm. If HA offers to set an encryption key, accept it.
3. Assign an area (for example Garden). Entities appear on their own, no YAML needed.
4. Create the Maintenance mode helper (see Maintenance mode), you will need it for updates.

Later the device sleeps most of the time and shows up in HA at its next wake-up.

Installation#

1. Measure the tank#

You will need:

• Tank height: inner height from the bottom to the level you consider full (usually the overflow), in cm.
• Sensor offset: how many cm the sensor face sits above the full level. If the sensor is in a neck 10 cm above the overflow, enter 10. If it is exactly at the overflow level, leave 0.
• Depending on the shape:
  • vertical cylinder (barrel, round IBC, well): diameter
  • horizontal cylinder (lying tank): diameter and length. Enter the tank height equal to the diameter.
  • box (IBC container, concrete cistern): width and length
  • irregular shape: a "height in cm : litres" table, see Tank setup

All dimensions are inner dimensions in centimetres.

2. Mount the sensor#

• The sensor must point straight down at the water surface. Even a few degrees of tilt distorts the reading.
• Keep it at least 15 to 20 cm away from walls, ladders, pipes and the inflow. Ultrasound reflects off them.
• The water must never come closer than 3 cm to the sensor face (blind zone). In practice leave at least 5 cm, or mount the sensor in a neck or riser.
• Fix the sensor in the tank lid or on a bracket. The sensor is waterproof, the Jádro board is protected by the enclosure.

3. Mount the enclosure#

• Place the enclosure outside the tank, out of direct rain and where water does not condense (not inside a closed cistern).
• Mount it so you can reach the screws on the underside when you swap the cell.
• Leave a drip loop in the cable below the enclosure so water runs off before reaching the gland.

Tank setup#

On the device page in HA, in the Configuration section:

1. Tank shape: pick the shape.
2. Enter Tank height, Sensor offset and the dimensions for the shape (diameter, length, width). The other fields are ignored for that shape.
3. Alarm below: fill level in percent below which Low level turns on (default 20 %).
4. Measurement interval in minutes (default 30).

Home Assistant cannot send changes to a sleeping device. So change settings in Maintenance mode (see below): turn it on, wait until the device wakes up and stays awake, set everything and turn maintenance mode off again. During the first start the device is awake for 5 minutes, so you can enter the settings right away.

Check: measure the distance from the sensor face to the water with a tape and compare with the Distance to surface entity. Up to 1 cm difference is normal. If the distance matches but the water level does not, adjust Sensor offset.

Custom table#

For tanks that are neither a cylinder nor a box (conical bottom, cellar cistern with a step), enter height in cm:litres pairs into Volume table, separated by commas or semicolons, decimal point:

0:0,20:150,50:600,100:1500,140:2200

Values between the points are interpolated linearly. The best way to get the points is while filling: after each known amount of water (water meter, bucket) note the Water level. 4 to 8 points are enough, more where the shape changes. The field holds up to 255 characters.

The fill level in percent is always a share of the volume, not the height. A horizontal cylinder is 50 % full at half height, but only about 20 % full at a quarter of the height.

Maintenance mode#

After a timer wake-up the device stays awake only until the data is sent (about 3 to 5 s) and goes straight back to sleep. For an OTA firmware update or for fine-tuning settings it has to stay awake. That is what Maintenance mode is for: the device does not sleep and setting changes take effect immediately. Turn it on in one of these ways:

• With a Home Assistant helper (the main way, the enclosure stays closed). Create it once: Settings, Devices and services, Helpers, Create helper, Toggle, name it "Plošná ryba údržba". This creates the entity input_boolean.plosna_ryba_udrzba. The device reads it right after connecting on every wake-up, so you just turn the helper on and wait for the next wake-up. One helper works for all battery powered Plošná ryba devices.
• With the BOOT button while the device is awake. The button is under the lid, so this only works with the enclosure open (for example during the first start).
• With the Maintenance mode switch on the device page in HA, while the device is awake.

In maintenance mode the status LED gives a short flash every 2 s. When you are done, turn the helper off, the device then leaves maintenance mode and goes to sleep. The helper and the BOOT button do not get in each other's way: the helper turned on switches maintenance mode on, the helper turned off switches it off only when you change it while the device is awake. So the helper state right after a wake-up does not cancel maintenance mode started with BOOT, turn that off with the Maintenance mode switch. As long as the helper is on, maintenance mode comes on at every wake-up. The device remembers the mode across sleep and restarts and would drain the battery in a few days.

You can use a different helper entity in your own build by setting the udrzba_entita substitution in the YAML.

Entities#

Home Assistant builds the entity ID from the device name and the entity name, typically sensor.plosna_ryba_hladina_volume. With several devices HA adds _2 and so on. The table lists the suffix after the device name (English firmware build).

Automations#

Low water notification to the HA mobile app. Replace notify.mobile_app_phone with your own service.

automation:
  - alias: "Tank: low level"
    triggers:
      - trigger: state
        entity_id: binary_sensor.plosna_ryba_hladina_low_level
        to: "on"
    actions:
      - action: notify.mobile_app_phone
        data:
          title: "Tank is running low"
          message: >
            {{ states('sensor.plosna_ryba_hladina_volume') }} l left
            ({{ states('sensor.plosna_ryba_hladina_fill_level') }} %).

Stop the irrigation pump when the tank gets low:

automation:
  - alias: "Tank: stop pump below 10 %"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.plosna_ryba_hladina_fill_level
        below: 10
    actions:
      - action: switch.turn_off
        target:
          entity_id: switch.irrigation_pump

Troubleshooting#

Battery life#

Calculated estimate, not a measurement. With the 30 minute interval (default) a 3000 mAh 18650 cell at room temperature lasts about 10 months. A longer interval means a proportionally longer life. Below freezing the cell delivers noticeably less, so expect a shorter time in winter. WiFi signal strength and the condition of the cell matter too. The calculation and its assumptions are in docs/baterie.md (Czech).

A forgotten Maintenance mode shortens the battery life a lot. Charging is described in the 18650 cell section.

Safety#

• Li-ion cells: do not use damaged, swollen or dented cells. Do not charge below 0 °C or above 45 °C, so never outdoors in winter. Do not short the terminals. Remove or disconnect the cell for transport and storage.
• Outdoors: the Jádro enclosure must not stand in water or in a cistern that can flood. The sensor is IP67, the board is not.
• No mains voltage: the device runs on safety extra-low voltage only (USB 5 V, battery 3.7 V). Do not connect anything from the 230 V mains to it. Control pumps and valves through HA and switches made for that.
• Drinking water: the sensor does not touch the water, but only put clean, undamaged parts into a drinking water tank.

Version 2: pressure probe (documentation only for now)#

Ultrasound has limits: depths above roughly 4 m, foam on the surface, narrow shafts, heavy condensation. For those cases we are preparing a head with a submersible pressure probe. There is no firmware for it yet.

• Hydrostatic pressure probe for 0 to 5 m water column, 4 to 20 mA current output (4 mA = empty, 20 mA = 5 m).
• Water level h = (I - 4 mA) / 16 mA x 5 m. The volume is calculated the same way as now.
• The probe lies on the bottom. The cable needs a vent tube for atmospheric pressure compensation and its end has to stay dry.
• The current loop needs 12 to 24 V. The head will have a converter from 5 V or the battery and will power the probe only during the measurement (through HEAD_EN), otherwise a loop drawing up to 20 mA would drain the battery quickly.
• Current measurement: a shunt resistor and an ADC converter on Qwiic (for example ADS1115), more accurate than the built-in ADC.
• Pros: foam, condensation and shaft shape do not matter. Cons: the probe sits in the water, costs more, and the vented cable is more delicate.