Control a Yahboom DOFBOT arm with Viam

What You'll Build

A Viam-powered Yahboom DOFBOT arm. Get started quickly with this codelab!

GIF of testing arm joint movement

Prerequisites

An assembled Yahboom Dofbot arm with a Raspberry Pi (you won't need the Yahboom mobile app!)
A microSD card to use with your Pi

What You'll Need

What You'll Learn

How to configure a Yahboom Dofbot arm in Viam
How to control the Yahboom Dofbot arm through Viam

Watch the video

Coming soon!

The Raspberry Pi boots from a microSD card. You need to install Raspberry Pi OS on a microSD card that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.

Install Raspberry Pi OS

Connect the microSD card to your computer.
Launch the Raspberry Pi Imager.
Click CHOOSE DEVICE. Select your Raspberry Pi model.
Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
Click CHOOSE STORAGE. From the list of devices, select the microSD card you intend to use in your Raspberry Pi.
Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
Check Set hostname and enter the name you would like to access the Pi by in that field, for example, echo.
Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). Also specify a password.
Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Also change the section Wireless LAN country to where your router is currently being operated. This will allow your Pi to connect to your Wi-Fi so that you can run viam-server wirelessly.
Check Set locale settings and set your time zone and keyboard layout.
Be sure that you remember the hostname, username, and password you set, as you will need this when you SSH into your Pi.
Select the SERVICES tab, check Enable SSH, and select Use password authentication.
Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on the microSD card. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the microSD card.
Remove the microSD card from your computer when the installation is complete.

Connect with SSH

Place the microSD card into your Raspberry Pi and boot the Pi by turning on the dofbot arm. A red LED will turn on to indicate that the Pi is connected to power.
Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the username and hostname you configured when you set up your Pi.
```
ssh <USERNAME>@<HOSTNAME>.local

# for example, my command would look like this:
ssh atacke@echo.local
```
If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt.
Update your Raspberry Pi to ensure all the latest packages are installed
```
sudo apt update
sudo apt upgrade
```

Enable communication protocols

Launch the Pi configuration tool by running the following command
```
sudo raspi-config
```
Use your keyboard to select "Interface Options", and press return.
Enable the relevant protocols to allow communication with the dofbot's expansion board. One of those is I2C (Inter-Integrated Circuit), a two-wire serial communication protocol used for short-distance communication between electronic devices. Enable I2C.
Confirm the options to enable the I2C interface. And reboot the Pi when you're finished.
```
sudo reboot
```

In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.
Once your machine is created, you are brought to your machine overview page. Click View setup instructions.
To install viam-server on your device, select Linux/Aarch64. Leave the default installation method of viam-agent:
Follow the instructions that are shown for your platform. If you are following along with a Pi, you'll copy the command shown and run it in your SSH session on your Pi.
The setup page will indicate when the machine is successfully connected.

With a machine configured, we now need to configure the arm's components next!

This approach will walk you through the JSON configuration of the dofbot components you'll need to configure. You'll primarily work within the JSON editor of your machine.

Configure your machine via JSON

In the Viam app, find the CONFIGURE tab.
Click on the {} JSON tab to open the machine's JSON configuration page.

