https://github.com/bitmeal/rosproxy
A proxy for the Robot Operating System (ROS)
https://github.com/bitmeal/rosproxy
container docker proxy ros
Last synced: about 2 months ago
JSON representation
A proxy for the Robot Operating System (ROS)
- Host: GitHub
- URL: https://github.com/bitmeal/rosproxy
- Owner: bitmeal
- License: mpl-2.0
- Created: 2021-08-08T19:17:34.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2022-03-02T16:41:25.000Z (over 4 years ago)
- Last Synced: 2025-08-16T13:33:35.820Z (10 months ago)
- Topics: container, docker, proxy, ros
- Language: JavaScript
- Homepage:
- Size: 199 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ROSProxy
> 📌 Companion paper
> * DOI: [10.1109/SII52469.2022.9708884](https://doi.org/10.1109/SII52469.2022.9708884)
> * arXiv: [arXiv:2201.01613](https://arxiv.org/abs/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://:/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:
```bash
# assuming configured ROS environment:
# ROS_MASTER_URI=http://yourmasteruri:11311/
# ROS_HOSTNAME=myhost
rosproxy
```
Run a node with proxied connection:
```bash
ROS_MASTER_URI=http://myhost:11311/ rosrun
```
### 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.
```yaml
version: '3.8'
services:
node:
image: ros:noetic-ros-core
environment:
- ROS_MASTER_URI=http://rosproxy:11311/
- ROS_HOSTNAME=node
command: ['rosrun', '', '']
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)
```bash
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](https://doi.org/10.1109/SII52469.2022.9708884).
You may use following BibTeX entry:
```bibtex
@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}
}
```