棋牌室分房控电系统 – 完整部署手册

一、核心依赖清单（必须安装）

依赖名称	版本号	作用	安装命令
Python	3.7+	程序运行基础环境	官网下载安装（https://www.python.org/）
pymodbus	2.5.3	Modbus TCP 控制继电器	pip install pymodbus==2.5.3
paho-mqtt	任意新版	MQTT 客户端（连接 EMQX 服务器）	pip install paho-mqt

备注：Python 建议装 3.8/3.9 版本（兼容性最好，避免新版 Python 的坑）

二、部署步骤（按顺序执行，5 分钟搞定）

步骤 1：安装 Python 环境

下载 Python 3.8+（https://www.python.org/downloads/），安装时勾选「Add Python to PATH」（关键！）

2. 验证安装：打开 CMD/PowerShell，输入 python –version，能显示版本号（如 Python 3.8.10）即可。

步骤 2：安装依赖库 打开 CMD/PowerShell，依次执行以下命令：

# 安装指定版本的pymodbus（解决slave参数兼容问题）
pip install pymodbus==2.5.3

# 安装MQTT客户端
pip install paho-mqtt

# 验证安装（可选）
pip list | findstr "pymodbus paho-mqtt"
# 能看到 pymodbus (2.5.3) 和 paho-mqtt 即安装成功

步骤 3：准备程序文件

1.在新电脑桌面新建文件夹 名称：（棋牌室控电 ）或者其它！

2. 把下面的程序保存为 relay_control.py，放到这个文件夹里：

# 棋牌室分房控电最终版（带重试+JSON解析+异常兜底）
from pymodbus.client.sync import ModbusTcpClient
import paho.mqtt.client as mqtt
import json
import time

# -------------------------- 配置区（仅改这里！） --------------------------
# EMQX 服务器配置（和原电脑一致）
EMQX_HOST = "43.137.8.230"    # EMQX公网IP
EMQX_USER = "wmjk"            # EMQX账号
EMQX_PWD = "88888888"         # EMQX密码
MQTT_TOPIC = "cashier/power/set/1"  # 订阅的MQTT主题

# 继电器模块配置（和原电脑一致）
RELAY_HOST = "192.168.0.7"    # 继电器模块内网IP
RELAY_PORT = 8234             # 继电器Modbus端口
RETRY_TIMES = 3               # 指令失败重试次数（不用改）
RETRY_INTERVAL = 1            # 重试间隔（秒，不用改）
# -------------------------------------------------------------------------

# 初始化Modbus客户端（带重连）
def init_modbus_client():
    client = ModbusTcpClient(RELAY_HOST, port=RELAY_PORT)
    for i in range(RETRY_TIMES):
        if client.connect():
            print("✅ Modbus 继电器模块连接成功！")
            return client
        print(f"⚠️ Modbus连接失败，第{i+1}次重试...")
        time.sleep(RETRY_INTERVAL)
    print("❌ Modbus连接失败（已重试3次），程序退出！")
    exit(1)

# 执行继电器控制（带重试）
def control_relay(modbus_client, coil_addr, power_state, slave_id=1):
    target_state = True if power_state.lower() == "on" else False
    action = "打开" if target_state else "关闭"
    for i in range(RETRY_TIMES):
        try:
            result = modbus_client.write_coil(coil_addr, target_state, slave=slave_id)
            if not result.isError():
                print(f"✅ {action}成功 → 线圈{coil_addr}（slave={slave_id}）")
                return True
            print(f"⚠️ 第{i+1}次重试：{action}线圈{coil_addr}失败 → {result}")
        except Exception as e:
            print(f"⚠️ 第{i+1}次重试：{action}线圈{coil_addr}异常 → {str(e)}")
        time.sleep(RETRY_INTERVAL)
    print(f"❌ {action}失败（已重试{RETRY_TIMES}次）→ 线圈{coil_addr}")
    return False

# MQTT连接回调
def on_connect(client, userdata, flags, rc):
    client.subscribe(MQTT_TOPIC)
    print(f"✅ MQTT连接成功！已订阅主题：{MQTT_TOPIC}")
    print("🔄 等待JSON控电指令...")

