---
title: "Liquid Level Sensor"
description: "Monitor water level via Modbus RTU over RS-485. Configurable units (m, cm) and decimal precision. TapHome template for hydrostatic level sensors."
url: "https://taphome.com/en/compatibility/liquid-level-sensor/"
language: en
lastmod: 2026-10-08
generator: hugo
ai:
  topics: ["modbus-rtu","sensor","rs485","liquid-level","hydrostatic","water-tank"]
  questions: ["How to integrate a Modbus RTU liquid level sensor with TapHome?","What units does the liquid level sensor TapHome template support?","How to connect a submersible level sensor via RS-485 to TapHome?","Why does the liquid level sensor return NaN in TapHome?","How to change the slave address on a Modbus level sensor?","How to configure decimal points on a Modbus level transmitter?"]
---

# Liquid Level Sensor

Communication: Modbus RTU

## Integration guide

A generic Modbus RTU submersible hydrostatic liquid level sensor for monitoring water level in tanks, wells, or retention basins. The sensor communicates over RS-485 half-duplex and reports the measured level via holding register H:4. The TapHome template reads the measurement value with automatic decimal point conversion, supporting meters (m) and centimeters (cm) as display units.

This template is designed for generic Chinese-manufactured pressure/level transmitters that follow the same Modbus register map. The sensor is typically powered by 12-36 V DC and uses a 2-wire RS-485 connection to a Modbus to LAN converter (RS-485 to Ethernet).

## Hardware connection

The sensor uses an RS-485 half-duplex interface for Modbus RTU communication. Connect the sensor to a Modbus to LAN converter (RS-485 to Ethernet):

- **A+** (RS-485 Data+) on the sensor to **A+** on the Modbus to LAN converter
- **B-** (RS-485 Data-) on the sensor to **B-** on the Modbus to LAN converter
- **GND** to a common ground reference

The sensor also requires a separate DC power supply (typically 12-36 V DC, depending on the model). Power wires are separate from the RS-485 data wires.

> [!WARNING]
> Ensure a common ground reference between the sensor and the Modbus to LAN converter. Without proper grounding, Modbus communication may be unreliable or fail entirely.

## Configuration

### Default communication parameters

The sensor ships with the following default serial settings:

| Parameter | Default |
|-----------|---------|
| Baud rate | 9600 bps |
| Data bits | 8 |
| Parity | None |
| Stop bits | 1 |
| Slave address | 1 |

The baud rate can be changed via register H:1 (supported values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200). After changing the baud rate, write 0 to register H:15 to save the setting to the user area.

### Unit selection

The measurement unit is configured via register H:2. The TapHome template only supports two units:

| H:2 value | Unit | Behavior |
|-----------|------|----------|
| 16 | **m** (meters) | Returns the raw value directly (with decimal point conversion) |
| 17 | **cm** (centimeters) | Returns the value divided by 100 |
| All others | MPa, kPa, bar, etc. | **Returns NaN** -- not supported by the template |

> [!WARNING]
> If the sensor is configured to a unit other than m (16) or cm (17), the TapHome template will show NaN. Verify the unit setting before importing the template.

### Decimal point precision

Register H:3 controls how many decimal places the raw measurement value uses:

| H:3 value | Format | Division factor |
|-----------|--------|-----------------|
| 0 | #### | 1 |
| 1 | ###.# | 10 |
| 2 | ##.## | 100 |
| 3 | #.### | 1000 |
| 4 | .#### | 10000 |

The TapHome template automatically divides the raw H:4 value by 10^(H:3) to produce the correct reading. For example, if H:3 = 1 (one decimal point) and H:4 = 2500, the displayed value is 250.0.

### Import parameters

When importing the template in TapHome, two parameters are required:

| Parameter | Description | Example |
|-----------|-------------|---------|
| **Slave Id** | Modbus slave address of the sensor (1–247) | `1` |
| **IP address** | IP address of the Modbus to LAN converter | `192.168.1.100` |

## Device capabilities

### Water level measurement

The template provides a single read-only sensor device -- **Water Level** -- that reads holding register H:4 (Int16). The ReadState script applies dynamic conversion:

1. Reads the raw integer value from H:4
2. Divides by 10^(H:3) to apply the decimal point setting
3. Switches on H:2 (unit): if unit = 16 (m), returns the value directly; if unit = 17 (cm), divides by 100; otherwise returns NaN

The sensor polls every 15 seconds.

### Service diagnostics

The module exposes four service attributes for monitoring the sensor configuration:

- **Slave Address** -- current Modbus slave address (H:0)
- **Baud Rate** -- current communication speed, displayed as the actual baud rate value (e.g. 9600, not the register enum)
- **Unit** -- currently configured measurement unit (e.g. "m", "cm", "MPa")
- **Decimal Points** -- current decimal point format (e.g. "###.#")

A service action **Rewrite Slave Address** allows changing the sensor's Modbus address (valid Modbus range 1–247) directly from TapHome without external tools. The action writes the new address and automatically saves it to the sensor's user area.

### Additional capabilities

