Metadata-Version: 2.4
Name: esp32io-mqtt
Version: 0.1.0
Summary: A lightweight Python MQTT client for controlling ESP32IO-MQTT devices (Home Assistant compatible).
Author: Noritama-Lab
License: MIT
Project-URL: Repository, https://github.com/Noritama-Lab/esp32io-mqtt-api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paho-mqtt<2.0,>=1.6
Dynamic: license-file

# ESP32IO-MQTT Python MQTT Client

ESP32IO-MQTT is a lightweight Python **MQTT** client for controlling [ESP32IO-MQTT](https://github.com/Noritama-Lab/esp32io-mqtt-firmware) devices.

日本語 / English

---

## 日本語

ESP32IO-MQTT Pythonクライアントは、**MQTTブローカー** 経由で ESP32IO-MQTT ファームウェアを制御するための軽量Pythonクライアントです。

ESP32IO-MQTT ファームウェアはデバイス制御を **MQTT** 経由で行います。本クライアントもMQTT専用です。

---

## 特徴

- MQTTブローカー経由での接続のみをサポート（HTTP/シリアルは非対応）
- 汎用JSONコマンドチャネル (`<base>/cmd` → `<base>/cmd/result`) を使った同期API (`read_di()`, `set_do()`, `get_io_state()` 等)
- 個別エンティティのトピック (Home Assistant MQTT Discovery互換) にも対応
  - `get_cached_state()` で直近受信した状態のスナップショットを取得
  - `on_state_change()` で状態変化のコールバックを登録
  - `publish_do()` / `publish_pwm()` / `publish_rgb()` / `publish_led_off()` / `publish_led_mode()` / `publish_oled()` で応答待ちなしに直接publish
- I2Cスキャン、リード/ライト、BME280/MPU6050/VL53L1Xなどのセンサー一括取得、OLED表示をサポート
- PWM周波数・分解能の取得/更新に対応
- 通信エラー・タイムアウト・プロトコル不整合・デバイスエラーなど統一例外を定義
- 任意JSONを送れる低レベルAPI `command()` を提供

---

## 動作環境

- Python 3.8 以上
- `paho-mqtt>=1.6,<2.0`
- MQTTブローカー (Mosquitto等)
- ESP32IO-MQTT ファームウェア（MQTT対応）

---

## インストール

```bash
pip install -r requirements.txt
# または
pip install -e .
```

---

## クイックスタート

```python
from esp32io_mqtt import ESP32S3IOMqtt

# DEVICE_ID は設定ポータル (http://<device_ip>/) のページタイトルや
# mDNSホスト名 (ESP32IO_MQTT_XXXXXX) で確認できます。
with ESP32S3IOMqtt("ESP32IO_MQTT_XXXXXX", "192.168.1.5", debug=False) as esp:
    print("ping =", esp.ping())
    print("di0 =", esp.read_di(0))
    print("adc0 =", esp.read_adc(0))
    print("pwm config =", esp.get_pwm_config())

    esp.set_do(0, 1)
    esp.set_pwm(0, 128)

    print(esp.get_io_state())
```

サンプル実行:

```bash
py -m examples.mqtt_example
```

---

## 通信方式

### 1. 汎用JSONコマンドチャネル (同期API)

`command()` および `read_di()` / `set_do()` などの高レベルメソッドは、`<base>/cmd` にJSONをpublishし `<base>/cmd/result` の応答を待つ同期方式です。戻り値やエラー(`ESP32IODeviceError`)で結果を確認できます。

### 2. 個別エンティティのトピック (Home Assistant MQTT Discovery互換)

接続時に `di/+/state` `do/+/state` `pwm/+/state` `rgb/state` `led_mode/state` `oled/state` `bme280/#` `mpu6050/#` `vl53l1x/#` `diag/#` `status` を自動的にsubscribeし、受信するたびに内部キャッシュへ保存します。

- `get_cached_state()` — 直近に受信した値のスナップショット (dict) を取得
- `on_state_change(callback)` — 状態トピックを受信するたびに `callback(topic_suffix, payload)` を呼び出す
- `is_online` — LWTトピック (`<base>/status`) が `online` かどうか
- `publish_do(pin_id, value)` / `publish_pwm(pin_id, duty)` / `publish_rgb(r, g, b, brightness)` / `publish_led_off()` / `publish_led_mode(mode)` / `publish_oled(text)` — 応答を待たずに直接publish（Home Assistant側からの操作と同じ経路）

---

## API 一覧（主要メソッド）

- `ESP32S3IOMqtt(device_id, host, port=1883, user=None, password=None, topic_root="esp32io", keepalive=30, cmd_timeout=5.0, connect_timeout=10.0, debug=False)`
- `ping()`
- `read_di(pin_id)` / `set_do(pin_id, value)`
- `read_adc(pin_id)`
- `set_pwm(pin_id, duty)`
- `get_pwm_config()` / `set_pwm_config(freq, res)`
- `set_led_mode(mode)` / `set_rgb(r, g, b, brightness)` / `led_off()` / `get_led_state()`
- `i2c_scan()` / `i2c_read(addr, length)` / `i2c_write(addr, data)`
- `get_sensors()`
- `set_oled(text, x, y, size, clear)`
- `get_io_state()` / `get_status()`
- `command(cmd, **kwargs)`
- `help()`
- `get_cached_state()` / `on_state_change(callback)` / `is_online`
- `publish_do()` / `publish_pwm()` / `publish_rgb()` / `publish_led_off()` / `publish_led_mode()` / `publish_oled()`
- `close()`

---

## 例外

- `ESP32IOError`（基底クラス）
- `ESP32IOMqttError` — ブローカー接続・publish失敗
- `ESP32IOTimeoutError` — `cmd/result` 応答待ちのタイムアウト（`ESP32IOMqttError`のサブクラス）
- `ESP32IOProtocolError` — デバイスから不正な応答
- `ESP32IODeviceError` — デバイスが `status=error` を返した場合

---

## プロジェクト構成

```text
.
├── esp32io_mqtt/
│   ├── __init__.py
│   ├── client.py
│   ├── exceptions.py
│   └── protocol.py
├── examples/
│   ├── mqtt_example.py
│   └── i2c_example.py
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md
```

---

## ファームウェア

対応ファームウェア: [ESP32IO-MQTT](https://github.com/Noritama-Lab/esp32io-mqtt-firmware)（MQTT + Home Assistant MQTT Discovery対応）。
トピック構成・汎用JSONコマンド一覧は同リポジトリの `COMMAND_REFERENCE.md` を参照してください。

---

## ライセンス

MIT License
Copyright (c) 2026 Noritama-Lab

---

## English

ESP32IO-MQTT Python client is a lightweight **MQTT** client for controlling [ESP32IO-MQTT](https://github.com/Noritama-Lab/esp32io-mqtt-firmware) firmware.

ESP32IO-MQTT firmware controls devices over **MQTT**. This client is MQTT-only.

### Features

- MQTT broker connection only (no HTTP/Serial support)
- Synchronous API over the generic JSON command channel (`<base>/cmd` → `<base>/cmd/result`) (`read_di()`, `set_do()`, `get_io_state()`, etc.)
- Support for individual entity topics (Home Assistant MQTT Discovery compatible)
  - `get_cached_state()` for a snapshot of the latest received state
  - `on_state_change()` to register a callback for state changes
  - `publish_do()` / `publish_pwm()` / `publish_rgb()` / `publish_led_off()` / `publish_led_mode()` / `publish_oled()` to publish directly without waiting for a response
- I2C scanning, raw read/write, sensor batch reads (BME280/MPU6050/VL53L1X), and OLED control
- PWM frequency/resolution read & update
- Unified exceptions for MQTT, protocol, timeout, and device errors
- Low-level `command()` API for custom JSON commands

### Requirements

- Python 3.8+
- `paho-mqtt>=1.6,<2.0`
- An MQTT broker (e.g. Mosquitto)
- ESP32IO-MQTT firmware (MQTT-based)

### Installation

```bash
pip install -r requirements.txt
# or
pip install -e .
```

### Quick Start

```python
from esp32io_mqtt import ESP32S3IOMqtt

with ESP32S3IOMqtt("ESP32IO_MQTT_XXXXXX", "192.168.1.5", debug=False) as esp:
    print("ping =", esp.ping())
    print("di0 =", esp.read_di(0))
    esp.set_do(0, 1)
    print(esp.get_io_state())
```

### License

MIT License
Copyright (c) 2026 Noritama-Lab
