Skip to main content

ESP32IO Python API

ESP32IO is a lightweight Python client for controlling ESP32-S3 devices over USB serial or Wi-Fi (HTTP).

日本語 / English


日本語

ESP32IO は、ESP32-S3 を USB シリアル または Wi-Fi (HTTP) 経由で制御するための軽量 Python クライアントです。
ESP32 側で JSON コマンドを受け取るファームウェアと組み合わせることで、DIO / ADC / PWM / 内蔵 RGB LED / I2C / OLED を統一 API で扱えます。


特徴

  • USB シリアル & Wi-Fi (HTTP) の両通信方式を単一パッケージでサポート
  • JSON プロトコルを ESP32S3IOSerial / ESP32S3IONet が抽象化
  • DIO、ADC、PWM、RGB LED、システム状態取得に対応
  • I2C スキャン、リード/ライト、BME280 などのセンサー一括取得、OLED 表示をサポート
  • PWM 周波数・分解能の取得/更新に対応
  • 通信エラー・タイムアウト・プロトコル不整合・デバイスエラーなど統一例外を定義
  • 任意 JSON を送れる低レベル API command() を提供

動作環境

  • Python 3.8 以上
  • pyserial>=3.5
  • requests>=2.25.0
  • 対応する ESP32-S3 ファームウェア

インストール

pip install esp32io

クイックスタート

USB シリアル接続

from esp32io import ESP32S3IOSerial

esp = ESP32S3IOSerial("COM4", debug=False)

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

esp.close()

Wi-Fi (HTTP) 接続

from esp32io import ESP32S3IONet

esp = ESP32S3IONet("192.168.1.10", debug=False)

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

esp.close()

サンプル実行:

py -m examples.serial_example

API 一覧(主要メソッド)

  • ESP32S3IOSerial(port, baud=115200, timeout=2.0, debug=False, recv_timeout=None)
  • ESP32S3IONet(address, timeout=2.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()
  • close()

例外

  • ESP32S3IOError(基底クラス)
  • ESP32S3IONetworkError / ESP32S3IOSerialError
  • ESP32S3IOProtocolError
  • ESP32S3IODeviceError

必要なファームウェアコマンド

  • ping
  • read_di / set_do
  • read_adc
  • set_pwm / get_pwm_config / set_pwm_config
  • led_off / get_led_state / set_led_mode / set_rgb
  • get_io_state
  • i2c_scan / i2c_read / i2c_write
  • get_sensors
  • set_oled
  • get_status
  • help

プロジェクト構成

.
├── esp32io/
│   ├── __init__.py
│   ├── client.py
│   ├── exceptions.py
│   └── protocol.py
├── examples/
│   ├── serial_example.py
│   ├── i2c_example.py
│   └── wifi_example.py
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md

ファームウェア

このパッケージには ESP32 側ファームウェアは含まれていません。
以下の JSON プロトコル対応ファームウェアを使用してください。

https://github.com/noritama-lab/esp32io-firmware


ライセンス

MIT License
Copyright (c) 2026 Noritama-Lab


English

ESP32IO is a lightweight Python client for controlling an ESP32-S3 over USB serial or Wi-Fi (HTTP).
When paired with firmware that accepts JSON commands, it provides a unified API for DIO, ADC, PWM, RGB LED, I2C, sensors, and OLED control.

Features

  • Unified support for USB serial and HTTP communication
  • JSON protocol abstracted by ESP32S3IOSerial and ESP32S3IONet
  • Supports DIO, ADC, PWM, RGB LED, and full I/O state reads
  • I2C scanning, raw read/write, sensor batch reads, and OLED control
  • PWM frequency/resolution read & update
  • Unified exceptions for communication, protocol, and device errors
  • Low-level command() API for custom JSON commands

Requirements

  • Python 3.8+
  • pyserial>=3.5
  • requests>=2.25.0
  • Compatible ESP32-S3 firmware

Installation

pip install esp32io

Quick Start

(USB / Wi-Fi examples remain the same as Japanese section)

License

MIT License
Copyright (c) 2026 Noritama-Lab

Metadata

Release files for esp32io 0.1.4

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 0.1.4
File Size Uploaded Provenance Actions
esp32io-0.1.4.tar.gz 11.2 kB Without provenance Details for esp32io-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for esp32io 0.1.4
File Interpreter ABI Platform Actions
esp32io-0.1.4-py3-none-any.whl Python 3 none any Details for esp32io-0.1.4-py3-none-any.whl

Total release size: 21.2 kB

Release files / esp32io-0.1.4.tar.gz

Download URL esp32io-0.1.4.tar.gz
Size 11.2 kB
Tags Source
SHA-256 checksum
How to use checksums
576058d4e0182857228bb84d87c94e8366f5ef0a895f7f0e5469fd1086bf0014
BLAKE2b-256 checksum
How to use checksums
e2d7fea569f50dd6534d0a96822e4adce40ea86c6d813319d28d20adeca82135
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.14

Release files / esp32io-0.1.4-py3-none-any.whl

Download URL esp32io-0.1.4-py3-none-any.whl
Size 10.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
efd80bfbb1957fb113b8e5f8885183feff5ea33a8c68472966f6ad2708c91ed6
BLAKE2b-256 checksum
How to use checksums
c9d784744f0bfc3301c9e56c64d000f7538433a33681f2fc9290f1e8447a83b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.14

Security for esp32io 0.1.4

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.

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