Supervisor 1.1 doc (#39)

.github/workflows/docs.yml → .github/workflows/build_doc.yml

@@ -1,6 +1,7 @@
-name: Documentation
+name: Build Documentation
 
 on:
+  workflow_call: ~
   workflow_dispatch: ~
   push:
     branches: [master]
@@ -16,6 +17,7 @@ jobs:
           python-version: "3.10"
 
       - name: Install dependencies
+        shell: bash
         run: |
           sudo apt-get install -y sed jq git
           pip install --upgrade sphinx_rtd_theme myst-parser sphinx docutils sphinx-sitemap sphinxcontrib-spelling sphinx-tabs sphinxcontrib-youtube pygments breathe sphinx-copybutton
@@ -36,9 +38,3 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: gh-pages
           publish_dir: ./gh-pages
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: DocumentationHTML
-          path: gh-pages

.github/workflows/publish_release.yml

@@ -0,0 +1,21 @@
+name: publish release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_name:
+        description: "Version name"
+        required: true
+
+jobs:
+  build_docs:
+    uses: ./.github/workflows/build_doc.yml
+
+  edit_release:
+    runs-on: ubuntu-latest
+    needs: [build_docs]
+    steps:
+      - name: Edit release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release edit supervisor_${{inputs.version_name}} --draft=false

docs/sources/getting_started.rst

@@ -97,7 +97,7 @@ The initial view of the Control Panel is the "Configuration" page, which consist
 4. Interface with your stack
 *****************************
 
-In order to perform collision avoidance maneuvers, the Supervisor must be able to send commands to your robot actuators. These commands will be published on the ``/lll/ram/filtered_input`` topic.
+In order to perform collision avoidance maneuvers, the Supervisor must be able to send commands to your robot actuators. These commands will be published by default on the ``/lll/ram/filtered_input`` topic (this is a customizable name via the Control Panel.
 
 Your low-level controller therefore needs to subscribe to this topic and apply the commands to your robot:
 
@@ -106,7 +106,7 @@ Your low-level controller therefore needs to subscribe to this topic and apply t
   :width: 600px
   :alt: Operations page showing a configured robot that does not yet have sensor or planning data.
 
-For that, you can either create an extra dedicated subscriber in your low-level control stack to receive the commands from the Supervisor, or you can use ROS topic remapping feature to remap the low-level controller subscription from ``/cmd`` to ``/lll/ram/filtered_input``:
+For that, you can either create an extra dedicated subscriber in your low-level control stack to receive the commands from the Supervisor, or you can use ROS topic remapping feature to remap the low-level controller subscription from ``/cmd`` to ``/lll/ram/filtered_input`` (default):
 
 .. tabs::
   .. tab:: ROS1

docs/sources/troubleshooting.rst

@@ -26,7 +26,7 @@ Try launching Supervisor from a terminal to see what error messages appear. Supe
 
 Supervisor may also keep the platform stationary if the LIDAR data or the list of obstacles is not delivering data quickly enough.  This design ensures that if Supervisor does not have sufficient information about surrounding collision candidates, it does not allow the platform to proceed.  A good strategy is to start up the Operations tab for Control Panel (with Rosbridge) and see if any of the input blocks (desired input, state, perception) is a color other than green.
 
-Another cause of platform failing to move is that the topic routing is not correct.  The ROS ``rqt`` tool with the Node Graph can visually display the routing well.  Verify that the desired inputs (e.g. cmd_vel_plan) are coming into Supervisor, and that Supervisor's outputs (e.g. /lll/ram/filtered_input) is properly mapped to the signal that the lower layer is expecting (e.g. cmd_vel).
+Another cause of platform failing to move is that the topic routing is not correct.  The ROS ``rqt`` tool with the Node Graph can visually display the routing well.  Verify that the desired inputs (e.g. cmd_vel_plan) are coming into Supervisor, and that Supervisor's outputs (e.g. /lll/ram/filtered_input by default) is properly mapped to the signal that the lower layer is expecting (e.g. cmd_vel).
 
 My robot doesn't move when I send a command
 ============================================

docs/sources/user_guide/configuration/supervisor.rst

@@ -48,7 +48,7 @@ General Parameters
 
 * **Desired control input**: This is the set of commands requesting speed and rotation (or speed and steering) that the autonomy stack is publishing. The ROS message type is needed so that Supervisor knows what to monitor in order to calculate the barrier function value. The message quality and receipt rate are monitored as part of the aggregated metrics, and if it fails to arrive within the expected time [1/(signal rate) * Timeout factor], an event will be created and the Run-time Assurance Module will transition to the failure command mode.
 
-* **Computed safe control input**: The right side of this area is purely informational. However, if the robot is to be controlled by the run-time assurance signal, it needs to subscribe to the message that is presented here. Alternatively, the launch file for Supervisor can be modified so that */lll/ram/filtered_input* is remapped to the command signal expected by the platform.
+* **Computed safe control input**: This is the output of the supervisor Run-time Assurance Module. This topic configuration can mirror the Desired control input one or have a different message type and QoS (the rate is set by the :ref:`filter rate <config_sup_filter_rate>`). The message type can be: the same as received on the Desired control input, an equivalent one (You can convert from timestamped message to non timestamped, with or without covariance for example) or a dynamic type like lll_msgs/Float64VectorStamped or std_msgs/Float[32/64]MultiArray. This limitations are due to the fact that converting types to others can lead to loss of message information. ROS has semantic messages and converting message from a type to another can lead to various errors and misinterpretations.
 
 * **Parameters > Activate**: This checkbox controls whether the run-time assurance intercepts and modifies commands from the planner/trajectory generator and forwards modified versions to the vehicle. The Run-time Assurance Module will only modify the outputs if the option is activated. If it is not activated, the unmodified "desired control input" will be transmitted on the designated "Computed safe control" message.  Additionally, when activated the Run-time Assurance Module passes the unmodified desired input through to the platform except when a corrective action is needed.
 
@@ -126,6 +126,6 @@ Supervisor activation logic
 .. image:: ../../data/supervisor_activation_logic.png
    :width: 800px
 
-The bottom section relates to republishing the control commands to the robot that are being sent from the autonomy stack. The values will be published on the *lll/ram/filtered_input* channel if the Run-time Assurance Module is activate or not. However, the values will only be different from the *Desired control input* if the Run-time Assurance Module is active.
+The bottom section relates to republishing the control commands to the robot that are being sent from the autonomy stack. The values will be published on the *lll/ram/filtered_input* (default topic name, can be customized) channel  if the Run-time Assurance Module is activate or not. However, the values will only be different from the *Desired control input* if the Run-time Assurance Module is active.
 
 * **Finite States** are messages that the Diagnostics can listen to and issue events when the value of the finite state matches a predefined value.

docs/sources/user_guide/reference/ros_topics.rst

@@ -18,7 +18,7 @@ Run-time Assurance Module
 
 When the Supervisor filter (Run-time Assurance Module) is enabled, the following additional topics are published:
 
-- ``/lll/ram/filtered_input``: The filtered velocity command that is sent to the robot's actuators when the Supervisor receives inputs from the planner/upstream.  Note that this signal may be remapped to match the name of the input the downstream systems expects.
+- ``/lll/ram/filtered_input`` (default): The filtered velocity command that is sent to the robot's actuators when the Supervisor receives inputs from the planner/upstream.  Note that this signal may be remapped or renamed to match the name of the input the downstream systems expects.
 
 - ``/lll/ram/markers``: Visualization tools such as RVIZ and FoxGlove can subscribe to this signal in order to display the illustrated vectors between the robot and obstacles that the Supervisor uses to make decisions on modifications to the input signal.  The image below shows an rviz2 display where the red box represents the robot, the blue vectors represent the vector between a sensed laser point and the closest point on the robot's boundary, and the green dots represent laser scan points that are being actively monitored by Supervisor. These values are all embedded into the ``/lll/ram/metadata``.  The white dots are the 2D laser scan points that are subscribed-to separately.