If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ob-f/OpenBot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ob-f/OpenBot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ob-f/OpenBot.

What it runs against: a local clone of ob-f/OpenBot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ob-f/OpenBot | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ob-f/OpenBot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ob-f/OpenBot.git
#   cd OpenBot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ob-f/OpenBot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ob-f/OpenBot(\\.git)?\\b" \\
  && ok "origin remote is ob-f/OpenBot" \\
  || miss "origin remote is not ob-f/OpenBot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "android/controller/src/main/java/org/openbot/controller/ControllerActivity.kt" \\
  && ok "android/controller/src/main/java/org/openbot/controller/ControllerActivity.kt" \\
  || miss "missing critical file: android/controller/src/main/java/org/openbot/controller/ControllerActivity.kt"
test -f "android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt" \\
  && ok "android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt" \\
  || miss "missing critical file: android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt"
test -f "android/controller/src/main/java/org/openbot/controller/NetworkServiceConnection.kt" \\
  && ok "android/controller/src/main/java/org/openbot/controller/NetworkServiceConnection.kt" \\
  || miss "missing critical file: android/controller/src/main/java/org/openbot/controller/NetworkServiceConnection.kt"
test -f "android/controller/src/main/java/org/openbot/controller/NearbyConnection.kt" \\
  && ok "android/controller/src/main/java/org/openbot/controller/NearbyConnection.kt" \\
  || miss "missing critical file: android/controller/src/main/java/org/openbot/controller/NearbyConnection.kt"
test -f "android/controller/src/main/java/org/openbot/controller/PhoneSensorToDualDriveConverter.kt" \\
  && ok "android/controller/src/main/java/org/openbot/controller/PhoneSensorToDualDriveConverter.kt" \\
  || miss "missing critical file: android/controller/src/main/java/org/openbot/controller/PhoneSensorToDualDriveConverter.kt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ob-f/OpenBot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

OpenBot transforms affordable smartphones into autonomous robot brains for a ~$50 robot body by running an Android software stack that powers real-time computer vision tasks (person following, obstacle avoidance, autonomous navigation). It bridges the gap between consumer hardware and robotics by leveraging the processing power, sensors, and cameras already in mobile phones rather than requiring expensive dedicated robotic controllers. Monorepo structure: android/ contains the core Android apps (controller app, comlib communication library, OpenBot main app); body/ holds CAD models and assembly guides; firmware/ contains Arduino code for the motor controller; policy/ has Python notebooks and training scripts; open-code/ hosts a web-based Playground. Android app hierarchy includes build.gradle for dependency management, Google services config, and ProGuard rules for release builds.

Roboticists and makers building low-cost autonomous vehicles; educators teaching robotics and AI with budget constraints; developers implementing computer vision and reinforcement learning on mobile devices; contributors working on TensorFlow Lite inference, Android camera pipelines, or PyTorch policy training.

Actively maintained and production-viable: 890K+ Swift, 714K+ Java lines of code across android/, body/, firmware/, and policy/ modules; comprehensive CI/CD via GitHub Actions (gradle.yml, nodejs-server.yml, python.yml); multilingual documentation (English, Chinese, German, French, Spanish, Korean); strong community signals (stars, forks, downloads badges visible). Verdict: actively developed with professional-grade tooling.

Dependency on Firebase (google-services.json, crashlytics) and Google Play Services (location_version, nearby_version) introduces proprietary lock-in; Kotlin 1.8.0, Gradle 7.4.2 are not bleeding-edge but stable; no explicit test directory visible in top 60 files, raising test coverage concerns; multi-language support and 6 translated READMEs suggest maintenance overhead. Check recent commit history for active development cadence.

Active CI/CD pipelines: gradle.yml (Android builds), nodejs-server.yml (server), python.yml (policy training), frontend.yml (web UI); GPT-powered automation (gpt-translate.yml, gpt_review.yml) for docs and code review; issue/PR automation (assigned-issues-inprogress.yml, opened-issues-todo.yml); recent releases tracked in releases.yml. The project is integrating AI-assisted workflows while maintaining multi-language parity.

Clone and build the Android app:

git clone https://github.com/ob-f/OpenBot.git
cd OpenBot/android
./gradlew build

Then:

1. Flash Arduino firmware to the robot body (firmware/ directory)
2. Install the Android app on a smartphone
3. Connect via Bluetooth to the robot's motor controller
4. Read android/README.md for detailed setup and android/controller/README.md for controller configuration.

Daily commands: Build and run the Android app:

cd OpenBot/android
./gradlew assembleDebug  # Build APK
./gradlew installDebug   # Install on connected device

