Metadata-Version: 2.4
Name: capybarish
Version: 0.1.0
Summary: Lightweight communication middleware for cloud-based robotics controllers
Author-email: Chen Yu <chenyu@u.northwestern.edu>
Maintainer-email: Chen Yu <chenyu@u.northwestern.edu>
License: Apache-2.0
Project-URL: Homepage, https://github.com/chenyu-northwestern/capybarish
Project-URL: Repository, https://github.com/chenyu-northwestern/capybarish.git
Project-URL: Bug Tracker, https://github.com/chenyu-northwestern/capybarish/issues
Project-URL: Research Paper, https://arxiv.org/abs/2505.00784
Keywords: robotics,middleware,communication,modular-robots,udp,real-time,cloud-robotics,distributed-systems
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: omegaconf>=2.1.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: rich>=10.0.0
Requires-Dist: pyyaml>=5.4.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: pre-commit>=2.15.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.17.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=6.0.0; extra == "test"
Requires-Dist: pytest-cov>=2.10.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "test"
Requires-Dist: pytest-mock>=3.6.0; extra == "test"
Dynamic: license-file

# 🦫 Capybarish

[![PyPI version](https://badge.fury.io/py/capybarish.svg)](https://badge.fury.io/py/capybarish)
[![Python Support](https://img.shields.io/pypi/pyversions/capybarish.svg)](https://pypi.org/project/capybarish/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![arXiv](https://img.shields.io/badge/arXiv-2505.00784-b31b1b.svg)](https://arxiv.org/abs/2505.00784)

**Capybarish** is a lightweight communication middleware designed for cloud-based robotics controllers. This MVP (Minimum Viable Product) was developed to support research on [reconfigurable legged metamachines](https://arxiv.org/abs/2505.00784) - modular robots that can dynamically reconfigure their morphology using autonomous modular legs.

## 🔬 Research Context

This package supports the research presented in ["Reconfigurable legged metamachines that run on autonomous modular legs"](https://arxiv.org/abs/2505.00784) by Chen Yu et al. The middleware enables real-time communication between cloud-based controllers and distributed modular robot components, facilitating the coordination of autonomous modular legs that can form complex legged metamachines.

## 🚀 Quick Start

### Installation

```bash
pip install capybarish
```

### Basic Usage

```python
from capybarish.interface import Interface
from capybarish.utils import load_cfg
import numpy as np

# Load configuration
config = load_cfg("default")

# Initialize the interface
interface = Interface(config)

# Basic control loop for modular robot communication
for i in range(100):
    # Receive sensor data from robot modules
    interface.receive_module_data()
    
    # Get observable data
    data = interface.get_observable_data()
    
    # Send control commands to modular legs
    action = np.array([0.1 * np.sin(i * 0.1)])
    interface.send_action(action, kps=np.array([10.0]), kds=np.array([1.0]))
```

### Configuration

Create a YAML configuration file in the `config/` directory:

```yaml
# config/default.yaml
interface:
  module_ids: [1, 2, 3]  # IDs of your modular robot components
  communication:
    protocol: "udp"
    timeout: 0.1
  dashboard:
    enabled: true
    port: 6667
```

## 🏗️ Architecture

Capybarish provides a modular middleware architecture with:

- **Interface**: Main control interface for robot communication
- **Communication Manager**: UDP-based real-time communication
- **Dashboard Server**: Data visualization and monitoring
- **Plugin System**: Extensible architecture for custom components
- **Configuration Management**: Flexible YAML-based setup

## 📋 Requirements

- Python 3.8+
- NumPy >= 1.20.0
- OmegaConf >= 2.1.0
- MessagePack >= 1.0.0
- Rich >= 10.0.0 (for UI)
- PyYAML >= 5.4.0

## 🔧 Development Status

**This is an MVP under active development.** The package is being continuously updated and generalized as part of ongoing PhD research at Northwestern University. Features and APIs may change as the research progresses.

### Roadmap
- Enhanced plugin system for more sensors
- Improved cloud-robotics integration
- Performance optimizations for real-time control

## 🤝 Contributing

This project is primarily research-focused, but contributions are welcome! Please feel free to:

- Report issues or bugs
- Suggest improvements
- Submit pull requests

## 📚 Citation

If you use this software in your research, you are welcomed cite:

```bibtex
@software{metamachine2024,
  title={Capybarish: A lightweight communication middleware designed for cloud-based robotics controllers},
  author={Chen Yu},
  year={2025},
  url={https://github.com/chenaah/capybarish}
}
```

```bibtex
@article{yu2025reconfigurable,
  title={Reconfigurable legged metamachines that run on autonomous modular legs},
  author={Yu, Chen and Matthews, David and Wang, Jingxian and Gu, Jing and Blackiston, Douglas and Rubenstein, Michael and Kriegman, Sam},
  journal={arXiv preprint arXiv:2505.00784},
  year={2025}
}
```

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 📞 Contact

**Chen Yu**  
PhD Student, Northwestern University  
Email: chenyu@u.northwestern.edu

---

*This middleware is part of ongoing research on evolutionary modular robots. Updates and improvements will be released as the research progresses.*
