Skip to content
AuthorPascal DateJuly 14, 2026 Rev1.0

Binabik Software

Central, source-of-truth documentation for the binabik robot stack. The code lives in its own repositories (the brain, the per-robot integrations, the MCP servers); this topic holds the cross-cutting docs — architecture, guides, and design specs — so they don't drift across repos. Each code repo keeps only its own README.md.

Start here

  •  Architecture

    Read this first. From-scratch onboarding: the layer model (explained before any service is named), the control/data split, where everything runs, a repo-by-repo map, the honest current state, the change roadmap, and how to add a new robot or skill.

    Architecture

  •  Coding guidelines

    The conventions every binabik codebase follows: ports & adapters, config-driven DI, Hydra + Pydantic config, async, security, logging, and testing. Read before you write code.

    Coding guidelines

  •  Using the brain

    Using and operating the brain: the mental model, the layer model, driving it (chat + the Visual Command / observer view), and admin operations (run / update / configure / prompts).

    Using the brain

  •  Integrating a robot

    Connecting a robot: the quick-connect flow plus the full MCP contract (tools, optional capabilities, checklists) a robot developer implements.

    Integrating a robot

  •  Design specs

    Per-service design specs — one file per MCP server / component (perception, memory, skill control, the kit, the agent, prompt building).

    Design specs

  •  Verify the rollout

    End-to-end runbook: deploy + verify the layer-3 rollout (grasp-service, the robots.yaml attach, the Skills panel, cloud perception) live on a robot — with expected results and rollback.

    Verification runbook

Where the code lives

Repo Role
binabik-orchestrator Umbrella: product-general specs + the component repos below.
robot-voice-chat The brain (planner, plan runtime, web UI).
binabik-brain-host Brain deployment (brainctl, image, UI, HTTPS).
robot-mcp-perception / mcp-perception-buffer / ros2_vision_interfaces Perception / vision (data plane).
robot-mcp-memory / ros2-memory Process/skill memory + episodic memory.
robot-mcp-kit Shared MCP library (Async Task Contract).
rap-integration Reference robot integration (Galaxea R1Pro).

See Architecture for what each does, which layer it is, and where it runs.

Archive

Kept for reference: