HDS 湿度检测传感器驱动 - MicroPython版本

目录

• 简介
• 主要功能
• 硬件要求
• 软件环境
• 文件结构
• 文件说明
• 快速开始
• 主要 API
• 寄存器与单位
• 注意事项
• 版本记录
• 联系方式
• 许可协议

简介

本项目为敏源 HDS（Humidity Detection Sensor）湿度检测传感器提供 MicroPython 驱动。驱动通过 UART Modbus-RTU 读取温度、两路电容、计数值、频率及设备信息，适用于滚刷、拖布、地毯等吸水材料的干湿状态检测。

HDS 使用电容变化表征材料含水变化，其结果不是环境相对湿度 %RH。如需输出干湿状态或分档结果，应在实际机械结构、材料和温度条件下采集样本并建立阈值。

主要功能

• 支持 UART Modbus-RTU 通信，默认地址为 0x01。
• 内置独立命名的 hds_umodbus 通信库，避免与其他驱动包互相覆盖。
• 支持读取温度、C1/C2 电容及全部实时测量寄存器。
• 支持读取设备地址、平均次数、ID 和软硬件版本。
• 支持设置平均次数、修改设备地址及触发校准命令。
• 支持超时与 CRC 异常分类，读取失败默认重试 2 次。
• 使用外部 Modbus 主机依赖注入，驱动内部不创建 UART。
• 提供 RP2040 GP16/GP17 的完整运行示例。

硬件要求

推荐测试硬件

• Raspberry Pi Pico 或其他 RP2040 开发板
• 敏源 HDS 湿度检测传感器
• USB 数据线
• 杜邦线或可靠的焊接连接
• 可选：3.3 V UART 逻辑分析仪，用于排查通信问题

引脚说明

RP2040 GPIO 不耐受 5 V。若 HDS 使用 5 V 供电，应确认其 UART TX 输出电平，并在 HDS TX 与 GP17 之间使用合适的电平转换。

软件环境

文件结构

hds_driver/
├── code/
│   ├── hds.py
│   ├── main.py
│   └── hds_umodbus/
│       ├── __init__.py
│       ├── common.py
│       ├── const.py
│       ├── functions.py
│       ├── modbus.py
│       ├── serial.py
│       ├── tcp.py
│       ├── typing.py
│       └── version.py
├── package.json
├── README.md
└── LICENSE

文件说明

快速开始

1. 安装 MicroPython 固件

为 Raspberry Pi Pico 安装 MicroPython v1.23.0 或兼容版本，并确认开发工具可以访问开发板文件系统。

2. 复制文件

使用 Thonny、MicroPico 或 mpremote，将以下内容复制到开发板文件系统根目录：

/
├── hds.py
├── main.py
└── hds_umodbus/
    ├── __init__.py
    ├── common.py
    ├── const.py
    ├── functions.py
    ├── modbus.py
    ├── serial.py
    ├── tcp.py
    ├── typing.py
    └── version.py

使用 package.json 安装时会安装 hds.py 和 hds_umodbus。独立命名可避免安装其他 Modbus 驱动时覆盖本驱动依赖。测试文件 code/main.py 不在安装映射中，如需开机运行示例，应单独上传为开发板根目录的 main.py。

3. 完成接线

按照“硬件要求”中的引脚表连接 HDS，重点确认：

• HDS TX 连接 GP17。
• HDS RX 连接 GP16。
• Pico 与 HDS 必须共地。
• 推荐使用 3.3 V 为 HDS 供电。

4. 最小运行示例

from machine import Pin
from hds_umodbus.serial import Serial as ModbusRTUMaster
from hds import HDS

modbus = ModbusRTUMaster(
    uart_id=0,
    baudrate=9600,
    data_bits=8,
    stop_bits=1,
    parity=None,
    pins=(Pin(16), Pin(17)),
)

sensor = HDS(
    host=modbus,
    address=0x01,
    retries=2,
    retry_delay_ms=50,
)

print(sensor.read_basic_measurements())

5. 运行结果

code/main.py 每秒读取一次数据，典型输出如下：

FreakStudio: HDS Humidity Detection Sensor Initialization
Device: {'address': 1, 'averaging': 10, 'humidity_level_raw': 0, 'id': 0, 'software_version': None, 'hardware_version': None}
T=26.7 C, C1=7.929 pF, C2=51.282 pF

按 Ctrl+C 可停止程序并释放驱动和 UART 资源。

主要 API

初始化

sensor = HDS(
    host=modbus,
    address=0x01,
    retries=2,
    retry_delay_ms=50,
    debug=False,
)

公共方法

寄存器与单位

注意事项

版本记录

联系方式

• 作者：December
• 邮箱：149050476+Gypsyold@users.noreply.github.com
• GitHub：Gypsyold

许可协议

MIT License

Copyright (c) 2026 December

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.