Added wiki docs for workflows, plus corrected small errors.

docs/hardware/gpio.rst

@@ -100,3 +100,13 @@ To read the value, :code:`{0,1}`, from the GPIO pin, used the command:
 	sudo gpioget <gpio_chip_name> <line_number>
 
 For example, if the input is connected to pin 18 of the J21 expansion header, then according to the table above pin 18 connects to line 161 of the :code:`tegra-gpio` chip. Hence you can read the value of pin 18 with the
+
+.. code-block:: bash
+
+	sudo gpioget tegra-gpio 161
+
+To monitor a line for multiple of a particular event, use the following:
+
+.. code-block:: bash
+
+	sudo gpiomon --num-events=3 --rising-edge tegra-gpio 161

docs/hardware/power_bank_voltaic_v88.rst

@@ -62,10 +62,10 @@ Power a Robot
 1. :ref:`Turn on <voltaic-v88-on-off>` the Voltaic V88 power bank.
 2. If the Voltaic V88 has two or fewer bars, then :ref:`charge it <voltaic-v88-charge-from-ac>` before proceeding.
 3. :ref:`Select the voltage <voltaic-v88-change-voltage>` necessary for your robot.
-4. Pur the Voltaic V88 in :ref:`Always On Mode <voltaic-v88-always-on>`.
-5. Plug in the DC cable to the **DC Output Port** if the Voltaic V88.
-6. Plug in the DC cable to the DC power jack of your robot.
-7. Press the power button on the Voltaic V88 to begin powering your robot.
+4. :ref:`Turn off <voltaic-v88-on-off>` the Voltaic V88 power bank.
+5. Connect the power jack of your robot to the **DC Output Port** of the Voltaic V88.
+6. Press the power button on the Voltaic V88 to begin powering your robot.
+7. Put the Voltaic V88 in :ref:`Always On Mode <voltaic-v88-always-on>` to prevent an unexpected shutdown during periods of low current draw.
 
 .. warning:: Do NOT simultaneously charge the Voltaic V88 power bank and use it to power your robot.
 

docs/hardware/sbc_jetson_xavier_nx.rst

@@ -83,24 +83,26 @@ The following table summarises the mapping:
 	|       | Ground         |  9 | 10 | UART1_RX       |       |
 	|   140 | UART1_RTS      | 11 | 12 | I2S0_SCLK      |   157 |
 	|   192 | SPI1_SCK       | 13 | 14 | Ground         |       |
-	|    20 | GPIO 12        | 15 | 16 | SPI1_CS1       |   196 |
+	|  ^ 20^| GPIO 12        | 15 | 16 | SPI1_CS1       |   196 |
 	|       | 3.3V Supply    | 17 | 18 | SPI1_CS0       |   195 |
 	|   205 | SPI0_MOSI      | 19 | 20 | Ground         |       |
 	|   204 | SPI0_MOSO      | 21 | 22 | SPI1_MISO      |   193 |
 	|   203 | SPI0_SCK       | 23 | 24 | SPI0_CS0       |   206 |
 	|       | Ground         | 25 | 26 | SPI0_CS0       |   207 |
-	|       | I2C0           | 27 | 28 | I2C0 SCL       |       |
+	|       | I2C0 SDA       | 27 | 28 | I2C0 SCL       |       |
 	|   133 | GPIO 01        | 29 | 30 | Ground         |       |
 	|   134 | GPIO 11        | 31 | 32 | GPIO 07        |   136 |
 	|   105 | GPIO 13        | 33 | 34 | Ground         |       |
 	|   160 | I2S_FS         | 35 | 36 | UART1_CTS      |   141 |
 	|   194 | SPI1_MOSI      | 37 | 38 | I2S0_SDIN      |   159 |
-	|       | Ground         | 25 | 26 | I2S0_SDOUT     |   158 |
+	|       | Ground         | 39 | 40 | I2S0_SDOUT     |   158 |
 	|-------|----------------|---------|----------------|-------|
 
 
