robonix_api.capability

User-facing CapabilityProvider classes: Primitive, Service, Skill.

A Robonix package instantiates exactly one of these. The framework talks to atlas (RegisterPrimitive/Service/Skill + DeclareCapability + Heartbeat), serves the lifecycle gRPC API (Driver(CMD_INIT/ACTIVATE/DEACTIVATE/SHUTDOWN)), and provides thin helpers over rclpy / grpcio / FastMCP for the most common patterns.

Internal _ProviderBase shares all the lifecycle / decorator / server plumbing; the three concrete classes differ only in which atlas Register RPC they call.

Layered API:

  • Layer 1 (always available): declare_capability, connect_capability, spawn subprocess, sentinel waits.

  • Layer 2 (opt-in convenience): create_publisher / create_subscription for ROS 2; @provider.provides_grpc(…) / @provider.provides_mcp(…) decorators that register the handler AND atlas-declare the Capability in one step (description is pulled from the function’s docstring or passed explicitly).

Classes

Primitive(id, namespace, *[, pkg_root, md_path])

A hardware / data-source driver CapabilityProvider.

Service(id, namespace, *[, pkg_root, md_path])

A composed CapabilityProvider built on top of Primitives / Services.

Skill(id, namespace, *[, pkg_root, md_path])

A model-backed, executor-activated CapabilityProvider.
class robonix_api.capability.Primitive(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]

Bases: _ProviderBase

A hardware / data-source driver CapabilityProvider. e.g. tiago_camera, mid360_lidar, ranger CAN chassis.

primitive_cam = Primitive(

id=”webots_tiago_camera_front”, namespace=”robonix/primitive/camera”,

)

class robonix_api.capability.Service(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]

Bases: _ProviderBase

A composed CapabilityProvider built on top of Primitives / Services. e.g. mapping, navigation, scene; also the platform- internal pilot / executor / scene / memory / liaison services.

service_mapping = Service(

id=”mapping”, namespace=”robonix/service/mapping”,

)

class robonix_api.capability.Skill(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]

Bases: _ProviderBase

A model-backed, executor-activated CapabilityProvider. Sits at INACTIVE between calls; the executor flips it to ACTIVE on demand (and MAY flip back when idle, configurable).

skill_explore = Skill(

id=”explore”, namespace=”robonix/skill/explore”,

)