Release Installation
====================

Table of Contents
------------------

- :ref:`generic-installation`

  - :ref:`ubuntu-2204-installation`
  - :ref:`bios-setup`
  - :ref:`os-customization`
  - :ref:`prerequisites`
  - :ref:`ros2-installation`

- :ref:`robot-specific-installation`

  - :ref:`initial-configuration`
  - :ref:`pad`
  - :ref:`sensors-and-components`

.. _generic-installation:

Generic Installation
---------------------

.. _ubuntu-2204-installation:

Ubuntu 22.04 LTS Installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Follow the standard Ubuntu installation wizard:

#. Language: **English**
#. Keyboard Layout: **Spanish - Spanish**
#. Connect to Internet if required.
#. Set up installation:
   - **Minimal Installation**
   - **Other options > Download updates while installing Ubuntu**
#. **Erase disk and install Ubuntu**
#. Timezone: **Madrid**
#. User setup:
   - Name: **robot**
   - Computer name: **robot-id**
   - Username: **robot**
   - Password: ********
   - **Log in automatically**
#. Skip welcome screens and disable privacy.

.. tip::
   For more info, visit the `official Ubuntu installation tutorial <https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview>`_.

.. _dual-boot-optional:

1.1 Dual Boot (OPTIONAL)
~~~~~~~~~~~~~~~~~~~~~~~~

If dual booting with Ubuntu 20.04 and 22.04, install 20.04 first. Then:

#. Configure GRUB to remember last boot:

.. code-block:: bash

   sudo sed -i  '/^GRUB_SAVEDEFAULT=/d;s/^GRUB_DEFAULT=.*/GRUB_DEFAULT=saved\nGRUB_SAVEDEFAULT=true/' /etc/default/grub && \
   sudo update-grub

#. Change the default OS boot using a script: Create script ``/usr/local/sbin/toggle-default-boot-partition`` and make it executable. See original document for contents.
#. Create script ``/usr/local/sbin/list-boot-partition`` to view boot entries. See original document for contents.
#. How to use:

.. code-block:: bash

   sudo list-boot-partition
   sudo toggle-default-boot-partition -b [BOOT ENTRY]

.. note::
   Use the main number, submenu entries are not supported.

.. _desktop-icons-ubuntu2204:

1.1.1 Desktop Icons (Ubuntu 22.04)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create launcher for toggling GRUB boot. Refer to the original document for exact `.desktop` file contents.

.. _desktop-icons-ubuntu2004:

1.1.2 Desktop Icons (Ubuntu 20.04)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Same as above, with reversed boot entry numbers.

.. _bios-setup:

BIOS Setup
----------

.. _intel-nuc:

Intel NUC
^^^^^^^^^

1. Press ``F2`` at boot to enter BIOS
2. Navigate to ``Advanced > Power``
3. Set ``After Power Failure`` to ``Power On``
4. Save and exit

.. _jetway-nf797:

Jetway NF797-Q370
^^^^^^^^^^^^^^^^^

1. Press ``supr`` at boot to enter BIOS
2. Go to ``Chipset > PCH-IO Configuration``
3. Set ``State after G3`` to ``Always On``
4. Enable ``Wake-on-LAN``
5. Save and exit

.. _os-customization:

OS Customization
----------------

Refer to sections for network config, wallpaper, updates, screen settings, GRUB tweaks, SocketCAN, virtual dummy HDMI, and more. Rewritten per section later.

.. _prerequisites:

Prerequisites
-------------

1. Update the system:

.. code-block:: bash

   sudo apt-get update && sudo apt-get upgrade -y

2. Install packages (Terminator, Docker, OpenSSH, Screen):

.. code-block:: bash

   sudo apt-get install -y terminator htop git vim aria2 screen curl openssh-server
   curl -fsSL https://get.docker.com | sudo bash
   sudo usermod -a -G docker $USER

3. Setup fzf and `.screenrc`. See original document.
4. Remove unused packages:

.. code-block:: bash

   sudo apt-get remove brltty -y

5. Enable remote desktop. Configure via GNOME settings and allow legacy VNC if needed.
6. Configure keyring: open "Passwords and Keys" and clear login password.
7. Set up SocketCAN via ``/etc/systemd/network/80-can.network`` file. See original for contents.
8. Apply OS tweaks (power button, animations, screensaver, GRUB): see original.
9. Virtual dummy HDMI: download archive and run `configure_autoscreen.sh`. Add dummy script to auto-enable HDMI output.
10. Prevent network delays from unconnected interfaces. See systemd override config examples.

.. _ros2-installation:

ROS 2 Installation
------------------

Native Installation on Ubuntu 22.04 (RECOMMENDED)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Add APT repo and public keys:

.. code-block:: bash

   sudo apt install curl -y
   sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

2. Add ROS 2 sources to APT:

.. code-block:: bash

   echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

3. Update and upgrade:

.. code-block:: bash

   sudo apt-get update && sudo apt-fast upgrade -y

4. Install ROS 2 Humble and related packages:

.. code-block:: bash

   sudo apt-fast install ros-humble-desktop-full ros-dev-tools -y

5. Configure `.bashrc`:

.. code-block:: bash

   echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
   echo "export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp" >> ~/.bashrc
   source ~/.bashrc

6. Download robot release and place in `~/robot_ws/src/robot_packages`
7. Install dependencies with `rosdep`
8. Compile using `colcon build`
9. Configure using provided script `configure.sh`
10. Check `README.md`

.. note::
   If issues arise, revisit auto-updates disabling from earlier section.

Container Installation (WIP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Authenticate to registry:

.. code-block:: bash

   docker login https://registry.robotnik.ws

2. Create `docker-compose.yaml`. See original for contents.
3. Run with:

.. code-block:: bash

   docker compose up -d

.. _robot-specific-installation:

Robot Specific Installation
---------------------------

.. _initial-configuration:

Initial Configuration
^^^^^^^^^^^^^^^^^^^^^

If robot doesn't boot, revisit BIOS setup.

Set robot serial number in:

- ``/etc/hostname``
- ``/etc/hosts``
- ``~/.bashrc`` (`ROS_MASTER_URI`)

Update router SSID via `192.168.0.1` if applicable.

.. _pad:

PAD
^^^

**PS4:**

- Use `bluetooth_setup.sh` to configure dongle
- Pair with Share + PS buttons
- Test with `jstest /dev/input/js_base`

**PS5:**

- Pair via GNOME Bluetooth settings
- Create udev rule for `/dev/input/js_base`
- Reload udev and restart

.. _sensors-and-components:

Sensors and Components
^^^^^^^^^^^^^^^^^^^^^^

**Intel RealSense:**

Add Intel repo and install packages:

.. code-block:: bash

   sudo mkdir -p /etc/apt/keyrings
   curl -sSf https://librealsense.intel.com/Debian/librealsense.pgp | sudo tee /etc/apt/keyrings/librealsense.pgp > /dev/null
   echo "deb [signed-by=/etc/apt/keyrings/librealsense.pgp] https://librealsense.intel.com/Debian/apt-repo `lsb_release -cs` main" | \
     sudo tee /etc/apt/sources.list.d/librealsense.list
   sudo apt-get update
   sudo apt-fast -y install librealsense2-dkms librealsense2-utils

.. toctree::
   :maxdepth: 1