Metadata-Version: 2.4
Name: vassar-feetech-servo-sdk
Version: 0.2.2
Summary: Vassar College's Python SDK for Feetech servo control and position reading
Author-email: Vassar Robotics <hello@vassarrobotics.com>
Maintainer-email: Vassar Robotics <hello@vassarrobotics.com>
License: MIT
Project-URL: Homepage, https://github.com/vassar-robotics/feetech-servo-sdk
Project-URL: Repository, https://github.com/vassar-robotics/feetech-servo-sdk
Project-URL: Issues, https://github.com/vassar-robotics/feetech-servo-sdk/issues
Keywords: robotics,servo,feetech,serial,hardware,sts,hls,control
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
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: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Requires-Dist: build>=0.9; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Vassar Feetech Servo SDK

A comprehensive Python SDK and command-line tool for controlling Feetech servos (STS/HLS series).

## Features

- 🔌 **Auto-detection** of serial ports
- 🎯 **Support for STS and HLS servos** (HLS includes torque control)
- 📖 **Read positions** from single or multiple servos  
- 🎯 **Set middle position** - Calibrate servos to position 2048
- ✍️ **Write position targets** (coming soon)
- 💪 **Write torque targets** (coming soon)
- 🚀 **High-performance** group sync operations
- 📊 **Real-time monitoring** with configurable update rates
- 🐍 **Clean Python API** with servo configuration at initialization
- 💻 **Command-line interface** for all operations
- 🔧 **Context manager support** for clean resource management

## Installation

### From PyPI

```bash
pip install vassar-feetech-servo-sdk
```

### From Source

```bash
git clone https://github.com/vassar-robotics/feetech-servo-sdk.git
cd feetech-servo-sdk
pip install -e .
```

## Dependencies

- Python >= 3.7
- pyserial >= 3.5

Note: The `scservo_sdk` is bundled with this package, so no separate installation is needed.

## Quick Start

### Command Line Usage

```bash
# Read from motors 1-6 continuously at 30Hz
vassar-servo

# Set all servos to middle position
vassar-servo --set-middle

# Read from specific motors at 60Hz
vassar-servo --motor-ids 1,3,5 --hz 60

# Use HLS servos (default is STS)
vassar-servo --servo-type hls

# Read once and exit
vassar-servo --once

# Output JSON format (useful for scripting)
vassar-servo --once --json
```

### Python API Usage

```python
from vassar_feetech_servo_sdk import ServoController

# Initialize controller with your servo configuration
servo_ids = [1, 2, 3, 4, 5, 6]
controller = ServoController(servo_ids=servo_ids, servo_type="sts")  # or "hls"
controller.connect()

# Read all configured servos
positions = controller.read_all_positions()
for motor_id, pos in positions.items():
    print(f"Motor {motor_id}: {pos} ({pos/4095*100:.1f}%)")

# Set servos to middle position
success = controller.set_middle_position()
if success:
    print("All servos calibrated to middle position!")

controller.disconnect()

# Using context manager
with ServoController([1, 2, 3], "sts") as controller:
    positions = controller.read_all_positions()
    print(positions)

# Continuous reading with callback
def my_callback(positions):
    print(f"Got positions: {positions}")

with ServoController([1, 2, 3], "hls") as controller:
    controller.read_positions_continuous(
        callback=my_callback,
        frequency=50.0
    )
```

### Advanced Usage

```python
# Initialize with specific configuration
controller = ServoController(
    servo_ids=[1, 2, 3, 4, 5, 6],
    servo_type="hls",  # 'sts' or 'hls'
    port="/dev/ttyUSB0",
    baudrate=1000000
)

# Error handling
from vassar_feetech_servo_sdk import ServoReaderError, PortNotFoundError

try:
    controller = ServoController([1, 2, 3], "sts")
    controller.connect()
    positions = controller.read_all_positions()
except PortNotFoundError:
    print("No servo port found!")
except ServoReaderError as e:
    print(f"Error: {e}")
```

## API Reference

### ServoController Class

#### Constructor

```python
ServoController(servo_ids, servo_type="sts", port=None, baudrate=1000000)
```

- `servo_ids`: List of servo IDs to control (e.g., [1, 2, 3, 4, 5, 6])
- `servo_type`: Type of servo - 'sts' or 'hls' (default: 'sts')
- `port`: Serial port path (auto-detect if None)
- `baudrate`: Communication speed (default: 1000000)

#### Methods

- `connect()`: Establish connection to servos
- `disconnect()`: Close connection
- `read_position(motor_id)`: Read single motor position
- `read_positions(motor_ids=None)`: Read multiple motor positions
- `read_all_positions()`: Read all configured servo positions
- `set_middle_position(motor_ids=None)`: Calibrate servos to middle position (2048)
- `read_positions_continuous(motor_ids=None, callback=None, frequency=30.0)`: Continuously read positions

### Utility Functions

- `find_servo_port()`: Auto-detect servo serial port

## Servo Types

- **STS**: Standard Feetech servos (default) - position and speed control
  - Middle position calibration uses torque=128 method
- **HLS**: High-end servos with additional torque control capabilities
  - Middle position calibration uses offset calibration (`reOfsCal`) method

## Troubleshooting

### Port Not Found

If auto-detection fails, specify the port manually:

```bash
# Linux
vassar-servo --port /dev/ttyUSB0

# macOS
vassar-servo --port /dev/tty.usbserial-*

# Windows
vassar-servo --port COM3
```

### Permission Denied (Linux)

Add your user to the dialout group:

```bash
sudo usermod -a -G dialout $USER
# Log out and back in for changes to take effect
```

### Connection Failed

1. Check servo power supply
2. Verify baudrate matches servo configuration (default: 1000000)
3. Ensure proper wiring (TX/RX not swapped)

## Examples

The package includes several example scripts in the `examples/` directory:

- `basic_usage.py` - Simple example showing how to connect and read servo positions
- `continuous_reading.py` - Real-time monitoring with custom callbacks
- `servo_types.py` - Demonstrates differences between STS and HLS servos
- `set_middle_position.py` - Shows how to calibrate servos to middle position



## Acknowledgments

Built on top of the excellent `scservo_sdk` library for Feetech servo communication.
