clearpath-docs · civerachb-cpr · May 15, 2018 · Jul 23, 2019 · Jul 23, 2019 · Mar 10, 2020
diff --git a/doc/cartographer.rst b/doc/cartographer.rst
@@ -0,0 +1,64 @@
+Jackal Cartographer Demo
+===========================
+
+This tutorial shows you how to use `move_base <http://wiki.ros.org/move_base>`_ with `Google Cartographer <https://github.com/googlecartographer>`_ to perform autonomous planning and movement with simultaneous localization and mapping (SLAM), on a simulated Jackal, or a factory-standard Jackal with a laser scanner publishing on the */front/scan* topic.
+
+To adapt this demo to your own Jackal, you may need to clone the `jackal_cartographer_navigation <http://github.com/jackal/jackal_cartographer_navigation.git>`_ repository, and modify the relevant parameters. To learn about move_base and the navigation stack, see the `Navigation Tutorials <http://wiki.ros.org/navigation/Tutorials>`_. To learn more about Google Cartographer for ROS, see the `Cartographer ROS <https://google-cartographer-ros.readthedocs.io/en/latest/>`_ documentation.
+
+Instructions
+-------------
+
+1. To get started with 2-D SLAM using Google Cartographer, clone this repository into your working directory:
+
+.. code-block:: bash
+
+    git clone http://github.com/jackal/jackal_cartographer_navigation.git
+
+2. Run the following script to create a workspace and install proto3. This script will also install the packages required to use Cartographer as well as the `jackal_desktop <https://github.com/jackal/jackal_desktop>`_, `jackal <https://github.com/jackal/jackal>`_, and `jackal_simulator <https://github.com/jackal/jackal_simulator>`_ packages:
+
+.. code-block:: bash
+
+    source $(pwd)/jackal_cartographer_navigation/protobuf3_local.sh
+
+3. Open three new terminal/tabs, source the workspace for each terminal/tab:
+
+.. code-block:: bash
+
+    source install_isolated/setup.bash
+
+3.1 Launch the Gazebo simulation with the *front_laser* config:
+
+.. code-block:: bash
+
+    roslaunch jackal_gazebo jackal_world.launch config:=front_laser
+
+3.2 Launch RViz to visualize the robot:
+
+.. code-block:: bash
+
+    roslaunch jackal_viz view_robot.launch config:=gmapping
+
+3.3 Launch the Cartographer node to begin SLAM:
+
+.. code-block:: bash
+
+    roslaunch jackal_cartographer_navigation cartographer_demo.launch
+
+4. In the Rviz visualizer, make sure the visualizers in the Navigation group are enabled.
+
+5. Use the 2D Nav Goal tool in the top toolbar to select a movement goal in the visualizer. Make sure to select an unoccupied (dark grey) or unexplored (light grey) location.
+
+6. As the robot moves, you should see the grey static map (map topic) grow. There might be discrete jumps in the map as the Cartographer algorithm attempts to localize the robot.
+
+7. To save the generated map, you can run the map_saver utility:
+
+.. code-block:: bash
+
+    rosrun map_server map_saver -f <filename>
+
+Tuning Cartographer
+---------------------
+
+To tune Cartographer for low latency SLAM, edit the *jackal.lua* configuration file found in the *jackal_cartographer_navigation/config* directory.
+
+For more information on tuning, click `here <http://google-cartographer-ros.readthedocs.io/en/latest/tuning.html>`_.
diff --git a/doc/conf.py b/doc/conf.py
@@ -40,10 +40,10 @@
 }
 
 rst_prolog = """
-.. |ros_distro| replace:: kinetic
-.. |ubuntu_distro| replace:: xenial
+.. |ros_distro| replace:: melodic
+.. |ubuntu_distro| replace:: bionic
 """
-#.. ubuntu_distro: xenial
+#.. ubuntu_distro: bionic
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = False

