Connecting to sources…

How to build Papaya Pathfinder: the whole process

86 steps to build Papaya Pathfinder, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the offic…

Papaya Pathfinder is a family of small ESP32-based remote-controlled wheeled rovers. The repository provides fully 3D-printable mechanical designs, STEP CAD files, component lists, wiring diagrams, and firmware documentation for Papaya Pathfinder and Papaya Pathfinder Mini.

Buy parts

  • Source the rover components

    Select a rover variant for its size, motors, and power requirements, then obtain the ESP32 controller, BTS7960 motor drivers, GA25 gear motors, MS24 servos, 3S LiPo battery, and two UBECs. The ELRS receiver is required only when running firmware-elrs.

  • Prepare ESP32 Camera for WiFi

    Use an ESP32 with a camera, either ESP32-CAM or ESP32-S3-CAM, when running `firmware-wifi`.

  • Prepare ELRS Receiver

    An ELRS receiver is required only when running `firmware-elrs`.

  • Prepare Six N20 Gear Motors

    Prepare 6 N20 DC gear motors.

  • Prepare a 2S LiPo Battery

    Use a LiPo 2S power supply.

  • Prepare the 5V Step-Down Regulator

    Prepare one 5V DC-DC step-down regulator for the ESP32 or ESP32-CAM.

  • Prepare the 6V Step-Down Regulator

    Prepare one 6V DC-DC step-down regulator for the N20 motors.

Print and make

  • Print the mechanical parts

    All mechanical parts for the selected variant are fully 3D-printable, with models available in that variant's 3d-models/ directory. Print the models in that directory to make the mechanical parts.

  • Download All Rover STL Files

    Obtain all STL files for the rover from `pathfinder-mini/3d-models/`.

  • Obtain the Complete STEP Design

    The complete mechanical design is also provided as `pathfinder-mini/cad/papaya-pathfinder-mini.step` in STEP format.

  • Choose Structural and Tire Materials

    Print the structural parts with PETG or PLA and the tires with TPU.

  • Print Six TPU Tires

    Print 6 `tire.stl` tires using TPU.

Assemble

  • Confirm native application files

    Confirm that the native files are in `android/app/src/main`. The old GLB unused by the game is excluded from the APK, while the rover FBX is included.

  • Assemble with M3 Screws and Nuts

    All parts are designed to be assembled with M3 screws and nuts.

Software

  • Install dependencies

    Use Node.js 22.12 or later and npm, then install dependencies from the project root.

  • Start the development server

    Run the development server, then open the URL printed by Vite in the terminal. Code changes are reflected during development.

  • Access the game from a phone

    Connect the phone and computer to the same Wi-Fi network, then open the computer's local IP address with the port shown by Vite in the phone browser, for example `http://192.168.1.50:5173`. Your computer's firewall must allow the connection.

  • Build the web version

    Run the build command. The compiled output is generated in `dist/`, including `index.html`, `assets/`, `papaya-pathfinder.fbx`, and `model.glb` copied from `public/`.

  • Preview the local build

    Preview the built web version locally.

  • Install JDK 17 or later

    Besides the web dependencies, install JDK 17 or later so that `java`, `javac`, `jar`, and `keytool` are available. The APK has been built using JDK 21.

  • Install Android SDK platform and build tools

    Install Android SDK Platform 35 and Android SDK Build Tools, with version 36.1.0 having been used. These SDK components can be installed through Android Studio's SDK Manager, and Android Studio does not need to be open to generate the APK.

  • Set the SDK path environment variable

    The build script automatically looks for the SDK in `~/Library/Android/sdk` on macOS and `~/Android/Sdk` on Linux. If your SDK is installed elsewhere, set `ANDROID_HOME` or `ANDROID_SDK_ROOT`, for example on macOS with `export ANDROID_HOME="$HOME/Library/Android/sdk"`.

  • Select a JDK with JAVA_HOME

    Set `JAVA_HOME` to the installation directory of the JDK to select a particular JDK.

  • Select an installed build tools version

    You can select an installed Build Tools version with `ANDROID_BUILD_TOOLS`, for example setting it to 36.1.0. These packaging instructions apply to macOS and Linux.

  • Generate the APK from the project root
  • Locate the generated APK output file

    The output file is `artifacts/papaya-pathfinder-debug.apk`.

  • Build a new Android APK

    Run the Android APK build command after changing the game.

  • Install the new APK over the old version

    Install the new APK over the previous version without uninstalling the application.

  • Keep the development signing key

    Keep `android/build/debug.keystore`; updates must use the same key to install over the previous version and retain its data. Deleting the entire `android/build/` directory also deletes this key.

  • Build the development APK

    Run the packaging command in the project directory to generate an installer that includes the game and works without a server or connection.

  • Locate the generated APK

    Find the generated development APK at `artifacts/papaya-pathfinder-debug.apk`.

  • Install the build toolchain

    Install Node, JDK 17 or newer, Android SDK Platform 35, and Android SDK Build Tools.

  • Configure Android tool paths

    The script detects the SDK in usual macOS and Linux locations; it also accepts `ANDROID_HOME` or `ANDROID_SDK_ROOT`, `JAVA_HOME`, and `ANDROID_BUILD_TOOLS`.

  • Preserve the development signing key

    Keep the development key at `android/build/debug.keystore`. It is excluded from Git so new builds can be installed over earlier builds while preserving progress.

  • Choose the communication firmware

    firmware-wifi provides WiFi-based control and an HTTP API for movement commands, with support for the Python desktop controller or Android app. firmware-elrs provides control through ExpressLRS.

  • Select the WiFi Firmware

    `firmware-wifi` provides WiFi-based control, movement commands through an HTTP API, and live video streaming over WiFi.

  • Select the ExpressLRS Firmware

    `firmware-elrs` provides control through ExpressLRS (ELRS).

  • Choose the Python Desktop Controller

    The Python desktop controller displays the live video stream and sends gamepad-based control commands to the rover via HTTP.

  • Choose the Android Mobile App

    The Android app displays the live video stream and enables rover control with a gamepad, providing the same driving experience as the desktop controller.

