Skip to content

Add persistent ROS 2 mapping sessions #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
temiroff merged 1 commit into from
Aug 10, 2026
Merged

Add persistent ROS 2 mapping sessions #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
| `detection` | On | Managed OpenCV detection streams |
| `tracking` | On | Deterministic color tracking and target hints |
| `imu` | On | `IMU`, live ROS 2 orientation, and `IMUViewer` |
| `slam`, `localization` | Off | Optional capability contracts |
| `slam` | Off | Persistent mapping sessions, SLAM Toolbox integration, and map artifacts |
| `localization` | Off | Optional localization capability contracts |

## Main nodes

Expand All @@ -35,6 +36,7 @@ does not use Warp.
- `DepthCamera` and `DepthObstacleWarning` expose capability and safety state after depth processing.
- `CameraViewer`, `DepthViewer`, and `IMUViewer` present processed sensor contracts with controls specific to that sensor.
- `LiDAR` exposes normalized scans; the optional CUDA `LiDARViewer` is the explicit Warp visualization path.
- `MapEnvironment` attaches to or session-scopes SLAM Toolbox and persists an occupancy map plus pose graph.
- `TrackingObject` serves annotated MJPEG, masks, snapshots, and latest detections.
- `VLM`, `ReasoningStream`, and `ReasoningDashboard` support OpenAI-compatible, NVIDIA NIM, Anthropic, and local Ollama endpoints.

Expand All @@ -49,6 +51,10 @@ Add a `Camera` node with `selection: 0` for the first local camera. Sensor templ

Managed camera, tracker, reasoning, IMU, and spatial viewers start or update one background service. New frames do not require graph recooks. Worker health and source freshness are reported separately, and stale data is never presented as live.

The `ROSOrin Persist Environment Map` workflow stores a live SLAM Toolbox map
under `/home/ubuntu/Blacknode/maps`. It consumes the existing robot graph and
does not replace ROSOrin's vendor startup configuration.

## Development

```powershell
Expand Down
17 changes: 15 additions & 2 deletions blacknode-package.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "blacknode-perception"
version = "0.5.4"
version = "0.5.5"
description = "Camera, tracking, VLM, and spatial-perception capabilities organized as selectable components."
requires-blacknode = ">=0.3.0"
layer = "perception"
Expand Down Expand Up @@ -134,10 +134,23 @@ imports = ["cv2", "numpy"]
requires = [{ package = "blacknode-perception", component = "camera", version = ">=0.2.0,<1.0.0" }]

[components.slam]
description = "Mapping and SLAM lifecycle contracts."
description = "Persistent mapping sessions and provider-neutral map artifacts."
default = false
capabilities = ["perception.slam"]

[components.slam.adapters.ros2]
description = "SLAM Toolbox mapping over an existing or Blacknode-owned ROS 2 session."
default = false
capabilities = ["adapter.perception.slam.ros2"]
nodes = ["components/slam/adapters/ros2/nodes"]
templates = ["components/slam/adapters/ros2/templates"]
node-types = ["MapEnvironment"]

[components.slam.adapters.ros2.dependencies]
requires = [
{ package = "blacknode-ros2", component = "core", version = ">=0.6.2,<1.0.0" }
]

[components.localization]
description = "Localization state, confidence, and recovery contracts."
default = false
Expand Down
26 changes: 14 additions & 12 deletions components/slam/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# Slam
# SLAM

Component of `blacknode-perception`.
The optional SLAM component owns persistent mapping sessions and normalized
`blacknode.map-artifact` records. Its ROS 2 adapter provides `MapEnvironment`
for SLAM Toolbox.

Node sources for this component belong in this folder. Until they move here,
nodes claim the component inline:
`MapEnvironment` supports four useful actions:

@node(name="MyNode", component="slam", ...)
- `start` attaches to an existing `/map` publisher or launches only a
Blacknode-owned SLAM Toolbox process when `lifecycle=managed`.
- `save` calls the configured SLAM Toolbox map and pose-graph services and
returns the persisted artifact paths.
- `status` reports the normalized provider state.
- `stop` terminates only the process handle Blacknode started.

Once sources live here, declare the folder in `blacknode-package.toml`:

[components.slam]
nodes = ["components/slam/nodes"]

and the inline `component=` argument can be dropped — the loader infers it
from the directory.
For ROSOrin, use `/home/ubuntu/ros2_ws/src/slam/config/slam.yaml` as the managed
SLAM parameters file. The provider does not launch the vendor robot bringup,
edit that workspace, or change boot services.
1 change: 1 addition & 0 deletions components/slam/adapters/ros2/nodes/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
from . import mapping # noqa: F401
Loading