Skip to main content

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

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)

Source distribution for esp32io-mqtt 0.1.0
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)

Table of built distributions (wheels) for esp32io-mqtt 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page