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_onlinepublish_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 stateon_state_change()to register a callback for state changespublish_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
Metadata
Release files for esp32io-mqtt 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| esp32io_mqtt-0.1.0.tar.gz | 13.0 kB | Without provenance | Details for esp32io_mqtt-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| esp32io_mqtt-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for esp32io_mqtt-0.1.0-py3-none-any.whl |
Total release size: 24.8 kB
Release files / esp32io_mqtt-0.1.0.tar.gz
| Download URL | esp32io_mqtt-0.1.0.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
738e64145452b681f9e7d0cae446c4069c031483aaa361fa3e1306515935f150
|
|
BLAKE2b-256 checksum How to use checksums |
975f8a6d5258441781a9a45d702bfa05349f9eb6e593cb968fcd7ee2da1c5be4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / esp32io_mqtt-0.1.0-py3-none-any.whl
| Download URL | esp32io_mqtt-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f132355c31c82b38ed09cf8248b14b917ca14e4fda978c66d5edcca998bd7cbc
|
|
BLAKE2b-256 checksum How to use checksums |
3bf69a564fa511464abca384f9e32f6b9b8a4594dab99ac0a505e705a47d947a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for esp32io-mqtt 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.