Calibrate and test

  • Validate the packaged APK

    Packaging automatically validates Java/DEX compilation, APK signing, and alignment.

  • Check the app on a real device

    Check the application's functionality and performance on a real device.

Use it

  • Publish the web version

    Copy the entire contents of `dist/` to a static hosting service and serve it from the root of a domain or subdomain. The current configuration uses absolute paths such as `/assets/` and `/papaya-pathfinder.fbx`.

  • Serve all required game files

    Do not copy only `index.html`; the JavaScript and model files are also required. Serve the game over HTTP or HTTPS, because opening the HTML directly using `file://` may prevent modules and resources from loading.

  • Copy the APK to your phone and install

    Copy this file to your phone and open it to install the application. Android may ask you to allow installations from the file manager or browser you use. The app requires Android 8 or later and a WebView with WebGL 2 support.

  • Choose a course and start racing

    Choose one of six courses and use **Correr** to race the red rover.

  • Wait for the three-second countdown

    Starting a race places both rovers on the grid and begins a three-second countdown.

  • Review course distance and time limit

    Before starting, the selector shows the course distance, and the panel shows its checkpoint count and time limit.

  • Drive through checkpoints in order

    Drive through the course's numbered checkpoints in order; the last one is marked **META**.

  • Follow the next checkpoint

    Your next checkpoint is highlighted in gold, and the course appears on the map. The race panel shows elapsed time and the opponent's checkpoint count.

  • Finish the lap and record your time

    If the red rover finishes first, you can still finish your lap and record your time. Personal bests are saved separately for each course.

  • Cancel or repeat the race

    Use **Abandonar** to cancel or **Repetir** after finishing. The red rover resumes its patrol when the race ends.

  • Open the orbital globe

    Press M or tap PLANETA to open an orbital globe view.

  • Rotate the globe

    Drag to rotate freely, including across the poles. Drag sensitivity follows the visible ground scale at the current altitude and stops when released.

  • Zoom the globe

    Scroll or use +/− to approach within eight metres of the surface.

  • Observe terrain loading

    Nearby terrain begins loading before it is visible. Between 1,800 and 100 metres, the orbital globe gradually blends into the streamed terrain, rocks, structures, and rover.

  • Descend to the destination

    Choose Descender aquí to place the rover at the center of the view. Only nearby destination terrain is loaded; the green marker shows the rover and the gold marker shows the landing region.

  • Return to the rover

    Choose Volver al rover, press M, or press Escape to return without moving. The game pauses while viewing the globe, and descending to a new location cancels the current race.

  • Use upward boost

    The upward boost gives a hop of about 1.8 m from rest on level ground. There is no cooldown; each press adds momentum along the rover’s local up axis, including in mid-air.

  • Control airborne thrusters

    In the air, W/S or the left touch stick fires forward/reverse thrusters, A/D rotates the rover about its own axis, and the arrow keys or right touch stick fire lateral thrusters.

  • Brake horizontal drift

    Press Space/Freno to brake horizontal drift. Exhaust swivels opposite the requested thrust and stays visible while thrust is applied.

  • Hold G for Continuous Thrust

    Hold G, or toggle “Rápido” on touchscreens, for continuous high-power thrust; W + G provides up to 1,800 m/s² of forward acceleration, while reverse or lateral acceleration reaches 60 m/s².

  • Control Ascent and Impulse

    Press Z / Subir for stabilized radial ascent, and use F for a short impulse along the rover’s inclination. In the air, combine G with W/S or the Left/Right arrow keys to switch to directional flight.

  • Hold Altitude and Descend

    After powered flight begins, releasing vertical input holds the current altitude; press X to descend, and actual ground contact restores normal driving. G never commands ascent, and releasing W while G remains held coasts without switching to lift.

  • Use Fast Planetary Flight

    Forward boost eases toward a 6,000 m/s cruise speed, with the speed reduced near the ground. Fast flight uses coarser terrain tiles and larger local frames, restoring detailed terrain collision when approaching the surface.

  • Check Desktop Rendering Limits

    Desktop rendering is capped at 60 FPS during play and 30 FPS while idle, and hidden tabs pause simulation and rendering. The desktop Retina framebuffer is capped at 1.5× pixel ratio and three million pixels, while retaining HDR, contact shading, and 2× MSAA.

  • Verify Airborne Terrain Collision

    Airborne movement sweeps the chassis and six tyres along the full 3D path against terrain and rocks. During low passes below 80 m of clearance, excessive horizontal speed is progressively shed, and impacts dissipate flight velocity.

  • Use Ground Wheel Assistance

    Forward driving automatically uses wheel-thruster assistance, with a normal cruising speed of 8 m/s; races use a shared 7 m/s limit for the player and rival. Braking or coasting cuts the assistance, and ordinary ground driving has no thruster animation.

  • Lift, Travel, and Descend

    Press Z to lift the rover from the surface, W/S to travel, A/D to rotate, and X to descend.

  • Fast Planetary Travel

    Hold W + G for fast planetary travel at the current altitude. G controls speed independently, and hold Z only when you want to climb.

  • Hold Altitude While Coasting

    When vertical thrust is released, the flight controller holds the current altitude, so coasting does not send the rover upward.

  • Adjust the Pitch Angle

    Hold Up arrow to pitch the nose down up to 85°, or Down arrow to raise it. The selected pitch remains after release.

  • Strafe and Steer

    Left/Right arrows provide lateral thrust. A/D turns with gentle banking, and boosted steering remains responsive at high speed.

  • Brake and Level

    Press Space to brake and level the rover, or X to level it for a controlled landing. Releasing thrust smoothly brakes vertical motion into a hover.

  • High-Altitude Scene and Camera

    As altitude increases, the game reveals the curved globe, transitions to a dark sky and stars, and adjusts the camera to show the planet below. Mouse dragging still lets you look around.

  • Distant Detail and Descent Recovery

    In high flight, distant surface detail uses a coarse spherical LOD, while detailed sectors and contact shading sleep and return during descent. There is no orbital-view switch or teleport in this flight path.

  • Approach and Land

    Hold X to approach and land at any location. Descent slows near the surface, impacts dissipate flight energy, and actual tyre contact restores normal rover driving and rocker-bogie suspension.

  • Use the Separate Inspection View

    The optional M/PLANETA inspection view remains separate from the continuous flight view.

  • Explore planetary regions

    After flying away from the landing region, the mission panel shows the current region and guides you to nearby sites containing rocks, abandoned probes, geological stations, and expedition beacons.

  • Register an exploration discovery

    Stop within seven metres of a nearby site and hold E / Escanear for 2.5 seconds to register a discovery. Discoveries are saved in the browser or Android WebView's local storage.

  • Drive with the Left Stick

    On a touch device, use the proportional left stick for forward movement, reverse, and steering. Small deflections give gentler input, and the stick center has a dead zone.

  • Control Flight with the Second Stick

    In flight, a second stick appears for controlling nose pitch and lateral thrust.

Documents