Configuration System

Complete reference for JOSHUA's configuration-driven architecture. Learn how a single Protocol Buffers text file defines your entire robot system—hardware, sensors, AI models, communication, and operation mode—without requiring any code changes.

Overview

The entire JOSHUA system is driven by a single .pbtxt (Protocol Buffers text format) configuration file. This design philosophy eliminates the need for code changes when reconfiguring the robot: swapping hardware, changing operation modes, adding sensors, or switching AI models are all accomplished by editing the configuration file alone.

Key benefits of the configuration-driven approach:

• Zero code changes — Reconfigure hardware, sensors, AI models, and operation modes entirely through configuration.
• Schema validation — The Protocol Buffers schema catches invalid configurations at parse time before any hardware is initialized.
• Preset library — Over 25 pre-built configuration presets for common robot setups, training scenarios, and simulation environments.
• Version control — Text-format configurations produce clean diffs, enabling meaningful code review of system changes.
• Cross-language support — The same configuration is consumed by C++ node orchestrators and Python AI inference pipelines via generated bindings.

The configuration file is parsed by the Node Generator (the central orchestrator), which validates the configuration, resolves hardware dependencies, detects port conflicts, and spawns the appropriate ROS2 nodes as child processes.

Configuration Schema Hierarchy

The root of every JOSHUA configuration is the Config proto message. It is a composite structure containing five major sub-messages, each governing a distinct aspect of the system:

// Root configuration message
message Config {
  General     general     = 1;   // Operation mode, robot identity
  Robot       robot       = 2;   // Actuators and sensors
  Ai          ai          = 3;   // AI models, data stores, training
  Calibration calibration = 4;   // Servo calibration data
  SimulationConfig simulation = 5; // MuJoCo simulation settings
}

The hierarchy is designed so each subsystem is self-contained. The Node Generator reads the top-level Config and delegates each sub-message to the corresponding subsystem:

General Configuration

The General message defines the system-wide identity and operation mode for the robot. Every configuration file must include a general block.

message General {
  OperationMode mode       = 1;   // System operation mode
  string        robot_type = 2;   // e.g., "SO-ARM100", "LeKoch"
  string        name       = 3;   // Human-readable name
  string        id         = 4;   // Unique identifier
}

Operation Modes

The OperationMode enum determines the entire behavioral profile of the system. It controls which nodes are spawned, what hardware is initialized, and how data flows through the pipeline.

Example general configuration block:

general {
  mode: MODE_TELEOPERATE
  robot_type: "SO-ARM100"
  name: "leader_follower_teleop"
  id: "joshua-arm-001"
}

Robot Configuration

The Robot message defines all physical hardware in the system. It contains two repeated fields: one for actuators (actions) and one for sensors (perceptions). Each entry maps a piece of hardware to a ROS2 node with full communication configuration.

message Robot {
  repeated SingleAction     actions     = 1;  // Actuators (motors, servos)
  repeated SinglePerception perceptions = 2;  // Sensors (cameras, encoders, LiDAR)
}

SingleAction

Each SingleAction entry defines one actuator group (e.g., one robot arm) with its ROS2 node configuration, action type, and hardware-specific driver settings.

message SingleAction {
  Node        node        = 1;   // ROS2 node configuration
  ActionType  action_type = 2;   // Type of actuator
  oneof actuator_config {
    STS3215Config    sts3215_config    = 3;  // Waveshare STS3215 servo bus
    MockMotorConfig  mock_motor_config = 4;  // Virtual motor for testing
    SpikeMotorConfig spike_motor_config = 5; // LEGO SPIKE Pybricks motor
  }
}

ActionType Enum

Actuator Configurations

STS3215Config — Configuration for Waveshare STS3215 serial bus servos commonly used in the SO-ARM100 and similar arm designs:

message STS3215Config {
  Comm          comm          = 1;  // Serial port configuration
  repeated int32 motor_ids    = 2;  // Bus IDs [1, 2, 3, 4, 5, 6]
  int32         position_min  = 3;  // Minimum position value
  int32         position_max  = 4;  // Maximum position value
  int32         velocity      = 5;  // Default velocity
  int32         acceleration  = 6;  // Default acceleration
}

MockMotorConfig — Virtual motor driver for testing without physical hardware:

message MockMotorConfig {
  int32         num_motors   = 1;  // Number of simulated motors
  int32         position_min = 2;  // Simulated range minimum
  int32         position_max = 3;  // Simulated range maximum
}