Copy the following code and paste it into the JSON editor (don't worry, we'll go through each of the components and explain what's happening). Be sure to click Save in the top right to apply your changes.

{
  "components": [
    {
      "name": "dofbot-camera",
      "api": "rdk:component:camera",
      "model": "rdk:builtin:ffmpeg",
      "attributes": {
        "video_path": "/dev/video0"
      }
    },
    {
      "name": "dofbot-arm",
      "api": "rdk:component:arm",
      "model": "hipsterbrown:dofbot:arm",
      "attributes": {},
      "frame": {
        "parent": "world",
        "translation": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    },
    {
      "name": "dofbot-gripper",
      "api": "rdk:component:gripper",
      "model": "hipsterbrown:dofbot:gripper",
      "attributes": {},
      "frame": {
        "parent": "dofbot-arm",
        "translation": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "hipsterbrown_dofbot",
      "module_id": "hipsterbrown:dofbot",
      "version": "latest"
    }
  ]
}

Let's step through what we configured. You'll notice that within the components array, there are three objects: one for the camera (dofbot-camera), one for the arm (dofbot-arm), and one for the gripper (dofbot-gripper):

{
  "components": [
    {
      "name": "dofbot-camera",
      "api": "rdk:component:camera",
      "model": "rdk:builtin:ffmpeg",
      "attributes": {
        "video_path": "/dev/video0"
      }
    },
    {
      "name": "dofbot-arm",
      "api": "rdk:component:arm",
      "model": "hipsterbrown:dofbot:arm",
      "attributes": {},
      "frame": {
        "parent": "world",
        "translation": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    },
    {
      "name": "dofbot-gripper",
      "api": "rdk:component:gripper",
      "model": "hipsterbrown:dofbot:gripper",
      "attributes": {},
      "frame": {
        "parent": "dofbot-arm",
        "translation": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    }
  ],

You'll see specific configuration options for each component. For example, the camera component uses the rdk:builtin:ffmpeg model, rdk:component:camera api, and has a video_path attribute that points to the default location for cameras on Raspberry Pis.
```
    {
      "name": "dofbot-camera",
      "api": "rdk:component:camera",
      "model": "rdk:builtin:ffmpeg",
      "attributes": {
        "video_path": "/dev/video0"
      }
    },
```

For the arm component, you'll see it's respective api rdk:component:arm and model hipsterbrown:dofbot:arm as well as a frame attribute. This represents a coordinate system that describes the position and orientation of the arm within the machine's spatial environment. For now, this is a single, default frame added to the arm.

  {
    "name": "dofbot-arm",
    "api": "rdk:component:arm",
    "model": "hipsterbrown:dofbot:arm",
    "attributes": {},
    "frame": {
      "parent": "world",
      "translation": {
        "x": 0,
        "y": 0,
        "z": 0
      },
      "orientation": {
        "type": "ov_degrees",
        "value": {
          "x": 0,
          "y": 0,
          "z": 1,
          "th": 0
        }
      }
    }
  }

For the gripper component, you'll see a similar configuration to the arm. One difference is within the frame attribute for the gripper: it's parent is now the arm, rather than the world.

  {
    "name": "dofbot-gripper",
    "api": "rdk:component:gripper",
    "model": "hipsterbrown:dofbot:gripper",
    "attributes": {},
    "frame": {
      "parent": "dofbot-arm",
      "translation": {
        "x": 0,
        "y": 0,
        "z": 0
      },
      "orientation": {
        "type": "ov_degrees",
        "value": {
          "x": 0,
          "y": 0,
          "z": 1,
          "th": 0
        }
      }
    }
  }

Lastly, you'll see a module array. This will list any module from the Viam Registry or custom module you are running on your machine. You'll notice that you can set a version of the module to use as well. For now, we have a single module, the hipsterbrown_dofbot module which allows us to seamlessly integrate with the dofbot arm in Viam:
```
 "modules": [
    {
      "type": "registry",
      "name": "hipsterbrown_dofbot",
      "module_id": "hipsterbrown:dofbot",
      "version": "latest"
    }
  ]
```
Troubleshooting: If you receive the following error error while loading shared libraries: libnlopt.so.0: cannot open shared object file: No such file or directory, you may have to manually install the missing package on your Pi. To do so, you can run sudo su to assume root user control, then sudo apt-get install libnlopt0 to install the missing package via your SSH session on your Pi. Alternatively, you can connect a monitor and keyboard to your Pi, switch to your Pi's OS, and run the same commands on a terminal in the Pi's OS. Once you've finished this, be sure to reload your machine's page.

If your camera feed is not showing or you have errors, your video path might be different. Refer to the discovery service steps to capture the exact video path of your dofbot's camera.

Great, you've configured your machine via JSON! Skip ahead to the Test your arm step.

This step accomplishes the same tasks as the last step, but in a beginner-friendly, visual manner. If you've already completed the previous step Configure your dofbot (JSON-approach), please skip ahead to Test your arm! Otherwise, you will duplicate components in your machine.

Configure your dofbot's camera

In the Viam app, find the CONFIGURE tab.
Click the + icon in the left-hand menu and select Component or service.
Select camera, and find the ffmpeg module.
Change the name to something descriptive, like dofbot-camera, then click Create. This adds the module for working with the default camera that comes with the Yahboom Dofbot.
Notice adding this module adds the camera hardware component called dofbot-camera. You'll see a collapsible card on the right, where you can configure the camera component, and the corresponding dofbot-camera part listed in the left sidebar.
To configure the camera component, the video_path of the intended device needs to be set. You can quickly find which devices are connected to your machine by adding a discovery service. Click Add webcam discovery service that appears in the prompt.
Notice that this adds the discovery-1 service and find-webcams module to your machine in the left sidebar. Corresponding cards to these items also appear on the right. (If you don't see the prompt in the previous step, you can always manually add the find-webcams module to your machine by searching for it through the + icon, selecting Component or service, then searching for find-webcams. Don't forget to click Save)
Click Save in the top right to save and apply your configuration changes.
Expand the TEST panel of the discovery-1 card. Here, you'll find attributes of all discoverable cameras connected to your machine. Find the video_path of the device you'd like to use as your webcam, then copy the value. For example, I'll use the detected camera from the dofbot, so I'll copy /dev/video0.
Paste the copied video_path value into your camera component's video_path input, which is in the Attributes section:
Click Save in the top right once more to save and apply your configuration changes.

Great, your machine now has eyes! Let's add the arm next.

Configure your dofbot's arm

Click the + icon in the left-hand menu and select Component or service.
Search for the dofbot :arm module and select it.
A helpful card about the module is shown. Information such as what the module does, its usage, and supported platforms are all available. Click Add module.
Change the name to something descriptive, like dofbot-arm, then click Create. This adds the module for working with the Dofbot's arm, particularly its joints.
Notice adding this module adds the arm hardware component called dofbot-arm. You'll see a collapsible card on the right, where you can configure the arm component, see any errors originating from the component, and test the component directly, and the corresponding dofbot-arm part listed in the left sidebar.
To give the arm a reference to its position and orientation within the machine's spatial environment, we'll need to add a frame. Within the Configure panel within the arm component, click Add Frame.
Notice that this adds a default frame with some default values.
Click Save in the top right to save and apply your configuration changes.

We now have a connection to the arm (and its joints). Last thing to add is the gripper.

Configure your dofbot's gripper

Click the + icon in the left-hand menu and select Component or service.
Search for the dofbot :gripper module and select it.
Change the name to something descriptive, like dofbot-gripper, then click Create. This adds the module for working with the Dofbot's gripper, particularly its joints.
Notice adding this module adds the gripper hardware component called dofbot-gripper. You'll see a collapsible card on the right, where you can configure the gripper component, see any errors originating from the component, and test the component directly, and the corresponding dofbot-gripper part listed in the left sidebar.
To give the gripper a reference to its position and orientation within the machine's spatial environment, we'll need to add a frame. In th eConfigure panel (within the gripper component), click Add Frame.
Notice that this adds a default frame with some default values. For the parent key, change the value to the name of your arm, so dofbot-arm:
Click Save in the top right to save and apply your configuration changes.

Now that all of your dofbot arm's components are configured in Viam, it's time to test them out.

Click the CONTROL tab. If properly configured, you'll find testing panels for your dofbot's arm, camera, and gripper. You should see a set of Joint Position Movement panels for the arm, a live camera feed for the dofbot's camera, and an Open/Close testing panel for the gripper.

Test your dofbot camera

Expand the dofbot camera's TEST panel. You should see a live feed from your dofbot camera. You can change the rate of refresh for your camera and test the feed. You can also enable a picture-in-picture window by clicking Toggle picture-in-picture:
If your camera feed is not showing or you have errors, your video path might be different. Refer to the discovery service steps to capture the exact video path of your dofbot's camera. Also check the components error logs and the machine level logs for further information.

Test your dofbot arm

Expand your dofbot arm's TEST panel. Here, you can test the movement of your arm's joints in different ways.
To test the movement of specific joints, you can use the MoveToJointPositions panel. For example, to move joint 0 (the lowest on the arm), change the angle for joint 0's input, the press Execute. To test the top-most joint (in our case, where the gripper is mounted), change the angle for joint 4, then press Execute:
Try also testing the movement to specific positions using the MoveToPosition panel. For example, to move the arm forward and backward (relative to its orientation in the world and known coordinate system), change the Y input value, then press Execute. To move the arm up, change the Z input value to a higher number. To move it back down, change the Z input value to a lower number. To test the rotation of the wrist, try changing the θ's input value:

Test your dofbot gripper

Expand your dofbot gripper's TEST panel. Here, you can test opening and closing the gripper.
Assuming the gripper is in the default open state, test the Grab action by selecting the Grab button. To test the open action, select the Open button:

Congratulations! You now have a working Yahboom Dofbot arm connected to Viam.

Congratulations! You've just connected your Yahboom DOFBOT arm to Viam and can work with it through the platform. This foundational step allows you to remotely access and manage the arm, extend its functionality with some of Viam's SDKs, or extend its functionality with modules from the Viam Registry. Do let me know if you've built this!

What You Learned

How to configure a Yahboom Dofbot arm in Viam
How to control the Yahboom Dofbot arm through Viam

Extend your Viam-powered Yahboom DOFBOT arm

Right now, you have a Yahboom DOFBOT arm that can take advantage of Viam's capabilities and can be controlled remotely. Why not:

Create a custom CV model to detect objects and a custom module to sort them.
Build your own arcade claw game!
Add AI tracking support to your arm's webcam and the arm itself.