diff --git a/doc/flashcomplete.png b/doc/flashcomplete.png
diff --git a/doc/img1.JPG b/doc/img1.JPG
diff --git a/doc/img2.JPG b/doc/img2.JPG
diff --git a/doc/img3.JPG b/doc/img3.JPG
diff --git a/doc/img4.JPG b/doc/img4.JPG
diff --git a/doc/img5.JPG b/doc/img5.JPG
diff --git a/doc/img6.JPG b/doc/img6.JPG
diff --git a/doc/index.rst b/doc/index.rst
@@ -4,7 +4,6 @@ Jackal UGV Tutorials
 .. image:: jackal_banner.png
     :alt: Jackal Robot
 
-
 This package supplies Sphinx-based tutorial content to assist you with setting up and operating your Jackal_
 mobile robot. The tutorials topics are listed in the left column, and presented in the suggested reading order.
 
@@ -36,6 +35,8 @@ skip the introductory chapters and jump straight to these ones.
     startup
     calibration
     update
+    jetson
+    cartographer
 
 .. toctree::
     :titlesonly:

diff --git a/doc/jetson.rst b/doc/jetson.rst
@@ -0,0 +1,107 @@
+Installing a Jetson TX2 on a Jackal
+=====================================
+
+Start by opening up the Jackal to reveal the computer tray. Use the lever on the front of the Jackal then the thumb screws on the lid. For more instructions refer to the `Jackal User's Manual <http://bit.ly/1f4hmqP>`_.
+
+Step 1: Remove mini-ITX Computer
+--------------------------------
+
+(Skip this step if you don't have a computer)
+
+If you have a mini-ITX computer installed it will need to be removed. With the computer tray open locate each of the cables connected to the motherboard and harddrive. Remove the power, power switch, USB and SATA cables. The two cable ties can be cut to completely remove the power and SATA cables. The two antenna cables are connected underneath. Keep this in mind for the next steps.
+
+.. image:: img1.JPG
+
+Remove the four (4) hex screws from the motherboard using a 2.5mm wrench. Gently lift it out disconnecting the antenna connectors as you do so.
+
+.. image:: img2.JPG
+
+Remove the zipties holding the USB header, power switch signal and antenna wire. The Jetson TX2 doesn't have a USB header so it will have to be replaced with a USB mini cable. You will need extra slack in both the antenna cable and power switch signal as well.
+
+.. image:: img3.JPG
+
+Step 2: Install the TX2
+------------------------
+Install the Jetson TX2 using M3 screws or the screws removed from the computer. The holes will only line up in one orientation. Plug a USB mini cable from the Jetson to the Jackal MCU board.
+
+.. image:: img4.JPG
+
+This is beside where the USB header was removed if you had a computer. We recommend using a USB hub to increase the number of connected devices.  Plug the power switch cable into the power switch header (J6). If you wish to use the antenna cables attached to the Jackal remove the U.FL connectors from the Jetson module and connect the antenna cables. Caution: Take your time with this step the UF.L connectors are fragile.  If you wish not to disconnect the UF.L cables you can replace the antenna mounts on the Jackal with SMA extensions.
+
+In order to power the Jetson make a cable which connects to the 12V user power to a barrel connector with center positive. Refer to the Jackal manual for the pinout of the user power. We used one of the molex user power connectors.
+
+.. image:: img5.JPG
+
+**Warning:** Make sure not to plug this into the ITX power plug on the power distribution board.
+
+Step 3: Installing the software
+--------------------------------
+
+`Download the latest version of Nvidia's SDK Manager <https://developer.nvidia.com/nvidia-sdk-manager>`_ on a PC running Ubuntu 18.04.  While that's downloading, put the TX2 into reovery mode by following these steps:
+
+1.  Connect the TX2 to your PC using the provided microUSB cable.
+2.  Make sure the TX2 is powered off
+3.  Connect a monitor, mouse, and keyboard to the Jetson.  (The mouse is optional, but recommended.  If you do not have an all-in-one mouse+keyboard you will need to use a small USB hub, as the Jetson TX2 only has a single USB port.)
+4.  Press and hold the REC button
+5.  Press the power button.
+
+Install the SDK Manager by running the following commands:
+
+.. code-block:: bash
+
+    cd <folder where you downloaded SDK manager>
+    sudo dpkg -i sdkmanager_<version>_amd64.deb
+
+.. note::
+
+    If your system is missing dependencies you may see error messages in the output of the ``dpkg`` command.  To resolve these, run ``sudo apt-get -f install``.
+
+Once SDK Manager is installed, run it with the ``sdkmanager`` command.  `Follow SDK Manager's instructions <https://docs.nvidia.com/sdk-manager/install-with-sdkm-jetson/index.html>`_ to install the operating system and Nvidia components on your Jetson TX2.  During installation you will be asked to configure the login information on the Jetson.  To do this, use the monitor & keyboard you connected before to enter the username and password you want to use.
+
+.. note::
+
+    For compatibility with older versions of the Jetson TX2 software, we recommend setting the username and password to ``nvidia``.
+
+Once the OS has been written to the TX2, log into it and run the following commands to configure it for use with Jackal:
+
+.. code-block:: bash
+
+    curl -s https://raw.githubusercontent.com/clearpathrobotics/jetson_setup/melodic/scripts/tx2_setup.sh | bash -s --
+    bash JACKAL_SETUP.sh
+
+These commands will download and install ROS along with the necessary APT packages to get Jackal up and running.  Depending on your network speed it may take a long time for everything to install.  Reboot the TX2 after these commands are done to complete the configuration.
+
+When the Jetson starts up again, it should be connected to the Jackal. To see that the Jackal is connected by opening a terminal and executing "rostopic echo /status". You should see a 1hz message containing the Jackal's diagnostic information.
+
+Your Jetson TX2 should now be configured to operate as the Jackal's main PC.  See :doc:`Extending Jackal Startup <startup>` for more on how to configure Jackal's accessories.
+
+If you would like to pair a PS4 controller to drive the Jackal, hold down the PS and Share buttons on the controller until the light bar starts to flash. In a terminal on the Jackal, run ``bluetoothctl`` and then run the following commands:
+
+.. code-block:: text
+
+    agent on
+    scan on
+    < look for the MAC address of your controller; it will be identified by "Wireless Controller" or similar text >
+    scan off
+    pair <MAC ADDRESS>
+    trust <MAC ADDRESS>
+    connect <MAC ADDRESS>
+    < ctrl + d to exit >
+
+The light on the controller will turn solid blue once it is paired. With the controller paired you should be able to control the Jackal by pressing L1 and using the left stick to drive. For more information see the Jackal manual.
+
+To use your host computer with the Jackal first `install ROS <http://wiki.ros.org/|ros_distro|/Installation>`_ and `setup a catkin workspace <http://wiki.ros.org/catkin/Tutorials/create_a_workspace>`_. Clone the general Jackal repo and the desktop specific repo in to the src folder and compile them, installing rosdeps if necessary:
+
+.. code-block:: bash
+
+    cd src
+    git clone -b melodic-devel https://github.com/jackal/jackal
+    git clone -b melodic-devel https://github.com/jackal/jackal_desktop.
+    cd ..
+    rosdep install --from-paths src --ignore-src -r -y
+    catkin_make
+    source devel/setup.bash
+
+Note the IP address of the TX2 and `setup your host computer <http://wiki.ros.org/ROS/Tutorials/MultipleMachines>`_ to use it as the master.
+
+You can then run ``roslaunch jackal_viz view_robot.launch`` on your host machine.  You should see a model of the robot and be able to move the Jackal using the interactive markers. See: :doc:`Navigating with Jackal <navigation>` for more information on using maps for navigation and localization.
diff --git a/doc/minimuminstall.png b/doc/minimuminstall.png
diff --git a/doc/simulation.rst b/doc/simulation.rst
@@ -14,7 +14,7 @@ set up on your Ubuntu desktop, and install the Jackal-specific metapackages for
 
 .. code:: bash
 
-    sudo apt-get install ros-kinetic-jackal-simulator ros-kinetic-jackal-desktop
+    sudo apt-get install ros-melodic-jackal-simulator ros-melodic-jackal-desktop ros-melodic-jackal-navigation
 
 
 Launch Gazebo

diff --git a/doc/startup.rst b/doc/startup.rst
@@ -44,7 +44,7 @@ launch files associated with the ``ros`` background job. If you add launch files
 Jackal's startup.
 
 However, it's important to note that in the default configuration, any launch files you add may only reference ROS
-software installed in ``/opt/ros/kinetic/``. If you want to launch something from workspace in
+software installed in ``/opt/ros/melodic/``. If you want to launch something from workspace in
 the home directory, you must change ``/etc/ros/setup.bash`` to source that workspace's setup file rather than the
 one from ``opt``.
 
@@ -61,5 +61,70 @@ The second, more sophisticated way to modify the URDF is to create a *new* packa
 your own URDF which wraps the one provided by :roswiki:`jackal_description`.
 
 
-Putting It All Together
------------------------
+Controllers
+--------------------
+
+Jackal ships with a PS4 controller for teleoperation.  If you need to re-pair the controller, you can do so
+using the ``bluetoothctl`` command.  Ensure that the controller is in pairing mode by pressing and holding the
+Share and PS buttons, run ``bluetoothctl`` on the robot, and enter the following commands:
+
+.. code-block:: text
+
+    agent on
+    scan on
+
+Look for your game controller; it should be identified with "Wireless Controller".  Copy the MAC address of the
+controller, and then enter the following:
+
+.. code-block:: text
+
+    scan off
+    pair <MAC ADDRESS>
+    trust <MAC ADDRESS>
+    connect <MAC ADDRESS>
+
+Once the controller is connected the light should turn blue.  Press `ctrl+d` to exit bluetoothctl.
+
+To drive the robot, hold the left shoulder button (L1) and use the left thumb-stick.  Holding the right shoulder button
+(R1) will enable turbo, and increase the robot's maximum speed.
+
+.. warning::
+
+    Only enable turbo when you are familiar with how Jackal operates.  Do not use turbo in narrow, enclosed
+    environments.  Always make sure you have a clear line of sight to the robot when operating it.
+
+Other controllers can also be used with Jackal.  Some older robots shipped with a Logitech F710 controller.  This
+controller uses a USB dongle and will pair automatically when the dongle is connected to the robot.  To enable
+the Logitech controller add the following to ``/etc/ros/setup.bash``:
+
+.. code-block:: bash
+
+    export JACKAL_LOGITECH=1
+
+and then run
+
+.. code-block:: bash
+
+    source /etc/ros/setup.bash
+    sudo systemctl restart ros
+
+The Logitech controller uses the same button layout as the PS4 controller: holding LB will enable driving and holding
+RB will enable turbo.
+
+Certain very old Jackal robots may have shipped with a PS3 controller.  If this is the case, you will need to follow
+some additional steps.
+
+First, add the PS3 driver apt repository:
+
+.. code-block:: bash
+
+    sudo add-apt-repository ppa:clearpath-robotics/ps3-joystick
+    sudo apt-get update
+
+Then install the driver:
+
+.. code-block:: bash
+
+    sudo apt-get install sixad
+
+Finally, pair the PS3 controller with the ``sixpair`` command.
diff --git a/doc/update.rst b/doc/update.rst
@@ -31,7 +31,7 @@ is the case in one of two ways:
 1. The firmware and PC are unable to connect to each other, which will be apparent if the two-arrow comms indicator
    fails to come on after system bootup.
 2. If the firmware version number in the ``/status`` message does not match the package version output by
-   ``dpkg -s ros-kinetic-jackal-firmware``. In the future there will be an automated check for this which outputs
+   ``dpkg -s ros-melodic-jackal-firmware``. In the future there will be an automated check for this which outputs
    a diagnostics warning when a firmware update is available to be applied.
 
 If new firmware is available, follow the below procedure to flash it to Jackal's MCU:

diff --git a/package.xml b/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package>
   <name>jackal_tutorials</name>
-  <version>0.5.1</version>
+  <version>0.5.3</version>
   <description>Jackal's tutorials.</description>
   <maintainer email="mpurvis@clearpathrobotics.com">Mike Purvis</maintainer>