Skip to content

Commit

Permalink
improve readme
Browse files Browse the repository at this point in the history
  • Loading branch information
lukicdarkoo committed Sep 25, 2024
1 parent 9ad66ed commit 37931b1
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 26 deletions.
47 changes: 22 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,63 +1,61 @@
![Teleop](./media/teleop.png)

Turns your phone into a robot arm teleoperation device in 3 simple steps:
1. Install and start the server on your computer.
2. Open the URL on your phone.
3. Click `Start` and hold the `Move` button to move the robot arm.

The web application utilizes the WebXR API that fuses the phone's sensors to get the orientation and position of the phone in 3D space. The server receives the phone's pose and sends it to the robot arm controller.
Transform your phone into a robot arm teleoperation device in three simple steps:

1. Install and launch the server on your computer.
2. Open the provided URL on your phone.
3. Tap `Start`, then press and hold the `Move` button to control the robot arm.

The web application leverages the WebXR API, which combines your phone’s sensors to detect its orientation and position in 3D space. The server receives this data and sends it to the robot arm controller.

| ![Lite6 Physical Teleoperation](./media/lite6_physical_teleop.gif) | ![UR5e Webots Teleoperation](./media/ur5e_webots.gif) |
|:-------------------------------------------------------------------:|:----------------------------------------------------:|
| Teleoperation of a physical Lite6 robot | Teleoperation of a Webots simulated UR5e robot |
| Teleoperation of a physical Lite6 robot | Teleoperation of a simulated UR5e robot in Webots |

## Installation

The package is available on [PyPI](https://pypi.org/project/teleop/), you can install it using pip.
The package is available on [PyPI](https://pypi.org/project/teleop/). You can install it using pip:

```bash
pip3 install teleop
```

## Usage

Out of the box, we provide some robot arm interfaces that you can just run, but you can create you own interface by including the [`teleop.Teleop`](./teleop/__init__.py) class in your project.
We provide some ready-to-use robot arm interfaces, but you can also create your own by incorporating the [`teleop.Teleop`](./teleop/__init__.py) class into your project.

### Basic Interface

A simple interface that simply prints the teleop response.
You can use it as a reference for creating your own interface.
A simple interface that prints the teleop responses. You can use it as a reference to build your own interface.

```bash
python3 -m teleop.basic
```

### ROS 2 Interface

A ROS 2 interface is primarily designed to be compatible with the [cartesian_controllers](https://github.com/fzi-forschungszentrum-informatik/cartesian_controllers) package, but it could also be adapted for [MoveIt Servo](https://moveit.picknik.ai/main/doc/examples/realtime_servo/realtime_servo_tutorial.html) or other packages.
The ROS 2 interface is designed primarily for use with the [cartesian_controllers](https://github.com/fzi-forschungszentrum-informatik/cartesian_controllers) package, but it can also be adapted for [MoveIt Servo](https://moveit.picknik.ai/main/doc/examples/realtime_servo/realtime_servo_tutorial.html) or other packages.

```bash
python3 -m teleop.ros2
```

Published topics:
- `target_frame` ([geometry_msgs/PoseStamped](https://docs.ros2.org/latest/api/geometry_msgs/msg/PoseStamped.html)) : The target pose of the robot arm end effector in the robot base frame.
**Published topics:**
- `target_frame` ([geometry_msgs/PoseStamped](https://docs.ros2.org/latest/api/geometry_msgs/msg/PoseStamped.html)): The target pose of the robot arm’s end effector in the robot base frame.
- `tf` ([tf2_msgs/TFMessage](https://docs.ros2.org/latest/api/tf2_msgs/msg/TFMessage.html)): The transform between the robot base frame and the target frame for visualization.

Subscribed topics:
- `current_pose` ([geometry_msgs/PoseStamped](https://docs.ros2.org/latest/api/geometry_msgs/msg/PoseStamped.html)): The current pose of the robot arm end effector in the robot base frame. Used for updating the reference pose.
**Subscribed topics:**
- `current_pose` ([geometry_msgs/PoseStamped](https://docs.ros2.org/latest/api/geometry_msgs/msg/PoseStamped.html)): The current pose of the robot arm’s end effector in the robot base frame. Used to update the reference pose.

You can override the default topic names using standard ROS 2 arguments:

You can use the standard ROS 2 arguments to override the default values, for example:
```bash
python3 -m teleop.ros2 --ros-args -r target_frame:=/some_other_topic_name
```

### Custom Interface

For most applications you will need to create a custom interface to interact with your robot arm.
For most applications, you will need to create a custom interface to interact with your robot arm. Here’s an example:

```python
import numpy as np
Expand All @@ -66,29 +64,28 @@ from teleop import Teleop

def callback(pose: np.ndarray, message: dict) -> None:
"""
A callback function that will be called when pose updates are received.
The callback function should take two arguments:
Callback function triggered when pose updates are received.
Arguments:
- np.ndarray: A 4x4 transformation matrix representing the end-effector target pose.
- dict: A dictionary containing additional information.
"""

print(f'Pose: {pose}')
print(f'Message: {message}')


teleop = Teleop()
teleop.subscribe(callback)
teleop.run()
```

## Examples

Check out the examples to see how to use the package in different scenarios:
- [examples/webots](./examples/webots): A teleoperation example of a UR5e robot arm with [ikpy](https://github.com/Phylliade/ikpy) in a [Webots](https://github.com/cyberbotics/webots/) simulator.
Explore the examples to learn how to use the package in various scenarios:

- [examples/webots](./examples/webots): Teleoperation of a UR5e robot arm using [ikpy](https://github.com/Phylliade/ikpy) in the [Webots](https://github.com/cyberbotics/webots/) simulator.

## Development

To contribute to the project, you can install the package in editable mode.
If you’d like to contribute, install the package in editable mode:

```bash
# Install the package in editable mode
Expand Down
Binary file modified media/lite6_physical_teleop.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

setup(
name="teleop",
version="0.0.6",
version="0.0.7",
packages=["teleop", "teleop.basic", "teleop.ros2"],
long_description=long_description,
long_description_content_type="text/markdown",
Expand Down

0 comments on commit 37931b1

Please sign in to comment.