An autonomous mobile robot that retrieves, stores, and throws balls to humans or other robots. Built around a 4-wheel swerve drive rover with onboard perception and a precision ball-throwing mechanism.
The throwing subsystem is operational. It accepts a target state (position and time) and executes a throw to hit that target. This mechanism was originally developed as part of the Jugglebot project and is now the foundation for the full Ball Butler system.
- Throwing to arbitrary commanded target states (position, time)
- Ball hopper with manual reloading (of the hopper - BB can automatically reload itself)
- Integration with Jugglebot as a ball-serving system
The full Ball Butler is a standalone mobile robot comprising:
- Rover platform — 4-wheel swerve drive (8 DoF) for omnidirectional movement over sidewalks, curb cuts, grass, and gravel. Suspended wheels for terrain compliance.
- Throwing mechanism — evolved from the current thrower, mounted atop the rover.
- Ball pickup — a mostly-mechanical system to collect balls from the ground and feed them into onboard storage.
- Ball storage — onboard hopper carrying 5-10 balls (~70 mm, ~80 g each).
- Navigation — LiDAR and/or depth cameras for obstacle avoidance and path planning, teleoperated via a handheld controller with autonomous path smoothing.
| Parameter | Target |
|---|---|
| All-up mass | 25-35 kg |
| Top speed | 1.5-2 m/s |
| Obstacle clearance | Up to ~5-8 cm |
| Runtime | 1-2 hours |
| Drive motors | Hoverboard hub motors (x4) |
| Steering motors | BLDC with belt reduction (x4) |
| Motor controllers | moteus r4.11 (drive), moteus c1 (steering) |
| Compute | Jetson Orin Nano/NX |
The rover platform is being developed simulation-first in MuJoCo before committing to hardware. The full simulation plan is documented in BB_rover_mujoco_plan.md and covers six phases:
Environment & tooling setup— MuJoCo scene, control loop, input handling (done)Rigid chassis + swerve modules— driveable swerve drive on flat ground, inverse kinematics, teleoperation (done)Suspension— spring-damper prismatic joints modelling the splined-shaft suspension concept, ride quality tuning (done)Terrain & obstacle traversal— heightfield terrains (concrete, cracked sidewalk, curb cuts, grass, gravel), multi-terrain course, slope/tip-over analysis (done)- Control stack — motor controller modelling, swerve drive controller, velocity frame toggle (global/body), path following, odometry & state estimation
- Power & actuator analysis — torque/speed/power logging, battery sizing, motor sizing validation
- Disturbance & robustness testing — external forces, actuator failures, payload shift from throwing
The simulation will later extend to include Ball Butler integration (throwing disturbance on the rover), ball collection, hopper dynamics, and a simulated perception stack.
BallButler/
├── ball_butler_main/ # Thrower firmware (Arduino/Teensy)
│ ├── ball_butler_main.ino # Main sketch — state machine orchestration
│ ├── StateMachine.cpp/.h # State machine (BOOT → IDLE → THROWING → RELOADING)
│ ├── CanInterface.cpp/.h # CAN-FD communication with ODrives
│ ├── PitchAxis.cpp/.h # Pitch axis ODrive position control
│ ├── YawAxis.cpp/.h # Yaw axis brushed DC motor control
│ ├── HandPathPlanner.cpp/.h # Throw trajectory planning
│ ├── HandTrajectoryStreamer.h # Trajectory streaming to actuators
│ ├── Proprioception.cpp/.h # Central axis state repository
│ ├── Trajectory.h / TrajFrame.h # Trajectory and frame data structures
│ ├── RobotState.h # Robot state definitions
│ ├── BallButlerConfig.h # Thrower configuration parameters
│ ├── hardware_config.h # Auto-generated hardware constants (from Jugglebot config)
│ └── protocol_config.h # CAN protocol configuration
│
├── ball_butler_circuit_diagram/ # KiCad project — main electronics schematic
│ ├── *.kicad_sch # Schematic sheets (main + Power and CAN)
│ ├── *.kicad_pcb # PCB layout
│ ├── Ball_Butler_*.kicad_sym # Custom symbol libraries
│ └── Ball Butler Schematic*.pdf # Exported schematic PDFs
│
├── hand_sensor_pcb_rail/ # KiCad project — hand sensor PCB rail
│ ├── *.kicad_sch / *.kicad_pcb # Schematic and PCB layout
│ └── Production/ # Gerber files for manufacturing
│
├── zTesting/ # Test scripts and experiments
│ ├── ball_butler_spacemouse.py # SpaceMouse teleoperation
│ ├── simulating_throw_types.py # Throw trajectory simulation
│ ├── yaw_inverse_kinematics.py # Yaw axis IK exploration
│ ├── calibrating_yaw_axis_with_mocap/ # MoCap-based yaw calibration
│ ├── sensored_hand_testing/ # Hand sensor testing
│ ├── throw_testing/ # Throw characterisation
│ └── ... # Other hardware tests
│
├── BB_rover_mujoco_plan.md # MuJoCo simulation plan for the rover platform
├── sim/ # MuJoCo rover simulation (Phase 3 complete)
│ ├── main.py # Simulation entry point — control loop, global-frame velocity, terrain support
│ ├── config.py # Simulation parameters
│ ├── input_handler.py # Keyboard/gamepad → velocity commands
│ ├── data_logger.py # CSV data logging
│ ├── models/ # MJCF model files
│ │ ├── rover.xml # Shared rover body, actuators, sensors, contacts (included by scenes)
│ │ ├── scene.xml # Flat ground + Phase 2 test terrain (bumps, curb-cut ramp)
│ │ └── scene_terrain.xml # Multi-terrain course + slope analysis area (Phase 3)
│ ├── controllers/ # Control algorithms
│ │ └── swerve_ik.py # Swerve drive inverse kinematics (4-wheel, with 180° flip optimisation)
│ ├── utils/ # Shared utilities (transforms, model helpers, sim runner, constants)
│ ├── terrains/ # Heightfield terrain generation
│ │ └── terrain_generator.py # Procedural grass/gravel heightfield generation
│ ├── tests/ # Simulation test scenarios (exit 1 on failure)
│ │ ├── test_suspension.py # Phase 2 headless suspension validation
│ │ └── test_terrain.py # Phase 3 terrain course + slope/tip-over validation
│ ├── logs/ # CSV data logs (gitignored)
│ └── requirements.txt # Python dependencies
│
├── bb_pitch_odrive_micro_config.json # ODrive configuration for the pitch axis
└── .gitignore
As the rover and full system are built out, expect these directories to appear:
BallButler/
├── rover/ # Rover platform (planned)
│ ├── firmware/ # Motor controller firmware (moteus)
│ ├── config/ # Rover hardware configuration
│ └── cad/ # Mechanical design exports
│
├── navigation/ # Navigation & perception (planned)
│ ├── local_planner/ # Obstacle avoidance
│ └── odometry/ # Wheel odometry + IMU fusion
│
└── config/ # Shared configuration (planned)
- Jugglebot — the robot that Ball Butler (v0) was originally built to serve. Shared configuration files (e.g.
hardware_config.h) are generated by Jugglebot and consumed by this repo.