# rospec
[](https://github.com/pcanelas/rospec/actions/workflows/ruff.yaml)
[](https://github.com/pcanelas/rospec/actions/workflows/pytest.yaml)
## Description
rospec is a domain specification language to specify configurations of ROS components and their integration.
Current approaches focus on runtime verification or require system execution to detect misconfigurations.
rospec allows component writer developers to express specifications for their ROS components, while component integrators
select their components and provide their configurations --- any mismatches are raised statically prior to execution.
By providing a formal way to describe the expected configuration and integration of ROS components, rospec helps identify
misconfigurations early in the development process, preventing costly errors during system execution.
The tool can be used to validate various aspects of ROS components configuration and integration, including but not only:
- Topic, service, and action connections between nodes;
- Parameter value constraints and dependencies;
- Component compatibility requirements.
## Installation
rospec can be installed using either pip or by building from source. We recommend
using a virtual environment to avoid conflicts with other Python packages.
### Prerequisites
- [Python 3.9+](https://www.python.org/downloads/)
- [uv (>=0.7.6)](https://docs.astral.sh/uv/getting-started/installation/)
### Setup
#### Option 1: Install from PyPI (when available)
```bash
# Create and activate a virtual environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install rospec
uv add rospec
```
#### Option 2: Install from source
1. Clone the repository:
```bash
git clone https://github.com/pcanelas/rospec.git
cd rospec
```
2. Create a virtual environment and install dependencies:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
```
3. Install in development mode (if you plan to contribute):
```bash
uv sync --extra dev
```
## Usage
rospec offers a command line interface (CLI) for parsing and verifying specifications.
To run the CLI, you can use the following command:
```bash
rospec --specifications path/to/your/spec.rospec
uv run pre-commit install
```
Or if installed in development mode:
```bash
uv run rospec --specifications path/to/your/spec.rospec
```
### Basic Example
Here's a simple example of a rospec specification containing the specification for one component and its integration:
```
node type move_group_type {
param elbow_joint/max_acceleration: double where {_ >= 0};
optional param elbow_joint/max_velocity: double = 2.0;
optional param elbow_joint/has_velocity_limits: bool = false;
optional param elbow_joint/has_acceleration_limits: bool = false;
} where {
exists(elbow_joint/max_acceleration) -> elbow_joint/has_acceleration_limits;
}
system {
node instance move_group: move_group_type {
param elbow_joint/max_acceleration = 0;
param elbow_joint/max_velocity = 3.14;
param elbow_joint/has_acceleration_limits = false;
param elbow_joint/has_velocity_limits = false;
}
}
```
To verify this specification:
```bash
rospec --specifications examples/evaluation/detectable-364801.rospec
```
## Development
For development setup and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
### Quick Development Setup
```bash
git clone https://github.com/pcanelas/rospec.git
cd rospec
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync --dev
uv run pre-commit install
```
### Running Tests
```bash
uv run pytest -n auto
```
### Code Formatting
```bash
uv run ruff format
uv run ruff check --fix
```
## Authors
This project is a research project within the [Software and Societal Systems Department](https://s3d.cmu.edu/) (S3D)
and the [Robotics Institute](https://www.ri.cmu.edu/) at Carnegie Mellon University, and [LASIGE](https://lasige.pt/)
at University of Lisbon, by:
- [Paulo Canelas](https://pcanelas.com/)
- [Bradley Schmerl](https://www.cs.cmu.edu/~schmerl/)
- [Alcides Fonseca](https://wiki.alcidesfonseca.com/)
- [Christopher S. Timperley](https://chris.timperley.info/)
## Acknowledgements
This work was supported by Fundação para a Ciência e Tecnologia (FCT) in the LASIGE Research Unit under the ref.
(UID/00408/2025 and EXPL/CCI-COM/1306/2021), and the CMU Portugal Dual PhD program (SFRH/BD/151469/2021).
## Publications
[The Usability Argument for ROS-based Robot Architectural Description Languages](https://acme.able.cs.cmu.edu/pubs/uploads/pdf/2024_plateau_rospecusabilityCanelas_RospecADL_2025.pdf),
at PLATEAU 2025.
[Understanding Misconfigurations in ROS: An Empirical Study and Current Approaches](https://doi.org/10.1145/3650212.3680350/),
at ISSTA 2024.
Raw data
{
"_id": null,
"home_page": null,
"name": "rospec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "robotics, ros, specification, verification",
"author": "Bradley Schmerl, Alcides Fonseca, Christopher S. Timperley",
"author_email": "Paulo Canelas <pasantos@andrew.cmu.edu>",
"download_url": "https://files.pythonhosted.org/packages/2e/8b/f13bae8a0325e07c008a7905490491b6863e8ee956ed0c4f1fe69cdfbfc8/rospec-0.1.0.tar.gz",
"platform": null,
"description": "# rospec\n\n[](https://github.com/pcanelas/rospec/actions/workflows/ruff.yaml)\n[](https://github.com/pcanelas/rospec/actions/workflows/pytest.yaml)\n\n## Description\n\nrospec is a domain specification language to specify configurations of ROS components and their integration.\nCurrent approaches focus on runtime verification or require system execution to detect misconfigurations.\nrospec allows component writer developers to express specifications for their ROS components, while component integrators\nselect their components and provide their configurations --- any mismatches are raised statically prior to execution.\nBy providing a formal way to describe the expected configuration and integration of ROS components, rospec helps identify\nmisconfigurations early in the development process, preventing costly errors during system execution.\n\nThe tool can be used to validate various aspects of ROS components configuration and integration, including but not only:\n\n- Topic, service, and action connections between nodes;\n- Parameter value constraints and dependencies;\n- Component compatibility requirements.\n\n## Installation\n\nrospec can be installed using either pip or by building from source. We recommend\nusing a virtual environment to avoid conflicts with other Python packages.\n\n### Prerequisites\n\n- [Python 3.9+](https://www.python.org/downloads/)\n- [uv (>=0.7.6)](https://docs.astral.sh/uv/getting-started/installation/)\n\n### Setup\n\n#### Option 1: Install from PyPI (when available)\n\n```bash\n# Create and activate a virtual environment\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install rospec\nuv add rospec\n```\n\n#### Option 2: Install from source\n\n1. Clone the repository:\n\n ```bash\n git clone https://github.com/pcanelas/rospec.git\n cd rospec\n ```\n\n2. Create a virtual environment and install dependencies:\n\n ```bash\n uv venv\n source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n uv sync\n ```\n\n3. Install in development mode (if you plan to contribute):\n\n ```bash\n uv sync --extra dev\n ```\n\n## Usage\n\nrospec offers a command line interface (CLI) for parsing and verifying specifications.\nTo run the CLI, you can use the following command:\n\n```bash\nrospec --specifications path/to/your/spec.rospec\nuv run pre-commit install\n```\n\nOr if installed in development mode:\n\n```bash\nuv run rospec --specifications path/to/your/spec.rospec\n```\n\n### Basic Example\n\nHere's a simple example of a rospec specification containing the specification for one component and its integration:\n\n```\nnode type move_group_type {\n param elbow_joint/max_acceleration: double where {_ >= 0};\n optional param elbow_joint/max_velocity: double = 2.0;\n optional param elbow_joint/has_velocity_limits: bool = false;\n optional param elbow_joint/has_acceleration_limits: bool = false;\n} where {\n exists(elbow_joint/max_acceleration) -> elbow_joint/has_acceleration_limits;\n}\n\nsystem {\n node instance move_group: move_group_type {\n param elbow_joint/max_acceleration = 0;\n param elbow_joint/max_velocity = 3.14;\n param elbow_joint/has_acceleration_limits = false;\n param elbow_joint/has_velocity_limits = false;\n }\n}\n```\n\nTo verify this specification:\n\n```bash\nrospec --specifications examples/evaluation/detectable-364801.rospec\n```\n\n## Development\n\nFor development setup and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Quick Development Setup\n\n```bash\ngit clone https://github.com/pcanelas/rospec.git\ncd rospec\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv sync --dev\nuv run pre-commit install\n```\n\n### Running Tests\n\n```bash\nuv run pytest -n auto\n```\n\n### Code Formatting\n\n```bash\nuv run ruff format\nuv run ruff check --fix\n```\n\n## Authors\n\nThis project is a research project within the [Software and Societal Systems Department](https://s3d.cmu.edu/) (S3D)\nand the [Robotics Institute](https://www.ri.cmu.edu/) at Carnegie Mellon University, and [LASIGE](https://lasige.pt/)\nat University of Lisbon, by:\n\n- [Paulo Canelas](https://pcanelas.com/)\n- [Bradley Schmerl](https://www.cs.cmu.edu/~schmerl/)\n- [Alcides Fonseca](https://wiki.alcidesfonseca.com/)\n- [Christopher S. Timperley](https://chris.timperley.info/)\n\n## Acknowledgements\n\nThis work was supported by Funda\u00e7\u00e3o para a Ci\u00eancia e Tecnologia (FCT) in the LASIGE Research Unit under the ref.\n(UID/00408/2025 and EXPL/CCI-COM/1306/2021), and the CMU Portugal Dual PhD program (SFRH/BD/151469/2021).\n\n## Publications\n\n[The Usability Argument for ROS-based Robot Architectural Description Languages](https://acme.able.cs.cmu.edu/pubs/uploads/pdf/2024_plateau_rospecusabilityCanelas_RospecADL_2025.pdf),\nat PLATEAU 2025.\n\n[Understanding Misconfigurations in ROS: An Empirical Study and Current Approaches](https://doi.org/10.1145/3650212.3680350/),\nat ISSTA 2024.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Specification and verification of ROS-based robot software",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/pcanelas/rospec",
"Issues": "https://github.com/pcanelas/rospec/issues",
"Repository": "https://github.com/pcanelas/rospec"
},
"split_keywords": [
"robotics",
" ros",
" specification",
" verification"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d29696a3eab800300023d9cee315037e5d385bc294508609b1b657fb22b2e175",
"md5": "90921254e6d53ad01c4b223a788f31f6",
"sha256": "0102b07c434847fe67ccb9122d3ea4e9a370d1a5bb675755205eef8484b7e599"
},
"downloads": -1,
"filename": "rospec-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90921254e6d53ad01c4b223a788f31f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 46869,
"upload_time": "2025-07-25T20:39:26",
"upload_time_iso_8601": "2025-07-25T20:39:26.123179Z",
"url": "https://files.pythonhosted.org/packages/d2/96/96a3eab800300023d9cee315037e5d385bc294508609b1b657fb22b2e175/rospec-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2e8bf13bae8a0325e07c008a7905490491b6863e8ee956ed0c4f1fe69cdfbfc8",
"md5": "d637bc92cc2c7d8463c5ff08918682b1",
"sha256": "8e612712cae55be0b66b2f6ab3fbafd0308c38687c4c8adfaddb3976e02233da"
},
"downloads": -1,
"filename": "rospec-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d637bc92cc2c7d8463c5ff08918682b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 114351,
"upload_time": "2025-07-25T20:39:27",
"upload_time_iso_8601": "2025-07-25T20:39:27.290295Z",
"url": "https://files.pythonhosted.org/packages/2e/8b/f13bae8a0325e07c008a7905490491b6863e8ee956ed0c4f1fe69cdfbfc8/rospec-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 20:39:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pcanelas",
"github_project": "rospec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rospec"
}
JSON
