MacSim

This repository contains a docker image to run a vrx gazebo simulation. This simulation uses ROS for communication. In addition, we use the Rosbridge suite to allow for communication between non-ros clients such as the browser or a node applicaiton.

Requirements

Docker

Running The Image

To build image locally, clone this repository build the image in images/base:

git clone https://github.com/cjpappas/MacSim.git
docker build -f images/base/Dockerfile -t altmattr/simulation .

Alternatively, you can pull the latest version from Dockerhub. This is done automatically if the image isn't found locally. We provide two images, one for standard (linux/amd64) architectures and one for the M1 chips (linux/arm64). The default image that is pulled is linux/amd64. If you want to run the sim on an M1, please use altmattr/simulation:latest-m1 in the command below.

To run the image:

docker run -itd \
    --name sim \
    -p 9090:9090 \
    -p 8080:8080 \
    -p 80:80 \
    altmattr/simulation:latest

You can connect to the image and source ROS with:

docker exec -it sim /bin/bash
source /opt/ros/noetic/setup.bash
source ~/vrx_ws/devel/setup.bash

Connecting to the Simulation

The container hosts a small webserver that allows you to connect to the simulation via a webpage. To access the simulation you can navigate to http://localhost or you can open the image/base/html/hud/html in the browser and it will provide a visula overview of the simualtion. You can also connect to the simulation from other programs such as node. Detailed documentation on the api can be found on the repositories wiki here.

Development

For those wishing to alter the codebase, we recommend starting the container with the html folder mounted so changes are instantly reflected:

docker run -itd \
    --name sim \
    -v <path_to_folder>/images/base/html:/home/developer/html \
    -p 9090:9090 \
    -p 8080:8080 \
    -p 80:80 \
    altmattr/simulation

Changing the Goal Location for Staion Keeping

To change the goal location and heading, change the value in the <goal_pose> tags in images/base/src/vrx/vrx_gazebo/worlds/stationkeeping_task.world.xacro. Note if you move the position far enough away that it is outside the default zoom of the map, it may be a good idea to lower the zoom value in the initMap function of hud.html.

Generating & Sharing Programs

You can generate and share programs with other users through the use of base64 encoded strings. These strings can be provided through the code url parameter http://.../hud?code=<base64_string>. There are currently two options to generate these strings:

Through the browser using the share button.
Through the node program provided as part of the repository.

The links generated by the browser provide a url for people running the application on localhost and (coming soon) a url to view the demo program using the application running on a remote server.

The node program is located in local_programs/program_encoder. The program can be run (from the project root) with:

node local_programs/program_encoder/Main.js <path_to_file>

This will output the encoded program string to the console, which you can then supply in the url.

Troubleshooting

If your docker build fails, try increasing the memory and the swap file available to docker (docker desktop > preferences).

Submission Image

To build to submission image:

docker build -t altmattr/macsim-submission -f ./images/submission/Dockerfile .

To run the submission image:

docker run -it \
    --name macsim-submission \
    -v <path_to_repo>/MacSim/images/submission/src:/home/macsim/src \
    altmattr/macsim-submission

The submission image is expecting an eviroment variable COMPETITOR_IP to be set by the test script. If you want to run the image without the test script, add the enviroment variable to docker run:

docker run -it \
    -e COMPETITOR_IP=localhost \
    --name macsim-submission \
    -v <path_to_repo>/MacSim/images/submission/src:/home/macsim/src \
    altmattr/macsim-submission

cjpappas / MacSim

readme