The TurtleBot 4 Lite is a powerful ROS2-based mobile robot platform that's perfect for learning robotics, research, and development. By integrating Viam with your TurtleBot, you can unlock powerful remote control capabilities, cloud-based data management, and seamless integration with modern robotics workflows.

Viam integration w/ ROS2 overview

In this codelab, we'll transform your TurtleBot 4 Lite into a cloud-connected robot that you can control from anywhere and automatically capture sensor data for analysis and machine learning applications.

TurtleBot 4 Lite with Viam integration

What You'll Build

Prerequisites

What You'll Learn

What You'll Need

Watch the Video

See a demonstration of controlling the ROS2 Turtlebot using Viam.

Before integrating Viam with your TurtleBot, we need to configure the ROS2 environment and ensure proper network connectivity.

Connect to your TurtleBot

  1. Power on your TurtleBot 4 Lite and wait for it to fully boot up.
  2. Connect to your TurtleBot via SSH. Replace <TURTLEBOT_IP> with your robot's IP address: 
    ssh ubuntu@<TURTLEBOT_IP>

Update system packages

  1. Update the package lists and upgrade existing packages: 
    sudo apt update
sudo apt upgrade -y
  2. Install Python virtual environment support (required for the Viam module): 
    sudo apt install -y python3-venv
  3. Install the ROS2 cv_bridge package for camera integration: 
    # For ROS2 Humble
sudo apt install -y ros-humble-cv-bridge

# For ROS2 Jazzy (if applicable)
sudo apt install -y ros-jazzy-cv-bridge

Configure FastDDS for UDP-only mode

Viam requires UDP-only communication, so we need to disable shared memory.

  1. Create the FastDDS configuration file: 
    sudo nano /etc/turtlebot4/fastdds_rpi.xml
  2. Add the following XML configuration: 
    <?xml version="1.0" encoding="UTF-8" ?>
<dds>
    <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" >
        <transport_descriptors>
            <transport_descriptor>
                <transport_id>CustomUdpTransport</transport_id>
                <type>UDPv4</type>
            </transport_descriptor>
        </transport_descriptors>

        <participant profile_name="turtlebot4_default_profile" is_default_profile="true">
            <rtps>
                <userTransports>
                    <transport_id>CustomUdpTransport</transport_id>
                </userTransports>
                <useBuiltinTransports>false</useBuiltinTransports>
            </rtps>
        </participant>
    </profiles>
</dds>
  3. Save and exit the file (Ctrl+X, then Y, then Enter).

Configure the ROS2 namespace

To avoid conflicts with existing ROS2 nodes, we'll set up a dedicated namespace for Viam.

  1. Edit the TurtleBot setup file to add our namespace and point to the FastDDS configuration: 
    sudo nano /etc/turtlebot4/setup.bash
  2. Add the following lines at the end of the file: 
    export ROBOT_NAMESPACE=/viamrostwo
export FASTRTPS_DEFAULT_PROFILES_FILE=/etc/turtlebot4/fastdds_rpi.xml
  3. Save and exit the file (Ctrl + X, then Y, then Enter).

Verify ROS2 functionality

  1. Source the ROS2 environment: 
    source /opt/ros/humble/setup.bash  # or /opt/ros/jazzy/setup.bash
source /etc/turtlebot4/setup.bash
  2. Check that ROS2 topics are available: 
    ros2 topic list
    You should see topics like /viamrostwo/cmd_vel, /viamrostwo/scan, etc.

Your TurtleBot is now ready for Viam integration!

Create your machine in Viam

  1. In the Viam app under the LOCATIONS tab, create a machine by typing in a name like "ros-two" and clicking Add machine. add machine
  2. Click View setup instructions.
  3. Select the Linux / Aarch64 platform for the Raspberry Pi, and leave your installation method as viam-agent. select platform
  4. Use the viam-agent to download and install viam-server on your TurtleBot. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your TurtleBot. installation agent
  5. The setup page will indicate when the machine is successfully connected. successful toast

Now we'll configure the individual components that make up your TurtleBot system.

