How to Create a Mouse Mover Using a Servo

Have you ever been working from home and needed to step out for a moment? Maybe it was to clear your head, grab your lunch, answer the door, and you get in trouble because it showed you as offline?

Error

This tutorial will show you how to build a mouse mover using Viam, a Raspberry Pi, a servo, and an optical mouse. This machine will turn the continuous servo that’s secured inside the box, which will turn the circle under the optical mouse. This will keep your computer from falling asleep.

This project is a good place to begin if you’re new to robotics and would like to learn how to use a servo component with the Viam app and Viam’s Python SDK.

Requirements

Hardware

Tools and consumables

  • Suitable sized box (box should allow servo with wheel/arm with circle cut out on top of wheel/arm to sit flush with the top of the box)
  • Double sided tape
  • Tape to seal the box (we used black gaffers tape)
  • Box cutters
  • Marker

Software

Install Viam software

First, prepare your Raspberry Pi according to our setup guide. Then connect to your Raspberry Pi with SSH.

Add a new machine in the Viam app. On the machine’s page, follow the setup instructions to install viam-server on the computer you’re using for your project. Wait until your machine has successfully connected to the Viam app.

Next, run this command in your Raspberry Pi terminal to install the pip package manager. Select “yes” when asked if you want to continue.

sudo apt-get install pip

The command above installs the latest version of python3 and pip3 on your Raspberry Pi. To verify and get the version of the package, you can run the command:

pip3 --version

The Viam Python SDK (Software Development Kit) allows you to write programs in the Python programming language to operate robots using Viam. To get the Python SDK working on the Raspberry Pi, run the following command in your Raspberry Pi terminal:

pip install viam-sdk

Test the SDK with your robot

On the Viam app, select the CONNECT tab, then select Python as your language.

The word Language with four boxes below it with Python, Golang, Typescript (Web), and Remotes in each one. Python has a black background with white text and a checkmark, the other three have white backgrounds with black text.

Since you already installed the Python SDK, skip the first step. Copy the sample Python code under step 2.

To show your machine’s API key in the sample code, toggle Include API key.

The copied code needs to go in a Python file on the Raspberry Pi. You can do so by creating a file on the Raspberry Pi and editing the file with nano.

Inside the Raspberry Pi Terminal, run the following command to create a folder to put your files in (name this folder whatever you want).

mkdir mousefolder

Go into mousefolder.

cd mousefolder

Create a file using nano with the .py which is the python file extension, (name this file whatever you want).

nano anyname.py

Paste the code you got from the CONNECT tab in the Viam app. Press CTRL+O, then CTRL+M, then CTRL+X to save the code and exit.

Raspberry Pi terminal showing the connect code from the previous example.

Now, run the code using the below command to get the resource information that lets us know if the connection is good or if there are any errors.

python3 anyname.py

The output of the code showing a list of the resources.

There are no errors in the resources above, so we have confirmed a good software connection between the Python SDK and your Viam robot!

Connect the servo

First, turn off your Raspberry Pi. This will help prevent any accidents when connecting the hardware.

Now, follow this schematic diagram to attach jumper wires to the servo and Raspberry Pi.

  • GND on servo attached to pin 6 on Pi
  • 5V on servo attached to pin 2 on Pi
  • PWM on servo attached to pin 12 on Pi

Computer-drawn photo schematic of a Raspberry Pi connected to a FS90R servo. It shows the yellow wire coming from the servo as the PWM wire and it’s attached to pin twelve on the raspberry pi. The red wire coming from the servo is a five-volt wire and it’s attached to pin two. The black wire coming from the servo is the ground wire and it’s attached to pin eight.

Once you have the wires connected, attach the wheel/arm to servo and turn on the Raspberry Pi.

Configure your robot

The servo is now physically connected to the Raspberry Pi, but the Viam app hasn’t been told the details of which components/services it’s using yet, so it’s not able to control the servo.

