episode 3 the tools
Every adventure needs the right equipment / Toda aventura necesita el equipo correcto
Commit and release version: Pre-Release: Episode 3 - The tools
- 🎥 Watch the Short
- 📖 Episode Description
- 🛠️ Hardware Components
- 💻 Software Stack
- 📋 Installation Guide
- 📚 References & Additional Resources
- 💡 Lessons & Learnings
- 🎯 Challenge Posed
- ⏭️ Next Episode
David asks the critical question: what do we actually need to build this? Danna lists the hardware components they've been reviewing—membrane keyboard, potentiometers, joystick, cables, LEDs, buttons. Felipe interrupts to emphasize the most crucial component: the ESP32. David then pivots to software tools on the PC side. Felipe's answer reveals the full stack: Ubuntu 24.04, ROS 2 Jazzy, micro-ROS, Docker, VS Code, and PlatformIO. Danna's reaction is immediate: "That's complex! We'll need a guide." Felipe smiles: "Already working on it." And with that, the hands-on work officially begins.
This list will be updated as the chapters release to ensure the list remains consistent with the content.
| Component | Purpose | Notes | Shopping Link |
|---|---|---|---|
| ESP32 | Main microcontroller | Brain of the vambrace, runs micro-ROS client | Amazon |
| Joystick | Teleoperation control | Controls ORION's movement | Amazon |
| Potentiometers | Arm control | Adjust ORION's arm positions (left/right) | Amazon |
| Membrane Keyboard | Quick actions | Program default emotions and actions | Amazon |
| LEDs & Resistors | Visual feedback | Status indicators for connection, mode, etc. | Amazon |
| Buttons | Additional controls | Mode switching, emergency stop, etc. | Amazon |
| Cables | Wiring | Connecting all components to ESP32 | Amazon |
| Protoboard | Prototyping | Breadboard for temporary connections | Amazon |
| Power Supply | Battery/USB | Powering the entire system | — |
| Tool | Purpose | Why We Need It |
|---|---|---|
| Ubuntu 24.04 LTS | Operating system | Primary platform for ROS 2 Jazzy |
| ROS 2 Jazzy | Robotics middleware | Communication backbone for ORION |
| micro-ROS | Micro-controller bridge | Connects ESP32 to ROS 2 ecosystem |
| Docker | Containerization | Consistent development environment |
| VS Code | Code editor | Unified environment for all development |
| PlatformIO | Embedded dev platform | ESP32 firmware development |
Below is the complete installation guide to set up your development environment for the Vambrace Adventure.
Ubuntu 24.04 "Noble Numbat" is the base operating system for ORION's stack. It is the recommended distribution for ROS 2 Jazzy, as it is its primary supported platform.
| Method | When to use it |
|---|---|
| Native installation | Dedicated robot hardware or main development PC |
| Virtual machine (VirtualBox/VMware) | Quick testing for software on local setup without risks |
| WSL2 (Windows) | Windows development with access to Linux tooling on a local environment |
| Dual boot | Full hardware access without giving up your main operating system |
That is why we recommend a native or dual bool installation, as we will use the system and the communications, where a virtual machine or WSL2 do not external communication for this type of project. You can also try with Docker containers for ROS 2 Jazzy or micro-ROS containers.
We recommend the next resources for installation:
VS Code is the primary editor Felipe uses for ORION development. Through its extensions, it covers both micro-controller firmware and ROS 2 node development in a single environment.
Installation on Ubuntu 24.04:
-
Download the .deb file from Download VS Code.
-
Install it
sudo apt install ./<file.deb># Download and install from the official Microsoft repository
sudo apt update && sudo apt install -y wget gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg
echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] \
https://packages.microsoft.com/repos/code stable main" | \
sudo tee /etc/apt/sources.list.d/vscode.list > /dev/null
sudo apt update && sudo apt install -y codeOnce VS Code is installed, search and install these extensions from the Marketplace (Ctrl+Shift+X):
| Extension | Purpose |
|---|---|
ms-python.python |
ROS 2 node development in Python |
ms-vscode.cpptools |
C++ development for ROS 2 and firmware |
platformio.platformio-ide |
Microcontroller firmware management |
ms-vscode-remote.remote-containers |
Docker container integration |
redhat.vscode-yaml |
ROS 2 configuration file editing |
Feel free to install any other extension you may consider relevant to the development.
PlatformIO is the development ecosystem for ORION's microcontroller firmware. It integrates directly as a VS Code extension.
PlatformIO is installed as a VS Code extension:
- Open VS Code
- Go to Extensions (
Ctrl+Shift+X) - Search for PlatformIO IDE
- Click Install
PlatformIO will automatically install its core (PlatformIO Core) and all required dependencies on first use. Just a note, tt may take a while to install.
Once installed, verify the environment is working correctly:
# Verify PlatformIO Core from the terminal
pio --version
# Expected output:
# PlatformIO Core, version X.X.XAs a little story, when Felipe first show PlatformIO to the team, it was funny when Danna highlighted that pio wasn't so serious for a project as it sounded like a chicken clucking, then Felipe just said it was a short version of PlatformIO (PIO). However, it was memorable.
ROS 2 Jazzy is ORION's core middleware for node communication, navigation, and HRI applications. It is the LTS version compatible with Ubuntu 24.04.
Installation:
# 1. Set up locale
sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
# 2. Add the ROS 2 repository
sudo apt install -y software-properties-common curl
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
-o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \
http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | \
sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
# 3. Install ROS 2 Jazzy (full Desktop)
sudo apt update && sudo apt upgrade -y
sudo apt install -y ros-jazzy-desktop
# 4. Install development tools
sudo apt install -y python3-colcon-common-extensions python3-rosdep ros-dev-tools
# 5. Initialize rosdep
sudo rosdep init
rosdep updateEnvironment Setup:
# Add the source to .bashrc so it's available in every terminal session
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrcVerification:
# Verify the installation with the classic demo
# Terminal 1 — Publisher:
ros2 run demo_nodes_cpp talker
# Terminal 2 — Subscriber:
ros2 run demo_nodes_py listenerIf you see messages like [INFO] [talker]: Publishing: 'Hello World: X', ROS 2 Jazzy is up and running!
Docker allows containerizing development and deployment environment, ensuring reproducibility across different development machines. It may help you if you need a rapid deploy of a ROS 2 container or a micro ROS setup to test a device.
Installation:
# 1. Remove old versions (if any)
sudo apt remove -y docker docker-engine docker.io containerd runc 2>/dev/null
# 2. Install dependencies
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
# 3. Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# 4. Add the repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 5. Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginPost-installation setup:
# Allow running Docker without sudo
sudo groupadd docker 2>/dev/null
sudo usermod -aG docker $USER
# Apply group changes (or restart your session)
newgrp dockerVerification:
docker run hello-world
# Expected output: "Hello from Docker!"
docker --version
docker compose versionmicro-ROS extends the ROS 2 ecosystem to resource-constrained micro-controllers, enabling ORION's low-level hardware to communicate directly with ROS 2 Jazzy nodes.
ORION Architecture:
[ Microcontroller (PlatformIO + micro-ROS client) ]
↕ (Serial / UDP)
[ micro-ROS Agent (Ubuntu / Docker) ]
↕ (DDS)
[ ROS 2 Jazzy Nodes ]
Option A — micro-ROS Agent via Docker (recommended):
The cleanest way to run the agent without polluting the base installation:
# Pull and run the micro-ROS agent (adjust the serial port)
docker run -it --rm \
--net=host \
--device=/dev/ttyUSB0 \
microros/micro-ros-agent:jazzy \
serial --dev /dev/ttyUSB0 -b 115200💡 Replace
/dev/ttyUSB0with the serial port where your microcontroller is connected. Usels /dev/tty*to identify it.
Option B — Build from source in the ROS 2 workspace:
# 1. Create the micro-ROS workspace
mkdir -p ~/microros_ws/src && cd ~/microros_ws
# 2. Clone the setup tools package
git clone -b jazzy https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup
# 3. Install dependencies and build
source /opt/ros/jazzy/setup.bash
sudo apt update && rosdep update
rosdep install --from-paths src --ignore-src -y
colcon build --symlink-install
source install/local_setup.bash
# 4. Create and build the agent
ros2 run micro_ros_setup create_agent_ws.sh
ros2 run micro_ros_setup build_agent.sh
source install/local_setup.bash
# 5. Run the agent
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -b 115200PlatformIO Integration:
Add the micro-ROS library to your platformio.ini:
[env:orion_mcu]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
lib_deps =
https://github.com/micro-ROS/micro_ros_arduino.gitVerification:
With the agent running and the microcontroller connected, open another terminal:
source /opt/ros/jazzy/setup.bash
ros2 topic list
# You should see the topics published by the micro-controllerOnce all steps are completed, use this checklist to confirm the full stack is operational:
# Operating System
lsb_release -a # Ubuntu 24.04 Noble
# VS Code
code --version
# PlatformIO
pio --version
# ROS 2 Jazzy
source /opt/ros/jazzy/setup.bash
ros2 --version # ros2cli 0.x (Jazzy)
ros2 pkg list | grep -c "" # number of installed packages
# Docker
docker --version
docker compose version
docker run hello-world
# micro-ROS Agent (Docker)
docker pull microros/micro-ros-agent:jazzy && echo "Image available ✓"| Resource | URL |
|---|---|
| ROS 2 Jazzy documentation | https://docs.ros.org/en/jazzy/ |
| micro-ROS documentation | https://micro.ros.org/docs/overview/ |
| PlatformIO documentation | https://docs.platformio.org/ |
| Docker get started | https://docs.docker.com/get-started/ |
| Ubuntu 24.04 release notes | https://ubuntu.com/blog/ubuntu-desktop-24-04-noble-numbat-deep-dive |
| ESP32 Arduino Core | https://github.com/espressif/arduino-esp32 |
| micro-ROS for Arduino | https://github.com/micro-ROS/micro_ros_arduino |
You don't need expensive proprietary tools or industrial-grade software licenses. The open-source community has created a complete, professional-grade toolkit that's freely available to anyone with curiosity and determination.
-
Open source democratizes innovation: Every tool in ORION's stack—from Ubuntu to ROS 2 to PlatformIO—is free and open-source. This means anyone, anywhere, can build sophisticated robotics projects without financial barriers.
-
Complexity is manageable with the right guide: Felipe's list might sound intimidating at first, but each tool serves a specific purpose. With proper documentation and step-by-step guidance, even complex stacks become approachable.
-
The community has your back: Behind every open-source tool is a community of developers, educators, and enthusiasts. When you get stuck, forums, documentation, and tutorials are there to help. You're never truly alone in your learning journey.
-
Hardware and software must work together: The vambrace isn't just electronics or just code—it's both. The ESP32 captures physical inputs, but without ROS 2 and micro-ROS bridging the gap to ORION, those inputs are meaningless. Integration is where magic happens.
The tools we use tell a story about modern robotics:
- Ubuntu 24.04 - A stable, community-driven OS trusted worldwide.
- ROS 2 Jazzy - Years of robotics research distilled into accessible middleware.
- micro-ROS - Extending ROS 2's power to tiny micro-controllers.
- Docker - Ensuring your environment works the same way everywhere.
- VS Code - A versatile editor that adapts to any workflow.
- PlatformIO - Making embedded development feel modern and intuitive.
Each of these represents thousands of hours of collective human effort, freely shared with the world. When we build with open-source tools, we're not just creating projects—we're participating in a global movement toward accessible knowledge and collaborative innovation.
The lesson: Don't be intimidated by the stack. Embrace it as proof that the barrier to entry for robotics has never been lower. What once required corporate labs can now happen in your bedroom, garage, or your own workshop.
"That's complex! We'll need a guide." — Danna "Already working on it." — Felipe
The guide is ready. The tools are identified. The environment is being set up. Now comes the real work: writing code, connecting components, testing integrations, and bringing the vambrace to life. The adventure moves from planning to building.
The next chapter of the Vambrace Adventure is in development. Stay tuned!
Characters: David, Danna, Felipe and ORION | Published: TBD | Wiki: March 1, 2025