Configure the base component

The base component will allow you to control the TurtleBot's movement.

  1. Click the + icon in the left-hand menu and select Component or service. select component or service
  2. Select base, then search for "ros" and select the viam-soleng:ros2:base model. select ros base
  3. When prompted for the viam-soleng:viam-ros2-integration module, click Add module. add ros2 integration module
  4. Name it rosbase and click Create. create rosbase
  5. In the Attributes section, configure: 
    {
  "ros_topic": "/viamrostwo/cmd_vel",
  "publish_rate": "0.1"
}
    configure base component
  6. Click on the JSON tab in the left sidebar above your machine name to display the full configuration JSON for your machine.
    switch to JSON config
  7. Configure the viam-soleng:viam-ros2-integration module environment variables by adding an env field with the relevant config, which should look like the following: 
    {
  "type": "registry",
  "name": "viam-soleng_viam-ros2-integration",
  "module_id": "viam-soleng:viam-ros2-integration",
  "version": "latest",
  "env": {
    "ROS_ENV": "/opt/ros/humble/setup.bash",
    "OVERLAYS": "/etc/turtlebot4/setup.bash",
    "VIAM_ROS_NAMESPACE": "/viamrostwo",
    "FASTRTPS_DEFAULT_PROFILES_FILE": "/etc/turtlebot4/fastdds_rpi.xml"
  }
}
  8. Click Save in the top right to save your configuration.

Configure the camera component

  1. Click the + icon in the left-hand menu and select Component or service.
  2. Select camera, then search for and select the viam-soleng:ros2:camera model.
  3. Name it roscamera and click Create.
  4. In the Attributes section, configure: 
    {
  "ros_topic": "/viamrostwo/oakd/rgb/preview/image_raw",
  "encoding": "rgb8"
}
    configure camera component

Configure the battery status sensor

  1. Click the + icon in the left-hand menu and select Component or service.
  2. Select sensor, then search for and select the viam-soleng:ros2:sensor model.
  3. Name it battery_state and click Create.
  4. In the Attributes section, configure: 
    {
  "ros_topic": "/viamrostwo/battery_state",
  "ros_msg_package": "sensor_msgs.msg",
  "ros_msg_type": "BatteryState"
}
    configure battery sensor

Configure the dock status sensor

  1. Click the + icon in the left-hand menu and select Component or service.
  2. Select sensor, then search for and select the viam-soleng:ros2:sensor model.
  3. Name it dock_status and click Create.
  4. In the Attributes section, configure: 
    {
  "ros_topic": "/viamrostwo/dock_status",
  "ros_msg_package": "irobot_create_msgs.msg",
  "ros_msg_type": "DockStatus"
}
    configure dock sensor

Configure the wheel status sensor

  1. Click the + icon in the left-hand menu and select Component or service.
  2. Select sensor, then search for and select the viam-soleng:ros2:sensor model.
  3. Name it wheel_status and click Create.
  4. In the Attributes section, configure: 
    {
  "ros_topic": "/viamrostwo/wheel_status",
  "ros_msg_package": "irobot_create_msgs.msg",
  "ros_msg_type": "WheelStatus"
}
    configure wheel sensor

Click Save to apply all your component configurations.

Your Viam machine is now configured with ROS2 integration capabilities!

Now we'll set up automated data capture for your robot's sensors and camera, with automatic sync to the Viam cloud.

Add the data management service

  1. In the Viam app, click the + icon in the left-hand menu and select Component or service, and then data management.
  2. Create a new Data Management service called datacapture.
  3. Notice adding this service adds the data manager service called datacapture. It will default to the "Capturing" and "Syncing" toggles as enabled.
  4. In the "Additional paths" field of the Cloud sync section, type /opt/rosbags and hit the Enter key to also sync your rosbag files. view default configuration for data manager
  5. Click Save in the top right. This may take a moment to apply your configuration changes.

Configure camera data capture

  1. Navigate to your roscamera component.
  2. In the Data capture section, click Add method.
  3. Configure the capture settings:
    • Method: GetImage
    • Frequency (hz): 0.1 (capture one image every 10 seconds)
    • MIME type: image/jpegconfigure camera capture

