Skip to content

Commit

Permalink
Cleanup of README.md (#342)
Browse files Browse the repository at this point in the history 
* Reformatted README.md

This is an initial cleanup attempt of the README.md file.  All
non-code lines have been wrapped to an 80 column width, and some
markdown was cleaned up.  Further work is needed.

Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Added 'bash' info string to appropriate fenced code blocks.

Numerous fenced code blocks did not have a
[info string](https://github.github.com/gfm/#info-string), which
meant that the enclosed code block wouldn't be rendered correctly.
As it turned out, all of these were intended to be run in a bash
shell, so I added that as their info strings.

Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* WIP: Updated the scripts in the README.md file to use environment variables.

The scripts weren't directly executable before, requiring manual
substitution of various 'variables'.  This was unfortunate as Github
makes copying and pasting code blocks simple and straightforward.

The changes in this commit make it possible to copy/paste each example
into it's own shell, which should make it slightly easier for new users
to start using the bridge.

Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* fix: Unwrapped lines per request from @gbiggs.

@gbiggs commented at #342 (comment)
that files in ROS2 are intentionally not wrapped to make handling
diffs in PRs easier.  I've copied in the relevant original lines
to unwrap the lines I wrapped earlier.

Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Accepted suggestion from @gbiggs

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* Update README.md

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* The service name might provide more debug information than host:port details (#346)

* The service name might provide more debug information than host:port details

Signed-off-by: Tim Clephas <tim.clephas@nobleo.nl>
Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com>
Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

* fix: Changed 'galactic' to 'rolling'

Changes due to suggestions from @gbiggs in the discussion of [PR 342](#342 (comment))

Signed-off-by: Cem Karan <cem.f.karan.civ@army.mil>

Co-authored-by: Geoffrey Biggs <gbiggs@killbots.net>
Co-authored-by: Tim Clephas <tim.clephas@nobleo.nl>
Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com>
  • Loading branch information
@ckaran @gbiggs
@Timple @fujitatomoya
4 people authored Mar 24, 2022
1 parent bf0da9d commit 852f2c4
Showing 1 changed file with 94 additions and 56 deletions.
150 changes: 94 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,31 @@ To run the following examples you will also need these ROS 1 packages:
* `rostopic`
* `rqt_image_view`

### Prerequisites for the examples in this file

In order to make the examples below portable between versions of ROS, we define two environment variables, `ROS1_INSTALL_PATH` and `ROS2_INSTALL_PATH`.
These are defined as the paths to the installation location of their respective ROS versions.

If you installed Noetic in the default location, then the definition of `ROS1_INSTALL_PATH` will be `/opt/ros/noetic`.

Building the bridge as described below requires you to build all of ROS 2.
We assume that you have downloaded it to `~/ros2_rolling`, and that is where you plan on building it.
In this case, `ROS2_INSTALL_PATH` will be defined as `~/ros2_rolling/install`.

If you've chosen to install either or both versions of ROS somewhere else, you will need adjust the definitions below to match your installation paths.

Because these definitions are used continuously throughout this page, it is useful to add the following lines to your shell startup file (`~/.bashrc` if you are using `bash`, `~/.zshrc` if you are using `zsh`).
Modify these definitions as appropriate for the versions of ROS that you're using, and for the shell that you're using.


```bash
export ROS1_INSTALL_PATH=/opt/ros/noetic
export ROS2_INSTALL_PATH=~/ros2_rolling/install
```

Note that no trailing '/' character is used in either definition.
If you have problems involving paths, please verify that you have the correct path to the installation location, and that you do not have a trailing '/' in either definition.

### Building the bridge from source

Before continuing you should have the prerequisites for building ROS 2 from source installed following [these instructions](https://github.com/ros2/ros2/wiki/Installation).
Expand All @@ -60,14 +85,17 @@ Here are the steps for Linux and OSX.
You should first build everything but the ROS 1 bridge with normal colcon arguments.
We don't recommend having your ROS 1 environment sourced during this step as it can add other libraries to the path.

```

```bash
colcon build --symlink-install --packages-skip ros1_bridge
```

Next you need to source the ROS 1 environment, for Linux and ROS Melodic that would be:
Next you need to source the ROS 1 environment.
If you set the `ROS1_INSTALL_PATH` environment variable as described above, then the following will source the correct `setup.bash` file.

```
source /opt/ros/melodic/setup.bash

```bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
```
Expand All @@ -77,10 +105,11 @@ Therefore you must add any ROS 1 or ROS 2 workspaces that have message/service p
This can be done by adding explicit dependencies on the message/service packages to the `package.xml` of the bridge, so that `colcon` will add them to the path before it builds the bridge.
Alternatively you can do it manually by sourcing the relevant workspaces yourself, e.g.:

```

```bash
# You have already sourced your ROS installation.
# Source your ROS 2 installation:
. <install-space-with-ros2>/local_setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
# And if you have a ROS 1 overlay workspace, something like:
# . <install-space-to-ros1-overlay-ws>/setup.bash
# And if you have a ROS 2 overlay workspace, something like:
Expand All @@ -89,7 +118,8 @@ Alternatively you can do it manually by sourcing the relevant workspaces yoursel

Then build just the ROS 1 bridge:

```

```bash
colcon build --symlink-install --packages-select ros1_bridge --cmake-force-configure
```

Expand All @@ -109,9 +139,10 @@ You will get errors from most tools if they have both workspaces in their enviro

First we start a ROS 1 `roscore`:

```

```bash
# Shell A (ROS 1 only):
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
roscore
Expand All @@ -122,14 +153,15 @@ roscore
Then we start the dynamic bridge which will watch the available ROS 1 and ROS 2 topics.
Once a *matching* topic has been detected it starts to bridge the messages on this topic.

```

```bash
# Shell B (ROS 1 + ROS 2):
# Source ROS 1 first:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
# Source ROS 2 next:
. <install-space-with-bridge>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
# For example:
# . /opt/ros/dashing/setup.bash
export ROS_MASTER_URI=http://localhost:11311
Expand All @@ -142,9 +174,10 @@ The program will start outputting the currently available topics in ROS 1 and RO

Now we start the ROS 1 talker.

```

```bash
# Shell C:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
rosrun rospy_tutorials talker
Expand All @@ -156,24 +189,27 @@ The ROS 1 node will start printing the published messages to the console.

Now we start the ROS 2 listener from the `demo_nodes_cpp` ROS 2 package.

```

```bash
# Shell D:
. <install-space-with-ros2>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 run demo_nodes_cpp listener
```

The ROS 2 node will start printing the received messages to the console.

When looking at the output in *shell B* there will be a line stating that the bridge for this topic has been created:

```

```bash
created 1to2 bridge for topic '/chatter' with ROS 1 type 'std_msgs/String' and ROS 2 type 'std_msgs/String'
```

At the end stop all programs with `Ctrl-C`.
Once you stop either the talker or the listener in *shell B* a line will be stating that the bridge has been torn down:

```

```bash
removed 1to2 bridge for topic '/chatter'
```

Expand All @@ -186,22 +222,24 @@ The screenshot shows all the shell windows and their expected content:

The steps are very similar to the previous example and therefore only the commands are described.

```

```bash
# Shell A:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
roscore
```

---

```

```bash
# Shell B:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
. <install-space-with-bridge>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
export ROS_MASTER_URI=http://localhost:11311
ros2 run ros1_bridge dynamic_bridge
```
Expand All @@ -210,25 +248,24 @@ ros2 run ros1_bridge dynamic_bridge

Now we start the ROS 2 talker from the `demo_nodes_py` ROS 2 package.

```
```bash
# Shell C:
. <install-space-with-ros2>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 run demo_nodes_py talker
```

---

Now we start the ROS 1 listener.

```
```bash
# Shell D:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
rosrun roscpp_tutorials listener
```


## Example 2: run the bridge and exchange images

The second example will demonstrate the bridge passing along bigger and more complicated messages.
Expand All @@ -237,20 +274,20 @@ And a ROS 1 publisher can send a message to toggle an option in the ROS 2 node.

First we start a ROS 1 `roscore` and the bridge:

```
```bash
# Shell A:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
roscore
```

```
```bash
# Shell B:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
. <workspace-with-bridge>/install/setup.bash
source ${ROS2_INSTALL_PATH}/install/setup.bash
export ROS_MASTER_URI=http://localhost:11311
ros2 run ros1_bridge dynamic_bridge
```
Expand All @@ -259,34 +296,35 @@ ros2 run ros1_bridge dynamic_bridge

Now we start the ROS 1 GUI:

```
```bash
# Shell C:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
rqt_image_view /image
```

--
---

Now we start the ROS 2 image publisher from the `image_tools` ROS 2 package:
```
```bash
# Shell D:
. <workspace-with-ros2>/install/setup.bash
source ${ROS2_INSTALL_PATH}/install/setup.bash
ros2 run image_tools cam2image
```

You should see the current images in `rqt_image_view` which are coming from the ROS 2 node `cam2image` and are being passed along by the bridge.

--
---

To exercise the bridge in the opposite direction at the same time you can publish a message to the ROS 2 node from ROS 1.
By publishing either `true` or `false` to the `flip_image` topic, the camera node will conditionally flip the image before sending it.
You can either use the `Message Publisher` plugin in `rqt` to publish a `std_msgs/Bool` message on the topic `flip_image`, or run one of the two following `rostopic` commands:

```

```bash
# Shell E:
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
rostopic pub -r 1 /flip_image std_msgs/Bool "{data: true}"
Expand Down Expand Up @@ -314,36 +352,36 @@ is installed on your system and the environment is set up correctly while you bu

Launch ROS master

```
```bash
# Shell A:
. <ros-install-dir>/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
roscore -p 11311
```

Launch dynamic_bridge:

```
```bash
# Shell B:
. <ros-install-dir>/setup.bash
. <ros2-install-dir>/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
export ROS_MASTER_URI=http://localhost:11311
ros2 run ros1_bridge dynamic_bridge
```

Launch TwoInts server:

```
```bash
# Shell C:
. <ros-install-dir>/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
export ROS_MASTER_URI=http://localhost:11311
rosrun roscpp_tutorials add_two_ints_server
```

Launch AddTwoInts client:

```
```bash
# Shell D:
. <ros2-install-dir>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 run demo_nodes_cpp add_two_ints_client
```

Expand All @@ -369,7 +407,7 @@ Start a ROS 1 roscore:
```bash
# Shell A (ROS 1 only):
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
roscore
Expand All @@ -379,7 +417,7 @@ Then load the bridge.yaml config file and start the talker to publish on the `/c

```bash
Shell B: (ROS1 only):
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash
rosparam load bridge.yaml
Expand All @@ -389,7 +427,7 @@ rosrun rospy_tutorials talker

```bash
Shell C: (ROS1 only):
. /opt/ros/melodic/setup.bash
source ${ROS1_INSTALL_PATH}/setup.bash
# Or, on OSX, something like:
# . ~/ros_catkin_ws/install_isolated/setup.bash

Expand All @@ -400,22 +438,22 @@ Then, in a few ROS 2 terminals:

```bash
# Shell D:
. <install-space-with-ros2>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 run ros1_bridge parameter_bridge
```

If all is well, the logging shows it is creating bridges for the topic and service and you should be able to call the service and listen to the ROS 1 talker from ROS 2:

```bash
# Shell E:
. <install-space-with-ros2>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 run demo_nodes_cpp listener
```
This should start printing text like `I heard: [hello world ...]` with a timestamp.

```bash
# Shell F:
. <install-space-with-ros2>/setup.bash
source ${ROS2_INSTALL_PATH}/setup.bash
ros2 service call /add_two_ints example_interfaces/srv/AddTwoInts "{a: 1, b: 2}"
```
If all is well, the output should contain `example_interfaces.srv.AddTwoInts_Response(sum=3)`

0 comments on commit 852f2c4

Please sign in to comment.