geme-plug

geme-plug 是一个用于 GemeOpen / GeekOpen GSPM1B 智能插座 的 Python MQTT SDK，面向自建 MQTT Broker（例如 EMQX）。

本项目是第三方开源 SDK，与 GemeOpen / 武汉智鸟科技无隶属关系。

安装

pip install geme-plug

快速开始

from geme_plug import SmartPlug

plug = SmartPlug(
    host="192.168.31.100",   # EMQX Broker IP / hostname
    mac="AABBCCDDEEFF",
)

plug.connect()

plug.turn_on()
plug.turn_off()

print(plug.get_status())
print(plug.get_power())

plug.disconnect()

也支持上下文管理器：

from geme_plug import SmartPlug

with SmartPlug(host="192.168.31.100", mac="AA:BB:CC:DD:EE:FF") as plug:
    plug.turn_on()
    print(plug.get_power())

EMQX 认证

仓库中的 Compose 配置默认启用 MQTT 客户端认证，并内置以下局域网设备账号：

用户名：geme-plug
密码：x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA

SDK 和设备配网页都要使用相同的账号：

plug = SmartPlug(
    host="192.168.31.100",
    mac="AABBCCDDEEFF",
    username="geme-plug",
    password="x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA",
)

port 默认是 1883。

使用 Docker Compose 启动 EMQX

仓库内置了 EMQX Compose 配置，包含账号密码认证和持久化数据卷：

docker compose up -d

• MQTT Broker：mqtt://<本机局域网 IP>:1883
• EMQX Dashboard：http://127.0.0.1:18083

设备必须连接到运行 EMQX 的电脑的局域网 IP，不能使用设备视角下的 127.0.0.1。EMQX Dashboard 的初始登录信息请以当前镜像的启动页提示为准， 首次登录后应立即修改密码。

关断测试

确认设备已经连到该 Broker 后，可运行：

python examples/turn_off.py \
  --host <运行 EMQX 的局域网 IP> \
  --mac <插座 MAC 地址>

脚本先查询当前状态，再发布关断指令，最后重新查询并验证设备报告为关闭。

设备 MQTT 配置

在使用 SDK 前，插座必须已经：

1. 完成 2.4 GHz Wi-Fi 配网；
2. 配置为连接你的 MQTT Broker / EMQX；
3. 配置与 SDK 一致的 MQTT Topic。

geme-plug 默认使用两个简洁的 Topic：

request
response

• SDK 向 request 发布控制指令，设备订阅该主题；
• SDK 订阅 response，设备通过该主题返回状态和电量数据。

在 GemeOpen 的“自定义 MQTT”页面中填写：

• 订阅主题：request
• 发布主题：response

设备配置页的字段名称与 SDK 视角相反：SDK 的 publish_topic 对应设备的 “订阅主题”，SDK 的 subscribe_topic 对应设备的“发布主题”。如果同一个 Broker 连接多台设备，应为每台设备设置独立 Topic，避免消息互相干扰。

如果你已经给设备配置了其他 Topic，可以显式覆盖：

plug = SmartPlug(
    host="192.168.31.100",
    mac="AABBCCDDEEFF",
    publish_topic="my/device/command",
    subscribe_topic="my/device/state",
)

API

SmartPlug(...)

SmartPlug(
    host: str,
    mac: str,
    port: int = 1883,
    username: str | None = None,
    password: str | None = None,
    timeout: float = 5.0,
    publish_topic: str | None = None,
    subscribe_topic: str | None = None,
    client_id: str | None = None,
)

MAC 可以使用以下任意格式：

AABBCCDDEEFF
AA:BB:CC:DD:EE:FF
AA-BB-CC-DD-EE-FF

SDK 内部统一规范化为 aabbccddeeff。

connect() / disconnect()

连接或断开 MQTT Broker。

turn_on() / turn_off()

控制插座通断电。SDK 根据 GSPM1B 协议发送：

{"type":"event","key":1}

或：

{"type":"event","key":0}

get_status()

查询设备状态，返回 PlugStatus，常用字段包括：

• mac
• device_type
• version
• key / is_on
• signal
• ip
• ssid
• wifi_lock
• key_lock
• on_state
• timer_enable
• timer_interval

get_power()

查询电量数据，返回 PowerStatus：

• voltage：V
• current：A
• power：W
• energy：kWh
• key / is_on

说明

本版本聚焦于最基础、稳定的控制能力：连接 Broker、通断控制、状态查询和电量查询。设备配网和局域网自动发现暂不包含在 1.0.0 中。

License

MIT