Skip to content
AuthorPascal DateJuly 18, 2026 Rev1.1

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. How the whole system fits together: the layer model, the abstraction seam, where everything runs, a repo-by-repo map, the honest current state, and how to add a robot or a skill. It is also the hub that says which page owns what.

    Architecture

  •  Set up your own stack

    From an empty machine to a brain you can type into, driving the R1 in the Gazebo sim. The simulator is per person; the brain already runs on the 4090 — you request an instance rather than building one. Includes how to verify each layer, and the traps that make a setup look broken.

    Set up your own robot + sim

  •  Running the simulator

    The R1 in Gazebo Harmonic on hardware you control: Linux (a box or a VM) and macOS / Apple silicon (RoboStack, no VM), through the same two r1ctl commands — with an honest matrix of what each one can and cannot do.

    Running the simulator

  •  Running a brain

    The single reference for brainctl on the brain host (the 4090): every command and flag, onboarding a colleague in one command, configuring an instance (planner, model, Hydra overrides), brain.env, the shared central memory, HTTPS and the installable PWA URL.

    Running a brain

  •  Using the brain

    Driving a brain that already runs: the mental model, chat + the Debug panel, the live sub-module telemetry, the Visual Command / observer view, and how it learns from your corrections.

    Using the brain

  •  Integrating a robot

    For robot developers: the MCP contract your robot implements — the canonical tool set, return shapes, conventions, the optional capabilities, and the checklist.

    Integrating a robot

  •  R1 robot stack

    The R1 robot-side reference: r1ctl, what runs in which tmux window, every port and env var, the smoke tests that prove the MCP path, and the recovery runbooks.

    R1 robot stack

  •  Design specs

    Per-service design specs — one file per MCP server / component (the grasp skill, the world state, fleet memory, the kit, the agent).

    Design specs

  •  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

Where the code lives

Repo Role
binabik-orchestrator Umbrella: product-general specs + the component repos below.
robot-voice-chat The brain (planner, plan runtime, MCP client, web UI + admin).
binabik-brain-host Brain deployment (brainctl, image, robots.yaml attach, HTTPS).
robot-mcp-kit Shared MCP library — Async Task Contract (server) + ToolClient (client).
grasp-service / skill-service-template Layer-3 skill services: reliable pick-up + the copy-me scaffold.
robot-mcp-perception / ros2_vision_interfaces Archived (July 2026) — v2 vision module + message defs, superseded by galaxea on-demand perception + binabik-r1-vision.
robot-mcp-memory Central fleet memory — registry + group-scoped learning; deployed by default via brainctl.
mcp-perception-buffer / ros2-memory Retired (BIN-306, August 2026) — the ambient "what do you see" buffer and episodic recall. Nothing launches either; "what do you see" is the world state, on demand.
segmentation-modal SAM 3 segmenter on Modal + an MCP wrapper — segment plus the segmenter_status/stop/deploy lifecycle, also over HTTP as sam3-control (optional, paid off-robot perception).
binabik-scene-perception Robot-agnostic scene core: grounding → segmentation → the canonical capture_scene object list (no ROS).
rap-integration Archived (July 2026) — the pre-abstraction R1Pro/Jazzy-sim integration, superseded by r1-abstraction + r1ctl.
r1-abstraction binabik's R1 adapter — presents the canonical contract over galaxea_agent's MCP servers.
binabik-r1-vision R1 on-demand scene service (:9230) — capture_scene / get_frame / pixel_to_3d; opt-in, adapter falls back to look.
galaxea_agent The R1's own MCP servers (r1_manipulation, perception, nav2, ros) — sim-proven on Jazzy; real-robot (Humble) bring-up in progress.
galaxea_isaac_moveit The R1's ROS substrate (sim + MoveIt/Nav2 + robot def); one unified branch, main, for both.

Everything above the Binabik Robot Abstraction Layer (brain, skills, kit) is robot-agnostic; only the robot's MCP servers below it are robot-specific. See Architecture — §2a for the abstraction seam and §4 for the repo map.

There is no archive

Superseded documents are deleted, not shelved. Every page here describes the stack as it is now; what it used to be is in git history (git log --diff-filter=D --stat) and in Linear, not in a folder people can mistake for current truth.