Labs / Electronic modules

Water Flow Bubble Detector MWFD

Author: Li Zisheng · Source: FreakStudio open documentation, v1.2 · License: CC BY 4.0 · Driver code (sensors/mwfd_driver): MIT License

Contents

Introduction

In scenarios such as water dispensers, coffee machines, medical infusion, and industrial fluid delivery, the detection of bubbles or flow interruption in pipelines is a key link to ensuring the safe and stable operation of equipment. Traditional contact bubble detection solutions are not only prone to liquid contamination and corrosion, but also prone to misjudgment due to factors such as differences in liquid conductivity and pipe wall thickness, which affects the normal operation of equipment.

Traditional contact-based bubble detection solutions have long faced inherent industry challenges that are difficult to overcome:

The MWFD water flow bubble detector is a new generation of non-contact detection solution designed specifically to address these pain points.

Water Flow Bubble Detector MWFD

Core Advantages of MWFD: Precise, Fast, and Non-Contact Bubble Detection

Can be used for:

I. Module Introduction

The MWFD (Minyuan Water Flow Detector), a water flow and air bubble detector, measures changes in the dielectric constant of the liquid inside the pipe via a high-frequency capacitance detection chip: different capacitance values indicate whether the pipe contains air or liquid, and it outputs a high level for alarm once air is detected. Featuring strong penetration, this sensor can effectively address issues such as varying water pipe materials, thick pipe walls, and differences in the conductivity of different liquids. It boasts a fast measurement response, with a maximum detection cycle of 20ms, and can identify the current state within 500ms in coordination with the microprocessor algorithm.The built-in microprocessor chip supports functions such as parameter calibration, temperature compensation, detection algorithm and alarm threshold configuration.

Water Flow Bubble Detector MWFD
Water Flow Bubble Detector MWFD
Water Flow Bubble Detector MWFD

This figure presents the product introduction, module appearance and main application scenarios of MWFD.

2. Introduction to Main Chips

2.1 Chip Overview

The module operates entirely based on the high-frequency capacitance detection principle, identifies water flow, air bubbles and liquid shortage states by measuring the change in the dielectric constant inside the tube, and outputs corresponding digital level signals.

2.2 Pin Definition

Water Flow Bubble Detector MWFD

This figure provides the dimensions, interface definitions and wire sequence description of the MWFD, which can be used for hardware integration design.

2.3 Functional Block Diagram

None.

2.4 Performance Parameters

Water Flow Bubble Detector MWFD
Water Flow Bubble Detector MWFD

This diagram supplements the dimensional and structural parameters of the sensor spring, serving as a suitable reference for model selection and mechanical mating.

2.5 Reference Circuit

None.

2.6 Chip Configuration

None.

This module adopts DIO high and low level output, and does not involve serial Communication Protocols such as UART / I2C / SPI. A high level output indicates a detected bubble or liquid shortage alarm, while a low level output indicates a normal liquid state.

III. Circuit Engineering

3.1 Circuit Source Engineering

To obtain the source project of the circuit, please refer to the link below:

https://mysentech.com/productinfo/2423155.html

3.2 Module Usage Instructions

3.2.1 Module Test Environment Setup and Notes

Pass the pipeline under test through both spring electrodes of the module simultaneously; to ensure detection sensitivity, the following requirements must be met:

Water Flow Bubble Detector MWFD

The module supports connections for two usage scenarios:

PinFunction description
OUTSignal output: low level = liquid present (normal), high level = bubble / no liquid
VCC/GNDPower and ground pins; must match the module's rated voltage

When using the device for the first time, replacing the pipeline/liquid, or detecting a deviation, it is necessary to perform no-load calibration to eliminate system errors. The steps are as follows:

Water Flow Bubble Detector MWFD
Water Flow Bubble Detector MWFD
Water Flow Bubble Detector MWFD

After completing the no-load calibration, refer to the content in the following section to enter the normal operation mode.

When using it, the following points should also be noted:

Troubleshooting Common Issues:

SymptomTroubleshooting steps
Unstable detection results / false detections1. Check how well the spring fits the tubing and eliminate any gap; 2. Confirm there is no metal or human-body interference around the sensor; 3. Perform no-load calibration again
No output signal1. Check that the power connection is normal; 2. Confirm the IO pin wiring is correct; 3. Restart the module and recalibrate
False bubble alarms during liquid detection1. Confirm there are no actual bubbles in the liquid; 2. Check whether the tubing is vibrating or shaking; 3. Recalibrate and optimize the installation position

3.2.2 Usage of Modbus Poll

Modbus Poll is a universal Modbus master debugging tool compatible with all capacitive sensors in this series that support the Modbus-RTU protocol. It enables quick serial communication debugging, real-time data reading and log export between sensors and computers, serving as a universal host computer tool for verifying sensor functions and collecting test data. The software supports Modbus RTU/ASCII/TCP/IP protocols, is compatible with multiple register types and data formats, and its operation process is universal for the entire series of sensors.

Before use, you need to complete the software installation and activation first. You can download the installation package through official channels; the first launch supports a 30-day trial, and you can also enter a registration code for permanent activation. After the hardware connects the sensor to the computer, open the software and click "Connection" - "Connect", then configure the serial port parameters (Port Number, baud rate, data bit/parity bit/stop bit; this series of sensors defaults to the 9600 Baud, 8N1 format, subject to the specification sheet of the corresponding specific model) in the pop-up window, and confirm to establish a communication connection.

Water Flow Bubble Detector MWFD

