Setup

This guide walks you through setting up the JOSHUA robotics framework on your development machine, building the project, and running your first robot configuration. JOSHUA supports both native installation on Ubuntu and containerized development via Docker.

Prerequisites

Before installing JOSHUA, ensure your system meets the following requirements. JOSHUA supports two Ubuntu LTS releases, each paired with its corresponding ROS2 distribution.

Operating System

Required Software

• Bazel 8.3.1 — Installed automatically via Bazelisk. Bazelisk manages the correct Bazel version based on the project's .bazelversion file.
• Python 3.10 (Ubuntu 22.04) or Python 3.12 (Ubuntu 24.04) — System default Python for the respective Ubuntu version.
• Git — For cloning the repository and version control.

Optional Software

• NVIDIA GPU with CUDA — Required for AI model training (SmolVLA, PPO reinforcement learning) and GPU-accelerated MuJoCo-XLA simulation. Not needed for teleoperation, basic simulation, or mock testing.
• Docker & Docker Compose — For containerized development and deployment. Recommended for CI/CD workflows and cross-platform builds (AMD64/ARM64).

Installation

JOSHUA provides two installation methods: native installation directly on Ubuntu, or Docker-based containerized development. Choose the method that best fits your workflow.

Option A: Native Installation

Native installation gives you the fastest development experience with direct hardware access. The setup script auto-detects your Ubuntu version and installs all required dependencies.

1. Clone the Repository

git clone https://github.com/Joshua-AI-Robotics/Joshua.git
cd Joshua

2. Run the Setup Script

JOSHUA provides a setup script that handles all dependency installation. Choose the environment that matches your use case:

Full Development Environment (includes all development tools, linters, testing frameworks):

scripts/setup.sh --env=dev

Minimal Runtime Environment (only essential runtime dependencies):

scripts/setup.sh --env=runtime

3. Source the ROS2 Environment

After installation, source the ROS2 setup file. This must be done in every new terminal session:

For Ubuntu 22.04 (Humble):

source /opt/ros/humble/setup.bash

For Ubuntu 24.04 (Jazzy):

source /opt/ros/jazzy/setup.bash

Option B: Docker Installation

Docker provides a fully isolated, reproducible development environment. This is the recommended approach for CI/CD pipelines, cross-platform development, and quick evaluation of the framework.

1. Prerequisites

Ensure Docker and Docker Compose are installed:

sudo apt-get update
sudo apt-get install docker.io docker-compose-v2
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

2. Clone and Start Containers

git clone https://github.com/Joshua-AI-Robotics/Joshua.git
cd Joshua

Start the container for your target platform:

# Ubuntu 22.04 (AMD64)
docker-compose up joshua-u22

# Ubuntu 24.04 (AMD64)
docker-compose up joshua-u24

# Ubuntu 22.04 (ARM64 - for Jetson Orin Nano)
docker-compose up joshua-u22-arm64

# Ubuntu 24.04 (ARM64)
docker-compose up joshua-u24-arm64

# Web UI only
docker-compose up joshua-ui

Available Docker Services

Building the Project

JOSHUA uses Bazel for hermetic, reproducible builds. The build system supports both Ubuntu 22.04 and 24.04 through platform-specific configurations.

Full Build

Build all targets in the project:

bazel build //...

Run All Tests

Execute the full test suite:

bazel test //...

Platform-Specific Builds

The .bazelrc file provides platform-specific configurations. Use the --config flag to target a specific Ubuntu version:

# Build for Ubuntu 22.04
bazel build //... --config=u22

# Build for Ubuntu 24.04
bazel build //... --config=u24

Building Specific Targets

You can build individual targets for faster iteration:

# Build only the main launcher
bazel build //launcher:joshua_main

# Build only robot drivers
bazel build //robot/...

# Build only AI inference modules
bazel build //ai/...

# Build only simulation targets
bazel build //simulation/...

Running Your First Robot

The JOSHUA launcher (joshua_main) is the central entry point for all robot operations. It reads a Protocol Buffers text configuration file (.pbtxt) that defines the complete system: hardware, sensors, AI models, communication, and operation mode.

The Mock Test Configuration

The simplest way to verify your installation is by running the mock test configuration. This preset uses mock (simulated) hardware drivers, so no physical robot hardware is required.

bazel run //launcher:joshua_main -- --config=config/config_preset/mock_py_test.pbtxt

The mock_py_test.pbtxt configuration does the following:

• Instantiates mock servo motors and sensors using the Python-based driver backend
• Sets up ROS2 nodes for sensor publishing and command subscription
• Runs the Node Generator orchestrator to manage the lifecycle of all child processes
• Validates the full configuration pipeline without requiring physical hardware

Running Other Configurations

The general pattern for running any configuration preset is:

bazel run //launcher:joshua_main -- --config=config/config_preset/<preset_name>.pbtxt

For example, to run the interactive MuJoCo simulation:

bazel run //launcher:joshua_main -- --config=config/config_preset/sim_interactive.pbtxt

Configuration Presets

JOSHUA ships with 25+ configuration presets in config/config_preset/. Each preset is a complete, ready-to-run system definition. The table below lists the available presets organized by operation mode.

Teleoperation Presets

AI Inference Presets

Simulation Presets

Calibration & Testing Presets

Hardware-Specific Presets

Project Structure

The JOSHUA repository is organized into clearly separated layers, each with its own Bazel BUILD files for independent builds and testing.

Joshua/
├── ai/                     # AI inference models and training pipelines
│   ├── model/              # Model implementations (SmolVLA, Decision Transformer)
│   ├── training/           # RL training loops (PPO, MJX)
│   └── registry/           # Model registry and factory
├── config/                 # Configuration system
│   ├── config_preset/      # Ready-to-run .pbtxt configuration presets
│   └── proto/              # Protocol Buffers schema definitions
├── launcher/               # joshua_main entry point and node generator
├── robot/                  # Robot Hardware Abstraction Layer
│   ├── actuator/           # Servo motors (STS3215, Pybricks)
│   ├── sensor/             # Camera, LiDAR, encoder drivers
│   ├── communication/      # Serial, Bluetooth, USB protocols
│   └── mock/               # Mock drivers for testing
├── simulation/             # MuJoCo simulation engine
│   ├── mujoco/             # MuJoCo wrapper and modes
│   ├── mjx/                # MuJoCo-XLA GPU training
│   ├── isaac/              # NVIDIA Isaac Sim integration
│   └── models/             # MJCF robot model files
├── ui/                     # User interfaces
│   ├── qt/                 # Qt6 C++ desktop control panel
│   └── web/                # React/TypeScript web monitoring UI
├── ros2/                   # ROS2 message definitions and utilities
│   └── msg/                # Custom message types
├── scripts/                # Setup, build, and deployment scripts
│   └── setup.sh            # Automated environment setup
├── docker/                 # Dockerfiles and docker-compose.yml
├── third_party/            # Third-party dependencies (Bazel external)
├── .bazelrc                # Bazel configuration (platform configs)
├── .bazelversion           # Pinned Bazel version (8.3.1)
├── BUILD                   # Root BUILD file
├── MODULE.bazel            # Bazel module definition
└── WORKSPACE               # Bazel workspace configuration

Next Steps

Now that you have JOSHUA installed and running, explore the following documentation to deepen your understanding of the framework: