# 3robotics SDK
[English](README.md) | [中文](README_zh.md)
A comprehensive Python SDK for AlphaDog robotic dog control, providing intuitive programming interfaces for robot motion control, parameter adjustment, and real-time interaction.
## System Requirements
**⚠️ Important: This SDK requires Python 3.9 specifically**
- **Python Version**: Python 3.9 (Required - other versions are not supported)
- **Operating System**: Windows, macOS, Linux
- **Network**: Robot and computer must be on the same network
## Installation
### Prerequisites
First, ensure you have Python 3.9 installed:
```bash
# Check Python version
python --version # Should show Python 3.9.x
# If you don't have Python 3.9, install it from python.org
# Quick version check using our tool
python check_python_version.py
```
### Install 3robotics SDK
```bash
# Install from PyPI
pip install 3robotics
# Or install from source
git clone https://github.com/3robotics/3robotics.git
cd 3robotics
pip install -e .
```
## Quick Start
1. **Network Setup**: Ensure your computer is on the same network as the robotic dog
2. **IP Configuration**: Note the IP address of the robotic dog (default: 10.10.10.10)
3. **Python Environment**: Verify Python 3.9 is active in your environment
### Basic Example
```python
from 3robotics import Dog
import time
# Connect to the robot dog
with Dog() as dog:
print("Connected to 3robotics!")
# Adjust standing height
dog.body_height = 0.25
time.sleep(2)
# Move forward slowly
dog.vx = 0.2
time.sleep(3)
# Stop movement
dog.vx = 0.0
# Restore default height
dog.set_parameters({'body_height': 0.23})
```
### Advanced Connection Options
```python
from 3robotics import Dog
# Connect with custom IP
dog = Dog(host="192.168.1.100")
# Connect with custom port
dog = Dog(host="10.10.10.10", port=9090)
# Use context manager for automatic cleanup
with Dog(host="10.10.10.10") as dog:
# Your robot control code here
pass
```
## Parameter Control Features
The SDK provides comprehensive parameter control capabilities:
### 1. Basic Motion Parameters
```python
dog.vx = 0.2 # Forward velocity (-1.0 to 1.0)
dog.vy = 0.1 # Lateral velocity (-1.0 to 1.0)
dog.wz = 0.1 # Rotational velocity (-1.0 to 1.0)
```
### 2. Posture Control
```python
dog.roll = 0.1 # Roll angle (-0.5 to 0.5)
dog.pitch = 0.1 # Pitch angle (-0.5 to 0.5)
dog.yaw = 0.1 # Yaw angle (-0.5 to 0.5)
dog.body_height = 0.25 # Body height (0.1 to 0.35)
```
### 3. Gait Parameters
```python
dog.foot_height = 0.08 # Foot lift height (0.0 to 0.15)
dog.swing_duration = 0.3 # Swing period (0.1 to 1.0)
dog.friction = 0.6 # Friction coefficient (0.1 to 1.0)
```
### 4. Advanced Control Features
Combined parameter settings:
```python
# Set gait parameters
dog.set_gait_params(
friction=0.6, # Friction coefficient
scale_x=1.2, # Support surface X scaling
scale_y=1.0 # Support surface Y scaling
)
# Set motion parameters
dog.set_motion_params(
swaying_duration=2.0, # Swaying period
jump_distance=0.3, # Jump distance
jump_angle=0.1 # Jump rotation angle
)
# Set control parameters
dog.set_control_params(
velocity_decay=0.8, # Velocity decay
collision_protect=1, # Collision protection
decelerate_time=2.0, # Deceleration delay
decelerate_duration=1.0 # Deceleration duration
)
```
## Example Programs
The `examples` directory contains comprehensive demonstrations:
### Available Examples
1. **`demo_basic_movement.py`** - Basic motion control and posture adjustment
2. **`demo_advanced_movement.py`** - Advanced motion parameters and gait control
3. **`demo_modes.py`** - User mode switching and state management
4. **`keyboard_control.py`** - Real-time keyboard control interface
5. **`test.py`** - System testing and validation
### Running Examples
```bash
# Navigate to the examples directory
cd examples
# Run basic movement demo
python demo_basic_movement.py
# Run keyboard control (requires pynput)
pip install pynput
python keyboard_control.py
# Run advanced movement demo
python demo_advanced_movement.py
```
### Keyboard Control
The keyboard control example provides real-time control:
- **W/S**: Forward/Backward movement
- **A/D**: Left/Right movement
- **Q/E**: Rotate left/right
- **R/F**: Increase/Decrease body height
- **SPACE**: Emergency stop
- **ESC**: Exit program
## API Reference
### Core Classes
- **`Dog`**: Main robot control interface
- **`UserMode`**: Robot operation modes (IDLE, TROT, etc.)
- **`DogController`**: Low-level parameter control
- **`ROSClient`**: ROS communication handler
### Key Methods
```python
# Robot connection
dog = Dog(host="10.10.10.10", port=9090)
dog.connect()
dog.disconnect()
# Parameter control
dog.set_parameters(params_dict)
dog.set_gait_params(friction=0.6, scale_x=1.2)
dog.set_motion_params(jump_distance=0.3)
dog.set_control_params(velocity_decay=0.8)
# State queries
current_state = dog.get_state()
position = (dog.x, dog.y, dog.z)
```
## Troubleshooting
### Common Issues
1. **Connection Failed**
- Check network connectivity
- Verify robot IP address
- Ensure robot is powered on and ready
2. **Python Version Error**
- This SDK requires Python 3.9 specifically
- Install Python 3.9 from [python.org](https://www.python.org/downloads/)
3. **Import Errors**
- Install required dependencies: `pip install -r requirements.txt`
- For keyboard control: `pip install pynput`
4. **Performance Issues**
- Reduce control frequency if network is slow
- Check robot battery level
- Minimize network interference
### Debug Mode
Enable debug logging for troubleshooting:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
from 3robotics import Dog
# Debug information will be printed
```
### Contributing
Issues and pull requests are welcome. For major changes, please open an issue first to discuss proposed changes.
### License
This project is licensed under the MIT License - see the `LICENSE` file for details.
### Contact
For questions or suggestions:
- Submit GitHub Issues
- Email: <towardsrwby@gmail.com>
Raw data
{
"_id": null,
"home_page": "https://github.com/3robotics/3robotics",
"name": "3robotics",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.9.*",
"maintainer_email": null,
"keywords": "robotics, alphadog, ros, robot control, python",
"author": "3robotics",
"author_email": "towardsrwby@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e1/5e/1cff13169ee2791962f9ce20498728986d7cdd8ce4318585acc2b730fa6c/3robotics-0.0.1.tar.gz",
"platform": null,
"description": "# 3robotics SDK\n\n[English](README.md) | [\u4e2d\u6587](README_zh.md)\n\nA comprehensive Python SDK for AlphaDog robotic dog control, providing intuitive programming interfaces for robot motion control, parameter adjustment, and real-time interaction.\n\n## System Requirements\n\n**\u26a0\ufe0f Important: This SDK requires Python 3.9 specifically**\n\n- **Python Version**: Python 3.9 (Required - other versions are not supported)\n- **Operating System**: Windows, macOS, Linux\n- **Network**: Robot and computer must be on the same network\n\n## Installation\n\n### Prerequisites\n\nFirst, ensure you have Python 3.9 installed:\n\n```bash\n# Check Python version\npython --version # Should show Python 3.9.x\n\n# If you don't have Python 3.9, install it from python.org\n\n# Quick version check using our tool\npython check_python_version.py\n```\n\n### Install 3robotics SDK\n\n```bash\n# Install from PyPI\npip install 3robotics\n\n# Or install from source\ngit clone https://github.com/3robotics/3robotics.git\ncd 3robotics\npip install -e .\n```\n\n## Quick Start\n\n1. **Network Setup**: Ensure your computer is on the same network as the robotic dog\n2. **IP Configuration**: Note the IP address of the robotic dog (default: 10.10.10.10)\n3. **Python Environment**: Verify Python 3.9 is active in your environment\n\n### Basic Example\n\n```python\nfrom 3robotics import Dog\nimport time\n\n# Connect to the robot dog\nwith Dog() as dog:\n print(\"Connected to 3robotics!\")\n \n # Adjust standing height\n dog.body_height = 0.25\n time.sleep(2)\n \n # Move forward slowly\n dog.vx = 0.2\n time.sleep(3)\n \n # Stop movement\n dog.vx = 0.0\n \n # Restore default height\n dog.set_parameters({'body_height': 0.23})\n```\n\n### Advanced Connection Options\n\n```python\nfrom 3robotics import Dog\n\n# Connect with custom IP\ndog = Dog(host=\"192.168.1.100\")\n\n# Connect with custom port\ndog = Dog(host=\"10.10.10.10\", port=9090)\n \n# Use context manager for automatic cleanup\nwith Dog(host=\"10.10.10.10\") as dog:\n # Your robot control code here\n pass\n```\n\n## Parameter Control Features\n\nThe SDK provides comprehensive parameter control capabilities:\n\n### 1. Basic Motion Parameters\n\n```python\ndog.vx = 0.2 # Forward velocity (-1.0 to 1.0)\ndog.vy = 0.1 # Lateral velocity (-1.0 to 1.0)\ndog.wz = 0.1 # Rotational velocity (-1.0 to 1.0)\n```\n\n### 2. Posture Control\n\n```python\ndog.roll = 0.1 # Roll angle (-0.5 to 0.5)\ndog.pitch = 0.1 # Pitch angle (-0.5 to 0.5)\ndog.yaw = 0.1 # Yaw angle (-0.5 to 0.5)\ndog.body_height = 0.25 # Body height (0.1 to 0.35)\n```\n\n### 3. Gait Parameters\n\n```python\ndog.foot_height = 0.08 # Foot lift height (0.0 to 0.15)\ndog.swing_duration = 0.3 # Swing period (0.1 to 1.0)\ndog.friction = 0.6 # Friction coefficient (0.1 to 1.0)\n```\n\n### 4. Advanced Control Features\n\nCombined parameter settings:\n\n```python\n# Set gait parameters\ndog.set_gait_params(\n friction=0.6, # Friction coefficient\n scale_x=1.2, # Support surface X scaling\n scale_y=1.0 # Support surface Y scaling\n)\n\n# Set motion parameters\ndog.set_motion_params(\n swaying_duration=2.0, # Swaying period\n jump_distance=0.3, # Jump distance\n jump_angle=0.1 # Jump rotation angle\n)\n\n# Set control parameters\ndog.set_control_params(\n velocity_decay=0.8, # Velocity decay\n collision_protect=1, # Collision protection\n decelerate_time=2.0, # Deceleration delay\n decelerate_duration=1.0 # Deceleration duration\n)\n```\n\n## Example Programs\n\nThe `examples` directory contains comprehensive demonstrations:\n\n### Available Examples\n\n1. **`demo_basic_movement.py`** - Basic motion control and posture adjustment\n2. **`demo_advanced_movement.py`** - Advanced motion parameters and gait control\n3. **`demo_modes.py`** - User mode switching and state management\n4. **`keyboard_control.py`** - Real-time keyboard control interface\n5. **`test.py`** - System testing and validation\n\n### Running Examples\n\n```bash\n# Navigate to the examples directory\ncd examples\n\n# Run basic movement demo\npython demo_basic_movement.py\n\n# Run keyboard control (requires pynput)\npip install pynput\npython keyboard_control.py\n\n# Run advanced movement demo\npython demo_advanced_movement.py\n```\n\n### Keyboard Control\n\nThe keyboard control example provides real-time control:\n\n- **W/S**: Forward/Backward movement\n- **A/D**: Left/Right movement \n- **Q/E**: Rotate left/right\n- **R/F**: Increase/Decrease body height\n- **SPACE**: Emergency stop\n- **ESC**: Exit program\n\n## API Reference\n\n### Core Classes\n\n- **`Dog`**: Main robot control interface\n- **`UserMode`**: Robot operation modes (IDLE, TROT, etc.)\n- **`DogController`**: Low-level parameter control\n- **`ROSClient`**: ROS communication handler\n\n### Key Methods\n\n```python\n# Robot connection\ndog = Dog(host=\"10.10.10.10\", port=9090)\ndog.connect()\ndog.disconnect()\n\n# Parameter control\ndog.set_parameters(params_dict)\ndog.set_gait_params(friction=0.6, scale_x=1.2)\ndog.set_motion_params(jump_distance=0.3)\ndog.set_control_params(velocity_decay=0.8)\n\n# State queries\ncurrent_state = dog.get_state()\nposition = (dog.x, dog.y, dog.z)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection Failed**\n - Check network connectivity\n - Verify robot IP address\n - Ensure robot is powered on and ready\n\n2. **Python Version Error**\n - This SDK requires Python 3.9 specifically\n - Install Python 3.9 from [python.org](https://www.python.org/downloads/)\n\n3. **Import Errors**\n - Install required dependencies: `pip install -r requirements.txt`\n - For keyboard control: `pip install pynput`\n\n4. **Performance Issues**\n - Reduce control frequency if network is slow\n - Check robot battery level\n - Minimize network interference\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\nfrom 3robotics import Dog\n# Debug information will be printed\n```\n\n### Contributing\n\nIssues and pull requests are welcome. For major changes, please open an issue first to discuss proposed changes.\n\n### License\n\nThis project is licensed under the MIT License - see the `LICENSE` file for details.\n\n### Contact\n\nFor questions or suggestions:\n\n- Submit GitHub Issues\n- Email: <towardsrwby@gmail.com>\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for controlling AlphaDog robotic dogs",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/3robotics/3robotics/issues",
"Documentation": "https://github.com/3robotics/3robotics/wiki",
"Homepage": "https://github.com/3robotics/3robotics",
"Source Code": "https://github.com/3robotics/3robotics"
},
"split_keywords": [
"robotics",
" alphadog",
" ros",
" robot control",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f42bb3b1bb3766cb69aa7efb2c7da18c66063c05514a0d18e7fa65bdffaf0088",
"md5": "5982fcb8fbd4f24bd78821aa63c7e1b0",
"sha256": "38361e89679c9edcdfe6f3e5cf23b4c28fe2bef0eca94735951dd1b119cb6010"
},
"downloads": -1,
"filename": "3robotics-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5982fcb8fbd4f24bd78821aa63c7e1b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.9.*",
"size": 12672,
"upload_time": "2025-07-28T17:51:35",
"upload_time_iso_8601": "2025-07-28T17:51:35.320744Z",
"url": "https://files.pythonhosted.org/packages/f4/2b/b3b1bb3766cb69aa7efb2c7da18c66063c05514a0d18e7fa65bdffaf0088/3robotics-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e15e1cff13169ee2791962f9ce20498728986d7cdd8ce4318585acc2b730fa6c",
"md5": "1b4184839f4329bc1d4a4a8d49bbb7fc",
"sha256": "7134e2f210ca2803b3573f2e8703e84dce9f13fb80247158f71b35bc27c7bc58"
},
"downloads": -1,
"filename": "3robotics-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1b4184839f4329bc1d4a4a8d49bbb7fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.9.*",
"size": 11258,
"upload_time": "2025-07-28T17:51:36",
"upload_time_iso_8601": "2025-07-28T17:51:36.620998Z",
"url": "https://files.pythonhosted.org/packages/e1/5e/1cff13169ee2791962f9ce20498728986d7cdd8ce4318585acc2b730fa6c/3robotics-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 17:51:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "3robotics",
"github_project": "3robotics",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"2.0.1"
]
]
},
{
"name": "pyserial",
"specs": [
[
">=",
"3.5"
]
]
},
{
"name": "pynput",
"specs": [
[
">=",
"1.7.6"
]
]
},
{
"name": "pygame",
"specs": [
[
">=",
"2.5.0"
]
]
}
],
"lcname": "3robotics"
}
JSON
