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/hybridgroup/gobot 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.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 5 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 hybridgroup/gobot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hybridgroup/gobot.

What it runs against: a local clone of hybridgroup/gobot — 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 hybridgroup/gobot | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch release exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 150 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hybridgroup/gobot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hybridgroup/gobot.git
#   cd gobot
#
# 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 hybridgroup/gobot and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "robot.go" \\
  && ok "robot.go" \\
  || miss "missing critical file: robot.go"
test -f "adaptor.go" \\
  && ok "adaptor.go" \\
  || miss "missing critical file: adaptor.go"
test -f "driver.go" \\
  && ok "driver.go" \\
  || miss "missing critical file: driver.go"
test -f "connection.go" \\
  && ok "connection.go" \\
  || miss "missing critical file: connection.go"
test -f "api/api.go" \\
  && ok "api/api.go" \\
  || miss "missing critical file: api/api.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 150 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~120d)"
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/hybridgroup/gobot"
  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).

Gobot is a Go framework for robotics, drones, and IoT that provides unified hardware abstraction across multiple platforms (Arduino, Raspberry Pi, Beaglebone, Parrot drones, etc.). It lets developers write cross-platform embedded code in Go with a single API, handling platform-specific details through adaptors and drivers—the core strength is simultaneous multi-device coordination without vendor lock-in. Monolithic modular structure: root-level abstractions (adaptor.go, connection.go, device.go, driver.go) define the core interfaces; drivers/ subdirectory organizes driver implementations by protocol (aio/ for analog I/O, gpio/, i2c/, etc.); platforms/ folder contains platform-specific adaptors (firmware, raspi, etc.); api/ provides optional REST API and web dashboard; examples/ has runnable working code for each platform.

Go developers building physical computing projects, roboticists prototyping with Go, IoT engineers deploying to embedded Linux systems, and drone developers using Parrot or similar platforms. Users who want to avoid the low-level C/embedded language complexity while maintaining fine-grained hardware control.

Actively developed and production-ready: v2 is the current major version (go.mod shows module gobot.io/x/gobot/v2), CircleCI and AppVeyor CI pipelines are running, codecov integration is present, and comprehensive examples are maintained in examples/. The framework has stabilized enough for real deployments but is still actively adding platform support.

Moderate dependency risk: 21 direct dependencies including MQTT, serial communication, OpenCV bindings (gocv), and Bluetooth libraries—each adds platform-specific compilation complexity. Single primary maintainer pattern visible (deadprogram in CI config). Breaking changes exist (MIGRATION.md present), and platform-specific drivers (periph.io, go-gpiocdev) may lag behind hardware evolution.

The repo is on the dev branch (CircleCI config references branch/dev), recent toolchain bumped to Go 1.24.6, Dependabot active for security updates, and platform support is being maintained (periph.io and gocv versions recently updated). No major breaking changes appear imminent, but v2 API is considered stable.

git clone https://github.com/hybridgroup/gobot.git
cd gobot
git checkout release
ls examples/
env GOOS=linux GOARCH=arm GOARM=5 go build -o ./output/raspi_blink examples/raspi_blink.go

Daily commands: Gobot is a library, not a standalone app. To run examples: go run examples/raspi_blink.go (after go mod tidy). For custom projects: create module, import gobot.io/x/gobot/v2 and platform-specific packages, then go build. See README code example showing firmata.NewAdaptor() + gpio.NewLedDriver() pattern.

• robot.go — Core Robot struct that orchestrates all devices and connections—every contributor must understand the main control loop and initialization pattern
• adaptor.go — Base interface for hardware adaptors (e.g., GPIO, serial)—defines the contract that all hardware integrations must implement
• driver.go — Base interface for device drivers—establishes the pattern for adding new sensors, actuators, and peripheral support
• connection.go — Connection interface for managing communication channels—required reading for understanding device lifecycle management
• api/api.go — HTTP API server for robot command/control—essential for understanding how external systems interact with the framework
• commander.go — Command execution and event-driven architecture—core to how the framework processes user actions and device events
• go.mod — Dependency manifest with robotics/IoT libraries (Paho MQTT, gocv, serial, GPIO)—shows architectural dependencies and supported hardware ecosystems

Add a New Hardware Adaptor (e.g., UART Serial Adaptor)

