Skip to content

Commit

Permalink
Update BlueOS Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@itskalvik
itskalvik committed Jan 7, 2025
1 parent 9d873b6 commit 7654d36
Showing 1 changed file with 59 additions and 37 deletions.
96 changes: 59 additions & 37 deletions docs/blueos.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# [BlueOS SGP-Tools :simple-github:](https://github.com/itskalvik/docker-sgp-tools/tree/main/robot-docker)
A [BlueOS](https://blueos.cloud/) Extension for Autonomous Approximate Bathymetric Surveys
#### A [BlueOS](https://blueos.cloud/) Extension for Autonomous Approximate Bathymetric Surveys

<div style="text-align:left">
<img height="60" src="https://raw.githubusercontent.com/itskalvik/docker-sgp-tools/refs/heads/main/.assets/blueos_sgptools.png">
Expand All @@ -10,14 +10,17 @@ Autonomous Surface Vehicles (ASVs), such as the [BlueRobotics BlueBoat](https://

The [SGP-Tools python library](https://www.itskalvik.com/sgp-tools) provides path planners to address the above problem, known as the informative path planning problem. The BlueOS SGP-Tools extension uses this library to determine ideal locations for the ASV to collect data and controls the ASV to autonomously visit the selected locations.

The following shows the path planner adaptively planning paths for four robots tasked with surveying a given area:
The following shows the path planner adaptively planning a path for an aerial drone with a downward-facing camera tasked with surveying a given area:
<div style="text-align:left">
<p><a href="http://itskalvik.com/sgp-tools">
<img width="472" src="https://raw.githubusercontent.com/itskalvik/docker-sgp-tools/refs/heads/main/.assets/AIPP-4R.gif">
<img width="472" src="https://raw.githubusercontent.com/itskalvik/docker-sgp-tools/refs/heads/main/.assets/AIPP-non-point_sensing.gif">
</a></p>
</div>


## Usage

### Starting a Mission
1. First, we need to define the survey area and the robot launch location. The extension can read this data from [QGC plan files](https://docs.qgroundcontrol.com/Stable_V4.3/en/qgc-user-guide/plan_view/plan_geofence.html). The survey area and launch position must be defined using a **polygon-shaped** geofence drawn in [QGC](https://qgroundcontrol.com/) and saved as ```mission.plan```.

<div style="text-align:left">
Expand All @@ -44,27 +47,30 @@ The following shows the path planner adaptively planning paths for four robots t
</a></p>
</div>
4. The sensor data, along with the corresponding GPS coordinates, will be logged to an [HDF5](https://docs.h5py.org/en/stable/) file in the ```DATA_FOLDER```, where the ```mission.plan``` was uploaded.
### Viewing the Data after a Mission
The sensor data, along with the corresponding GPS coordinates, will be logged to an [HDF5](https://docs.h5py.org/en/stable/) file in the ```DATA_FOLDER```, where the ```mission.plan``` was uploaded.
We can estimate the bathymetry of the entire survey area using the collected data and visualize a normalized version with the following command (⚠️ Do not run this during the mission, as it will disrupt the path planner):
```
ros2 launch ros_sgp_tools visualize_data.launch.py
```
We can estimate the bathymetry of the entire survey area using the collected data and visualize a normalized version with the following command:
The above command will publish a point cloud that can be viewed using [foxglove](https://foxglove.dev/product). You can access it from a web browser at [https://app.foxglove.dev/](https://app.foxglove.dev/). Use the ```open connection``` feature and change the address from ```localhost``` to the IP address of the ASV.
⚠️ Do not run this during the mission, as it will disrupt the path planner
```
ros2 launch ros_sgp_tools visualize_data.launch.py
```
<div style="text-align:left">
<img width="472" src="https://raw.githubusercontent.com/itskalvik/docker-sgp-tools/refs/heads/main/.assets/data_viz.gif">
</a></p>
</div>
The above command will publish a point cloud that can be viewed using [foxglove](https://foxglove.dev/product). You can access it from a web browser at [https://app.foxglove.dev/](https://app.foxglove.dev/). Use the ```open connection``` feature and change the address from ```localhost``` to the IP address of the ASV.
You can control the point cloud density using the ```num_samples``` parameter. You can set this from foxglove's ```Parameters``` panel.
<div style="text-align:left">
<img width="472" src="https://raw.githubusercontent.com/itskalvik/docker-sgp-tools/refs/heads/main/.assets/data_viz.gif">
</a></p>
</div>
By default, the latest mission log will be visualized. You can visualize a specific mission log using the following command (replace ```<log folder name>``` with the log folder name):
You can control the point cloud density using the ```num_samples``` parameter. You can set this from foxglove's ```Parameters``` panel.
```
ros2 launch ros_sgp_tools visualize_data.launch.py mission_log:=<log folder name>
```
By default, the latest mission log will be visualized. You can visualize a specific mission log using the following command (replace ```<log folder name>``` with the log folder name):
```
ros2 launch ros_sgp_tools visualize_data.launch.py mission_log:=<log folder name>
```
## Parameters
You can control the following extension parameters by running the following command in the terminal provided by the SGP-Tools extension:
Expand All @@ -75,39 +81,55 @@ export <parameter_name>=<parameter_value>
The parameters reset to their default values after rebooting. They can be made permanent by configuring the parameters using the app environment variables on the BlueOS extensions page in pirate mode.
#### Available Parameters:
### Available Parameters:
* ```PING2_PORT``` (```default: /dev/ttyUSB0```):
* ```PING2_PORT``` (```default: /dev/ttyUSB0```):
- Specifies the device to which the Ping2 sonar is mounted. You can get the device port from the ```Ping Sonar Devices``` page in BlueOS.
Specifies the device to which the Ping2 sonar is mounted.
* ```NUM_WAYPOINTS``` (```default: 20```):
The number of waypoints optimized by the path planner. Increasing the number of waypoints gives a more complex path which potentally covers a larger area but also requires more compute and could result in slower online path updates.
* ```NUM_WAYPOINTS``` (```default: 20```):
- The number of waypoints optimized by the path planner.
- Increasing the number of waypoints results in a more complex path that covers a larger area.
- Recommend increasing only when the default setting results in a poor reconstruction of the environment, as this increases the computational cost and leads to slower online path updates.
* ```SAMPLING_RATE``` (```default: 2```):
The number of points to sample along each edge of the path during path planning. Increasing the samping rate results in the planner being aware of the data being collected along the whole path instead of assuming that the data is collected only at the vertices. This method requires relatively less compute then increasing the number of waypints, but still adds to the overall compute cost.
- The number of points to sample along each edge of the path during path planning. The default value of ```2``` means that only the vertices of the path are used.
- The path planner assumes the data is collected only at the sampled points. Increasing the sampling rate allows the planner to better approximate the information along the entire path, thereby resulting in more informative paths.
- Recommend increasing only when the default setting results in a poor reconstruction of the environment, as this increases the computational cost and leads to slower online path updates.
* ```START_FOXGLOVE``` (```default: False```):
* ```DATA_BUFFER_SIZE``` (```default: 100```):
- The number of sensor data samples to collect before using the data to update the model parameters, which, in turn, will be used to update future waypoints.
- Increasing the buffer size will allow the planner to compute better parameter estimates, which will result in more informative paths.
- Recommend increasing only when the default setting results in a poor reconstruction of the environment, as this increases the computational cost and leads to slower online path updates.
* ```TRAIN_PARAM_INDUCING``` (```default: False```):
- Enables training the inducing points of the parameter model (sparse Gaussian process) in addition to the kernel parameters during the path update.
- Enabling this feature will result in more accurate parameter estimates and more informative paths.
- Recommend increasing only when the default setting results in a poor reconstruction of the environment, as this increases the computational cost and leads to slower online path updates.
Enables [foxglove](https://foxglove.dev/product), a web-based data visualization platform similar to [RViz](https://docs.ros.org/en/humble/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.html).
* ```NUM_PARAM_INDUCING``` (```default: 40```):
- The number of inducing points used in the parameter model (sparse Gaussian process).
- Increasing the number of inducing points will result in more accurate parameter estimates and more informative paths.
- Recommend enabling only when the default setting results in a poor reconstruction of the environment, as this increases the computational cost and leads to slower online path updates.
* ```ADAPTIVE_IPP``` (```default: True```):
* ```START_FOXGLOVE``` (```default: False```):
- Enables [foxglove](https://foxglove.dev/product), a web-based data visualization platform similar to [RViz](https://docs.ros.org/en/humble/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.html).
- Currently it does not publish any new information that is not available through Cockpit or QGC.
Enables adaptive IPP, which uses the data streaming from the sonar to learn the correlations in the underwater bathymetry and further optimizes the future waypoints to maximize collecting new informative data.
* ```ADAPTIVE_IPP``` (```default: True```):
- Enables adaptive informative path planning.
- When enabled, it uses the data streaming from the sonar to learn the correlations in the underwater bathymetry and further optimizes the future waypoints to collect even more informative data.
- Recommend disabling it if the onboard sonar is currently unsuppored by this package.
* ```NAMESPACE``` (```default: robot_0```):
- ROS2 namespace, useful when multiple ROS2 robots are operating on the same network.
- Currently, only the single robot planner is fully supported.
ROS2 namespace, useful when multiple ROS2 robots are operating on the same network.
* ```DATA_TYPE``` (```default: Ping2```):
Type of sensor to be used by the path planner. Currently, only the [BlueRobotics Ping Sonar](https://bluerobotics.com/store/sonars/echosounders/ping-sonar-r2-rp/) is supported.
- Type of sensor to be used by the path planner.
- Currently, only the [BlueRobotics Ping Sonar](https://bluerobotics.com/store/sonars/echosounders/ping-sonar-r2-rp/) is supported.
* ```FAKE_DATA``` (```default: False```):
Enables a fake sensor data publisher used for testing. Requires ```DATA_TYPE=SerialPing2```.
- Enables a fake sensor data publisher used only for testing. Requires ```DATA_TYPE=SerialPing2```.
## Hardware Configuration
- This extension works only on 64-bit operating systems. You can install the latest version of [BlueOS](https://github.com/bluerobotics/BlueOS) on [64-bit Raspberry Pi OS Lite](https://www.raspberrypi.com/software/operating-systems/) by running the following command on the Pi (ensure the username is set to ```pi```):
Expand Down

0 comments on commit 7654d36

Please sign in to comment.