+.. note::
+	Pins (3,5) correspond to I2C bus 8, and pins (27,28) correspond to I2C bus 1. Hence the connected devices can be quickly checked from command line using: :code:`sudo i2cdetect -y -r <bus_number>` where :code:`<bus_number>` is replaced by 8 or 1.
+
 ..
 	.. note:: the :code:`Tegra line` numbers marked with exclamation marks, i.e., of the form :code:`!xxx!`, should **NOT** be used as GPIO pins. The information displayed by :code:`sudo gpioinfo tegra-gpio` lists these lines as :code:`unused`, but they should still **NOT** be used as GPIO pins
 
-..
-	.. note:: the :code:`Tegra line` numbers marked with hats, i.e., of the form :code:`^xxx^`, did not work when tested without additional configuration..
+.. note:: the :code:`Tegra line` numbers marked with hats, i.e., of the form :code:`^xxx^`, did not work when tested without additional configuration..

docs/index.rst

@@ -21,6 +21,8 @@ This wiki is expected to grow and expand as semester progresses, and everyone is
 	hardware/power_supply
 	hardware/single_board_computers
 	hardware/communication_protocols
+	software/workflows
+
 
 
 

docs/software/ros_cmd_line_basics.rst

@@ -12,6 +12,14 @@ The `ROS Tutorials <http://wiki.ros.org/ROS/Tutorials>`_ are a great place to st
 * `Understanding ROS Nodes <http://wiki.ros.org/ROS/Tutorials/UnderstandingNodes>`_
 
 
+What is ROS?
+************
+The best answer to this is given on the `ROS wiki page <http://wiki.ros.org/ROS/Introduction>`_ where it states:
+
+* *ROS is an open-source, meta-operating system for your robot. It provides the services you would expect from an operating system, including hardware abstraction, low-level device control, implementation of commonly-used functionality, message-passing between processes, and package management. It also provides tools and libraries for obtaining, building, writing, and running code across multiple computers*
+
+See the `home page of the ROS wiki <http://wiki.ros.org>`_ for the familiarising with various aspects of ROS.
+
 Compiling
 *********
 

docs/software/workflow_git_merge_from_upstream_fork.rst

+.. _workflow-git-merge-from-upstream-fork:
+
+Git Merge from Upstream Fork
+============================
+
+If you created your :code:`asclinic-system` repository as a fork of:
+
+https://gitlab.eng.unimelb.edu.au/asclinic/asclinic-system
+
+then it will be beneficial to occasionally synchronise, i.e., merge, changes from that "original" repository into your fork.
+To understand the descriptions below, the key terminology is that the "original" :code:`asclinic-system` repository that you forked is referred to as the "upstream" repository.
+
+This `repository mirroring entry <https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#repository-mirroring>`_ in the GitLab documentation, the the links therein, provide a description for how to synchronise changes via the website.
+
+Alternatively, you can synchronise changes by the following command line commands.
+
+
+Add the upstream remote
+***********************
+
+1. Your repository needs to be configured to have the upstream repository as a so-called :code:`remote`. Add the upstream repository using the command:
+
+.. code-block:: bash
+
+	git remote add upstream https://gitlab.eng.unimelb.edu.au/asclinic/asclinic-system.github
+
+2. Verify that step 1 worked by observing the output displayed by the command:
+
+.. code-block:: bash
+
+	git remote -v
+
+**Note** that these two steps above only need to be performed once for the repository.
+
+
+Merge in changes from the upstream remote
+*****************************************
+
+1. Fetch changes from the upstream repository using the command:
+
+.. code-block:: bash
+
+	git fetch upstream
+
+2. Checkout the, i.e., change to, the master branch of your local repository:
+
+.. code-block:: bash
+
+	git checkout master
+
+3. Merge the changes from the master branch of the upstream repository, i.e., from :code:`upstream/master`, into the master branch of your local repository:
+
+.. code-block:: bash
+
+	git merge upstream/master
+
+If there are merge conflicts, these will need to be handled in the usual fashion.

