QuecPython Modbus IoT 设备技能#

技能说明#

技能名称: quecpython-modbus-iot

版本: 1.0.0

作者: 天津安信华瑞科技有限公司

描述: 基于移远 QuecPython 平台的 Modbus IoT 设备通用框架，支持传感器数据采集、4G 网络传输、云平台对接、OTA 升级等功能。

---

触发条件#

当用户提到以下需求时激活此技能：

• 需要在 QuecPython 设备上开发 Modbus 数据采集程序
• 需要将传感器数据上报到云平台
• 需要定制 IoT 设备的通信协议
• 需要修改设备上报频率、平台地址等配置
• 需要基于现有框架开发新的 IoT 应用
• 提到移远模组、QuecPython、EC200U、EC600N 等关键词

---

核心功能#

1. 数据采集#

• Modbus RTU 协议实现
• 支持 32 个传感器设备
• 自动扫描在线传感器
• 状态数据 + 浓度数据读取

2. 网络通信#

• 4G LTE 网络连接
• 自动重连机制
• 信号强度监测
• NTP 时间同步

3. 数据上报#

• HTTP/HTTPS 协议
• JSON 格式数据
• 失败自动重试
• 基于 IMEI 的错时上报

4. 系统管理#

• 硬件看门狗保护
• 电源状态监测
• LED 状态指示
• OTA 远程固件升级

---

使用流程#

步骤 1: 复制模板#

将技能模板复制到用户项目目录：

bash

# 从技能模板创建新项目
cp -r ~/.easyclaw/skills/quecpython-modbus-iot/template/ ~/projects/your-project/

步骤 2: 修改配置#

编辑 config/config.py 文件，修改以下关键参数：

python

# ========== 必须修改的配置 ==========

# 1. 数据上报平台地址
URL_REPORT = "https://your-platform.com/api/data"  # 客户平台地址
URL_OTA = "https://your-ota-server.com/ota"         # OTA 服务器地址

# 2. 设备信息
PROJECT_NAME = "your-project-name"                  # 项目名称
PROJECT_VERSION = "1.0.0"                           # 版本号
MANUFACTURER_NAME = "Your Company Name"             # 厂商名称
MANUFACTURER_ID = "your-contact-phone"              # 联系电话

# 3. 上报频率 (秒)
REPORT_INTERVAL_SEC = 60  # 60 秒 = 1 分钟，可根据需求调整

# ========== 根据硬件修改的配置 ==========

# 4. Modbus 通信参数
MODBUS_UART = 2              # UART 端口 (1/2/3)
MODBUS_BAUDRATE = 9600       # 波特率 (根据传感器调整)

# 5. LED 引脚
LED_NET_PIN = 36             # 网络指示灯 GPIO
LED_MODBUS_PIN = 44          # Modbus 指示灯 GPIO

# ========== 可选修改的配置 ==========

# 6. 传感器配置
SENSOR_MAX_COUNT = 32        # 最大传感器数量 (1-32)
SENSOR_BASE_ADDR = 1000      # 浓度数据起始地址
SENSOR_STAT_ADDR = 2000      # 状态数据起始地址

# 7. 重试次数
MODBUS_RETRY_MAX = 5         # Modbus 重试次数
HTTP_RETRY_MAX = 2           # HTTP 重试次数

步骤 3: 定制传感器协议 (如需要)#

如果传感器协议与默认不同，修改 src/sensor_device.py：

python

# 修改状态码解析
def read_status(self):
    result = self.modbus.read_registers(1, 2000 + self.addr, 1)
    status_value = result['data'][0]

    # 根据你的传感器协议修改状态码
    if status_value == 0:
        # 正常
        pass
    elif status_value == 1:
        # 你的自定义状态
        self.level_1_alarm = 1
    # ... 更多状态

步骤 4: 定制数据格式 (如需要)#

如果平台数据格式不同，修改 src/data_reporter.py：

python

