feat(nebula_sample): add sample sensor package as template

[drwnz]

PR Type

• Feature

Related Links

• N/A

Description

Add a new nebula_sample package that serves as a vendor-agnostic template for integrating new sensors into Nebula.

Goals

This package achieves three main objectives:

1. Faster onboarding: Provides a working example that developers can copy and modify to add support for new sensors.
2. Clear architecture: Demonstrates the modular structure of Nebula with separate packages for common, decoders, hardware interfaces, and ROS wrapper.
3. Documentation: Includes a simple integration guide with step-by-step instructions and implementation details.

Package Structure

The sample sensor consists of four packages:

• nebula_sample_common - Common definitions and configuration structures
• nebula_sample_decoders - Packet decoder and driver implementation
• nebula_sample_hw_interfaces - Hardware interface for sensor communication
• nebula_sample - ROS 2 wrapper and launch files

Key Features

• ✅ Compiles and runs without errors
• ✅ Empty/stub implementations for required classes
• ✅ Integration guide included in the tutorial documentation (integration_guide.md)
• ✅ Based on Hesai implementation structure
• ✅ Passes all pre-commit checks

Documentation

• README.md - Quick overview and package structure
• INTEGRATION_GUIDE.md - Simple integration instructions covering:
  • Cloning and renaming the package
  • Implementation details for each component
  • Verification steps
  • Checklist for developers

Pre-Review Checklist for the PR Author

• Assign PR to reviewer
• All files pass pre-commit checks
• Package builds successfully
• Launch file works correctly

Checklist for the PR Reviewer

• Commits are properly organized and messages are according to the guideline
• PR title describes the changes
• Documentation is clear and comprehensive

Post-Review Checklist for the PR Author

• All open points are addressed and tracked via issues or tickets

[Copilot]

Pull request overview

This PR adds a vendor-agnostic nebula_sample package template to accelerate integration of new sensors into the Nebula LiDAR driver framework. It provides a complete working example with stub implementations that compile successfully and can serve as a copy-and-modify starting point for developers.

• Implements four-package modular structure (common, decoders, hw_interfaces, ROS wrapper)
• Includes comprehensive integration guide with step-by-step instructions
• Provides stub implementations that demonstrate the required architecture

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/nebula_sample/nebula_sample_common/*	Common configuration structures and dependencies
src/nebula_sample/nebula_sample_decoders/*	Decoder interface and driver with stub packet parsing
src/nebula_sample/nebula_sample_hw_interfaces/*	Hardware interface for sensor communication setup
src/nebula_sample/nebula_sample/*	ROS 2 wrapper node with point cloud publisher and launch file
src/nebula_sample/README.md	Package overview and quick-start documentation
src/nebula_sample/INTEGRATION_GUIDE.md	Detailed step-by-step integration instructions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mojomex]

Thanks! I think it's already close to what we want!

I left some smaller feedback about overly Hesai-specific examples and style.
Maybe comments in the code to make the role of each of the function stubs more understandable would be nice.

As for the integration guide, I think it would need to contain sections about what building blocks Nebula provides (UDP socket handling, diagnostic helpers, etc.), and also about the required behavior on startup, reconfiguration, connection loss, etc.
I alos think that the guide shall be moved to the docs and rendered with Mkdocs to have everything in one place.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.12%. Comparing base (bf52dda) to head (02d40ba).

❌ Your patch check has failed because the patch coverage (0.00%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #382      +/-   ##
==========================================
+ Coverage   36.75%   37.12%   +0.36%     
==========================================
  Files         138      145       +7     
  Lines       11207    11387     +180     
  Branches     5961     6020      +59     
==========================================
+ Hits         4119     4227     +108     
- Misses       6301     6342      +41     
- Partials      787      818      +31     

Flag	Coverage Δ
nebula_continental_hw_interfaces	38.97% <0.00%> (?)
nebula_core_common	38.97% <0.00%> (?)
nebula_core_decoders	38.97% <0.00%> (?)
nebula_core_hw_interfaces	38.97% <0.00%> (?)
nebula_core_ros	38.97% <0.00%> (?)
nebula_hesai	38.97% <0.00%> (?)
nebula_hesai_decoders	38.97% <0.00%> (?)
nebula_hesai_hw_interfaces	38.97% <0.00%> (?)
nebula_sample	38.97% <0.00%> (?)
nebula_sample_common	38.97% <0.00%> (?)
nebula_sample_decoders	38.97% <0.00%> (?)
nebula_sample_hw_interfaces	38.97% <0.00%> (?)
nebula_velodyne_hw_interfaces	38.97% <0.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[drwnz]

Thanks! I think it's already close to what we want!

I left some smaller feedback about overly Hesai-specific examples and style. Maybe comments in the code to make the role of each of the function stubs more understandable would be nice.

As for the integration guide, I think it would need to contain sections about what building blocks Nebula provides (UDP socket handling, diagnostic helpers, etc.), and also about the required behavior on startup, reconfiguration, connection loss, etc. I alos think that the guide shall be moved to the docs and rendered with Mkdocs to have everything in one place.

Thanks for the review! I moved the integration guide to https://github.com/tier4/nebula/blob/3f235db56c121c587c7dec41f272ae7001fbdc05/docs/integration_guide.md and added a lot more information to it.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mojomex]

Addressed review threads with commit references (see inline).

[mojomex]

@codex Please review.

• Is the intent of the PR clear?
• What would you do differently?
• Are docs and code consistent, easily understandable, and bloat-free?

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e2c3c95d92

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b08432e38d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".