1. Create adaptor package directory (drivers/uart/uart_adaptor.go)
2. Implement Adaptor interface (Connect/Disconnect/Finalize) and establish serial connection (drivers/uart/uart_adaptor.go)
3. Create connection wrapper to handle read/write operations (drivers/uart/uart_connection.go)
4. Add unit tests following existing pattern (mock, fixtures, lifecycle) (drivers/uart/uart_adaptor_test.go)
5. Register adaptor in examples and update api/api.go if exposing via REST (api/api.go)

Add a New Sensor Driver (e.g., Humidity Sensor)

1. Create driver struct embedding BaseDriver and define sensor-specific methods (drivers/aio/humidity_sensor_driver.go)
2. Implement Start/Halt lifecycle and polling loop to read from adaptor connection (drivers/aio/humidity_sensor_driver.go)
3. Add event channels (e.g., Data, Error) and callback registration (drivers/aio/humidity_sensor_driver.go)
4. Write tests with mock adaptor and verify event emission (drivers/aio/humidity_sensor_driver_test.go)
5. Add driver to robot example and document in README.md (README.md)

Add a New REST API Endpoint for Robot Control

1. Define new route handler function in api/api.go that reads robot state and devices (api/api.go)
2. Use Pat router to bind handler to HTTP method/path (e.g., POST /devices/:name/action) (api/api.go)
3. Wrap handler with auth/CORS middleware (basic_auth.go, cors.go) if required (api/api.go)
4. Marshal response to JSON and return via http.ResponseWriter (api/api.go)
5. Test endpoint with api_test.go helpers and verify robot device interaction (api/api_test.go)

Add a New Device Type (e.g., Drone with Flight Controller)

1. Create driver struct with flight-specific fields (altitude, speed, orientation) (drivers/drone/flight_controller_driver.go)
2. Implement Start/Halt and command methods (TakeOff, Land, Yaw, Pitch, Roll) (drivers/drone/flight_controller_driver.go)
3. Define adaptor interface for BLE or serial comms (inherit from existing ble_driver or uart_adaptor) (drivers/drone/flight_controller_driver.go)
4. Wire event channels for telemetry (altitude, battery, status changes) (drivers/drone/flight_controller_driver.go)
5. Write integration test using mock adaptor connection (drivers/drone/flight_controller_driver_test.go)
6. Register routes in api/api.go for flight commands (POST /drone/takeoff, etc.) (api/api.go)

• Go (Golang) — Lightweight, fast compilation, excellent concurrency primitives (goroutines, channels) for real-time sensor polling and event-driven robot control
• BLE (Bluetooth Low Energy) — Standard wireless protocol for consumer robots and IoT devices; low power consumption ideal for battery-powered hardware
• MQTT (Paho client) — Publish-subscribe messaging for distributed robot fleets and IoT network integration (e.g., cloud telemetry, multi-robot coordination)
• REST API with Pat router — Simple HTTP interface for remote robot control and dashboards; lightweight alternative to gRPC for basic IoT scenarios
• OpenCV (gocv) — Computer vision capabilities for robots with cameras (e.g., object detection, lane following, autonomous navigation)
• GPIO/Serial/Joystick drivers — Direct hardware abstraction for single-board computers (Raspberry Pi, Arduino) and input devices in robotics projects

• Interface-based driver/adaptor architecture with no dependency injection framework
  • Why: Keeps the framework lightweight and easy to learn for robotics hobbyists; avoids heavy IoC containers
  • Consequence: Manual wiring of devices to

Serial port permissions: on Linux/macOS, /dev/ttyACM0 access requires user in dialout/uucp group or sudo. Platform-specific builds: cross-compilation requires CGO_ENABLED=1 and correct toolchain for ARM; build examples include env vars (e.g., GOOS=linux GOARCH=arm GOARM=5). Firmware requirements: Arduino boards need Firmata firmware preloaded; Raspberry Pi needs setup (GPIO via /dev/mem or newer gpiocdev); Parrot drones require specific driver versions. Module imports: always use gobot.io/x/gobot/v2 (v2 is explicit in module path); v1 imports will fail. Robeaux UI: optional web UI in api/robeaux/ requires separate static assets not tracked in main repo.