Configure sensor data capture

  1. Navigate to your battery_state component.
  2. In the Data capture section, click Add method.
  3. Configure:
    • Method: Readings
    • Frequency (hz): 0.5 (capture every 30 seconds) configure battery capture
  4. Repeat the same process for dock_status and wheel_status sensors with the same frequency.

Verify data capture configuration

  1. Click Save to apply all configurations.
  2. Navigate to the CONTROL tab to verify all components are working.
  3. Check that your camera shows a live feed and sensors display current readings.

Your TurtleBot will now automatically capture and sync data to the Viam cloud!

The ROS2 logger service will stream your robot's debug logs directly to Viam for real-time monitoring.

Add the ROS2 logger service

  1. Click the + icon in the left-hand menu and select Component or Service.
  2. Search for ros2_logger and select the viam-soleng:ros2:logger model.
  3. Name it ros2_logger and click Create.
  4. In the Attributes section, configure: 
    {
  "ros_topic": "/rosout",
  "log_level": "debug"
}
    configure ros logger

Test the logger service

  1. Click Save to apply the configuration.
  2. Navigate to the LOGS tab in the Viam app.
  3. You should start seeing ROS2 log messages appearing in the Viam logs interface. view ros logs

The logger service will now stream all ROS2 system messages with "debug" level and above directly to Viam for easy monitoring and debugging.

Now comes the exciting part - controlling your TurtleBot from anywhere using the Viam web interface!

Test basic movement

  1. Navigate to the CONTROL tab in the Viam app.
  2. Find your rosbase component card.
  3. Use the Quick move buttons to test basic movements:
    • Click Forward to move the robot forward
    • Click Backward to move the robot backward
    • Click Left and Right to turn the robot base control interface

Enable keyboard control

  1. In the base component control card, toggle Keyboard control to ON.
  2. Now you can use your computer's keyboard to drive the TurtleBot:
    • W or ↑: Move forward
    • S or ↓: Move backward
    • A or ←: Turn left
    • D or →: Turn right base keyboard control interface

Test advanced movements

  1. Try the Move straight function:
    • Set distance (in mm) and velocity
    • Click Execute to move a precise distance base actions

Monitor live camera feed

  1. Scroll to your roscamera component.
  2. Set the refresh dropdown to "Live" to see the live camera feed from your TurtleBot. camera live feed
  3. You can now see what your robot sees while driving it remotely!

Your TurtleBot is now fully controllable from Viam.

Let's explore the data your TurtleBot has been automatically capturing and syncing to the cloud.

Access the data tab

  1. In the Viam app, click on the document icon in the top-right of the machine configuration page to view captured data.
  2. You'll see Images section by default to view photos captured by your TurtleBot's camera.
  3. You can:
    • View individual images with timestamps
    • Filter by date range
    • Search by tags
    • Annotate for machine learning training captured images view

Review sensor data

  1. Click on the Sensors section to view captured sensor readings.
  2. You'll see data from:
    • Battery status (charge level, voltage, temperature)
    • Dock status (whether robot is docked)
    • Wheel status (motor health and performance)
  3. Data is displayed in a JSON format and can be queried using SQL or MQL by clicking on the "Query" in the top-right of your machine card. sensor data

Your TurtleBot's data is now safely stored in the cloud and ready for analysis!

Congratulations! 🎉 You've successfully transformed your TurtleBot 4 Lite into a cloud-connected, remotely controllable robot with automated data capture capabilities.

The combination of TurtleBot's robust hardware platform, ROS2's flexible software ecosystem, and Viam's cloud-native robotics tools provides an incredibly powerful foundation for your robotics projects.

What You've Accomplished

Expanding Your Robot's Capabilities

Now that you have the foundation in place, consider these exciting next steps:

Computer Vision & AI

Advanced Sensors

Automation & Scheduling

Fleet Management

Real-World Applications

Your enhanced TurtleBot setup opens doors to numerous practical applications:

Resources for Continued Learning