The following is a description of the general operation process:

  1. Serial Port Connection Configuration: After connecting the sensor to the computer via a USB-to-serial port module, launch the Modbus Poll software, click "Connection" - "Connect" on the menu bar, select the COM Port Number corresponding to the sensor in the pop-up window, and configure the serial port parameters matching the sensor (baud rate, data bits, parity check mode, stop bits; this series of sensors defaults to 9600 Baud, 8N1 format), then confirm to establish a communication connection.
  2. Import Sensor Configuration File: The software supports importing. mbp pre-configuration files corresponding to various sensor models. These files come with preset register addresses, data formats, and alias definitions, eliminating the need for manual register configuration. Simply open the. mbp file for the corresponding sensor in the software to automatically load all parameters. Once the connection is established, real-time detection data of the sensor (such as dust/rain/frost thickness values, status flag bits, etc.) will be displayed directly.
  3. Data Logging (Optional): If you need to save test data, you can configure logging rules via the "Setup" - "Excel Log" function. It supports logging data at fixed intervals or with every data update, and allows you to set a maximum number of log entries, facilitating subsequent analysis and verification of sensor data.

The above are the general basic operations of the host computer. For the. mbp preconfiguration files, specific register definitions and special configuration details of different sensor models, please refer to the content in "VII. Related Materials".

3.3 Application Experiment

Here, we use the GraftPort-RP2040 development board for testing, and the water flow bubble detector MWFD uses the DIO interface to communicate with the main controller.

Here, we first use the HY2.0-4P connection cable to connect the module via the PH2.0-3P to Grove adapter board to the GraftPort-RP2040 development board's DIO0 interface:

The module connections are shown in the following table:

Development Board Pins

Module Pins

Description

Pin 16

MTX

UART data transmission line, corresponding to the transmit pin of the development board

GND

GND

ground wire

VCC

VCC

Power cable, PH2.0-3P to Grove adapter board with 5V to 3.3V circuit,

The water flow bubble detector MWFD requires a 3.3V power supply

Here, we need to search for the relevant driver packages on uPyPI: https://upypi.net/zh/

This diagram demonstrates the procedure for searching for the MWFD driver package in uPyPI.

Enter mwfd_driver to search, and the following will be displayed:

Water Flow Bubble Detector MWFD

This figure shows the search results for mwfd_driver, which can be used to confirm the driver name.

Click to copy the local installation command:

Water Flow Bubble Detector MWFD

This diagram shows the copy interface of the MWFD driver installation command, which facilitates quick local installation.

Import the module driver library code via the mip tool. Below are the usage commands for the mpremote tool:

mpremote mip install https://upypi.net/pkgs/mwfd_driver/1.0.0

Import the MWFD-MicroPython driver code for the water flow bubble detector, then copy the following main.py code into our project:

# Python env   : MicroPython v1.23.0
# -*- coding: utf-8 -*-
# @Time    : 2026/4/3 2:30 PM
# @Author  : hogeiha
# @File    : main.py
# @Description : MWFD water flow bubble detector interrupt and polling example program

# ======================================== Import Modules =========================================
from machine import Pin
from mwfd import MWFD
import time

# ======================================== Global Variables ============================================

# ======================================== Functions ============================================
def on_state_change(state):
    """
    Interrupt callback function, triggered automatically when the sensor state changes
    Args:
        state (bool): True means bubble/no liquid, False means normal liquid

    Raises:
        None

    Notes:
        This function is called by the interrupt service routine and should be kept short and fast

    ==========================================
    Interrupt callback function, automatically triggered when sensor state changes
    Args:
        state (bool): True for bubble/lack of liquid, False for normal liquid

    Raises:
        None

    Notes:
        This function is called by interrupt service routine, keep it short and fast
    """
    # Print different messages according to the state
    if state:
        print("[Interrupt] Warning: Bubble or lack of liquid")
    else:
        print("[Interrupt] Normal liquid")

# ======================================== Custom Classes ============================================

# ======================================== Initialization configuration ===========================================
# Wait 3 seconds for the system to stabilize
time.sleep(3)
# Print the startup banner
print("FreakStudio: MWFD sensor demo started")

# Initialize sensor pin (GPIO15, input mode, internal pull-down)
sensor_pin = Pin(15, Pin.IN, Pin.PULL_DOWN)

# Create MWFD driver instance
sensor = MWFD(sensor_pin)

# Enable interrupt and bind the callback function
sensor.irq(callback=on_state_change)

# ========================================  Main Program  ============================================
# Main loop: actively poll the sensor state and print it
while True:
    # Read current state
    state = sensor.read()
    # Output message according to the state
    if state:
        print("[Polling] Warning: Bubble or lack of liquid")
    else:
        print("[Polling] Normal liquid")
    # Delay 200 ms
    time.sleep(0.2)

Burn the code, open the terminal, and the output is as follows:

Water Flow Bubble Detector MWFD

This figure demonstrates the interrupt and polling output effects of the MWFD sample program, through which the feedback of state changes can be visually observed.

4. Drivers

mwfd_driver.zip 4 KB

None

VI. Revision History

Document Version

Date of Modification

Modifier

Revised Content

v1.0

2026-04-24

Hou Junhan

Initialize Document

v1.1

2026-05-14

Li Zisheng

Modify the document.

v1.2

2026-05-20

Li Zisheng

Add introduction and the usage of 3.2.2 Modbus Poll

VII. Relevant Materials

MWFD Water Flow Bubble Detector Product Manual-MinYuan202603.pdf 564 KB