Update README.md

README.md

@@ -17,7 +17,81 @@ pip install hpl-rv-ros
 
 ## Usage
 
-TO DO
+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