pytmrobot 0.1.0__tar.gz

pytmrobot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harry
+
+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.

pytmrobot-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: pytmrobot
+Version: 0.1.0
+Summary: Python API for controlling Techman (TM) robots via Listen Node — no TMScript required
+Author: Harry
+License: MIT License
+        
+        Copyright (c) 2026 Harry
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/harry123180/TMDemo
+Project-URL: Documentation, https://github.com/harry123180/TMDemo/blob/master/docs/wiki.md
+Project-URL: Repository, https://github.com/harry123180/TMDemo
+Project-URL: Bug Tracker, https://github.com/harry123180/TMDemo/issues
+Project-URL: Changelog, https://github.com/harry123180/TMDemo/blob/master/CHANGELOG.md
+Keywords: robot,techman,TM robot,collaborative robot,cobot,industrial automation,TMScript,Listen Node
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# pytmrobot
+
+**Python API for Techman (TM) Robots** — control your TM robot without writing TMScript.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[繁體中文說明文件](docs/wiki.md) | [Changelog](CHANGELOG.md)
+
+---
+
+## Features
+
+| Category | Capabilities |
+|---|---|
+| **Motion** | PTP, Line, Circle, relative moves, PVT trajectories |
+| **I/O** | Digital / analog output & input, batch read |
+| **State** | TCP position, joint angles, force, speed, snapshot |
+| **Force sensing** | TouchStop, Compliance, Force control (FTSensor) |
+| **Communication** | Modbus TCP read/write with named Presets |
+| **Vision** | Trigger vision jobs, read output poses |
+| **HMI** | Operator dialogs (choice + popup) |
+| **Multi-robot** | Each `TMRobot` instance is fully independent — run 12+ in parallel |
+
+---
+
+## Requirements
+
+- Python **3.10+**
+- TM Robot running **TMflow 1.80+** with a **Listen Node** in the flow
+- Network access to port **5890** on the robot controller
+
+No external dependencies — only the Python standard library.
+
+---
+
+## Installation
+
+```bash
+pip install pytmrobot
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/harry-techman/pytmrobot.git
+cd pytmrobot
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from pytmrobot import TMRobot, CartPoint
+
+with TMRobot("192.168.1.101") as robot:
+
+    home = CartPoint(400, -100, 500, 180, 0, 90)   # X, Y, Z, Rx, Ry, Rz
+    pick = CartPoint(400, -100, 280, 180, 0, 90)
+
+    robot.move.ptp(home, speed=30)       # point-to-point move, 30 %
+    robot.move.ptp(pick, speed=10)       # slow approach
+
+    robot.io.set_do(2, True)             # close gripper (DO[2] = 1)
+    robot.sleep(500)                     # wait 500 ms on robot side
+
+    robot.move.ptp(home, speed=30)
+    robot.io.set_do(2, False)            # open gripper
+
+    pos = robot.state.tcp_position       # read current TCP pose
+    print(f"Done — X={pos[0]:.1f}  Y={pos[1]:.1f}  Z={pos[2]:.1f} mm")
+```
+
+---
+
+## Sub-controllers
+
+| Property | Description |
+|---|---|
+| `robot.move` | PTP / Line / Circle / relative / PVT |
+| `robot.io` | DO, AO, DI, AI, batch read |
+| `robot.state` | TCP position, joints, force, speed, snapshot |
+| `robot.decision` | `ask()` choice dialog, `popup()` confirmation |
+| `robot.modbus` | Modbus TCP connect / preset / read / write |
+| `robot.touchstop` | TouchStop — detect contact and stop |
+| `robot.compliance` | Compliance — compliant motion until resistance |
+| `robot.force` | Force control with external FTSensor |
+| `robot.vision` | Trigger vision jobs, get output pose |
+
+---
+
+## More Examples
+
+### Read robot state
+
+```python
+s = robot.state.snapshot()
+print(s.tcp_position)   # (X, Y, Z, Rx, Ry, Rz)
+print(s.joint_angles)   # (J1 … J6)
+print(s.tcp_force_3d)   # resultant force N
+```
+
+### TouchStop — find workpiece surface
+
+```python
+result = robot.touchstop.run(
+    direction=32,    # Z−  (1=X+, 2=X−, 4=Y+, 8=Y−, 16=Z+, 32=Z−)
+    distance=50.0,   # max travel mm
+    force=5.0,       # contact threshold N
+    speed=10,
+)
+if result == 5:      # Resisted
+    z = robot.touchstop.get_stopped_pos()[2]
+    print(f"Surface at Z = {z:.2f} mm")
+```
+
+### Multi-robot (12 concurrent)
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+robots = [TMRobot(f"192.168.1.{100+i}") for i in range(12)]
+for r in robots:
+    r.connect()
+
+with ThreadPoolExecutor(max_workers=12) as pool:
+    futures = [pool.submit(run_task, r) for r in robots]
+    for f in futures:
+        f.result()
+
+for r in robots:
+    r.disconnect()
+```
+
+### Modbus TCP
+
+```python
+robot.modbus.connect("192.168.1.10")
+robot.modbus.preset("light", 1, "DO", 7206, "bool")
+robot.modbus.write("light", True)
+print(robot.modbus.read_bool("light"))
+robot.modbus.disconnect()
+```
+
+### Vision-guided pick
+
+```python
+if robot.vision.do_job("DetectPart"):
+    pose = robot.vision.get_output_pose("DetectPart", "ArmPose_0")
+    robot.move.ptp(CartPoint(*pose), speed=20)
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+All 259 tests run without a physical robot (mock-based unit tests).
+
+---
+
+## Documentation
+
+Full API reference and tutorials (繁體中文): [`docs/wiki.md`](docs/wiki.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pytmrobot-0.1.0/README.md

@@ -0,0 +1,176 @@
+# pytmrobot
+
+**Python API for Techman (TM) Robots** — control your TM robot without writing TMScript.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[繁體中文說明文件](docs/wiki.md) | [Changelog](CHANGELOG.md)
+
+---
+
+## Features
+
+| Category | Capabilities |
+|---|---|
+| **Motion** | PTP, Line, Circle, relative moves, PVT trajectories |
+| **I/O** | Digital / analog output & input, batch read |
+| **State** | TCP position, joint angles, force, speed, snapshot |
+| **Force sensing** | TouchStop, Compliance, Force control (FTSensor) |
+| **Communication** | Modbus TCP read/write with named Presets |
+| **Vision** | Trigger vision jobs, read output poses |
+| **HMI** | Operator dialogs (choice + popup) |
+| **Multi-robot** | Each `TMRobot` instance is fully independent — run 12+ in parallel |
+
+---
+
+## Requirements
+
+- Python **3.10+**
+- TM Robot running **TMflow 1.80+** with a **Listen Node** in the flow
+- Network access to port **5890** on the robot controller
+
+No external dependencies — only the Python standard library.
+
+---
+
+## Installation
+
+```bash
+pip install pytmrobot
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/harry-techman/pytmrobot.git
+cd pytmrobot
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from pytmrobot import TMRobot, CartPoint
+
+with TMRobot("192.168.1.101") as robot:
+
+    home = CartPoint(400, -100, 500, 180, 0, 90)   # X, Y, Z, Rx, Ry, Rz
+    pick = CartPoint(400, -100, 280, 180, 0, 90)
+
+    robot.move.ptp(home, speed=30)       # point-to-point move, 30 %
+    robot.move.ptp(pick, speed=10)       # slow approach
+
+    robot.io.set_do(2, True)             # close gripper (DO[2] = 1)
+    robot.sleep(500)                     # wait 500 ms on robot side
+
+    robot.move.ptp(home, speed=30)
+    robot.io.set_do(2, False)            # open gripper
+
+    pos = robot.state.tcp_position       # read current TCP pose
+    print(f"Done — X={pos[0]:.1f}  Y={pos[1]:.1f}  Z={pos[2]:.1f} mm")
+```
+
+---
+
+## Sub-controllers
+
+| Property | Description |
+|---|---|
+| `robot.move` | PTP / Line / Circle / relative / PVT |
+| `robot.io` | DO, AO, DI, AI, batch read |
+| `robot.state` | TCP position, joints, force, speed, snapshot |
+| `robot.decision` | `ask()` choice dialog, `popup()` confirmation |
+| `robot.modbus` | Modbus TCP connect / preset / read / write |
+| `robot.touchstop` | TouchStop — detect contact and stop |
+| `robot.compliance` | Compliance — compliant motion until resistance |
+| `robot.force` | Force control with external FTSensor |
+| `robot.vision` | Trigger vision jobs, get output pose |
+
+---
+
+## More Examples
+
+### Read robot state
+
+```python
+s = robot.state.snapshot()
+print(s.tcp_position)   # (X, Y, Z, Rx, Ry, Rz)
+print(s.joint_angles)   # (J1 … J6)
+print(s.tcp_force_3d)   # resultant force N
+```
+
+### TouchStop — find workpiece surface
+
+```python
+result = robot.touchstop.run(
+    direction=32,    # Z−  (1=X+, 2=X−, 4=Y+, 8=Y−, 16=Z+, 32=Z−)
+    distance=50.0,   # max travel mm
+    force=5.0,       # contact threshold N
+    speed=10,
+)
+if result == 5:      # Resisted
+    z = robot.touchstop.get_stopped_pos()[2]
+    print(f"Surface at Z = {z:.2f} mm")
+```
+
+### Multi-robot (12 concurrent)
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+robots = [TMRobot(f"192.168.1.{100+i}") for i in range(12)]
+for r in robots:
+    r.connect()
+
+with ThreadPoolExecutor(max_workers=12) as pool:
+    futures = [pool.submit(run_task, r) for r in robots]
+    for f in futures:
+        f.result()
+
+for r in robots:
+    r.disconnect()
+```
+
+### Modbus TCP
+
+```python
+robot.modbus.connect("192.168.1.10")
+robot.modbus.preset("light", 1, "DO", 7206, "bool")
+robot.modbus.write("light", True)
+print(robot.modbus.read_bool("light"))
+robot.modbus.disconnect()
+```
+
+### Vision-guided pick
+
+```python
+if robot.vision.do_job("DetectPart"):
+    pose = robot.vision.get_output_pose("DetectPart", "ArmPose_0")
+    robot.move.ptp(CartPoint(*pose), speed=20)
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+All 259 tests run without a physical robot (mock-based unit tests).
+
+---
+
+## Documentation
+
+Full API reference and tutorials (繁體中文): [`docs/wiki.md`](docs/wiki.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pytmrobot-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+# ── Project metadata ────────────────────────────────────────────────────────
+
+[project]
+name            = "pytmrobot"
+version         = "0.1.0"
+description     = "Python API for controlling Techman (TM) robots via Listen Node — no TMScript required"
+readme          = "README.md"
+license         = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors         = [{ name = "Harry" }]
+keywords        = [
+    "robot", "techman", "TM robot", "collaborative robot", "cobot",
+    "industrial automation", "TMScript", "Listen Node",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Manufacturing",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Hardware",
+    "Typing :: Typed",
+]
+
+# 無任何執行期依賴，僅需標準函式庫
+dependencies = []
+
+[project.urls]
+Homepage      = "https://github.com/harry123180/TMDemo"
+Documentation = "https://github.com/harry123180/TMDemo/blob/master/docs/wiki.md"
+Repository    = "https://github.com/harry123180/TMDemo"
+"Bug Tracker" = "https://github.com/harry123180/TMDemo/issues"
+Changelog     = "https://github.com/harry123180/TMDemo/blob/master/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "ruff>=0.4",
+]
+
+# ── Package discovery ───────────────────────────────────────────────────────
+
+[tool.setuptools.packages.find]
+include = ["pytmrobot*"]
+
+[tool.setuptools.package-data]
+pytmrobot = ["py.typed"]   # PEP 561 — 告知 mypy/pyright 本套件有 type hints
+
+# ── pytest ──────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths    = ["tests"]
+addopts      = "-q"
+
+# ── ruff（lint + format）────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length    = 100
+target-version = "py310"
+exclude        = [
+    ".git", "__pycache__", ".pytest_cache",
+    "chapters/", "examples/",
+]
+
+[tool.ruff.lint]
+# E/W = pycodestyle  F = pyflakes  I = isort  UP = pyupgrade  B = flake8-bugbear
+select  = ["E", "W", "F", "I", "UP", "B"]
+ignore  = [
+    "E501",   # line too long — 長字串 TMScript 不切割
+    "B008",   # do not perform function calls in argument defaults
+    "UP006",  # use `type` instead of `Type` — 兼容 3.10 TYPE_CHECKING 用法
+    "UP007",  # use `X | Y` — 保留 Union 在 TYPE_CHECKING 區塊
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pytmrobot"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# ── mypy（選用，嚴格模式）──────────────────────────────────────────────────
+
+[tool.mypy]
+python_version        = "3.10"
+strict                = false
+ignore_missing_imports = true

pytmrobot-0.1.0/pytmrobot/__init__.py

@@ -0,0 +1,89 @@
+"""
+pytmrobot — Python TM Robot 控制函式庫
+
+讓 Python 開發者無需了解 TMScript，直接以 Pythonic API 控制達明機器人。
+
+Quick Start::
+
+    from pytmrobot import TMRobot, CartPoint
+
+    with TMRobot("192.168.1.101") as robot:
+        home = CartPoint(400, -100, 500, 180, 0, 90)
+        pick = CartPoint(400, -100, 280, 180, 0, 90)
+
+        robot.move.ptp(home, speed=30)
+        robot.move.ptp(pick, speed=10)
+        robot.io.set_do(2, True)          # 夾爪閉合
+        robot.sleep(500)
+        robot.move.ptp(home, speed=30)
+        robot.io.set_do(2, False)         # 夾爪張開
+
+        pos = robot.state.tcp_position
+        print(f"完成！位置: X={pos[0]:.2f}, Y={pos[1]:.2f}, Z={pos[2]:.2f}")
+
+Public API
+----------
+主類別：
+    TMRobot         控制機器人的主要入口（支援 context manager）
+
+點位型別：
+    CartPoint       笛卡爾座標目標點 (X, Y, Z, Rx, Ry, Rz)
+    JointPoint      關節角度目標點 (J1, J2, J3, J4, J5, J6)
+
+列舉：
+    SpeedUnit       直線/圓弧速度單位 (PERCENT / ABS_SYNC / ABS_LOCK)
+    BlendUnit       軌跡混合單位 (PERCENT / RADIUS)
+
+資料容器：
+    RobotState      robot.state.snapshot() 的回傳型別
+    IOState         robot.io.get_all_io() 的回傳型別
+
+例外：
+    TMError         所有例外的基礎類別
+    TMConnectionError  連線失敗
+    TMScriptError   機器人回傳 ERROR
+    TMTimeoutError  等待逾時
+    TMValueError    參數超出範圍
+"""
+
+from .exceptions import (
+    TMConnectionError,
+    TMError,
+    TMScriptError,
+    TMTimeoutError,
+    TMValueError,
+)
+from .robot import TMRobot
+from .types import (
+    BlendUnit,
+    CartPoint,
+    IOState,
+    JointPoint,
+    Pose6,
+    RobotState,
+    SpeedUnit,
+)
+
+__version__ = "0.1.0"
+__author__  = "TMDemo Contributors"
+
+__all__ = [
+    # 主類別
+    "TMRobot",
+    # 點位型別
+    "CartPoint",
+    "JointPoint",
+    "Pose6",
+    # 列舉
+    "SpeedUnit",
+    "BlendUnit",
+    # 資料容器
+    "RobotState",
+    "IOState",
+    # 例外
+    "TMError",
+    "TMConnectionError",
+    "TMScriptError",
+    "TMTimeoutError",
+    "TMValueError",
+]