# 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? 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](https://docs.viam.com/reference/components/servo/) with Viam and Viam’s [Python SDK](https://python.viam.dev/). ## Requirements ### Hardware - [Raspberry Pi with microSD card](https://a.co/d/bxEdcAT), with `viam-server` installed per our [installation guide](https://docs.viam.com/set-up-a-machine/first-machine/) - microSD card reader - [Continuous rotation servo](https://a.co/d/2w0u6rK) (we used the FS90R servo) - Wheel or arm for the servo (this comes in some of the FS90R packages) - [Jumper wires](https://www.amazon.com/EDGELEC-Breadboard-Optional-Assorted-Multicolored/dp/B07GD2BWPY) - Optical mouse - corded or uncorded ### 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 - [Python3](https://www.python.org/download/releases/3.0/) - [Pip](https://pip.pypa.io/en/stable/#) - [viam-server](https://github.com/viamrobotics/rdk/tree/0c550c246739b87b4d5a9e8d96d2b6fdb3948e2b) - [Viam Python SDK](https://python.viam.dev/) - [Mousemover tutorial code](https://github.com/viam-labs/tutorial-mousemover) ## Install Viam software First, prepare your Raspberry Pi according to our [setup guide](https://docs.viam.com/reference/device-setup/rpi-setup/). Then connect to your Raspberry Pi with SSH. Add a new machine on [Viam](https://app.viam.com/). 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 Viam. Next, run this command in your Raspberry Pi terminal to install the pip package manager. Select “yes” when asked if you want to continue. ```sh 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: ```sh pip3 --version ``` The [Viam Python SDK](https://python.viam.dev/) (Software Development Kit) allows you to write programs in the Python programming language to operate machines using Viam. To get the Python SDK working on the Raspberry Pi, follow [Install the Python SDK](https://docs.viam.com/reference/sdks/python/python-venv/). ## Test the SDK with your machine On your machine’s page, select the **CONNECT** tab, then select **Python** as your language. 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**. #### Caution: Keep your API key safe We strongly recommend that you add your API key as an environment variable. Anyone with your API key can access your machine, and the computer running your machine. 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). ```sh mkdir mousefolder ``` Go into mousefolder. ```sh cd mousefolder ``` Create a file using nano with the .py which is the python file extension, (name this file whatever you want). ```sh nano anyname.py ``` Paste the code you got from the **CONNECT** tab. Press CTRL+O, then CTRL+M, then CTRL+X to save the code and exit. 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. ```sh python3 anyname.py ``` There are no errors in the resources above, so we have confirmed a good software connection between the Python SDK and your machine! ## 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 Once you have the wires connected, attach the wheel/arm to servo and turn on the Raspberry Pi. ## Configure your machine The servo is now physically connected to the Raspberry Pi, but Viam is not yet configured with the components to use it, so it’s not able to control the servo. Navigate to the **CONFIGURE** tab. ### Board component Create a [board component](https://docs.viam.com/reference/components/board/): 1. Navigate to the **CONFIGURE** tab of your machine’s page. 2. Click the **+** icon next to your machine part in the left-hand menu and select **Blocks**. 3. Search for `raspberry pi`, then select the `raspberry-pi/rpi` block 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 `raspberry-pi/rpi5` block instead. 4. Enter the name `local` for your board and click **Add to machine**. #### Tip You can name the board whatever you want, but if you change the name you must update the references to the board in the code we use later. ### Servo component Create a [servo component](https://docs.viam.com/reference/components/servo/): 1. Navigate to the **CONFIGURE** tab of your machine’s page. 2. Click the **+** icon next to your machine part in the left-hand menu and select **Blocks**. 3. Search for `rpi-servo`, then select the `raspberry-pi/rpi-servo` block. 4. Enter the name `fs90f` for your servo and click **Add to machine**. After clicking **Add to machine**, 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"`. Click the **Save** button in the upper right corner of the screen to save your config. ## Control the servo with the web UI 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 machine with code Copy the code from the [mousemover GitHub repository](https://github.com/viam-labs/tutorial-mousemover) into your nano file, save it, and run it. The code uses the Python SDK to securely connect to your machine. 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 machines, take a look at our other [tutorials](https://docs.viam.com/tutorials/). And if you didn’t like this tutorial and would like to speak to my manager, their name is You can also join us in [Viam’s Discord](https://discord.gg/viam) for any issues, comments, hardware chats, banter, and debates on if pineapple belongs on pizza or not.