Or use Android Studio: File > Open > android/ and click Build → Run. For Python policy training, see policy/README.md. For the Node.js server: cd open-code && npm install && npm start.

• android/controller/src/main/java/org/openbot/controller/ControllerActivity.kt — Main entry point for the Android controller app; orchestrates connection management, UI rendering, and drive command dispatch.
• android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt — Core state management for drive commands; translates sensor input and UI events into motor control signals sent to the robot.
• android/controller/src/main/java/org/openbot/controller/NetworkServiceConnection.kt — Handles network communication with the robot via WebRTC and socket protocols; critical for real-time command delivery.
• android/controller/src/main/java/org/openbot/controller/NearbyConnection.kt — Manages local Bluetooth/WiFi peer discovery and connection using Google Nearby; fallback to network-based control.
• android/controller/src/main/java/org/openbot/controller/PhoneSensorToDualDriveConverter.kt — Converts accelerometer and gyroscope sensor data into dual-motor drive signals; enables tilt-based robot control.
• android/controller/build.gradle — Defines Android app dependencies (Kotlin, WebRTC, Google Nearby, Firebase); build configuration for controller module.
• android/build.gradle — Root build configuration with version pins (Kotlin 1.8, WebRTC 1.0.32006, Gradle 7.4.2); coordinated across all Android modules.

Add a New Drive Control Mode

1. Create a new custom control layout class extending the pattern in DriveModeSlidersLayout.kt or DriveModeTiltLayout.kt. (android/controller/src/main/java/org/openbot/controller/customComponents/)
2. Implement sensor-to-drive-command conversion logic (if needed) in a new class following PhoneSensorToDualDriveConverter.kt pattern. (android/controller/src/main/java/org/openbot/controller/PhoneSensorToDualDriveConverter.kt)
3. Register the new mode in ScreenSelector.kt to make it accessible from the UI mode switcher. (android/controller/src/main/java/org/openbot/controller/ScreenSelector.kt)
4. Wire drive commands through DriveCommandReducer.kt to ensure the new mode's output is properly serialized and sent to the robot. (android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt)

Add a New Connection Method

1. Create a new class implementing ILocalConnection.kt interface with connect(), disconnect(), send(), and setDataListener() methods. (android/controller/src/main/java/org/openbot/controller/ILocalConnection.kt)
2. Register the new connection in ConnectionSelector.kt to make it selectable and manage lifecycle. (android/controller/src/main/java/org/openbot/controller/ConnectionSelector.kt)
3. Emit connection status events via StatusEventBus.kt when connection state changes (connecting, connected, disconnected, error). (android/controller/src/main/java/org/openbot/controller/StatusEventBus.kt)
4. Add dependency declarations in android/controller/build.gradle if the new method requires external libraries (e.g., Bluetooth, WiFi Direct). (android/controller/build.gradle)

Add a New Telemetry Indicator or Status Display

1. Create a custom view component in the customComponents folder (e.g., BatteryIndicator.kt) extending the pattern of existing indicators. (android/controller/src/main/java/org/openbot/controller/customComponents/)
2. Define a new status event type in StatusEventBus.kt to publish telemetry updates. (android/controller/src/main/java/org/openbot/controller/StatusEventBus.kt)
3. Update BotDataListener.kt callback interface if the telemetry data structure changes. (android/controller/src/main/java/org/openbot/controller/BotDataListener.kt)
4. Wire the new indicator into ControllerActivity.kt lifecycle and subscribe to telemetry events from the active connection. (android/controller/src/main/java/org/openbot/controller/ControllerActivity.kt)

Add a New UI Custom Component

1. Create a new Kotlin class in customComponents folder extending View or ViewGroup; implement the desired interactive behavior. (android/controller/src/main/java/org/openbot/controller/customComponents/)
2. If the component affects drive commands, wire it into DriveCommandReducer.kt as a new event source. (android/controller/src/main/java/org/openbot/controller/DriveCommandReducer.kt)
3. Add the component to the appropriate layout (MainFrameLayout.kt, BotSetupControlsLayout.kt, DriveModeSlidersLayout.kt, etc.) in ScreenSelector.kt or the relevant parent layout. (android/controller/src/main/java/org/openbot/controller/customComponents/MainFrameLayout.kt)

• Kotlin + Android Framework — Leverages smartphone OS for hardware access (camera, sensors, WiFi), UI framework, and lifecycle management; targets billions of Android devices worldwide.
• WebRTC (v1.0.32006) — Low-latency peer-to-peer