def report_sensor_data(self, net_info, sensor_stat, sensor_dens, sys_stat):
    # 修改数据格式
    body = {
        # 根据你的平台协议修改字段
        'device_id': net_info.get('IMEI', ''),
        'timestamp': utime.time(),
        'sensors': sensor_stat,
        # ...
    }

步骤 5: 部署到设备#

将以下 8 个文件复制到 QuecPython 设备的 /usr 目录：

text

/usr/
├── config.py              ← 从 config/config.py 复制
├── main.py                ← 从 src/main.py 复制
├── led_control.py         ← 从 src/led_control.py 复制
├── modbus_rtu.py          ← 从 src/modbus_rtu.py 复制
├── sensor_device.py       ← 从 src/sensor_device.py 复制
├── network_manager.py     ← 从 src/network_manager.py 复制
├── system_manager.py      ← 从 src/system_manager.py 复制
└── data_reporter.py       ← 从 src/data_reporter.py 复制

---

配置参数说明#

核心配置#

参数说明默认值必须修改URL_REPORT数据上报平台地址天津安信华瑞平台✅URL_OTAOTA 升级服务器地址天津安信华瑞 OTA✅PROJECT_NAME项目名称tuoan_demo_shenzhen✅PROJECT_VERSION项目版本2026.3.26 tuoan-dingzhi✅REPORT_INTERVAL_SEC上报频率 (秒)60✅

硬件配置#

参数说明默认值按需修改MODBUS_UARTUART 端口号2根据硬件MODBUS_BAUDRATEModbus 波特率9600根据传感器LED_NET_PIN网络 LED 引脚36根据硬件LED_MODBUS_PINModbus LED 引脚44根据硬件

传感器配置#

参数说明默认值按需修改SENSOR_MAX_COUNT最大传感器数32根据实际SENSOR_BASE_ADDR浓度数据起始地址1000根据协议SENSOR_STAT_ADDR状态数据起始地址2000根据协议

---

常见定制场景#

场景 1: 修改上报频率为 5 分钟#

python

# config/config.py
REPORT_INTERVAL_SEC = 300  # 300 秒 = 5 分钟

场景 2: 修改平台地址#

python

# config/config.py
URL_REPORT = "https://api.mycompany.com/iot/data"
URL_OTA = "https://ota.mycompany.com/firmware"

场景 3: 修改波特率为 19200#

python

# config/config.py
MODBUS_BAUDRATE = 19200

场景 4: 只使用 8 个传感器#

python

# config/config.py
SENSOR_MAX_COUNT = 8

场景 5: 关闭调试输出 (生产环境)#

python

# config/config.py
DEBUG_ENABLE = False
DEBUG_MODBUS = False
DEBUG_NETWORK = False
DEBUG_HTTP = False

场景 6: 修改数据格式#

在 src/data_reporter.py 中修改 report_sensor_data() 方法：

python

# 原格式
body = {
    'id': timestamp,
    'time': time_str,
    'unit_code': net_info.get('IMEI', ''),
    # ...
}

# 修改为新格式
body = {
    'deviceId': net_info.get('IMEI', ''),
    'timestamp': timestamp,
    'data': {
        'sensors': sensor_stat,
        'densities': sensor_dens
    }
    # ...
}

---

项目结构#

text

quecpython-modbus-iot/
├── SKILL.md                 # 技能说明 (本文件)
├── README.md                # 技能介绍
├── template/                # 项目模板
│   ├── config/             # 配置文件
│   │   ├── __init__.py
│   │   └── config.py       # ⚙️ 主配置
│   ├── src/                # 源代码
│   │   ├── main.py         # 🚀 主程序
│   │   ├── led_control.py  # 💡 LED 控制
│   │   ├── modbus_rtu.py   # 🔌 Modbus 协议
│   │   ├── sensor_device.py# 📡 传感器管理
│   │   ├── network_manager.py # 🌐 网络管理
│   │   ├── system_manager.py  # 🖥️ 系统管理
│   │   └── data_reporter.py   # 📤 数据上报
│   └── docs/               # 文档
│       ├── README.md       # 项目说明
│       ├── 部署指南.md
│       ├── 配置说明.md
│       └── 调试指南.md
└── examples/               # 示例配置
    ├── example-gas/        # 气体监测示例
    ├── example-temp/       # 温湿度监测示例
    └── example-water/      # 水质监测示例

