docs: move README contents to documentation (#159)

* docs: move README contents to documentation Signed-off-by: David Wong <[email protected]> * fix(docs): spelling Signed-off-by: David Wong <[email protected]> * fix(docs): more spelling Signed-off-by: David Wong <[email protected]> * fix(docs): replace ❌ etc. by emoji * docs: add link to tutorial branch --------- Signed-off-by: David Wong <[email protected]> Co-authored-by: Max Schmeller <[email protected]>
tier4 · Jun 2, 2024 · 18848ab · 18848ab
1 parent 6cc19f8
commit 18848ab
Show file tree

Hide file tree

Showing 14 changed files with 364 additions and 441 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -5,6 +5,7 @@
   "words": [
     "adctp",
     "Adctp",
+    "applicate",
     "AT",
     "autosar",
     "block_id",

diff --git a/README.md b/README.md
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,7 @@
+# About Nebula
+
+WIP, please check back soon!
+
+
+
+
diff --git a/docs/add_sensor.md b/docs/add_sensor.md
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,3 @@
+# Contributing to Nebula
+
+WIP - please check back soon!
diff --git a/docs/design.md b/docs/design.md
@@ -1,102 +1,5 @@
-# Nebula requirements
+# Nebula design
 
-The driver follows the following functional requirements:
-ドライバは、次の機能的な要求に応えなければならない。
-
-## Hardware interface independent
-
-The data acquisition and communication with the sensor must not be bound to a specific hardware interface.
-センサでのデータ取得と通信は、特定のハードウェアに縛られてはならない。
-
-### Why?
-
-Writing a general-purpose driver independent of the interface will support different types of hardware interfaces.
-インターフェイスに依存しない汎用ドライバを書くことで、異なったタイプのハードウェアインターフェイスに対応することができる。
-
-## Sensor Control
-
-The driver should obtain, set, and confirm the desired sensor configuration at launch, i.e., scan frequency, synchronization methods, etc.
-ドライバは起動時に、望ましいセンサ設定（スキャン周波数、同期方法等）を取得、設定、確認できる必要がある。
-
-### Why?
-
-The sensor control will ensure that the sensor works in the expected mode as it was initially intended.
-これによって、センサが当初より意図していたモードで動いていることが確認できる。
-
-## Configurable output cloud
-
-The ROS wrapper should be able to define the desired output format of the point cloud. i.e., customize the fields to be contained in the final output cloud.
-ROS ラッパーは点群の望ましい出力フォーマットで定義できなければならない（最終的な出力クラウドに含まれるフィールドをカスタマイズできる）
-In addition, it should be able to generate the corresponding 2D range image for the output point cloud.
-
-さらに、出力された点群を対応する二次元レンジ画像に生成することができなければならない。
-If the sensor allows it, have an option to add a minimum and maximum range distance as an option. For instance, if the user launches the driver with a range limit set to 0, the driver will not perform any filtering.
-センサが許可している場合は、オプションとして最小値と最大値のレンジ距離を追加することができる。例えば、ユーザーが範囲制限を 0 に設定してドライバーを起動した場合、ドライバはフィルタリングを行わない。
-The driver should have an option to define if the output cloud is of a fixed size or dynamic size. If a fixed size is selected, the output cloud must include NaN values for those lasers without any return. If a dynamic size is selected, the lasers with no valid returns are to be removed.
-ドライバは、出力クラウドを固定されたサイズか、もしくはダイナミックサイズにするかを定義するオプションが必要である。固定されたサイズを選択した場合、出力クラウドは、リターンのないレーザの NaN 値を含まなければならない。ダイナミックサイズを選択した場合、リターンのないレーザは削除される。
-Default behavior: Dynamic, remove invalid laser returns (NaN).
-デフォルトの動作：ダイナミック、無効なレーザリターンを削除。（NaN)
-
-### Why?
-
-The configurable output will allow the generation of the point cloud according to the expected use case application.
-これによって、予定したユースケースアプリケーションにより必要な出力を生成することができる。
-
-## Sensor Metadata
-
-The driver should include the following metadata for each generated point cloud:
-ドライバは、生成された点群それぞれに、次のメタデータが含まれなければならない：
-
-### Calibration data キャリブレーションデータ
-
-Contains the sensor calibration parameters used to generate the point cloud from the raw data.
-生データから点群を生成するのに使用したセンサキャリブレーションパラメータ
-
-### Sensor settings センサ設定
-
-The configuration mode in which the sensor is being executed:
-センサが実行された設定モード
-
-### Synchronization mode (PTP, PPS/NMEA)　同期モード(PTP, PPS/NMEA)
-
-Sensor Type
-センサタイプ
-Sensor Model
-センサモデル
-Scan frequency
-スキャン周波数
-
-### Why?
-
-The processed point cloud or the raw data does not always contain the state on which the sensor was run. Moreover, having this information at hand will help identify, classify and understand the situation of the recorded data.
-処理した点群、つまり生データは、常にセンサが作動した状態を含んでいるとは限らない。手元に情報があることは、記録データの状況を素早く把握し、分類し、理解することの助けになる。
-
-## Multi echo compatible
-
-The sensor should consider the possibility of the future inclusion of more than two echos.
-センサは２つ以上のエコーが将来的に含まれる可能性があることを考慮すべきである。
-
-### Why?
-
-Multi-echo support will help to future-proof the driver according to new features included or used in new sensors. In addition, multiple echo support has been proven to improve sensor resilience against weather conditions such as rain, fog, and snow.
-これによって、新しいセンサに搭載された、もしくは、開発された新機能によって、ドライバの将来性を高めることができる。複数のエコーに対応することで、雨や霧、雪などの天候条件に対して、センサの回復力が改善されることが証明されている。
-
-## ROS independent
-
-The objects used inside the driver must be ROS independent.
-ドライバ内に使用されている API 等の対象物は、ROS に依存してはならない。
-
-### Why?
-
-The third-party dependency reduction allows any software to be quickly updated without waiting for external dependencies to be updated.
-これにより、どんなソフトウェアでも、アップデートのための外部依存を待つ必要がなく、素早くアップデートすることができる。
-
-## Offline ready
-
-The data parser API inside the driver should not be designed to expect the data to be received in a real-time stream.
-ドライバ内のデータパーサ API は、データをリアルタイムストリームで受け取るように設計されるべきではない。
-
-### Why?
-
-Offline processing will help process the data faster than in real-time.
-これにより、データがセンサの代わりにログファイルから発信された時にデータ処理をリアルタイムより速く処理することができる。
+WIP - please check back soon!
+For now, here is some related information about the Hesai decoder design:
+[Hesai decoder design](hesai_decoder_design.md)
diff --git a/docs/index.md b/docs/index.md
@@ -1,72 +1,32 @@
-# Nebula introduction
-
-The project is separated into four main parts:
-プロジェクトは主となる 4 つのパートに分かれている：
-Lidar ドライバ、ROS ラッパー、HWI インターフェイスだ。
-
-- Common: `nebula_common`. This packages contains the structures, data types, calibration and configuration definitions used among all the packages.
-- Drivers: `nebula_decoders`. The Drivers take care of all the data parsing and conversion. Lidar ドライバは、全てのセンサ通信とデータパーシングを管理している。
-- ROS Nodes Wrappers: `nebula_ros`, The ROSWrappers are a lightweight layer responsible for the data conversion between the LidarDriver point cloud and the corresponding ROS counterparts. The ROSWrapper also provides methods for configuration and the obtention of the status information of the Lidar. ROS ラッパーは、Lidar ドライバ点群と対応する ROS のカウンターパーツのデータ変換を掌る軽量のレイヤである。 ROS ラッパーは、構成方法、Lidar のステータス情報取得の方法を提供している。
-- HWInterface: `nebula_hw_interfaces`. The HWInterface offers an abstraction layer between the parser and the sensor communication. HW インターフェイスは、パーサとセンサ間の抽象化レイヤを提供している。
-
-# Nebula Common
-
-The Nebula common package contains structure definition such as configuration, calibration, point types.
-It also contains other common status strings and conversions used among all the packages.
-
-## Point Types
-
-Nebula supports three point cloud output types.
-However, it can easily be extended to support other custom point cloud types.
-
-These definitions can be found in the `nebula_common/include/point_types.hpp`.
-
-### PointXYZIR
-
-| Field         | Type    | Units | Description                                                          |
-| ------------- | ------- | ----- | -------------------------------------------------------------------- |
-| `x`           | `float` | `m`   | Contains the abscissa member of the point in cartesian coordinates.  |
-| `y`           | `float` | `m`   | Contains the ordinate member of the point in cartesian coordinates.  |
-| `z`           | `float` | `m`   | Contains the applicate member of the point in cartesian coordinates. |
-| `intensity`   | `uint8` |       | Contains the laser energy return value as reported by the sensor.    |
-| `return type` | `uint8` |       | Contains the lase return type according to the sensor configuration. |
-
-### PointXYZICAETR
-
-| Field         | Type    | Units | Description                                                          |
-| ------------- | ------- | ----- | -------------------------------------------------------------------- |
-| `x`           | `float` | `m`   | Contains the abscissa member of the point in cartesian coordinates.  |
-| `y`           | `float` | `m`   | Contains the ordinate member of the point in cartesian coordinates.  |
-| `z`           | `float` | `m`   | Contains the applicate member of the point in cartesian coordinates. |
-| `intensity`   | `uint8` |       | Contains the laser energy return value as reported by the sensor.    |
-| `channel`     | `uint8` |       | Contains the laser channel id.                                       |
-| `azimuth`     | `float` | `rad` | Contains the azimuth of the current point.                           |
-| `elevation`   | `float` | `rad` | Contains the elevation of the current point.                         |
-| `timestamp`   | `float` | `ns`  | Contains the relative time to the triggered scan time.               |
-| `return type` | `uint8` |       | Contains the lase return type according to the sensor configuration. |
-
-### PointXYZICATR
-
-| Field         | Type    | Units     | Description                                                          |
-| ------------- | ------- | --------- | -------------------------------------------------------------------- |
-| `x`           | `float` | `m`       | Contains the abscissa member of the point in cartesian coordinates.  |
-| `y`           | `float` | `m`       | Contains the ordinate member of the point in cartesian coordinates.  |
-| `z`           | `float` | `m`       | Contains the applicate member of the point in cartesian coordinates. |
-| `intensity`   | `uint8` |           | Contains the laser energy return value as reported by the sensor.    |
-| `channel`     | `uint8` |           | Contains the laser channel id.                                       |
-| `azimuth`     | `float` | `degrees` | Contains the azimuth of the current point.                           |
-| `timestamp`   | `float` | `ns`      | Contains the relative time to the triggered scan time.               |
-| `return type` | `uint8` |           | Contains the lase return type according to the sensor configuration. |
-
-### PointXYZIRADT
-
-| Field         | Type    | Units     | Description                                                                |
-| ------------- | ------- | --------- | -------------------------------------------------------------------------- |
-| `x`           | `float` | `m`       | Contains the abscissa member of the point in cartesian coordinates.        |
-| `y`           | `float` | `m`       | Contains the ordinate member of the point in cartesian coordinates.        |
-| `z`           | `float` | `m`       | Contains the applicate member of the point in cartesian coordinates.       |
-| `intensity`   | `uint8` |           | Contains the laser energy return value as reported by the sensor.          |
-| `return type` | `uint8` |           | Contains the lase return type according to the sensor configuration.       |
-| `azimuth`     | `float` | `degrees` | Contains the azimuth of the current point.                                 |
-| `distance`    | `float` | `m`       | Contains the distance from the sensor origin to this echo on the XY plane. |
-| `timestamp`   | `float` | `ns`      | Contains the relative time to the triggered scan time.                     |
+# Welcome to the Nebula documentation
+Welcome to the Nebula documentation. Here you will find information about the background of the project, how to install and use with ROS 2, and also how to add new sensors to the Nebula driver.
+
+# About Nebula
+Nebula is a sensor driver platform that is designed to provide a unified framework for as wide a variety of devices as possible.
+While it primarily targets Ethernet-based LiDAR sensors, it aims to be easily extendable to support new sensors and interfaces. 
+Nebula works with ROS 2 and is the recommended sensor driver for the [Autoware](https://autoware.org/) project. The project aims to provide:
+
+- A universal sensor driver
+  - Supporting an increasing number of LiDAR, radar and camera sensors
+- 100% open source, with a no-binaries policy
+- ROS 2 wrappers for easy inclusion in robotics and self-driving vehicle projects
+- A driver solution to suit current Autoware requirements
+  - Interfaces and pointcloud type updates made in unison with Autoware developments
+
+For more information, please refer to [About Nebula](about.md).
+
+# Getting started
+- [Installation](installation.md)
+- [Launching with ROS 2](usage.md)
+
+# Nebula architecture
+- [Design](design.md)
+- [Parameters](parameters.md)
+- [Point cloud types](point_types.md)
+
+# Supported sensors
+- [Supported sensors](supported_sensors.md)
+
+# Development
+- [Tutorials](tutorials.md)
+- [Contributing](contributing.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,39 @@
+# Installing Nebula
+
+## Requirements
+Nebula requires ROS 2 (Galactic or Humble) to build the ROS 2 wrapper.
+Please see the [ROS 2 documentation](https://docs.ros.org/en/humble/index.html) for how to install.
+
+
+## Getting the source and building
+> **Note**
+>
+> A [TCP enabled version of ROS' Transport Driver](https://github.com/mojomex/transport_drivers/tree/mutable-buffer-in-udp-callback) is required to use Nebula.
+> It is installed automatically into your workspace using the below commands. However, if you already have ROS transport driver binaries installed, you will have to uninstall them to avoid conflicts (replace `humble` with your ROS distribution):
+> `sudo apt remove ros-humble-udp-driver ros-humble-io-context`
+
+To build Nebula run the following commands in your workspace:
+
+```bash
+# In workspace
+mkdir src
+git clone https://github.com/tier4/nebula.git src
+# Import dependencies
+vcs import src < src/build_depends.repos
+rosdep install --from-paths src --ignore-src -y -r
+# Build Nebula
+colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+```
+
+## Testing your build
+
+To run Nebula unit tests:
+```bash
+colcon test --event-handlers console_cohesion+ --packages-above nebula_common
+```
+
+Show results:
+
+```bash
+colcon test-result --all
+```