Contents
- Introduction
- 1. Module Introduction
- 2. Introduction to Main Chips
- 2.1 Chip Overview
- 2.2 Pin Definitions
- 2.3 Functional Block Diagram
- 2.4 Performance Parameters
- 2.5 Reference Circuit
- 2.6 Chip Configuration
- 2.7 Communication Interfaces and Related Protocols
- III. Circuit Engineering
- 3.1 Circuit Source Project
- 3.2 Module Usage Instructions
- 3.3 Application Experiment
- 4. Driver
- 5. BOM & Recommended Alternatives
- 6. Change History
- VII. Related Materials
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:
- Prone to Contamination and Corrosion : The electrodes need to be in direct contact with the liquid, and long-term use will result in contamination by scale and impurities or corrosion by corrosive liquids, leading to detection failure;
- Greatly affected by liquid and pipeline: Differences in liquid conductivity, changes in pipe wall material and thickness will all affect the detection results, with a high Error Rate;
- Multiple installation restrictions: Installation of electrodes requires drilling holes in the pipeline, which damages the pipeline integrity, and has poor adaptability, making it difficult to be compatible with pipelines of different diameters;
- Slow response speed: Unable to quickly identify bubbles, difficult to trigger flow interruption protection in a timely manner, posing potential safety hazards.
The MWFD Water Flow Bubble Detector is precisely a new generation of non-contact detection solution designed to address these pain points.

Core Advantages of MWFD - Precise, Fast, and Non-contact Bubble Detection:
- ✅ Non-contact detection, completely eliminating contamination and corrosion:MWFD uses high-frequency capacitive detection technology, eliminating the need for direct contact with the liquid inside the pipeline, thus fundamentally avoiding the issues of electrode contamination and corrosion; the detector can penetrate non-metallic pipe walls such as plastic and silicone for detection, without the need to damage the pipeline structure, making installation convenient and adaptable to pipelines of different materials.
- ✅ Strong penetration + high anti-interference, capable of stable output even in complex scenarios: The sensor has strong penetration, effectively overcoming issues such as different water pipe materials, thick pipe walls, and differences in liquid conductivity; with built-in microprocessor and intelligent algorithms, it supports parameter calibration, temperature compensation, and alarm threshold configuration, effectively filtering out environmental interference, stably distinguishing air and liquid in the pipeline, and remaining unaffected by water quality and liquid composition.
- ✅ Ultra-fast response speed, real-time protection of device safety: The measurement response speed can reach up to 20ms per detection cycle. Combined with the microprocessor algorithm, it can quickly distinguish the state inside the pipeline within 500ms. When air/bubbles are detected, it can output a high-level alarm signal, promptly trigger flow cutoff protection, avoid risks such as dry burning and idling of the device, and ensure the safe operation of the device.
- ✅ Multi-pipe diameter adaptation + easy integration, suitable for various scenarios: The detector offers multiple spring inner diameter specifications, adaptable to pipes with different diameters ranging from 3.5mm to 12.5mm; the module has a compact structure, is easy to install, and supports quick integration into various fluid delivery equipment, making it an ideal bubble detection solution for water dispensers, coffee machines, medical devices, and industrial fluid systems.
can be used for:
- Small Appliance Scenarios: Flow Interruption / Bubble Protection for Water Dispensers / Coffee Makers: In devices such as water dispensers and coffee makers, MWFD can be installed on the water delivery pipeline to detect bubbles and flow interruption in the water flow in real time. When bubbles or flow interruption occur in the pipeline, the detector can quickly identify and output a signal, triggering the device's anti-dry-burning protection to prevent damage to the heating tube caused by idling without water; the non-contact design is not contaminated by scale and can maintain stable detection performance even after long-term use, providing reliable safety protection for the device.
- Medical device scenario: Bubble monitoring for infusion/fluid delivery: In medical infusion devices, MWFD can be installed on the infusion line to non-contact detect bubbles inside the pipeline, preventing bubbles from entering the human body and causing safety hazards; the detector is compatible with infusion tubes of different diameters, does not come into contact with the medicinal solution, will not contaminate the medicinal solution, and its fast response speed can promptly identify bubbles, providing assurance for the safe operation of medical devices.
- Industrial Fluid Scenario: Continuous Monitoring of Pipeline Fluid: In industrial fluid transportation systems, MWFD can be used to detect flow interruption and bubble conditions inside pipelines, preventing issues such as pump idling and pipeline blockage; the detector is not affected by liquid conductivity or impurities and can operate stably in complex industrial environments, providing reliable data support for the automated control and safety monitoring of fluid systems.
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.



This figure shows the product introduction, module appearance, and main application scenarios of MWFD.
- By detecting the change in the dielectric constant inside the tube through high-frequency capacitance, it distinguishes between the air and liquid states;
- Outputs a high-level alarm when air, bubbles, or liquid deficiency is detected;
- Strong penetration, adaptable to scenarios with different pipe materials, thicker pipe walls, and different liquid conductivities;
- Suitable for scenarios such as water purifiers, coffee machines, milk tea machines, infusion lines, and water pump liquid extraction.
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

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


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.
2.7 Communication Interfaces and Related Protocols
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:
- The inner diameter of the spring should match the outer diameter of the pipeline as much as possible to avoid an excessive gap between them, as an excessive gap will reduce the detection accuracy.
- Spring electrodes should not directly contact conductive objects such as desktops and metals to prevent introducing interference
- During installation, avoid relative displacement between the pipeline and the spring to reduce detection fluctuations caused by mechanical vibration

The module supports connections for two usage scenarios:
- Development Board Debugging: Connect MWFD to the 3-pin socket of the
MCSK-MWFDcalibration development board. The development board is connected to the PC via USB for calibration and data debugging - Master Control Integration: The module can be directly connected to the user's master control IO port, and the detection status can be determined by outputting the level. Core interface definitions:
| Pin | Function description |
|---|---|
| OUT | Signal output: low level = liquid present (normal), high level = bubble / no liquid |
| VCC/GND | Power 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:



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:
- Interference source protection: When a human body or a metal object touches or approaches within 1 cm of the sensor, it will interfere with the capacitance detection, leading to misjudgment. Sufficient interference-free space must be reserved during installation.
- Calibration and Maintenance:When replacing pipelines, liquid types, or when there are significant changes in the detection environment (temperature, humidity), it is necessary to re-perform no-load calibration to ensure detection accuracy.
- Installation Stability: The spring and pipeline must maintain a close fit to prevent loosening and displacement during long-term use, which could affect detection sensitivity.
- Environmental Adaptation: Avoid using the module in high-temperature and strong electromagnetic interference environments to prevent the high-frequency detection signal from being affected, which may lead to abnormal detection.
Troubleshooting Common Issues:
| Symptom | Troubleshooting steps |
|---|---|
| Unstable detection results / false detections | 1. 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 signal | 1. 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 detection | 1. 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.

The following is a description of the general operating procedure:
- 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.
- Import Sensor Configuration File: The software supports importing the corresponding
.mbppre-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.mbpfile 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. - 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 |
|
|
GND |
| Ground Wire |
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:

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:

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.0After 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:

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
5. BOM & Recommended Alternatives
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 |
VII. Related Materials
MWFD Water Flow Bubble Detector Product Manual-MinYuan202603.pdf 564 KB