ROSProxy

📌 Companion paper

• DOI: 10.1109/SII52469.2022.9708884
• arXiv: arXiv:2201.01613

Transparently proxy ROS communication between different networks - physical or virtual - or connect local containers to an external ROS network.

Get it!

npm

the npm package allows you to run the rosproxy cli as rosproxy; from everywhere when installed globally.

npm install -g rosproxy

container

get it in a container form ghcr.io

docker pull ghcr.io/bitmeal/rosproxy

Use it

• point the proxy to your ROS master
• configure the proxy http://<internal_hostname>:<port>/master as master for nodes to proxy
• 🎉

rosproxy [options] [port]

• --port/-p (default: copied from $ROS_MASTER_URI): management/XMLRPC API port to listen on; must be available on internal (to be proxied) network segment
• --ros-master-uri/-m or $ROS_MASTER_URI: ROS master address
• --hostname/-n or $ROS_HOSTNAME/$ROS_IP (default: machines hostname): hostname to report to all ROS nodes for proxied endpoints; has to be available from the external (to be proxied to) network
• --port-range/-r (default: none/random allocation): limit all port allocations (except master API) to given range; enables exposing nodes from containers
• --quiet/-q: suppress output
• --debug/-d: set log level debug

Example

Running ROSProxy using node/npm package. Will read master address and hostname from ROS environment variable configuration and use same port as your ROS master:

# assuming configured ROS environment:
# ROS_MASTER_URI=http://yourmasteruri:11311/
# ROS_HOSTNAME=myhost
rosproxy

Run a node with proxied connection:

ROS_MASTER_URI=http://myhost:11311/ rosrun <pkg> <node>

Proxying containerized ROS nodes

Using ROSProxy you can enable containerized ROS nodes to communicate with nodes running "directly" on a network - and vice versa. Below docker-compose file uses a container node running some ROS node, and a rosproxy container. As in the example above, ROS_MASTER_URI is set to the actual masters address for the proxy and the proxy address for the node. We configure ROSProxy to allocate all its proxy ports from the range 50000-50100, which should serve ~50 nodes (n/2). This port range gets forwarded to the host and will make all containerized nodes using the proxy available from the outside.

version: '3.8'

services:
  node:
    image: ros:noetic-ros-core
    environment:
    - ROS_MASTER_URI=http://rosproxy:11311/
    - ROS_HOSTNAME=node
    command: ['rosrun', '<pkg>', '<node>']
    depends_on:
    - rosproxy
  
  rosproxy:
    image: ghcr.io/bitmeal/rosproxy
    environment:
    - ROS_MASTER_URI=http://roscore:11311/
    - ROS_HOSTNAME=rosproxy
    command: ['-r', '50000-50100']
    ports:
    - "50000-50100"

Development

Testing

⚠ Test requires docker/docker-compose (and WSL on Windows)

npm test

Tests use bats testing framework. Running npm test will take care of most things and report what's missing. Info and error messages generated by npm test may not be TAP compliant! To ensure machine readable output, init submodules manually and ensure all dependencies to be available.

• Tests are executed in a docker-compose setup, recreating a NAT routed setup with internal and external networks.
• Use ASCII collation order LC_COLLATE=C when running bats without using test/test.bash

License and citing

The source code provided in this repository is licensed under MPL 2.0. A different license may apply to binary versions of this software!

If used in published research, please cite as:

• A. Wendt and T. Schüppstuhl, "Proxying ROS communications — enabling containerized ROS deployments in distributed multi-host environments," 2022 IEEE/SICE International Symposium on System Integration (SII), 2022, pp. 265-270, DOI: 10.1109/SII52469.2022.9708884.

You may use following BibTeX entry:

@inproceedings{Wendt_Schuppstuhl_2021_ROSProxy,
    author={Wendt, Arne and Sch{\"u}ppstuhl, Thorsten},
    booktitle={{2022 IEEE/SICE International Symposium on System Integration (SII)}},
    title={{Proxying ROS communications — enabling containerized ROS deployments in distributed multi-host environments}},
    year={2022},
    pages={265-270},
    doi={10.1109/SII52469.2022.9708884}
}