Firebase requirement: google-services.json hardcoded in android/controller/ means you must configure Firebase credentials or disable certain telemetry features. WebRTC version pinning: ext.webrtc_version = 1.0.32006 is specific; upgrading may break video streaming. Arduino firmware dependency: Android app and firmware must use matching communication protocol versions (check firmware/README for serial protocol spec). Multi-language overhead: 6 translated CONTRIBUTING.md and README files require keeping docs in sync; use GPT workflows but verify quality. No visible test directory: Limited visibility into test infrastructure; check android/comlib/build.gradle and controller/build.gradle for test dependencies (may use espresso or mockito).

• TensorFlow Lite (TFLite) — OpenBot relies on TFLite for running neural networks (person detection, obstacle avoidance) directly on the smartphone without cloud offloading; core to real-time autonomous capability.
• WebRTC (Web Real-Time Communication) — Enables low-latency video streaming from robot camera to controller app and remote web interface; ext.webrtc_version = 1.0.32006 is pinned because protocol changes break connectivity.
• Reinforcement Learning (Policy Gradient / DQN) — policy/ module trains neural network driving policies using RL; OpenBot's autonomous navigation relies on learning reward-driven behavior rather than handcoded rules.
• Bluetooth Low Energy (BLE) — Communication protocol between smartphone (main controller) and Arduino firmware on robot body; ext.nearby_version = 18.0.2 handles BLE scanning and pairing.
• Mobile Computer Vision Pipeline — Real-time processing of smartphone camera frames for person detection, lane following, and obstacle avoidance; requires careful frame rate / latency / battery trade-offs absent in desktop CV.
• Android Native Bridge (JNI/NDK) — Performance-critical vision and motor control code often uses C++ via Android NDK; android/comlib likely uses JNI for Bluetooth/WebRTC native calls.
• Monorepo & Multi-platform CI/CD — OpenBot's .github/workflows/ orchestrate builds for Android (gradle.yml), Python (python.yml), Node.js (nodejs-server.yml), and firmware—illustrating how to manage cross-platform robotics projects with unified versioning.

• donkeycar/donkeycar — Parallel DIY autonomous vehicle platform using Raspberry Pi brain; shares reinforcement learning and computer vision goals but uses different hardware (Pi instead of smartphone).
• tinyML/tinyML-hardware — TensorFlow Lite optimization and deployment for embedded/mobile devices; directly relevant to OpenBot's on-device ML inference pipeline.
• tensorflow/tensorflow — Core ML framework used by OpenBot's policy/ training scripts and TensorFlow Lite model export for robot inference.
• NVIDIA/jetbot — NVIDIA's Jetson-based robot platform; alternative approach to affordable autonomy (GPU-powered board vs. smartphone brain).
• ros-drivers/openni_camera — ROS drivers for depth camera integration; relevant if adding 3D vision sensors to OpenBot body or Gazebo simulation.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add instrumented Android tests for controller module communication layers

The android/controller/src/androidTest directory only contains ExampleInstrumentedTest.kt. Given that the controller module handles critical BotDataListener, ILocalConnection, and IDataReceived interfaces for robot communication, there's a significant gap in testing the actual data flow between smartphone controller and robot. This is high-value because communication failures directly impact robot functionality.

• [ ] Create androidTest/java/org/openbot/controller/BotDataListenerTest.kt to test data reception and callbacks
• [ ] Create androidTest/java/org/openbot/controller/LocalConnectionTest.kt to test ILocalConnection implementations (Bluetooth, USB, WebRTC)
• [ ] Create androidTest/java/org/openbot/controller/DriveCommandReducerTest.kt to verify command state transitions match expected robot behavior
• [ ] Add assertions for connection lifecycle (connect → send commands → disconnect)
• [ ] Update android/controller/README.md with testing instructions

Implement Python test coverage for server-side robotics workloads

The .github/workflows/python.yml exists but there's no visible python/ directory in the file structure with test configurations. Given the project description mentions 'advanced robotics workloads such as person following and real-time autonomous navigation', there's likely Python code for vision processing and AI models that lacks CI test coverage. This prevents regressions in core autonomous features.

• [ ] Identify the location of Python robotics code (person following, navigation models)
• [ ] Create python/tests/ directory structure with init.py files
• [ ] Add pytest.ini and conftest.py for test configuration
• [ ] Create tests/test_person_following.py with mock vision pipeline tests
• [ ] Create tests/test_navigation.py for autonomous navigation logic
• [ ] Update .github/workflows/python.yml to run pytest with coverage reporting and fail on <80% threshold

Add localized CONTRIBUTING guide validation workflow

The repo has CONTRIBUTING guides in 6 languages (CONTRIBUTING.md, CONTRIBUTING.de-DE.md, CONTRIBUTING.es-ES.md, CONTRIBUTING.fr-FR.md, CONTRIBUTING.ko-KR.md, CONTRIBUTING.zh-CN.md) but no CI workflow to ensure they stay in sync or are actually valid. The gpt-translate.yml workflow exists but there's no validation that translated files maintain key sections. This prevents outdated contribution guidance in non-English locales.