The sensor also exposes registers for range zero point (H:5) and full scale point (H:6) calibration references, a zero-bit offset register (H:12) for fine-tuning the measurement output, a 4-byte IEEE 754 floating point measurement output (H:22-23), and serial parity configuration (H:37). A factory reset command (H:16) can restore all parameters to factory defaults. These can be added in a future template update.

> [!TIP]
> If higher precision is needed, the floating point measurement at registers H:22-23 provides the same reading in IEEE 754 format (big-endian ABCD byte order) without the integer rounding of H:4.

## Troubleshooting

### Sensor returns NaN

1. Check register H:2 (Unit) -- the template only supports unit 16 (m) and 17 (cm). All other units will return NaN
2. Use the **Unit** service attribute in TapHome to verify the current setting
3. If the unit is incorrect, use a Modbus tool to write the correct value to H:2, then write 0 to H:15 to save

### No communication

1. Verify RS-485 wiring: A+ to A+, B- to B-, and common GND
2. Check that the baud rate matches between the sensor and TapHome (default: 9600, N, 8, 1)
3. Confirm the correct Slave ID was entered during template import
4. Verify the IP address points to the correct Modbus to LAN converter
5. If wires are swapped (A+/B-), reverse them -- some sensors label pins differently

### Incorrect readings

1. Verify the decimal point setting (H:3) matches the sensor's factory configuration
2. Check the unit setting (H:2) -- cm mode (17) divides by an additional factor of 100
3. For submersible sensors, ensure the probe is fully submerged and the cable is not kinked

## Available devices 1

These devices appear in TapHome after import.

Liquid Level Sensor Module

Service Attributes

|                |
|----------------|
| Slave Address  |
| Baud Rate      |
| Unit           |
| Decimal Points |

Service Actions

|                       |
|-----------------------|
| Rewrite Slave Address |

Service Attributes

Slave Address

```taphome
modbusr(H, 0, int16);
```

Baud Rate

```taphome
SWITCH(modbusr(H, 1, int16),
	0, 1200,
	1, 2400,
	2, 4800,
	3, 9600,
	4, 19200,
	5, 38400,
	6, 57600,
	7, 115200,
      NaN
);
```

Unit

```taphome
switch(modbusr(H, 2, int16),
	0, "MPa",
	1, "KPa",
	2, "Pa",
	3, "bar",
	4, "mbar",
	5, "Kgcm2",
	6, "PSI",
	7, "mH2O",
	8, "mmH2O",
	9, "inH2O",
	10, "H2O",
	11, "mHg",
	12, "mmHg",
	13, "inHg",
	14, "atm",
	15, "Torr",
	16, "m",
	17, "cm",
	18, "mm",
	19, "Kg",
	20, "°C",
	21, "PH",
	22, "°F",
	NaN
);
```

Decimal points

```taphome
SWITCH(modbusr(H, 3, int16),
	0, "####",
	1, "###.#",
	2, "##.##",
	3, "#.###",	
	4, "#.###",
	NaN
);
```

Service Actions

Rewrite the Slave Address

Parameters: Slave Address (1–255 SlaveAddr)

```taphome
modbusw(SH, 0, int16, SlaveAddr);
modbusw(SH, 15, int16, 0);  # Save to user area
```

Water Level Variable Read-only

Liquid level measurement in meters or centimeters — reads the hydrostatic pressure sensor output with configurable decimal precision

Register: H:4 Int16 Unit: dynamic numeric

Read

```taphome
VAR val := MODBUSR(H, 4, Int16)/power(10, modbusr(H, 3, int16));

switch(modbusr(H, 2, int16),
	16, val,
	17, val / 100, 
	NaN
);
```

**Connection:** Modbus RTU • 9600 baud• 8N1 • Slave ID: $\[SlaveId]

Possible improvements (6)

- H:5 Range Zero Point — Int16, transmitter range zero point — factory calibration reference
- H:6 Range Full Point — Int16, transmitter range full scale point — factory calibration reference
- H:12 Zero Bit Offset — Int16 (R/W via 0x06), zero-bit offset value — pressure output = calibration + offset. Factory default 0
- H:22 Floating Point Measurement — 4-byte float (IEEE 754, big-endian ABCD), 2 registers starting at 0x0016 — same measurement as H:4 but in float format
- H:37 Serial Check Bit — Int16 (R/W via 0x06); enum: 0=None, 1=Odd, 2=Even — serial parity configuration
- H:16 Restore Factory Parameters — Write 1 to 0x0010 to restore factory defaults — resets address, baud rate, and calibration. Requires re-searching for transmitter

## Import parameters

Enter these values when you import the XML.

| Asked in the app | Default       |
|------------------|---------------|
| Slave Id         | `1`           |
| IP address       | `192.168.1.0` |

## Sources

- Modbus RTU communication protocol documentation for pressure and level transmitter

## Related Documentation

- [Modbus Integration](https://taphome.com/en/compatibility/modbus-guide/)
- [Modbus](https://taphome.com/en/docs/integration/modbus/)
- [Simple configuration using templates](https://taphome.com/en/docs/integration/modbus/templates/)
- [Modbus scripts and prefetch](https://taphome.com/en/docs/script/modbus-scripts/)
- [Modbus functions](https://taphome.com/en/docs/script/modbus/)
- [Modbus data types](https://taphome.com/en/docs/script/modbus-data-types/)