docs/software/workflow_gpio_single_pin.rst

+.. _workflow-gpio-single-pin:
+
+ROS Interface with a Single GPIO Pin
+====================================
+
+Once the device is physically connected to a GPIO, and before attempting to interface using ROS, you should use the command line tool to check the device is properly connected.
+See the :ref:`GPIO page <comm-protocol-GPIO>` for details of the command line tools, and see the :ref:`SBC page <single-board-computers>` for details of the GPIO pins for the relevant SBC.
+
+
+For example, if the input is connected to pin 7 of the J21 expansion header of the Jetson Xavier NX, then this corresponds to line 148 of the :code:`gpiochip0` chip. Hence you can read the value of pin 7 with the command:
+
+.. code-block:: bash
+
+	sudo gpioget gpiochip0 148
+
+To monitor a line for multiple of a particular event, use the command:
+
+.. code-block:: bash
+
+	sudo gpiomon --num-events=3 --rising-edge gpiochip0 148
+
+To interface with a single GPIO pin via a ROS node, there are two templates provided:
+
+* The file named :code:`template_gpio_event_triggered.cpp`: this template monitors the GPIO line for events (i.e., a rising and/or falling edge), and publishes a message each time an event occurs.
+* The file named :code:`template_gpio_polling.cpp`: this template check the value of the GPIO line at a fixed frequency.
+
+Both files are located in the repository at the relative file path:
+
+.. code-block:: bash
+
+  catkin_ws/src/asclinic_pkg/src/nodes/
+
+Both files are extensively commented and the comments serve as the documentation for how to edit the file to implement your use case.
+The GPIO templates are C++ files because the library used for interfacing with the GPIO pins is C++ based.
+There does exist Python bindings for the GPIO library, but that is not currently developed as part of this repository.
+
+Both template nodes are launched by file :code:`template_gpio.launch`.
+You should review the launch file to check how it is structure to add a parameter to each node upon launch (see also the note below).
+Then you can launch the template GPIO nodes with:
+
+.. code-block:: bash
+
+  roslaunch asclinic_pkg template_gpio.launch
+
+
+
+.. note::
+  `This website <https://libgpiod-dlang.dpldocs.info/gpiod.html>`_ provides a comprehensive list of all the function offered by the :code:`gpiod` library for monitoring a GPIO pin.
+
+
+
+.. note::
+  The line number to monitor is specified as a parameter in the launch file.
+  Hence, to change the line number being monitored, you simply need to change the line number parameter in the launch file and re-launch the node.
+
+  * This has the benefit that you can change the line number without needing to recompile the code.
+  * This has the disadvantage that you cannot specify the line number parameter when using :code:`rosrun`.
+
+
+
+.. note::
+  When you copy either template C++ file, you will need to add it to the :code:`CMakeLists.txt` file in the repository at the relative file path:
+
+  .. code-block:: bash
+
+    catkin_ws/src/asclinic_pkg/CMakeLists.txt
+
+  Simply duplicate and accordingly edit the lines where the name of the respective template GPIO C++ file appears.
+  Most important is that the :code:`target_link_libraries(...)` needs the compile link flag :code:`-lgpiod` at the end.
+
+  .. code-block:: bash
+
+    target_link_libraries(template_gpio ${catkin_LIBRARIES} -lgpiod)

docs/software/workflow_i2c.rst