• [ ] Create .github/workflows/contributing-validation.yml GitHub Action
• [ ] Add validation logic to check all CONTRIBUTING.*.md files contain required sections: [Setup, Development, Testing, PR Guidelines]
• [ ] Add a check that all localized CONTRIBUTING files reference the same version of build tools from build.gradle
• [ ] Run validation on PR to any CONTRIBUTING.* file to ensure consistency
• [ ] Document expected sections in CONTRIBUTING.md itself

• Add unit tests for android/comlib communication library: create android/comlib/src/test/java/ with test suites for Bluetooth message serialization and WebRTC connection lifecycle, since no test files appear in the top 60.
• Improve Android README documentation: android/README.md lacks detailed troubleshooting for common build errors (missing NDK, API level mismatches); add a FAQ section with gradle.yml error mappings.
• Create a Python linting/type-checking pipeline: policy/ contains 153K lines of Python with Jupyter notebooks; add a GitHub Action (similar to gradle.yml, nodejs-server.yml) that runs mypy and black to catch policy training bugs early.

The OpenBot Android project has moderate security concerns primarily related to outdated dependencies and potential credential exposure. The most critical issues are the use of outdated Kotlin (1.8.0) and Gradle (7.4.2) versions, which may contain known vulnerabilities. The presence of google-services.json in version control poses a credential exposure risk. While the project structure appears well-organized with GitHub workflows and documentation, dependency management needs immediate attention. Overall security posture is below recommended standards for a robotics

• High · Outdated Gradle Build Tool — build.gradle - classpath 'com.android.tools.build:gradle:7.4.2'. The project uses Gradle 7.4.2, which may contain known vulnerabilities. Gradle 7.4.2 was released in early 2023 and newer versions with security patches are available. This can expose the build process to supply chain attacks. Fix: Update to the latest stable Gradle version (8.x or higher) and AGP (Android Gradle Plugin) to receive security patches and improvements.
• High · Outdated Kotlin Version — build.gradle - ext.kotlin_version = '1.8.0'. Kotlin 1.8.0 is outdated and may contain known security vulnerabilities. The current stable version is 2.0+. Using outdated versions increases vulnerability to known exploits. Fix: Update Kotlin to version 2.0.0 or later to benefit from security patches and latest language features.
• Medium · Deprecated JCenter Repository — build.gradle - repositories section includes jcenter(). The project includes jcenter() repository which was deprecated and shut down in May 2021. While it may be cached, relying on deprecated repositories creates maintenance issues and potential supply chain risks. Fix: Remove jcenter() from the repositories block. Ensure all dependencies are available through mavenCentral() or other active repositories.
• Medium · Potential Credentials in google-services.json — android/controller/google-services.json. The file 'android/controller/google-services.json' appears in the repository structure. This Firebase configuration file may contain sensitive API keys, project IDs, and other credentials that should not be committed to version control. Fix: Add google-services.json to .gitignore. Use environment variables or secure credential management systems (e.g., Google Secret Manager) to handle Firebase configuration in CI/CD pipelines.
• Medium · Outdated Google Play Services Dependencies — build.gradle - ext.location_version and ext.nearby_version. Google Play Services libraries (location 19.0.1, nearby 18.0.2) may be outdated and contain known vulnerabilities. These should be kept current to ensure security patches are applied. Fix: Review and update Google Play Services dependencies to their latest stable versions. Use dependency management tools to automate version checking.
• Medium · WebRTC Library Version — build.gradle - ext.webrtc_version = '1.0.32006'. WebRTC version 1.0.32006 is specified but version management for this critical component should be verified. WebRTC handles real-time media which has significant security implications. Fix: Verify the WebRTC version is up-to-date with security patches. Check release notes for any known vulnerabilities and upgrade if necessary.
• Low · Incomplete ProGuard Configuration — android/controller/proguard-rules.pro. The project includes proguard-rules.pro file, but without visibility into its content, it's unclear if proper obfuscation and security rules are applied. Inadequate ProGuard configuration can leak sensitive code patterns. Fix: Review and enhance ProGuard rules to ensure proper code obfuscation, removal of sensitive information, and protection against reverse engineering.
• Low · Truncated Build Configuration — build.gradle - applyStyle task definition. The build.gradle file appears to be truncated in the provided content ('includ' is incomplete). This may indicate the full security configuration is not visible or the file may be malformed. Fix: Ensure all build.gradle files are properly formatted and complete. Validate Gradle syntax and configuration.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.