Go to the Viam app, and navigate to the CONFIGURE tab.

Board component

Create a board component:

  1. Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

  2. Click the + icon next to your machine part in the left-hand menu and select Component.

  3. Select the board type, then select the viam:raspberry-pi:rpi model if you are using a Raspberry Pi 4, Raspberry Pi 3 or Raspberry Pi Zero 2 W. If you are using a Raspberry Pi 5, use the pi5 model instead.

  4. Enter the name local for your board and click Create.

Servo component

Create a servo component:

  1. Navigate to the CONFIGURE tab of your machine’s page in the Viam app.
  2. Click the + icon next to your machine part in the left-hand menu and select Component.
  3. Select the servo type, then select the viam:raspberry-pi:pi-servo model.
  4. Enter the name fs90f for your servo and click Create.

After clicking Create, you see where you can put in attributes for the servo. This is where you tell Viam which hardware pin to use to control the servo.

  • For "pin" use 12 - this is the pin you attached the PWM (Pulse Width Modulation) jumper wire to.
  • For "board" select "local".

The attribute section will look like this:

This is a screenshot of the Viam app on the Config page. This shows the options that populate when you create a servo with the pi Model. It shows attributes. 'Pin' is filled in with '12' and 'Board' is filled in with 'local'. Pin and board are required fields.

Click the Save button in the upper right corner of the screen to save your config.

Control the servo in the Viam app

If everything went well, the servo started to move.

Navigate to the CONTROL tab and press the STOP button on the servo card (matching what you named the servo) to stop the servo.

Click on the top of the servo card to open the servo controls.

Angle will determine what speed your servo goes and in what direction. 90 degrees is the midway point and is the stopping point. Try changing the angle to a few different settings.

Assemble the mouse mover

Now that you’ve confirmed that the software and hardware are connected and working correctly with Viam, let’s assemble the mouse mover.

Position the Raspberry Pi and servo in the box

Put the Raspberry Pi and servo in the box and mark out where each should be, then take the Raspberry Pi out. Now, make sure the servo is close to level with the top (leaving a tiny bit of room for the circle cut out and tape). Tape the servo in place.

Cut a holes in the box for the Pi

Place the Raspberry Pi back in the box and mark where the USB-C plug is so that you know where it is on the outside of the box. Take out the Raspberry Pi. Grab a box cutter and cut out a power hole.

Since the Raspberry Pi will be in a box and won’t have much ventilation, cutting a courtesy hole to allow for it to vent is the least we could do to keep it from frying.

Be sure to tape the jumper wires out of the way of the servo.

Cut the mouse mover circle out of the box and tape to servo

The technique we used to find the center of the circle was to mark the screw on the servo. Gently push on the box to get a mark on the inside of the box, then create a cut we could see from the other side.

Tape the box shut, add “baby gates”, and plug in the Raspberry Pi

When taping the box shut be sure the servo with the circle cut out sits fairly flush to the top of the box. Add “baby gates” or rails to keep the mouse from wandering off if it catches some friction.

Control your robot with code

Copy the code from the mousemover GitHub repository into your nano file, save it, and run it.

The code uses the Python SDK to securely connect to your robot through Viam app. Then, it enters a for loop in which position tells us the servo to move to positions (angles) between 80 and 93 degrees as specified in the sequence list. The code uses pause_time to wait for a random amount of time between 5 and 20 seconds to stay at that position.

You can adjust the range (or speed/direction) by changing the two numbers in the position statement. (Currently set at 80 and 93). You can also change the time that the servo is allowed to spin in any direction by changing the two numbers in the pause_time statement. Experiment and have fun.

Next steps

If you want to build more robots, take a look at our other tutorials. And if you didn’t like this tutorial and would like to speak to my manager, their name is Fuzzy box meant to censor text. (Update: apparently that’s a big no no.)

You can also join us in Viam’s Discord for any issues, comments, hardware chats, banter, and debates on if pineapple belongs on pizza or not.