primitive-beingbeyond-d1-camera-rbnx

中文版

robonix.primitive.beingbeyond.d1.camera — Robonix primitive for the BeingBeyond D1 head Intel RealSense D435i RGB-D camera. Talks to pyrealsense2 directly, with no ROS backend, serving on-demand frames only.

Capabilities

Contract	Transport	What it does
`robonix/primitive/camera/driver`	gRPC	lifecycle (`CMD_INIT` / `ACTIVATE` / `DEACTIVATE` / `SHUTDOWN`)
`robonix/primitive/camera/snapshot`	gRPC	one RGB frame as a JPEG-encoded `sensor_msgs/Image`
`robonix/primitive/camera/depth_snapshot`	MCP	one depth frame, normalised to JPEG

The rgb / depth / intrinsics / extrinsics topic_out streaming contracts are intentionally not provided — this deployment has no ROS backend. Consumers pull frames on demand.

Configuration

Fields, units and defaults are in config.spec. The essentials:

width / height (default 1280 / 720) — keep these at the resolution the hand-eye calibration was done at, or the downstream detector's pixel→world homography stops being valid.
fps (default 30) — the underlying stream rate; snapshots pull single frames on demand.
frame_id (default camera) — the frame_id stamped into the emitted sensor_msgs/Image header.

Every field also falls back to a matching D1_CAMERA_* env var.

Dependencies and permissions

Python ≥ 3.10 with pyrealsense2 and robonix_api.
USB permissions: the RealSense needs the udev rules from librealsense (99-realsense-libusb.rules), otherwise a non-root user cannot open the device.
The camera has to be on a USB 3.0 port; 1280x720@30 is not available over USB 2.0.
scripts/start.sh defaults to $HOME/miniconda3/envs/bb_d1_robonix/bin/python3; override with BLOCK_GRASP_PYTHON.

Build and run

bash scripts/build.sh        # rbnx codegen (--mcp, since depth_snapshot is an MCP contract)
bash scripts/start.sh        # or let rbnx boot start it from a deployment manifest
rbnx caps -v | grep camera   # check all 3 capabilities registered and the provider is ACTIVE

init opens the camera and confirms one frame arrives before reporting ready, so a startup failure means a hardware or permissions problem.

Shutdown is handled by the Driver's CMD_SHUTDOWN. There is no cleanup beyond that, so no scripts/stop.sh is provided.

Note

An on-demand snapshot can otherwise hand back a stale frame queued up inside the RealSense, so the queue is drained before a frame is taken. That matters for any call chain that moves the head and then immediately takes a picture.

Layout

package_manifest.yaml   config.spec   README.md   README_CN.md
scripts/{build.sh, start.sh}
d1_camera/{__init__.py, main.py, vision.py}

vision.py (the RealSenseCamera wrapper) ships with the package, so it is self-contained.

License

MulanPSL-2.0