Labs / Electronic modules / Water Flow Bubble Detector MWFD

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 transportation, detecting air bubbles or flow interruptions inside pipes is a crucial step in ensuring the safe and stable operation of equipment. Traditional contact-based air bubble detection solutions are not only prone to contamination and corrosion by liquids but also subject to misjudgment due to factors such as differences in liquid conductivity and pipe wall thickness, which can affect the normal operation of the equipment.

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

The MWFD Water Flow Bubble Detector is precisely a new generation of non-contact detection solution designed 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:

1. Module Introduction

The water flow bubble detector MWFD (Minyuan Water Flow Detector) measures the change in the dielectric constant of the liquid inside the tube through a high-frequency capacitive detection chip: different capacitance values reflect whether there is air or liquid inside the tube, and when air is detected, it outputs a high level for alarm. The sensor has strong penetration ability and can effectively overcome problems such as different water pipe materials, thick pipe walls, and differences in conductivity of different liquids. The sensor has a fast measurement response, with a maximum detection cycle of up to 20ms, and can distinguish the current state within 500ms when combined with the microprocessor algorithm. The built-in microprocessor chip can perform parameter calibration, temperature compensation, detection algorithms, alarm threshold configuration, etc.

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

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

2. Introduction to Main Chips

2.1 Chip Overview

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

2.2 Pin Definitions

Water Flow Bubble Detector MWFD

This diagram presents the dimensions, interface definitions, and wire sequence descriptions of 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 figure supplements the sensor spring dimensions and structural parameters, suitable for reference during model selection and mechanical coordination.

2.5 Reference Circuit

None.

2.6 Chip Configuration

None.

This module uses DIO high and low level outputs, and does not involve UART / I2C / SPI and other serial communication protocols. A high level output indicates the detection of a bubble or a liquid shortage alarm, while a low level output indicates that the liquid state is normal.

III. Circuit Engineering

3.1 Circuit Source Project

To obtain the circuit source project, please check the link below:

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

3.2 Module Usage Instructions

3.2.1 Module Test Environment Setup and Precautions

Pass the pipeline under test through the two spring electrodes of the module simultaneously. To ensure detection sensitivity, the following conditions 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 for the first time, replacing the pipeline/liquid, or detecting a deviation, no-load calibration must be performed to eliminate systematic 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 of the following section to enter the normal usage mode.

When using, you also need to note:

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 general-purpose Modbus master station debugging tool that is compatible with all capacitive sensors in this series that support the Modbus-RTU protocol. It can quickly achieve serial communication debugging between sensors and computers, real-time data reading, and log export, and is a general-purpose upper computer tool for verifying sensor functions and collecting test data. The software supports Modbus RTU/ASCII/TCP/IP protocols, is compatible with various register types and data formats, and its operation process is universal for all sensors in the series.

Before use, you need to complete the software installation and activation first. You can download the installation package through official channels. When opening it for the first time, you can try it for 30 days, or you can enter the registration code to activate it permanently. After connecting the sensor to the computer via hardware, open the software and click "Connection" - "Connect". In the pop-up window, configure the serial port parameters (Port Number, Baud Rate, Data Bits / Parity Bits / Stop Bits; sensors in this series default to 9600 Baud, 8N1 format, with the specific details subject to the corresponding model specification). After confirmation, you can establish a communication connection.

Water Flow Bubble Detector MWFD

The following is a description of the general operating procedure:

  1. Serial Connection Configuration: After connecting the sensor to the computer via a USB-to-serial module, open the Modbus Poll software, click on the menu bar "Connection" - "Connect", select the COM Port Number corresponding to the sensor in the pop-up window, and configure the serial port parameters that match the sensor (Baud Rate, Data Bits, Parity, Stop Bits; sensors in this series default to 9600 Baud, 8N1 format). After confirmation, the communication connection can be established.
  2. Import Sensor Configuration File: The software supports importing the corresponding .mbp pre-configured files for each sensor model. The register address, data format, and alias definition have been pre-set in the file, eliminating the need for manual register configuration. Simply open the corresponding sensor's .mbp file in the software, and all parameters will be automatically loaded. After a successful connection, the real-time detection data of the sensor (such as dust/rain/frost thickness values, status flags, etc.) will be directly displayed.
  3. Data Logging (Optional): If you need to save test data, you can configure logging rules through the "Setup" - "Excel Log" function, which supports logging data at fixed intervals or every time data is updated, and allows you to set an upper limit on the number of records, facilitating subsequent analysis and verification of sensor data.

The above are the general basic operations of the host computer. For the pre-configured files, specific register definitions, and special configuration details of the .mbp 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 bubble detector MWFD uses the DIO interface to communicate with the master.

Here, we first use the HY2.0-4P connection cable to connect the module through 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 Pin

Description

Pin 16

MTX

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

GND

GND

Ground Wire

VCC

VCC

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

The water flow bubble detector MWFD requires 3.3V power supply

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

This figure demonstrates the operation process of searching for the MWFD driver package in uPyPI.

Enter mwfd_driver to search, and the display is as follows:

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 figure shows the copy interface for the MWFD driver installation command, facilitating quick local installation.

Import module driver library code via mip tool, the following are the usage instructions for mpremote tool:

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

After importing the MWFD-MicroPython driver code for the water flow bubble detector, 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 shows the interrupt and polling output effects of the MWFD example program, allowing for intuitive observation of state change feedback.

4. Driver

mwfd_driver.zip 4 KB

None

6. Change History

Document Version

Modification Date

Modifier

Modified 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, 3.2.2 Usage of Modbus Poll

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