• Hardware Abstraction Layer (Adaptor Pattern) — Gobot's core architectural pattern; adaptors decouple driver code from platform-specific I/O details, enabling same driver to work across Arduino, RPi, BeagleBone by implementing a common interface
• Firmata Protocol — The firmware standard Gobot uses to communicate with Arduino and Arduino-compatible boards; understanding Firmata messaging is critical for debugging Arduino platform issues
• GPIO (General Purpose Input/Output) — The lowest-level hardware abstraction Gobot exposes; all digital sensors and actuators interact via GPIO drivers, making GPIO understanding essential for any hardware project
• I²C / SPI Bus Multiplexing — Gobot supports multiple I²C and SPI devices on the same bus; understanding address conflicts and clock stretching prevents hardware debugging nightmares on multi-device projects
• Goroutine-based Event Loop — Gobot's internal architecture uses Go goroutines for concurrent device communication without blocking; misunderstanding channel timing causes race conditions in multi-robot systems
• Cross-compilation for ARM — Gobot code is typically written on x86/x64 but deployed to ARM (Raspberry Pi, BeagleBone); environment variables (GOOS, GOARCH, GOARM) control binary output; missing these causes 'exec format error' at runtime
• MQTT Pub/Sub for IoT — Gobot includes eclipse/paho.mqtt.golang for distributed sensor networks; MQTT is the industry standard for lightweight IoT messaging and makes Gobot robots work in swarms

• tinygo-org/tinygo — Sister project mentioned in README; runs Go directly on microcontrollers (ARM, RISC-V) without OS—Gobot targets high-level robotics while TinyGo targets embedded systems
• arduino/arduino-cli — Complementary tool for managing Arduino firmware and uploads; Gobot assumes Firmata is already on the board, arduino-cli handles getting it there
• periph-devices/periph — Gobot's underlying GPIO/peripheral abstraction on Linux; periph.io is a direct dependency for Raspberry Pi and BeagleBone support
• go-echarts/go-echarts — Visualization library for real-time sensor data from Gobot IoT deployments; used in dashboards paired with Gobot's REST API
• eclipse/mosquitto — MQTT broker that Gobot clients connect to via eclipse/paho.mqtt.golang dependency; standard choice for IoT message routing

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 comprehensive integration tests for api/cors.go and api/basic_auth.go

The api package has test files for cors_test.go and basic_auth_test.go, but given that these are security-critical middleware components, there are likely gaps in edge case coverage. A new contributor could add tests for: CORS origin validation with wildcards/subdomains, credential handling in basic auth, and interaction between both middlewares. This is high-value because security middleware bugs directly impact framework reliability.

• [ ] Review existing api/cors_test.go and api/basic_auth_test.go for coverage gaps
• [ ] Add tests for invalid CORS origins, wildcard patterns, and credential edge cases
• [ ] Add integration tests in api/helpers_test.go for middleware interaction scenarios
• [ ] Verify coverage meets >90% threshold using 'go test -cover ./api'

Add missing tests for driver.go and adaptor.go core interfaces

The repo has driver.go, adaptor.go, connection.go, and device.go as foundational files but no corresponding *_test.go files visible in the listing. These are core abstractions that all 20+ driver subdirectories depend on. A new contributor should add comprehensive unit tests covering driver/adaptor lifecycle, connection management, and the Commander interface (see commander_test.go exists). This is critical because bugs in base classes affect the entire ecosystem.

• [ ] Create driver_test.go with tests for driver Start/Stop/Halt lifecycle
• [ ] Create adaptor_test.go with tests for adaptor Connect/Disconnect/IsConnected
• [ ] Create device_test.go with tests for device initialization and property management
• [ ] Add tests for edge cases: double-connect, connect-after-halt, nil connection scenarios

Add GitHub Actions workflow for cross-platform driver testing (Windows/macOS/Linux)

The repo has .circleci/config.yml and appveyor.yml but the file listing shows a modern .github/workflows/ directory. Currently only golangci-lint.yml exists there. Given the hardware-abstraction nature of gobot (drivers for GPIO, serial, BLE, etc.), a new contributor should add a GitHub Actions matrix workflow testing key drivers across Windows/macOS/Linux. This prevents regressions in platform-specific code (e.g., go-gpiocdev is Linux-only, warthog618/go-gpiocdev is platform-specific).

