esp32io 0.1.0__py3-none-any.whl

esp32io/__init__.py

@@ -0,0 +1,13 @@
+from .client import ESP32IO
+from .exceptions import (
+    ESP32IOError,
+    ESP32IOTimeoutError,
+    ESP32IOProtocolError,
+)
+
+__all__ = [
+    "ESP32IO",
+    "ESP32IOError",
+    "ESP32IOTimeoutError",
+    "ESP32IOProtocolError",
+]

esp32io/client.py

@@ -0,0 +1,218 @@
+import serial
+import json
+import time
+from typing import Any, Dict, Optional
+
+from .exceptions import (
+    ESP32IOError,
+    ESP32IOTimeoutError,
+    ESP32IOProtocolError,
+)
+
+class ESP32IO:
+    """
+    ESP32 と JSON ベースのシリアルプロトコルで通信するクライアント。
+
+    想定プロトコル:
+      PC -> ESP32: {"cmd": "read_di", "pin_id": 0}
+      ESP32 -> PC: {"status": "ok", "value": 1}
+
+      PC -> ESP32: {"cmd": "set_pwm", "pin_id": 0, "duty": 128}
+      ESP32 -> PC: {"status": "ok"}
+    """
+
+    def __init__(
+        self,
+        port: str,
+        baud: int = 115200,
+        timeout: float = 2.0,
+        debug: bool = False,
+        recv_timeout: Optional[float] = None,
+    ) -> None:
+        """
+        :param port: 例: "COM5" や "/dev/ttyUSB0"
+        :param baud: ボーレート (デフォルト: 115200)
+        :param timeout: pyserial の read タイムアウト秒数
+        :param debug: True にすると送受信ログを表示
+        :param recv_timeout: _safe_recv 内での最大待ち時間（秒）。
+                             None の場合は無制限ループ（pyserial の timeout に依存）
+        """
+        self.debug = debug
+        self.ser = serial.Serial(port, baudrate=baud, timeout=timeout)
+        self.recv_timeout = recv_timeout
+
+        # ESP32 側のリセット直後のゴミを捨てる
+        time.sleep(0.5)
+        self.ser.reset_input_buffer()
+
+        # ウォームアップ: ping を投げて応答を捨てる（失敗しても無視）
+        try:
+            self._send({"cmd": "ping"})
+            self._safe_recv()
+        except Exception:
+            pass
+
+    # ------------------------------
+    # 内部ユーティリティ
+    # ------------------------------
+    def _log(self, *args: Any) -> None:
+        if self.debug:
+            print("[ESP32IO]", *args)
+
+    def _send(self, obj: Dict[str, Any]) -> None:
+        """JSON オブジェクトを 1 行の JSON として送信する"""
+        line = json.dumps(obj, separators=(",", ":")) + "\n"
+        self._log("SEND:", line.strip())
+        data = line.encode("utf-8")
+
+        total = 0
+        while total < len(data):
+            written = self.ser.write(data[total:])
+            if written == 0:
+                raise ESP32IOProtocolError("Failed to write to serial port")
+            total += written
+
+    def _safe_recv(self) -> Dict[str, Any]:
+        """
+        空行を無視し、JSON を返すまで待つ。
+        - status=error の場合は ESP32IOError を送出
+        - recv_timeout を超えた場合は ESP32IOTimeoutError を送出
+        - 不正 JSON の場合は ESP32IOProtocolError を送出
+        """
+        start = time.perf_counter()
+
+        while True:
+            if self.recv_timeout is not None:
+                if (time.perf_counter() - start) > self.recv_timeout:
+                    raise ESP32IOTimeoutError("Timeout waiting for response from ESP32")
+
+            line_bytes = self.ser.readline()
+            if not line_bytes:
+                # pyserial の timeout による空読み。recv_timeout が None なら継続。
+                if self.recv_timeout is None:
+                    continue
+                # recv_timeout 管理は上の if でやっているのでここでは単に continue
+                continue
+
+            try:
+                line = line_bytes.decode("utf-8", errors="replace").strip()
+            except UnicodeDecodeError as e:
+                raise ESP32IOProtocolError(f"Invalid UTF-8 from ESP32: {line_bytes!r}") from e
+
+            if not line:
+                # 空行は無視
+                continue
+
+            self._log("RECV:", line)
+
+            # JSON パース
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise ESP32IOProtocolError(f"Invalid JSON from ESP32: {line}") from e
+
+            # エラー応答なら例外
+            if data.get("status") == "error":
+                code = data.get("code", "UNKNOWN")
+                detail = data.get("detail", "")
+                raise ESP32IOError(f"{code}: {detail}")
+
+            # 正常応答
+            return data
+
+    def command(self, cmd: str, **kwargs: Any) -> Dict[str, Any]:
+        """
+        任意のコマンドを送信し、JSON 応答を返す低レベル API。
+
+        :param cmd: "read_di" など
+        :param kwargs: 追加パラメータ
+        :return: ESP32 からの JSON 応答
+        """
+        req: Dict[str, Any] = {"cmd": cmd}
+        req.update(kwargs)
+        self._send(req)
+        return self._safe_recv()
+
+    # ------------------------------
+    # 基本4コマンド（公開 API）
+    # ------------------------------
+    def read_di(self, pin_id: int) -> int:
+        """
+        デジタル入力を読む。
+
+        :param pin_id: ピン番号（ESP32 側の定義に依存）
+        :return: 0 or 1
+        """
+        res = self.command("read_di", pin_id=pin_id)
+        value = res.get("value")
+        if not isinstance(value, int):
+            raise ESP32IOProtocolError(f"Invalid read_di response: {res}")
+        return value
+
+    def set_do(self, pin_id: int, value: int) -> Dict[str, Any]:
+        """
+        デジタル出力を書き込む。
+
+        :param pin_id: ピン番号
+        :param value: 0 or 1
+        :return: ESP32 の生 JSON 応答
+        """
+        return self.command("set_do", pin_id=pin_id, value=value)
+
+    def read_adc(self, pin_id: int) -> int:
+        """
+        ADC を読む。
+
+        :param pin_id: ピン番号
+        :return: ADC 値（0〜4095 など、ESP32 側の仕様に依存）
+        """
+        res = self.command("read_adc", pin_id=pin_id)
+        value = res.get("value")
+        if not isinstance(value, int):
+            raise ESP32IOProtocolError(f"Invalid read_adc response: {res}")
+        return value
+
+    def set_pwm(self, pin_id: int, duty: int) -> Dict[str, Any]:
+        """
+        PWM デューティを設定する。
+
+        :param pin_id: ピン番号
+        :param duty: デューティ値（0〜255 など、ESP32 側の仕様に依存）
+        :return: ESP32 の生 JSON 応答
+        """
+        return self.command("set_pwm", pin_id=pin_id, duty=duty)
+    
+    # ------------------------------
+    # 全データ取得コマンド（公開 API）
+    # ------------------------------
+    def get_io_state(self):
+        """
+        ESP32 の全 I/O 状態をまとめて取得する。
+        戻り値:
+            dio_in  : list[int] (len=6)
+            dio_out : list[int] (len=6)
+            adc     : list[int] (len=2)
+            pwm     : list[int] (len=2)
+        """
+        res = self.command("get_io_state")
+
+        return {
+            "dio_in":  list(res["dio_in"]),
+            "dio_out": list(res["dio_out"]),
+            "adc":     list(res["adc"]),
+            "pwm":     list(res["pwm"]),
+        }
+
+    # ------------------------------
+    # 後片付け
+    # ------------------------------
+    def close(self) -> None:
+        """シリアルポートを閉じる"""
+        if self.ser and self.ser.is_open:
+            self.ser.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

