# HPL RV for ROS
This project provides tools to create and deploy runtime monitors for your Robot Operating System applications.
- [Installing](#installing)
- [Usage](#usage)
- [GitHub Features](#github-features)
- [Tooling](#tooling)
## Installing
This package can be installed with `pip`:
```bash
pip install hpl-rv-ros
```
## Usage
You can use this project to generate code both as a library and as a standalone tool.
First, you will need a mapping of ROS topic types to message types.
This can be specified in YAML or JSON formats, when provided as a file.
For example:
```yaml
%YAML 1.2
# file: topics.yaml
---
/a: std_msgs/Int64
/b: std_msgs/Int64
/p: std_msgs/Bool
/q: std_msgs/Bool
```
Then, you will also need to provide a HPL specification. This can be either a list of properties, or a `.hpl` file, depending on how you want to use this package.
### As a Standalone Tool
This package provides the `hpl-rv-ros` CLI script.
#### Required Arguments
1. a path to the topic type mapping file
2. either a list of properties or a list of `.hpl` files, depending on flags
#### Optional Arguments
- flag `--rospy`: generate ROS1 code instead of ROS2 code
- flag `-f` or `--files`: treat positional arguments as a list of paths to `.hpl` files instead of a list of properties
- argument `-o` or `--output`: pass a path to an output file for the generated code (default: print to screen)
#### Example
To generate ROS2 code:
```bash
hpl-rv-ros -f -o rclpy_node.py topics.yaml properties.hpl
```
To generate ROS1 code:
```bash
hpl-rv-ros --rospy -f -o rospy_node.py topics.yaml properties.hpl
```
### As a Library
This repository provides the `hplrv_ros` Python package.
#### Example
```py
from typing import Dict, List
from pathlib import Path
from hpl.ast import HplProperty
from hpl.parser import property_parser
from hplrv_ros.rclpy import generate_node as generate_rclpy
from hplrv_ros.rospy import generate_node as generate_rospy
parser = property_parser()
topic_types: Dict[str, str] = { '/a': 'std_msgs/Int32' }
properties: List[HplProperty] = [parser.parse('globally: no /a {data > 0}')]
rclpy_code: str = generate_rclpy(properties, topic_types)
rospy_code: str = generate_rospy(properties, topic_types)
path: Path = Path('rclpy_node.py')
path.write_text(rclpy_code, encoding='utf-8')
path = Path('rospy_node.py')
path.write_text(rospy_code, encoding='utf-8')
```
## GitHub Features
The `.github` directory comes with a number of files to configure certain GitHub features.
- Various Issue templates can be found under `ISSUE_TEMPLATE`.
- A Pull Request template can be found at `PULL_REQUEST_TEMPLATE.md`.
- Automatically mark issues as stale after a period of inactivity. The configuration file can be found at `.stale.yml`.
- Keep package dependencies up to date with Dependabot. The configuration file can be found at `dependabot.yml`.
- Keep Release Drafts automatically up to date with Pull Requests, using the [Release Drafter GitHub Action](https://github.com/marketplace/actions/release-drafter). The configuration file can be found at `release-drafter.yml` and the workflow at `workflows/release-drafter.yml`.
- Automatic package building and publishing when pushing a new version tag to `main`. The workflow can be found at `workflows/publish-package.yml`.
## Tooling
This package sets up various `tox` environments for static checks, testing, building and publishing.
It is also configured with `pre-commit` hooks to perform static checks and automatic formatting.
If you do not use `tox`, you can build the package with `build` and install a development version with `pip`.
Assume `cd` into the repository's root.
To install the `pre-commit` hooks:
```bash
pre-commit install
```
To run type checking:
```bash
tox -e typecheck
```
To run linting tools:
```bash
tox -e lint
```
To run automatic formatting:
```bash
tox -e format
```
To run tests:
```bash
tox
```
To build the package:
```bash
tox -e build
```
To build the package (with `build`):
```bash
python -m build
```
To clean the previous build files:
```bash
tox -e clean
```
To test package publication (publish to *Test PyPI*):
```bash
tox -e publish
```
To publish the package to PyPI:
```bash
tox -e publish -- --repository pypi
```
To install an editable version:
```bash
pip install -e .
```
Raw data
{
"_id": null,
"home_page": "https://github.com/HAROS-framework/hpl-rv-ros",
"name": "hpl-rv-ros",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8, <4",
"maintainer_email": "",
"keywords": "ros,runtime verification,runtime monitoring,code generation",
"author": "Andr\u00e9 Santos",
"author_email": "haros.framework@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5c/c3/58729fa1fd19bc553e36888e7fcd2c9f7161fa5682e439f296deea7429b3/hpl-rv-ros-1.1.0.tar.gz",
"platform": null,
"description": "# HPL RV for ROS\n\nThis project provides tools to create and deploy runtime monitors for your Robot Operating System applications.\n\n- [Installing](#installing)\n- [Usage](#usage)\n- [GitHub Features](#github-features)\n- [Tooling](#tooling)\n\n## Installing\n\nThis package can be installed with `pip`:\n\n```bash\npip install hpl-rv-ros\n```\n\n## Usage\n\nYou can use this project to generate code both as a library and as a standalone tool.\n\nFirst, you will need a mapping of ROS topic types to message types.\nThis can be specified in YAML or JSON formats, when provided as a file.\nFor example:\n\n```yaml\n%YAML 1.2\n# file: topics.yaml\n---\n/a: std_msgs/Int64\n/b: std_msgs/Int64\n/p: std_msgs/Bool\n/q: std_msgs/Bool\n```\n\nThen, you will also need to provide a HPL specification. This can be either a list of properties, or a `.hpl` file, depending on how you want to use this package.\n\n### As a Standalone Tool\n\nThis package provides the `hpl-rv-ros` CLI script.\n\n#### Required Arguments\n\n1. a path to the topic type mapping file\n2. either a list of properties or a list of `.hpl` files, depending on flags\n\n#### Optional Arguments\n\n- flag `--rospy`: generate ROS1 code instead of ROS2 code\n- flag `-f` or `--files`: treat positional arguments as a list of paths to `.hpl` files instead of a list of properties\n- argument `-o` or `--output`: pass a path to an output file for the generated code (default: print to screen)\n\n#### Example\n\nTo generate ROS2 code:\n\n```bash\nhpl-rv-ros -f -o rclpy_node.py topics.yaml properties.hpl\n```\n\nTo generate ROS1 code:\n\n```bash\nhpl-rv-ros --rospy -f -o rospy_node.py topics.yaml properties.hpl\n```\n\n### As a Library\n\nThis repository provides the `hplrv_ros` Python package.\n\n#### Example\n\n```py\nfrom typing import Dict, List\nfrom pathlib import Path\nfrom hpl.ast import HplProperty\nfrom hpl.parser import property_parser\nfrom hplrv_ros.rclpy import generate_node as generate_rclpy\nfrom hplrv_ros.rospy import generate_node as generate_rospy\n\nparser = property_parser()\n\ntopic_types: Dict[str, str] = { '/a': 'std_msgs/Int32' }\nproperties: List[HplProperty] = [parser.parse('globally: no /a {data > 0}')]\n\nrclpy_code: str = generate_rclpy(properties, topic_types)\nrospy_code: str = generate_rospy(properties, topic_types)\n\npath: Path = Path('rclpy_node.py')\npath.write_text(rclpy_code, encoding='utf-8')\npath = Path('rospy_node.py')\npath.write_text(rospy_code, encoding='utf-8')\n```\n\n\n## GitHub Features\n\nThe `.github` directory comes with a number of files to configure certain GitHub features.\n\n- Various Issue templates can be found under `ISSUE_TEMPLATE`.\n- A Pull Request template can be found at `PULL_REQUEST_TEMPLATE.md`.\n- Automatically mark issues as stale after a period of inactivity. The configuration file can be found at `.stale.yml`.\n- Keep package dependencies up to date with Dependabot. The configuration file can be found at `dependabot.yml`.\n- Keep Release Drafts automatically up to date with Pull Requests, using the [Release Drafter GitHub Action](https://github.com/marketplace/actions/release-drafter). The configuration file can be found at `release-drafter.yml` and the workflow at `workflows/release-drafter.yml`.\n- Automatic package building and publishing when pushing a new version tag to `main`. The workflow can be found at `workflows/publish-package.yml`.\n\n## Tooling\n\nThis package sets up various `tox` environments for static checks, testing, building and publishing.\nIt is also configured with `pre-commit` hooks to perform static checks and automatic formatting.\n\nIf you do not use `tox`, you can build the package with `build` and install a development version with `pip`.\n\nAssume `cd` into the repository's root.\n\nTo install the `pre-commit` hooks:\n\n```bash\npre-commit install\n```\n\nTo run type checking:\n\n```bash\ntox -e typecheck\n```\n\nTo run linting tools:\n\n```bash\ntox -e lint\n```\n\nTo run automatic formatting:\n\n```bash\ntox -e format\n```\n\nTo run tests:\n\n```bash\ntox\n```\n\nTo build the package:\n\n```bash\ntox -e build\n```\n\nTo build the package (with `build`):\n\n```bash\npython -m build\n```\n\nTo clean the previous build files:\n\n```bash\ntox -e clean\n```\n\nTo test package publication (publish to *Test PyPI*):\n\n```bash\ntox -e publish\n```\n\nTo publish the package to PyPI:\n\n```bash\ntox -e publish -- --repository pypi\n```\n\nTo install an editable version:\n\n```bash\npip install -e .\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Runtime Verification tools for ROS systems",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/HAROS-framework/hpl-rv-ros",
"Source": "https://github.com/HAROS-framework/hpl-rv-ros/",
"Tracker": "https://github.com/HAROS-framework/hpl-rv-ros/issues"
},
"split_keywords": [
"ros",
"runtime verification",
"runtime monitoring",
"code generation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10994ca506d29662b9b960b6370fa79591eea1a715f752590a99676922db2914",
"md5": "eb83d19f5d32eaccd05bae4979b62827",
"sha256": "55194b4f1f9fee3bdb92a334ae39ee579af9fcb9c3262fa74ee5d5aba7909258"
},
"downloads": -1,
"filename": "hpl_rv_ros-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb83d19f5d32eaccd05bae4979b62827",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8, <4",
"size": 11335,
"upload_time": "2023-09-05T08:32:40",
"upload_time_iso_8601": "2023-09-05T08:32:40.413954Z",
"url": "https://files.pythonhosted.org/packages/10/99/4ca506d29662b9b960b6370fa79591eea1a715f752590a99676922db2914/hpl_rv_ros-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5cc358729fa1fd19bc553e36888e7fcd2c9f7161fa5682e439f296deea7429b3",
"md5": "008df2d87dfbdd0af0c79092ff3d2793",
"sha256": "a3f265732c97eb950aa8e906f553575dc7463d8810da453338c1cd4b5ba074c2"
},
"downloads": -1,
"filename": "hpl-rv-ros-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "008df2d87dfbdd0af0c79092ff3d2793",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8, <4",
"size": 18024,
"upload_time": "2023-09-05T08:32:41",
"upload_time_iso_8601": "2023-09-05T08:32:41.952174Z",
"url": "https://files.pythonhosted.org/packages/5c/c3/58729fa1fd19bc553e36888e7fcd2c9f7161fa5682e439f296deea7429b3/hpl-rv-ros-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-05 08:32:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HAROS-framework",
"github_project": "hpl-rv-ros",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "hpl-rv-ros"
}
JSON
