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: 复制模板

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

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

步骤 2: 修改配置

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

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

# 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：

# 修改状态码解析
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：

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 目录：

/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_OTA`	OTA 升级服务器地址	天津安信华瑞 OTA	✅
`PROJECT_NAME`	项目名称	tuoan_demo_shenzhen	✅
`PROJECT_VERSION`	项目版本	2026.3.26 tuoan-dingzhi	✅
`REPORT_INTERVAL_SEC`	上报频率 (秒)	60	✅

硬件配置

参数	说明	默认值	按需修改
`MODBUS_UART`	UART 端口号	2	根据硬件
`MODBUS_BAUDRATE`	Modbus 波特率	9600	根据传感器
`LED_NET_PIN`	网络 LED 引脚	36	根据硬件
`LED_MODBUS_PIN`	Modbus LED 引脚	44	根据硬件

传感器配置

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

常见定制场景

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

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

场景 2: 修改平台地址

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

场景 3: 修改波特率为 19200

# config/config.py
MODBUS_BAUDRATE = 19200

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

# config/config.py
SENSOR_MAX_COUNT = 8

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

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

场景 6: 修改数据格式

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

# 原格式
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
    }
    # ...
}

项目结构

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.py`	Modbus 协议	⚠️ 协议不变不改
`sensor_device.py`	传感器管理	✅ 根据传感器修改
`data_reporter.py`	数据上报	✅ 根据平台修改

辅助模块

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

数据格式

默认上报格式

{
  "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. 启用调试输出

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

2. 测试 Modbus 通信

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

3. 测试网络

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. 测试上报

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.0	2026-03-28	初始版本，气体监测设备框架