Rearranged tutorial lists and added content in Architecture (#17)

* Rearranged tutorial lists and added content in Architecture * Added tutorials * tutorials * Fixed typos * enable LaTeX Signed-off-by: Michael Anderson <[email protected]> * adding spring documentation Signed-off-by: Michael Anderson <[email protected]> * add gas modeling Signed-off-by: Michael Anderson <[email protected]> * fix typo Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * add more steps from after law of cooling Signed-off-by: Michael Anderson <[email protected]> * minor Signed-off-by: Michael Anderson <[email protected]> * enable LaTeX (#20) Signed-off-by: Michael Anderson <[email protected]> * Added draft parameter tables * Updated theory.md * Adjusted physical characteristic values in theory.md * typo * updated buoy added mass values in doc * updated buoy added mass values, again * Computes added masses and stability derivatives. * Updated notation * Updated values and some new parameters. * Updated stability derivative computations. * Updated install tutorials to reflect Humble/Garden * fixed typo * Now includes first pass at all parameters. * Now includes a first pass at all necessary parameters. * Formats mass matrix into Mkdoc markup with embedded Latex symbols. * Changed inertias and added mass intertias of the three bodies to be consistent.They're about the link frame origin. Updated other parameters and notation. * Updated notation. Reduced the number of significant digits. * Fixed norm symbols, corrected accuracies. * fix typos; reorder added mass in sdf order --------- Signed-off-by: Michael Anderson <[email protected]> Co-authored-by: Andrew Hamilton <[email protected]> Co-authored-by: Andrew Hamilton <[email protected]> Co-authored-by: Michael Anderson <[email protected]> Co-authored-by: Rob McEwen <[email protected]>
osrf · Feb 14, 2023 · 72872c5 · 72872c5
1 parent 7a71869
commit 72872c5
Show file tree

Hide file tree

Showing 27 changed files with 1,159 additions and 103 deletions.
diff --git a/docs/docs/ControlAndTelemetry.md b/docs/docs/ControlAndTelemetry.md
@@ -0,0 +1 @@
+## Telemetry
diff --git a/docs/docs/Tutorials/Install/Install_apt.md b/docs/docs/Tutorials/Install/Install_apt.md
diff --git a/docs/docs/Tutorials/Install/Install_docker.md b/docs/docs/Tutorials/Install/Install_docker.md
@@ -1,3 +1,5 @@
+Docker images that include the neccessary software and dependencies have been created for convenience. 
+
 ##### Requirements
 
 1. Install Docker using [installation instructions.](https://docs.docker.com/engine/install/ubuntu/).
@@ -12,22 +14,23 @@
 
 1. Clone the buoy_entrypoint repository to download the latest Dockerfile.
 
-    ```
-    git clone https://github.com/osrf/buoy_entrypoint.git
-    cd ~/buoy_entrypoint/docker/
-    ```
+```
+$ git clone https://github.com/osrf/buoy_entrypoint.git
+$ cd ~/buoy_entrypoint/docker/
+```
 
 1. Build the docker image
-    
-    ```
-    ./build.bash buoy
-    ```
+
+```
+$ ./build.bash buoy
+```
 
 1. Run the container
 
-    ```
-    ./run.bash [-d|s] buoy:latest
-    ```
+```
+$ ./run.bash [-d|s] buoy:latest
+```
+
     where `./run.bash` option:
     * -d     Use for development with host system volume mount
     * -s     Simulation purposes only
@@ -37,8 +40,18 @@
 
 1. To have another window running the same docker container, run this command in a new terminal:
 
-   ```
-   ./join.bash buoy_latest_runtime
-   ```
+```
+$ ./join.bash buoy_latest_runtime
+```
 
 > The build and run bash scripts are a wrapper around rocker, checkout its [documentation](https://github.com/osrf/rocker) for additional options.
+
+##### Run an example to test
+
+Inside the docker container, run:
+
+```
+$ gz sim mbari_wec.sdf -r
+```
+
+The simulation software should now be available.  To run and test, proceed to the [Run the Simulator](../../../tutorials/#running-the-simulator) tutorial series. 
diff --git a/docs/docs/Tutorials/Install/Install_source.md b/docs/docs/Tutorials/Install/Install_source.md
@@ -0,0 +1,77 @@
+##### Install Requirements
+Use Ubuntu 22.04.
+
+1. Install [ROS 2 Humble](https://docs.ros.org/en/humble/index.html)
+
+Buoy Sim is tested against the cyclonedds rmw implementation, so set that up as follows:
+```
+sudo apt install -y ros-humble-rmw-cyclonedds-cpp
+export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
+```
+
+2. Install [Gazebo Garden](https://gazebosim.org/docs/garden)
+
+
+3. Install necessary tools
+
+```
+$ sudo apt install python3-vcstool python3-colcon-common-extensions python3-pip git wget
+```
+
+##### Buoy Simulation Software Build
+
+1. Create a workspace, for example:
+
+```
+$ mkdir -p ~/buoy_ws/src
+$ cd ~/buoy_ws/src
+```
+
+1. Clone all source repos with the help of `vcstool`:
+
+```
+$ wget https://raw.githubusercontent.com/osrf/buoy_entrypoint/main/buoy_all.yaml
+$ vcs import < buoy_all.yaml
+$ cd ~/buoy_ws
+```
+
+1. Set the Gazebo version to Garden. This is needed because we're not using an
+   official ROS + Gazebo combination:
+
+```
+$ export GZ_VERSION=garden
+```
+
+1. Install ROS dependencies
+
+```
+$ sudo pip3 install -U rosdep
+$ sudo rosdep init
+$ rosdep update
+$ rosdep install --from-paths src --ignore-src -r -y -i
+```
+
+1. Build and install
+
+```
+$ source /opt/ros/humble/setup.bash
+$ cd ~/buoy_ws
+$ colcon build
+```
+
+The simulation software should build without errors.  To run and test, proceed to the [Run the Simulator](../../../tutorials/#running-the-simulator) tutorial series.  Or run a quick test as described below to confirm all has worked as expected.
+
+##### Run an example to test
+
+1. In a new terminal, source the workspace
+
+```
+$ . ~/buoy_ws/install/setup.sh`
+```
+
+1. Launch the simulation
+
+```
+$ ros2 launch buoy_gazebo mbari_wec.launch.py`
+```
+
diff --git a/docs/docs/Tutorials/ROS2/ROS2.md → .../docs/Tutorials/ROS2/ClosedLoopControl.md b/docs/docs/Tutorials/ROS2/ROS2.md → .../docs/Tutorials/ROS2/ClosedLoopControl.md
diff --git a/docs/docs/Tutorials/ROS2/MPC.md b/docs/docs/Tutorials/ROS2/MPC.md
diff --git a/docs/docs/Tutorials/ROS2/MessagesAndServices.md b/docs/docs/Tutorials/ROS2/MessagesAndServices.md
diff --git a/docs/docs/Tutorials/ROS2/OpenLoopControl.md b/docs/docs/Tutorials/ROS2/OpenLoopControl.md
diff --git a/docs/docs/Tutorials/ROS2/Template.md b/docs/docs/Tutorials/ROS2/Template.md
diff --git a/docs/docs/Tutorials/Simulation/RunSimulator.md b/docs/docs/Tutorials/Simulation/RunSimulator.md
@@ -0,0 +1,32 @@
+##### Introduction
+
+This tutorial will illustrate how to start the buoy simulation in Gazebo, when the simulation is running, a rendering of the buoy system motions will be visible, and ROS2 messages will be published that represent the buoy systems state.  The simulation also provides the same ROS2 services the real buoy does, so will respond to ROS2 messages appropriately.
+
+Subsequent tutorials will illustrate how to view and plot data being published by the simulation, view data logs being generated, and control the simulated buoy with the command-line tool that is available on the buoy.
+
+
+##### Run
+To run the simulator, it is necessary to source the workspace in a separate terminal than was used to build the application.  Therefore, open a new terminal window and do the following:
+
+1. Source the workspace
+
+```
+$ . ~/buoy_ws/install/setup.sh
+```
+
+1. Launch the simulation
+
+```
+$ ros2 launch buoy_gazebo mbari_wec.launch.py 
+```
+
+The Gazebo rendering of the buoy system should become visible and appear as follows:
+
+![here](images/BuoyGazebo.png)
+
+To start the simulation, press the "play" arrow in the lower left, the buoy should start to move in response to incoming waves.
+
+It is also possible to adjust various parameters such as the sea-state, visibility of the rendering, and speed the simulation will run relative to real-time.  These topics are covered in a later tutorial.
+
+To view the ROS2 messages and associated data while the simulation runs, proceed to the next tutorial: [View ROS2 Messages](SimulatorOutputROS.md)
+
diff --git a/docs/docs/Tutorials/Simulation/Simulation.md → ...orials/Simulation/SimulatorInteraction.md b/docs/docs/Tutorials/Simulation/Simulation.md → ...orials/Simulation/SimulatorInteraction.md
diff --git a/docs/docs/Tutorials/Simulation/SimulatorOutputLogs.md b/docs/docs/Tutorials/Simulation/SimulatorOutputLogs.md
@@ -0,0 +1,12 @@
+##### Run
+
+1. Source the workspace
+
+    `. ~/buoy_ws/install/setup.sh`
+
+1. Launch the simulation
+
+    `ros2 launch buoy_gazebo mbari_wec.launch.py rviz:=True`
+
+
+![startup](images/Buoy_Gazebo_RViz.png)
diff --git a/docs/docs/Tutorials/Simulation/SimulatorOutputPbcmd.md b/docs/docs/Tutorials/Simulation/SimulatorOutputPbcmd.md
@@ -0,0 +1,12 @@
+##### Run
+
+1. Source the workspace
+
+    `. ~/buoy_ws/install/setup.sh`
+
+1. Launch the simulation
+
+    `ros2 launch buoy_gazebo mbari_wec.launch.py rviz:=True`
+
+
+![startup](images/Buoy_Gazebo_RViz.png)
diff --git a/docs/docs/Tutorials/Simulation/SimulatorOutputPlotjuggler.md b/docs/docs/Tutorials/Simulation/SimulatorOutputPlotjuggler.md
@@ -0,0 +1,23 @@
+"[PlotJuggler](https://www.plotjuggler.io/)" is a plotting program that includes support for ROS2 messages, and allows real-time plotting of data from ROS2 messages while the simulator runs, as well as plotting of logged data.  
+
+- To install, see instructions [here](https://index.ros.org/p/plotjuggler/).  If using the supplied docker images, this step is not necessary as the software is already installed.
+
+- To start, issue the following command in a window where the environment has already been sourced using ```$ . ~/buoy_ws/install/setup.sh```:
+
+```
+$ ros2 run plotjuggler plotjuggler 
+```
+
+- After an entertaining splash-screen, a blank PlotJuggler screen will appear. Under "Streaming" (upper left, second item below "File"), select the "ROS2 Topic Subscriber" option and click "Start".  A new window will appear showing the ROS2 topics available on the system.  Note that the Gazebo Simulator of the buoy must be running for the ROS2 topics that contain the buoy data to be present.
+
+Select the /arhs_data, /power_data, /spring_data, battery_data, heavecone_data and /xb_data topics and click "OK"
+
+- The selected topics will appear in the "Timeseries List" window, and selecting the carot to the left of each topic will expand them and show the data that can be plotted.  Note that these topics and data are the same as are visible using the ```$ ros2 topic list``` and ```$ ros2 topic echo ...``` commands from the command-line.
+
+
+- Dragging any data item into the plot field on the right will plot that data on a scrolling graph. The time-extent of the graph can be changed using the "Buffer" text-box under the "Streaming" box in the upper left.  Graphs can be split horizontally and vertically to make room for more data items, see this guide for information on manipulating the PlotJuggler windows.
+
+- After a bit of data selection, the window can look like the example below and show many data items in real-time.  Under the "File" box in the upper left, there are options to save and retrieve this layout to avoid setting up the windows at each invocation of PlotJuggler.  PlotJuggler will continue to run through re-starts of the simulator, so it is often not necessary to re-start PlotJuggler often.
+
+
+![](images/PlotJuggler.png)
diff --git a/docs/docs/Tutorials/Simulation/SimulatorOutputROS.md b/docs/docs/Tutorials/Simulation/SimulatorOutputROS.md
@@ -0,0 +1,53 @@
+##### ROS2 Message
+
+While running, the simulator generates exactly the same ROS2 messages that the buoy hardware does during operation.  These are grouped into ROS2 topics that corresponds to data being produced by each micro-controller or instrument on the buoy.  To see all ROS2 topics being published to on the system, issue the following command (after sourcing the workspace if needed in a new terminal ``` $ . ~/buoy_ws/install/setup.sh```
+
+``` 
+$ ros2 topic list 
+/ahrs_data
+/clock
+/joint_states
+/parameter_events
+/power_data
+/rosout
+/spring_data
+/tf
+/tf_static
+/xb_imu
+```
+
+The topics /ahrs_data, /battery_data, /spring_data, /power_data, and /heavecone_data coorespond to the buoy-based instrumentation (AHRS), battery controller, spring controller, power-converter controller, and heave-cone controller.  To see the data being published in these topics, issue the following command and the data will scroll by:
+
+```
+$ ros2 topic echo power_data
+---
+header:
+  stamp:
+    sec: 712
+    nanosec: 710000000
+  frame_id: ''
+seq_num: 6703
+rpm: 369.927978515625
+sd_rpm: 0.0
+voltage: 313.98431396484375
+draw_curr_limit: 0.0
+bcurrent: -0.14509780704975128
+wcurrent: -0.2554447054862976
+torque: 0.0
+diff_press: 2.9100000858306885
+bias_current: 0.0
+loaddc: 0.0
+scale: 1.0
+retract: 0.6000000238418579
+target_v: 0.0
+target_a: -0.2554447054862976
+charge_curr_limit: 0.0
+status: 0
+---
+```
+
+The data in each topic corresponds to the message descriptions which can be seen here along wit a description of each field.
+
+Several of these topics are only available in simulation, and only /ahrs_data, /battery_data, /spring_data, /power_data, and /heavecone_data will be present on the real buoy.
+
+The next tutorial "[View Messages with Plotjuggler](SimulatorOutputPlotjuggler.md)" shows how to conveniently plot these data items while the simulator is running.
diff --git a/docs/docs/Tutorials/Simulation/SimulatorParameters.md b/docs/docs/Tutorials/Simulation/SimulatorParameters.md
@@ -0,0 +1,9 @@
+##### Start-up parameters
+There are a number of parameters that change the behavior of the simulator, and must be specified at start-up:
+
+- Sea-State: This is specified as a Wave Height and Period.  If a positive value of wave-period is specified, a Pierson-Moskowitch spectrum with the specfied significant wave-height and peak-period is used.  If a negative value of wave-period is specified, a mono-chromatic incoming wave at the specified period and height is used.
+- Real-time factor:  This specifies how fast the simulator will run.  A real-time factor of 1.0 cooresponds to the simulation time proceeding at the same speed as the wall-clock.  A larger value runs the simulator faster than real-time, practical upper limits on normal hardware are a real-time factor of about 30, and if this is not possible the simulator will run as fast as possible.
+- Heave-cone door position:  The simulation can be run with the heave-cone doors either open, or closed. This can not be changed while the simulation is running.
+- Simulation Rendering: The simulator can be run with our without a visual rendering of the system.  The simulator may run faster without the rendering graphics.
+
+##### Run-time control
diff --git a/docs/docs/Tutorials/Simulation/images/BuoyGazebo.png b/docs/docs/Tutorials/Simulation/images/BuoyGazebo.png
diff --git a/docs/docs/images/Buoy_Gazebo_RViz.png → ...ls/Simulation/images/Buoy_Gazebo_RViz.png b/docs/docs/images/Buoy_Gazebo_RViz.png → ...ls/Simulation/images/Buoy_Gazebo_RViz.png
diff --git a/docs/docs/Tutorials/Simulation/images/PlotJuggler.png b/docs/docs/Tutorials/Simulation/images/PlotJuggler.png