---

模块说明#

核心模块#

模块功能是否可修改config.py配置参数✅ 必须修改main.py主程序逻辑⚠️ 一般不改modbus_rtu.pyModbus 协议⚠️ 协议不变不改sensor_device.py传感器管理✅ 根据传感器修改data_reporter.py数据上报✅ 根据平台修改

辅助模块#

模块功能是否可修改led_control.pyLED 控制❌ 无需修改network_manager.py网络管理❌ 无需修改system_manager.py系统管理❌ 无需修改

---

数据格式#

默认上报格式#

json

{
  "id": 1711600000,
  "time": "2026-03-28 09:00:00",
  "unit_code": "863950067267346",
  "sys_stat": {
    "main_power_fail": 0,
    "back_power_fail": 0,
    "has_alarm": 0,
    "has_fail": 0
  },
  "sensor_stat": [
    {
      "sensor_index": 1,
      "sensor_addr": 0,
      "level_1_alarm": 0,
      "level_2_alarm": 0,
      "com_error": 0,
      "sensor_fail": 0
    }
  ],
  "sensor_dens": [
    {
      "sensor_index": 1,
      "sensor_addr": 0,
      "sensor_dense": 15
    }
  ],
  "collections": {
    "IMEI": "863950067267346",
    "signal_power": 20,
    "error_code": 0,
    "gas_sensor_state": 0
  }
}

---

调试方法#

1. 启用调试输出#

python

# config/config.py
DEBUG_ENABLE = True
DEBUG_MODBUS = True
DEBUG_NETWORK = True
DEBUG_HTTP = True

2. 测试 Modbus 通信#

python

from modbus_rtu import ModbusRTU
modbus = ModbusRTU(2, 9600, 8, 0, 1, 0)
result = modbus.read_registers(1, 0, 1)
print("电池状态:", result)

3. 测试网络#

python

from network_manager import NetworkManager
net = NetworkManager("test", "1.0")
if net.wait_connected(30):
    info = net.get_network_info()
    print("IMEI:", info['IMEI'])
    print("信号:", info['signal_power'])

4. 测试上报#

python

from data_reporter import DataReporter
from led_control import LED
led = LED(36)
reporter = DataReporter(URL_REPORT, URL_OTA, led)
test_data = '{"test": 1}'
result = reporter.post(test_data, URL_REPORT)
print("上报结果:", result)

---

常见问题#

Q: 如何修改上报频率？#

A: 修改 config.py 中的 REPORT_INTERVAL_SEC 参数

Q: 如何更换平台地址？#

A: 修改 config.py 中的 URL_REPORT 和 URL_OTA

Q: 传感器读取失败？#

A: 检查 MODBUS_BAUDRATE 是否与传感器一致，检查 RS485 接线

Q: 网络连不上？#

A: 检查 SIM 卡、天线，查看信号强度 net.csqQueryPoll()

Q: 如何添加新传感器类型？#

A: 修改 sensor_device.py 中的状态解析逻辑

---

技术支持#

• 技能作者: 天津安信华瑞科技有限公司
• 联系电话: 18513099902
• 适用平台: 移远 QuecPython (EC200U/EC600N 等)

---

版本历史#

版本日期说明1.0.02026-03-28初始版本，气体监测设备框架

---

许可证#

Copyright © 2026 天津安信华瑞科技有限公司

---

使用此技能前，请确保你有 QuecPython 开发环境和兼容的硬件设备。