esp32io-mqtt 0.1.0

A lightweight Python MQTT client for controlling ESP32IO-MQTT devices (Home Assistant compatible).

ESP32IO-MQTT Python MQTT Client

ESP32IO-MQTT is a lightweight Python MQTT client for controlling ESP32IO-MQTT 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対応）

---

インストール

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

---

クイックスタート

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())

サンプル実行:

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 を返した場合

---

プロジェクト構成

.
├── 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（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 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

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

Quick Start

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