robotclaw 0.1.0__tar.gz

robotclaw-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-15
+
+### Added
+
+- `ServoBus` — LOBOT LX serial bus servo protocol driver
+  - Frame building, checksum, thread-safe read/write
+  - Commands: move, read position/voltage/temperature, load/unload, scan
+- `RobotConfig` — Hardware configuration data classes
+  - `JointConfig`, `LegConfig`, `RobotConfig` with JSON serialization
+  - `DEFAULT_CONFIG` — 10 servos, dual-leg biped layout
+- `Robot` — High-level robot controller
+  - Joint-level control with automatic direction/offset mapping
+  - Context manager support
+  - Batch operations: go_home, get_positions, set_joints
+- **Motion Recorder** subsystem
+  - `MotionRecorder` — Keyframe-based motion teaching
+  - `MotionPlayer` — Playback with variable speed control
+  - `MotionClip` / `Keyframe` — JSON-serializable data model
+- **CLI tools**
+  - `roboclaw-scan` — Servo bus diagnostic scanner
+  - `roboclaw-teach` — Interactive motion teaching terminal
+- **OpenClaw integration**
+  - `OpenClawSkill` — Skill adapter for OpenClaw AI agent platform
+  - `SKILL.md` — OpenClaw skill descriptor file

robotclaw-0.1.0/LICENSE

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

robotclaw-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include CHANGELOG.md