+.. _workflow-i2c:
+
+ROS Interface with an I2C Bus
+=============================
+
+Once the device is physically connected to an I2C bus, and before attempting to interface using ROS, you should use the command line tool to check the device is properly connected.
+See the :ref:`I2C page <comm-protocol-i2c>` for details of the command line tools, and see the :ref:`SBC page <single-board-computers>` for details of the I2C buses for the relevant SBC.
+
+
+For example, if the device is connected to the I2C bus of pins (3,5) of the J21 expansion header of the Jetson Xavier NX, then this corresponds to I2C bus 8. Hence the addresses of the connected devices can be quickly checked with the command:
+
+.. code-block:: bash
+
+	sudo i2cdetect -y -r 8
+
+To interface with I2C devices via a ROS node, there are two templates provided:
+
+* The file named :code:`template_i2c_external.cpp`: this template manages the I2C bus for devices connected to the exterior of the robot. In the default build wiring configuration, this is I2C bus 8 of the Jetson Xavier NX.
+* The file named :code:`template_i2c_internal.cpp`: this template manages the I2C bus for devices connected in the interior of the robot. In the default build wiring configuration, this is I2C bus 1 of the Jetson Xavier NX.
+
+Both files are located in the repository at the relative file path:
+
+.. code-block:: bash
+
+  catkin_ws/src/asclinic_pkg/src/nodes/
+
+Both files are extensively commented and the comments serve as the documentation for how to edit the file to implement your use case.
+The I2C templates are C++ files because the library used for interfacing with the I2C buses is C++ based, and hence the driver developed for the I2C devices are also written in C++.
+
+Both template nodes are launched by file :code:`template_i2c.launch`.
+You should review the launch file to check how it is structured.
+Then you can launch the template I2C nodes with:
+
+.. code-block:: bash
+
+  roslaunch asclinic_pkg template_i2c.launch
+
+
+..
+	You should review the launch file to check how it is structured to add a parameter to each node upon launch (see also the note below).
+
+
+..
+	.. note::
+	  The I2C bus to manage is specified as a parameter in the launch file.
+	  Hence, to change the bus number being managed, you simply need to change the line number parameter in the launch file and re-launch the node.
+
+	  * This has the benefit that you can change the bus number without needing to recompile the code.
+	  * This has the disadvantage that you cannot specify the line number parameter when using :code:`rosrun`.
+
+
+
+.. note::
+  When you copy either template C++ file, you will need to add it to the :code:`CMakeLists.txt` file in the repository at the relative file path:
+
+  .. code-block:: bash
+
+    catkin_ws/src/asclinic_pkg/CMakeLists.txt
+
+  Simply duplicate and accordingly edit the lines where the name of the respective template I2C C++ file appears.
+  Most important is that the :code:`add_executable(...)` needs to list the executable files for any I2C driver that in included by the node. For example, the :code:`template_i2c_external` node has the following :code:`add_executable(...)` in the :code:`CMakeLists.txt` file:
+
+	.. code-block:: bash
+
+		add_executable(template_i2c_external
+			src/nodes/template_i2c_external.cpp
+			src/drivers/src/i2c_driver/i2c_driver.cpp
+			src/drivers/src/vl53l1x/vl53l1x.cpp
+			src/drivers/src/vl53l1x/core/VL53L1X_api.c
+			src/drivers/src/vl53l1x/platform/vl53l1_platform.c
+			)
+
+
+.. note::
+
+	You can view the source code of the available drivers at the relative path:
+
+	.. code-block:: bash
+
+		catkin_ws/src/asclinic_pkg/src/drivers/src/

docs/software/workflows.rst

+.. _workflows:
+
+WORKFLOWS
+=========
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  workflow_git_merge_from_upstream_fork
+  workflow_gpio_single_pin
+  workflow_i2c
+
+
+
+The following workflows are intended to assist you to get familiar with the various parts of the software for the robot:
+
+* Workflow for: :ref:`Git merging changes from an upstream fork into your repository <workflow-git-merge-from-upstream-fork>`.
+* Workflow for: :ref:`ROS interface with a single GPIO pin <workflow-gpio-single-pin>`.
+* Workflow for: :ref:`ROS interface with an I2C bus <workflow-i2c>`.