Detect and Follow a Colored Object with the SCUTTLE Robot on Viam

This tutorial shows how to use the Viam Vision Service to make a SCUTTLE rover follow a colored object.

Code used in this tutorial GitHub Gist


The prerequisite of this tutorial is to have a SCUTTLE rover connected to the Viam app. Please refer to the Configure a SCUTTLE Robot tutorial if you have not already configured your SCUTTLE.

Set up your code environment

We highly suggest using a virtual Python environment like Poetry or Miniconda.

Then create an environment for Python by running the following on the terminal:

poetry new pysdk  # new poetry project
conda create -n pysdk python=3.9  # new (mini)conda environment

You can also name your environment as you wish, but please remember to keep it consistent. We named our environment pysdk, referring to the Viam Python SDK.

NOTE: If using (mini)conda, activate the environment by running the following command:

conda activate pysdk

Poetry environments are implicitly activated.

Before you can run the code, you need to install the “viam” module. Follow the Python SDK installation guide to properly install the package.

NOTE: If using a python environment, ensure that the package is installed in the proper environment.

pip freeze | grep viam  # generic
poetry show | grep viam  # for poetry environments
conda list | grep viam  # for (mini)conda environments

You should see viam-sdk listed near the end.

Save the code

Download the code to a directory on your computer. Feel free to choose your own location, but as an example, we’ve chosen the Desktop.

In the Python code, you must add your robot’s address and secret (payload), which are found on the Code Sample tab of the Viam app. Viam pre-populates the Code Sample tab with the robot name, address, and secret:

Remote configuration JSON

In your local copy of, paste your robot payload and address where indicated. Save the file.

Now you are ready to run the code!

Run the code

Now you should try to drive the SCUTTLE around following the color red. You can use something like a red sports ball or book cover as a target to follow.

Navigate to the folder where you saved the Python script. From that folder, run this in the terminal:


Be sure to replace ~/Desktop/ with the /path/toYour/directory/ where the Python code was saved.

python ~/Desktop/

Notes on color detection operation

Within getVisService(robot), a detector is configured with particular properties and subsequently added to the Vision Service. This particular detector is a color detector, which means the relevant parameters are detect_color (hex string), hue_tolerance_pct (float from 0 to 1), and segment_size_px (integer). Feel free to configure more detectors with different parameters! To learn about all the different detectors and parameters, check out the Vision Service documentation.

The leftOrRight() code splits the screen vertically into thirds (left, center, and right) and makes a determination about which third the object (red ball) is in. Within main(), this decides how the robot moves (as configured by the 4 given variables). Run the code as is before making changes to see how it affects the output!

Have questions, or want to meet other people working on robots? Join our Community Discord.