robotclaw-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: robotclaw
+Version: 0.1.0
+Summary: Bridge OpenClaw AI agents with physical servo robots — connecting the digital mind to the physical world
+Author: RoboClaw Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/roboclaw-project/roboclaw
+Project-URL: Repository, https://github.com/roboclaw-project/roboclaw
+Project-URL: Issues, https://github.com/roboclaw-project/roboclaw/issues
+Project-URL: Changelog, https://github.com/roboclaw-project/roboclaw/blob/main/CHANGELOG.md
+Keywords: openclaw,robot,servo,ai-agent,robotics,lobot,bus-servo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# 🦾 RoboClaw
+
+> Bridge OpenClaw AI agents with physical servo robots — connecting the digital mind to the physical world.
+
+**RoboClaw** 是一个 Python 库，将 [OpenClaw](https://openclaw.ai) 自主 AI 代理平台与 LOBOT LX 总线舵机机器人深度集成。通过 `pip install roboclaw`，即可让 AI 获得控制物理机器人的能力。
+
+---
+
+## ✨ Features
+
+- 🔌 **LOBOT LX Protocol Driver** — Full implementation of the LX serial bus servo protocol
+- 🤖 **High-Level Robot API** — Joint-level control with direction/offset mapping
+- 🎬 **Motion Teaching** — Record, save, and playback robot movements with variable speed
+- 🧠 **OpenClaw Integration** — Skill adapter for AI agent → robot control
+- 🛠️ **CLI Tools** — `roboclaw-scan` for diagnostics, `roboclaw-teach` for interactive teaching
+- ⚡ **Thread-Safe** — All serial operations protected by mutex locks
+
+## 📦 Installation
+
+```bash
+pip install roboclaw
+```
+
+
+For development:
+```bash
+pip install roboclaw[dev]
+``` 
+
+## 🚀 Quick Start
+
+### Basic Servo Control
+
+```python
+from roboclaw import ServoBus
+
+# Connect to servo bus
+bus = ServoBus()
+bus.connect("COM3", baudrate=115200)
+
+# Move servo ID=1 to position 500 in 1 second
+bus.move(servo_id=1, position=500, time_ms=1000)
+
+# Read current position
+pos = bus.read_position(servo_id=1)
+print(f"Position: {pos}")
+
+bus.disconnect()
+```
+
+### High-Level Robot Control
+
+```python
+from roboclaw import Robot, DEFAULT_CONFIG
+
+with Robot(config=DEFAULT_CONFIG, port="COM3") as robot:
+    # All joints to home position
+    robot.go_home(time_ms=2000)
+
+    # Move a single joint
+    robot.set_joint("left_hip_pitch", position=350, time_ms=500)
+
+    # Read all joint positions
+    positions = robot.get_positions()
+    print(positions)
+```
+
+### Motion Teaching & Playback
+
+```python
+from roboclaw import Robot, DEFAULT_CONFIG
+from roboclaw.recorder import MotionRecorder, MotionPlayer
+
+with Robot(config=DEFAULT_CONFIG, port="COM3") as robot:
+    # Record a motion
+    recorder = MotionRecorder(robot)
+    recorder.start_recording("wave_hand")
+
+    robot.unload_all()          # Let user pose the robot
+    input("Press Enter to capture frame 1...")
+    recorder.capture_frame()
+
+    input("Press Enter to capture frame 2...")
+    recorder.capture_frame()
+
+    clip = recorder.finish_recording()
+    recorder.save(clip, "motions/wave_hand.json")
+
+    # Play it back at 1.5x speed
+    robot.load_all()
+    player = MotionPlayer(robot)
+    player.play(clip, speed=1.5)
+```
+
+### CLI Tools
+
+```bash
+# Scan for connected servos
+roboclaw-scan --port COM3
+
+# Interactive motion teaching
+roboclaw-teach --port COM3
+```
+
+## 🧠 OpenClaw Integration
+
+RoboClaw ships with a built-in [OpenClaw](https://openclaw.ai) skill that allows AI agents to control the robot through natural language commands:
+
+```
+You: "让机器人回到初始位置"
+AI:  → robot.go_home(2000) ✅
+
+You: "播放走路动作，2倍速"
+AI:  → player.play(walk_clip, speed=2.0) ✅
+
+You: "检查所有舵机的电压"
+AI:  → robot.scan() → 报告电压状态 ✅
+```
+
+## 🔧 Hardware Requirements
+
+| Component | Specification |
+|-----------|---------------|
+| Servos | LOBOT LX-16A / LX-224 / LX-225 bus servos |
+| Interface | USB-to-TTL serial adapter |
+| Baudrate | 115200 (direct) or 9600 (controller board) |
+| Power | 6-8.4V DC, ≥5A for 10 servos |
+| Default Config | 10 servos, 5 per leg (biped) |
+
+## 📁 Project Structure
+
+```
+src/roboclaw/
+├── __init__.py          # Public API exports
+├── servo_bus.py         # LOBOT LX protocol driver
+├── robot_config.py      # Hardware configuration
+├── robot.py             # High-level robot controller
+├── cli.py               # CLI entry points
+├── openclaw_skill.py    # OpenClaw skill adapter
+├── SKILL.md             # OpenClaw skill descriptor
+└── recorder/            # Motion teaching subsystem
+    ├── motion_data.py   # Keyframe & MotionClip models
+    ├── recorder.py      # Motion recorder
+    └── player.py        # Motion player
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the [CHANGELOG](CHANGELOG.md) for recent changes.
+
+```bash
+# Clone and install in development mode
+git clone https://github.com/roboclaw-project/roboclaw.git
+cd roboclaw
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+```
+
+## 📄 License
+
+[MIT License](LICENSE)

robotclaw-0.1.0/README.md

@@ -0,0 +1,163 @@
+# 🦾 RoboClaw
+
+> Bridge OpenClaw AI agents with physical servo robots — connecting the digital mind to the physical world.
+
+**RoboClaw** 是一个 Python 库，将 [OpenClaw](https://openclaw.ai) 自主 AI 代理平台与 LOBOT LX 总线舵机机器人深度集成。通过 `pip install roboclaw`，即可让 AI 获得控制物理机器人的能力。
+
+---
+
+## ✨ Features
+
+- 🔌 **LOBOT LX Protocol Driver** — Full implementation of the LX serial bus servo protocol
+- 🤖 **High-Level Robot API** — Joint-level control with direction/offset mapping
+- 🎬 **Motion Teaching** — Record, save, and playback robot movements with variable speed
+- 🧠 **OpenClaw Integration** — Skill adapter for AI agent → robot control
+- 🛠️ **CLI Tools** — `roboclaw-scan` for diagnostics, `roboclaw-teach` for interactive teaching
+- ⚡ **Thread-Safe** — All serial operations protected by mutex locks
+
+## 📦 Installation
+
+```bash
+pip install roboclaw
+```
+
+
+For development:
+```bash
+pip install roboclaw[dev]
+``` 
+
+## 🚀 Quick Start
+
+### Basic Servo Control
+
+```python
+from roboclaw import ServoBus
+
+# Connect to servo bus
+bus = ServoBus()
+bus.connect("COM3", baudrate=115200)
+
+# Move servo ID=1 to position 500 in 1 second
+bus.move(servo_id=1, position=500, time_ms=1000)
+
+# Read current position
+pos = bus.read_position(servo_id=1)
+print(f"Position: {pos}")
+
+bus.disconnect()
+```
+
+### High-Level Robot Control
+
+```python
+from roboclaw import Robot, DEFAULT_CONFIG
+
+with Robot(config=DEFAULT_CONFIG, port="COM3") as robot:
+    # All joints to home position
+    robot.go_home(time_ms=2000)
+
+    # Move a single joint
+    robot.set_joint("left_hip_pitch", position=350, time_ms=500)
+
+    # Read all joint positions
+    positions = robot.get_positions()
+    print(positions)
+```
+
+### Motion Teaching & Playback
+
+```python
+from roboclaw import Robot, DEFAULT_CONFIG
+from roboclaw.recorder import MotionRecorder, MotionPlayer
+
+with Robot(config=DEFAULT_CONFIG, port="COM3") as robot:
+    # Record a motion
+    recorder = MotionRecorder(robot)
+    recorder.start_recording("wave_hand")
+
+    robot.unload_all()          # Let user pose the robot
+    input("Press Enter to capture frame 1...")
+    recorder.capture_frame()
+
+    input("Press Enter to capture frame 2...")
+    recorder.capture_frame()
+
+    clip = recorder.finish_recording()
+    recorder.save(clip, "motions/wave_hand.json")
+
+    # Play it back at 1.5x speed
+    robot.load_all()
+    player = MotionPlayer(robot)
+    player.play(clip, speed=1.5)
+```
+
+### CLI Tools
+
+```bash
+# Scan for connected servos
+roboclaw-scan --port COM3
+
+# Interactive motion teaching
+roboclaw-teach --port COM3
+```
+
+## 🧠 OpenClaw Integration
+
+RoboClaw ships with a built-in [OpenClaw](https://openclaw.ai) skill that allows AI agents to control the robot through natural language commands:
+
+```
+You: "让机器人回到初始位置"
+AI:  → robot.go_home(2000) ✅
+
+You: "播放走路动作，2倍速"
+AI:  → player.play(walk_clip, speed=2.0) ✅
+
+You: "检查所有舵机的电压"
+AI:  → robot.scan() → 报告电压状态 ✅
+```
+
+## 🔧 Hardware Requirements
+
+| Component | Specification |
+|-----------|---------------|
+| Servos | LOBOT LX-16A / LX-224 / LX-225 bus servos |
+| Interface | USB-to-TTL serial adapter |
+| Baudrate | 115200 (direct) or 9600 (controller board) |
+| Power | 6-8.4V DC, ≥5A for 10 servos |
+| Default Config | 10 servos, 5 per leg (biped) |
+
+## 📁 Project Structure
+
+```
+src/roboclaw/
+├── __init__.py          # Public API exports
+├── servo_bus.py         # LOBOT LX protocol driver
+├── robot_config.py      # Hardware configuration
+├── robot.py             # High-level robot controller
+├── cli.py               # CLI entry points
+├── openclaw_skill.py    # OpenClaw skill adapter
+├── SKILL.md             # OpenClaw skill descriptor
+└── recorder/            # Motion teaching subsystem
+    ├── motion_data.py   # Keyframe & MotionClip models
+    ├── recorder.py      # Motion recorder
+    └── player.py        # Motion player
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the [CHANGELOG](CHANGELOG.md) for recent changes.
+
+```bash
+# Clone and install in development mode
+git clone https://github.com/roboclaw-project/roboclaw.git
+cd roboclaw
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+```
+
+## 📄 License
+
+[MIT License](LICENSE)

robotclaw-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robotclaw"
+version = "0.1.0"
+description = "Bridge OpenClaw AI agents with physical servo robots — connecting the digital mind to the physical world"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "RoboClaw Contributors" },
+]
+keywords = ["openclaw", "robot", "servo", "ai-agent", "robotics", "lobot", "bus-servo"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pyserial>=3.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/roboclaw-project/roboclaw"
+Repository = "https://github.com/roboclaw-project/roboclaw"
+Issues = "https://github.com/roboclaw-project/roboclaw/issues"
+Changelog = "https://github.com/roboclaw-project/roboclaw/blob/main/CHANGELOG.md"
+
+[project.scripts]
+roboclaw-scan = "roboclaw.cli:scan_main"
+roboclaw-teach = "roboclaw.cli:teach_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

robotclaw-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

robotclaw-0.1.0/src/roboclaw/__init__.py

@@ -0,0 +1,21 @@
+"""RoboClaw - Bridge OpenClaw AI agents with physical servo robots.
+
+Connecting the digital mind to the physical world by integrating
+OpenClaw autonomous AI agent platform with LOBOT LX bus servo robots.
+"""
+
+__version__ = "0.1.0"
+
+from .servo_bus import ServoBus
+from .robot_config import JointConfig, LegConfig, RobotConfig, DEFAULT_CONFIG
+from .robot import Robot
+
+__all__ = [
+    "__version__",
+    "ServoBus",
+    "JointConfig",
+    "LegConfig",
+    "RobotConfig",
+    "DEFAULT_CONFIG",
+    "Robot",
+]