From 6caa080df5111a940be41f4603908a7b4a849225 Mon Sep 17 00:00:00 2001 From: methylDragon Date: Tue, 28 Jun 2022 18:53:31 -0700 Subject: [PATCH] Update docs Signed-off-by: methylDragon --- doc/index.rst | 81 +++++++++++++++++++++++++++++++---------- ros1_bridge/__init__.py | 4 +- 2 files changed, 64 insertions(+), 21 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 4d0c3867..155621d1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -149,25 +149,6 @@ The mapping can optionally only define ``request_fields_1_to_2`` or ``response_f ros1_bar: 'ros2_bar' -How can I define a mapping rules for a foreign package? ------------------------------------------------------- - -In the previous sections, it was stated that the ``ros2_package_name`` mapping rule must be the same as the ROS 2 package the mapping rule was defined in. -While this is **recommended** to prevent conflicting and/or duplicate rules, it is possible to override the check that enforces this with the ``enable_foreign_mappings`` field. - -This will mean that, for every package mapping rule defined in the ``yaml`` file, the check for ROS 2 package name equality will be skipped. -Again, note that this is a dark art that should be wielded with responsibility, please be very careful with this! - -With ``enable_foreign_mappings`` set to ``true``, you can then specify mapping rules for ROS 2 packages that are not the same as the package your mapping rules file resides in:: - - - - enable_foreign_mappings: true - ros1_package_name: 'ros1_pkg_name' - ros1_service_name: 'ros1_srv_name' - ros2_package_name: 'ros2_FOREIGN_pkg_name' - ros2_service_name: 'ros2_srv_name' - - How does the bridge know about custom interfaces? ------------------------------------------------- @@ -257,6 +238,68 @@ Run the bridge, reusing shells from above:: rostopic list rostopic echo /joint_command + +How can I define a mapping rules for a foreign package, from a foreign package? +------------------------------------------------------------------------------- + +In the previous sections, it was stated that the ``ros2_package_name`` mapping rule must be the same as the ROS 2 package the mapping rule was defined in. +While this is **recommended** to prevent conflicting and/or duplicate rules, it is possible to override the check that enforces this with the ``enable_foreign_mappings`` field. + +This will mean that, for every package mapping rule defined in the ``yaml`` file, the check for ROS 2 package name equality will be skipped. +Again, note that this is a dark art that should be wielded with responsibility, please be very careful with this! +If there are conflicting mapping rules, the last one that is parsed in sorting order is used! +This is usually hard to predict, so be very careful! + +With ``enable_foreign_mappings`` set to ``true``, you can then specify mapping rules for ROS 2 packages that are not the same as the package your mapping rules file resides in:: + + - + enable_foreign_mappings: true + ros1_package_name: 'ros1_pkg_name' + ros1_service_name: 'ros1_srv_name' + ros2_package_name: 'ros2_FOREIGN_pkg_name' # the package with the message definition + ros2_service_name: 'ros2_srv_name' + +You must also make the ``ros1_bridge_foreign_mapping`` ament resource available to the index in the mapping package's ``CMakeLists.txt``. +A good place to put the line is to do this is before the install rule for your mapping rules, like so:: + + - + ament_index_register_resource("ros1_bridge_foreign_mapping") + install( + FILES YOUR_MAPPING_RULE_FILE.yaml + DESTINATION share/${PROJECT_NAME}) + +**Note**: In this case, the package name you should put in ```ros2_package_name`` is the name of the package with the message definition. +In effect, it'll be a foreign package, relative to the mapping package you're defining your mapping rules in. + +An example directory layout looks like this:: + + . + ├─ ros1_msgs_ws + │ └─ src + │ └─ ros1_bridge_msgs + │ └─ msg + │ └─ ros1_msg_name.msg + ├─ ros2_msgs_ws + │ └─ src + │ └─ ros2_bridge_msgs + │ │ ├─ msg + │ │ │ └─ ros2_msg_name.msg + │ └─ ros2_bridge_mappings + │ └─ # YAML file that defines mapping rules for bridge_msgs, or some other foreign msg package + └─ bridge_ws + └─ src + └─ ros1_bridge + +In the above example, the mapping rule would look like this:: + + - + enable_foreign_mappings: true + ros1_package_name: 'ros1_bridge_msgs' + ros1_message_name: 'ros1_msg_name' + ros2_package_name: 'ros2_bridge_msgs' # this is a foreign package, relative to ros2_bridge_mappings! + ros2_message_name: 'ros2_msg_name' + + Known Issues ------------ diff --git a/ros1_bridge/__init__.py b/ros1_bridge/__init__.py index 4601a5a1..c4d177d5 100644 --- a/ros1_bridge/__init__.py +++ b/ros1_bridge/__init__.py @@ -265,7 +265,7 @@ def get_ros2_messages(): }) for package_name, val_tuple in resources.items(): prefix_path, resource_type = val_tuple - if resource_type == "rosidl_interfaces": + if resource_type == "rosidl_interfaces": # Required, otherwise linking fails pkgs.append(package_name) resource, _ = ament_index_python.get_resource(resource_type, package_name) interfaces = resource.splitlines() @@ -327,7 +327,7 @@ def get_ros2_services(): resource_type = 'rosidl_interfaces' for package_name, val_tuple in resources.items(): prefix_path, resource_type = val_tuple - if resource_type == "rosidl_interfaces": + if resource_type == "rosidl_interfaces": # Required, otherwise linking fails pkgs.append(package_name) resource, _ = ament_index_python.get_resource(resource_type, package_name) interfaces = resource.splitlines()