SpikeMotorConfig — Configuration for LEGO SPIKE motors controlled via Pybricks over BLE:

message SpikeMotorConfig {
  Comm           comm        = 1;  // BLE connection configuration
  repeated string port_names = 2;  // Hub port identifiers ["A", "B", "C"]
}

SinglePerception

Each SinglePerception entry defines one sensor with its ROS2 node, perception type, and device-specific configuration.

message SinglePerception {
  Node            node            = 1;  // ROS2 node configuration
  PerceptionType  perception_type = 2;  // Type of sensor
  oneof device_config {
    CameraConfig   camera_config  = 3;  // Camera (OpenCV)
    EncoderConfig  encoder_config = 4;  // Rotary encoder
    LidarConfig    lidar_config   = 5;  // LiDAR sensor
  }
}

PerceptionType Enum

Device Configurations

CameraConfig — OpenCV-based camera configuration with full control over capture parameters:

message CameraConfig {
  int32  device_id   = 1;   // /dev/video index (e.g., 0, 2, 4)
  int32  width       = 2;   // Capture width in pixels (e.g., 640)
  int32  height      = 3;   // Capture height in pixels (e.g., 480)
  int32  fps         = 4;   // Frames per second (e.g., 30)
  string pixel_format = 5;  // OpenCV pixel format (e.g., "MJPG")
  int32  brightness  = 6;   // OpenCV CAP_PROP_BRIGHTNESS
  int32  contrast    = 7;   // OpenCV CAP_PROP_CONTRAST
  int32  saturation  = 8;   // OpenCV CAP_PROP_SATURATION
  int32  exposure    = 9;   // OpenCV CAP_PROP_EXPOSURE
}

EncoderConfig — Rotary encoder for joint position feedback:

message EncoderConfig {
  Comm   comm             = 1;  // Communication interface
  int32  resolution       = 2;  // Ticks per revolution
  bool   inverted         = 3;  // Reverse counting direction
}

LidarConfig — LiDAR sensor for distance measurement and mapping:

message LidarConfig {
  Comm   comm             = 1;  // Communication interface
  float  angle_min        = 2;  // Minimum scan angle (radians)
  float  angle_max        = 3;  // Maximum scan angle (radians)
  float  range_min        = 4;  // Minimum detection range (meters)
  float  range_max        = 5;  // Maximum detection range (meters)
}

AI Configuration

The Ai message configures the complete AI pipeline: model selection, dataset management, and training infrastructure.

message Ai {
  repeated SingleModel models     = 1;  // AI models to load
  DataStore            data_store = 2;  // Dataset configuration
  Training             training   = 3;  // Training pipeline settings
}

SingleModel

Each SingleModel entry registers an AI model with the system. Models are loaded into the model registry and can be instantiated on demand.

message SingleModel {
  ModelType model_type                   = 1;  // Model architecture
  string    pretrained_model_name_or_path = 2;  // HuggingFace model ID or local path
  Node      node                         = 3;  // ROS2 node for inference I/O
}

ModelType Enum

Example model configuration for SmolVLA inference:

models {
  model_type: SMOLVLA
  pretrained_model_name_or_path: "lerobot/smolvla_base"
  node {
    node_name: "smolvla_inference"
    node_id: 1
    node_type: PYTHON
    publishers {
      data_type: JOINT_STATE
      topic_name: "/ai/actions"
      publish_rate_hz: 10.0
    }
    subscriptions {
      data_type: IMAGE
      topic_name: "/camera/top/image_raw"
    }
    subscriptions {
      data_type: IMAGE
      topic_name: "/camera/wrist/image_raw"
    }
  }
}

DataStore

The DataStore message configures how demonstration data and training datasets are managed.

message DataStore {
  DataFormat     format       = 1;  // Serialization format
  StorageBackend storage      = 2;  // Storage location
  string         dataset_name = 3;  // Dataset identifier
  string         local_path   = 4;  // Local filesystem path
  string         remote_url   = 5;  // Cloud storage URL
}

DataFormat Enum

StorageBackend Enum

Training

The Training message configures the full training pipeline, including environment selection, training method, and simulator backend.

message Training {
  TrainingEnvironment environment        = 1;  // Sim or real
  TrainingMethod      method             = 2;  // RL, imitation, or evaluation
  SimulatorBackend    simulator_backend  = 3;  // MJX or Isaac Sim
  RLConfig            rl_config          = 4;  // Reinforcement learning parameters
  ImitationConfig     imitation_config   = 5;  // Imitation learning parameters
  EvalConfig          eval_config        = 6;  // Evaluation parameters
}

