Redirecting backend REST and WebSocket communication during URCap development
Introduction
When developing both frontend and backend contributions, you can redirect all REST and WebSocket traffic to a different server without modifying your backend code. This configurable proxy feature can ease the development and integration of components and easily be removed after development. Examples include:
The URCap is running on a robot, to enable debugging, the backend server is running in an IDE on a developer PC
The URCap is running in simulation, to enable the frontend to access robot specific resources, such as tool connector or USB hotplug, the backend is running on a robot.
The URCap is running in simulation and the backend is running directly on a PC host.
Configuration
Enabling redirection is done in the URCap manifest file, specifically in the container.ingress
section,
using the devUrl
key.
Case 1: Running a URCap on the robot and directing REST/WS traffic to an IDE running on another host
The following example enables all traffic in the simple-docker
sample to be redirected to a server running at
port 5000 on a development machine with IP address 10.52.4.26.
Step 1: Configure URCap and reinstall on the robot
Add the devUrl
to the URCaps manifest and reinstall the URCap on the robot.
containers:
- id: "simple-docker-backend"
image: "simple-docker-backend:latest"
ingress:
- id: rest-api
containerPort: 5000
protocol: http
proxyUrl: /
devUrl: http://10.52.4.26:5000
mounts:
- mount: persistent:/mount
access: rw
Note
Undoing the redirection is as simple as commenting out the devUrl line above
Step 2: Run the simple-docker backend (simple-rest-api.py) from and IDE on the developer machine
In this specific case, special attention is needed when running the simple-docker-backend python server from an IDE:
proxyUrl
As can be seen above, the server running in the container is using the “proxyUrl” feature. When PolyScope X starts a
backend container contribution the proxyUrl conveniently maps the long unique container URL to something simpler inside
the contribution container, in this case
universal-robots/simple-docker/simple-docker-backend/rest-api
is mapped to /
.
We must compensate for this when running the server in an IDE outside of the URCap container either by not using proxyUrl
or making a change in the code running in the IDE. In simple-rest-api.py
it could look like this:
...
PROXY_URL_PREFIX = "/universal-robots/simple-docker/simple-docker-backend/rest-api"
@app.route(PROXY_URL_PREFIX+"/", methods=["GET"])
...
@app.route(PROXY_URL_PREFIX+"/", methods=["POST"])
...
Container resources
In the above manifest snippet we can see that the backend container will create a /mount
mount point inside the
container. When running outside the container we can either create this folder manually or use a different file path in
the code. In simple-rest-api.py
this could look like:
...
#data_file = "/mount/data.txt"
data_file = "/my/path/data.txt"
...
After taking care of these details, run the Python Flask server on port 5000.
Case 2 Running a URCap in simulation and directing REST/WS traffic to an backend URCap running on a robot
These are almost the same steps as in case 1.
Again the example URCap is the simple-docker
sample, this time installed in the simulator. REST/WS traffic is redirected to a
backend URCap running on a robot with IP address 10.54.4.231
Step 1: Configure URCap and reinstall in the simulator
Add the devUrl
to the URCaps manifest and reinstall the URCap in the simulator.
containers:
- id: "simple-docker-backend"
image: "simple-docker-backend:latest"
ingress:
- id: rest-api
containerPort: 5000
protocol: http
proxyUrl: /
devUrl: http://10.54.4.231/universal-robots/simple-docker/simple-docker-backend/rest-api/
mounts:
- mount: persistent:/mount
access: rw
Step 2: Install URCap on the robot
Note: In this case, the URCap installed on the robot does not need the devUrl parameter.
Case 3 Running a URCap in simulation and directing REST/WS traffic to an IDE on the developer PC host
When developing a URCap in simulation it might be convenient to develop the backend outside the URCap docker container.
This example enables all traffic in the simple-docker
sample to be redirected from the simulator to a server running on
the simulator host at port 5000.
Step 1: Configure URCap and reinstall in the simulator
Add the devUrl
to the URCaps manifest and reinstall the URCap in the simulator.
containers:
- id: "simple-docker-backend"
image: "simple-docker-backend:latest"
ingress:
- id: rest-api
containerPort: 5000
protocol: http
proxyUrl: /
devUrl: http://10.52.4.26:5000
mounts:
- mount: persistent:/mount
access: rw
Step 2: Run the simple-docker backend (simple-rest-api.py) from and IDE on the simulator host machine
When running a backend URCap contribution outside of its contribution container, it is needed to compensate for the URCap container features not available outside the container. See Case 1 - Step 2 on how to do that for the simple-docker backend. Finally, run the Python Flask server on port 5000 on the simulator host.