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