Gazebo Simulation Setup

This guide walks you through setting up the Gazebo simulation used in the Your First Project tutorial.

Prerequisites

• Docker Desktop installed and running
• A free Viam account
• ~5GB disk space for the Docker image

Step 1: Build the Docker Image

The simulation runs in a Docker container with Gazebo Harmonic and viam-server pre-installed.

Clone the simulation repository:

git clone https://github.com/viamrobotics/can-inspection-simulation.git
cd can-inspection-simulation

Build the Docker image:

docker build -t gz-harmonic-viam .

This takes 5-10 minutes depending on your internet connection.

Step 2: Create a Machine in Viam

1. Go to app.viam.com and log in
2. Click the Locations tab
3. Click + Add machine
4. Name it inspection-station-1
5. Click Add machine

Step 3: Create a credentials file

1. Click the Awaiting setup button
2. Click Machine cloud credentials to copy your machine’s credentials
3. In the can-inspection-simulation directory, create a file called station1-viam.json
4. Paste your machine’s credentials into this file and save

Step 4: Start the Container

Note

If you have a local installation of viam-agent running on your machine, it uses port 8080 by default. Running the container with -p 8080:8080 will conflict with it. To avoid this, either stop the local viam-agent before starting the container, or change the host port mapping (for example, -p 8090:8080) and access the container on the new port instead.

• Mac/Linux
• Windows (PowerShell)

docker run --name gz-station1 -d \
  -p 8080:8080 -p 8081:8081 -p 8443:8443 \
  -v "$(pwd)/station1-viam.json:/etc/viam.json" \
  gz-harmonic-viam

docker run --name gz-station1 -d `
  -p 8080:8080 -p 8081:8081 -p 8443:8443 `
  -v "${PWD}\station1-viam.json:/etc/viam.json" `
  gz-harmonic-viam

Step 5: Verify the Setup

Check container logs:

docker logs gz-station1

Look for:

• “Can Inspection Station 1 Running!”
• viam-server startup messages

View the simulation:

Open your browser to http://localhost:8081

You should see a web-based 3D view of the inspection station with:

• A conveyor belt
• Cans moving along the belt
• An overhead camera view

Verify machine connection:

1. Go to app.viam.com
2. Click on inspection-station-1
3. The status indicator should show Live (in green)

Troubleshooting

Container won't start

Check if ports are in use:

• Mac/Linux
• Windows (PowerShell)

lsof -i :8080
lsof -i :8081

netstat -ano | findstr :8080
netstat -ano | findstr :8081

If something is using these ports, stop it or use different port mappings.

Machine shows Offline in Viam

1. Check container is running: docker ps
2. Check logs for errors: docker logs gz-station1
3. Verify credentials in your config file match the Viam app
4. Try restarting: docker restart gz-station1

Simulation viewer is blank or slow

• The web viewer requires WebGL support
• Try a different browser (Chrome usually works best)
• Check your system has adequate resources (4GB+ RAM recommended)

Container Management

Stop the container:

docker stop gz-station1

Start a stopped container:

docker start gz-station1

Remove the container (to recreate):

docker rm gz-station1

View logs:

docker logs -f gz-station1

Ready to Continue

Once your machine shows Live in the Viam app, you’re ready to continue with the tutorial.

**Continue to Part 1: Vision Pipeline →