Connecting to sources…

How to build Andino (Ekumen's open-source ROS 2 education robot): the whole process

206 steps to build Andino (Ekumen's open-source ROS 2 education robot), from buying parts, printing and assembly to software, calibration and training, with the bill of …

Ekumen's 2023‑07 announcement puts the build under $300 (the creator's estimate, for the design before the redesign, without saying what it covers); the redesigned README BOM gives purchase links but no prices. No official kit is sold

Buy parts

  • Buy Raspberry Pi 4 B

    Buy a Raspberry Pi 4 B with 4 GB; the document also notes that the 8 GB model can provide better performance.

  • Buy two encoder motors

    Buy two Hobby Motor with Encoder - Metal Gear (DG01D-E) motors.

  • Buy wheels for TT motors

    Buy generic wheels for TT motors.

  • Buy an Arduino Nano

    Buy the listed Arduino Nano using the provided purchase link.

  • Buy the BNO055 IMU

    Buy the listed BNO055 IMU using the provided purchase link.

  • Buy the L298N dual H-bridge module

    Buy the listed L298N Dual H Bridge using the provided purchase link.

  • Buy the RPLidar A1M8

    Buy the RPLidar A1M8 from RobotShop or Amazon as listed in the document.

  • Check and buy a micro-USB cable

    Check whether the RPLidar A1M8 includes a microUSB-USB cable; if not, purchase one.

  • Buy Raspi Camera Module V2, 8 MP

    Buy the Raspberry Pi Camera Module V2 (8 MP) from Robotshop or Amazon.

  • Also get a 30 cm longer cable as spare

    The document includes a link for a 30 cm longer cable in case the one included with the camera is too short.

  • Buy a battery case for 18650 cells

    Buy the plastic battery case on Amazon; the link is for a 6-pack of cases but only one is needed.

  • Buy 18650 batteries

    Buy rechargeable 18650 batteries on Amazon; any 18650 batteries should work.

  • Buy an 18650 Battery Charger

    Buy any 18650 battery charger, such as one for more than two batteries.

  • Choose a 12V-to-5V DC-DC Converter

    Use a step-down DC-DC regulator with a 12V input and a 5V output of at least 3A.

  • Choose a Properly Sized Kill Switch

    Choose a kill switch with mounting holes measuring 13 × 20 mm.

  • Buy a Caster Wheel

    Buy the caster wheel listed for the robot.

  • Buy zip ties

    Buy zip ties from Amazon; only 4 to 6 will be used.

Print and make

  • Print the base chassis

    3D print the Base_chassis STL file.

  • Print the lidar chassis

    3D print the lidar_chassis STL file.

  • Print the battery chassis

    3D print the Battery_chassis STL file.

  • Print the Arduino lock base

    3D print the Arduino_lock_base STL file.

  • Print the camera case

    3D print the Camera_case model.

Assemble

  • Solder the Arduino Nano pins

    The Arduino pins may be soldered in any position, but they are recommended to be soldered as shown in the picture.

  • Install the rear wheel

    Place the base chassis face down and install the wheel in the base chassis.

  • Place the chassis face up

    Place the base chassis face up.

  • Install motors and IMU

    Install the motors with four 30 mm screws and install the IMU with a zip tie.

  • Route the camera flex

    Pass the camera flex through the hole below the IMU base as shown in the image.

  • Place camera in its case

    Place the camera inside the camera case as shown in the image.

  • Position the camera case

    Place the camera case in its position as shown; when spreading the base, avoid damaging it.

  • Place Raspberry and wheels

    Rotate the base 180 degrees, place the Raspberry as shown, and insert the wheels into the motors.

  • Connect motor driver power

    Add power and 5 V cables to the motor driver; the power cables should be at least 15 cm long.

  • Complete driver connections

    Finish all motor driver connections according to the connection diagram.

  • Mount the Arduino

    Place the Arduino using the Arduino lock base.

  • Wire and organize cables

    Make the remaining connections according to the connection diagram and organize the cables as preferred.

  • Place lidar in its base

    Place the lidar in the lidar base as shown in the image.

  • Secure lidar driver

    Fix the lidar driver to the lidar base with zip ties as shown in the image.

  • Mount lidar base on chassis

    Place the lidar base above the base chassis and screw it into place.

  • Install converter and killer switch

    Place the 5 V step-down driver and killer switch in the battery chassis as shown.

  • Check battery chassis exterior

    Check that the exterior looks like the shown image.

  • Place battery case in chassis

    Place the battery case inside the battery chassis as shown in the image.

  • Connect power and assemble

    Make all power connections according to the power connection diagram and place the battery chassis in the base chassis as shown.

  • Finish the Andino assembly

    Complete the final Andino assembly in its closed configuration.

  • Connect the Switch Ground

    Connect the ground cable to the switch only when it has an LED indicator.

  • Connect the Camera Ribbon Cable

    When connecting the camera ribbon cable, ensure the blue or silver side faces the USB ports.

  • Connect and verify RPLidar

    Connect the A1M8 RPLidar to the USB port. The green light on the A1M8 side board of the USB converter should turn on.

  • Wire Using the Board Definition

    Wire the Arduino Uno using the pin assignment in boards/arduino_uno/andino/board.h; the Arduino Nano uses the same assignment.

  • Connect the L298N Enable Input

    If the L298N motor-driver board has an enable jumper, connect it directly to 5V.

  • Connect Encoder Interrupt Inputs

    Connect the encoder inputs to their assigned pins in the board pin definition and use interrupt-capable pins; AVR boards use pin-change interrupts.

  • Connect the Optional BNO055 IMU

    Optionally connect an Adafruit BNO055 over the I2C bus; the firmware also works without it.

  • Wire the Blue Pill by Definition

    Wire the STM32 Blue Pill using the pin assignment in boards/stm32_bluepill/andino/board.h.

  • Use Distinct Encoder Pin Numbers

    Use different encoder pin numbers, here 12 through 15, because pins with the same number on each port share an external interrupt line.

  • Avoid USB and Debugger Pins

    Do not assign other functions to PA11, PA12, PA13, or PA14; the first pair is used by USB and the second pair by the debugger.

  • Connect Board or ST-Link

    Connect the board to the host machine's USB port. The Blue Pill is flashed through an ST-Link connected to its SWD header, so connect the ST-Link instead.

  • Connect Blue Pill Serial Port

    After flashing, connect the Blue Pill to the host with a second USB cable. The ST-Link is only needed for flashing, and the Blue Pill's USB CDC serial port usually appears as `/dev/ttyACM0`.

  • Read the Andino hardware assembly instructions

    Open the andino_hardware directory and assemble the robot using its assembly instructions.

Software

  • Upload Microcontroller Firmware

    Upload the microcontroller firmware by following the andino_firmware package instructions.

  • Configure the SBC with Ansible

    Use the community-provided Ansible playbooks to configure the SBC; the link is https://github.com/garyservin/andino_ansible_config.

  • Choose the Raspberry Pi OS

    For ROS 2 Humble, use Ubuntu Mate 22.04 ARM64; for ROS 2 Jazzy, use Ubuntu Server/Desktop 24.04.

  • Write the OS to a microSD Card

    Download the image for the target ROS distribution and install it to a microSD card with Raspberry Pi Imager; no extra configuration is required.

  • Boot and Complete Initial Setup

    Boot the Raspberry Pi with the microSD card and an HDMI connection, then complete the setup wizard; the document suggests simple credentials such as user pi and password admin.

  • Update the System and Reboot

    Run sudo apt update && sudo apt upgrade in a terminal to update the system, then reboot.

  • Install the SSH server

    Install openssh-server on the Raspberry so it can be accessed remotely over the same network.

  • Enable and connect over SSH

    Enable the SSH service, then connect to the Raspberry from a remote computer. The documented example uses user pi and address 192.168.0.102.

  • Update the package index

    Update the Raspberry's package index before installing the dependencies needed later.

  • Install common utilities

    Install git, net-tools, software-properties-common, and build-essential.

  • Install ROS Python packages

    Install the listed ROS Python and Catkin-related packages.

  • Install Colcon and ROS 2

    Install Colcon using the linked instructions, then install ROS 2 Humble or ROS 2 Jazzy according to the Ubuntu version. For Jazzy and later, check the official Raspberry Pi instructions and rely on Ubuntu Noble's noble-backports.

  • Automatically source ROS

    Add `source /opt/ros/humble/setup.bash` to the `~/.bashrc` file so the ROS installation is sourced automatically.

  • Install Arduino drivers

    Install Arduino on the Raspberry for serial communication between the SBC and the Arduino microcontroller.

  • Configure serial device permissions

    Add the current user to the `dialout` and `plugdev` groups for serial device access.

  • Reboot to apply group permissions

    Reboot the system after configuring the user groups so the changes take effect.

  • Remove the brltty conflict

    On Ubuntu 22.04, remove `brltty` from the system to avoid a conflict with some chip drivers.

  • Install the camera software

    After connecting the camera module to the Raspberry's camera port, install the required packages.

  • Grant video device access

    Add the current user to the `video` group to use the Raspberry camera.

  • Check the camera status

    Run the camera status command to check whether the Raspberry camera is available.

  • Modify the boot configuration

    Open /boot/firmware/config.txt, add start_x=1 and gpu_mem=128 under [all], then save and close it.

  • Install and launch raspi-config

    Install raspi-config and then run sudo raspi-config.

  • Enable the Raspberry Pi camera

    Open Interface Options, select camera, and enable it.

  • Reboot and confirm the camera

    Reboot the system; the camera should then work correctly.

  • Check the RPLidar serial-port authority

    Run ls -l /dev |grep ttyUSB to inspect the permissions of the RPLidar serial-port device.

  • Grant RPLidar serial-port permissions

    Run sudo chmod 666 /dev/ttyUSB<number_of_device> to add permissions, replacing <number_of_device> with the actual device number.

  • Create fixed USB port-name rules

    Create rules that run whenever the Raspberry Pi boots and link each real ttyUSBX port to its designated fixed name.

  • Check connected USB devices

    Run sudo dmesg | grep ttyUSB. In the tested setup, the Arduino Microcontroller was on usb 1-1.2 with ttyUSB0, and the A1M8 Lidar Scanner was on usb 1-1.1 with ttyUSB1.

  • Find the USB device attributes

    Run the attribute walk for each device and find idProduct and idVendor under the category matching its USB number. The document's Arduino example uses /dev/ttyUSB0.

  • Create the robot workspace

    Create the `robot_ws/src` workspace under the home directory.

  • Check UTF-8 locale

    Check whether the current locale supports UTF-8, then install the locales package.

  • Generate and set US UTF-8 locale

    Install locales, generate en_US.UTF-8, and set the LC_ALL, LANG, and LANG environment variables.

  • Verify locale settings

    Run locale again to verify the settings.

  • Install ROS 2 apt source package

    Download and install the latest ros2-apt-source release package; it provides keys and apt source configuration.

  • Install development tools optionally

    If you are going to build ROS packages or otherwise do development, you can install the development tools. On Ubuntu 24.04, check the suite settings in the apt source file.

  • Update apt suite configuration

    If noble-updates or noble-backports are missing, edit /etc/apt/sources.list.d/ubuntu.sources and set the Suites line to noble, noble-updates, and noble-backports. Then clean and update the packages.

  • Install ROS development tools

    Update the apt cache and install ros-dev-tools.

  • Update apt repository caches

    After setting up the repositories, update the apt repository caches.

  • Upgrade the Ubuntu system

    Before installing new packages, ensure that the system is up to date.

  • Install ROS desktop

    Install the recommended desktop package with ROS, RViz, demos, and tutorials.

Calibrate and test

  • Check the Application Configuration

    Inspect App::Config in include/andino/app/app.h; it is defined as andino::kAppConfig in the board package and passed to App in src/main.cpp.

  • Match the Host Serial Baud Rate

    Set the host serial baud rate to 57600 so it matches Board::kSerialBaudRate in the board package.

  • Check the Maximum Motor Speed

    Check Motor::kMaxSpeed in include/andino/drivers/motor.h; the maximum motor speed uses a PWM duty cycle of 255.

  • Verify open-loop motor control

    Send setpwm 255 255 to run at full speed, then send setpwm 0 0 to stop.

  • Read encoder values

    Send getenc to read and inspect the encoder values.

  • Calibrate ticks per motor revolution

    First send rstenc to reset the encoders to zero, then rotate the motors a chosen number of revolutions, such as 10. Divide the encoder ticks by the number of revolutions and save the result as the control-loop calibration.

  • Verify closed-loop speed control

    Send setspd <tps> <tps>, where tps means ticks per second. For a motor-encoder system with 700 ticks per revolution, setspd 700 700 rotates both motors at one revolution per second, about 6.28 rad/s.

  • Find the Board Serial Port

    Run `pio device list` to find the board's serial port. Arduino boards usually use `/dev/ttyUSB0`, while Blue Pill boards usually use `/dev/ttyACM0`.

  • Run the Hardware Connection Check

    Run `tools/hw_check.py` from the `andino_firmware` directory to validate the hardware connections to the MCU and firmware flashing. If `--port` is omitted, the tool will attempt to use the only connected device, if there is one.

  • Check Motor Rotation Direction

    If one motor rotates opposite to its chassis orientation, toggle the positive and negative outputs of the L298N.

  • Check Encoder Count Direction

    Encoder values should increase when moving forward and decrease when moving backward. If they behave oppositely, toggle the A and B encoder signals.

  • Verify camera support

    If supported=1 detected=1 is shown, the camera is fine; otherwise, perform the configuration first.

  • Identify each USB device

    If a device cannot be identified, connect the devices one by one and check the command output to determine each one's ttyUSB port.

  • Record each device's identifying attributes

    Record the idProduct and idVendor of each device as the attributes that anchor a specific device to its assigned name.

  • Run the C++ talker

    In one terminal, source the setup file and run the demo_nodes_cpp talker.

  • Run the Python listener

    In another terminal, source the setup file and run the demo_nodes_py listener.

  • Verify message publishing and reception

    Confirm that the talker reports publishing messages and the listener reports hearing those messages.

  • Confirm the C++ and Python APIs

    Use the examples to verify that both the ROS 2 C++ and Python APIs work properly.

  • Automatically select the distro configuration

    By default, the configuration is selected automatically according to the ROS 2 distribution: Humble uses nav2_params_humble.yaml and Jazzy uses nav2_params_jazzy.yaml.

  • Use a custom parameter file

    Pass the path to a custom parameter file when launching the navigation stack.

  • Configure sensor initialization

    include_rplidar and include_camera are both true by default. Use launch arguments to disable or manage each sensor initialization separately.

  • Inspect ROS topics

    After launching the robot, inspect the environment with the ROS 2 CLI. Running ros2 topic list displays available topics such as /cmd_vel, /odom, /scan, and /image_raw.

  • Check the Docker Compose version

    If Docker Desktop is already installed, select About Docker Desktop from the Docker menu to check the Compose version.

  • Configure ROS 2 Control Hardware Parameters

    Pass hardware-interface parameters through the ros2_control tag in the URDF description at andino_description/urdf/include/andino_control.urdf.xacro.

Data and training

  • Teleoperate with keyboard

    Launch Andino teleoperation using the keyboard. This is similar to running teleop_twist_keyboard.

  • Teleoperate with joystick

    Using a joystick is notably better for robot teleoperation. Configure the joystick as described in andino_hardware/README.md before launching.

  • Map with the Robot

    Use the robot for mapping and see `andino_slam` for more information.

  • Record Topics With rosbag

    Use `rosbag_record.launch.py` to execute `ros2 bag record` and store the specified topics in a `.bag` file. If no topics are specified, all topics are recorded.

  • Teleoperate With a Keyboard

    Use `teleop_keyboard.launch.py` to command the robot with a keyboard. It uses the `teleop_twist_keyboard` package.

  • Save the SLAM Map

    Use the map_saver_cli node provided by Nav2 to save a map, and specify the map name with -f.

  • Adjust Map Space Thresholds

    Use the --free and --occ arguments to modify the thresholds for free space and occupied space.

  • Provide a recorded map

    Prepare a recorded map for navigation; refer to andino_slam for map recording.

Use it

  • Use Closed-Loop Wheel Control

    Use `setspd` to enable a PID controller for each wheel, and use `setspd 0 0` to stop the motors and disable the PID. Every 33 ms (`pid_rate_hz`, 30 Hz), the controller compares the measured ticks with the target and updates the motor PWM.

  • Use Open-Loop PWM Control

    Use `setpwm` to disable the PID and drive the motors directly with the specified PWM value. Positive values move forward, and negative values move backward.

  • Keep Commands to Prevent Auto-Stop

    If no `setspd` or `setpwm` command is received for 3 seconds (`auto_stop_window_ms`), the motors stop and the PID is disabled. Keep sending the command periodically to keep the robot moving.

  • Start RViz Visualization

    Run the provided launch file to start `rviz2` with the included configuration.

  • Bring Up the Navigation Stack

    Follow the `andino_navigation` README instructions to bring up the Nav2-based navigation stack on the real robot or in simulation.

  • Choose a Simulation Platform

    Choose a simulator from the platforms provided in the Andino ecosystem; `andino_gz` is recommended.

  • Visualize Andino in RViz

    Use `rviz.launch.py` to execute the RViz visualization tool with the default `andino.rviz` configuration. Visualize the robot's 3D model and information from the topics.

  • Connect to the firmware serial monitor

    After the firmware is flashed, open a serial connection to the board at 57600 baud to send the firmware commands described in the firmware README. Press Ctrl+C to exit the monitor.

  • Launch the Nav2 navigation stack

    Launch the Andino navigation stack with the path to the map YAML file.

  • Navigate on the Saved Map

    After saving the map, follow the andino_navigation instructions to navigate on it.

Common problems

  • Printed chassis lacks mounting holes, requiring manual drilling after printing. #14
  • Real robot fails to run even though Gazebo simulation works. #274
  • First-time colcon build fails due to unmet ROS dependencies. #117 #272
  • Arduino firmware fails to compile; required libraries are not listed. #276
  • Motors only turn on or off; no speed control available. #292

Parts

  • Raspberry Pi 4B 4GB (or 8GB) with a 64 GB SD card
  • Arduino Nano (the firmware also supports the Uno and STM32 Blue Pill) with an L298N dual H-bridge
  • 2 × DG01D‑E metal-gear encoder motors (SparkFun), generic TT-motor wheels and a caster wheel
  • RPLidar A1M8 lidar, Raspberry Pi Camera Module V2 (8 MP), BNO055 IMU
  • 18650 batteries, battery case and charger, a 12V-to-5V step-down converter (3A or more), a kill switch
  • Printed parts: base chassis, lidar chassis, battery chassis, Arduino lock base and camera case; M3 screws, nuts and zip ties

Tools

  • A set of screwdrivers (README tool list)
  • A 3D printer or a printing service
  • The Arduino header pins may need soldering (the README suggests an orientation)

Skills

  • Ubuntu and ROS 2: colcon, rosdep, launch files
  • udev rules for fixed serial port names, Raspberry Pi camera setup
  • Building and flashing the firmware with PlatformIO (in Docker)
  • SLAM mapping and Nav2 navigation

Software

  • ROS 2 Humble (Ubuntu 22.04) or Jazzy (Ubuntu 24.04), with apt binaries, or set up with Ansible
  • andino_firmware: PlatformIO firmware with 30 Hz wheel-speed PID, encoder counting, BNO055 reading and auto-stop after 3 s without commands
  • andino_base (ros2_control hardware interface), andino_slam (slam_toolbox), andino_navigation (Nav2)
  • Simulation: andino_gz (recommended), Webots, O3DE, Isaac Sim, MuJoCo

Documents