diff --git a/Gemfile b/Gemfile index 517436bec..b33f91ca6 100644 --- a/Gemfile +++ b/Gemfile @@ -2,6 +2,7 @@ source "https://rubygems.org" gem "jekyll" gem "jekyll-sitemap" +gem "jekyll-redirect-from" gem "json" gem 'rouge' # gem "html-proofer" diff --git a/_config.yml b/_config.yml index 985c9ddd3..8ce88b603 100644 --- a/_config.yml +++ b/_config.yml @@ -20,3 +20,6 @@ exclude: - LICENSE - README.md - vendor + +plugins: + - jekyll-redirect-from diff --git a/articles/140_topic_and_service_name_mapping.md b/articles/140_resource_names.md similarity index 50% rename from articles/140_topic_and_service_name_mapping.md rename to articles/140_resource_names.md index 43870e4eb..49b2bcd5b 100644 --- a/articles/140_topic_and_service_name_mapping.md +++ b/articles/140_resource_names.md @@ -1,10 +1,11 @@ --- layout: default -title: Topic and Service name mapping to DDS -permalink: articles/topic_and_service_names.html +title: Resource Names +permalink: articles/resource_names.html +redirect_from: articles/topic_and_service_names.html abstract: - This article describes the proposed mapping between ROS topic and service names to DDS topic and service names. -author: '[William Woodall](https://github.com/wjwwood)' + This article describes a specification proposal for resource addressing in ROS, as well as its implementation in a DDS setting. +author: '[William Woodall](https://github.com/wjwwood), [Michel Hidalgo](https://github.com/hidmic)' published: true --- @@ -19,13 +20,33 @@ published: true Original Author: {{ page.author }} -## Context +## Background -Before proposing constraints for ROS 2 topic and service names and a mapping to underlying DDS topics, this article will first summarize the existing guidelines and restrictions for both ROS 1 and DDS. +### Concepts -### ROS 1 Names +#### Content-oriented resources -In ROS 1, topic and service name guidelines are all covered under the umbrella of "ROS Names" and have these restrictions: +Borrowing both terminology and key concepts from [_Content Centric Networking_](https://en.wikipedia.org/wiki/Content_centric_networking), content-oriented resources are not bound to any particular node in a given system, but instead allow information addressing through unique names and independently of the actual source. +ROS topics, which may be freely published or subscribed to by multiples ROS nodes, fall under this classification. +Note that in ROS 1, every resource i.e. topics, services, actions, and parameters, is a content-oriented resource. + +#### Host-oriented resources + +Host-oriented resources are provided by a node in a given system and thus are bound to it. +Multiple resources with the same name and type may be provided by different nodes. +Therefore, the host node name is necessary to unambiguously address a host-oriented resource. + +*Note*: In the preceding, it is assumed that node name uniqueness has been ensured by means not prescribed in this document. + +ROS services, actions, and parameters fall under this classification. + +### Restrictions + +Before proposing constraints for ROS resource names and a mapping to underlying DDS concepts, this article will first summarize the existing guidelines and restrictions for both ROS 1 and DDS. + +#### ROS 1 Names + +In ROS 1, topic and service name restrictions are all covered under the umbrella of "ROS Names": *From [http://wiki.ros.org/Names](http://wiki.ros.org/Names):* @@ -38,152 +59,158 @@ A valid name has the following characteristics: Exception: base names (described below) cannot have forward slashes (/) or tildes (~) in them. ``` -### DDS Topic Names +#### DDS Topic Names -In DDS, topic names are restricted by these restrictions: +In DDS, topic names restrictions include: -*From DDS 1.4 specification, or the [RTI documentation](http://community.rti.com/rti-doc/510/ndds/doc/html/api_cpp/group__DDSQueryAndFilterSyntaxModule.html):* +*From DDS 1.4 specification, or [RTI documentation](http://community.rti.com/rti-doc/510/ndds/doc/html/api_cpp/group__DDSQueryAndFilterSyntaxModule.html):* ``` TOPICNAME - A topic name is an identifier for a topic, and is defined as any series of characters 'a', ..., 'z', 'A', ..., 'Z', '0', ..., '9', '_' but may not start with a digit. ``` -*Note:* that the DDS specification has a known typo, where it says `-` are allowed, but the RTI documentation correctly lists `_` as allowed. +*Note:* the DDS specification has a known typo, where it says `-` are allowed, but the RTI documentation correctly lists `_` as allowed. Additionally, DDS - or more precisely the underlaying RTPS protocol - has a hard limit on topic names of 256 characters, so an additional goal is to minimize the number of extra characters used when mapping from ROS to DDS names. See The Real-time Publish-Subscribe Protocol (RTPS) DDS Interoperability Wire Protocol Specification, Table 9.12 for more details. -## ROS 2 Topic and Service Name Constraints +## Uniform Resource Locators (URLs) -In this section an outline of the proposed constrains for ROS 2 topic and service names will be enumerated along with rationales where appropriate. +Resources are addressed by means of the [Uniform Resource Locators (URL)](https://en.wikipedia.org/wiki/Uniform_Resource_Locator) format. -For convenience here is a summary of all rules for topic and service names in ROS 2: +### Syntax Components -- must not be empty -- may contain alphanumeric characters (`[0-9|a-z|A-Z]`), underscores (`_`), or forward slashes (`/`) -- may use balanced curly braces (`{}`) for substitutions -- may start with a tilde (`~`), the private namespace substitution character -- must not start with a numeric character (`[0-9]`) -- must not end with a forward slash (`/`) -- must not contain any number of repeated forward slashes (`/`) -- must not contain any number of repeated underscores (`_`) -- must separate a tilde (`~`) from the rest of the name with a forward slash (`/`), i.e. `~/foo` not `~foo` -- must have balanced curly braces (`{}`) when used, i.e. `{sub}/foo` but not `{sub/foo` nor `/foo}` +#### Host Names -The content of substitutions, i.e. the string in side of balanced curly braces (`{}`), follow very similar rules to names. -The content of substitutions: +For host-oriented resources, i.e. services, actions, and parameters, the host name refers to the ROS node that is exposing said resources. -- must not be empty -- may contain alphanumeric characters (`[0-9|a-z|A-Z]`) and underscores (`_`) -- must not start with a numeric character (`[0-9]`) +##### Definition -### Fully Qualified Names +A host name is made up of one or more tokens, delimited by periods (`.`), and thus borrowing [FQDNs](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) syntax. -The topic and service name rules allow for some convenience syntax, which in some cases requires additional context to expand to the fully qualified name and then to the DDS equivalent name. -For example, as outlined in further detail in the sections that follow, names may be relative (e.g. `foo` versus the absolute `/foo`), they may contain the private namespace substitution character (`~`), or arbitrary substitutions which are within the curly braces (`{}`) syntax. -With context, each of these features can be expanded to some simple string to form the fully qualified name. -Fully qualified names have these additional restrictions: +Each token: -- must start with a forward slash (`/`), i.e. they must be absolute -- must not contain tilde (`~`) or curly braces (`{}`) +- must not be empty. +- may use alphanumeric characters (`[0-9|a-z|A-Z]`) and/or underscores (`_`) only. +- must not start with numeric characters (`[0-9]`). +- must not contain any number of repeated underscores (`_`). -Note that expanded substitutions must result in a valid name and comply to the name constraints stated in the previous section. -An example of an invalid substitution would be `{sub}/foo` and replace `{sub}` with a numeric value, which thus leads to a topic starting with a numeric character. +As a consequence, a host name: -### Uniform Resource Locators (URLs) +- must not contain any number of repeated periods (`.`), e.g. the name `foo..bar` is not allowed. + - rationale: it removes the chance for accidental `..` from concatenation and therefore the need to collapse `..` to `.`. -Additionally, topic and service names can be represented in the [Uniform Resource Locator (URL)](https://en.wikipedia.org/wiki/Uniform_Resource_Locator) format to further disambiguate the resource name. -A topic name may be preceded by a `rostopic://` scheme prefix, and a service name may be preceded by a `rosservice://` scheme prefix. -For example, the absolute name `/foo` could also be represented as a topic with `rostopic:///foo` or as a service with `rosservice:///foo`. -Note the triple forward slash (`/`), which is a similar style to the `file://` scheme. -A relative name `foo/bar` could would be represented (as a topic) with `rostopic://foo/bar`. +Additionally, a host name must not end nor start with a period (`.`). -### ROS 2 Name Examples +The last token in a host name is its base name and any preceding tokens make up its namespace. +For example, a `foo.bar.baz` host name is made up of `foo`, `bar` and `baz` tokens, and refers to a node in the `foo.bar` namespace whose base name is `baz`. -For example, these are valid names: +#### Resource Names -| `foo` | `abc123` | `_foo` | `Foo` | `BAR` | -| `~` | `foo/bar` | `~/foo` | `{foo}_bar` | `foo/{ping}/bar` | -| `foo/_bar` | `foo_/bar` | `foo_` | `rosservice:///foo` | `rostopic://foo/bar` | +All resources, whether content-oriented or host-oriented, have a name. -But these are not valid names: +##### Definition -| `123abc` | `123` | `foo bar` | ` ` | `foo//bar` | -| `/~` | `~foo` | `foo~` | `foo~/bar` | `foo/~bar` | -| `foo/~/bar` | `foo/` | `foo__bar` | | | +A resource name is made up of one or more tokens, delimited by forward slashes (`/`), and thus borrowing URI path syntax. -These are some valid fully qualified names: +Each token: + +- must not be empty. +- may use alphanumeric characters (`[0-9|a-z|A-Z]`), underscores (`_`), and/or balanced curly braces (`{}`). +- must not start with numeric characters (`[0-9]`). +- may be a single tilde character (`~`). + +As a consequence, a resource name: -| `/foo` | `/bar/baz` | `rostopic:///ping` | `/_private/thing` | `/public_namespace/_private/thing` | +- must not contain any number of repeated forward slashes (`/`), e.g. the name `//bar` is not allowed. + - rationale: it removes the chance for accidental `//` from concatenation and therefore the need to collapse `//` to `/`. -### Namespaces +Additionally, a resource name must not end with a forward slash (`/`), but may start with one (see [Locator Resolution](#locator-resolution) section). -Topic and service names: +The last token in a resource name is its base name, and any preceding tokens make up its namespace. +For example, a `/foo/bar/baz` resource path is made up of `foo`, `bar` and `baz` tokens, and refers to a resource in the `/foo/bar` namespace whose base name is `baz`. -- may be split into tokens using a forward slash (`/`) as a delimiter +#### Resource Type - - see the "Name Tokens" section for more details on tokens +All resources have a well known type. -- must not end with a forward slash (`/`) +##### Definition -The last token is the topic or service base name, and any preceding tokens make up the namespace of the topic or service. +For each ROS resource type, a URL scheme (or protocol identifier) is defined as follows: -For example, the topic name `/foo/bar/baz` is composed of a topic or service with the base name `baz` in the `/foo/bar` namespace. -In another example, the name `/foo` splits into one token, such that it is composed of a topic or service with the base name `foo` in the `/` namespace (the root namespace). +| Resource | Scheme | +|----------------|------------| +| ROS Topics | rostopic | +| ROS Services | rosservice | +| ROS Actions | rosaction | +| ROS Parameters | rosparam | -Topic and service names: +Thus, a topic name may be preceded by a `rostopic://` scheme prefix, and a service name may be preceded by a `rosservice://` scheme prefix. +For example, the resource name `/foo` may unambiguously refer to a topic with `rostopic:///foo` or to a service with `rosservice:///foo`. +Note the triple forward slash (`/`), which is a similar style to the `file://` scheme. + +### Locator Resolution + +#### Rationale -- may be specified as absolute or relative -- must start with a forward slash (`/`) if they are absolute +For ease of use, resource locators allow for a number of context dependent resolution mechanisms. -An absolute name begins with a forward slash (`/`) and does not respect namespaces, i.e. it can be considered "global". -A relative name does not begin with a forward slash (`/`) and does respect the namespace of the node which created them. +Additionally, both resource type and host name components may be left unspecified, which may or may not lead to ambiguity when addressing resources in a system. +Tools and libraries may error in such circumstances, recompose missing components based on well known assumptions or simply leverage that ambiguity in application specific ways. +Some examples of this include but are not limited to: -Relative names are appended to the namespace of the node which creates them. -For example, if the node is put into a namespace `/ping/pong` and the topic or service name is `foo/bar`, then the absolute name will become `/ping/pong/foo/bar`. -However, if the topic or service name is `/foo/bar`, then the absolute name will stay just `/foo/bar`, ignoring the node's namespace. +- remapping paths for multiple resources of different types that are named alike if no resource type is specified e.g. `foo:=bar` may result in name remapping for matching topics, services and actions. +- presume (and enforce) that upon a given operation on a resource, said resource is of the expected type even if not resource type is specified e.g. if subscribing to `foo/chatter` it is assumed and expected that said resource name refers to a topic. +- operating on a subset of all matching resources if no resource type and/or no provider name (if it applies) are specified e.g. calling an `add_two_ints` service may result in the first service found being called or all of them being called and the first response received returned. -### Name Tokens +#### Regular Resource Names (RRNs) -"Name tokens" are the strings between the namespace delimiters, e.g. the tokens of the topic or service `/foo/bar/baz` are `foo`, `bar`, and `baz`. +Regular resource names allow for a number of context dependent resolution mechanisms. -Topic and service name tokens: +*Note*: this applies to resource names and not to provider names, which are always fully qualified. -- must not be empty, e.g. the name `//bar` is not allowed +##### Relative names resolution - - rationale: it removes the chance for accidental `//` from concatenation and therefore the need to collapse `//` to `/` +Content-oriented resource names may be absolute or relative. -- may use alphanumeric characters (`[0-9|a-z|A-Z]`), underscores (`_`), and/or balanced curly braces (`{}`) +An absolute name begins with a forward slash (`/`) and it's not affected by the addressing node's namespace. +It can be regarded as a _global_ name, or a name at the _root_ namespace. -- must not start with numeric characters (`[0-9]`) +A relative name does not begin with a forward slash (`/`) and it is resolved _relative_ to the addressing node's namespace. +Periods (`.`) in the addressing node's namespace are replaced by forward slashes (`/`) and a leading forward slash (`/`) is added during resolution. -- may be a single tilde character (`~`) +For example, if a node with the address `ping.pong.ball` publishes or subscribes to a topic `foo/bar`, then the topic name will be resolved to `/ping/pong/foo/bar`. +However, for the `/foo/bar` topic the topic name will stay `/foo/bar`, ignoring the node's namespace. -### Private Namespace Substitution Character +##### Private namespace substitution character + +The special single character token `~` is substituted by the addressing node's name. +Periods (`.`) in the addressing node's name are replaced by forward slashes (`/`) and a leading forward slash (`/`) is added during substitution. -The special single character token `~` will be replaced with a namespace snippet that is a concatenation of the namespace for the node and the node name. -For example, a node `node1` in a namespace `/foo` would result in `~` being replaced with `/foo/node1`. -As another example, a node `node1` in a namespace `foo/bar` would result in `~` being replaced with `foo/bar/node1`. It must be used at the beginning of a non-fully qualified name, if at all. + Here is a table with some example expansions: -| **Input Name** | Node: `my_node` NS: none | Node: `my_node` NS: `/my_ns` | -|----------------|--------------------------|--------------------------------| -| `ping` | *`/ping`* | *`/my_ns/ping`* | -| `/ping` | *`/ping`* | *`/ping`* | -| `~` | *`/my_node`* | *`/my_ns/my_node`* | -| `~/ping` | *`/my_node/ping`* | *`/my_ns/my_node/ping`* | +| **Name** | **Node** : `my_node` | **Node** : `my_ns.my_node` | +|----------|----------------------|----------------------------| +| `ping` | *`/ping`* | *`/my_ns/ping`* | +| `/ping` | *`/ping`* | *`/ping`* | +| `~` | *`/my_node`* | *`/my_ns/my_node`* | +| `~/ping` | *`/my_node/ping`* | *`/my_ns/my_node/ping`* | -Note the private namespace substitution character makes the name absolute, and therefore the namespace is not added a second time. +Note that the private namespace substitution character makes the name absolute, and therefore the namespace is not added a second time. -### Substitutions +##### Substitutions -The bracket syntax (`{substitution_name}`) may be used in non-fully qualified names to substitute useful contextual information into the name. -The set of substitution keys (names) are not set in this document, but some reasonable examples might be: `{node}` expands to the current node's name or `{ns}` expands to the current node's namespace. +The bracket syntax (`{substitution_name}`) may be used in resource names to substitute useful contextual information into the them. +The set of substitution keys (names) are not set in this document, but some reasonable examples might be `{node}`, expanding to the addressing node's name, or `{ns}`, expanding to the addressing node's namespace. + +Substitutions must result in a valid name and comply with the name constraints. +An example of an invalid substitution would be `{sub}/foo` and replace `{sub}` with a numeric value, which thus leads to a *invalid* resource name starting with a numeric character. Substitutions are expanded after the private namespace substitution character is expanded. Therefore a substitution may not contain the private namespace substitution character, i.e. `~`. -For example, given the name `{private}foo` and a substitution called `{private}` which expands to `~/_`, you will get an error because the `~/_` will end up in the expanded name as `/my_ns/~/_foo` which is is not allowed to have a `~` in it. +For example, given the name `{private}foo`, a substitution called `{private}` which expands to `~/_` results in an error because the `~/_` will end up in the expanded name as `/my_ns/~/_foo`, which is invalid. Substitutions are expanded in a single pass, so substitutions should not expand to contain substitutions themselves. For example, given the name `/foo/{bar_baz}` where `{bar_baz}` expands to `{bar}/baz` and where `{bar}` in turn expands to `bar`, you will get `/foo/{bar}/baz` as the final result, which is invalid, and not `/foo/bar/baz` as you might expect. @@ -192,81 +219,154 @@ Substitutions are also not allowed to be nested, i.e. substitutions may not cont This is implicitly enforced by the rules above that say substitution names may only contain alphanumerics and underscores (`_`). For example, given the name `{% raw %}/foo/{{bar}_baz}{% endraw %}` would result in an error because `{` and `}` are not allowed in a substitution names and the substitution name `{bar}_baz` does contain them. -### Hidden Topic or Service Names +#### Fully Qualified Resource Names (FQRNs) + +Regular resource name resolution rules allow for convenient syntax, which in some cases requires additional context to expand to a fully qualified name that can be mapped to another kind of name e.g. a DDS topic name. +For example, as outlined in further detail in the preceding sections, resource names may be relative (e.g. `foo` versus the absolute `/foo`), they may contain the private namespace substitution character (`~`), or arbitrary substitutions in curly braces (`{}`) syntax. +With enough context, each of these features can be expanded to some simple string to form the fully qualified name. + +Fully qualified names have these additional restrictions: + +- must start with a forward slash (`/`), i.e. they must be absolute. +- must not contain tilde (`~`) nor balanced curly braces (`{}`). -Any topic or service name that contains any tokens (either namespaces or a topic or service name) that start with an underscore (`_`) will be considered hidden and tools may not show them unless explicitly asked. +### Resource Qualification -## Mapping of ROS 2 Topic and Service Names to DDS Concepts +#### Hidden nodes -The ROS topic and service name constraints allow more types of characters than the DDS topic names because ROS additionally allows the forward slash (`/`), the tilde (`~`), and the balanced curly braces (`{}`). -These must be substituted or otherwise removed during the process of converting the topic or service name to DDS concepts. -Since ROS 2 topic and service names are expanded to fully qualified names, any balanced bracket (`{}`) substitutions and tildes (`~`) will have been expanded. -Additionally any URL related syntax, e.g. the `rostopic://` prefix, will be removed once parsed. -Previously forward slashes (`/`) were disallowed in DDS topic names, now the restriction has been lifted (see [issue](https://issues.omg.org/issues/lists/dds-rtf5#issue-42236) on omg.org) and therefore the ROS topic names are first prefixed with ROS Specific Namespace prefix (described below) are then mapped directly into DDS topic names. +If a node name (a.k.a. resource host) contains any tokens that start with an underscore (`_`), the node it refers to will be considered hidden and tools may not show them unless explicitly asked to do so. + +#### Hidden resources + +If a resource name contains any tokens that start with an underscore (`_`), the resource it refers to will be considered hidden and tools may not show them unless explicitly asked to do so. + +### Examples + +For example, these are valid names: + +| `foo` | `abc123` | `_foo` | `Foo` | `BAR` | +| `~` | `foo/bar` | `~/foo` | `{foo}_bar` | `foo/{ping}/bar` | +| `foo/_bar` | `foo_/bar` | `foo_` | `rosservice:///foo` | `rostopic://foo/bar` | + +But these are not valid names: + +| `123abc` | `foo//bar` | `foo bar` | `foo/~/bar` | +| `/~` | `~foo` | `foo~` | `foo~/bar` | +| `foo/` | `/456` | `~/456` | `foo/~bar` | + +These are some valid fully qualified names: + +| `/foo` | `rosparam://another.node/bool_param` | +| `rosaction://a.node/ping` | `/bar/baz` | +| `rostopic:///ping` | `/_private/thing` | +| `/public_namespace/_private/thing` | `rosservice://_private.node/reset` | + +### Summary + +For convenience, here is a summary of all the rules that apply to URLs in ROS. + +Host names in a URL: + +- may contain alphanumeric characters (`[0-9|a-z|A-Z]`), underscores (`_`) and periods (`.`). +- must not start with a numeric character (`[0-9]`). +- must not end nor start with a period (`.`). +- must not contain any number of repeated periods (`.`). +- must not contain any number of repeated underscores (`_`). + +Resource names in a URL: + +- must not be empty. +- may contain alphanumeric characters (`[0-9|a-z|A-Z]`), underscores (`_`), and forward slashes (`/`). +- may use balanced curly braces (`{}`) in the resource name for substitutions i.e. `{sub}/foo` but not `{sub/foo` nor `/foo}`. +- may start with a tilde (`~`), the private namespace substitution character. +- must not start with a numeric character (`[0-9]`). +- must not end with a forward slash (`/`). +- must not contain any number of repeated forward slashes (`/`). +- must not contain any number of repeated underscores (`_`). +- must separate a tilde (`~`) from the rest of the name with a forward slash (`/`), i.e. `~/foo` not `~foo`. + +The content of substitutions, i.e. the string in side of balanced curly braces (`{}`), follow very similar rules to names. +These: + +- must not be empty. +- may contain alphanumeric characters (`[0-9|a-z|A-Z]`) and underscores (`_`). +- must not start with a numeric character (`[0-9]`). + +## Mapping Resource Names to DDS Concepts + +### Naming Constraints + +#### Allowed characters + +The ROS URL syntax allows for more characters than are allowed in other kinds of name e.g. DDS topic names. +For example, the tilde (`~`), the balanced curly braces (`{}`), the period (`.`) and the semicolon (`:`) are all allowed in the ROS URL syntax, but are not allowed in DDS topic names. +These must be substituted or otherwise removed during the process of converting a ROS URL to another kind of name e.g. a DDS topic name. + +*Note*: Previously, forward slashes (`/`) were also disallowed in DDS topic names but now the restriction has been lifted (see [issue](https://issues.omg.org/issues/lists/dds-rtf5#issue-42236) on omg.org) and therefore ROS topic names are first prefixed with a ROS Specific Namespace prefix (described below) and then mapped directly to DDS topic names. + +After ROS resource names are expanded to fully qualified names, any balanced bracket (`{}`) substitutions and tildes (`~`) will have been expanded. +Periods (`.`) in host names must be transformed into another suitable character e.g. the forward slash `/`, as it is done when resolving relative resource names. +Type schemes must also be removed after parsing and before mapping can take place. + +#### Name Length Limit + +The length of a DDS topic name must not exceed 256 characters. Therefore the length of a ROS topic name, including the namespace hierarchy, the base name of the topic and any ros specific prefixes must not exceed 256 characters since this is mapped directly as DDS topic. + +##### Considerations for RTI Connext + +While testing our implementation with Connext, we encountered some additional limitations when it comes to the topic length. +That is, for example the length of a service name has tighter limits than the length of a topic. +In the RTI Connext implementation, service names are suffixed with the GUID value of the DDS participant for the service response topic. +Additionally, a content filtered topic (max length 256 characters) is created which is mapped from the suffixed service name. +Therefore when linking against `rmw_connext_c` or `rmw_connext_cpp`, service names cannot be longer than 185 characters including the namespace hierarchy and any ROS specific prefixes. ### ROS Specific Namespace Prefix -In order to differentiate ROS topics easily, all DDS topics created by ROS shall be automatically prefixed with a namespace like `/rX`, where `X` is a single character that indicates to which subsystem of ROS the topic belongs. -For example, a plain topic called `/foo` would translate to a DDS topic `rt/foo`, which is the result of implicitly adding `rt` to the namespace of a ROS topic which is in the root namespace `/` and has a base name `foo`. +In order to differentiate ROS resources easily in a DDS ecosystem, all DDS resources like topics created by ROS shall have their names automatically prefixed with a namespace like `/rX`, where `X` is a single character that indicates to which subsystem of ROS the resource belongs. +For example, a plain topic called `/foo` would translate to a DDS topic called `rt/foo`, which is the result of implicitly adding `rt` to the namespace of a ROS topic which is in the root namespace `/` and has a base name `foo`. As another example, a topic called `/left/image_raw` would translate to a DDS topic `rt/left/image_raw`, which is the result of implicitly adding `rt` to the namespace of a ROS topic which is in the namespace `/left` and has a base name `image_raw`. -For systems where Services are implemented with topics (like with OpenSplice), a different subsystem character can be used: `rq` for the request topic and `rr` for the response topic. -On systems where Services are handled explicitly implemented, we consider a separate prefix, e.g. `rs`. +For systems where services are implemented with topics (e.g. OpenSplice), a different subsystem character can be used: `rq` for the request topic and `rr` for the response topic. +On systems where services are handled explicitly implemented, we consider a separate prefix, e.g. `rs`. Here is a non-exhaustive list of prefixes: | ROS Subsystem | Prefix | |----------------------|--------| -| ROS Topics | rt | +| ROS Topic | rt | +| ROS Service | rs | | ROS Service Request | rq | | ROS Service Response | rr | -| ROS Service | rs | -| ROS Parameter | rp | -| ROS Action | ra | While all planned prefixes consist of two characters, i.e. `rX`, anything proceeding the first namespace separator, i.e. `/`, can be considered part of the prefix. The standard reserves the right to use up to 8 characters for the prefix in case additional prefix space is needed in the future. -### Examples of ROS Names to DDS Concepts +### Examples Here are some examples of how a fully qualified ROS name would be broken down into DDS concepts: -| ROS Name | DDS Topic | +| ROS Topic Name | DDS Topic | |---------------------------------|-----------------------------------| | `/foo` | `rt/foo` | | `rostopic:///foo/bar` | `rt/foo/bar` | | `/robot1/camera_left/image_raw` | `rt/robot1/camera_left/image_raw` | +### Addressing Non-ROS DDS Resources -### ROS Topic and Service Name Length Limit - -The length of the DDS topic must not exceed 256 characters. Therefore the length of a ROS Topic, including the namespace hierarchy, the base name of the topic and any ros specific prefixes must not exceed 256 characters since this is mapped directly as DDS topic. - -#### Considerations for RTI Connext - -While testing our implementation with Connext, we encountered some additional limitations when it comes to the topic length. -That is, for example the length of a service name has tighter limits than the length of the ROS Topics. -The RTI Connext implementation for service names are suffixed with the GUID value of the DDS participant for the service response topic. -Additionally, a content filtered topic (max length 256 characters) is created which is mapped from the suffixed service name. -Therefore when linking against `rmw_connext_c` or `rmw_connext_cpp`, service names cannot be longer than 185 characters including the namespace hierarchy and any ros specific prefixes. - -### Communicating with Non-ROS Topics - -Since all ROS topics are prefixed when being converted to DDS topic names, it makes it impossible to subscribe to existing DDS topics which do not follow the same naming pattern. -For example, if an existing DDS program is publishing on the `image` topic (and is using the DDS equivalent to the ROS message type) then a ROS program could not subscribe to it because of the name mangling produced by the implicit ROS specific namespace. -Therefore to allow ROS programs to interoperate with "native" DDS topic names the API should provide a way to skip the ROS specific prefixing. - +Since all ROS URLs are transformed and prefixed when being converted to DDS resource names, it makes it impossible to address existing DDS resources which do not follow the same naming pattern. +For example, if an existing DDS program is publishing on the `image` topic (and is using the DDS equivalent to the ROS message type) then a ROS program would not be able to subscribe to it because of the name mangling produced by the implicit ROS specific namespace. +Therefore, to allow ROS programs to interoperate with "native" DDS topic names, the API should provide a way to skip the ROS specific prefixing. -There is an option in the API, a boolean `avoid_ros_namespace_convention` in the qos_profile which can be set to `false` to use ROS prefix and `true` to not using ROS namespace prefixing. +There is an option in the API, a boolean `avoid_ros_namespace_convention` in the `qos_profile` which can be set to `false` to use ROS namespace prefixes and to `true` to not use them. For example: -| ROS Name | avoid_ros_namespace_conventions | DDS Topic | -|-----------------------|------------------------------------|-------------| -| `rostopic://image` | `false` | `rt/image` | -| `rostopic://image` | `true` | `image` | +| ROS Name | avoid\_ros\_namespace_conventions | DDS Topic | +|--------------------|-----------------------------------|------------| +| `rostopic://image` | `false` | `rt/image` | +| `rostopic://image` | `true` | `image` | -#### Alternative(Idea) +#### Alternative (Idea) Note that the alternative below is not part of the proposal, but only possible solutions to the issue of communicating with "native" DDS topics. Another option would be to have some markup in the scheme name, for example: @@ -278,35 +378,35 @@ Another option would be to have some markup in the scheme name, for example: | `rostopic+exact://camera_left/image` | `camera_left/image` | | `rostopic+exact:///camera_left/image` | `camera_left/image` | -## Compare and Contrast with ROS 1 +## Comparison with ROS 1 In order to support a mapping to the - slightly more - restrictive DDS topic name rules, these rules are in some ways more constraining than the rules for ROS 1. Other changes have been proposed for convenience or to remove a point of confusion that existed in ROS 1. -In ROS 2, topic and service names differ from ROS 1 in that they: +In ROS 2, resource names differ from ROS 1 in that they: -- must separate the tilde (`~`) from the rest of the name with a forward slash (`/`) +- must separate the tilde (`~`) from the rest of the name with a forward slash (`/`). - - This is done to avoid inconsistency with how `~foo` works in filesystem paths versus when used in a ROS name. + - This is done to avoid inconsistency with how `~foo` works in filesystem paths versus when used in a name. - may contain substitutions which are delimited with balanced curly braces (`{}`) - This is a more generic extension of the idea behind the tilde (`~`). -- have length limits +- have length limits. - - This is driven by the topic name length limit of DDS. + - This is driven by the name length limits in DDS. -- may be indicated as "hidden" by using a leading underscore (`_`) in one of the namespaces +- may be indicated as "hidden" by using a leading underscore (`_`) in one of the namespaces. - - This is used to hide common but infrequently introspected topics and services. + - This is used to hide common but infrequently introspected resources like topics and services. -## Concerns/Alternatives +## Discussion This section lists concerns about the proposed design and alternatives that were considered. ### Alternative Name Rules and Concerns About Name Rules -There were some suggested but then rejected alternatives to the rules for topic and service names. +There were some suggested but then rejected alternatives to the rules for ROS resource names. #### More Versatile Private Namespace Substitution Character @@ -337,7 +437,7 @@ The `{}` syntax will collide with Python String substitution, but since that is This document does not prescribe what substitutions should be supported by implementations. This was done to avoid blocking progress on this document on the need to agree on the set of required substitutions. However, this is just delaying the issue. -For the substitutions to be useful, then all implementations that process topic and service names need to support them. +For the substitutions to be useful, then all implementations that process resource names need to support them. This compromise was made so that when more work is done on substitutions, it would hopefully not require changes to the name syntax, but instead revolve around what substitutions to support and whether or not that support is optional. @@ -347,14 +447,15 @@ There was some discussion of alternatives and concerns with respect to the ROS - #### Alternative using DDS Partitions -Previously the usage of forward slashes (`/`) was disallowed in DDS topic name and hence a strategy was proposed which used DDS partitions to address the forward slashes (`/`) which are present in ROS names. The main idea was to separate the ROS name into the "namespace" and the "base name", and then place the namespace, stripped of leading and trailing forward slashes (`/`), into a single DDS partition entry and the remaining base name into the DDS topic name. -This addressed the issue because the ROS name's base name will not contain any forward slashes (`/`) by definition and so there are no longer any disallowed characters in the DDS topic name. -The DDS partition would contain the ROS name's namespace, including any forward slashes (`/`) that made up the namespace and were not at the beginning or the end of the namespace. -That is acceptable because DDS partitions are allowed to contain forward slashes (`/`) unlike the DDS topics previously but now DDS topic names allow forward slashes (`/`). +Previously the usage of forward slashes (`/`) was disallowed in DDS topic names and hence a strategy was proposed which used DDS partitions to address the forward slashes (`/`) which are present in ROS resource names. The main idea was to separate the ROS resource name into "namespace" and "base name", and then place the namespace, stripped of leading and trailing forward slashes (`/`), into a single DDS partition entry and the remaining base name into the DDS topic name. +This addressed the issue because ROS resource base names will not contain any forward slashes (`/`) by definition and so there are no longer any disallowed characters in the DDS topic name. +The DDS partition would contain the ROS resource namespace, including any forward slashes (`/`) that made up the namespace and were not at the beginning or the end of the namespace. +That is acceptable because DDS partition names are allowed to contain forward slashes (`/`) unlike the DDS topic names previously, but now DDS topic names allow forward slashes (`/`). -DDS partitions are implemented as an array of strings within the `DDS::Publisher` and `DDS::Subscriber` QoS settings and have no hierarchy or order, Each entry in the partition array is directly combined with the DDS topic and they are not sequentially combined. +DDS partitions are implemented as an array of strings within the `DDS::Publisher` and `DDS::Subscriber` QoS settings and have no hierarchy or order. +Each entry in the partition array is directly combined with the DDS topic and they are not sequentially combined. If a publisher has two partition entries, e.g. `foo` and `bar` with a base name of `baz`, this would be equivalent to having two different publishers on these topics: `/foo/baz` and `/bar/baz`. -Therefore this proposal used only one of the strings in the partitions array to hold the entire ROS name's namespace. +Therefore this proposal used only one of the strings in the partitions array to hold the entire ROS resource's namespace. You can read more about partitions in RTI's documentation: @@ -362,19 +463,19 @@ You can read more about partitions in RTI's documentation: Trade-offs (in comparison to using the whole ROS name along with the namespaces): -- Splitting the ROS name into "namespace" and "base name", and placing the complete namespace into a field designed for another purpose seemed incorrect. -- In general partitions are recommended to be used as a spare, but using partitions for all ROS names suggested otherwise. +- Splitting the ROS resource name into "namespace" and "base name", and placing the complete namespace into a field designed for another purpose seemed incorrect. +- In general partitions are recommended to be used as a spare, but using partitions for all ROS resource names suggested otherwise. - Major concern was reported in this [issue](https://github.com/ros2/rmw_connext/issues/234), where having two topics with same base name, although different namespace and different types caused problem. For example: topicA is `/camera/data` of type `Image` and topicB is `/imu/data` of type `Imu`. The base names for both topicA and topicB is `data`, generated errors as described in the [issue](https://github.com/ros2/rmw_connext/issues/234). - Newer standards such as [DDS-XRCE](https://www.omg.org/spec/DDS-XRCE) might not have partitions at all. -- Using the complete ROS name in the later strategy will cause a tighter length limit on base name because the DDS topic name would contain ROS prefix, namespace along with the base name which should not exceed DDS topic name limitation which is 256 characters. +- Using the complete ROS name in the later strategy will cause a tighter length limit on base name because the DDS topic name would contain ROS prefix, namespace along with the base name which should not exceed DDS topic name limitation which is 256 characters. Rationale: - With the decision from the DDS vendors to allow forward slashes (`/`) in DDS topic names, using the complete ROS name seemed simple and more intuitive than using partitions. #### Alternative Substitute the Namespace Delimiter -A previous proposal was to substitute the namespace delimiter, i.e. forward slash (`/`), with something that is allowed in DDS topic names, and then only use the DDS topic name to represent the full ROS name. -For example in the simplest case, a topic `/foo/bar/baz` might become `__foo__bar__baz`, where the forward slash (`/`) is being replaced with a double underscore (`__`) and double underscores (`__`) were not allowed in ROS topic and service names. +A previous proposal was to substitute the namespace delimiter, i.e. the forward slash (`/`), with something that is allowed in DDS topic names, and then only use the DDS topic name to represent the full ROS resource name. +For example in the simplest case, a topic name `/foo/bar/baz` might become `__foo__bar__baz`, where the forward slash (`/`) has been replaced with a double underscore (`__`) and double underscores (`__`) were not allowed in ROS resource names. Trade-offs (in comparison to the use of DDS partitions):