TrainingEnvironment Enum

TrainingMethod Enum

SimulatorBackend Enum

Training Sub-configurations

message RLConfig {
  string algorithm          = 1;  // e.g., "PPO"
  int32  num_envs           = 2;  // Parallel environments (e.g., 2048)
  int32  total_timesteps    = 3;  // Total training steps
  float  learning_rate      = 4;  // Optimizer learning rate
  float  gamma              = 5;  // Discount factor
  float  clip_range         = 6;  // PPO clipping parameter
  int32  batch_size         = 7;  // Mini-batch size
  string reward_function    = 8;  // Reward function identifier
}

message ImitationConfig {
  string dataset_name       = 1;  // Dataset to train on
  int32  num_epochs         = 2;  // Training epochs
  float  learning_rate      = 3;  // Optimizer learning rate
  int32  batch_size         = 4;  // Batch size
  string loss_function      = 5;  // e.g., "mse", "l1"
}

message EvalConfig {
  string model_checkpoint   = 1;  // Path to model weights
  int32  num_episodes       = 2;  // Episodes to evaluate
  repeated string metrics   = 3;  // e.g., ["success_rate", "avg_return"]
}

ROS2 Node Configuration

Every hardware device, AI model, and system component in JOSHUA is backed by a ROS2 node. The Node proto provides a unified configuration for node identity, process type, communication quality, and topic mappings.

message Node {
  string              node_name     = 1;  // ROS2 node name
  int32               node_id       = 2;  // Unique numeric identifier
  NodeType            node_type     = 3;  // Process backend
  QoSSettings         qos           = 4;  // Quality of Service profile
  repeated Publisher   publishers   = 5;  // Outgoing topics
  repeated Subscription subscriptions = 6; // Incoming topics
}

NodeType Enum

QoS Settings

Quality of Service settings control the reliability and performance characteristics of ROS2 communication.

message QoSSettings {
  Reliability reliability = 1;  // RELIABLE or BEST_EFFORT
  Durability  durability  = 2;  // VOLATILE or TRANSIENT_LOCAL
  History     history     = 3;  // KEEP_LAST or KEEP_ALL
  int32       depth       = 4;  // Queue depth (e.g., 10)
  Liveliness  liveliness  = 5;  // AUTOMATIC or MANUAL_BY_TOPIC
}

Publisher and Subscription

Publishers and subscriptions define the topic interface for each node. JOSHUA supports all 91 standard ROS2 message types.

message Publisher {
  DataType data_type       = 1;  // One of 91 ROS2 message types
  string   topic_name      = 2;  // Topic path (e.g., "/arm/joint_states")
  float    publish_rate_hz = 3;  // Publishing frequency in Hz
}

message Subscription {
  DataType data_type       = 1;  // Expected message type
  string   topic_name      = 2;  // Topic to subscribe to
}

DataType Enum (Selected Types)

The DataType enum maps to all 91 standard ROS2 message types. Below is a representative subset organized by category:

Communication Configuration

The Comm message (defined in comm.proto) configures the physical communication interface between the host and hardware devices.

// comm.proto
message Comm {
  oneof interface {
    Serial serial = 1;   // Wired serial (USB/UART)
    BLE    ble    = 2;   // Bluetooth Low Energy
  }
}

message Serial {
  string port     = 1;   // Device path (e.g., "/dev/ttyACM0")
  int32  baudrate = 2;   // Baud rate (e.g., 1000000)
}

message BLE {
  string device_name = 1;   // BLE device name to connect to
  string service_uuid = 2;  // BLE service UUID
}

Example serial communication for an STS3215 servo bus:

comm {
  serial {
    port: "/dev/ttyACM0"
    baudrate: 1000000
  }
}

Example BLE communication for a SPIKE hub:

comm {
  ble {
    device_name: "Pybricks Hub"
    service_uuid: "c5f50001-8280-46da-89f4-6d8051e4aeef"
  }
}

Simulation Configuration

The SimulationConfig message (defined in simulation.proto) controls the MuJoCo physics simulation engine. It supports four distinct operational modes and provides configuration for model loading and digital twin topic mapping.

