geme-plug 1.0.0__tar.gz

geme_plug-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loks666
+
+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.

geme_plug-1.0.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: geme-plug
+Version: 1.0.0
+Summary: Python MQTT SDK for GemeOpen GSPM1B smart plugs using a self-hosted broker such as EMQX.
+Author: loks666
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loks666/geme-plug
+Project-URL: Repository, https://github.com/loks666/geme-plug
+Project-URL: Issues, https://github.com/loks666/geme-plug/issues
+Keywords: GemeOpen,GeekOpen,GSPM1B,MQTT,EMQX,smart plug,IoT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt<3,>=2.1
+Dynamic: license-file
+
+# geme-plug
+
+`geme-plug` 是一个用于 **GemeOpen / GeekOpen GSPM1B 智能插座** 的 Python MQTT SDK，面向自建 MQTT Broker（例如 EMQX）。
+
+> 本项目是第三方开源 SDK，与 GemeOpen / 武汉智鸟科技无隶属关系。
+
+## 安装
+
+```bash
+pip install geme-plug
+```
+
+## 快速开始
+
+```python
+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()
+```
+
+也支持上下文管理器：
+
+```python
+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 客户端认证，并内置以下局域网设备账号：
+
+```text
+用户名：geme-plug
+密码：x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA
+```
+
+SDK 和设备配网页都要使用相同的账号：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    username="geme-plug",
+    password="x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA",
+)
+```
+
+`port` 默认是 `1883`。
+
+## 使用 Docker Compose 启动 EMQX
+
+仓库内置了 EMQX Compose 配置，包含账号密码认证和持久化数据卷：
+
+```bash
+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 后，可运行：
+
+```bash
+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：
+
+```text
+request
+response
+```
+
+- SDK 向 `request` 发布控制指令，设备订阅该主题；
+- SDK 订阅 `response`，设备通过该主题返回状态和电量数据。
+
+在 GemeOpen 的“自定义 MQTT”页面中填写：
+
+- 订阅主题：`request`
+- 发布主题：`response`
+
+设备配置页的字段名称与 SDK 视角相反：SDK 的 `publish_topic` 对应设备的
+“订阅主题”，SDK 的 `subscribe_topic` 对应设备的“发布主题”。如果同一个
+Broker 连接多台设备，应为每台设备设置独立 Topic，避免消息互相干扰。
+
+如果你已经给设备配置了其他 Topic，可以显式覆盖：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    publish_topic="my/device/command",
+    subscribe_topic="my/device/state",
+)
+```
+
+## API
+
+### `SmartPlug(...)`
+
+```python
+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 可以使用以下任意格式：
+
+```text
+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 协议发送：
+
+```json
+{"type":"event","key":1}
+```
+
+或：
+
+```json
+{"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

geme_plug-1.0.0/README.md

@@ -0,0 +1,210 @@
+# geme-plug
+
+`geme-plug` 是一个用于 **GemeOpen / GeekOpen GSPM1B 智能插座** 的 Python MQTT SDK，面向自建 MQTT Broker（例如 EMQX）。
+
+> 本项目是第三方开源 SDK，与 GemeOpen / 武汉智鸟科技无隶属关系。
+
+## 安装
+
+```bash
+pip install geme-plug
+```
+
+## 快速开始
+
+```python
+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()
+```
+
+也支持上下文管理器：
+
+```python
+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 客户端认证，并内置以下局域网设备账号：
+
+```text
+用户名：geme-plug
+密码：x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA
+```
+
+SDK 和设备配网页都要使用相同的账号：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    username="geme-plug",
+    password="x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA",
+)
+```
+
+`port` 默认是 `1883`。
+
+## 使用 Docker Compose 启动 EMQX
+
+仓库内置了 EMQX Compose 配置，包含账号密码认证和持久化数据卷：
+
+```bash
+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 后，可运行：
+
+```bash
+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：
+
+```text
+request
+response
+```
+
+- SDK 向 `request` 发布控制指令，设备订阅该主题；
+- SDK 订阅 `response`，设备通过该主题返回状态和电量数据。
+
+在 GemeOpen 的“自定义 MQTT”页面中填写：
+
+- 订阅主题：`request`
+- 发布主题：`response`
+
+设备配置页的字段名称与 SDK 视角相反：SDK 的 `publish_topic` 对应设备的
+“订阅主题”，SDK 的 `subscribe_topic` 对应设备的“发布主题”。如果同一个
+Broker 连接多台设备，应为每台设备设置独立 Topic，避免消息互相干扰。
+
+如果你已经给设备配置了其他 Topic，可以显式覆盖：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    publish_topic="my/device/command",
+    subscribe_topic="my/device/state",
+)
+```
+
+## API
+
+### `SmartPlug(...)`
+
+```python
+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 可以使用以下任意格式：
+
+```text
+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 协议发送：
+
+```json
+{"type":"event","key":1}
+```
+
+或：
+
+```json
+{"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

geme_plug-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geme-plug"
+version = "1.0.0"
+description = "Python MQTT SDK for GemeOpen GSPM1B smart plugs using a self-hosted broker such as EMQX."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "loks666" }
+]
+keywords = ["GemeOpen", "GeekOpen", "GSPM1B", "MQTT", "EMQX", "smart plug", "IoT"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Home Automation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "paho-mqtt>=2.1,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/loks666/geme-plug"
+Repository = "https://github.com/loks666/geme-plug"
+Issues = "https://github.com/loks666/geme-plug/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

geme_plug-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

geme_plug-1.0.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

geme_plug-1.0.0/src/geme_plug/__init__.py

@@ -0,0 +1,16 @@
+from .client import SmartPlug, normalize_mac
+from .exceptions import ConnectionError, GemePlugError, ProtocolError, RequestTimeoutError
+from .models import PlugStatus, PowerStatus
+
+__all__ = [
+    "SmartPlug",
+    "PlugStatus",
+    "PowerStatus",
+    "normalize_mac",
+    "GemePlugError",
+    "ConnectionError",
+    "RequestTimeoutError",
+    "ProtocolError",
+]
+
+__version__ = "1.0.0"

geme_plug-1.0.0/src/geme_plug/client.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import json
+import re
+import threading
+import uuid
+from typing import Any
+
+import paho.mqtt.client as mqtt
+
+from .exceptions import ConnectionError, ProtocolError, RequestTimeoutError
+from .models import PlugStatus, PowerStatus
+
+_MAC_RE = re.compile(r"^[0-9a-f]{12}$")
+
+
+def normalize_mac(mac: str) -> str:
+    """Normalize a MAC address to 12 lowercase hexadecimal characters."""
+    normalized = re.sub(r"[^0-9A-Fa-f]", "", mac).lower()
+    if not _MAC_RE.fullmatch(normalized):
+        raise ValueError(
+            "mac must contain exactly 12 hexadecimal characters, "
+            "for example 'AABBCCDDEEFF' or 'AA:BB:CC:DD:EE:FF'"
+        )
+    return normalized
+
+
+class SmartPlug:
+    """Synchronous MQTT client for GemeOpen GSPM1B-compatible smart plugs.
+
+    The plug must already be configured to connect to the same MQTT broker and
+    use the same publish/subscribe topics as this client.
+    """
+
+    def __init__(
+        self,
+        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,
+    ) -> None:
+        if not host or not host.strip():
+            raise ValueError("host cannot be empty")
+        if port <= 0 or port > 65535:
+            raise ValueError("port must be between 1 and 65535")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than 0")
+        if password is not None and username is None:
+            raise ValueError("username is required when password is provided")
+
+        self.host = host.strip()
+        self.port = int(port)
+        self.mac = normalize_mac(mac)
+        self.username = username
+        self.password = password
+        self.timeout = float(timeout)
+
+        # The SDK publishes commands to the topic subscribed to by the device,
+        # and subscribes to the topic used by the device for responses.
+        self.publish_topic = publish_topic or "request"
+        self.subscribe_topic = subscribe_topic or "response"
+        self.client_id = client_id or f"geme-plug-{self.mac}-{uuid.uuid4().hex[:8]}"
+
+        self._connected = threading.Event()
+        self._connect_error: str | None = None
+        self._pending: dict[str, tuple[threading.Event, dict[str, Any] | None]] = {}
+        self._pending_lock = threading.Lock()
+
+        self._client = mqtt.Client(
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+            client_id=self.client_id,
+            protocol=mqtt.MQTTv311,
+        )
+        if self.username is not None:
+            self._client.username_pw_set(self.username, self.password)
+
+        self._client.on_connect = self._on_connect
+        self._client.on_disconnect = self._on_disconnect
+        self._client.on_message = self._on_message
+
+    def connect(self) -> "SmartPlug":
+        """Connect to the MQTT broker and subscribe to the plug response topic."""
+        if self._connected.is_set():
+            return self
+
+        self._connect_error = None
+        try:
+            rc = self._client.connect(self.host, self.port, keepalive=60)
+        except OSError as exc:
+            raise ConnectionError(
+                f"failed to connect to MQTT broker {self.host}:{self.port}: {exc}"
+            ) from exc
+        if rc != mqtt.MQTT_ERR_SUCCESS:
+            raise ConnectionError(
+                f"failed to connect to MQTT broker {self.host}:{self.port}: rc={rc}"
+            )
+        self._client.loop_start()
+
+        if not self._connected.wait(self.timeout):
+            self._client.loop_stop()
+            try:
+                self._client.disconnect()
+            except Exception:
+                pass
+            detail = f": {self._connect_error}" if self._connect_error else ""
+            raise ConnectionError(
+                f"failed to connect to MQTT broker {self.host}:{self.port}{detail}"
+            )
+        return self
+
+    def disconnect(self) -> None:
+        """Disconnect from the MQTT broker."""
+        if not self._connected.is_set():
+            return
+        try:
+            self._client.disconnect()
+        finally:
+            self._client.loop_stop()
+            self._connected.clear()
+
+    def turn_on(self) -> None:
+        """Turn the plug output on."""
+        self._publish({"type": "event", "key": 1})
+
+    def turn_off(self) -> None:
+        """Turn the plug output off."""
+        self._publish({"type": "event", "key": 0})
+
+    def get_status(self) -> PlugStatus:
+        """Query basic plug status."""
+        payload = self._request({"type": "info"})
+        return PlugStatus.from_payload(payload)
+
+    def get_power(self) -> PowerStatus:
+        """Query voltage, current, power, energy and switch state."""
+        payload = self._request({"type": "statistic"})
+        return PowerStatus.from_payload(payload)
+
+    def __enter__(self) -> "SmartPlug":
+        return self.connect()
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.disconnect()
+
+    def _ensure_connected(self) -> None:
+        if not self._connected.is_set():
+            raise ConnectionError("not connected; call plug.connect() first")
+
+    def _publish(self, payload: dict[str, Any]) -> None:
+        self._ensure_connected()
+        encoded = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+        info = self._client.publish(self.publish_topic, encoded, qos=0, retain=False)
+        if info.rc != mqtt.MQTT_ERR_SUCCESS:
+            raise ConnectionError(f"MQTT publish failed with rc={info.rc}")
+        info.wait_for_publish(timeout=self.timeout)
+
+    def _request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self._ensure_connected()
+        message_id = uuid.uuid4().hex
+        request = dict(payload)
+        request["messageId"] = message_id
+        event = threading.Event()
+
+        with self._pending_lock:
+            self._pending[message_id] = (event, None)
+
+        try:
+            self._publish(request)
+            if not event.wait(self.timeout):
+                raise RequestTimeoutError(
+                    f"device {self.mac} did not respond within {self.timeout:g}s"
+                )
+            with self._pending_lock:
+                _, response = self._pending.get(message_id, (event, None))
+            if response is None:
+                raise ProtocolError("device response was empty")
+            return response
+        finally:
+            with self._pending_lock:
+                self._pending.pop(message_id, None)
+
+    def _on_connect(
+        self,
+        client: mqtt.Client,
+        userdata: Any,
+        flags: mqtt.ConnectFlags,
+        reason_code: mqtt.ReasonCode,
+        properties: mqtt.Properties | None,
+    ) -> None:
+        if reason_code.is_failure:
+            self._connect_error = str(reason_code)
+            return
+        result, _ = client.subscribe(self.subscribe_topic, qos=0)
+        if result != mqtt.MQTT_ERR_SUCCESS:
+            self._connect_error = f"subscribe failed with rc={result}"
+            return
+        self._connected.set()
+
+    def _on_disconnect(
+        self,
+        client: mqtt.Client,
+        userdata: Any,
+        disconnect_flags: mqtt.DisconnectFlags,
+        reason_code: mqtt.ReasonCode,
+        properties: mqtt.Properties | None,
+    ) -> None:
+        self._connected.clear()
+
+    def _on_message(self, client: mqtt.Client, userdata: Any, message: mqtt.MQTTMessage) -> None:
+        try:
+            payload = json.loads(message.payload.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return
+        if not isinstance(payload, dict):
+            return
+
+        message_id = payload.get("messageId")
+        if message_id is None:
+            return
+        message_id = str(message_id)
+
+        with self._pending_lock:
+            pending = self._pending.get(message_id)
+            if pending is None:
+                return
+            event, _ = pending
+            self._pending[message_id] = (event, payload)
+            event.set()

geme_plug-1.0.0/src/geme_plug/exceptions.py

@@ -0,0 +1,14 @@
+class GemePlugError(Exception):
+    """Base exception for geme-plug."""
+
+
+class ConnectionError(GemePlugError):
+    """Raised when the MQTT broker connection cannot be established."""
+
+
+class RequestTimeoutError(GemePlugError):
+    """Raised when the plug does not respond within the configured timeout."""
+
+
+class ProtocolError(GemePlugError):
+    """Raised when a malformed or unexpected device response is received."""

geme_plug-1.0.0/src/geme_plug/models.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PlugStatus:
+    mac: str
+    device_type: str | None = None
+    version: str | None = None
+    key: int | None = None
+    wifi_lock: int | None = None
+    key_lock: int | None = None
+    signal: int | None = None
+    on_state: int | None = None
+    timer_enable: int | None = None
+    timer_interval: int | None = None
+    ip: str | None = None
+    ssid: str | None = None
+    message_id: str | None = None
+
+    @property
+    def is_on(self) -> bool | None:
+        if self.key is None:
+            return None
+        return self.key == 1
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "PlugStatus":
+        return cls(
+            mac=str(payload.get("mac", "")),
+            device_type=payload.get("type"),
+            version=payload.get("version"),
+            key=_to_int(payload.get("key")),
+            wifi_lock=_to_int(payload.get("wifiLock")),
+            key_lock=_to_int(payload.get("keyLock")),
+            signal=_to_int(payload.get("signal")),
+            on_state=_to_int(payload.get("onState")),
+            timer_enable=_to_int(payload.get("timerEnable")),
+            timer_interval=_to_int(payload.get("timerInterval")),
+            ip=payload.get("ip"),
+            ssid=payload.get("ssid"),
+            message_id=_to_str_or_none(payload.get("messageId")),
+        )
+
+
+@dataclass(frozen=True)
+class PowerStatus:
+    mac: str
+    voltage: float | None = None
+    current: float | None = None
+    power: float | None = None
+    energy: float | None = None
+    key: int | None = None
+    message_id: str | None = None
+
+    @property
+    def is_on(self) -> bool | None:
+        if self.key is None:
+            return None
+        return self.key == 1
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "PowerStatus":
+        return cls(
+            mac=str(payload.get("mac", "")),
+            voltage=_to_float(payload.get("voltage")),
+            current=_to_float(payload.get("current")),
+            power=_to_float(payload.get("power")),
+            energy=_to_float(payload.get("energy")),
+            key=_to_int(payload.get("key")),
+            message_id=_to_str_or_none(payload.get("messageId")),
+        )
+
+
+def _to_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    return int(value)
+
+
+def _to_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    return float(value)
+
+
+def _to_str_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)

geme_plug-1.0.0/src/geme_plug.egg-info/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: geme-plug
+Version: 1.0.0
+Summary: Python MQTT SDK for GemeOpen GSPM1B smart plugs using a self-hosted broker such as EMQX.
+Author: loks666
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loks666/geme-plug
+Project-URL: Repository, https://github.com/loks666/geme-plug
+Project-URL: Issues, https://github.com/loks666/geme-plug/issues
+Keywords: GemeOpen,GeekOpen,GSPM1B,MQTT,EMQX,smart plug,IoT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt<3,>=2.1
+Dynamic: license-file
+
+# geme-plug
+
+`geme-plug` 是一个用于 **GemeOpen / GeekOpen GSPM1B 智能插座** 的 Python MQTT SDK，面向自建 MQTT Broker（例如 EMQX）。
+
+> 本项目是第三方开源 SDK，与 GemeOpen / 武汉智鸟科技无隶属关系。
+
+## 安装
+
+```bash
+pip install geme-plug
+```
+
+## 快速开始
+
+```python
+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()
+```
+
+也支持上下文管理器：
+
+```python
+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 客户端认证，并内置以下局域网设备账号：
+
+```text
+用户名：geme-plug
+密码：x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA
+```
+
+SDK 和设备配网页都要使用相同的账号：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    username="geme-plug",
+    password="x7Tq9V2mK8rP4nD6sH3wF5cJ1bL0zQeA",
+)
+```
+
+`port` 默认是 `1883`。
+
+## 使用 Docker Compose 启动 EMQX
+
+仓库内置了 EMQX Compose 配置，包含账号密码认证和持久化数据卷：
+
+```bash
+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 后，可运行：
+
+```bash
+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：
+
+```text
+request
+response
+```
+
+- SDK 向 `request` 发布控制指令，设备订阅该主题；
+- SDK 订阅 `response`，设备通过该主题返回状态和电量数据。
+
+在 GemeOpen 的“自定义 MQTT”页面中填写：
+
+- 订阅主题：`request`
+- 发布主题：`response`
+
+设备配置页的字段名称与 SDK 视角相反：SDK 的 `publish_topic` 对应设备的
+“订阅主题”，SDK 的 `subscribe_topic` 对应设备的“发布主题”。如果同一个
+Broker 连接多台设备，应为每台设备设置独立 Topic，避免消息互相干扰。
+
+如果你已经给设备配置了其他 Topic，可以显式覆盖：
+
+```python
+plug = SmartPlug(
+    host="192.168.31.100",
+    mac="AABBCCDDEEFF",
+    publish_topic="my/device/command",
+    subscribe_topic="my/device/state",
+)
+```
+
+## API
+
+### `SmartPlug(...)`
+
+```python
+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 可以使用以下任意格式：
+
+```text
+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 协议发送：
+
+```json
+{"type":"event","key":1}
+```
+
+或：
+
+```json
+{"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

geme_plug-1.0.0/src/geme_plug.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+src/geme_plug/__init__.py
+src/geme_plug/client.py
+src/geme_plug/exceptions.py
+src/geme_plug/models.py
+src/geme_plug.egg-info/PKG-INFO
+src/geme_plug.egg-info/SOURCES.txt
+src/geme_plug.egg-info/dependency_links.txt
+src/geme_plug.egg-info/requires.txt
+src/geme_plug.egg-info/top_level.txt
+tests/test_client.py

geme_plug-1.0.0/src/geme_plug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

geme_plug-1.0.0/src/geme_plug.egg-info/requires.txt

@@ -0,0 +1 @@
+paho-mqtt<3,>=2.1

geme_plug-1.0.0/src/geme_plug.egg-info/top_level.txt

@@ -0,0 +1 @@
+geme_plug

geme_plug-1.0.0/tests/test_client.py

@@ -0,0 +1,117 @@
+import json
+import threading
+
+import pytest
+
+from geme_plug import PlugStatus, PowerStatus, SmartPlug, normalize_mac
+
+
+def test_normalize_mac():
+    assert normalize_mac("AA:BB:CC:DD:EE:FF") == "aabbccddeeff"
+    assert normalize_mac("aa-bb-cc-dd-ee-ff") == "aabbccddeeff"
+    assert normalize_mac("AABBCCDDEEFF") == "aabbccddeeff"
+
+
+@pytest.mark.parametrize("value", ["", "abc", "GG:BB:CC:DD:EE:FF", "AABBCCDDEEFF00"])
+def test_normalize_mac_rejects_invalid(value):
+    with pytest.raises(ValueError):
+        normalize_mac(value)
+
+
+def test_default_topics():
+    plug = SmartPlug(host="127.0.0.1", mac="AA:BB:CC:DD:EE:FF")
+    assert plug.publish_topic == "request"
+    assert plug.subscribe_topic == "response"
+
+
+def test_custom_topics():
+    plug = SmartPlug(
+        host="127.0.0.1",
+        mac="AABBCCDDEEFF",
+        publish_topic="custom/command",
+        subscribe_topic="custom/state",
+    )
+    assert plug.publish_topic == "custom/command"
+    assert plug.subscribe_topic == "custom/state"
+
+
+def test_status_model():
+    status = PlugStatus.from_payload(
+        {
+            "mac": "aabbccddeeff",
+            "type": "Socket-mini",
+            "version": "2.0.0",
+            "key": 1,
+            "wifiLock": 0,
+            "keyLock": 0,
+            "signal": -55,
+            "onState": 1,
+            "timerEnable": 1,
+            "timerInterval": 60,
+            "ip": "192.168.31.123",
+            "ssid": "wifi",
+            "messageId": "abc",
+        }
+    )
+    assert status.is_on is True
+    assert status.device_type == "Socket-mini"
+    assert status.ip == "192.168.31.123"
+
+
+def test_power_model():
+    power = PowerStatus.from_payload(
+        {
+            "mac": "aabbccddeeff",
+            "voltage": 226.024,
+            "current": 1.027,
+            "power": 232.511,
+            "energy": 25.047,
+            "key": 1,
+            "messageId": "abc",
+        }
+    )
+    assert power.voltage == pytest.approx(226.024)
+    assert power.energy == pytest.approx(25.047)
+    assert power.is_on is True
+
+
+class _PublishInfo:
+    rc = 0
+
+    def wait_for_publish(self, timeout=None):
+        return None
+
+
+class _FakeClient:
+    def __init__(self, plug):
+        self.plug = plug
+        self.published = []
+
+    def publish(self, topic, payload, qos=0, retain=False):
+        self.published.append((topic, payload))
+        data = json.loads(payload)
+        if data["type"] in {"info", "statistic"}:
+            response = {"messageId": data["messageId"], "mac": self.plug.mac}
+            if data["type"] == "info":
+                response.update({"type": "Socket-mini", "key": 1, "ip": "192.168.31.9"})
+            else:
+                response.update({"voltage": 220.0, "current": 0.5, "power": 110.0, "energy": 1.25, "key": 1})
+
+            class Message:
+                payload = json.dumps(response).encode()
+
+            threading.Timer(0.01, lambda: self.plug._on_message(self, None, Message())).start()
+        return _PublishInfo()
+
+
+def test_request_response_flow():
+    plug = SmartPlug(host="127.0.0.1", mac="AABBCCDDEEFF", timeout=1)
+    plug._connected.set()
+    plug._client = _FakeClient(plug)
+
+    status = plug.get_status()
+    power = plug.get_power()
+
+    assert status.device_type == "Socket-mini"
+    assert status.ip == "192.168.31.9"
+    assert power.power == pytest.approx(110.0)