Skip to main content

ROSbot XL - quick start

ROSbot XL is a universal, ROS 2-native autonomous mobile robot platform designed for R&D, rapid prototyping and custom robot development for indoor use cases.



How to get it?

If you don't have ROSbot XL yet, you can get it from the online store.

Looking for a manual?

This is a quick start guide. If you need a manual instead, you can find it here

OS version

To use the utility scripts (eg. ~/flash_firmware.sh, ~/ros_driver_start.sh) make sure you have at least the *-2023-07-18 version of the ROS 2 Humble Husarion OS installed.

If you have the older version, please update it or use commands from the [Docker way] tab.

I have the *-2023-07-18 (or higher) version of the Husarion OS.

Unboxing​

What's in the box:

  • ROSbot XL
  • a Wi-Fi 2.4GHz / 5GHz antenna
  • a USB-C charger
  • an Ethernet cable
  • a set of regular (pneumatic) wheels
  • two Allen keys: 2.5mm and 4mm
  • a camera stand for mounting external cameras on the ROSbot.

Connecting the battery​

caution

The robot is shipped with the battery disconnected.

You need to connect the battery before the first use:

  • Use a 2.5mm Allen key to unscrew the battery cover located at the bottom of the ROSbot XL.
  • Once opened, you will see a 4-pin white connector (plug) and a socket. Insert the plug into the socket.
  • Install the battery cover back to its place.

The robot is now ready for the next steps.

Mounting external components​

If you want to mount an external camera, LIDAR, or any other equipment on your ROSbot, first you need to run the cable through the robot's cover. The video below demonstrates how to do that.


Then, attach the equipment to the cover and plug it into the appropriate connector inside the robot.

Installing the System Image for ROSbot​

ROSbot XL comes with 3 SBC options, setup instructions vary slightly between them, so please select your version below.

info

ROSbot XL comes with a pre-installed ROS Humble OS image. If you have just received your brand new ROSbot XL, you can skip this step.

In some situations, you may need to restore the ROSbot system to its default settings:

  • If the system is accidentally damaged,
  • To update the OS to the latest version with supported documentation,
  • To erase all user changes and revert to factory settings.

For instructions on how to reinstall the operating system, please refer to the OS reinstallation guide.

Accessing ROSbot's Linux terminal​

To perform the initial network configuration, you need to access ROSbot's Linux terminal. There are two options:

Option 1: Using display, mouse and keyboard​

To use this option, you will need an external monitor, USB and HDMI cables, mouse and keyboard.

ROSbot is basically a computer running Ubuntu, so let's open it like a standard PC.

  1. Plug in a display with HDMI, mouse and keyboard into the USB port on the rear panel of ROSbot.
  2. Turn on the robot and wait until it boots.
  3. Open the Application Launcher (Husarion Logo in the top-left corner) > System Tools > Terminator app.

using etcher for flashing ROS system image

info

ROSbot's graphical desktop environment requires about 2 minutes to start during the first boot. Subsequent boots require only about 1 minute after power on.

Option 2: Using an Ethernet port​

  1. Turn on the robot and wait until it boots.
  2. Plug one end of the Ethernet cable into your computer and the other end into the robot's Ethernet port.
If you don't have at least the *-2023-07-18 version of the ROS 2 Humble Husarion OS installed, first complete this step.

Set a static IP address on your computer for its Ethernet card in a 192.168.77.0/24 subnet, eg:

  • IPv4: 192.168.77.27
  • mask: 255.255.255.0

  1. To connect to the ROSbot via SSH, type in your terminal:

    user@mylaptop:/home/user$
    ssh husarion@192.168.77.2

    The default password for the user husarion is also husarion.

Connecting ROSbot XL to your Wi-Fi network​

Netplan

ROSbot XL uses netplan instead of a graphical Wi-Fi manager. It allows you to have all physical network interfaces configured from a single text file.

To find available Wi-Fi networks, use the following Linux command:

husarion@rosbotxl:/home/husarion$
sudo nmcli dev wifi rescan
nmcli dev wifi

To connect your ROSbot to a Wi-Fi network, edit /etc/netplan/01-network-manager-all.yaml file, e.g. with nano:

husarion@rosbotxl:/home/husarion$
sudo nano /etc/netplan/01-network-manager-all.yaml

And modify lines 22-23 by replacing "PLACE_YOUR_WIFI_SSID_HERE" with your SSID (Wi-Fi network name) and "PLACE_YOUR_WIFI_PASSWORD_HERE" with your Wi-Fi password:

See the Netplan configuration file
/etc/netplan/01-network-manager-all.yaml
network:
  version: 2
  renderer: NetworkManager

  ethernets:

    all-eths:
      match:
        name: eth*
      dhcp4: no
      dhcp6: no
      optional: true
      addresses:
        - 192.168.77.2/24

  wifis:
    # ========================================
    # standard Wi-Fi config (client)
    # ========================================
    wlan0:
      dhcp4: true
      dhcp6: true
      optional: true
      access-points:
        "PLACE_YOUR_WIFI_SSID_HERE":
          password: "PLACE_YOUR_WIFI_PASSWORD_HERE"

    # ========================================
    # access point Wi-Fi config
    # repace "channel" with the number permitted in your country
    # https://en.wikipedia.org/wiki/List_of_WLAN_channels
    # ========================================
    # wlan0:
    #   dhcp4: yes
    #   addresses:
    #     - 192.168.78.1/24
    #   access-points:
    #     "rosbotap":
    #       band: "5GHz"
    #       channel: "149"
    #       mode: "ap"
    #       password: "husarion"

then save the file (with ctrl+o if using nano) and apply the new network setup:

husarion@rosbotxl:/home/husarion$
sudo netplan -d apply

You can check to which Wi-Fi network your ROSbot is connected by using this command:

husarion@rosbotxl:/home/husarion$
sudo iwgetid

To find your IP address (for the wlan0 network interface) type:

husarion@rosbotxl:/home/husarion$
ip -4 addr show wlan0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'

Save this IP address for the next step.

Complex Wi-Fi setups

If your Wi-Fi network setup is more complex (eg. if you want to connect to Eduroam based Wi-Fi that is popular in many universities), visit netplan configuration examples and netplan documentation.

Remote access​

OPTION 1: in a LAN network​

While ROSbot is connected to a Wi-Fi network, you can access it by using its IPv4 address by SSH:

user@mylaptop:/home/user$
ssh husarion@ROSBOT_IP

OPTION 2: over the Internet (VPN)​

If LAN access is not enough you can access the ROSbot over the Internet using Husarnet. You can find the full guide on how to do it here.

Launching the ROS driver​

At this stage, your ROSbot should be up and running, with a remote (LAN or VPN) connection from your laptop.

Now let's start the ROS Driver that brings up the rosbot_xl_ros package and the Micro-ROS Agent (for interfacing with the firmware running on the STM32 Microcontroller).

ROS 2 API

You will find a ROS 2 API for the ROSbot XL here.

Flashing the firmware​

Access your ROSbot's terminal and run:

husarion@rosbotxl:/home/husarion$
~/flash_firmware.sh

Starting the Driver​

To launch basic ROSbot XL ROS 2 nodes, paste the following command in the ROSbot's terminal:

husarion@rosbotxl:/home/husarion$
~/ros_driver_start.sh

At this point, ROS nodes from the containers are available at the level of the host operating system.

Check available ROS topics:

husarion@rosbotxl:/home/husarion$
ros2 topic list

ROS2 topic list

info

If you don't have ROS 2 Humble natively installed on your OS (e.g. if you're using Nvidia Jetson Nano), access the rosbot-xl container:

husarion@rosbotxl:/home/husarion$
docker exec -it rosbot-xl bash

Now you can run the following command to check the topics:

root@a837c86387c2:/ros2_ws#
ros2 topic list

Manual ROSbot driving with teleop_twist_keyboard​

Launch a teleop_twist_keyboard ROS node for manual ROSbot control:

husarion@rosbotxl:/home/husarion$
ros2 run teleop_twist_keyboard teleop_twist_keyboard

After running the command, you will see the usage instruction:

list of ROS2 topics at ROSbot XL

Reference projects​

Now you know how to run core ROSbot XL ROS nodes.

Running ROS natively is fine for relatively small projects. For more complex ones, a full dockerized setup is a better approach.

danger

If you're planning to try the next demos, make sure to stop the basic setup first by running the following command:

husarion@rosbotxl:/home/husarion$
~/ros_driver_stop.sh

Find available projects below:

linkdescription
rosbot-xl-gamepadControl the robot manually using a Logitech F710 gamepad
rosbot-xl-autonomyAutonomous mapping & navigation demo for ROSbot XL. Using navigation2 and slam_toolbox
rosbot-xl-manipulationUsing ROSbot XL with OpenMANIPULATOR-X. Read more about this project in the dedicated tutorial (including Gazebo simulation)
rosbot-xl-telepresenceControlling ROSbot XL over the Internet with a live video feed

Here is an example of a map generated with the rosbot-xl-mapping project, which can be used in the rosbot-xl-navigation.

map example

ROS 2 Tutorials​

ROS 2 (Robot Operating System 2) provides libraries and tools to help software developers create robotic applications. We've put together a series of ROS 2 Tutorials dedicated for this platform that serve as a practical introduction to ROS 2. You can run them on any of our ROSbots, either on a physical robot or in the simulation environment. These step-by-step guides are tailored to accommodate both beginners embarking on their ROS 2 journey and experienced users looking to deepen their understanding of robot navigation.

info

ROS 2 Tutorials are still in the process of development, with new tutorials coming soon.