message SimulationConfig {
  SimulationMode mode       = 1;  // Simulation operational mode
  string         model_path = 2;  // Path to MJCF XML model file
  repeated MirrorTopicMapping mirror_topic_mappings = 3;  // Digital twin mappings
}

message MirrorTopicMapping {
  string ros_topic       = 1;  // ROS2 topic to subscribe to
  string mujoco_actuator = 2;  // MuJoCo actuator name to drive
}

SimulationMode Enum

Example simulation configuration for a digital twin setup:

simulation {
  mode: MIRROR
  model_path: "models/so_arm100/scene.xml"
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "joint_1"
  }
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "joint_2"
  }
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "joint_3"
  }
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "joint_4"
  }
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "joint_5"
  }
  mirror_topic_mappings {
    ros_topic: "/follower/joint_states"
    mujoco_actuator: "gripper"
  }
}

Example Configuration

Below is a complete .pbtxt configuration for a teleoperation setup with leader and follower SO-ARM100 arms, a top-mounted camera, and data recording.

# JOSHUA Configuration: Leader-Follower Teleoperation with SO-ARM100
# File: configs/teleop_so_arm100.pbtxt

general {
  mode: MODE_TELEOPERATE
  robot_type: "SO-ARM100"
  name: "leader_follower_teleop"
  id: "joshua-teleop-001"
}

robot {
  # Leader arm (input device)
  actions {
    node {
      node_name: "leader_arm"
      node_id: 1
      node_type: CPP
      qos {
        reliability: RELIABLE
        durability: VOLATILE
        history: KEEP_LAST
        depth: 10
        liveliness: AUTOMATIC
      }
      publishers {
        data_type: JOINT_STATE
        topic_name: "/leader/joint_states"
        publish_rate_hz: 50.0
      }
    }
    action_type: ACTION_LEADER
    sts3215_config {
      comm {
        serial {
          port: "/dev/ttyACM0"
          baudrate: 1000000
        }
      }
      motor_ids: [1, 2, 3, 4, 5, 6]
      position_min: 0
      position_max: 4095
      velocity: 0
      acceleration: 0
    }
  }

  # Follower arm (actuated output)
  actions {
    node {
      node_name: "follower_arm"
      node_id: 2
      node_type: CPP
      qos {
        reliability: RELIABLE
        durability: VOLATILE
        history: KEEP_LAST
        depth: 10
        liveliness: AUTOMATIC
      }
      publishers {
        data_type: JOINT_STATE
        topic_name: "/follower/joint_states"
        publish_rate_hz: 50.0
      }
      subscriptions {
        data_type: JOINT_STATE
        topic_name: "/leader/joint_states"
      }
    }
    action_type: ACTION_FOLLOWER
    sts3215_config {
      comm {
        serial {
          port: "/dev/ttyACM1"
          baudrate: 1000000
        }
      }
      motor_ids: [1, 2, 3, 4, 5, 6]
      position_min: 0
      position_max: 4095
      velocity: 1000
      acceleration: 200
    }
  }

  # Top-mounted camera
  perceptions {
    node {
      node_name: "camera_top"
      node_id: 3
      node_type: CPP
      qos {
        reliability: BEST_EFFORT
        durability: VOLATILE
        history: KEEP_LAST
        depth: 1
        liveliness: AUTOMATIC
      }
      publishers {
        data_type: IMAGE
        topic_name: "/camera/top/image_raw"
        publish_rate_hz: 30.0
      }
    }
    perception_type: PERCEPTION_CAMERA
    camera_config {
      device_id: 0
      width: 640
      height: 480
      fps: 30
      pixel_format: "MJPG"
      brightness: 128
      contrast: 128
      saturation: 128
      exposure: -6
    }
  }
}

ai {
  data_store {
    format: FORMAT_HUGGINGFACE
    storage: STORAGE_LOCAL
    dataset_name: "so_arm100_teleop_demos"
    local_path: "/data/datasets/so_arm100_teleop"
  }
}

Configuration Presets Reference

JOSHUA ships with over 25 pre-built configuration presets covering common robot setups, training scenarios, and simulation environments. Presets are stored in the configs/ directory and can be used directly or as templates for custom configurations.

To run a preset configuration:

# Run with a preset configuration
joshua --config configs/teleop_so_arm100.pbtxt

# Run with verbose logging for debugging
joshua --config configs/test_mock_hardware.pbtxt --log-level DEBUG

# Validate a configuration without launching
joshua --config configs/your_custom.pbtxt --validate-only