esp32io/exceptions.py

@@ -0,0 +1,11 @@
+class ESP32IOError(Exception):
+    """ESP32 が status=error を返したときの例外"""
+    pass
+
+class ESP32IOTimeoutError(TimeoutError):
+    """ESP32 からの応答がタイムアウトしたときの例外"""
+    pass
+
+class ESP32IOProtocolError(RuntimeError):
+    """ESP32 から不正な JSON や予期しない応答が返ったときの例外"""
+    pass

esp32io/protocol.py

@@ -0,0 +1 @@
+# 機能拡張用

esp32io-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: esp32io
+Version: 0.1.0
+Summary: ESP32IO is a Python API that turns an ESP32‑S3 into a USB‑connected I/O device.
+Author: Noritama-Lab
+License: MIT
+Project-URL: Repository, https://github.com/Noritama-Lab/esp32io-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: pyserial>=3.5
+Dynamic: license-file
+
+# ESP32IO Python API  
+日本語 / English
+
+---
+
+## 🇯🇵 ESP32IO Python API
+
+ESP32IO は、ESP32‑S3 を USB で接続するだけで I/O デバイスとして扱える Python API です。  
+ESP32‑S3 側のファームウェアと組み合わせることで、JSON コマンドを意識せずに Python から I/O を安全かつ直感的に操作できます。
+
+### 特徴
+
+- USB シリアル経由で I/O を制御  
+- JSON ベースの通信プロトコルを API 内部で抽象化  
+- ADC / PWM / DIO（入力・出力）を Python から簡単に操作  
+- エラー処理・タイムアウト処理を統一  
+- 全 I/O 状態を取得できる get_io_state()  
+- 初回動作確認用のサンプルコード付き  
+
+### リポジトリ構成
+
+```
+esp32io-api/
+├── esp32io/
+│   ├── __init__.py
+│   ├── client.py
+│   ├── exceptions.py
+│   └── protocol.py
+├── esp32io.egg-info
+├── examples
+│   └── samples.py
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+### 主なメソッド
+
+- read_di(pin_id) — デジタル入力  
+- set_do(pin_id, value) — デジタル出力  
+- read_adc(pin_id) — ADC 読み取り  
+- set_pwm(pin_id, duty) — PWM 出力  
+- get_io_state() — 全 I/O 状態の取得  
+
+### 使用例：ADC の値で LED の明るさを制御
+
+```python
+from esp32io import ESP32IO
+import time
+import serial
+
+def main():
+    try:
+        esp = ESP32IO("COM3", debug=False)
+        print("ESP32 に接続しました。")
+
+        while True:
+            adc_value = esp.read_adc(0)
+            duty = int(adc_value / 4095 * 255)
+            esp.set_pwm(0, duty)
+
+            print(f"ADC={adc_value}, PWM duty={duty}")
+            time.sleep(0.05)
+
+    except serial.SerialException as e:
+        print("ERROR: ESP32 に接続できませんでした。")
+        print("理由:", e)
+
+    finally:
+        try:
+            esp.set_pwm(0, 0)
+        except:
+            pass
+        print("終了しました。PWM を停止しました。")
+
+if __name__ == "__main__":
+    main()
+```
+
+### ESP32‑S3 ファームウェア
+
+この API は、以下のファームウェアと連携して動作します：  
+https://github.com/noritama-lab/esp32io-firmware
+
+### ライセンス
+
+MIT License  
+Copyright (c) 2026 Noritama-Lab
+
+---
+
+## 🇺🇸 ESP32IO Python API
+
+ESP32IO is a Python API that turns an ESP32‑S3 into a USB‑connected I/O device.  
+With the corresponding firmware, you can control I/O safely and intuitively without handling JSON commands directly.
+
+### Features
+
+- I/O control over USB serial  
+- JSON protocol fully abstracted inside the API  
+- Easy access to ADC / PWM / DIO (input/output)  
+- Unified error handling and timeout management  
+- get_io_state() for full I/O monitoring  
+- Includes sample code for quick testing  
+
+### Repository Structure
+
+```
+esp32io-api/
+├── esp32io/
+│   ├── __init__.py
+│   ├── client.py
+│   ├── exceptions.py
+│   └── protocol.py
+├── esp32io.egg-info
+├── examples
+│   └── samples.py
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+### Main Methods
+
+- read_di(pin_id) — Digital input  
+- set_do(pin_id, value) — Digital output  
+- read_adc(pin_id) — Read ADC  
+- set_pwm(pin_id, duty) — PWM output  
+- get_io_state() — Get all I/O states  
+
+### Example: Control LED brightness using ADC input
+
+```python
+from esp32io import ESP32IO
+import time
+import serial
+
+def main():
+    try:
+        esp = ESP32IO("COM3", debug=False)
+        print("Connected to ESP32.")
+
+        while True:
+            adc_value = esp.read_adc(0)
+            duty = int(adc_value / 4095 * 255)
+            esp.set_pwm(0, duty)
+
+            print(f"ADC={adc_value}, PWM duty={duty}")
+            time.sleep(0.05)
+
+    except serial.SerialException as e:
+        print("ERROR: Could not connect to ESP32.")
+        print("Reason:", e)
+
+    finally:
+        try:
+            esp.set_pwm(0, 0)
+        except:
+            pass
+        print("Finished. PWM stopped.")
+
+if __name__ == "__main__":
+    main()
+```
+
+### ESP32‑S3 Firmware
+
+This API works with the following firmware:  
+https://github.com/noritama-lab/esp32io-firmware
+
+### License
+
+MIT License  
+Copyright (c) 2026 Noritama-Lab