# MQTT消息处理（核心）
def on_message(client, userdata, msg):
    try:
        payload = msg.payload.decode('utf-8').strip()
        print(f"\n📥 收到指令：{payload}")
        # 解析JSON
        data = json.loads(payload)
        room_name = data.get("roomName", "未知房间")
        power = data.get("power", "").lower()
        slave_id = data.get("slaveId", 1)
        coil_addr = data.get("coil", 0)
        
        # 校验指令
        if power not in ["on", "off"]:
            print(f"⚠️ {room_name} → 无效指令：{power}（仅支持on/off）")
            return
        # 执行控制
        print(f"📌 控制{room_name} → {power.upper()}（线圈{coil_addr}）")
        control_relay(modbus_client, coil_addr, power, slave_id)
    except json.JSONDecodeError:
        print("❌ 指令不是合法JSON格式，忽略！")
    except Exception as e:
        print(f"❌ 指令处理异常：{str(e)}")

# 程序入口
if __name__ == "__main__":
    # 初始化Modbus
    modbus_client = init_modbus_client()
    # 初始化MQTT
    mqtt_client = mqtt.Client()
    mqtt_client.username_pw_set(EMQX_USER, EMQX_PWD)
    mqtt_client.on_connect = on_connect
    mqtt_client.on_message = on_message
    # 启动程序
    try:
        mqtt_client.connect(EMQX_HOST, 1883, 60)
        mqtt_client.loop_forever()
    except KeyboardInterrupt:
        print("\n🛑 程序手动终止！")
    except Exception as e:
        print(f"\n❌ MQTT运行异常：{str(e)}")
    finally:
        modbus_client.close()
        print("✅ Modbus连接已关闭！")

步骤 4：修改配置（仅改这 5 行！）

打开 relay_control.py，只修改「配置区」的 5 个参数（和你现在的电脑保持一致）：

EMQX_HOST = "43.137.8.230"    # 你的EMQX公网IP
EMQX_USER = "wmjk"            # EMQX账号
EMQX_PWD = "88888888"         # EMQX密码
RELAY_HOST = "192.168.0.7"    # 继电器模块内网IP
RELAY_PORT = 8234             # 继电器Modbus端口

步骤 5：启动程序

1.打开 CMD/PowerShell，切换到程序所在文件夹：

cd /d C:\Users\你的用户名\Desktop\棋牌室控电

2.启动程序：

python relay_control.py

3.看到以下日志即启动成功：

✅ Modbus 继电器模块连接成功！
✅ MQTT连接成功！已订阅主题：cashier/power/set/1
🔄 等待JSON控电指令...

三、必备文件清单（部署时需携带）

文件名称	作用	存放位置
relay_control.py	核心控电程序（带重试 + JSON 解析）	任意文件夹（建议桌面）
（可选）room_control.html	手机网页控制端	桌面（方便手机访问）

网页控制端（可选）：如果需要手机网页控制，把之前的 room_control.html 也复制过去，修改里面的 EMQX_HOST 即可。

四、关键注意事项（避坑指南）

1. 网络要求 • 新电脑必须：

① 能访问内网（和继电器模块通）；

② 能访问外网（连 EMQX 服务器）。 • 继电器模块的 8234 端口、EMQX 服务器的 1883 端口必须放行（防火墙 / 路由器）。

2. 常见问题排查

问题现象	解决方法
Modbus连接失败	检查继电器 IP / 端口，确保模块在 TCP-Server 模式
MQTT连接失败	检查 EMQX IP / 账号 / 密码，确保 1883 端口开放
指令解析失败	确认 MQTT 指令是 JSON 格式，包含power/coil字段
pymodbus报错slave参数	必须装 2.5.3 版本，执行 pip install pymodbus==2.5.3

3.开机自启（可选，不用手动启动）

启动控电程序.bat 文件，内容：

@echo off
cd /d C:\Users\你的用户名\Desktop\棋牌室控电
python relay_control.py
pause

2.按 Win+R，输入 shell:startup，把 .bat 文件复制到启动文件夹，重启电脑自动运行。

五、总结（核心关键点）

1. 环境部署：装 Python 3.7+ → 装 pymodbus==2.5.3 + paho-mqtt → 复制程序 → 修改 5 个配置 → 启动。

2. 核心依赖：仅需 2 个库（pymodbus==2.5.3 是关键，新版会报错）。

3. 关键配置：EMQX 和继电器的 IP / 端口 / 账号必须和原电脑一致。

4. 避坑重点：新电脑要同时通内网（连继电器）和外网（连 EMQX），端口必须放行。