• [ ] Create .github/workflows/integration-tests.yml with matrix for ubuntu-latest/macos-latest/windows-latest
• [ ] Configure conditional test skipping using build tags (//go:build darwin, //go:build linux, //go:build windows)
• [ ] Add tests for key driver packages: drivers/aio, drivers/ble (should work cross-platform)
• [ ] Ensure serial driver tests (go.bug.st/serial dependency) run on all platforms with proper skips

• Add comprehensive test coverage for drivers/aio/analog_actuator_driver.go and drivers/aio/analog_sensor_driver.go—only basic examples exist, missing edge cases like out-of-range values or connection loss handling
• Document the adaptor/driver lifecycle in cmd/docs or examples/—new contributors struggle with when Start()/Halt() are called; add a visual state machine diagram or lifecycle test
• Create a platform detection helper in the root package to simplify conditional compilation; right now examples use //go:build comments but no utility exists to detect running platform and load appropriate adaptor automatically

• High · Outdated Go Version — go.mod. The project specifies Go 1.24.0 with toolchain 1.24.6, which appears to be a future/unreleased version. This may indicate configuration issues or inability to build with stable Go versions. Current stable Go versions should be used. Fix: Update to the latest stable Go version (currently 1.23.x or later stable release). Verify the toolchain version matches available releases.
• High · Unpatched MQTT Dependency — go.mod - github.com/eclipse/paho.mqtt.golang v1.5.1. The project uses github.com/eclipse/paho.mqtt.golang v1.5.1. This version may have known vulnerabilities. MQTT implementations are security-critical for IoT applications. Fix: Check for security advisories on this dependency using 'go list -u -m all' and upgrade to the latest patched version. Review MQTT connection security settings in code.
• High · Legacy Ardrone Dependency — go.mod - github.com/hybridgroup/go-ardrone v0.0.0-20140402002621-b9750d8d7b78. The project includes github.com/hybridgroup/go-ardrone with a commit hash from 2014, which is over a decade old. This dependency is unlikely to receive security updates. Fix: Evaluate if this dependency is still needed. If required, consider forking and maintaining it, or replacing with a modern alternative. Audit the code for vulnerabilities.
• Medium · Old MJPEG Dependency — go.mod - github.com/hybridgroup/mjpeg v0.0.0-20140228234708-4680f319790e. The project uses github.com/hybridgroup/mjpeg from 2014, which is unmaintained. MJPEG processing for IoT/robotics applications could have security implications. Fix: Review if this dependency is actively used. Update or replace with a maintained alternative. Conduct security audit of MJPEG handling code.
• Medium · Multiple Outdated Dependencies — go.mod - Multiple dependencies (github.com/bmizerany/pat, github.com/nsf/termbox-go, etc.). Several dependencies show signs of age and infrequent updates: bmizerany/pat (security validation framework), nsf/termbox-go (terminal UI), and others. These may have unpatched vulnerabilities. Fix: Run 'go mod tidy' and 'go get -u' to update all dependencies. Review security advisories using tools like Nancy or Trivy. Consider replacing unmaintained packages.
• Medium · Basic Authentication Implementation — api/basic_auth.go. The codebase includes api/basic_auth.go, indicating basic HTTP authentication. This method transmits credentials in base64 encoding (not encrypted). IoT and robotics APIs need stronger authentication. Fix: Ensure HTTPS/TLS is mandatory for all API endpoints using basic auth. Consider implementing OAuth2, JWT tokens, or certificate-based authentication for production systems.
• Medium · CORS Implementation Present — api/cors.go. The presence of api/cors.go indicates CORS handling. Misconfigured CORS can lead to unauthorized cross-origin requests in IoT control scenarios. Fix: Review CORS configuration to ensure only trusted origins are allowed. Avoid using wildcard ('*') for Access-Control-Allow-Origin in production.
• Medium · Bluetooth Driver Security — drivers/ble/ directory. The codebase includes extensive BLE (Bluetooth Low Energy) drivers (drivers/ble/). Bluetooth security depends on proper pairing and encryption implementation. Fix: Audit BLE drivers for proper encryption, authentication, and pairing mechanisms. Ensure devices validate BLE credentials and implement bonding securely.
• Low · Debug Mode Possibility — debug.go. The presence of debug.go suggests debug functionality. Debug modes should be disabled in production releases. Fix: Verify that debug mode is disabled by default and cannot be enabled via environment variables

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.