esp32io-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+esp32io/__init__.py,sha256=kRf_jVE90UdfgDNdLGkPzNZZMMeX8BRdHafkc55eAj8,243
+esp32io/client.py,sha256=RO1go-xQOlg065GSHxLLHnvZJpNWZke1L3BhJ36wCmc,7318
+esp32io/exceptions.py,sha256=S3bapZmMTvUoWFPkZ6OYIDccXnoRw92dEUtRtVJE_e0,378
+esp32io/protocol.py,sha256=hYlzZ9X2arcEXs9_Xl6CD5qEjDtuxVvohYBoCsKlwmQ,17
+esp32io-0.1.0.dist-info/licenses/LICENSE,sha256=_-xJy5Ci_fk_7cVE6rgIC23vs9BXFrLWAb9QcH0_4PM,1069
+esp32io-0.1.0.dist-info/METADATA,sha256=BWb78GGqvdC0nmYEia1f3OpKoAulB6NN2AO9GM1EDpk,5421
+esp32io-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+esp32io-0.1.0.dist-info/top_level.txt,sha256=AftDH3OIXC1Ske5FXRY7OFgPb89fSpvy9itBd1DUoI0,8
+esp32io-0.1.0.dist-info/RECORD,,

esp32io-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

esp32io-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noritama-Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esp32io-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+esp32io