ROSbot XL - quick start
ROSbot XL is a universal, ROS 2-native autonomous mobile robot platform dedicated for R&D, rapid prototyping and custom robot development for indoor use cases.
This is a quick start guide. Would you need a manual instead?
If you don't have one, you can get it here.
Unboxing
What's in the box:
- ROSbot XL
- Wi-Fi 2.4GHz / 5GHz antenna
- USB-C charger
- Ethernet cable
- a set of regular (pneumatic) wheels
- Allen keys 2.5mm and 4mm
Additionally, to launch a robot for the first time you will need:
- USB-HDMI cable, mouse and keyboard
Connecting the battery
The robot is shipped with the battery disconnected. You need to connect it before the first use:
- Unscrew the battery cover using 2.5mm Allen key. The battery cover is located at the bottom of ROSbot XL.
- After opening you will see the 4-pin, white connector (plug) and the socket. Insert the plug into the socket.
- Install the battery cover back to its place.
The robot is now ready for the next steps.
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.
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
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.
In case of Nvidia Jetson Nano, it is necessary to install and customize the system image to work with ROSbot XL.
1. Write Image to the microSD Card
First you will need to install the official Jetson Nano image from Nvidia (based on Ubuntu 18.04), please follow instructions from the Nvidia guide.
2. Setup and First Boot
Follow the setup step of the Nvidia guide to fully complete the installation. In system configuration, use husarion
as a username and rosbotxl
as a computer name (it is required by robot configs setup).
3. Internet connection
The nmcli
tool will be used only temporarily to install dependencies and it will be replaced by netplan, so the later step Connecting ROSbot XL to your Wi-Fi network
will still be necessary.
Now please connect your Jetson to the Internet using Wi-Fi. You can use GUI or the nmcli
tool (nmcli device wifi connect PLACE_YOUR_WIFI_SSID_HERE password PLACE_YOUR_WIFI_PASSWORD_HERE
).
SSH is already installed, from now on you can switch to a remote connection.
4. Netplan installation
Install netplan and other useful utilities:
sudo apt update
sudo apt install -y netplan.io wireless-tools net-tools unison rfkill network-manager nano
5. Robot configs installation
Next install robot configs using:
git clone https://github.com/husarion/robot-configs
sudo ./robot-configs/install.sh
rm -rf robot-configs
sudo setup_robot_configuration rosbot_xl ros2_humble
6. Docker installation Use the following commands to install Docker Engine:
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
sudo groupadd docker
sudo usermod -aG docker $USER
Now install Docker compose v2.16.0:
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-aarch64 -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
7. Creating symlinks
To create symlinks first open the file:
sudo vim /etc/udev/rules.d/10-local.rules
copy and paste the following lines:
ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", SYMLINK+="ttyUSBDB"
ACTION=="add", ATTRS{idVendor}=="10c4", SYMLINK+="ttyRPLIDAR"
then save and quit (:wq
).
8. Husarnet installation
Use the following command to install Husarnet:
curl -s https://install.husarnet.com/install.sh | sudo bash
Now reboot to make sure that all changes were applied.
Accessing ROSbot's Linux terminal
To perform the initial network configuration, you need to access ROSbot's Linux terminal first. There are two options:
Option 1: Using display, mouse and keyboard
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
ROSbot is basically a computer running Ubuntu, so let's open it like a standard PC.
- Plug in a display with HDMI, mouse and keyboard into the USB port in the rear panel of ROSbot.
- Turn on the robot and wait until it boots.
- Open Application Launcher (Husarion Logo in top-left corner) > System Tools > Terminator app.
ROSbot's graphical desktop environment requires about 3 minutes to start during the first boot. The following ones require only about 1 minute after power on.
Just like in the installation step, you can connect to your Jetson using the display:
- Plug in a display with HDMI, mouse and keyboard into the USB port in the rear panel of ROSbot.
- Turn on the robot and wait until it boots.
- Use
Ctrl+Alt+T
to open the terminal.
Option 2: Using an Ethernet port
Turn on the robot and wait until it boots.
Plug one end of the Ethernet cable into your computer and another one into the robot's Ethernet port.
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
- IPv4:
To connect with ROSbot via ssh, type in your terminal:
user@mylaptop:/home/user$ssh husarion@192.168.77.2
The default password for user
husarion
is alsohusarion
.
Connecting ROSbot XL to your Wi-Fi network
Find available Wi-Fi networks with this Linux command:
nmcli dev wifi
ROSbot XL is using netplan instead of a graphical Wi-Fi manager. It allows you to have all physical network interfaces configured from a single text file.
To connect your ROSbot to a Wi-Fi network, edit /etc/netplan/01-network-manager-all.yaml
file, e.g. with nano
:
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:
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
# ========================================
# wlan0:
# dhcp4: no
# dhcp6: no
# addresses:
# - 192.168.100.1/24
# access-points:
# "rosbotap":
# band: 5GHz
# mode: "ap"
# password: "husarion"
then save the file (with ctrl+o if using nano) and apply the new network setup:
sudo netplan apply
You can check to which Wi-Fi network your ROSbot is connected by using this command:
sudo iwgetid
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.
Type
sudo ifconfig
to find your IP address (for wlan0
network interface). Save it for later.
Remote access
OPTION 1: in a local network
While ROSbot is connected to a Wi-Fi network, you can access it by using its IPv4 address by SSH:
ssh husarion@ROSBOT_IP
OPTION 2: over the Internet (VPN)
If LAN access is not enough you can access the ROSbot over the Internet thanks to Husarnet. The full guide on how to do it is here.
ROSbot ROS packages
At this stage you should have your ROSbot up and running, with a remote (LAN or VPN) connection from your laptop.
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
You can run ROSbot's ROS packages natively on your ROSbot's host OS, by just cloning and building rosbot_xl_ros repo. You will find a ROS 2 API for the ROSbot XL here.
Instead of installing ROSbot XL ROS packages natively, it is more convenient to use Docker images for that.
As ROS isn't installed natively, the only option for running ROSbot XL software is to use Docker images.
Pulling basic docker images for ROSbot
Access your ROSbot's terminal and run:
docker compose pull
To flash the right firmware, open ROSbot's terminal and execute the following command:
docker stop rosbot-xl microros || true && \
docker run --rm -it --privileged \
--mount type=bind,source=/dev/ttyUSBDB,target=/dev/ttyUSBDB \
husarion/rosbot-xl:humble \
flash-firmware.py -p /dev/ttyUSBDB
Running the ROSbot Docker image
To launch basic ROSbot XL ROS 2 nodes, paste the following command in the ROSbot's terminal:
docker compose up -d
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
At this point, ROS nodes from the containers are available on the level of the host operating system.
To ensure that ROS topics are visible, restart the currently running ROS daemon:
ros2 daemon stop
Check available ROS topics:
ros2 topic list
To check available topics first, you have to start a new shell session in the rosbot-xl
container:
docker exec -it rosbot-xl bash
Then you can run:
ros2 topic list
Manual ROSbot driving with teleop_twist_keyboard
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
Now launch a teleop_twist_keyboard
ROS node for manual ROSbot control:
ros2 run teleop_twist_keyboard teleop_twist_keyboard
After running the command, you will see the usage instruction:
If you followed the previous step, you should already have a shell in the container. If not, run:
docker exec -it rosbot-xl bash
Launch a teleop_twist_keyboard
ROS node for manual ROSbot control:
ros2 run teleop_twist_keyboard teleop_twist_keyboard
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, the full dockerized setup is a better approach.
Next demos start ROSbot's containers with different configurations, so remember to stop the basic setup first:
docker compose down
Find available projects below:
- Intel NUC/Raspberry Pi
- Nvidia Jetson Nano
link | description |
---|---|
rosbot-xl-gamepad | Control the robot manually using a Logitech F710 gamepad |
rosbot-xl-mapping | Create a map (using slam_toolbox) of the unknown environment with ROSbot controlled in LAN or over the Internet |
rosbot-xl-navigation | Autonomous navigation (using navigation2) on a map created with the rosbot-xl-mapping demo linked above. |
link | description |
---|---|
rosbot-xl-mapping | Create a map (using slam_toolbox) of the unknown environment with ROSbot controlled in LAN or over the Internet |
rosbot-xl-navigation | Autonomous navigation (using navigation2) on a map created with the rosbot-xl-mapping demo linked above. |
Here is a map example generated with the rosbot-xl-mapping project which can be used in the rosbot-xl-navigation.