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
